loom.interpreter.block_history

Copyright 2024 Entropica Labs Pte Ltd

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class loom.interpreter.block_history.BlockHistory(*args, **kwargs)[source]

Bases: object

Class to track the history of blocks over time.

- _blocks_by_timestamp

A mapping from timestamps to sets of block UUIDs present at those times.

Type:

dict[int, set[str]]

- _timestamps_sorted_asc

A sorted list of timestamps in ascending order. This allows for efficient searching of previous and next timestamps.

Type:

list[int]

- _timestamps_set

A set of timestamps for quick existence checks.

Type:

set[int]

- _all_blocks_set

A set of all block UUIDs that have ever been present in the history.

Type:

set[str]

blocks_at(timestamp)[source]

Return the blocks present at the given timestamp. If the exact timestamp does not exist, return the blocks at the most recent previous timestamp.

Parameters:

timestamp (int) – The timestamp to query.

Returns:

The set of block UUIDs present at the given timestamp.

Return type:

set[str]

blocks_over_time(t_start=None, t_stop=None)[source]

Return the timestamps and corresponding blocks over the specified time range.

Parameters:

  • t_start (int | None) – The start timestamp (inclusive). If None, starts from the first timestamp.

  • t_stop (int | None) – The stop timestamp (exclusive). If None, goes up to the last timestamp.

Returns:

An iterator over (timestamp, set of block UUIDs) tuples within the specified time range.

Return type:

Iterator[tuple[int, set[str]]]

classmethod create(blocks_at_0)[source]

Create a BlockHistory instance with initial blocks at timestamp 0.

Parameters:

blocks_at_0 (set[str]) – Set of block UUIDs present at timestamp 0.

Returns:

An instance of BlockHistory initialized with the given blocks at time 0.

Return type:

BlockHistory

classmethod is_set_of_uuid4(blocks)[source]

Return True if blocks is a set of valid UUID4 strings, False otherwise.

Return type:

bool

static is_uuid4(s)[source]

Return True if s is a valid UUID4 string, False otherwise.

Return type:

bool

max_timestamp_below_ref_value(ref_timestamp)[source]

Return the largest timestamp less than the input timestamp that exists in the block history.

Parameters:

ref_timestamp (int) – The reference timestamp.

Returns:

The largest timestamp less than the input timestamp.

Return type:

int

min_timestamp_above_ref_value(ref_timestamp)[source]

Return the smallest timestamp greater than the input timestamp that exists in the block history.

Parameters:

ref_timestamp (int) – The reference timestamp.

Returns:

The smallest timestamp greater than the input timestamp, or None if no such timestamp exists.

Return type:

int | None

update_blocks(timestamp, old_blocks, new_blocks)[source]

Modify the blocks at a given timestamp by replacing old_blocks with new_blocks. If the timestamp does not exist, it is created based on the previous timestamp’s blocks.

Parameters:

  • timestamp (int) – The timestamp at which to modify the blocks.

  • old_blocks (set[str]) – The set of block UUIDs to be removed.

  • new_blocks (set[str]) – The set of block UUIDs to be added.

Return type:

None

static validate_timestamp(timestamp)[source]

Raise ValueError if timestamp is not a non-negative integer.

Return type:

None