pyproject.toml

[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"

[project]
name = "sublime-text-stubs"
dynamic = ["version"]
description = "Typing stubs for the Sublime Text plugin API (sublime, sublime_plugin)"
readme = "README.md"
# mypy parses a `.pyi` with the `ast` module of the interpreter it runs on, and the
# PEP 696 defaults in the stubs' type parameter lists need Python 3.13 to parse.
requires-python = ">=3.13"
license = "MIT"
license-files = ["LICENSE"]
authors = [{ name = "FichteFoll" }]
keywords = ["sublime-text", "stubs", "typing", "pep561"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "Programming Language :: Python :: 3",
    "Topic :: Software Development :: Documentation",
    "Topic :: Text Editors",
    "Typing :: Stubs Only",
]

[project.urls]
Homepage = "https://github.com/SublimeText/sublime-text-stubs"
Issues = "https://github.com/SublimeText/sublime-text-stubs/issues"
Changelog = "https://github.com/SublimeText/sublime-text-stubs/blob/main/CHANGELOG.md"

[dependency-groups]
dev = [
    "basedpyright",
    "mypy",
    "pyright",
    "ruff",
    "ty",
    "typing-extensions",
]

[tool.hatch.version]
source = "vcs"

[tool.hatch.build.targets.wheel]
# PEP 561 stub-only distribution: the directory name carries the `-stubs` suffix,
# which is what makes type checkers associate it with the `sublime` module.
packages = [
    "stubs/sublime-stubs",
    "stubs/sublime_plugin-stubs",
    "stubs/sublime_types-stubs",
]

[tool.hatch.build.targets.sdist]
include = ["stubs", "tests", "tools", "README.md", "CONTRIBUTING.md", "CHANGELOG.md", "LICENSE"]

# --- type checkers -----------------------------------------------------------
# The Python versions below are that of the plugin host of Sublime Text (Python 3.14),
# not that of the interpreter used to run the checkers.

# Shared by pyright and basedpyright. basedpyright reads `[tool.pyright]` and honours
# its own extra rules from it; a separate `[tool.basedpyright]` section is not an
# option, because basedpyright rejects a pyproject.toml that carries both sections
# ("Config file could not be parsed") and silently falls back to its defaults.
# The basedpyright-only settings below therefore make plain pyright log
# "Config contains unrecognized setting"; it ignores them and carries on.
#
# `typeCheckingMode` stays at "strict" rather than basedpyright's "all", because
# plain pyright rejects the value ('Config "typeCheckingMode" entry must contain
# "off", "basic", "standard", or "strict"') and then silently falls back to
# "standard", which is weaker than what it manages today. Every rule "all" adds on
# top of "strict" is therefore listed individually below instead, so basedpyright
# still runs the full set.
[tool.pyright]
include = ["stubs", "tests"]
extraPaths = ["stubs"]
# `tools/` holds the stub generator, which runs on the current interpreter rather than
# the Sublime Text one configured below. It is checked separately, as its own project:
# see ./tools/pyproject.toml and the `Tools` workflow.
exclude = ["references", "tools", "**/__pycache__", ".venv"]
pythonVersion = "3.14"
typeCheckingMode = "strict"
# These stubs are stub-only by nature: the modules they describe exist only inside
# Sublime Text, so `import sublime` can never resolve to a source file.
reportMissingModuleSource = false

# The "all" rules, spelled out.
reportCallInDefaultInitializer = "error"
reportImplicitOverride = "error"
reportImplicitStringConcatenation = "error"
reportImportCycles = "error"
reportMissingSuperCall = "error"
reportPropertyTypeMismatch = "error"
reportUninitializedInstanceVariable = "error"
reportUnnecessaryTypeIgnoreComment = "error"
reportUnreachable = "error"
reportUnusedCallResult = "error"

# The following rules are known by basedpyright only.
# pyright logs them as unrecognized and carries on.
reportEmptyAbstractUsage = "error"  # basedpyright only
reportIgnoreCommentWithoutRule = "error"  # basedpyright only
reportImplicitAbstractClass = "error"  # basedpyright only
reportImplicitRelativeImport = "error"  # basedpyright only
reportIncompatibleUnannotatedOverride = "error"  # basedpyright only
reportInvalidAbstractMethod = "error"  # basedpyright only
reportInvalidCast = "error"  # basedpyright only
reportPrivateLocalImportUsage = "error"  # basedpyright only
reportSelfClsDefault = "error"  # basedpyright only
reportUnannotatedClassAttribute = "error"  # basedpyright only
reportUnsafeMultipleInheritance = "error"  # basedpyright only
reportUnusedParameter = "error"  # basedpyright only
reportAny = "error"  # basedpyright only
reportExplicitAny = "error"  # basedpyright only

[tool.mypy]
python_version = "3.14"
strict = true
mypy_path = "stubs"
files = ["stubs", "tests"]
warn_unreachable = true
enable_error_code = [
    "deprecated",
    "ignore-without-code",
    "possibly-undefined",
    "redundant-expr",
    "redundant-self",
    "truthy-bool",
    "truthy-iterable",
    "unimported-reveal",
    "unused-awaitable",
]

[tool.ty.src]
include = ["stubs", "tests"]
exclude = ["references", "tools"]

[tool.ty.environment]
python-version = "3.14"
extra-paths = ["stubs"]

# --- ruff --------------------------------------------------------------------
# The type checkers above validate what the stubs mean; ruff's flake8-pyi rules
# validate that they are written the way stubs should be, which no type checker
# looks at. A finding in `stubs/` is a bug in tools/generate_stubs.py: fix it there
# and regenerate, never edit a `.pyi`. `tools/` is linted separately, against its
# own Python target; see ./tools/pyproject.toml.
[tool.ruff]
include = ["stubs/**/*.pyi", "tests/**/*.py"]
# `tools/` has a ruff config of its own, which ruff would otherwise pick up and apply
# while walking down from here, linting the generator twice under two rule sets.
extend-exclude = ["references", "tools"]
line-length = 120
target-version = "py314"

[tool.ruff.lint]
# The families `tools/` selects, plus `PYI`. `PTH`, `DTZ`, `G` and friends cannot
# match declarations without bodies, but cost nothing to keep aligned with tools.
select = [
    "A",     # flake8-builtins
    "ARG",   # flake8-unused-arguments
    "B",     # flake8-bugbear
    "C4",    # flake8-comprehensions
    "DTZ",   # flake8-datetimez
    "E",     # pycodestyle errors
    "F",     # pyflakes
    "FURB",  # refurb
    "G",     # flake8-logging-format
    "I",     # isort
    "ISC",   # flake8-implicit-str-concat
    "LOG",   # flake8-logging
    "N",     # pep8-naming
    "PERF",  # perflint
    "PGH",   # pygrep-hooks
    "PIE",   # flake8-pie
    "PL",    # pylint
    "PTH",   # flake8-use-pathlib
    "PYI",   # flake8-pyi
    "RET",   # flake8-return
    "RUF",   # ruff-specific rules
    "SIM",   # flake8-simplify
    "SLF",   # flake8-self
    "TID",   # flake8-tidy-imports
    "UP",    # pyupgrade
    "W",     # pycodestyle warnings
]
ignore = [
    # typeshed's house style forbids docstrings in a stub. These stubs exist to carry
    # the reference documentation to the editor, so every declaration keeps its own.
    "PYI021",
    # The rule wants `KIND_AMBIGUOUS: Kind = ...` instead of the tuple the constant
    # really holds, which would hide its value from the editor.
    "PYI015",
]

[tool.ruff.lint.isort]
# The generator sorts imported names alphabetically. Ruff's default puts ALL_CAPS
# names first, which would disagree over `from sublime_types import DIP`.
order-by-type = false

[tool.ruff.lint.per-file-ignores]
"stubs/**/*.pyi" = [
    # Parameter names such as `id`, `type` and `format` are part of the API these
    # stubs describe; a plugin author passes them by keyword.
    "A002",
    # Signatures are wrapped at `STUB_LINE_WIDTH`, but the docstrings are reference
    # prose kept verbatim and a handful of its lines are longer than any limit worth
    # setting; the directive at references/python314/sublime_plugin.py:2157-2158 is
    # emitted as a single 188-character line.
    "E501",
    # The typographic quote comes from the reference docstring.
    "RUF002",
]
"tests/**/*.py" = [
    # `tests/typing/` is not a package: nothing imports or executes these files.
    "INP001",
]