Skip to content

Home

Jump to bottom
David Bookstaber edited this page Sep 26, 2025 · 21 revisions

Installation

It is not necessary to run setup.py build_ext --inplace or py -m build then install from dist, because the package has long been configured for self-assembly. More clear way to build and install exts (cython extensions) from repo root:

cd  ./py_ballisticcalc.exts
pip install -e .

To remove just pip uninstall py_ballisticcalc.exts

This is because when installing through pip it tries to build wheel using setup.py or pyproject.toml, which creates an isolated environment, downloads build dependencies (like setuptools and cython) and then builds wheel, then installs package using this wheel. So if using -e flag it installs it locally in editable mode (not to the site packages). Then if you change the code in pyx/pxd you can re-run pip install -e . to recompile binaries. With pure python modules you should not rerun pip install after changes, except in cases when you added entries to pyproject.toml, setup.py, etc.

Or to ensure all dependencies, from repo-root:

pip install -e .[dev,charts]
pip install -e ./py_ballisticcalc.exts[dev]

Alternative:

cd ./py_ballisticcalc.exts
pip install cython
python setup.py build_ext --inplace

Now with uv:

  • uv pip install -e py_ballisticcalc_exts --no-cache
  • uv sync --dev alone will removes exts
  • python .\py_ballisticcalc.exts\scripts\cleanup.py should removes old build artifacts
  • uv sync --dev --extra exts --no-cache should force rebuild

Development

uv sync --python="3.12" --dev --extra exts

(Without the --python argument it will default to the earliest supported version of Python.)

Then to get into the virtual environment that creates run: .venv\Scripts\activate

Test

  • pytest tests ... add -o log_cli=true -o log_cli_level=WARNING to display logger statements even on success.
  • pytest tests --engine="scipy_engine"
  • pytest tests/zero_finding.py --engine="cythonized_euler_engine"

There are also Cython-specific tests in the Cython project subfolder:

  • pytest .\py_ballisticcalc.exts\tests
  • pytest .\py_ballisticcalc.exts\tests -m stress to run stress tests

This Powershell script tests all engines and produces a summary.

Coverage

  • pytest --cov=py_ballisticcalc --cov-report=term-missing lists coverage% and lines missing coverage by module.
  • pytest --cov=py_ballisticcalc --cov-report=html generates HTML report in htmlcov subfolders

We can also include cython coverage.

python scripts\sync_cython_sources.py
pytest --engine="cythonized_rk4_engine" --cov=py_ballisticcalc --cov=py_ballisticcalc_exts --cov-report=html

Other checks

  1. mypy
  2. uv run ruff check
  3. Docstrings: pydocstyle .\py_ballisticcalc\
  4. Doctests: .\scripts\run_doctest.py
  5. uv run ruff format --diff to check Black-style formatting.

Documentation

Code should use Google style DocStrings.

Good example of documentation style we want for this project.

MkDocs

Use pure package installed only, because mkdocs can't read docstrings from .pyx and .pyd. To prepare venv for mkdocs use pip install -e .[docs].

Then start server by running mkdocs serve. Modify mkdocs.yml and docs/**/*.md on the fly to see changes.

Helpful references:

Clone this wiki locally