Clips

reels.Clips

Clips(clients, events, time_format=None, binary_image=None)

Interface to the c++ container object to hold clips.

The purpose of this object is to be filled (via successive scan_event() calls) this builds and stores the clips and passed to a Targets object. The content can just be serialized as a pickle to make it pythonic, checked for size and iterated by calling clips_client_hashes().

Parameters:

Name	Type	Description	Default
clients	Clients	A possibly initialized Clients object to restrict building the clips to a specific set of clients. Pass an empty Clients object for no restriction (all clients).	required
events	Events	An Events object that defines what events have to be considered to build the clips.	required
time_format	str	An optional definition of the time format that will affect how time is parsed by scan_event() the default is "%Y-%m-%d %H:%M:%S" https://www.gnu.org/software/libc/manual/html_node/Formatting-Calendar-Time.html	None
binary_image	list	An optional binary image (returned by save_as_binary_image()) to initialize the object with data copied from another Clips object. You have to pass empty clients and events to use this.	None

Source code in reels/Clips.py

def __init__(
    self, clients: Clients, events: Events, time_format: str=None, binary_image: list=None
):
    self.cp_id = new_clips(clients.cl_id, events.ev_id)

    if time_format is not None:
        clips_set_time_format(self.cp_id, time_format)

    if binary_image is not None:
        self.load_from_binary_image(binary_image)

__getstate__()

Used by pickle.dump() (See https://docs.python.org/3/library/pickle.html)

Source code in reels/Clips.py

def __getstate__(self):
    """Used by pickle.dump() (See https://docs.python.org/3/library/pickle.html)"""
    return self.save_as_binary_image()

__setstate__(state)

Used by pickle.load() (See https://docs.python.org/3/library/pickle.html)

Source code in reels/Clips.py

def __setstate__(self, state):
    """Used by pickle.load() (See https://docs.python.org/3/library/pickle.html)"""
    self.cp_id = new_clips(new_clients(), new_events())
    self.load_from_binary_image(state)

clips_client_hashes()

Return an iterator to iterate over all the hashed client ids.

Returns:

Type	Description
ClipsHashes	An iterator (a ClipsHashes object)

Source code in reels/Clips.py

def clips_client_hashes(self):
    """Return an iterator to iterate over all the hashed client ids.

    Returns:
        (ClipsHashes): An iterator (a ClipsHashes object)
    """
    return ClipsHashes(self.cp_id)

describe_clip(client)

Return a list ot the codes in chronological order for a given client.

Parameters:

Name	Type	Description	Default
client	str	Either a client identifier or the hash of a client identifier returned by Clients.hash_client_id().	required

Returns:

Type	Description
list	A list of integer codes on success or None on failure.

Source code in reels/Clips.py

def describe_clip(self, client):
    """Return a list ot the codes in chronological order for a given client.

    Args:
        client (str): Either a client identifier or the hash of a client identifier returned by Clients.hash_client_id().

    Returns:
        (list): A list of integer codes on success or None on failure.
    """
    s = clips_describe_clip(self.cp_id, client)

    if len(s) != 0:
        return [int(i) for i in s.split('\t')]

load_from_binary_image(binary_image)

Load the state of the c++ Clips object from a binary_image returned by a previous save_as_binary_image() call.

Parameters:

Name	Type	Description	Default
binary_image	list	A list of strings returned by save_as_binary_image()	required

Returns:

Type	Description
bool	True on success, destroys, initializes and returns false on failure.

Source code in reels/Clips.py

def load_from_binary_image(self, binary_image):
    """Load the state of the c++ Clips object from a binary_image
        returned by a previous save_as_binary_image() call.

    Args:
        binary_image (list): A list of strings returned by save_as_binary_image()

    Returns:
        (bool): True on success, destroys, initializes and returns false on failure.
    """
    failed = False

    for binary_image_block in binary_image:
        if not clips_load_block(self.cp_id, binary_image_block):
            failed = True
            break

    if not failed:
        failed = not clips_load_block(self.cp_id, "")

    if failed:
        destroy_clips(self.cp_id)
        self.cp_id = new_clips(new_clients(), new_events())
        return False

    return True

num_clips()

Return the number of clips in the object.

Returns:

Type	Description
int	The number of clips stored in the object. Clips are indexed by unique client hash.

Source code in reels/Clips.py

def num_clips(self):
    """Return the number of clips in the object.

    Returns:
        (int): The number of clips stored in the object. Clips are indexed by unique client hash.
    """
    return clips_num_clips(self.cp_id)

num_events()

Return the number of events counting all the clips stored by the object.

Returns:

Type	Description
int	The number of events stored in the object.

Source code in reels/Clips.py

def num_events(self):
    """Return the number of events counting all the clips stored by the object.

    Returns:
        (int): The number of events stored in the object.
    """
    return clips_num_events(self.cp_id)

save_as_binary_image()

Saves the state of the c++ Clips object as a Python list of strings referred to a binary_image.

Returns:

Type	Description
list	The binary_image containing the state of the Clips. There is not much you can do with it except serializing it as a Python (e.g., pickle) object and loading it into another Clips object. Pass it to the constructor to create an initialized object,

Source code in reels/Clips.py

def save_as_binary_image(self):
    """Saves the state of the c++ Clips object as a Python
        list of strings referred to a binary_image.

    Returns:
        (list): The binary_image containing the state of the Clips. There is
            not much you can do with it except serializing it as a Python
            (e.g., pickle) object and loading it into another Clips object.
            Pass it to the constructor to create an initialized object,
    """
    bi_idx = clips_save(self.cp_id)
    if bi_idx == 0:
        return None

    bi = []
    bi_size = size_binary_image_iterator(bi_idx)
    for t in range(bi_size):
        bi.append(next_binary_image_iterator(bi_idx))

    destroy_binary_image_iterator(bi_idx)

    return bi

scan_event(emitter, description, weight, client, time)

Process a row from a transaction file, to add the event to the client's timeline in a Clips object.

Parameters:

Name	Type	Description	Default
emitter	str	The "emitter". A string representing "owner of event".	required
description	str	The "description". A string representing "the event".	required
weight	float	The "weight". A double representing a weight of the event.	required
client	str	The "client". A string representing "the actor".	required
time	str	The "time". A timestamp of the event as a string. (The format is given via the time_format argument to the constructor.)	required

Returns:

Type	Description
bool	True on insertion. False usually just means, the event is not in events or the client is not in clients. It may be a time parsing error too.

Source code in reels/Clips.py

def scan_event(self, emitter: str, description: str, weight: float, client: str, time: str):
    """Process a row from a transaction file, to add the event to the client's timeline in a Clips object.

    Args:
        emitter:     The "emitter". A string representing "owner of event".
        description: The "description". A string representing "the event".
        weight:      The "weight". A double representing a weight of the event.
        client:      The "client". A string representing "the actor".
        time:        The "time". A timestamp of the event as a string. (The format
                     is given via the time_format argument to the constructor.)

    Returns:
        (bool): True on insertion. False usually just means, the event is not in events
            or the client is not in clients. It may be a time parsing error too.
    """
    return clips_scan_event(self.cp_id, emitter, description, weight, client, time)

test_sequence(seq_num, target)

Generates a constant sequence of codes for testing the Event Optimizer. This returns one of the 500 non target sequences or one of the 500 target sequences.

Parameters:

Name	Type	Description	Default
seq_num	int	The sequence id (in range 0.499).	required
target	bool	True for one of the target sequences, false for non target.	required

Returns:

Type	Description
list	A sequence of integer codes list or None if seq_num is out of range.

Source code in reels/Clips.py

def test_sequence(self, seq_num, target):
    """Generates a constant sequence of codes for testing the Event Optimizer.
        This returns one of the 500 non target sequences or one of the 500 target sequences.

    Args:
        seq_num (int): The sequence id (in range 0.499).
        target (bool):  True for one of the target sequences, false for non target.

    Returns:
        (list): A sequence of integer codes list or None if seq_num is out of range.
    """

    s = clips_test_sequence(seq_num, target)

    if s == '':
        return None

    return [int(i) for i in s.split(',')]

ClipsHashes(cp_id)

Iterator over the hashes of the Clients in a Clips container.

Source code in reels/Clips.py

def __init__(self, cp_id):
    self.cp_id = cp_id
    self.prev_hash = ''