pyproject.toml

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

[project]
name = "vws-python-mock"
description = "A mock for the Vuforia Web Services (VWS) API."
readme = { file = "README.rst", content-type = "text/x-rst" }
keywords = [
    "client",
    "fake",
    "mock",
    "vuforia",
    "vws",
]
license = "MIT"
authors = [
    { name = "Adam Dangoor", email = "adamdangoor@gmail.com" },
]
requires-python = ">=3.15"
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Environment :: Web Environment",
    "Framework :: Pytest",
    "Operating System :: Microsoft :: Windows",
    "Operating System :: POSIX",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.15",
]
dynamic = [
    "version",
]
dependencies = [
    "beartype>=0.23.0",
    "flask>=3.0.3",
    "httpx>=0.27.0",
    "httpx2>=2.12",
    "mock-response-delay>=2026.9.12",
    "numpy>=2.4.4",
    "opencv-contrib-python-headless>=5.0.0.93",
    "pillow>=12.2.0",
    "pydantic>=2.6",
    "pydantic-settings>=2.6.1",
    "pyteenybrisque>=0.1.1",
    "requests>=2.32.3",
    "responses>=0.25.3",
    "respx>=0.21.0",
    "tzdata; sys_platform=='win32'",
    "vws-auth-tools>=2024.7.12",
    "werkzeug>=3.1.2",
]
urls.Documentation = "https://vws-python.github.io/vws-python-mock/"
urls.Source = "https://github.com/VWS-Python/vws-python-mock"

[dependency-groups]
dev = [
    "actionlint-py==1.7.12.25",
    "beartype==0.23.1",
    "check-manifest==0.51",
    "check-wheel-contents==0.6.3",
    "coverage==7.16.2",
    "deptry==0.25.1",
    # Dill 0.4.1 predates Python 3.15 removal of co_lnotab.
    # Replace the source pin with a release containing this fix:
    # https://github.com/uqfoundation/dill/pull/755
    "dill @ git+https://github.com/uqfoundation/dill.git@37d2bf717ac7ac110f06be5210f989847959c2cd",
    "dirty-equals==0.11",
    "doc8==2.0.0",
    "doccmd==2026.9.16.1",
    "docker==7.2.0",
    "freezegun==1.5.5",
    "furo==2025.12.19",
    # We use ``hadolint-coatl`` rather than ``hadolint-py`` because the
    # ``hadolint-py`` macOS wheel published on PyPI is a corrupt archive and
    # cannot be installed.
    "hadolint-coatl==2.15.1",
    "interrogate==1.7.0",
    "mypy==2.4.0",
    "mypy-pytest-parametrize==2026.10.5.1",
    "mypy-strict-kwargs==2026.10.19",
    "myst-parser==5.1.0",
    "no-defaults==2026.9.1",
    "prek==0.5.6",
    "pydocstringformatter==1.0.0",
    "pydocstyle==6.3",
    "pylint[spelling]==4.1.3",
    "pylint-per-file-ignores==4.0.0",
    "pyproject-fmt==2.30.3",
    "pyprojroot==0.3.0",
    "pyrefly==1.4.0",
    "pyright==1.1.414",
    "pyroma==5.0.1",
    "pytest==9.1.1",
    "pytest-beartype==0.3.0",
    "pytest-multi-backend==2026.9.7",
    "pytest-partition-check==2026.10.11",
    "pytest-retry==1.7.0",
    "pytest-xdist==3.8.0",
    "pyyaml==6.0.3",
    "requests-mock-flask==2026.10.9",
    "ruff==0.17.1",
    # 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.11.0.1",
    "shfmt-py==4.2.0",
    "snapper-fmt==0.11.10",
    "sphinx==9.1.1",
    "sphinx-copybutton==0.5.2",
    "sphinx-lint==1.0.2",
    "sphinx-paramlinks==0.6",
    "sphinx-pyproject==0.3.0",
    "sphinx-substitution-extensions==2026.10.9",
    "sphinx-toolbox==4.3.1",
    "sphinxcontrib-httpdomain==2.2.1",
    "sphinxcontrib-spelling==8.0.2",
    # ``sphinxcontrib-towncrier`` renders unreleased news fragments
    # as Markdown in docs/source/unreleased.md during Sphinx builds.
    "sphinxcontrib-towncrier==0.5.0a0",
    "strict-kwargs==2026.10.9",
    "sybil==10.1.0",
    "tenacity==9.2.1",
    "towncrier==26.9.0",
    "ty==0.0.89",
    "types-docker==7.2.0.20261006",
    "types-pyyaml==6.0.12.20260906",
    "types-requests==2.33.0.20261006",
    "urllib3==2.8.0",
    "vale==3.22.0.0",
    "vulture==2.16",
    "vws-mock-contract-tests==0.0.0",
    "vws-mock-test-backends==0.0.0",
    "vws-python==2026.10.9",
    "vws-test-fixtures==2026.10.8",
    "vws-web-tools==2026.8.27",
    "yamlfix==1.19.1",
    "zizmor==1.31.1",
]
release = [ "check-wheel-contents==0.6.3", "towncrier==26.9.0" ]

[tool.setuptools]
packages.find.where = [
    "src",
]
package-data.mock_vws = [
    "py.typed",
]
zip-safe = false

[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"
# We use a fallback version like
# https://github.com/pypa/setuptools_scm/issues/77 so that we do not
# error in the Docker build stage of the release pipeline.
#
# This must be a PEP 440 compliant version.
fallback_version = "0.0.0"

[tool.uv]
sources.vws-mock-contract-tests = { workspace = true }
sources.vws-mock-test-backends = { workspace = true }
sources.vws-python-mock = { workspace = true }
workspace.members = [ "contract-tests", "test-backends" ]

[tool.ruff]
line-length = 79
src = [ "contract-tests/src", "src", "test-backends/src" ]
lint.select = [
    "ALL",
]
lint.extend-select = [ "ANN", "PGH003", "PYI" ]
lint.ignore = [
    # Ruff warns that this conflicts with the formatter.
    "COM812",
    # Copyright headers are not required.
    "CPY001",
    # Allow our chosen docstring line-style - pydocstringformatter handles formatting
    # but doesn't enforce D205 (blank line after summary) or D212 (summary on first line).
    "D205",
    "D212",
    "D415",
    # 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",
    # Beartype requires imports to be available at runtime, not just for type
    # checking. See https://github.com/beartype/beartype/discussions/594
    # for when beartype will support `if TYPE_CHECKING` imports.
    "TC001",
    "TC002",
    "TC003",
]
lint.explicit-preview-rules = true
lint.per-file-ignores."contract-tests/consumer/**" = [ "S101" ]
lint.per-file-ignores."contract-tests/src/**" = [ "S101", "S105", "S106" ]
lint.per-file-ignores."doccmd_*.py" = [
    # Allow our chosen docstring line-style - pydocstringformatter handles
    # formatting but docstrings in docs may not match this style.
    "D200",
    # Allow asserts in docs.
    "S101",
]
lint.per-file-ignores."test-backends/src/**" = [ "S101", "S105", "S106" ]
lint.per-file-ignores."tests/**" = [
    # Allow asserts in tests.
    "S101",
    # Allow possible hardcoded passwords in tests.
    "S105",
    "S106",
]
# 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.external = [ "NOD" ]
lint.flake8-tidy-imports.banned-api."operator.attrgetter".msg = "operator.attrgetter is banned: use a lambda instead."
lint.flake8-tidy-imports.banned-api."typing.cast".msg = """\
    typing.cast is banned: use explicit type narrowing or a typed variable instead.\
    """
lint.pydocstyle.convention = "google"
lint.preview = true

[tool.pylint]
# 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"
"MESSAGES CONTROL".disable = [
    # Too difficult to please
    "duplicate-code",
    # Let ruff handle long lines
    "line-too-long",
    "locally-disabled",
    "missing-return-type-doc",
    # We don't need everything to be documented because of mypy
    "missing-type-doc",
    # Style issues that we can deal with ourselves
    "too-few-public-methods",
    "too-many-arguments",
    "too-many-instance-attributes",
    "too-many-lines",
    "too-many-locals",
    # Let ruff deal with sorting
    "ungrouped-imports",
    # Let ruff handle unused imports
    "unused-import",
    # Let ruff handle imports
    "wrong-import-order",
]
# 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.
"MESSAGES CONTROL".enable = [
    "bad-inline-option",
    "deprecated-pragma",
    "file-ignored",
    "spelling",
    "use-symbolic-message-instead",
    "useless-suppression",
]
DEPRECATED_BUILTINS.bad-functions = [
    # Use Pylint until Ruff can ban bare builtin calls, or until custom rules
    # make this removable:
    # https://github.com/astral-sh/ruff/issues/10079
    # https://github.com/astral-sh/ruff/issues/970
    "filter",
    "getattr",
    "hasattr",
    "map",
    "setattr",
]
# Allow the body of an if to be on the same line as the test if there is no
# else.
FORMAT.single-line-if-stmt = false
# Return non-zero exit code if useless-suppression is emitted.
MAIN.fail-on = [
    "useless-suppression",
]
# Use multiple processes to speed up Pylint.
MASTER.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.
# 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.
MASTER.load-plugins = [
    "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",
    "pylint_per_file_ignores",
]
# 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
MASTER.per-file-ignores = [
    "docs/source/conf.py:invalid-name",
    "docs/source/doccmd_*.py:invalid-name",
    "doccmd_README_rst_*.py:invalid-name",
]
# Pickle collected data for later comparisons.
MASTER.persistent = true
MASTER.unsafe-load-any-extension = false
# Spelling dictionary name. Available dictionaries: none. To make it working
# install python-enchant package.
SPELLING.spelling-dict = "en_US"
# A path to a file that contains private dictionary; one word per line.
SPELLING.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.spelling-store-unknown-words = "no"

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

[tool.check-manifest]
ignore = [
    "*.enc",
    ".checkmake-config.ini",
    ".dockerignore",
    ".git_archival.txt",
    ".prettierrc",
    ".vale.ini",
    ".vscode/*.json",
    ".yamlfmt",
    "admin/**",
    "CHANGELOG.md",
    "ci",
    "ci/**",
    "CODE_OF_CONDUCT.rst",
    "conftest.py",
    "CONTRIBUTING.rst",
    "docker-bake.hcl",
    "docs",
    "docs/**",
    "LICENSE",
    "lint.mk",
    "Makefile",
    "newsfragments",
    "newsfragments/**",
    "prek.toml",
    "secrets.tar.gpg",
    "spelling_private_dict.txt",
    "src/mock_vws/_flask_server/Dockerfile",
    "styles/snapper/*.yml",
    "tests",
    "tests/**",
    "typings/**",
    "uv.lock",
    "vuforia_secrets.env.example",
    "zizmor.yml",
]

[tool.deptry]
per_rule_ignores.DEP002 = [
    # tzdata is needed on Windows for zoneinfo to work.
    # See https://docs.python.org/3/library/zoneinfo.html#data-sources.
    "tzdata",
]

[tool.vulture]
# Duplicate some of .gitignore
exclude = [ ".venv" ]
# Ideally we would limit the paths to the source code where we want to ignore names,
# but Vulture does not enable this.
ignore_names = [
    # Sphinx
    "autoclass_content",
    "autoclass_content",
    "autodoc_member_order",
    # Used in TYPE_CHECKING for type hints
    "CloudDatabaseDict",
    "copybutton_exclude",
    "DatabaseDict",
    # Too difficult to test (see notes in the code)
    "DATE_RANGE_ERROR",
    "extensions",
    # pytest fixtures - we name fixtures like this for this purpose
    "fixture_*",
    "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",
    # pydantic-settings
    "model_config",
    "nitpicky",
    "project_copyright",
    "pygments_style",
    "pytest_addoption",
    # pytest configuration
    "pytest_collect_file",
    "pytest_collection_modifyitems",
    "pytest_plugins",
    "pytest_set_filtered_exceptions",
    "pytestmark",
    "REQUEST_QUOTA_REACHED",
    "rst_prolog",
    # Sphinx extension entry point, called by the documentation builder.
    "setup",
    "source_suffix",
    "spelling_word_list_filename",
    "templates_path",
    "towncrier_draft_autoversion_mode",
    "towncrier_draft_include_empty",
    "towncrier_draft_working_directory",
    "VuMarkDatabaseDict",
    "VuMarkTargetDict",
    "warning_is_error",
]
ignore_decorators = [
    "@*APP.after_request",
    "@*APP.before_request",
    "@*APP.errorhandler",
    # Flask
    "@*APP.route",
    # pydantic
    "@model_validator",
    "@pytest.fixture",
    "@route",
]

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

[tool.mypy]
files = [ "." ]
exclude = [ "build" ]
exclude_gitignore = true
follow_untyped_imports = true
strict = true
plugins = [
    "mypy_pytest_parametrize",
    "pydantic.mypy",
    "mypy_strict_kwargs",
]
show_traceback = true
num_workers = "auto"

[tool.pyrefly]
search_path = [
    ".",
    "src",
]
errors.non-exhaustive-match = "error"
enabled-ignores = [ "pyrefly" ]
preset = "all"

[tool.pyright]
typeCheckingMode = "strict"
enableTypeIgnoreComments = false
reportUnnecessaryTypeIgnoreComment = true

[tool.ty]
rules.all = "error"
terminal.error-on-warning = true
analysis.respect-type-ignore-comments = false
analysis.strict-equality-semantics = true
analysis.strict-generic-narrowing = true

[tool.pytest]
addopts = [
    "--strict-markers",
]
beartype_packages = [ "mock_vws" ]
beartype_test_fixtures = true
beartype_tests = true
cumulative_timing = false
log_cli = true
markers = [
    "requires_docker_build",
]
# Legacy import modules keep the existing CI partitions stable.
norecursedirs = [ "contract-tests", "test-backends" ]
# Options for pytest-retry.
retries = "10"
retry_delay = "10"
xfail_strict = true

[tool.coverage]
run.source = [ "ci/", "contract-tests/src/", "src/", "test-backends/src/", "tests/" ]
# Import-only compatibility modules contain no assertions or backend logic.
# Their authoritative implementations remain subject to full coverage.
run.omit = [
    "tests/mock_vws/fixtures/credentials.py",
    "tests/mock_vws/fixtures/model_target_prepared_requests.py",
    "tests/mock_vws/fixtures/plugin.py",
    "tests/mock_vws/fixtures/real_credentials.py",
    "tests/mock_vws/fixtures/real_model_target_retries.py",
    "tests/mock_vws/fixtures/vuforia_backends.py",
    "tests/mock_vws/model_target_web_api/assertions.py",
    "tests/mock_vws/utils/__init__.py",
    "tests/mock_vws/utils/assertions.py",
    "tests/mock_vws/utils/backend_capabilities.py",
    "tests/mock_vws/utils/cloud_databases.py",
    "tests/mock_vws/utils/model_target_response_policy.py",
    "tests/mock_vws/utils/model_target_retries.py",
    "tests/mock_vws/utils/recognition_counts.py",
    "tests/mock_vws/utils/request_timeout_policy.py",
    "tests/mock_vws/utils/retries.py",
    "tests/mock_vws/utils/too_many_requests.py",
    "tests/mock_vws/utils/unrouted_requests.py",
]
run.branch = true
run.parallel = true
run.relative_files = true
run.patch = [ "subprocess" ]
report.fail_under = 100
report.exclude_also = [
    "case _ as unreachable:\n\\s*assert_never\\(",
    "class .*\\bProtocol\\):",
    "if TYPE_CHECKING:",
]
report.show_missing = true

[tool.towncrier]
# Write the same native Markdown file used by documentation and GitHub releases.
directory = "newsfragments"
filename = "docs/source/changelog/{version}.md"
title_format = "# {version} ({project_date})"
issue_format = "[#{issue}](https://github.com/VWS-Python/vws-python-mock/issues/{issue})"
single_file = false
# Reject invalid fragment names instead of silently losing release entries.
ignore = [ ".gitkeep" ]
type = [ { directory = "change", name = "Changes", showcontent = true } ]

[tool.pydocstringformatter]
write = true
split-summary-body = false
max-line-length = 75
linewrap-full-docstring = true

[tool.pydantic-mypy]
init_forbid_extra = true
init_typed = true
warn_required_dynamic_aliases = true
warn_untyped_fields = true

[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.yamlfix]
section_whitelines = 1
whitelines = 1

[tool.no_defaults]
private_only = true
per_file_enforcement."tests/**" = "all"