smartarr 0.1.0__tar.gz

smartarr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smartarr-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: smartarr
+Version: 0.1.0
+Summary: Expressive array utilities with an optional C backend.
+Author: OpenAI Codex
+License-Expression: MIT
+Keywords: array,utilities,c-extension,numpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: C
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.24; extra == "numpy"
+Dynamic: license-file
+
+# 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
+
+```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:
+
+```bash
+python -m pip install .
+```
+
+Editable install for development:
+
+```bash
+python -m pip install -e .
+```
+
+Optional NumPy support:
+
+```bash
+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
+
+```python
+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.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]]
+```
+
+## Design notes
+
+- `middle()` defaults to the right-middle element for even-length arrays, matching `arr[len(arr) // 2]`.
+- 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.
+
+## Supported input types
+
+- `list`
+- `tuple`
+- NumPy `ndarray` when NumPy is installed
+- general iterables such as `range`
+
+## Current feature coverage
+
+### V1
+
+- `first`
+- `last`
+- `middle`
+- `rotate`
+- `reverse`
+- `len`
+- `is_empty`
+
+### V2
+
+- `chunk`
+- `window`
+- `random`
+- `find`
+- `count`
+- `contains`
+- `is_sorted`
+- `sorted`
+
+### V3
+
+- `map`
+- `filter`
+- `reduce`
+- `sum`
+- `mean`
+- `median`
+- `min`
+- `max`
+- `peaks`
+- `unique`
+- `duplicates`
+- `frequency`
+- `flatten`
+- `reshape`
+
+## Development
+
+Run tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT

smartarr-0.1.0/README.md

@@ -0,0 +1,124 @@
+# 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
+
+```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:
+
+```bash
+python -m pip install .
+```
+
+Editable install for development:
+
+```bash
+python -m pip install -e .
+```
+
+Optional NumPy support:
+
+```bash
+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
+
+```python
+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.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]]
+```
+
+## Design notes
+
+- `middle()` defaults to the right-middle element for even-length arrays, matching `arr[len(arr) // 2]`.
+- 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.
+
+## Supported input types
+
+- `list`
+- `tuple`
+- NumPy `ndarray` when NumPy is installed
+- general iterables such as `range`
+
+## Current feature coverage
+
+### V1
+
+- `first`
+- `last`
+- `middle`
+- `rotate`
+- `reverse`
+- `len`
+- `is_empty`
+
+### V2
+
+- `chunk`
+- `window`
+- `random`
+- `find`
+- `count`
+- `contains`
+- `is_sorted`
+- `sorted`
+
+### V3
+
+- `map`
+- `filter`
+- `reduce`
+- `sum`
+- `mean`
+- `median`
+- `min`
+- `max`
+- `peaks`
+- `unique`
+- `duplicates`
+- `frequency`
+- `flatten`
+- `reshape`
+
+## Development
+
+Run tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT

smartarr-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smartarr"
+version = "0.1.0"
+description = "Expressive array utilities with an optional C backend."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "OpenAI Codex" }
+]
+keywords = ["array", "utilities", "c-extension", "numpy"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: C",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Utilities"
+]
+
+[project.optional-dependencies]
+numpy = ["numpy>=1.24"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

smartarr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smartarr-0.1.0/setup.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from distutils.errors import CCompilerError, DistutilsExecError, DistutilsPlatformError
+
+from setuptools import Extension, setup
+from setuptools.command.build_ext import build_ext
+
+
+class OptionalBuildExt(build_ext):
+    """Allow installation to continue when the optional C build is unavailable."""
+
+    def run(self) -> None:
+        try:
+            super().run()
+        except (DistutilsPlatformError, DistutilsExecError, CCompilerError, OSError, ValueError) as exc:
+            self._announce_skip(exc)
+
+    def build_extension(self, ext: Extension) -> None:
+        try:
+            super().build_extension(ext)
+        except (DistutilsPlatformError, DistutilsExecError, CCompilerError, OSError, ValueError) as exc:
+            self._announce_skip(exc)
+
+    def _announce_skip(self, exc: BaseException) -> None:
+        self.warn(
+            f"Skipping optional C extension for smartarr. "
+            f"The pure Python backend will be used instead. Reason: {exc}"
+        )
+
+
+setup(
+    ext_modules=[
+        Extension(
+            "smartarr._smartarr",
+            sources=["src/smartarr/_smartarr.c"],
+            optional=True,
+        )
+    ],
+    cmdclass={"build_ext": OptionalBuildExt},
+)

smartarr-0.1.0/src/smartarr/__init__.py

@@ -0,0 +1,4 @@
+from .api import SmartArray, smart
+
+__all__ = ["SmartArray", "smart"]
+__version__ = "0.1.0"

smartarr-0.1.0/src/smartarr/_backend.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from . import _pybackend
+
+try:  # pragma: no cover - depends on build environment
+    from . import _smartarr as _cbackend
+except ImportError:  # pragma: no cover - exercised when C build is unavailable
+    _cbackend = None
+
+
+BACKEND_NAME = "c" if _cbackend is not None else "python"
+
+length = _cbackend.length if _cbackend is not None else _pybackend.length
+is_empty = _cbackend.is_empty if _cbackend is not None else _pybackend.is_empty
+first = _cbackend.first if _cbackend is not None else _pybackend.first
+last = _cbackend.last if _cbackend is not None else _pybackend.last
+middle = _cbackend.middle if _cbackend is not None else _pybackend.middle
+rotate = _cbackend.rotate if _cbackend is not None else _pybackend.rotate
+reverse = _cbackend.reverse if _cbackend is not None else _pybackend.reverse
+find = _cbackend.find if _cbackend is not None else _pybackend.find
+count = _cbackend.count if _cbackend is not None else _pybackend.count
+contains = _cbackend.contains if _cbackend is not None else _pybackend.contains
+chunk = _cbackend.chunk if _cbackend is not None else _pybackend.chunk
+window = _cbackend.window if _cbackend is not None else _pybackend.window
+is_sorted = _cbackend.is_sorted if _cbackend is not None else _pybackend.is_sorted

smartarr-0.1.0/src/smartarr/_pybackend.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def length(values: list[Any]) -> int:
+    return len(values)
+
+
+def is_empty(values: list[Any]) -> bool:
+    return len(values) == 0
+
+
+def first(values: list[Any]) -> Any:
+    if not values:
+        raise ValueError("smartarr.first() cannot operate on an empty sequence")
+    return values[0]
+
+
+def last(values: list[Any]) -> Any:
+    if not values:
+        raise ValueError("smartarr.last() cannot operate on an empty sequence")
+    return values[-1]
+
+
+def middle(values: list[Any], mode: str = "right") -> Any:
+    if not values:
+        raise ValueError("smartarr.middle() cannot operate on an empty sequence")
+    if mode not in {"left", "right", "avg"}:
+        raise ValueError("middle mode must be one of: right, left, avg")
+
+    size = len(values)
+    if size % 2 == 1:
+        return values[size // 2]
+
+    if mode == "left":
+        return values[(size // 2) - 1]
+    if mode == "right":
+        return values[size // 2]
+
+    return (values[(size // 2) - 1] + values[size // 2]) / 2
+
+
+def rotate(values: list[Any], steps: int) -> list[Any]:
+    if not values:
+        return []
+    steps = steps % len(values)
+    if steps == 0:
+        return list(values)
+    return list(values[-steps:] + values[:-steps])
+
+
+def reverse(values: list[Any]) -> list[Any]:
+    return list(reversed(values))
+
+
+def find(values: list[Any], needle: Any) -> int:
+    for index, item in enumerate(values):
+        if item == needle:
+            return index
+    return -1
+
+
+def count(values: list[Any], needle: Any) -> int:
+    total = 0
+    for item in values:
+        if item == needle:
+            total += 1
+    return total
+
+
+def contains(values: list[Any], needle: Any) -> bool:
+    return find(values, needle) != -1
+
+
+def chunk(values: list[Any], size: int, drop_last: bool = False) -> list[list[Any]]:
+    if size <= 0:
+        raise ValueError("chunk size must be greater than 0")
+
+    chunks = [values[index : index + size] for index in range(0, len(values), size)]
+    if drop_last and chunks and len(chunks[-1]) < size:
+        chunks.pop()
+    return chunks
+
+
+def window(values: list[Any], size: int, step: int = 1) -> list[list[Any]]:
+    if size <= 0:
+        raise ValueError("window size must be greater than 0")
+    if step <= 0:
+        raise ValueError("window step must be greater than 0")
+    if size > len(values):
+        return []
+
+    return [
+        values[index : index + size]
+        for index in range(0, len(values) - size + 1, step)
+    ]
+
+
+def is_sorted(values: list[Any], reverse: bool = False) -> bool:
+    if len(values) < 2:
+        return True
+
+    if reverse:
+        return all(values[index - 1] >= values[index] for index in range(1, len(values)))
+    return all(values[index - 1] <= values[index] for index in range(1, len(values)))