Metadata-Version: 2.4
Name: list_reserve
Version: 0.5.0
Summary: Python builtin list memory allocation library
Author-email: ChanTsune <yshegou@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ChanTsune/list-reserve
Project-URL: Repository, https://github.com/ChanTsune/list-reserve
Project-URL: Issues, https://github.com/ChanTsune/list-reserve/issues
Project-URL: Changelog, https://github.com/ChanTsune/list-reserve/blob/master/CHANGELOG.md
Keywords: list,reserve,capacity,memory,cpython,c-extension
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# list-reserve

Python builtin list memory allocation library.  

[![PyPI version](https://img.shields.io/pypi/v/list-reserve.svg)](https://pypi.org/project/list-reserve/)
[![Python versions](https://img.shields.io/pypi/pyversions/list-reserve.svg)](https://pypi.org/project/list-reserve/)
[![Wheel](https://img.shields.io/pypi/wheel/list-reserve.svg)](https://pypi.org/project/list-reserve/)
[![Downloads](https://static.pepy.tech/badge/list-reserve)](https://pepy.tech/project/list-reserve)
[![License](https://img.shields.io/pypi/l/list-reserve.svg)](https://github.com/ChanTsune/list-reserve/blob/master/LICENSE)
[![Test](https://github.com/ChanTsune/list-reserve/workflows/Test/badge.svg)](https://github.com/ChanTsune/list-reserve/actions)

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

```bash
pip install list_reserve
```

### capacity

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

```py
from list_reserve import capacity

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

### reserve

Reserve list capacity.

```py
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.

```py
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.

```py
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.

```py
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.

```py
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](https://containers.dev). Open it in an editor that
supports Dev Containers ("Reopen in Container"), or run it headlessly with the
[Dev Containers CLI](https://github.com/devcontainers/cli):

```bash
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](./LICENSE)
