pyproject.toml

[build-system]
requires = ["setuptools >= 64"]
build-backend = "setuptools.build_meta"

[project]
name = "trio"
description = "A friendly Python library for async concurrency and I/O"
authors = [{name = "Nathaniel J. Smith", email = "njs@pobox.com"}]
license = {text = "MIT OR Apache-2.0"}
keywords = [
    "async",
    "io",
    "networking",
    "trio",
]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Framework :: Trio",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "License :: OSI Approved :: Apache Software License",
    "Operating System :: POSIX :: Linux",
    "Operating System :: MacOS :: MacOS X",
    "Operating System :: POSIX :: BSD",
    "Operating System :: Microsoft :: Windows",
    "Programming Language :: Python :: Implementation :: CPython",
    "Programming Language :: Python :: Implementation :: PyPy",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Topic :: System :: Networking",
    "Typing :: Typed",
]
requires-python = ">=3.9"
dependencies = [
    # attrs 19.2.0 adds `eq` option to decorators
    # attrs 20.1.0 adds @frozen
    # attrs 21.1.0 adds a dataclass transform for type-checkers
    # attrs 21.3.0 adds `import attrs`
    "attrs >= 23.2.0",
    "sortedcontainers",
    "idna",
    "outcome",
    "sniffio >= 1.3.0",
    # cffi 1.12 adds from_buffer(require_writable=True) and ffi.release()
    # cffi 1.14 fixes memory leak inside ffi.getwinerror()
    # cffi is required on Windows, except on PyPy where it is built-in
    "cffi>=1.14; os_name == 'nt' and implementation_name != 'pypy'",
    "exceptiongroup; python_version < '3.11'",
]
dynamic = ["version"]

[project.readme]
file = "README.rst"
content-type = "text/x-rst"

[project.urls]
Homepage = "https://github.com/python-trio/trio"
Documentation = "https://trio.readthedocs.io/"
Changelog = "https://trio.readthedocs.io/en/latest/history.html"

[project.entry-points.hypothesis]
trio = "trio._core._run:_hypothesis_plugin_setup"

[tool.setuptools]
# This means, just install *everything* you see under trio/, even if it
# doesn't look like a source file, so long as it appears in MANIFEST.in:
include-package-data = true

[tool.setuptools.dynamic]
version = {attr = "trio._version.__version__"}

[tool.black]
force-exclude = '''
(
  ^/docs/source/reference-.*
  | ^/docs/source/tutorial
)
'''

[tool.codespell]
ignore-words-list = 'astroid,crasher,asend'

[tool.ruff]
respect-gitignore = true
fix = true

# The directories to consider when resolving first vs. third-party imports.
# Does not control what files to include/exclude!
src = ["src/trio"]

include = ["*.py", "*.pyi", "**/pyproject.toml"]

extend-exclude = [
  "docs/source/reference-*",
  "docs/source/tutorial/*",
]

[tool.ruff.lint]
preview = true
allowed-confusables = ["–"]

select = [
    "A",     # flake8-builtins
    "ANN",   # flake8-annotations
    "ASYNC", # flake8-async
    "B",     # flake8-bugbear
    "C4",    # flake8-comprehensions
    "COM",   # flake8-commas
    "E",     # Error
    "EXE",   # flake8-executable
    "F",     # pyflakes
    "FA",    # flake8-future-annotations
    "FLY",   # flynt
    "FURB",  # refurb
    "I",     # isort
    "ICN",   # flake8-import-conventions
    "PERF",  # Perflint
    "PIE",   # flake8-pie
    "PT",    # flake8-pytest-style
    "PYI",   # flake8-pyi
    "Q",     # flake8-quotes
    "RUF",   # Ruff-specific rules
    "SIM",   # flake8-simplify
    "TC",    # flake8-type-checking
    "UP",    # pyupgrade
    "W",     # Warning
    "YTT",   # flake8-2020
]
extend-ignore = [
    "A002",    # builtin-argument-shadowing
    "ANN401",  # any-type (mypy's `disallow_any_explicit` is better)
    "E402",    # module-import-not-at-top-of-file (usually OS-specific)
    "E501",    # line-too-long
    "F403",    # undefined-local-with-import-star
    "F405",    # undefined-local-with-import-star-usage
    "PERF203", # try-except-in-loop (not always possible to refactor)
    "PT012",   # multiple statements in pytest.raises block
    "SIM117",  # multiple-with-statements (messes up lots of context-based stuff and looks bad)

    # conflicts with formatter (ruff recommends these be disabled)
    "COM812",
]

[tool.ruff.lint.per-file-ignores]
# F401 is ignoring unused imports. For these particular files,
# these are public APIs where we are importing everything we want
# to export for public use.
'src/trio/__init__.py' = ['F401']
'src/trio/_core/__init__.py' = ['F401']
'src/trio/abc.py' = ['F401', 'A005']
'src/trio/lowlevel.py' = ['F401']
'src/trio/socket.py' = ['F401', 'A005']
'src/trio/testing/__init__.py' = ['F401']
# RUF029 is ignoring tests that are marked as async functions but
# do not use an await in their function bodies. There are several
# places where internal trio synchronous code relies on being
# called from an async function, where current task is set up.
'src/trio/_tests/*.py' = ['RUF029']
'src/trio/_core/_tests/*.py' = ['RUF029']
# A005 is ignoring modules that shadow stdlib modules.
'src/trio/_abc.py' = ['A005']
'src/trio/_socket.py' = ['A005']
'src/trio/_ssl.py' = ['A005']

[tool.ruff.lint.isort]
combine-as-imports = true

[tool.ruff.lint.flake8-pytest-style]
fixture-parentheses = false

[tool.mypy]
python_version = "3.9"
files = ["src/trio/", "docs/source/*.py"]

# Be flexible about dependencies that don't have stubs yet (like pytest)
ignore_missing_imports = true

# Be strict about use of Mypy
local_partial_types = true
warn_unused_ignores = true
warn_unused_configs = true
warn_redundant_casts = true
warn_return_any = true

# Avoid subtle backsliding
disallow_any_decorated = true
disallow_any_explicit = true
disallow_any_generics = true
disallow_any_unimported = true
disallow_incomplete_defs = true
disallow_subclassing_any = true
disallow_untyped_calls = true
disallow_untyped_decorators = true
disallow_untyped_defs = true
check_untyped_defs = true

[tool.pyright]
pythonVersion = "3.9"
reportUnnecessaryTypeIgnoreComment = true
typeCheckingMode = "strict"

[tool.pytest.ini_options]
addopts = ["--strict-markers", "--strict-config", "-p trio._tests.pytest_plugin", "--import-mode=importlib"]
faulthandler_timeout = 60
filterwarnings = [
  "error",
  # https://gitter.im/python-trio/general?at=63bb8d0740557a3d5c688d67
  'ignore:You are using cryptography on a 32-bit Python on a 64-bit Windows Operating System. Cryptography will be significantly faster if you switch to using a 64-bit Python.:UserWarning',
  # https://github.com/berkerpeksag/astor/issues/217
  'ignore:ast.Num is deprecated:DeprecationWarning:astor',
]
junit_family = "xunit2"
markers = ["redistributors_should_skip: tests that should be skipped by downstream redistributors"]
xfail_strict = true

[tool.towncrier]
directory = "newsfragments"
filename = "docs/source/history.rst"
issue_format = "`#{issue} <https://github.com/python-trio/trio/issues/{issue}>`__"
# Usage:
# - PRs should drop a file like "issuenumber.feature" in newsfragments
# (or "bugfix", "doc", "removal", "misc"; misc gets no text, we can
# customize this)
# - At release time after bumping version number, run: towncrier
# (or towncrier --draft)
package = "trio"
package_dir = "src"
underlines = ["-", "~", "^"]

[[tool.towncrier.type]]
directory = "headline"
name = "Headline features"
showcontent = true

[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking changes"
showcontent = true

[[tool.towncrier.type]]
directory = "feature"
name = "Features"
showcontent = true

[[tool.towncrier.type]]
directory = "bugfix"
name = "Bugfixes"
showcontent = true

[[tool.towncrier.type]]
directory = "doc"
name = "Improved documentation"
showcontent = true

[[tool.towncrier.type]]
directory = "deprecated"
name = "Deprecations and removals"
showcontent = true

[[tool.towncrier.type]]
directory = "removal"
name = "Removals without deprecations"
showcontent = true

[[tool.towncrier.type]]
directory = "misc"
name = "Miscellaneous internal changes"
showcontent = true

[tool.coverage.html]
show_contexts = true
skip_covered = false

[tool.coverage.paths]
_site-packages-to-src-mapping = [
  "src",
  "*/src",
  '*\src',
  "*/lib/pypy*/site-packages",
  "*/lib/python*/site-packages",
  '*\Lib\site-packages',
]

[tool.coverage.run]
branch = true
source_pkgs = ["trio"]
omit = [
    # Omit the generated files in trio/_core starting with _generated_
    "*/trio/_core/_generated_*",
    # Type tests aren't intended to be run, just passed to type checkers.
    "*/type_tests/*",
    # Script used to check type completeness that isn't run in tests
    "*/trio/_tests/check_type_completeness.py",
]
# The test suite spawns subprocesses to test some stuff, so make sure
# this doesn't corrupt the coverage files
parallel = true
plugins = []
relative_files = true
source = ["."]

[tool.coverage.report]
precision = 1
skip_covered = true
skip_empty = true
show_missing = true
exclude_also = [
  '^\s*@pytest\.mark\.xfail',
   "abc.abstractmethod",
   "if TYPE_CHECKING.*:",
   "if _t.TYPE_CHECKING:",
   "if t.TYPE_CHECKING:",
   "@overload",
   'class .*\bProtocol\b.*\):',
   "raise NotImplementedError",
   'TODO: test this line'
]
partial_branches = [
    "pragma: no branch",
    "if not TYPE_CHECKING:",
    "if not _t.TYPE_CHECKING:",
    "if not t.TYPE_CHECKING:",
    "if .* or not TYPE_CHECKING:",
    "if .* or not _t.TYPE_CHECKING:",
    "if .* or not t.TYPE_CHECKING:",
   'TODO: test this branch',
]