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

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

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
83
84
85
86
87
88
89
90
91
92
def __init__(
    self, clients: Clients, events: Events, time_format=None, binary_image=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
103
104
105
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
107
108
109
110
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

An iterator (a ClipsHashes object)

Source code in reels/Clips.py
129
130
131
132
133
134
135
def clips_client_hashes(self):
    """Return an iterator to iterate over all the hashed client ids.

    Returns:
        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

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

required

Returns:

Type Description

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

Source code in reels/Clips.py
154
155
156
157
158
159
160
161
162
163
164
165
166
def describe_clip(self, client):
    """Return a list ot the codes in chronological order for a given client.

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

    Returns:
        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

A list of strings returned by save_as_binary_image()

required

Returns:

Type Description

True on success, destroys, initializes and returns false on failure.

Source code in reels/Clips.py
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
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: A list of strings returned by save_as_binary_image()

    Returns:
        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

The number of clips stored in the object. Clips are indexed by unique

client hash.

Source code in reels/Clips.py
137
138
139
140
141
142
143
144
def num_clips(self):
    """Return the number of clips in the object.

    Returns:
        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

The number of events stored in the object.

Source code in reels/Clips.py
146
147
148
149
150
151
152
def num_events(self):
    """Return the number of events counting all the clips stored by the object.

    Returns:
        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

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
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
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:
        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

The "emitter". A string representing "owner of event".

required
description

The "description". A string representing "the event".

required
weight

The "weight". A double representing a weight of the event.

required
client

The "client". A string representing "the actor".

required
time

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

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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def scan_event(self, 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.

    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:
        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

The sequence id (in range 0.499).

required
target

True for one of the target sequences, false for non target.

required

Returns:

Type Description

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

Source code in reels/Clips.py
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
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: The sequence id (in range 0.499).
        target:  True for one of the target sequences, false for non target.

    Returns:
        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 = ''