list-reserve

Python builtin list memory allocation library.

Why?

Python lists over-allocate internally to make repeated append operations efficient. list-reserve exposes a small set of CPython-specific helpers for inspecting and controlling that capacity.

Platform support

Prebuilt wheels are provided for CPython on Linux, macOS, and Windows.

Getting it

pip install list_reserve

capacity

Return the number of item slots currently allocated for a list.

from list_reserve import capacity

l = [1, 2, 3]
print(capacity(l)) # 3

reserve

Reserve list capacity.

from list_reserve import reserve, capacity

l = []
reserve(l, 10)

print(len(l)) # 0

print(capacity(l)) # 10

allocated_bytes

Return the memory size currently allocated for list item slots.

from list_reserve import allocated_bytes

l = [1, 2, 3]
print(allocated_bytes(l)) # capacity(l) * pointer size

remaining_capacity

since 0.5.0
Return the number of additional items a list can accept before it needs to expand.

from list_reserve import capacity, remaining_capacity

l = [1, 2, 3]
print(remaining_capacity(l)) # capacity(l) - len(l)

shrink_to_fit

since 0.1.0
shrink to fit list capacity.

from list_reserve import capacity, shrink_to_fit

l = list(range(100))

print(capacity(l)) # 118

shrink_to_fit(l)

print(capacity(l)) # 100

stats

since 0.5.0
Return list memory statistics in one call.

from list_reserve import reserve, stats

l = []
reserve(l, 10)

print(stats(l))
# {'length': 0, 'capacity': 10, 'allocated_bytes': 80,
#  'remaining_capacity': 10, 'utilization': 0.0}

Development

This repository ships a Dev Container. Open it in an editor that supports Dev Containers ("Reopen in Container"), or run it headlessly with the Dev Containers CLI:

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . python -m unittest

The container compiles the C extension on creation, so the tests are runnable immediately. Since list_reserve is a C extension, re-run pip install . after editing src/list_reserve.c.

License

MIT License