pyproject.toml

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

[project]
name = 'easydiffraction'
dynamic = ['version'] # Use versioningit to manage the version
description = 'Diffraction 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 = [
  'essdiffraction', # ESS-specific diffraction library
  'numpy',          # Numerical computing library
  'colorama',       # Color terminal output
  'tabulate',       # Pretty-print tabular data for terminal output
  'asciichartpy',   # ASCII charts for terminal output
  'pooch',          # Data downloader
  'typer',          # Command-line interface creation
  'rich',           # Rich text and beautiful formatting in the terminal
  'varname',        # Variable name introspection
  'asteval',        # An expression evaluator for Python
  'scipy',          # Scientific computing library
  'sympy',          # Symbolic mathematics library
  'lmfit',          # Non-linear optimization and curve fitting
  'bumps',          # Non-linear optimization and curve fitting
  'dfo-ls',         # Non-linear optimization and curve fitting
  'gemmi',          # Crystallography library
  'cryspy',         # Calculations of diffraction patterns
  'diffpy.pdffit2', # Calculations of Pair Distribution Function (PDF), Python >=3.11,<3.14
  'diffpy.utils',   # Utilities for PDF calculations
  'uncertainties',  # Propagation of uncertainties
  'typeguard',      # Runtime type checking
  'darkdetect',     # Detecting dark mode (system-level)
  'pandas',         # Displaying tables in Jupyter notebooks
  'plotly',         # Interactive plots
  'py3Dmol',        # Visualisation of crystal structures
]

[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
  '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://easydiffraction.org'
Documentation = 'https://easyscience.github.io/diffraction-lib'
'Release Notes' = 'https://github.com/easyscience/diffraction-lib/releases'
'Source Code' = 'https://github.com/easyscience/diffraction-lib'
'Issue Tracker' = 'https://github.com/easyscience/diffraction-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/easydiffraction']

[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 = 75 # 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 = 70      # 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)']
testpaths = ['tests']
filterwarnings = [
  # TEMPRORARY: Suppress some warnings
  # uncertainties 3.x warns on UFloat(value, 0); our CIF parser
  # intentionally creates zero-uncertainty values for free parameters.
  'ignore:Using UFloat objects with std_dev==0:UserWarning:uncertainties',
  # diffpy internals call their own deprecated APIs; nothing we can fix.
  "ignore:'diffpy\\.structure\\.GetSpaceGroup':DeprecationWarning",
  "ignore:'diffpy\\.structure\\.expandPosition':DeprecationWarning",
  "ignore:'diffpy\\.structure\\.Structure\\.writeStr':DeprecationWarning",
]

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

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

[tool.ruff]
exclude = [
  'tmp',
  # Vendored jupyter_dark_detect: keep as-is from upstream for easy updates
  # https://github.com/OpenMined/jupyter-dark-detect/tree/main/jupyter_dark_detect
  'src/easydiffraction/utils/_vendored/jupyter_dark_detect',
]
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 = 72 # Line length for code snippets in docstrings
indent-style = 'space'          # PEP 8 recommends using spaces over tabs
line-ending = 'lf'              # Line endings will be converted to \n
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
  '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
  # 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
  '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
  'FA',    # https://docs.astral.sh/ruff/rules/#flake8-future-annotations-fa
  'FBT',   # https://docs.astral.sh/ruff/rules/#flake8-boolean-trap-fbt
  #'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
  '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/
  # Temporary:
  'D100',   # https://docs.astral.sh/ruff/rules/undocumented-public-module/#undocumented-publi-module-d100
  'D104',   # https://docs.astral.sh/ruff/rules/undocumented-public-package/#undocumented-public-package-d104
  'DTZ005', # https://docs.astral.sh/ruff/rules/call-datetime-now-without-tzinfo/#call-datetime-now-without-tzinfo-dtz005
]

# 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/
  'RUF012', # https://docs.astral.sh/ruff/rules/mutable-class-default/ (test stubs use mutable defaults)
  'RUF069', # https://docs.astral.sh/ruff/rules/unreliable-float-equality/ (exact comparisons in assertions)
  'S101',   # https://docs.astral.sh/ruff/rules/assert/
  # Temporary:
  'ARG001',
  'ARG002',
  'ARG004',
  'ARG005',
  'B011',
  'B017',
  'B018',
  'E501',
  'E741',
  'F841',
  'I001',
  'N801',
  'N805',
  'N812',
  'PLC',
  'PLE',
  'PLR',
  'PLW',
  'SIM117',
  'SLF',
  'TRY',
  'W505',
]
'docs/**' = [
  'INP001', # https://docs.astral.sh/ruff/rules/implicit-namespace-package/
  'RUF001', # https://docs.astral.sh/ruff/rules/ambiguous-unicode-character-string/ (scientific symbols)
  'RUF002', # https://docs.astral.sh/ruff/rules/ambiguous-unicode-character-docstring/ (scientific symbols)
  'RUF003', # https://docs.astral.sh/ruff/rules/ambiguous-unicode-character-comment/ (en-dashes in headings)
  'T201',   # https://docs.astral.sh/ruff/rules/print/
  # Temporary:
  'ANN',
  'D',
  'W',
]

# 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 72 characters for docstrings.
max-line-length = 99 # See also `line-length` in [tool.ruff]
max-doc-length = 72

[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 = 7
max-positional-args = 7

#############################
# 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
exclude = 'src/easydiffraction/utils/_vendored/jupyter_dark_detect' # ED only
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
exclude = 'src/easydiffraction/utils/_vendored/jupyter_dark_detect' # ED only
docstring_style = 'numpy'
line_length = 72
fix_rst_backticks = true
verbose = 'default'