numba-utils 0.1.0__tar.gz

numba_utils-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolás Seijas
+
+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.

numba_utils-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: numba-utils
+Version: 0.1.0
+Summary: Battle-tested building blocks for production Numba workloads.
+Author-email: Nicolás Seijas <nicoseijas@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nicoseijas/numba-utils
+Project-URL: Repository, https://github.com/nicoseijas/numba-utils
+Project-URL: Documentation, https://nicoseijas.github.io/numba-utils/
+Project-URL: Changelog, https://github.com/nicoseijas/numba-utils/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/nicoseijas/numba-utils/issues
+Keywords: numba,njit,jit,high-performance,numerical-computing,hpc,parallel,benchmarking,data-structures
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numba
+Requires-Dist: numpy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Dynamic: license-file
+
+# numba-utils
+
+**Battle-tested building blocks for production
+[Numba](https://numba.pydata.org/) workloads.** Built for production
+numerical software with Numba.
+
+✓ Zero dependencies beyond NumPy + Numba &nbsp;·&nbsp; ✓ Callable inside
+`@njit` &nbsp;·&nbsp; ✓ Honest benchmarks &nbsp;·&nbsp; ✓ Diagnostics
+&nbsp;·&nbsp; ✓ CI &nbsp;·&nbsp; ✓ MIT
+
+```
+                    Numba
+                      ▲
+                      │
+                 numba-utils
+      ┌───────────────┼───────────────┐
+   Arrays        Collections       Parallel
+   Algorithms    Random            Profiling
+   Decorators    Testing           Diagnostics
+```
+
+```python
+from numba import njit
+from numba_utils import topk
+
+@njit
+def winners(scores):
+    return topk(scores, 10)     # O(n), no full sort — runs in nopython mode
+```
+
+```python
+from numba import njit
+from numba_utils import PriorityQueue, SparseSet
+
+@njit
+def simulate(n_events):
+    events = PriorityQueue(n_events)    # constructed in nopython mode
+    active = SparseSet(100_000)         # O(1) add/discard/contains/clear
+    ...
+```
+
+```python
+from numba_utils import compare
+
+compare(numpy_impl, njit_impl, args=(values,))
+# 31x on a fused kernel — JIT compilation excluded automatically
+```
+
+And the part that almost no library ships — diagnostics for compiled
+code:
+
+```python
+>>> from numba_utils import diagnostics
+>>> diagnostics.check(fn)
+⚠ cache=True may crash when loaded across processes (farms, network FS)
+  → NUMBA_UTILS_CACHE=0  or  configure(cache=False)
+⚠ fastmath=True relaxes IEEE 754 — not for exact/reproducible results
+```
+
+## Why this exists
+
+After enough numerical projects — long-running Monte Carlo engines,
+solvers, simulation farms — you realize you've rewritten the same binary
+search, the same typed collections, the same sampling algorithms and the
+same benchmarking helpers again. And debugged the same Numba production
+surprises again.
+
+numba-utils ships more than code. It ships the production knowledge
+that usually stays trapped inside numerical projects — as kernels with
+the pitfalls engineered around, as diagnostics, and as
+[documentation](https://github.com/nicoseijas/numba-utils/tree/main/docs).
+It does not compete with Numba: it builds on top of it.
+
+## Why not...
+
+- **heapq / `collections`?** They can't be called from nopython mode.
+  The containers here are jitclasses usable inside `@njit`.
+- **NumPy?** Many helpers are built to run *inside* compiled kernels,
+  where NumPy calls can't reach. Where NumPy is faster (bandwidth-bound
+  sweeps, its SIMD sort),
+  [BENCHMARKS.md](https://github.com/nicoseijas/numba-utils/blob/main/BENCHMARKS.md)
+  says so.
+- **SciPy?** A heavy dependency that isn't njit-callable; this stays at
+  NumPy + Numba and works in the compiled path.
+- **Numba itself?** Numba is a compiler. numba-utils is a standard
+  library on top of it.
+
+## Design principles
+
+1. **Performance First** — nothing ships without a benchmarked justification.
+2. **No Hidden Magic** — thin, readable layers over Numba; nothing rewrites your code.
+3. **Numba Compatible** — everything callable from your own `@njit` code, no hacks.
+4. **Minimal APIs** — `topk(arr, 10)`, not twenty keyword parameters.
+5. **Benchmark Honesty** — losses are published next to the wins.
+
+The identity behind these:
+[docs/philosophy.md](https://github.com/nicoseijas/numba-utils/blob/main/docs/philosophy.md).
+
+## Modules
+
+**Core** — decorators, arrays, algorithms ·
+**Performance** — parallel (complete operations, not prange wrappers),
+profiling (JIT excluded by default), diagnostics ·
+**Data structures** — collections, random ·
+**Developer tools** — testing, config
+
+Full API:
+[docs/modules.md](https://github.com/nicoseijas/numba-utils/blob/main/docs/modules.md)
+· Runnable code:
+[examples/](https://github.com/nicoseijas/numba-utils/tree/main/examples)
+
+## Benchmark honesty
+
+Every algorithm states whether it is **faster**, **similar but more
+ergonomic**, or **slower but solving a problem unavailable elsewhere**.
+[BENCHMARKS.md](https://github.com/nicoseijas/numba-utils/blob/main/BENCHMARKS.md)
+contains losing rows on purpose: they tell you when NOT to use a
+function. Backed in-repo by reproducible
+[benchmarks/](https://github.com/nicoseijas/numba-utils/tree/main/benchmarks),
+200+ reference-validated tests
+([why there's no coverage badge](https://github.com/nicoseijas/numba-utils/blob/main/docs/testing.md)),
+and CI running all of it. Trade-off records:
+[docs/design/](https://github.com/nicoseijas/numba-utils/tree/main/docs/design).
+
+## Used in
+
+Patterns extracted from real workloads: Monte Carlo equity engines,
+game-theory solvers (CFR), quantitative research, scientific
+simulations, optimization loops.
+
+## Status
+
+Phase 1 (see
+[ROADMAP.md](https://github.com/nicoseijas/numba-utils/blob/main/ROADMAP.md)):
+
+- [x] decorators, profiling, diagnostics, config
+- [x] arrays, algorithms, random, collections
+- [x] parallel patterns, testing helpers
+- [ ] dtype-generic collections, `stable_argsort`, `lexsort`
+- [ ] PyPI release
+
+## Development
+
+```
+python -m venv .venv
+.venv/Scripts/pip install -e .[dev]
+.venv/Scripts/python -m pytest
+```
+
+Contributions follow
+[GUIDELINES.md](https://github.com/nicoseijas/numba-utils/blob/main/GUIDELINES.md)
+— benchmarks are mandatory, honesty is policy.

numba_utils-0.1.0/README.md

@@ -0,0 +1,152 @@
+# numba-utils
+
+**Battle-tested building blocks for production
+[Numba](https://numba.pydata.org/) workloads.** Built for production
+numerical software with Numba.
+
+✓ Zero dependencies beyond NumPy + Numba  ·  ✓ Callable inside
+`@njit`  ·  ✓ Honest benchmarks  ·  ✓ Diagnostics
+ ·  ✓ CI  ·  ✓ MIT
+
+```
+                    Numba
+                      ▲
+                      │
+                 numba-utils
+      ┌───────────────┼───────────────┐
+   Arrays        Collections       Parallel
+   Algorithms    Random            Profiling
+   Decorators    Testing           Diagnostics
+```
+
+```python
+from numba import njit
+from numba_utils import topk
+
+@njit
+def winners(scores):
+    return topk(scores, 10)     # O(n), no full sort — runs in nopython mode
+```
+
+```python
+from numba import njit
+from numba_utils import PriorityQueue, SparseSet
+
+@njit
+def simulate(n_events):
+    events = PriorityQueue(n_events)    # constructed in nopython mode
+    active = SparseSet(100_000)         # O(1) add/discard/contains/clear
+    ...
+```
+
+```python
+from numba_utils import compare
+
+compare(numpy_impl, njit_impl, args=(values,))
+# 31x on a fused kernel — JIT compilation excluded automatically
+```
+
+And the part that almost no library ships — diagnostics for compiled
+code:
+
+```python
+>>> from numba_utils import diagnostics
+>>> diagnostics.check(fn)
+⚠ cache=True may crash when loaded across processes (farms, network FS)
+  → NUMBA_UTILS_CACHE=0  or  configure(cache=False)
+⚠ fastmath=True relaxes IEEE 754 — not for exact/reproducible results
+```
+
+## Why this exists
+
+After enough numerical projects — long-running Monte Carlo engines,
+solvers, simulation farms — you realize you've rewritten the same binary
+search, the same typed collections, the same sampling algorithms and the
+same benchmarking helpers again. And debugged the same Numba production
+surprises again.
+
+numba-utils ships more than code. It ships the production knowledge
+that usually stays trapped inside numerical projects — as kernels with
+the pitfalls engineered around, as diagnostics, and as
+[documentation](https://github.com/nicoseijas/numba-utils/tree/main/docs).
+It does not compete with Numba: it builds on top of it.
+
+## Why not...
+
+- **heapq / `collections`?** They can't be called from nopython mode.
+  The containers here are jitclasses usable inside `@njit`.
+- **NumPy?** Many helpers are built to run *inside* compiled kernels,
+  where NumPy calls can't reach. Where NumPy is faster (bandwidth-bound
+  sweeps, its SIMD sort),
+  [BENCHMARKS.md](https://github.com/nicoseijas/numba-utils/blob/main/BENCHMARKS.md)
+  says so.
+- **SciPy?** A heavy dependency that isn't njit-callable; this stays at
+  NumPy + Numba and works in the compiled path.
+- **Numba itself?** Numba is a compiler. numba-utils is a standard
+  library on top of it.
+
+## Design principles
+
+1. **Performance First** — nothing ships without a benchmarked justification.
+2. **No Hidden Magic** — thin, readable layers over Numba; nothing rewrites your code.
+3. **Numba Compatible** — everything callable from your own `@njit` code, no hacks.
+4. **Minimal APIs** — `topk(arr, 10)`, not twenty keyword parameters.
+5. **Benchmark Honesty** — losses are published next to the wins.
+
+The identity behind these:
+[docs/philosophy.md](https://github.com/nicoseijas/numba-utils/blob/main/docs/philosophy.md).
+
+## Modules
+
+**Core** — decorators, arrays, algorithms ·
+**Performance** — parallel (complete operations, not prange wrappers),
+profiling (JIT excluded by default), diagnostics ·
+**Data structures** — collections, random ·
+**Developer tools** — testing, config
+
+Full API:
+[docs/modules.md](https://github.com/nicoseijas/numba-utils/blob/main/docs/modules.md)
+· Runnable code:
+[examples/](https://github.com/nicoseijas/numba-utils/tree/main/examples)
+
+## Benchmark honesty
+
+Every algorithm states whether it is **faster**, **similar but more
+ergonomic**, or **slower but solving a problem unavailable elsewhere**.
+[BENCHMARKS.md](https://github.com/nicoseijas/numba-utils/blob/main/BENCHMARKS.md)
+contains losing rows on purpose: they tell you when NOT to use a
+function. Backed in-repo by reproducible
+[benchmarks/](https://github.com/nicoseijas/numba-utils/tree/main/benchmarks),
+200+ reference-validated tests
+([why there's no coverage badge](https://github.com/nicoseijas/numba-utils/blob/main/docs/testing.md)),
+and CI running all of it. Trade-off records:
+[docs/design/](https://github.com/nicoseijas/numba-utils/tree/main/docs/design).
+
+## Used in
+
+Patterns extracted from real workloads: Monte Carlo equity engines,
+game-theory solvers (CFR), quantitative research, scientific
+simulations, optimization loops.
+
+## Status
+
+Phase 1 (see
+[ROADMAP.md](https://github.com/nicoseijas/numba-utils/blob/main/ROADMAP.md)):
+
+- [x] decorators, profiling, diagnostics, config
+- [x] arrays, algorithms, random, collections
+- [x] parallel patterns, testing helpers
+- [ ] dtype-generic collections, `stable_argsort`, `lexsort`
+- [ ] PyPI release
+
+## Development
+
+```
+python -m venv .venv
+.venv/Scripts/pip install -e .[dev]
+.venv/Scripts/python -m pytest
+```
+
+Contributions follow
+[GUIDELINES.md](https://github.com/nicoseijas/numba-utils/blob/main/GUIDELINES.md)
+— benchmarks are mandatory, honesty is policy.

numba_utils-0.1.0/numba_utils/__init__.py

@@ -0,0 +1,137 @@
+"""numba-utils: high-performance building blocks for Numba."""
+
+from numba_utils import diagnostics, testing
+from numba_utils._config import config, configure
+from numba_utils.algorithms import (
+    argmax2,
+    counting_sort,
+    fast_argpartition,
+    insertion_sort,
+    nth_element,
+    partial_sort,
+    quickselect,
+    radix_sort,
+    topk,
+)
+from numba_utils.arrays import (
+    bincount,
+    binary_search,
+    cumulative_sum,
+    fast_clip,
+    histogram,
+    lower_bound,
+    normalize,
+    rolling_mean,
+    rolling_sum,
+    unique_sorted,
+    upper_bound,
+)
+from numba_utils.collections import (
+    BitSet,
+    FixedQueue,
+    ObjectPool,
+    PriorityQueue,
+    RingBuffer,
+    SparseSet,
+    Stack,
+    counter,
+    typed_defaultdict,
+)
+from numba_utils.decorators import (
+    boundscheck,
+    cached_njit,
+    njit_fast,
+    njit_parallel,
+)
+from numba_utils.parallel import (
+    parallel_histogram,
+    parallel_prefix_sum,
+    parallel_reduce,
+    parallel_sum,
+    parallel_topk,
+)
+from numba_utils.profiling import (
+    BenchmarkResult,
+    ComparisonResult,
+    TimingStats,
+    benchmark,
+    compare,
+    compile_stats,
+    compile_time,
+    warmup,
+)
+from numba_utils.random import (
+    alias_draw,
+    alias_sample,
+    alias_setup,
+    choice,
+    permutation,
+    reservoir_sampling,
+    seed,
+    shuffle,
+    weighted_sampling,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BenchmarkResult",
+    "BitSet",
+    "ComparisonResult",
+    "FixedQueue",
+    "ObjectPool",
+    "PriorityQueue",
+    "RingBuffer",
+    "SparseSet",
+    "Stack",
+    "TimingStats",
+    "alias_draw",
+    "alias_sample",
+    "alias_setup",
+    "argmax2",
+    "benchmark",
+    "bincount",
+    "binary_search",
+    "boundscheck",
+    "cached_njit",
+    "choice",
+    "compare",
+    "compile_stats",
+    "compile_time",
+    "config",
+    "configure",
+    "counter",
+    "counting_sort",
+    "cumulative_sum",
+    "diagnostics",
+    "fast_argpartition",
+    "fast_clip",
+    "histogram",
+    "insertion_sort",
+    "lower_bound",
+    "njit_fast",
+    "njit_parallel",
+    "normalize",
+    "nth_element",
+    "parallel_histogram",
+    "parallel_prefix_sum",
+    "parallel_reduce",
+    "parallel_sum",
+    "parallel_topk",
+    "partial_sort",
+    "permutation",
+    "quickselect",
+    "radix_sort",
+    "reservoir_sampling",
+    "rolling_mean",
+    "rolling_sum",
+    "seed",
+    "shuffle",
+    "testing",
+    "topk",
+    "typed_defaultdict",
+    "unique_sorted",
+    "upper_bound",
+    "warmup",
+    "weighted_sampling",
+]

numba_utils-0.1.0/numba_utils/_config.py

@@ -0,0 +1,92 @@
+"""Global configuration: code-level overrides with environment fallbacks.
+
+Two levels, resolved per option at decoration time:
+
+1. Code: ``configure(cache=False)`` or ``config.cache = False``.
+2. Environment: ``NUMBA_UTILS_CACHE=0`` (checked only when the code level
+   is unset).
+
+A set option (``True``/``False``) is a GLOBAL override: it wins over
+decorator defaults and per-call keyword arguments alike. That is the
+point — overrides exist for environment-level policy, like disabling the
+on-disk cache on machines where it is unsafe (see docs/numba-cache.md).
+``None`` means "no override": decorator defaults and per-call arguments
+apply unchanged.
+
+Overrides affect only functions decorated AFTER the change — configure
+before defining your jitted functions.
+"""
+
+from __future__ import annotations
+
+import os
+
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+_FALSY = frozenset({"0", "false", "no", "off"})
+
+OPTION_ENV_VARS = {
+    "cache": "NUMBA_UTILS_CACHE",
+    "fastmath": "NUMBA_UTILS_FASTMATH",
+    "parallel": "NUMBA_UTILS_PARALLEL",
+    "nogil": "NUMBA_UTILS_NOGIL",
+}
+
+
+class GlobalConfig:
+    """Tri-state global overrides for every numba-utils decorator.
+
+    Attributes ``cache``, ``fastmath``, ``parallel``, ``nogil`` are each
+    ``None`` (no override), ``True`` or ``False`` (forced globally).
+    """
+
+    __slots__ = ("cache", "fastmath", "parallel", "nogil")
+
+    def __init__(self) -> None:
+        self.reset()
+
+    def reset(self) -> None:
+        """Clear all code-level overrides. Environment fallbacks remain."""
+        for name in OPTION_ENV_VARS:
+            setattr(self, name, None)
+
+    def resolve(self, name: str) -> bool | None:
+        """Effective override for ``name``: code level, else environment,
+        else ``None``. Unrecognized environment values count as unset."""
+        value = getattr(self, name)
+        if value is not None:
+            return bool(value)
+        raw = os.environ.get(OPTION_ENV_VARS[name], "").strip().lower()
+        if raw in _TRUTHY:
+            return True
+        if raw in _FALSY:
+            return False
+        return None
+
+
+config = GlobalConfig()
+
+
+def configure(**options: bool | None) -> None:
+    """Set global decorator overrides in code.
+
+    ::
+
+        import numba_utils as nu
+        nu.configure(cache=False, fastmath=True)
+
+    Valid options: ``cache``, ``fastmath``, ``parallel``, ``nogil``.
+    Pass ``None`` to clear a single override; ``config.reset()`` clears
+    all. Raises ``ValueError`` on unknown names (fail fast, no typos
+    silently ignored).
+    """
+    for name, value in options.items():
+        if name not in OPTION_ENV_VARS:
+            valid = ", ".join(sorted(OPTION_ENV_VARS))
+            raise ValueError(
+                f"configure: unknown option {name!r}; valid options: {valid}"
+            )
+        if value is not None and not isinstance(value, bool):
+            raise ValueError(
+                f"configure: option {name!r} must be True, False or None"
+            )
+        setattr(config, name, value)

numba_utils-0.1.0/numba_utils/algorithms/__init__.py

@@ -0,0 +1,26 @@
+"""Selection and sorting algorithms specialized for Numba."""
+
+from numba_utils.algorithms._select import (
+    fast_argpartition,
+    nth_element,
+    quickselect,
+)
+from numba_utils.algorithms._sort import (
+    counting_sort,
+    insertion_sort,
+    partial_sort,
+    radix_sort,
+)
+from numba_utils.algorithms._topk import argmax2, topk
+
+__all__ = [
+    "argmax2",
+    "counting_sort",
+    "fast_argpartition",
+    "insertion_sort",
+    "nth_element",
+    "partial_sort",
+    "quickselect",
+    "radix_sort",
+    "topk",
+]