toarray
Small Python package for converting iterables to the smallest fitting array.array type.
Status
- Supports Python 3.9–3.13
- License: MIT
Description
toarray.get_array(iterable) inspects the values and returns the smallest suitable
array.array when possible, otherwise it returns a plain list.
Rules of thumb:
- Non-numeric values → returns
list - Integers → prefers
B,b,H,h,I,i,Q,q(in that order) - Floats → tries
fthend - Empty iterables → returns
[]
Note: Unicode arrays (array('u')) are deprecated/removed in modern Python and are not used.
Install
pip install toarray
# optional extras
pip install toarray[numpy]
pip install toarray[arrow]
Usage
from toarray import get_array, select_array, analyze_array, stream_array
get_array([0, 1, 255]).typecode # 'B'
get_array([-1, 0, 1]).typecode # 'b'
get_array([1e-3, 2.5]).typecode # 'f'
get_array(["a", "b"]) # ['a', 'b']
get_array([]) # []
# Policy-based selection (control bounds and strategy)
arr = select_array(
[0, 1, 256],
policy='smallest', # 'smallest' | 'balanced' | 'wide'
prefer_signed=False,
min_type=None, # e.g. 'h', 'i', 'q', 'f', 'd'
max_type=None,
)
# Metadata
info = analyze_array([1, 2, 3])
info.typecode, info.min, info.max # ('B', 1.0, 3.0)
# Streaming
for chunk in stream_array(range(1000), chunk_size=256):
pass
# Optional extras
# NumPy (pip install toarray[numpy])
from toarray import to_numpy
arr_np = to_numpy([0,1,2], dtype='min') # dtype: uint8
arr_np_exp = to_numpy([0,1,2], dtype='float64') # dtype: float64
# PyArrow (pip install toarray[arrow])
from toarray import to_arrow
arr_pa = to_arrow([0,1,2], type='min') # pa.array([0, 1, 2], type=uint8)
arr_pa_chunked = to_arrow(range(10), type='float64', chunk_size=4) # pa.ChunkedArray
Selection policies and strict mode
- Policies adjust the candidate order searched for a fit:
smallest: smallest footprint first (default)balanced: mildly prefers signed widths earlywide: wider integer types first
- Bounds:
min_type/max_typelet you constrain the search (e.g., up toionly). - Floats:
allow_float_downgrade=Falseskipsfwhen magnitudes exceed float32. no_float=Trueforces integers only; withstrict=Truethis raises on floats.
Notes
- Non‑numeric input returns a
list(text is not coerced toarray('u')). - Integer preference order:
B,b,H,h,I,i,Q,q. - Float preference order:
fthend(subject to range and policy).
Development
This project uses pytest, ruff, and black.
pip install -e .[dev]
ruff check .
black --check .
pytest
Authors
Odos Matthews — odosmatthews@gmail.com
License
MIT — see LICENSE.md for details
Metadata
Release files for toarray 0.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| toarray-0.3.2.tar.gz | 11.0 kB | Without provenance | Details for toarray-0.3.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| toarray-0.3.2-py3-none-any.whl | Python 3 | none | any | Details for toarray-0.3.2-py3-none-any.whl |
Total release size: 19.4 kB
Release files / toarray-0.3.2.tar.gz
| Download URL | toarray-0.3.2.tar.gz |
|---|---|
| Size | 11.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a976fb4325913c8f6f344cb3feda6a782ab1403a5fc14620adad9ced4e9a746e
|
|
BLAKE2b-256 checksum How to use checksums |
d499889572a9ee297a77cdf89ea0ad4a803c25e647e4880d3eaf24ec5d44286a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.8.18
|
Release files / toarray-0.3.2-py3-none-any.whl
| Download URL | toarray-0.3.2-py3-none-any.whl |
|---|---|
| Size | 8.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7436bfd1a740b7626e2479beaf6ddc85dee74f17160e3d8eca06f9c467179e51
|
|
BLAKE2b-256 checksum How to use checksums |
fc1ddc65fa917e9efbfeee40b79463b934b81d9bdde3fa50536ca638f6cfa79c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.8.18
|
Security for toarray 0.3.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.