pyproject.toml

[project]
name = "biotite"
requires-python = ">=3.12"
description = "A comprehensive library for computational molecular biology"
readme = "README.rst"
authors = [{ name = "The Biotite contributors" }]
license = "BSD-3-Clause"
license-files = ["LICENSE.rst", "THIRDPARTY.yml"]
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Intended Audience :: Developers",
    "Intended Audience :: Science/Research",
    "Natural Language :: English",
    "Operating System :: POSIX :: Linux",
    "Operating System :: MacOS",
    "Operating System :: Microsoft :: Windows",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: Implementation :: CPython",
    "Topic :: Scientific/Engineering :: Bio-Informatics",
]

dependencies = [
    # Wheels compiled with NumPy 2.0 are backward compatible with NumPy 1.x
    # https://numpy.org/devdocs/dev/depending_on_numpy.html#numpy-2-0-specific-advice
    "numpy >= 1.25",
    "biotraj >= 1.0, < 2.0",
    "requests >= 2.12",
    "msgpack >= 0.5.6",
    "networkx >= 2.0",
    "packaging >= 24.0",
]
dynamic = ["version"]

[project.optional-dependencies]
test = ["pytest", "pytest-codspeed"]
lint = ["ruff == 0.9.7", "numpydoc == 1.8.0", "pyright == 1.1.409", "taplo == 0.9.3"]

[project.urls]
homepage = "https://www.biotite-python.org"
repository = "https://github.com/biotite-dev/biotite"
documentation = "https://www.biotite-python.org"

[tool.ruff.lint]
select = [
    "F",    # Pyflakes (undefined names, unused imports, etc.)
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "I",    # isort (import ordering)
    "TID",  # flake8-tidy-imports (no relative imports)
    "N",    # pep8-naming (variable/function/class naming conventions)
    "ANN2", # missing return type annotations (`pyright` `reportMissingParameterType` only checks for missing parameter type annotations)
]
ignore = [
    # In docstrings long lines are often intentional
    # Most other ocassions are caught by the ruff formatter
    "E501",
    # Due to constants and class placeholders defined in functions
    "N806",
]

[tool.ruff.lint.per-file-ignores]
# Due to `* import` of BCIF encoding
"src/biotite/setup_ccd.py" = ["F405", "F403"]
# Due to imports after the PATH has been adjusted
"doc/conf.py" = ["E402"]
# Due to `from .module import *` imports in `__init__.py` modules
"__init__.py" = ["F403", "TID252"]
# Due to package existence check before other modules are imported
"src/biotite/interface/**/__init__.py" = ["E402"]
# Due to pymol scripts that are evaluated in other example scripts
"doc/examples/**/*_pymol.py" = ["F821"]
# Due to 'Table' class used as parametrized argument in test functions
"benchmarks/sequence/align/benchmark_kmers.py" = ["N803"]
# Annotation enforcement is reserved for the library source code
# tests, benchmarks and documentation scripts are exempt
"setup.py" = ["ANN2"]
"tests/**/*.py" = ["ANN2"]
"benchmarks/**/*.py" = ["ANN2"]
"doc/**/*.py" = ["ANN2"]

[tool.ruff.lint.flake8-tidy-imports]
ban-relative-imports = "all"

[tool.ruff.lint.isort]
# No separator lines between import sections
no-lines-before = ["future", "standard-library", "third-party", "first-party", "local-folder"]
order-by-type = true
known-first-party = ["biotite"]

[tool.numpydoc_validation]
# The description of each rule is documented at
# https://numpydoc.readthedocs.io/en/latest/validation.html#built-in-validation-checks
checks = [
    "all",
    # ... except:
    "GL08", # Properties do not have a docstring
    "SS03", # Sometimes the citation comes after the period
    "SS05", # Too error-prone; classes do not use infinite verbs
    "SS06", # Sometimes summaries are a bit longer
    "ES01", # Some functions are simple enough to not need an extended summary
    "PR06", # The types are quite descriptive (include shape, dtype, etc.)
    "RT02", # In Biotite all return values have names
    # Intentionally not all docstrings contain these sections
    "YD01",
    "SA01",
    "EX01",
]
exclude = [
    '__init__$',      # Subpackage descriptions are not Numpydoc formatted
    '\._[_a-z0-9]+$', # Do not validate private or special methods
    # Dataclasses: Numpydoc complains about additional constructor parameters,
    # but the constructor is absent
    'sdf.Metadata\.Key',
    'header.Header',
    'throttle.ThrottleStatus',
    # Numpydoc does not accept the parameters of inherited constructors
    "query.DepositGrouping",
    "query.UniprotGrouping",
    # Function uses args/kwargs, but docstring describes parameter
    'geometry.index_',
    'query.FieldQuery',
    'query.SimilarityQuery',
    'query.IdentityQuery',
    'query.StructureQuery',
    'query.SuperOrSubstructureQuery',
    'query.SuperstructureQuery',
    'query.SubstructureQuery',
    # Numpydoc expects a return value for decorators
    'application.requires_state',
    'version.requires_version',
    'object.validate',
    # Usage of the return value is not intended
    'display.show',
    'display.play',
]

[tool.pytest.ini_options]
testpaths = ["tests", "benchmarks"]
python_files = ["test_*.py", "benchmark_*.py"]
python_functions = ["test_*", "benchmark_*"]
filterwarnings = [
    # Appears in loading NetCDF trajectory files
    "ignore:The 'netCDF4' Python package is not installed.",
    "ignore:Input structure has no associated 'BondList'",
]

[tool.pyright]
include = ["src/biotite"]
exclude = [
    # `bonds.py` defines `BondType` dynamically as an `IntEnum` from Rust enum members
    # This is overridden by theP `bonds.pyi` stub
    "src/biotite/structure/bonds.py",
]
pythonVersion = "3.12"
typeCheckingMode = "basic"
# Force every parameter to carry an explicit annotation.
reportMissingParameterType = "error"

[tool.pixi.workspace]
channels = ["conda-forge", "bioconda"]
# Restricted to unix because bioconda packages have no Windows builds
platforms = ["linux-64", "linux-aarch64", "osx-64", "osx-arm64"]
requires-pixi = ">=0.40"

[tool.pixi.dependencies]
python = "3.12.*"
# Runtime
biotraj = ">=1.0,<2.0"
msgpack-python = ">=0.5.6"
networkx = ">=2.0"
numpy = ">=2.2"            # 2.2 introduces more struct typing stubs
packaging = ">=24.0"
requests = ">=2.12"
# Build
python-build = "*"
cargo-bundle-licenses = "*"
cython = ">=3.0"
pip = ">=10.0"
rust = ">=1.95"
setuptools = "*"
setuptools_scm = "*"
setuptools-rust = "*"
wheel = ">=0.30"

[tool.pixi.feature.interface.dependencies]
pymol-open-source = ">=2"
ipython = "<8.29"
ffmpeg = "*"
imagemagick = "*"
openmm = ">=8"
matplotlib = ">=3.3"

[tool.pixi.feature.interface.pypi-dependencies]
rdkit = ">=2024.09.1"

[tool.pixi.feature.application.dependencies]
vina = "*"
clustalo = "*"
dssp = "4.*"
libcifpp = "*"
mafft = "*"
sra-tools = "3.*"
tantan = "*"
viennarna = ">=2.5.0"
muscle = "3.*"

[tool.pixi.feature.test.dependencies]
pytest = ">=7.0"
pytest-codspeed = ">=2.0"

[tool.pixi.feature.muscle5.dependencies]
muscle = "5.*"

[tool.pixi.feature.lint.dependencies]
# Python style/type checkers
ruff = "==0.9.7"
numpydoc = "==1.8.0"
pyright = "==1.1.409"
taplo = "==0.9.3"
# Rust toolchain including `rustfmt` and `clippy`
rust = "==1.95"

[tool.pixi.feature.doc.dependencies]
pydata-sphinx-theme = "0.15.*"
matplotlib = ">=3.3"
ipython = "<8.29"
jupyter-sphinx = ">=0.5.3"
sphinx = ">=7.0"
sphinxcontrib-bibtex = ">=2.3"
sphinx-copybutton = ">=0.5"
sphinx-design = ">=0.5"
sphinx-gallery = "==0.18.0"
sphinx-notfound-page = ">=1.0"
numpydoc = "==1.8.0"
# Extra packages used in the example gallery
pandas = ">=1.5.2"
pydot = ">=1.4"
scikit-learn = ">=0.18"
scipy = ">=1.8.0"

[tool.pixi.environments]
default = { features = ["test", "interface", "application", "doc", "lint"] }
test = { features = ["test", "interface", "application"] }
test-muscle5 = { features = ["muscle5", "test"] }
doc = { features = ["doc", "interface", "application"] }
# `pyright` is ideally is run in the context of the runtime dependencies
# -> Add interfaced packages as well
lint = { features = ["lint", "interface"] }

[tool.pixi.tasks._pip-install-rust]
cmd = "python -m pip install -e ."
env = { BIOTITE_OMIT_CYTHON = "1" }
inputs = ["src/**/*.rs", "Cargo.toml", "pyproject.toml"]

[tool.pixi.tasks._pip-install-cython]
cmd = "python -m pip install -e ."
env = { BIOTITE_OMIT_RUST = "1" }
inputs = ["src/**/*.pyx", "src/**/*.pxd", "pyproject.toml"]

[tool.pixi.tasks._pip-install]
cmd = "python -m pip install -e ."
env = { BIOTITE_OMIT_CYTHON = "1", BIOTITE_OMIT_RUST = "1" }
depends-on = ["_pip-install-rust", "_pip-install-cython"]

[tool.pixi.tasks._current-date]
# Writes the current ISO year-month into a marker file
cmd = "date +%Y-%m > .date"

[tool.pixi.tasks._setup-ccd]
cmd = "python -m biotite.setup_ccd"
depends-on = ["_pip-install", "_current-date"]
# Cached: only re-runs once per month
inputs = [".date"]
outputs = ["src/biotite/structure/info/components.bcif"]

[tool.pixi.tasks.install]
cmd = "true"
depends-on = ["_pip-install", "_setup-ccd"]
description = "Install Biotite in editable mode"

[tool.pixi.tasks._bundle-licenses]
# Bundle the licenses of the Rust dependencies into a single file
cmd = "cargo bundle-licenses --format yaml --output THIRDPARTY.yml"
inputs = ["Cargo.toml", "Cargo.lock"]
outputs = ["THIRDPARTY.yml"]

[tool.pixi.tasks.build-wheel]
cmd = "python -m build --wheel"
depends-on = ["_setup-ccd", "_bundle-licenses"]
description = "Build a wheel distribution"

[tool.pixi.tasks.build-sdist]
cmd = "python -m build --sdist"
depends-on = ["_setup-ccd", "_bundle-licenses"]
description = "Build a source distribution"

[tool.pixi.feature.test.tasks.test]
cmd = "pytest"
depends-on = ["install"]
default-environment = "test"
description = "Run the test suite"

[tool.pixi.feature.lint.tasks]
# 'Private' tasks used by the 'lint' and 'format' tasks.
_ruff-check = { cmd = "ruff check", default-environment = "lint" }
_ruff-format-check = { cmd = "ruff format --diff", default-environment = "lint" }
# `pyright` complains if it does not see Biotite's extension modules
_pyright = { cmd = "pyright", depends-on = ["_pip-install"], default-environment = "lint" }
_numpydoc = { cmd = "numpydoc lint src/biotite/**/*.py", default-environment = "lint" }
_cargo-fmt-check = { cmd = "cargo fmt --check", default-environment = "lint" }
_cargo-clippy = { cmd = "cargo clippy -- -Dwarnings", default-environment = "lint" }
_taplo-check = { cmd = "taplo format --check", default-environment = "lint" }
_ruff-format = { cmd = "ruff format", default-environment = "lint" }
_ruff-fix = { cmd = "ruff check --fix", default-environment = "lint" }
_taplo-fmt = { cmd = "taplo format", default-environment = "lint" }
_rust-fmt = { cmd = "cargo fmt", default-environment = "lint" }
_rust-clippy = { cmd = "cargo clippy --fix --allow-dirty", default-environment = "lint" }

# A no-op `cmd = "true"` is required because pixi 0.69 only accepts the
# `default-environment` key on tasks that have a `cmd` field.
[tool.pixi.feature.lint.tasks.lint]
cmd = "true"
depends-on = [
    "_ruff-check",
    "_ruff-format-check",
    "_pyright",
    "_numpydoc",
    "_taplo-check",
    "_cargo-fmt-check",
    "_cargo-clippy",
]
default-environment = "lint"
description = "Check code style and type annotations"

[tool.pixi.feature.lint.tasks.format]
cmd = "true"
depends-on = ["_ruff-format", "_ruff-fix", "_taplo-fmt", "_rust-fmt", "_rust-clippy"]
default-environment = "lint"
description = "Apply automatic code style fixes"

[tool.pixi.feature.doc.tasks.doc]
cmd = "sphinx-build -a -D plot_gallery=0 doc build/doc"
depends-on = ["install"]
default-environment = "doc"
description = "Build documentation without the example gallery"

[tool.pixi.feature.doc.tasks.doc-full]
cmd = "sphinx-build -a doc build/doc"
depends-on = ["install"]
default-environment = "doc"
description = "Build documentation including the example gallery"

[tool.setuptools_scm]
version_file = "src/biotite/version.py"

[tool.hatch.build.targets.wheel.hooks.cython.options]
include_numpy = true
compile_py = false
define_macros = [["NPY_NO_DEPRECATED_API", "NPY_1_7_API_VERSION"]]

[build-system]
requires = ["setuptools", "setuptools-scm", "setuptools-rust", "puccinialin", "cython >= 3.0", "numpy >= 2.0"]
build-backend = "setuptools.build_meta"