The Python package lives in src/blosc2/, including the C/Cython extension sources
(blosc2_ext.*) and core modules such as core.py, ndarray.py, and schunk.py.
Tests are under tests/, with additional doctests enabled for select modules per
pytest.ini. Documentation sources are in doc/ and build output lands in html/.
Examples are in examples/, and performance/benchmark scripts live in bench/.
IMPORTANT — Environment: Always use the blosc2 conda environment for
running Python, tests, and any build/install commands
(conda activate blosc2, or conda run -n blosc2 …). It holds the working
editable install whose compiled extension matches the src/ sources. Other
interpreters (e.g. the miniforge base env) may load a stale blosc2_ext
shared library and fail with errors like
AttributeError: 'super' object has no attribute 'get_sparse_numpy'.
pip install .builds the bundled C-Blosc2 and installs the package.pip install -e .installs in editable mode for local development.CMAKE_PREFIX_PATH=/usr/local USE_SYSTEM_BLOSC2=1 pip install -e .builds against a separately installed C-Blosc2.pytestruns the default test suite (excludesheavyandnetworkmarkers).pytest -m "heavy"runs long-running tests.pytest -m "network"runs tests requiring network access.cd doc && rm -rf ../html _build && python -m sphinx . ../htmlbuilds docs.
- Keep a persistent CMake build directory and reuse the same native source
override (
FETCHCONTENT_SOURCE_DIR_MINIEXPR) when testing a local miniexpr checkout. - After native/Cython edits, prefer a direct incremental build over rebuilding a
wheel or repeating
pip install -e .:conda run -n blosc2 cmake --build <build-dir> --parallel 8. - Verify
blosc2.__file__andblosc2.blosc2_ext.__file__before testing: both must belong to the intended checkout/test package. A direct build does not necessarily update the extension copy loaded by an editable install. If needed, refresh only the rebuilt extensions in an isolated test package; do not overwrite another checkout's shared installation. - For isolated imports, use conda Python with
-Sand explicitly select the test package and dependency paths. Run pytest in that process with-n 0; workers can otherwise reload the shared editable install instead of the intended package. - Pure Python edits need no rebuild. Reinstall when packaging/configuration changes require it, and retain independent-wheel checks for final integration qualification.
Use Ruff for formatting and linting (line length 109). Enable pre-commit hooks:
python -m pip install pre-commit then pre-commit install. Follow Python
conventions: 4-space indentation, snake_case for functions/variables, and
PascalCase for classes. Pytest discovery expects tests/test_*.py and
test_* functions. Do not use leading underscores in module-level helper
function names when those helpers are imported from other modules; reserve
leading underscores for file-local implementation details. Avoid leading
underscores in core module filenames under src/blosc2/; prefer non-underscored
module names unless there is a strong reason to keep a module private.
For documentation and tutorial query examples, prefer the shortest idiom that
matches the intended result type. Use expr[:] or arr[mask][:] when showing
values, use expr.compute() when materializing an NDArray, and use
expr.compute(_use_index=False) when demonstrating scan-vs-index behavior.
Avoid expr.compute()[:] unless a NumPy array is specifically required.
Pytest is required; warnings are treated as errors. The default configuration
adds --doctest-modules, so keep doctest examples in blosc2/core.py,
blosc2/ndarray.py, and blosc2/schunk.py accurate. Use markers heavy and
network for slow or network-dependent tests.
Test behavior at the layer that owns it: exhaustive native numerical semantics, dtype/operator matrices, and JIT backend parity belong in miniexpr (or C-Blosc2 for its features). Python-Blosc2 tests should focus on bindings, API contracts, dispatch, scheduling, and a small representative set of end-to-end cases. Check existing native coverage before adding parametrized Python matrices; extend the native tests rather than duplicating their cross-products here.
Use pytest with the configured parallel workers by default. Reserve the slower pytest -n 0 for short, targeted tests requiring single-process execution, or isolated-package tests where workers could import the wrong installation
- Use
gh run watch <run-id> --interval 60 --exit-status(or a longer interval), never the three-second default. Avoid duplicate watchers across agents. - On rate limits, stop requests until
Retry-AfterorX-RateLimit-Resetallows resuming. Watcher/API errors do not imply CI test failures.
Recent commit messages are short, imperative sentences (e.g., “Add …”, “Fix …”)
without ticket prefixes. For pull requests: branch from main, add tests for
behavior changes, update docs for API changes, ensure the test suite passes,
and avoid introducing new compiler warnings. Link issues when applicable and
include clear reproduction steps for bug fixes.
IMPORTANT — Agent commit policy: Never run git commit, git push,
git reset, git rebase, or any other destructive/state-changing git operation
without explicit user's consent. Committing and all repo state changes are
exclusively the user’s decision.
Never ask, offer, suggest, or otherwise raise the topic of committing — not "Want me to commit?", not "Should I commit these as one commit or split?", not "ready to commit". Do not propose commit messages or splits unprompted. When the code work is done, summarize what changed and stop. The user alone decides if and when to commit, and will say so explicitly when they want it. Only act on commits when the user directly instructs you to.