Development workflows

This page records the recommended local checks for contributors and release preparation. The default workflow is offline and deterministic. Live NIST Chemistry WebBook checks are kept separate because failures may reflect network availability or upstream HTML changes rather than a package regression.

Offline tests

Install development dependencies and run the default suite:

python -m pip install -e ".[dev]"
pytest -q

The default suite uses synthetic/sanitized fixtures and does not contact the NIST Chemistry WebBook.

Coverage

For a coverage report:

coverage run -m pytest -q
coverage report -m

The index subsystem, request wrappers, search parsing, compound objects, and implemented property parsers should remain covered by offline tests. New parser features should normally add synthetic or sanitized fixture pages under tests/fixtures/.

Online tests

Live integration tests are stored under tests/online and marked with network. RDKit-dependent structural tests are additionally marked with rdkit. Offline tests run by default; select live or RDKit-specific subsets with pytest marker expressions:

pytest -q -m network
pytest -q -m "network and not rdkit"
pytest -q -m "network and rdkit"
pytest -q -m "rdkit and not network"

Long-running or broad WebBook reconstruction tests should not be added to the normal online suite. Prefer small smoke tests with known stable pages. If a live test fails, first check whether the upstream WebBook page or network behavior changed before treating it as a package bug.

Notebook regeneration

Documentation notebooks are committed with pregenerated outputs, while Sphinx is configured with nbsphinx_execute = 'never'. Regenerate notebooks manually when examples or public APIs change:

python -m pip install -e ".[docs,structure]"
jupyter nbconvert --execute docs/source/basic_search.ipynb --inplace
jupyter nbconvert --execute docs/source/compound_properties.ipynb --inplace
jupyter nbconvert --execute docs/source/structural_search.ipynb --inplace
jupyter nbconvert --execute docs/source/local_index.ipynb --inplace
jupyter nbconvert --execute docs/source/requests_config.ipynb --inplace

User-facing notebooks may contain pregenerated live WebBook outputs. Sphinx does not execute notebooks during documentation builds, so rerun notebooks manually before release or after public API changes. Keep long-running or broad index reconstruction outside notebooks; use tiny local CSV fixtures for local index examples.

Documentation build

Build the documentation locally with:

python -m pip install -e ".[docs,structure]"
cd docs
make html

Release artifact check

Before publishing a release, build the package and verify that no generated WebBook-derived artifacts are included:

python -m build
python tools/check_package_artifacts.py dist/*

The release check rejects files such as nist_data.zip, nist_data.csv, compounds_data.json, and package-internal nistchempy/data/ contents.