|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Module Organization |
| 4 | +The Python package lives in `src/blosc2/`, including the C/Cython extension sources |
| 5 | +(`blosc2_ext.*`) and core modules such as `core.py`, `ndarray.py`, and `schunk.py`. |
| 6 | +Tests are under `tests/`, with additional doctests enabled for select modules per |
| 7 | +`pytest.ini`. Documentation sources are in `doc/` and build output lands in `html/`. |
| 8 | +Examples are in `examples/`, and performance/benchmark scripts live in `bench/`. |
| 9 | + |
| 10 | +## Build, Test, and Development Commands |
| 11 | +- `pip install .` builds the bundled C-Blosc2 and installs the package. |
| 12 | +- `pip install -e .` installs in editable mode for local development. |
| 13 | +- `CMAKE_PREFIX_PATH=/usr/local USE_SYSTEM_BLOSC2=1 pip install -e .` builds |
| 14 | + against a separately installed C-Blosc2. |
| 15 | +- `pytest` runs the default test suite (excludes `heavy` and `network` markers). |
| 16 | +- `pytest -m "heavy"` runs long-running tests. |
| 17 | +- `pytest -m "network"` runs tests requiring network access. |
| 18 | +- `cd doc && rm -rf ../html _build && python -m sphinx . ../html` builds docs. |
| 19 | + |
| 20 | +## Coding Style & Naming Conventions |
| 21 | +Use Ruff for formatting and linting (line length 109). Enable pre-commit hooks: |
| 22 | +`python -m pip install pre-commit` then `pre-commit install`. Follow Python |
| 23 | +conventions: 4-space indentation, `snake_case` for functions/variables, and |
| 24 | +`PascalCase` for classes. Pytest discovery expects `tests/test_*.py` and |
| 25 | +`test_*` functions. Do not use leading underscores in module-level helper |
| 26 | +function names when those helpers are imported from other modules; reserve |
| 27 | +leading underscores for file-local implementation details. Avoid leading |
| 28 | +underscores in core module filenames under `src/blosc2/`; prefer non-underscored |
| 29 | +module names unless there is a strong reason to keep a module private. |
| 30 | + |
| 31 | +For documentation and tutorial query examples, prefer the shortest idiom that |
| 32 | +matches the intended result type. Use `expr[:]` or `arr[mask][:]` when showing |
| 33 | +values, use `expr.compute()` when materializing an `NDArray`, and use |
| 34 | +`expr.compute(_use_index=False)` when demonstrating scan-vs-index behavior. |
| 35 | +Avoid `expr.compute()[:]` unless a NumPy array is specifically required. |
| 36 | + |
| 37 | +## Testing Guidelines |
| 38 | +Pytest is required; warnings are treated as errors. The default configuration |
| 39 | +adds `--doctest-modules`, so keep doctest examples in `blosc2/core.py`, |
| 40 | +`blosc2/ndarray.py`, and `blosc2/schunk.py` accurate. Use markers `heavy` and |
| 41 | +`network` for slow or network-dependent tests. |
| 42 | + |
| 43 | +## Commit & Pull Request Guidelines |
| 44 | +Recent commit messages are short, imperative sentences (e.g., “Add …”, “Fix …”) |
| 45 | +without ticket prefixes. For pull requests: branch from `main`, add tests for |
| 46 | +behavior changes, update docs for API changes, ensure the test suite passes, |
| 47 | +and avoid introducing new compiler warnings. Link issues when applicable and |
| 48 | +include clear reproduction steps for bug fixes. |
0 commit comments