pyproject.toml

[tool.black]
line-length = 130
target-version = ["py310"]
skip-magic-trailing-comma = true
# Exclude protobuf files because they have long line lengths
# that can't be autofixed. Like docstrings and import aliases.
# Ideally, we could configure Black to allow longer line lengths
# for just these files, but doesn't seem possible yet.
force-exclude = ".*_pb2.pyi"

[tool.ruff]
line-length = 130
# Oldest supported Python version
target-version = "py38"
fix = true
exclude = [
    # virtual environment
    ".env",
    ".venv",
    "env",
    # cache directories, etc.:
    ".git",
    ".mypy_cache",
    ".pytype",
]

[tool.ruff.lint]
# Disable all rules on test cases by default:
# test cases often deliberately contain code
# that might not be considered idiomatic or modern.
#
# Note: some rules that are specifically useful to the test cases
# are invoked via separate runs of ruff in pre-commit:
# see our .pre-commit-config.yaml file for details
exclude = ["**/test_cases/**/*.py"]
# We still use flake8-pyi and flake8-noqa to check these (see .flake8 config file);
# tell ruff not to flag these as e.g. "unused noqa comments"
external = ["F821", "NQA", "Y"]
select = [
    "B", # flake8-bugbear
    "FA", # flake8-future-annotations
    "I", # isort
    "PGH", # pygrep-hooks
    "RUF", # Ruff-specific and unused-noqa
    "UP", # pyupgrade
    # Flake8 base rules
    "E", # pycodestyle Error
    "F", # Pyflakes
    "W", # pycodestyle Warning
    # PYI: only enable rules that have autofixes and that we always want to fix (even manually),
    # avoids duplicate # noqa with flake8-pyi and flake8-noqa flagging `PYI` codes
    # See https://github.com/plinss/flake8-noqa/issues/22
    "PYI009", # Empty body should contain `...`, not pass
    "PYI010", # Function body must contain only `...`
    "PYI012", # Class bodies must not contain `pass`
    "PYI013", # Non-empty class bodies must not contain `...`
    "PYI014", # Only simple default values allowed for arguments
    "PYI015", # Only simple default values allowed for assignments
    "PYI016", # Duplicate union member `{}`
    "PYI019", # Methods like `{method_name}` should return `Self` instead of a custom `TypeVar`
    "PYI020", # Quoted annotations should not be included in stubs
    "PYI025", # Use `from collections.abc import Set as AbstractSet` to avoid confusion with the `set` builtin
    # "PYI026", Waiting for this mypy bug to be fixed: https://github.com/python/mypy/issues/16581
    "PYI030", # Multiple literal members in a union. Use a single literal, e.g. `Literal[{}]`
    "PYI032", # Prefer `object` to `Any` for the second parameter to `{method_name}`
    "PYI034", # `__new__` methods usually return self at runtime
    "PYI036", # Star-args in `{method_name}` should be annotated with `object`
    "PYI044", # `from __future__ import annotations` has no effect in stub files, since type checkers automatically treat stubs as having those semantics
    "PYI055", # Multiple `type[T]` usages in a union. Combine them into one, e.g., `type[{union_str}]`.
    "PYI058", # Use `{return_type}` as the return value for simple `{method}` methods
    # "PYI061", # TODO: Enable when out of preview
    "PYI062", # Duplicate literal member `{}`
    "PYI064", # `Final[Literal[{literal}]]` can be replaced with a bare Final
]
extend-safe-fixes = [
    "UP036", # Remove unnecessary `sys.version_info` blocks
]
ignore = [
    # TODO: Ruff 0.8.0 added sorting of __all__ and __slots_. Validate whether we want this in stubs
    "RUF022",
    "RUF023",

    ###
    # Rules that can conflict with the formatter (Black)
    # https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
    ###
    "E111", # indentation-with-invalid-multiple
    "E114", # indentation-with-invalid-multiple-comment
    "E117", # over-indented
    "W191", # tab-indentation
    ###
    # Rules we don't want or don't agree with
    ###
    # Slower and more verbose https://github.com/astral-sh/ruff/issues/7871
    "UP038", # Use `X | Y` in `isinstance` call instead of `(X, Y)`
    # Used for direct, non-subclass type comparison, for example: `type(val) is str`
    # see https://github.com/astral-sh/ruff/issues/6465
    "E721", # Do not compare types, use `isinstance()`
    ###
    # False-positives, but already checked by type-checkers
    ###
    # Ruff doesn't support multi-file analysis yet: https://github.com/astral-sh/ruff/issues/5295
    "RUF013", # PEP 484 prohibits implicit `Optional`
]

[tool.ruff.lint.per-file-ignores]
"*.pyi" = [
    # Most flake8-bugbear rules don't apply for third-party stubs like typeshed.
    # B033 could be slightly useful but Ruff doesn't have per-file select
    "B", # flake8-bugbear
    # Rules that are out of the control of stub authors:
    "F403", # `from . import *` used; unable to detect undefined names
    # Stubs can sometimes re-export entire modules.
    # Issues with using a star-imported name will be caught by type-checkers.
    "F405", # may be undefined, or defined from star imports
]
# See comment on black's force-exclude config above
"*_pb2.pyi" = [
    "E501", # Line too long
]

[tool.ruff.lint.isort]
split-on-trailing-comma = false
combine-as-imports = true
extra-standard-library = [
    # Group these with stdlib
    "_typeshed",
    "typing_extensions",
    # Extra modules not recognized by Ruff
    # Added in Python 3.9
    "zoneinfo",
]
known-first-party = ["_utils", "ts_utils"]

[tool.typeshed]
oldest_supported_python = "3.8"