pyproject.toml

# PEP 518/621 Project Metadata File
# https://packaging.python.org/en/latest/specifications/pyproject-toml/

[build-system]
# Minimum requirements for the build system to execute.
# See https://www.python.org/dev/peps/pep-0518/
requires = [
    # Support for setup.cfg was added in 30.3.0 by
    # https://github.com/pypa/setuptools/pull/862
    # Support for setuptools.build_meta was added in 36.6.0 by
    # https://github.com/pypa/setuptools/pull/1143
    # bdist_wheel was adopted from wheel in 70.1.0
    # https://github.com/pypa/setuptools/issues/1386
    'setuptools>=70.1.0',
]
# Specify build-backend to avoid causing tox 3.7.0 to fail with:
# ERROR: missing build-backend key at build-system section inside pyproject.toml
# Note: pip would use 'setuptools.build_meta:__legacy__' from
#       setuptools >=40.8.0 if build-backend is not specified.
# https://pip.pypa.io/en/stable/reference/pip/#pep-517-and-518-support
build-backend = 'setuptools.build_meta'

[dependency-groups]
# Groups of dependencies for development use-cases
# https://packaging.python.org/en/latest/specifications/dependency-groups/
dev = [
    { include-group = "lint" },
    { include-group = "test" },
]
lint = [
    # Abstract top-level development dependencies (e.g. linters and other tools)
    # Support for pyproject.toml added in 1.7.1
    # https://github.com/PyCQA/bandit/pull/401
    'bandit[toml] >= 1.7.1',
    'flake8',
    'flake8-bugbear',
    'flake8-comprehensions',
    'flake8-docstrings',
    'flake8-quotes',
    'flake8-logging-format',
    'flake8-rst-docstrings >= 0.0.11',
    'isort',
    'mypy',
    # Support for pyproject.toml added in 6.1.0
    # https://github.com/PyCQA/pydocstyle/pull/534
    'pydocstyle >= 6.1.0',
    # Required for `setup.py check --restructuredtext --strict`.  Otherwise:
    # warning: check: Cannot analyze code. Pygments package not found.
    'pygments',
    'pylint',
    'pyroma',
    'ruff',
    # Require setuptools with pkg_resources as a workaround for
    # https://github.com/globality-corp/flake8-logging-format/issues/80
    'setuptools < 82',
    'types-mock',
    'types-setuptools',
    'vulture',
]
docs = [
    # Abstract top-level documentation generator dependencies
    'Sphinx >= 8.2.0',
    'sphinx-argparse',
]
test = [
    # Abstract top-level dependencies for running tests
    'coverage[toml]',
    # Support for [tool.pytest] was added in 9.0
    # https://docs.pytest.org/en/9.0.x/reference/customize.html#pyproject-toml
    'pytest >= 9',
    # Support for pyproject.toml added in 2.12.0
    # https://github.com/pytest-dev/pytest-cov/pull/410
    'pytest-cov >= 2.12.0',
]

[project]
name = 'python-project-template'
description = 'Short description of this package and its purpose.'
readme = 'README.rst'
# license should be a valid SPDX license expression
# https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license
# https://spdx.org/licenses/
license = 'MIT'
license-files = ['LICENSE.txt']
authors = [{name = 'Kevin Locke', email = 'kevin@kevinlocke.name'}]
# From PyPI classifiers list: https://pypi.org/classifiers/
classifiers = [
    'Development Status :: 3 - Alpha',
    'Intended Audience :: Developers',
    'Operating System :: OS Independent',
    'Programming Language :: Python',
    'Programming Language :: Python :: 3',
    'Programming Language :: Python :: 3.10',
    'Programming Language :: Python :: 3.11',
    'Programming Language :: Python :: 3.12',
    'Programming Language :: Python :: 3.13',
    'Programming Language :: Python :: 3.14',
    'Programming Language :: Python :: Implementation :: CPython',
    'Programming Language :: Python :: Implementation :: PyPy',
    'Topic :: Software Development',
]
# (Optional) Additional keywords used to assist searching.
keywords = ['sample', 'setuptools', 'development']
requires-python = '>=3.10'
dynamic = ['version']
dependencies = [
    # Abstract top-level run-time dependencies
]

[project.optional-dependencies]
# Optional dependencies
# https://packaging.python.org/en/latest/specifications/pyproject-toml/#dependencies-optional-dependencies
# https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies
argcomplete = ['argcomplete']

[project.scripts]
# Define entry points for automatic executable creation
# https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#creating-executable-scripts
# https://setuptools.pypa.io/en/latest/userguide/quickstart.html#entry-points-and-automatic-script-creation
packagename = 'packagename.cli:main'

[project.urls]
# Project URLs for specific purposes
# https://packaging.python.org/en/latest/specifications/well-known-project-urls/
Homepage = 'https://github.com/kevinoid/python-project-template'
Documentation = 'https://python-project-template.readthedocs.io/'
GitHub = 'https://github.com/kevinoid/python-project-template'
Tracker = 'https://github.com/kevinoid/python-project-template/issues'

[tool.setuptools]
zip-safe = true
# Use packages for directories, py_modules for single-file modules
# See https://packaging.python.org/guides/distributing-packages-using-setuptools/#packages
# py_modules = packagename
include-package-data = false

[tool.setuptools.package-dir]
# tombi: lint.rules.key-empty.disabled = true
'' = 'src'

[tool.setuptools.packages.find]
exclude = ['tests']
where = ['src']
namespaces = false

[tool.setuptools.package-data]
# Additional data files to include in the package
# https://setuptools.pypa.io/en/latest/userguide/datafiles.html
#
# Note: If files should also be included in source distributions, also add them
# to MANIFEST.in.  See https://stackoverflow.com/a/14159430
#
# If all files included in the sdist should be included in the bdist, consider
# setting include_package_data = True in [options]
packagename = [
    # Mark as containing inline type information
    # https://peps.python.org/pep-0561/#packaging-type-information
    'py.typed',
]

[tool.setuptools.dynamic]
version = {attr = 'packagename.__version__'}

[tool.aliases]
test = 'pytest'

[tool.bandit]
exclude_dirs = [
    '/.git/',
    '/.tox/',
    '/.venv/',
    '/__pycache__/',
]
skips = [
    'B101', # assert_used (needed for pytest, arguably useful outside)
    'B321', # ftplib (not actionable)
    'B402', # import_ftplib (not actionable)
    'B404', # import_subprocess (not actionable)
    'B603', # subprocess_without_shell_equals_true (misleading and not actionable)
    'B606', # start_process_with_no_shell (misleading and not actionable)
    'B607', # start_process_with_partial_path (usually desirable for portability)
]

[tool.coverage.run]
branch = true
omit = [
    'docs/*',
    'tests/*',
    '.vulture/*',
]

[tool.isort]
known_first_party = 'packagename'
# For compatibility with black (from black README.md) and
# https://pycqa.github.io/isort/docs/configuration/profiles/#black
ensure_newline_before_comments = true
force_grid_wrap = 0
include_trailing_comma = true
line_length = 80
lines_between_types = 1
multi_line_output = 3
use_parentheses = true

[tool.mypy]
disallow_any_unimported = true
exclude_gitignore = true
strict = true
warn_return_any = true
warn_unreachable = true

[tool.pydocstyle]
# Several errors are ignored by default pep257 convention:
# https://github.com/PyCQA/pydocstyle/blob/3.0.0/src/pydocstyle/violations.py#L242-L244
# Re-add them by selecting all D errors.
add_select = 'D'
add_ignore = [
    'D203',
    'D212',
]

[tool.pylint.basic]
bad-names = [
    # _LOGGER is too loud, even if it is more consistent
    '_LOGGER',
    'bar',
    'baz',
    'foo',
    'tata',
    'toto',
    'tutu',
]
good-names = [
    # Ok for throw-away values
    '_',
    # _LOGGER is too loud, even if it is more consistent
    '_logger',
    # Single-letter index names with small scopes are ok
    'i',
    'j',
    'k',
]

# pylint.extensions.docparams options
# https://pylint.readthedocs.io/en/latest/technical_reference/extensions.html#parameter-documentation-checker-options
accept-no-param-doc = false
accept-no-raise-doc = false
accept-no-return-doc = false
accept-no-yields-doc = false
default-docstring-type = 'sphinx'

[tool.pylint.format]
max-line-length = 80
ignore-long-lines = '^\s*(# )?<?https?://\S+>?$'

[tool.pylint.master]
ignore = [
    '.tox',
    '.venv',
    '.vulture',
]
# Add src to $PYTHONPATH so modules can be resolved during linting
# See https://stackoverflow.com/q/1899436
# FIXME: Can't get path to this file if specified using --rcfile option
init-hook = '''
import os.path
import sys
from pylint.config import find_default_config_files
# Find this file by UUID
for config_file in find_default_config_files():
    if b'11773e58-e61a-4366-ba2b-0b75481de6de' in open(config_file, 'rb').read():
        sys.path.append(os.path.join(os.path.dirname(config_file), 'src'))
        break
else:
    sys.stderr.write('Error: init-hook unable to find config file\n')
'''
load-plugins = [
    'pylint.extensions.bad_builtin',
    'pylint.extensions.check_elif',
    'pylint.extensions.docparams',
    'pylint.extensions.eq_without_hash',
    'pylint.extensions.overlapping_exceptions',
    'pylint.extensions.redefined_variable_type',
]

[tool.pylint.messages_control]
disable = [
    'fixme',
    'locally-disabled',
    # Covered by pydocstyle/flake8-docstrings which can easily ignore tests
    # See https://github.com/PyCQA/pylint/issues/618
    'missing-docstring',
    # Conflicts with isort when separately importing specific sub-modules:
    #     import a
    #     import b
    #     from a import c
    # Above is correct for isort, causes ungrouped-imports from pylint.
    'ungrouped-imports',
]
enable = [
    'useless-suppression',
]

[tool.pytest]
addopts = [
    '--strict-config',
    '--strict-markers',
]
# https://docs.pytest.org/en/stable/warnings.html
# Note: last matches first (opposite of python -W)
# Note: matches before python -W options passed in pytest invocation
filterwarnings = [
    # Treat warnings caused by this module (or submodules) as errors
    'error:::packagename(\.|$)',
    # Treat warnings caused by the tests module (or submodules) as errors
    'error:::tests(\.|$)',
]
markers = [
]
strict = true

[tool.ruff]
exclude = [
    '.vulture',
]
line-length = 80

[tool.ruff.format]
docstring-code-format = true
quote-style = 'single'

[tool.ruff.lint]
select = ['ALL']
ignore = [
    'COM812',   # missing-trailing-comma
    'D203',     # incorrect-blank-line-before-class
    'D212',     # multi-line-summary-first-line
    'FIX',      # flake8-fixme
    'Q001',     # bad-quotes-multiline-string
    'PTH123',   # builtin-open
    'TD002',    # missing-todo-author
    'TD003',    # missing-todo-link
]

[tool.ruff.lint.flake8-quotes]
inline-quotes = 'single'
multiline-quotes = 'double'

[tool.ruff.lint.isort]
known-first-party = ['packagename']
lines-between-types = 1

[tool.ruff.lint.per-file-ignores]
'docs/*' = [
    'INP001',   # implicit-namespace-package, since docs is not a package
    'ERA001',   # commented-out-code, for documentation and from scaffolding
    'S101',     # assert, since docs are not run with optimization
]
'tests/*' = [
    # TODO: ignore test_* funcs: https://github.com/astral-sh/ruff/issues/7401
    'D103',     # undocumented-public-function
    'S101',     # assert
]