pyproject.toml

[project]
name = "ops"
description = "The Python library behind great charms"
readme = "README.md"
requires-python = ">=3.10"
authors = [
    {name="The Charm Tech team at Canonical Ltd."},
]
license = "Apache-2.0"
license-files = ["LICENSE.txt"]
classifiers = [
    "Programming Language :: Python :: 3",
    "Development Status :: 5 - Production/Stable",
    "Intended Audience :: Developers",
    "Intended Audience :: System Administrators",
    "Operating System :: MacOS :: MacOS X",
    "Operating System :: POSIX :: Linux",
]
dependencies = [
    "PyYAML==6.*",
    "websocket-client==1.*",
    # Wide version range to preempt conflicts when charms pin a version.
    "opentelemetry-api~=1.0",
]
dynamic = ["version"]

[project.optional-dependencies]
testing = [
    "ops-scenario==8.10.0.dev0",
]
tracing = [
    "ops-tracing==3.10.0.dev0",
]
# Empty for now, because Harness is bundled with the base install, but allow
# specifying the extra to ease transition later.
harness = []

[dependency-groups]
lint = [
    "ruff==0.17.2",
    "codespell==2.4.2",
    "zizmor==1.30.1",
    "ops[testing,tracing]",
    "pyright~=1.1",
    "typing_extensions~=4.2",
]
# The mypy, pyrefly, and ty groups are used to type check example charms in CI.
mypy = [
    "mypy>=1.19",
    "types-PyYAML",
]
pyrefly = [
    "pyrefly>=1.3",
]
ty = [
    "ty==0.0.91",
]
unit = [
    "ops[testing,tracing]",
    "pytest~=9.0",
    "pydantic~=2.10",
]
xdist = [
    "pytest-xdist~=3.6",
]
coverage = [
    "coverage[toml]~=7.0",
]
benchmark = [
    "pytest-benchmark~=5.0",
]
integration = [
    "ops[testing,tracing]",
    "pytest~=9.0",
    "jubilant~=1.5",
    "jubilant-backports",
    "minio~=7.2",
    "httpx~=0.28",
]
tiobe = [
    "flake8==7.4.1",
    "pylint==4.1.3",
]

[project.urls]
"Homepage" = "https://canonical.com/juju/docs/ops/latest/"
"Repository" = "https://github.com/canonical/operator"
"Issues" = "https://github.com/canonical/operator/issues"
"Documentation" = "https://canonical.com/juju/docs/ops/latest/"
"Changelog" = "https://github.com/canonical/operator/blob/main/CHANGES.md"

[build-system]
requires = ["hatchling>=1.27"]
build-backend = "hatchling.build"

[tool.hatch.version]
source = "code"
path = "ops/version.py"
expression = "version"

[tool.hatch.build.targets.sdist]
# Only include ops, not docs, examples, or testing and tracing packages.
include = [
    "/ops",
    "/test",
    "/*.md",  # Include changelog and contributor docs.
]

[tool.hatch.build.targets.wheel]
packages = ["ops"]

[tool.uv.workspace]
members = ["tracing", "testing"]

[tool.uv.sources]
ops = { workspace = true }
ops-scenario = { workspace = true }
ops-tracing = { workspace = true }

# Testing tools configuration
[tool.coverage.run]
branch = true

[tool.coverage.report]
show_missing = true

# Formatting tools configuration
[tool.autopep8]
max-line-length = 99
ignore = ["W503"]
recursive = true
jobs = -1
aggressive = 3

# Linting tools configuration
[tool.ruff]
line-length = 99
exclude = ["examples"]
target-version = "py310"
extend-exclude = ["docs/conf.py", "docs/_dev/", "docs/tutorial/"]

# Ruff formatter configuration
[tool.ruff.format]
quote-style = "single"

[tool.ruff.lint]
select = [
    # Pyflakes
    "F",
    # Pycodestyle
    "E",
    "W",
    # isort
    "unsorted-imports",  # I001
    # pep8-naming
    "N",
    # flake8-builtins
    "A",
    # flake8-copyright
    "CPY",
    # pyupgrade
    "UP",
    # flake8-2020
    "YTT",
    # flake8-bandit
    "S",
    # flake8-bugbear
    "B",
    # flake8-simplify
    "SIM",
    # Ruff specific
    "RUF",
    # Perflint
    "PERF",
    # pyflakes-docstrings
    "D",
    # flake8-future-annotations
    "FA",
    # flake8-type-checking
    "TC",
]
ignore = [
    "typing-only-first-party-import",  # TC001
    "typing-only-third-party-import",  # TC002
    "typing-only-standard-library-import",  # TC003
    "assert",  # S101
    "assert-false",  # B011
    "suspicious-pickle-import",  # S403
    "suspicious-subprocess-import",  # S404

    "no-explicit-stacklevel",  # B028

    # We prefer the readability of returning the condition explicitly.
    "needless-bool",  # SIM103
    "suppressible-exception",  # SIM105
    "multiple-with-statements",  # SIM117

    "undocumented-magic-method",  # D105
    "undocumented-public-init",  # D107

    "manual-list-comprehension",  # PERF401
    "manual-dict-comprehension",  # PERF403

    # Since we have some `TypedDict`s that cannot use the class syntax, we're
    # currently choosing to be consistent in syntax even though some can be
    # moved to the class syntax.
    "convert-typed-dict-functional-to-class",  # UP013

    ## Likely worth doing, but later.

    "subprocess-without-shell-equals-true",  # S603
]
exclude = ["tracing/ops_tracing/vendor/*"]

[tool.ruff.lint.per-file-ignores]
"test/*" = [
    # All documentation linting.
    "D",

    "hardcoded-password-string",  # S105
    "hardcoded-password-func-arg",  # S106

    "useless-expression",  # B018

    # Tests check round-tripped exact-literal config values; pytest.approx
    # isn't appropriate here.
    "float-equality-comparison",  # RUF069
]
"testing/tests/*" = [
    # All documentation linting.
    "D",
]
"testing/src/scenario/_charmcraft_extensions.py" = [
    "line-too-long",  # E501: Auto-generated file; long description strings are unavoidable.
]
".github/generate_charmcraft_extensions.py" = [
    "start-process-with-partial-path",  # S607: Intentionally calls charmcraft/tox by name.
]
"ops/_private/timeconv.py" = [
    # `µ` (MICRO SIGN) rather than `μ` (GREEK SMALL LETTER MU).
    "ambiguous-unicode-character-string",  # RUF001
    "ambiguous-unicode-character-docstring",  # RUF002
]
"ops/__init__.py" = [
    "non-empty-init-module",  # RUF067: Wraps main() and imports ops_tracing at the bottom.
]
"ops/_private/__init__.py" = [
    "non-empty-init-module",  # RUF067: Exposes a module-level tracer.
]
"ops/lib/__init__.py" = [
    "non-empty-init-module",  # RUF067: Legacy library loader.
]
"test/test_helpers.py" = [
    # Seems safe, but may be changed in the future.
    "start-process-with-a-shell",  # S605
    "start-process-with-partial-path",  # S607
]
".github/patch-charm-deps.py" = [
    "start-process-with-partial-path",  # S607
]
".github/release/propose-release-version.py" = [
    "line-too-long",  # E501: The failure messages read best kept whole.
]
"docs/custom_conf.py" = [
    "undocumented-public-module",  # D100
    "undocumented-public-class",  # D101
    "undocumented-public-method",  # D102
    "undocumented-public-function",  # D103
    "multiple-leading-hashes-for-block-comment",  # E266
    "unsorted-imports",  # I001
    "ambiguous-unicode-character-comment",  # RUF003: EN DASH, RIGHT SINGLE QUOTATION MARK
    "mutable-class-default",  # RUF012
    "printf-string-formatting",  # UP031
]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.flake8-builtins]
builtins-ignorelist = ["id", "min", "map", "range", "type", "TimeoutError", "ConnectionError", "Warning", "input", "format"]

[tool.pyright]
# Whole trees rather than a list of directories, so that a new package or test
# charm is checked from the day it's added. What isn't checked yet is listed
# explicitly below instead.
include = [".github/release", "ops", "test", "testing"]
exclude = [
    "tracing/*",
    # Legacy, and not yet clean.
    "ops/lib",
    # A symlink to ops, which is already checked as itself.
    "test/charms/test_main/lib",
    # Not yet clean: mostly Any from the juju and jubilant APIs.
    "test/integration",
    "test/smoke",
    "testing/tests/benchmark",
]
extraPaths = ["testing", "tracing"]
pythonVersion = "3.10" # check no python > 3.10 features are used
pythonPlatform = "All"
typeCheckingMode = "strict"
reportIncompatibleMethodOverride = false
reportImportCycles = false
reportMissingModuleSource = false
reportPrivateUsage = false
reportUnnecessaryIsInstance = false
reportUnnecessaryComparison = false
reportUnnecessaryTypeIgnoreComment = "error"
disableBytesTypePromotions = true
stubPath = ""

[tool.codespell]
skip = './docs/_build,./docs/_dev,.venv,venv,build,examples,uv.lock'
quiet-level = 3