Internal Sparse Array - libtmux._internal.sparse_array

Warning

Be careful with these! Internal APIs are not covered by version policies. They can break or be removed between minor versions!

If you need an internal API stabilized please file an issue.

Sparse array for libtmux options and hooks.

libtmux._internal.sparse_array.is_sparse_array_list(items)

function

Parameters:

items (ExplodedComplexUntypedOptionsDict)

Return type:

TypeGuard[HookArray]

class libtmux._internal.sparse_array.SparseArray

class

Bases: dict[int, T], Generic[T]

Support non-sequential indexes while maintaining list-like behavior.

A normal list would raise IndexError.

There are no native sparse arrays in python that contain non-sequential indexes and maintain list-like behavior. This is useful for handling libtmux options and hooks:

command-alias[1] split-pane=split-window to {'command-alias[1]': {'split-pane=split-window'}}

list would lose indice info, and dict would lose list-like behavior.

Examples

Create a sparse array and add values at non-sequential indices:

>>> from libtmux._internal.sparse_array import SparseArray

>>> arr: SparseArray[str] = SparseArray()
>>> arr.add(0, "first hook command")
>>> arr.add(5, "fifth hook command")
>>> arr.add(2, "second hook command")

Access values by index (dict-style):

>>> arr[0]
'first hook command'
>>> arr[5]
'fifth hook command'

Check index existence:

>>> 0 in arr
True
>>> 3 in arr
False

Iterate values in sorted index order:

>>> list(arr.iter_values())
['first hook command', 'second hook command', 'fifth hook command']

Convert to a list (values only, sorted by index):

>>> arr.as_list()
['first hook command', 'second hook command', 'fifth hook command']

Append adds at max index + 1:

>>> arr.append("appended command")
>>> arr[6]
'appended command'

Access raw indices:

>>> sorted(arr.keys())
[0, 2, 5, 6]

add(index, value)

method

Add a value at a specific index.

Parameters:

• index (int) – The index at which to store the value.

• value (T) – The value to store.

Return type:

None

Examples

>>> from libtmux._internal.sparse_array import SparseArray

>>> arr: SparseArray[str] = SparseArray()
>>> arr.add(0, "hook at index 0")
>>> arr.add(10, "hook at index 10")
>>> arr[0]
'hook at index 0'
>>> arr[10]
'hook at index 10'
>>> sorted(arr.keys())
[0, 10]

append(value)

method

Append a value at the next available index (max + 1).

Parameters:

value (T) – The value to append.

Return type:

None

Examples

>>> from libtmux._internal.sparse_array import SparseArray

Appending to an empty array starts at index 0:

>>> arr: SparseArray[str] = SparseArray()
>>> arr.append("first")
>>> arr[0]
'first'

Appending to a non-empty array adds at max index + 1:

>>> arr.add(5, "at index 5")
>>> arr.append("appended")
>>> arr[6]
'appended'
>>> arr.append("another")
>>> arr[7]
'another'

iter_values()

method

Iterate over values in sorted index order.

Yields:

T – Values in ascending index order.

Return type:

Iterator[T]

Examples

>>> from libtmux._internal.sparse_array import SparseArray

>>> arr: SparseArray[str] = SparseArray()
>>> arr.add(5, "fifth")
>>> arr.add(0, "first")
>>> arr.add(2, "second")
>>> for val in arr.iter_values():
...     print(val)
first
second
fifth

as_list()

method

Return values as a list in sorted index order.

Returns:

List of values sorted by their indices.

Return type:

list[T]

Examples

>>> from libtmux._internal.sparse_array import SparseArray

>>> arr: SparseArray[str] = SparseArray()
>>> arr.add(10, "tenth")
>>> arr.add(0, "zeroth")
>>> arr.add(5, "fifth")
>>> arr.as_list()
['zeroth', 'fifth', 'tenth']