smartarr 0.2.0

Expressive array utilities with an optional C backend.

smartarr

smartarr is an expressive array utility layer for Python with a clean smart(arr) API and an optional C backend for fast core operations.

Why it exists

The goal is simple:

• one readable interface for lists, tuples, and NumPy arrays
• fast common operations when the C extension is available
• chainable transformations that still feel like Python

from smartarr import smart

value = smart([1, 2, 3, 4, 5]).rotate(2).reverse().middle()
print(value)  # 1

Install

Local install from this project:

python -m pip install .

Editable install for development:

python -m pip install -e .

Optional NumPy support:

python -m pip install ".[numpy]"

If a compiler is available, smartarr builds its C extension automatically. If not, installation still succeeds and falls back to the pure Python backend.

Quick start

from smartarr import smart

arr = smart([1, 2, 3, 4])

print(arr.first())                 # 1
print(arr.last())                  # 4
print(arr.middle())                # 3
print(arr.middle(mode="left"))     # 2
print(arr.middle(mode="avg"))      # 2.5
print(arr.size())                  # 4
print(len(arr))                    # 4
print(arr.rotate(1).to_list())     # [4, 1, 2, 3]
print(arr.reverse().to_list())     # [4, 3, 2, 1]
print(arr.chunk(2).to_list())      # [[1, 2], [3, 4]]
print(arr.window(2).to_list())     # [[1, 2], [2, 3], [3, 4]]
print(arr.peaks().to_list())       # local maxima values
print(arr.peaks(mode="index").to_list())  # local maxima indexes
print(arr.duplicates().to_list())  # unique duplicated values
print(arr.duplicates(mode="all").to_list())  # every repeated occurrence after the first
print(arr.argmax())                # 3
print(arr.argsort().to_list())     # [0, 1, 2, 3]

Design notes

• middle() defaults to the right-middle element for even-length arrays, matching arr[len(arr) // 2].
• SmartArray operations are non-mutating by default. Methods like rotate() and reverse() return a new wrapper and leave the original array unchanged.
• Prefer len(arr) or arr.size() for length checks. arr.len() remains as a compatibility alias.
• Structural methods return a new SmartArray, so chaining works naturally.
• Terminal methods return a final value, such as an element, a number, or a dictionary.
• Flat transformations preserve the original adapter where practical. Shape-changing operations return list-shaped data by default.
• random() returns one element when n is omitted, samples without replacement when replace=False, and samples with replacement when replace=True. A seed makes output deterministic.
• sample(frac) selects a fraction of the array. By default it samples without replacement and preserves the original order of selected elements.
• shuffle() returns a randomly reordered copy.
• peaks() returns local maxima values by default. Use mode="index" to return their positions.
• duplicates() returns each duplicated value once by default. Use mode="all" to return every repeated occurrence after the first.
• flatten() performs a deep recursive flatten across nested iterables, except string-like values such as str, bytes, and bytearray.
• flatten() follows the iteration order of the source containers. Ordered iterables stay ordered; unordered iterables such as set keep their native iteration behavior.
• reshape() validates that the requested shape exactly matches the flattened element count.
• window() returns an empty result when the requested window size is larger than the array length.
• reduce() requires either a non-empty array or an explicit initial value.
• frequency() returns counts in first-seen insertion order on Python 3.7+.
• take(), drop(), and remove_at() support negative indexes and raise clear IndexErrors when out of range.
• group_by() returns a dict of lists, and partition() returns a native tuple of lists.
• shape() requires a regular rectangular nested structure.
• join() requires string elements. split() is the inverse helper for a one-element string array.
• lazy() records operations and runs them later with execute().

Performance Notes

• The current C backend accelerates core access and array operations such as first, last, middle, rotate, reverse, find, count, contains, chunk, window, and is_sorted.
• Higher-level methods such as map, filter, reduce, sum, mean, median, peaks, unique, duplicates, frequency, flatten, and reshape currently run in Python.
• This means the API is already hybrid, but the biggest performance wins will come from moving heavier algorithms into the C layer over time.

Supported input types

• list
• tuple
• NumPy ndarray when NumPy is installed
• general iterables such as range

Current feature coverage

Access and Position

• first
• last
• middle
• len
• size
• is_empty
• find
• indices
• count
• contains
• argmax
• argmin
• argsort

Structural and Slicing

• rotate
• reverse
• chunk
• window
• slice
• take
• drop
• flatten
• reshape
• insert
• remove_at
• replace

Grouping and Combination

• group_by
• partition
• zip
• zip_with

Numeric and Rolling

• sum
• mean
• median
• min
• max
• diff
• cumsum
• rolling_mean
• rolling_max
• top_k
• bottom_k

Filtering and Boolean

• map
• filter
• where
• reduce
• mask
• random
• sample
• shuffle

Set-like and Comparison

• union
• intersection
• difference
• sorted
• sort_by
• is_sorted
• equals
• is_unique
• has_duplicates
• unique
• duplicates
• frequency
• peaks

Shape, Strings, and Debug

• shape
• ndim
• join
• split
• inspect
• summary
• lazy

Development

Run tests:

python -m unittest discover -s tests -v

License

MIT