pyproject.toml

###############################
# Configuration for the project
###############################

[project]
name = 'easydynamics'
dynamic = ['version']  # Use versioningit to manage the version
description = 'QENS data analysis'
authors = [{ name = 'EasyScience contributors' }]
readme = 'README.md'
license = 'BSD-3-Clause'
license-files = ['LICENSE']
classifiers = [
  'Intended Audience :: Science/Research',
  'Topic :: Scientific/Engineering',
  'License :: OSI Approved :: BSD License',
  'Operating System :: OS Independent',
  'Programming Language :: Python :: 3 :: Only',
  'Programming Language :: Python :: 3',
  'Programming Language :: Python :: 3.12',
  'Programming Language :: Python :: 3.13',
  'Programming Language :: Python :: 3.14',
]
requires-python = '>=3.12'
dependencies = [
  'easyscience>=2.5.1',  # The base library of the EasyScience framework. 2.5.1 adds fitting.Sampler
  'numpy',  # Numerical arrays (used directly throughout the library)
  'scipy',  # Numerical routines (convolution, interpolation, special functions)
  'scipp',  # Labelled multi-dimensional arrays; backs Experiment data handling
  'h5py',  # HDF5 backend for scipp's HDF5 I/O (Experiment.load_hdf5)
  'matplotlib',  # Plotting (posterior trace, corner, and predictive plots)
  'pooch',  # Data downloader
  'darkdetect',  # Detecting dark mode (system-level)
  'plopp>=26.9.0',  # Plotting library
  'jupyterlab',  # Jupyter notebooks
  'pixi-kernel',  # Pixi Jupyter kernel
  'ipykernel',  # Jupyter kernel (required for running notebooks)
  'ipywidgets',  # Widgets (needed for interactive matplotlib backends)
  'ipympl',  # Matplotlib Jupyter widget backend (%matplotlib widget)
  'IPython',  # Interactive Python shell
  'sympy',  # Symbolic mathematics (used for expression components)
]

[project.optional-dependencies]
dev = [
  'GitPython',  # Interact with Git repositories
  'build',  # Building the package
  'pre-commit',  # Pre-commit hooks
  'jinja2',  # Templating
  'nbmake',  # Building notebooks
  'nbstripout',  # Strip output from notebooks
  'nbqa',  # Linting and formatting notebooks
  'pytest',  # Testing
  'pytest-cov',  # Test coverage
  'pytest-xdist',  # Enable parallel testing
  'ruff',  # Linting and formatting code
  'radon',  # Code complexity and maintainability
  'validate-pyproject[all]',  # Validate pyproject.toml
  'versioningit',  # Automatic versioning from git tags
  'jupytext',  # Jupyter notebook text format support
  'jupyterquiz',  # Quizzes in Jupyter notebooks
  'pydoclint',  # Docstring linter
  'docstring-parser-fork!=0.0.15',  # Parser used by pydoclint. 0.0.15 splits NumPy-style defaults -> DOC105 failures
  'format-docstring',  # Docstring formatter
  'docstripy',  # Convert docstrings to other formats
  'interrogate',  # Docstring coverage checker
  'copier',  # Template management
  'mike',  # MkDocs: Versioned documentation support
  'mkdocs',  # Static site generator
  'mkdocs-material',  # Documentation framework on top of MkDocs
  'mkdocs-autorefs',  # MkDocs: Auto-references support
  'mkdocs-jupyter',  # MkDocs: Jupyter notebook support
  'mkdocs-plugin-inline-svg',  # MkDocs: Inline SVG support
  'mkdocs-markdownextradata-plugin',  # MkDocs: Markdown extra data support, such as global variables
  'mkdocstrings-python',  # MkDocs: Python docstring support
  'pyyaml',  # YAML parser
  'spdx-headers',  # SPDX license header validation
]

[project.urls]
Homepage = 'https://easyscience.github.io/dynamics-lib'
Documentation = 'https://easyscience.github.io/dynamics-lib'
'Release Notes' = 'https://github.com/easyscience/dynamics-lib/releases'
'Source Code' = 'https://github.com/easyscience/dynamics-lib'
'Issue Tracker' = 'https://github.com/easyscience/dynamics-lib/issues'

############################
# Build system configuration
############################

[build-system]
build-backend = 'hatchling.build'
requires = ['hatchling', 'versioningit']

#############################
# Configuration for hatchling
#############################

# 'hatch' -- Build system for Python
# https://hatch.pypa.io/

[tool.hatch.build.targets.wheel]
packages = ['src/easydynamics']

[tool.hatch.metadata]
allow-direct-references = true

[tool.hatch.version]
source = 'versioningit'  # Use versioningit to manage the version

################################
# Configuration for versioningit
################################

# 'versioningit' -- Versioning from git tags
# https://versioningit.readthedocs.io/

# Versioningit generates versions from git tags, so we don't need to
# either specify them statically in pyproject.toml or save them in the
# source code. Do not use {distance} in the version format, as it
# forces a version bump for every commit, which triggers unnecessary
# pixi.lock update without any changes to the source code.

[tool.versioningit.format]
distance = '{base_version}+dev{distance}'  # example: 1.2.3.post4+dev3
dirty = '{base_version}+dirty{distance}'  # example: 0.5.8+dirty3
distance-dirty = '{base_version}+devdirty{distance}'  # example: 0.5.8+devdirty3

# Configure how versioningit detects versions from Git
# - 'match' ensures it only considers tags starting with 'v'
# - 'default-tag' is used as a fallback when no matching tag is found
[tool.versioningit.vcs]
method = 'git'
match = ['v*']
default-tag = 'v999.0.0'

################################
# Configuration for interrogate
################################

# 'interrogate' -- Docstring coverage checker
# https://interrogate.readthedocs.io/en/latest/

[tool.interrogate]
fail-under = 0  # Minimum docstring coverage percentage to pass
verbose = 1
# exclude = ['src/**/__init__.py']

#######################################
# Configuration for coverage/pytest-cov
#######################################

# 'coverage' -- Code coverage measurement tool
# https://coverage.readthedocs.io/en/latest/

[tool.coverage.run]
branch = true  # Measure branch coverage as well
source = ['src']  # Limit coverage to the source code directory

[tool.coverage.report]
show_missing = true  # Show missing lines
skip_covered = false  # Skip files with 100% coverage in the report
fail_under = 0  # Minimum coverage percentage to pass

##########################
# Configuration for pytest
##########################

# 'pytest' -- Testing framework
# https://docs.pytest.org/en/stable/

[tool.pytest.ini_options]
addopts = '--import-mode=importlib'
markers = [
  'fast: mark test as fast (should be run on every push)',
  'network: mark test as downloading data files (deselect with -m "not network" when offline)',
]
testpaths = ['tests']

########################
# Configuration for ruff
########################

# 'ruff' -- Python linter and code formatter
# https://docs.astral.sh/ruff/rules/

[tool.ruff]
exclude = ['tmp']
indent-width = 4
line-length = 99  # See also `max-line-length` in [tool.ruff.lint.pycodestyle]
preview = true  # Enable new rules that are not yet stable, like DOC

# Formatting options for Ruff

[tool.ruff.format]
docstring-code-format = true  # Whether to format code snippets in docstrings
docstring-code-line-length = 99  # Line length for code snippets in docstrings
indent-style = 'space'  # PEP 8 recommends using spaces over tabs
quote-style = 'single'  # But double quotes in docstrings (PEP 8, PEP 257)

# Linting rules to use with Ruff

[tool.ruff.lint]
select = [
  # Various rules
  # 'C90',  # https://docs.astral.sh/ruff/rules/#mccabe-c90
  # 'D',   # https://docs.astral.sh/ruff/rules/#pydocstyle-d
  'F',  # https://docs.astral.sh/ruff/rules/#pyflakes-f
  # 'FLY',  # https://docs.astral.sh/ruff/rules/#flynt-fly
  # 'FURB', # https://docs.astral.sh/ruff/rules/#refurb-furb
  'I',  # https://docs.astral.sh/ruff/rules/#isort-i
  # 'N',    # https://docs.astral.sh/ruff/rules/#pep8-naming-n
  'NPY',  # https://docs.astral.sh/ruff/rules/#numpy-specific-rules-npy
  # 'PGH',  # https://docs.astral.sh/ruff/rules/#pygrep-hooks-pgh
  'PERF',  # https://docs.astral.sh/ruff/rules/#perflint-perf
  'RUF',  # https://docs.astral.sh/ruff/rules/#ruff-specific-rules-ruf
  # 'TRY',  # https://docs.astral.sh/ruff/rules/#tryceratops-try # overly restrictive
  'UP',  # https://docs.astral.sh/ruff/rules/#pyupgrade-up
  # pycodestyle (E, W) rules
  'E',  # https://docs.astral.sh/ruff/rules/#error-e
  'W',  # https://docs.astral.sh/ruff/rules/#warning-w
  # Pylint (PL) rules
  # 'PLC', # https://docs.astral.sh/ruff/rules/#convention-plc
  # 'PLE', # https://docs.astral.sh/ruff/rules/#error-ple
  # 'PLR', # https://docs.astral.sh/ruff/rules/#refactor-plr
  # 'PLW', # https://docs.astral.sh/ruff/rules/#warning-plw # Good to enable
  # flake8 rules
  'A',  # https://docs.astral.sh/ruff/rules/#flake8-builtins-a
  'ANN',  # https://docs.astral.sh/ruff/rules/#flake8-annotations-ann
  'ARG',  # https://docs.astral.sh/ruff/rules/#flake8-unused-arguments-arg
  'ASYNC',  # https://docs.astral.sh/ruff/rules/#flake8-async-async
  'B',  # https://docs.astral.sh/ruff/rules/#flake8-bugbear-b
  # 'BLE',   # https://docs.astral.sh/ruff/rules/#flake8-blind-except-ble # enable when base classes have been merged in
  'C4',  # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
  'COM',  # https://docs.astral.sh/ruff/rules/#flake8-commas-com
  'DTZ',  # https://docs.astral.sh/ruff/rules/#flake8-datetimez-dtz
  # 'EM',    # https://docs.astral.sh/ruff/rules/#flake8-errmsg-em # Unsure if I want it - requires all error messages to be rewritten
  'FA',  # https://docs.astral.sh/ruff/rules/#flake8-future-annotations-fa
  # 'FBT',   # https://docs.astral.sh/ruff/rules/#flake8-boolean-trap-fbt # should eventually be enabled, but may break serialization
  'FIX',  # https://docs.astral.sh/ruff/rules/#flake8-fixme-fix
  'G',  # https://docs.astral.sh/ruff/rules/#flake8-logging-format-g
  'ICN',  # https://docs.astral.sh/ruff/rules/#flake8-import-conventions-icn
  'INP',  # https://docs.astral.sh/ruff/rules/#flake8-no-pep420-inp
  'ISC',  # https://docs.astral.sh/ruff/rules/#flake8-implicit-str-concat-isc
  'LOG',  # https://docs.astral.sh/ruff/rules/#flake8-logging-log
  'PIE',  # https://docs.astral.sh/ruff/rules/#flake8-pie-pie
  # 'PT',    # https://docs.astral.sh/ruff/rules/#flake8-pytest-style-pt # Should eventually be enabled, but quite a few errors to fix
  'PTH',  # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
  'PYI',  # https://docs.astral.sh/ruff/rules/#flake8-pyi-pyi
  'RET',  # https://docs.astral.sh/ruff/rules/#flake8-return-ret
  'RSE',  # https://docs.astral.sh/ruff/rules/#flake8-raise-rse
  'S',  # https://docs.astral.sh/ruff/rules/#flake8-bandit-s
  'SIM',  # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
  'SLF',  # https://docs.astral.sh/ruff/rules/#flake8-self-slf
  'SLOT',  # https://docs.astral.sh/ruff/rules/#flake8-slots-slot
  'T20',  # https://docs.astral.sh/ruff/rules/#flake8-print-t20
  'TC',  # https://docs.astral.sh/ruff/rules/#flake8-type-checking-tc
  'TD',  # https://docs.astral.sh/ruff/rules/#flake8-todos-td
  'TID',  # https://docs.astral.sh/ruff/rules/#flake8-tidy-imports-tid
]

# Exceptions to the linting rules

# Ignore specific rules globally
ignore = [
  'COM812',  # https://docs.astral.sh/ruff/rules/missing-trailing-comma/
  # The following is replaced by 'D'/[tool.ruff.lint.pydocstyle] and [tool.pydoclint]  'DOC', # https://docs.astral.sh/ruff/rules/#pydoclint-doc
  # Disable, as [tool.format_docstring] split one-line docstrings into the canonical multi-line layout
  'D200',  # https://docs.astral.sh/ruff/rules/unnecessary-multiline-docstring/
]

# Ignore specific rules in certain files or directories
[tool.ruff.lint.per-file-ignores]
'*/__init__.py' = [
  'F401',  # re-exports are intentional in __init__.py
]
'tests/**' = [
  'ANN',  # https://docs.astral.sh/ruff/rules/#flake8-annotations-ann
  'D',  # https://docs.astral.sh/ruff/rules/#pydocstyle-d
  'DOC',  # https://docs.astral.sh/ruff/rules/#pydoclint-doc
  'INP001',  # https://docs.astral.sh/ruff/rules/implicit-namespace-package/
  'S101',  # https://docs.astral.sh/ruff/rules/assert/
  'SLF',  # https://docs.astral.sh/ruff/rules/#flake8-self-slf # may want to eventually enable it, but accessing private methods is quite useful in tests
]
'docs/**' = [
  'INP001',  # https://docs.astral.sh/ruff/rules/implicit-namespace-package/
  'T201',  # https://docs.astral.sh/ruff/rules/print/
]

# Specific options for certain rules

[tool.ruff.lint.flake8-tidy-imports]
# Disallow all relative imports
ban-relative-imports = 'all'

[tool.ruff.lint.isort]
# Forces all from imports to appear on their own line
force-single-line = true

[tool.ruff.lint.mccabe]
# Cyclomatic complexity threshold (default is 10)
max-complexity = 10

[tool.ruff.lint.pycodestyle]
# PEP 8 line length guidance:
# https://peps.python.org/pep-0008/#maximum-line-length
# Use 99 characters as the project-wide maximum for regular code lines.
# Use 99 characters for docstrings.
max-line-length = 99  # See also `line-length` in [tool.ruff]
max-doc-length = 99

[tool.ruff.lint.pydocstyle]
convention = 'numpy'

[tool.ruff.lint.pylint]
# Ruff counts `self`/`cls` in max-args; traditional pylint does not.
# Setting 6 here matches pylint's default of 5 (excluding self).
max-args = 6
max-positional-args = 6

#############################
# Configuration for pydoclint
#############################

# 'pydoclint' -- Docstring linter, a faster alternative to
# 'darglint' or 'darglint2'.
# https://pypi.org/project/pydoclint/

# This is a more advanced docstring linter compared to Ruff's built-in
# docstring check rules D or DOC. For example, among many other things,
# it can check that arguments in the docstring, which are used by MkDocs
# and IDEs to render parameter documentation, remain synchronized with
# the parameter declarations in the code (in function's signature).

[tool.pydoclint]
# exclude = '\.' # Temporarily disable pydoclint until we are ready
style = 'numpy'
check-style-mismatch = true
check-arg-defaults = true
allow-init-docstring = true

####################################
# Configuration for format-docstring
####################################

# 'format-docstring' -- Code formatter for docstrings
# https://github.com/jsh9/format-docstring

[tool.format_docstring]
# exclude = '\.' # Temporarily disable format-docstring until we are ready
docstring_style = 'numpy'
line_length = 99
fix_rst_backticks = true
verbose = 'default'