Skip to content

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
82
83
84
85
86
87
88
89
90
91
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
102
103
104
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
106
107
108
109
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
128
129
130
131
132
133
134
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
152
153
154
155
156
157
158
159
160
161
162
163
164
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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
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
136
137
138
139
140
141
142
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
144
145
146
147
148
149
150
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
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
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
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
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
44
45
46
def __init__(self, cp_id):
    self.cp_id = cp_id
    self.prev_hash = ''