pyproject.toml

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

[project]
name = 'EasyApplication'
dynamic = ['version'] # Use versioningit to manage the version
description = 'Qt/QML components for building graphical applications'
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 = [
  'numpy',   # Scientific computing library
  'PySide6', # Qt for Python
]

[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://app.easyscience.software'
Documentation = 'https://easyscience.github.io/gui-components'
'Release Notes' = 'https://github.com/easyscience/gui-components/releases'
'Source Code' = 'https://github.com/easyscience/gui-components'
'Issue Tracker' = 'https://github.com/easyscience/gui-components/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/EasyApplication']

[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)']
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 = 72 # 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
  #'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/
]

# 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/
]
'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 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 = 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 = 72
fix_rst_backticks = true
verbose = 'default'