pyproject.toml

[build-system]
build-backend = "setuptools.build_meta"
requires = [
    "setuptools",
    "setuptools-scm>=8.1.0",
]

[project]
name = "vws-python"
description = "Interact with the Vuforia Web Services (VWS) API."
readme = { file = "README.rst", content-type = "text/x-rst" }
keywords = [
    "client",
    "vuforia",
    "vws",
]
license = { file = "LICENSE" }
authors = [
    { name = "Adam Dangoor", email = "adamdangoor@gmail.com" },
]
requires-python = ">=3.13"
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Environment :: Web Environment",
    "License :: OSI Approved :: MIT License",
    "Operating System :: Microsoft :: Windows",
    "Operating System :: POSIX",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.13",
]
dynamic = [
    "version",
]
dependencies = [
    "beartype>=0.18.5",
    "requests>=2.32.3",
    "urllib3>=2.2.3",
    "vws-auth-tools>=2024.7.12",
]
optional-dependencies.dev = [
    "actionlint-py==1.7.7.23",
    "check-manifest==0.50",
    "deptry==0.23.0",
    "doc8==1.1.2",
    "doccmd==2025.4.8",
    "docformatter==1.7.5",
    "freezegun==1.5.1",
    "furo==2024.8.6",
    "interrogate==1.7.0",
    "mypy[faster-cache]==1.15.0",
    "mypy-strict-kwargs==2025.4.3",
    "pre-commit==4.2.0",
    "pydocstyle==6.3",
    "pyenchant==3.3.0rc1",
    "pygments==2.19.1",
    "pylint==3.3.6",
    "pylint-per-file-ignores==1.4.0",
    "pyproject-fmt==2.5.1",
    "pyright==1.1.399",
    "pyroma==4.2",
    "pytest==8.3.5",
    "pytest-cov==6.1.1",
    "pyyaml==6.0.2",
    "ruff==0.11.5",
    # We add shellcheck-py not only for shell scripts and shell code blocks,
    # but also because having it installed means that ``actionlint-py`` will
    # use it to lint shell commands in GitHub workflow files.
    "shellcheck-py==0.10.0.1",
    "shfmt-py==3.11.0.2",
    "sphinx==8.2.3",
    "sphinx-copybutton==0.5.2",
    "sphinx-lint==1.0.0",
    "sphinx-pyproject==0.3.0",
    "sphinx-substitution-extensions==2025.4.3",
    "sphinxcontrib-spelling==8.0.1",
    "sybil==9.1.0",
    "types-requests==2.32.0.20250328",
    "vulture==2.14",
    "vws-python-mock==2025.3.10.1",
    "vws-test-fixtures==2023.3.5",
    "yamlfix==1.17.0",
]
optional-dependencies.release = [ "check-wheel-contents==0.6.1" ]
urls.Documentation = "https://vws-python.github.io/vws-python/"
urls.Source = "https://github.com/VWS-Python/vws-python"

[tool.setuptools]
zip-safe = false

[tool.setuptools.packages.find]
where = [
    "src",
]

[tool.setuptools.package-data]
vws = [
    "py.typed",
]

[tool.distutils.bdist_wheel]
universal = true

[tool.setuptools_scm]

# This keeps the start of the version the same as the last release.
# This is useful for our documentation to include e.g. binary links
# to the latest released binary.
#
# Code to match this is in ``conf.py``.
version_scheme = "post-release"

[tool.ruff]
line-length = 79

lint.select = [
    "ALL",
]
lint.ignore = [
    # Ruff warns that this conflicts with the formatter.
    "COM812",
    # Allow our chosen docstring line-style - no one-line summary.
    "D200",
    "D205",
    "D212",
    # Ruff warns that this conflicts with the formatter.
    "ISC001",
    # Ignore "too-many-*" errors as they seem to get in the way more than
    # helping.
    "PLR0913",
]

lint.per-file-ignores."doccmd_*.py" = [
    # Allow asserts in docs.
    "S101",
]

lint.per-file-ignores."docs/source/*.py" = [
    # Allow asserts in docs.
    "S101",
]

lint.per-file-ignores."tests/*.py" = [
    # Allow asserts in tests.
    "S101",
]

# Do not automatically remove commented out code.
# We comment out code during development, and with VSCode auto-save, this code
# is sometimes annoyingly removed.
lint.unfixable = [
    "ERA001",
]
lint.pydocstyle.convention = "google"

[tool.pylint]

[tool.pylint.'MASTER']

# Pickle collected data for later comparisons.
persistent = true

# Use multiple processes to speed up Pylint.
jobs = 0

# List of plugins (as comma separated values of python modules names) to load,
# usually to register additional checkers.
# See https://chezsoi.org/lucas/blog/pylint-strict-base-configuration.html.
# and we also add `pylint_per_file_ignores` to allow per-file ignores.
# We do not use the plugins:
# - pylint.extensions.code_style
# - pylint.extensions.magic_value
# - pylint.extensions.while_used
# as they seemed to get in the way.
load-plugins = [
    "pylint_per_file_ignores",
    'pylint.extensions.bad_builtin',
    'pylint.extensions.comparison_placement',
    'pylint.extensions.consider_refactoring_into_while_condition',
    'pylint.extensions.docparams',
    'pylint.extensions.dunder',
    'pylint.extensions.eq_without_hash',
    'pylint.extensions.for_any_all',
    'pylint.extensions.mccabe',
    'pylint.extensions.no_self_use',
    'pylint.extensions.overlapping_exceptions',
    'pylint.extensions.private_import',
    'pylint.extensions.redefined_loop_name',
    'pylint.extensions.redefined_variable_type',
    'pylint.extensions.set_membership',
    'pylint.extensions.typing',
]

# Allow loading of arbitrary C extensions. Extensions are imported into the
# active Python interpreter and may run arbitrary code.
unsafe-load-any-extension = false

[tool.pylint.'MESSAGES CONTROL']

# Enable the message, report, category or checker with the given id(s). You can
# either give multiple identifier separated by comma (,) or put this option
# multiple time (only on the command line, not in the configuration file where
# it should appear only once). See also the "--disable" option for examples.
enable = [
    'bad-inline-option',
    'deprecated-pragma',
    'file-ignored',
    'spelling',
    'use-symbolic-message-instead',
    'useless-suppression',
]

# Disable the message, report, category or checker with the given id(s). You
# can either give multiple identifiers separated by comma (,) or put this
# option multiple times (only on the command line, not in the configuration
# file where it should appear only once).You can also use "--disable=all" to
# disable everything first and then reenable specific checks. For example, if
# you want to run only the similarities checker, you can use "--disable=all
# --enable=similarities". If you want to run only the classes checker, but have
# no Warning level messages displayed, use"--disable=all --enable=classes
# --disable=W"

disable = [
    'too-few-public-methods',
    'too-many-locals',
    'too-many-arguments',
    'too-many-instance-attributes',
    'too-many-return-statements',
    'too-many-lines',
    'locally-disabled',
    # Let ruff handle long lines
    'line-too-long',
    # Let ruff handle unused imports
    'unused-import',
    # Let ruff deal with sorting
    'ungrouped-imports',
    # We don't need everything to be documented because of mypy
    'missing-type-doc',
    'missing-return-type-doc',
    # Too difficult to please
    'duplicate-code',
    # Let ruff handle imports
    'wrong-import-order',
    # mypy does not want untyped parameters.
    'useless-type-doc',
]

# We ignore invalid names because:
# - We want to use generated module names, which may not be valid, but are never seen.
# - We want to use global variables in documentation, which may not be uppercase.
# - conf.py is a Sphinx configuration file which requires lowercase global variable names.
per-file-ignores = [
    "docs/:invalid-name",
    "doccmd_README_rst.*.py:invalid-name",
]

[tool.pylint.'FORMAT']

# Allow the body of an if to be on the same line as the test if there is no
# else.
single-line-if-stmt = false

[tool.pylint.'SPELLING']

# Spelling dictionary name. Available dictionaries: none. To make it working
# install python-enchant package.
spelling-dict = 'en_US'

# A path to a file that contains private dictionary; one word per line.
spelling-private-dict-file = 'spelling_private_dict.txt'

# Tells whether to store unknown words to indicated private dictionary in
# --spelling-private-dict-file option instead of raising a message.
spelling-store-unknown-words = 'no'

[tool.docformatter]
make-summary-multi-line = true

[tool.check-manifest]

ignore = [
    ".checkmake-config.ini",
    ".yamlfmt",
    "*.enc",
    ".pre-commit-config.yaml",
    "CHANGELOG.rst",
    "CODE_OF_CONDUCT.rst",
    "CONTRIBUTING.rst",
    "LICENSE",
    "Makefile",
    "ci",
    "ci/**",
    "codecov.yaml",
    "doc8.ini",
    "docs",
    "docs/**",
    ".git_archival.txt",
    "spelling_private_dict.txt",
    "tests",
    "tests-pylintrc",
    "tests/**",
    "vuforia_secrets.env.example",
    "lint.mk",
]

[tool.deptry]
pep621_dev_dependency_groups = [
    "dev",
    "release",
]

[tool.pyproject-fmt]
indent = 4
keep_full_version = true
max_supported_python = "3.13"

[tool.pytest.ini_options]

xfail_strict = true
log_cli = true

[tool.coverage.run]

branch = true

[tool.coverage.report]
exclude_also = [
    "if TYPE_CHECKING:",
]

[tool.mypy]

strict = true
files = [ "." ]
exclude = [ "build" ]
follow_untyped_imports = true
plugins = [
    "mypy_strict_kwargs",
]

[tool.pyright]

enableTypeIgnoreComments = false
reportUnnecessaryTypeIgnoreComment = true
typeCheckingMode = "strict"

[tool.interrogate]
fail-under = 100
omit-covered-files = true
verbose = 2

[tool.doc8]

max_line_length = 2000
ignore_path = [
    "./.eggs",
    "./docs/build",
    "./docs/build/spelling/output.txt",
    "./node_modules",
    "./src/*.egg-info/",
    "./src/*/_setuptools_scm_version.txt",
]

[tool.vulture]
# Ideally we would limit the paths to the source code where we want to ignore names,
# but Vulture does not enable this.
ignore_names = [
    # pytest configuration
    "pytest_collect_file",
    "pytest_collection_modifyitems",
    "pytest_plugins",
    # pytest fixtures - we name fixtures like this for this purpose
    "fixture_*",
    # Sphinx
    "autoclass_content",
    "autoclass_content",
    "autodoc_member_order",
    "copybutton_exclude",
    "extensions",
    "html_show_copyright",
    "html_show_sourcelink",
    "html_show_sphinx",
    "html_theme",
    "html_theme_options",
    "html_title",
    "htmlhelp_basename",
    "intersphinx_mapping",
    "language",
    "linkcheck_ignore",
    "linkcheck_retries",
    "master_doc",
    "nitpicky",
    "nitpick_ignore",
    "project_copyright",
    "pygments_style",
    "rst_prolog",
    "source_suffix",
    "spelling_word_list_filename",
    "templates_path",
    "warning_is_error",
]

# Duplicate some of .gitignore
exclude = [ ".venv" ]

[tool.yamlfix]
section_whitelines = 1
whitelines = 1