typeshed/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 = [
    "ARG", # flake8-unused-arguments
    "B", # flake8-bugbear
    "D", # pydocstyle
    "EXE", # flake8-executable
    "FA", # flake8-future-annotations
    "I", # isort
    "N", # pep8-naming
    "PGH", # pygrep-hooks
    "RUF", # Ruff-specific and unused-noqa
    "TRY", # tryceratops
    "UP", # pyupgrade
    "YTT", # flake8-2020
    # Flake8 base rules
    "E", # pycodestyle Error
    "F", # Pyflakes
    "W", # pycodestyle Warning
    # Only include flake8-annotations rules that are autofixable. Otherwise leave this to mypy+pyright
    "ANN2",
    # Don't include TC rules that create a TYPE_CHECKING block or stringifies annotations
    "TC004", # Move import `{qualified_name}` out of type-checking block. Import is used for more than type hinting.
    "TC005", # Found empty type-checking block
    # "TC008", # TODO: Enable when out of preview
    "TC010", # Invalid string member in `X | Y`-style union type
    # Most refurb rules are in preview and can be opinionated,
    # consider them individually as they come out of preview (last check: 0.8.4)
    "FURB105", # Unnecessary empty string passed to `print`
    "FURB129", # Instead of calling `readlines()`, iterate over file object directly
    "FURB136", # Replace `if` expression with `{min_max}` call
    "FURB167", # Use of regular expression alias `re.{}`
    "FURB168", # Prefer `is` operator over `isinstance` to check if an object is `None`
    "FURB169", # Compare the identities of `{object}` and None instead of their respective types
    "FURB177", # Prefer `Path.cwd()` over `Path().resolve()` for current-directory lookups
    "FURB187", # Use of assignment of `reversed` on list `{name}`
    # 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 = [
    ###
    # 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
    ###
    # We're not a library, no need to document everything
    "D1", # Missing docstring in ...
    # Doesn't support split "summary line"
    "D205", # 1 blank line required between summary line and description
    # 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()`
    # Mostly from scripts and tests, it's ok to have messages passed directly to exceptions
    "TRY003", # Avoid specifying long messages outside the exception class
    # Slower and more verbose https://github.com/astral-sh/ruff/issues/7871
    "UP038", # Use `X | Y` in `isinstance` call instead of `(X, Y)`
    ###
    # 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" = [
    # A lot of stubs are incomplete on purpose, and that's configured through pyright
    # Some ANN204 (special method) are autofixable in stubs, but not all.
    "ANN2", # Missing return type annotation for ...
    # Most pep8-naming rules don't apply for third-party stubs like typeshed.
    # N811 to N814 could apply, but we often use them to disambiguate a name whilst making it look like a more common one
    "N8",
    # 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
    # Ruff 0.8.0 added sorting of __all__ and __slots_.
    # There is no consensus on whether we want to apply this to stubs, so keeping the status quo.
    # See https://github.com/python/typeshed/pull/13108
    "RUF022",
    "RUF023",
]
"*_pb2.pyi" = [
    # Leave the docstrings as-is, matching source
    "D", # pydocstyle
    # See comment on black's force-exclude config above
    "E501", # Line too long
]

[tool.ruff.lint.pydocstyle]
convention = "pep257" # https://docs.astral.sh/ruff/settings/#lint_pydocstyle_convention

[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.9"