\n\n
\n ![\"Shows](\"https://raw.githubusercontent.com/astral-sh/ty/main/docs/assets/ty-benchmark-cli.svg\")
\n
\n Type checking the home-assistant project without caching.\n
\n\n\n\nty is backed by [Astral](https://astral.sh), the creators of\n[uv](https://github.com/astral-sh/uv) and [Ruff](https://github.com/astral-sh/ruff).\n\nty is currently in [beta](#version-policy).\n\n## Highlights\n\n- 10x - 100x faster than mypy and Pyright\n- Comprehensive [diagnostics](https://docs.astral.sh/ty/features/diagnostics/) with rich contextual information\n- Configurable [rule levels](https://docs.astral.sh/ty/rules/), [per-file overrides](https://docs.astral.sh/ty/reference/configuration/#overrides), [suppression comments](https://docs.astral.sh/ty/suppression/), and first-class project support\n- Designed for adoption, with support for [redeclarations](https://docs.astral.sh/ty/features/type-system/#redeclarations) and [partially typed code](https://docs.astral.sh/ty/features/type-system/#gradual-guarantee)\n- [Language server](https://docs.astral.sh/ty/features/language-server/) with code navigation, completions, code actions, auto-import, inlay hints, on-hover help, etc.\n- Fine-grained [incremental analysis](https://docs.astral.sh/ty/features/language-server/#fine-grained-incrementality) designed for fast updates when editing files in an IDE\n- Editor integrations for [VS Code](https://docs.astral.sh/ty/editors/#vs-code), [PyCharm](https://docs.astral.sh/ty/editors/#pycharm), [Neovim](https://docs.astral.sh/ty/editors/#neovim) and more\n- Advanced typing features like first-class [intersection types](https://docs.astral.sh/ty/features/type-system/#intersection-types), advanced [type narrowing](https://docs.astral.sh/ty/features/type-system/#top-and-bottom-materializations), and\n [sophisticated reachability analysis](https://docs.astral.sh/ty/features/type-system/#reachability-based-on-types)\n\n## Getting started\n\nRun ty with [uvx](https://docs.astral.sh/uv/guides/tools/#running-tools) to get started quickly:\n\n```shell\nuvx ty check\n```\n\nOr, check out the [ty playground](https://play.ty.dev) to try it out in your browser.\n\nTo learn more about using ty, see the [documentation](https://docs.astral.sh/ty/).\n\n## Installation\n\nTo install ty, see the [installation](https://docs.astral.sh/ty/installation/) documentation.\n\nTo add the ty language server to your editor, see the [editor integration](https://docs.astral.sh/ty/editors/) guide.\n\n## Getting help\n\nIf you have questions or want to report a bug, please open an\n[issue](https://github.com/astral-sh/ty/issues) in this repository.\n\nYou may also join our [Discord server](https://discord.com/invite/astral-sh).\n\n## Contributing\n\nDevelopment of this project takes place in the [Ruff](https://github.com/astral-sh/ruff) repository\nat this time. Please [open pull requests](https://github.com/astral-sh/ruff/pulls) there for changes\nto anything in the `ruff` submodule (which includes all of the Rust source code).\n\nSee the\n[contributing guide](./CONTRIBUTING.md) for more details.\n\n## Version policy\n\nty uses `0.0.x` versioning. ty does not yet have a stable API; breaking changes, including changes\nto diagnostics, may occur between any two versions. See the [type system support](https://github.com/astral-sh/ty/issues/1889)\ntracking issue for a detailed overview of currently supported features.\n\n## FAQ\n\n\n\n\n\n#### Why is ty doing \\_\\_\\_\\_\\_?\n\nSee our [typing FAQ](https://docs.astral.sh/ty/reference/typing-faq).\n\n#### How do you pronounce ty?\n\nIt's pronounced as \"tee - why\" ([`/tiː waɪ/`](https://en.wikipedia.org/wiki/Help:IPA/English#Key))\n\n#### How should I stylize ty?\n\nJust \"ty\", please.\n\n\n\n## License\n\nty is licensed under the MIT license ([LICENSE](LICENSE) or\n
\n \n ![\"Made](\"https://raw.githubusercontent.com/astral-sh/uv/main/assets/svg/Astral.svg\")
\n \n
\n"
},
{
"path": "SECURITY.md",
"content": "# Security policy\n\n## Reporting a vulnerability\n\nIf you have found a possible vulnerability, please email `security at astral dot sh`.\n\n## Bug bounties\n\nWhile we sincerely appreciate and encourage reports of suspected security problems, please note that\nAstral does not currently run any bug bounty programs.\n\n## Vulnerability disclosures\n\nCritical vulnerabilities will be disclosed via GitHub's\n[security advisory](https://github.com/astral-sh/ty/security) system.\n"
},
{
"path": "_typos.toml",
"content": "[files]\nextend-exclude = []\n\n[default.extend-words]\n\n[default]\nextend-ignore-re = [\n # Line ignore with trailing \"spellchecker:disable-line\"\n \"(?Rm)^.*#\\\\s*spellchecker:disable-line$\",\n \"LICENSEs\",\n \"ntBre\"\n]\n"
},
{
"path": "assets/badge/v0.json",
"content": "{\n \"label\": \"\",\n \"message\": \"ty\",\n \"logoSvg\": \"\",\n \"logoWidth\": 10,\n \"labelColor\": \"grey\",\n \"color\": \"#261230\"\n}\n"
},
{
"path": "dist-workspace.toml",
"content": "[workspace]\nmembers = [\"cargo:./ruff\"]\npackages = [\"ty\"]\nversion = \"0.0.24\"\n\n# Config for 'dist'\n[dist]\n# The preferred dist version to use in CI (Cargo.toml SemVer syntax)\ncargo-dist-version = \"0.31.0\"\n# Whether to consider the binaries in a package for distribution (defaults true)\ndist = false\n# CI backends to support\nci = \"github\"\n# The installers to generate for each app\ninstallers = [\"shell\", \"powershell\"]\n# The archive format to use for windows builds (defaults .zip)\nwindows-archive = \".zip\"\n# The archive format to use for non-windows builds (defaults .tar.xz)\nunix-archive = \".tar.gz\"\n# Target platforms to build apps for (Rust target-triple syntax)\ntargets = [\n \"aarch64-apple-darwin\",\n \"aarch64-unknown-linux-gnu\",\n \"aarch64-unknown-linux-musl\",\n \"aarch64-pc-windows-msvc\",\n \"arm-unknown-linux-musleabihf\",\n \"armv7-unknown-linux-gnueabihf\",\n \"armv7-unknown-linux-musleabihf\",\n \"x86_64-apple-darwin\",\n \"powerpc64-unknown-linux-gnu\",\n \"powerpc64le-unknown-linux-gnu\",\n \"s390x-unknown-linux-gnu\",\n \"x86_64-unknown-linux-gnu\",\n \"x86_64-unknown-linux-musl\",\n \"x86_64-pc-windows-msvc\",\n \"i686-unknown-linux-gnu\",\n \"i686-unknown-linux-musl\",\n \"i686-pc-windows-msvc\",\n]\n# Whether to auto-include files like READMEs, LICENSEs, and CHANGELOGs (default true)\nauto-includes = false\n# Whether dist should create a Github Release or use an existing draft\ncreate-release = true\n# Which actions to run on pull requests\npr-run-mode = \"plan\"\n# Whether to publish prereleases to package managers\npublish-prereleases = true\n# Whether CI should trigger releases with dispatches instead of tag pushes\ndispatch-releases = true\n# Which phase dist should use to create the GitHub release\ngithub-release = \"announce\"\n# Whether to enable GitHub Attestations\ngithub-attestations = true\n# When to generate GitHub Attestations\ngithub-attestations-phase = \"announce\"\n# Patterns to attest when creating attestations for release artifacts\ngithub-attestations-filters = [\"*.json\", \"*.sh\", \"*.ps1\", \"*.zip\", \"*.tar.gz\"]\n# Whether CI should include auto-generated code to build local artifacts\nbuild-local-artifacts = false\n# Local artifacts jobs to run in CI\nlocal-artifacts-jobs = [\"./build-binaries\", \"./build-docker\"]\n# Publish jobs to run in CI\npublish-jobs = [\"./publish-pypi\"]\n# Post-announce jobs to run in CI\npost-announce-jobs = [\"./publish-docs\", \"./publish-mirror\"]\n# Custom permissions for GitHub Jobs\ngithub-custom-job-permissions = { \"build-docker\" = { packages = \"write\", contents = \"read\", id-token = \"write\", attestations = \"write\" }, \"publish-mirror\" = { contents = \"read\" } }\n# Whether to install an updater program\ninstall-updater = false\n# Path that installers should place binaries in\ninstall-path = [\"$XDG_BIN_HOME/\", \"$XDG_DATA_HOME/../bin\", \"~/.local/bin\"]\n# Whether source tarballs should include submodules\nrecursive-tarball = true\n# Prefer simple hosting for downloads, falling back to GitHub releases\nhosting = [\"simple\", \"github\"]\nsimple-download-url = \"https://releases.astral.sh/github/ty/releases/download/{tag}\"\n\n[dist.github-custom-runners]\nglobal = \"depot-ubuntu-latest-4\"\n\n[dist.github-action-commits]\n\"actions/checkout\" = \"0c366fd6a839edf440554fa01a7085ccba70ac98\" # v6.0.2\n\"actions/upload-artifact\" = \"bbbca2ddaa5d8feaa63e36b76fdaad77386f024f\" # v7.0.0\n\"actions/download-artifact\" = \"70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3\" # v8.0.0\n\"actions/attest-build-provenance\" = \"00014ed6ed5efc5b1ab7f7f34a39eb55d41aa4f8\" # v3.1.0\n"
},
{
"path": "docs/.overrides/main.html",
"content": "{% extends \"base.html\" %}\n\n{% block htmltitle %}\n{% if page.meta and page.meta.title %}\n\n \nsubprocess import at the top of the file.\n ![\"Shows](\"./assets/ty-benchmark-cli-light.svg#only-light\")
\n
\n ![\"Shows](\"./assets/ty-benchmark-cli.svg#only-dark\")
\n
\n Type checking the home-assistant project without caching.\n
\n\nty is backed by [Astral](https://astral.sh), the creators of\n[uv](https://github.com/astral-sh/uv) and [Ruff](https://github.com/astral-sh/ruff).\n\n## Highlights\n\n- 10x - 100x faster than mypy and Pyright\n- Comprehensive [diagnostics](./features/diagnostics.md) with rich contextual information\n- Configurable [rule levels](./rules.md), [per-file overrides](./reference/configuration.md#overrides), [suppression comments](./suppression.md), and first-class project support\n- Designed for adoption, with support for [redeclarations](./features/type-system.md#redeclarations) and [partially typed code](./features/type-system.md#gradual-guarantee)\n- [Language server](./features/language-server.md) with code navigation, completions, code actions, auto-import, inlay hints, on-hover help, etc.\n- Fine-grained [incremental analysis](./features/language-server.md#fine-grained-incrementality) designed for fast updates when editing files in an IDE\n- Editor integrations for [VS Code](./editors.md#vs-code), [PyCharm](./editors.md#pycharm), [Neovim](./editors.md#neovim) and more\n- Advanced typing features like first-class [intersection types](./features/type-system.md#intersection-types), advanced [type narrowing](./features/type-system.md#top-and-bottom-materializations), and\n [sophisticated reachability analysis](./features/type-system.md#reachability-based-on-types)\n\n## Getting started\n\nRun ty with [uvx](https://docs.astral.sh/uv/guides/tools/#running-tools) to get started quickly:\n\n```shell\nuvx ty check\n```\n\nty will check all Python files in the working directory or project by default.\n\nSee the [type checking](./type-checking.md) documentation for more details.\n\n## Installation\n\nTo install ty, see the [installation](./installation.md) documentation.\n\nTo add the ty language server to your editor, see the [editor integration](./editors.md) guide.\n\n## Playground\n\nty has an [online playground](https://play.ty.dev) you can use to try it out on snippets or small\nprojects.\n\n!!! tip\n\n The playground is a great way to share snippets with other people, e.g., when sharing a bug\n report.\n" }, { "path": "docs/installation.md", "content": "# Installing ty\n\n## Running ty without installation\n\nUse [uvx](https://docs.astral.sh/uv/guides/tools/) to quickly get started with ty:\n\n```shell\nuvx ty\n```\n\n## Installation methods\n\n### Adding ty to your project\n\n!!! tip\n\n Adding ty as a dependency ensures that all developers on the project are using the same version\n of ty.\n\nUse [uv](https://github.com/astral-sh/uv) (or your project manager of choice) to add ty as a\ndevelopment dependency:\n\n```shell\nuv add --dev ty\n```\n\nThen, use `uv run` to invoke ty:\n\n```shell\nuv run ty\n```\n\nTo update ty, use `--upgrade-package`:\n\n```shell\nuv lock --upgrade-package ty\n```\n\n### Installing globally with uv\n\nInstall ty globally with uv:\n\n```shell\nuv tool install ty@latest\n```\n\nTo update ty, use `uv tool upgrade`:\n\n```shell\nuv tool upgrade ty\n```\n\n### Installing with the standalone installer\n\nty includes a standalone installer.\n\n=== \"macOS and Linux\"\n\n Use `curl` to download the script and execute it with `sh`:\n\n ```console\n $ curl -LsSf https://astral.sh/ty/install.sh | sh\n ```\n\n If your system doesn't have `curl`, you can use `wget`:\n\n ```console\n $ wget -qO- https://astral.sh/ty/install.sh | sh\n ```\n\n Request a specific version by including it in the URL:\n\n ```console\n $ curl -LsSf https://astral.sh/ty/0.0.24/install.sh | sh\n ```\n\n=== \"Windows\"\n\n Use `irm` to download the script and execute it with `iex`:\n\n ```pwsh-session\n PS> powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/ty/install.ps1 | iex\"\n ```\n\n Changing the [execution policy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4#powershell-execution-policies) allows running a script from the internet.\n\n Request a specific version by including it in the URL:\n\n ```pwsh-session\n PS> powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/ty/0.0.24/install.ps1 | iex\"\n ```\n\n!!! tip\n\n The installation script may be inspected before use:\n\n === \"macOS and Linux\"\n\n ```console\n $ curl -LsSf https://astral.sh/ty/install.sh | less\n ```\n\n === \"Windows\"\n\n ```pwsh-session\n PS> powershell -c \"irm https://astral.sh/ty/install.ps1 | more\"\n ```\n\n Alternatively, the installer or binaries can be downloaded directly from [GitHub](#installing-from-github-releases).\n\n### Installing from GitHub Releases\n\nty release artifacts can be downloaded directly from\n[GitHub Releases](https://github.com/astral-sh/ty/releases).\n\nEach release page includes binaries for all supported platforms as well as instructions for using\nthe standalone installer via `github.com` instead of `astral.sh`.\n\n### Installing globally with pipx\n\nInstall ty globally with pipx:\n\n```shell\npipx install ty\n```\n\nTo update ty, use `pipx upgrade`:\n\n```shell\npipx upgrade ty\n```\n\n### Installing with pip\n\nInstall ty into your current Python environment with pip:\n\n```shell\npip install ty\n```\n\n### Installing globally with mise\n\nInstall ty globally with with [mise](https://github.com/jdx/mise):\n\n```shell\nmise install ty\n```\n\nTo set it globally:\n\n```shell\nmise use --global ty\n```\n\n### Installing in Docker\n\nInstall ty in Docker by copying the binary from the official image:\n\n```dockerfile title=\"Dockerfile\"\nCOPY --from=ghcr.io/astral-sh/ty:latest /ty /bin/\n```\n\nThe following tags are available:\n\n- `ghcr.io/astral-sh/ty:latest`\n- `ghcr.io/astral-sh/ty:{major}.{minor}.{patch}`, e.g., `ghcr.io/astral-sh/ty:0.0.24`\n- `ghcr.io/astral-sh/ty:{major}.{minor}`, e.g., `ghcr.io/astral-sh/ty:0.0` (the latest patch\n version)\n\n### Using ty with Bazel\n\n[`aspect_rules_lint`](https://registry.bazel.build/docs/aspect_rules_lint#function-lint_ty_aspect)\nprovides a Bazel lint aspect that runs ty. See its documentation for setup instructions.\n\n## Adding ty to your editor\n\nSee the [editor integration](./editors.md) guide to add ty to your editor.\n\n## Shell autocompletion\n\n!!! tip\n\n You can run `echo $SHELL` to help you determine your shell.\n\nTo enable shell autocompletion for ty commands, run one of the following:\n\n=== \"Bash\"\n\n ```bash\n echo 'eval \"$(ty generate-shell-completion bash)\"' >> ~/.bashrc\n ```\n\n=== \"Zsh\"\n\n ```bash\n echo 'eval \"$(ty generate-shell-completion zsh)\"' >> ~/.zshrc\n ```\n\n=== \"fish\"\n\n ```bash\n echo 'ty generate-shell-completion fish | source' > ~/.config/fish/completions/ty.fish\n ```\n\n=== \"Elvish\"\n\n ```bash\n echo 'eval (ty generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv\n ```\n\n=== \"PowerShell / pwsh\"\n\n ```powershell\n if (!(Test-Path -Path $PROFILE)) {\n New-Item -ItemType File -Path $PROFILE -Force\n }\n Add-Content -Path $PROFILE -Value '(& ty generate-shell-completion powershell) | Out-String | Invoke-Expression'\n ```\n\nThen restart the shell or source the shell config file.\n" }, { "path": "docs/js/extra.js", "content": "function cleanupClipboardText(targetSelector) {\n const targetElement = document.querySelector(targetSelector);\n\n // exclude \"Generic Prompt\" and \"Generic Output\" spans from copy\n const excludedClasses = [\"gp\", \"go\"];\n\n const clipboardText = Array.from(targetElement.childNodes)\n .filter(\n (node) =>\n !excludedClasses.some((className) =>\n node?.classList?.contains(className)\n )\n )\n .map((node) => node.textContent)\n .filter((s) => s != \"\");\n return clipboardText.join(\"\").trim();\n}\n\n// Sets copy text to attributes lazily using an Intersection Observer.\nfunction setCopyText() {\n // The `data-clipboard-text` attribute allows for customized content in the copy\n // See: https://www.npmjs.com/package/clipboard#copy-text-from-attribute\n const attr = \"clipboardText\";\n // all \"copy\" buttons whose target selector is a element\n const elements = document.querySelectorAll(\n 'button[data-clipboard-target$=\"code\"]'\n );\n const observer = new IntersectionObserver((entries) => {\n entries.forEach((entry) => {\n // target in the viewport that have not been patched\n if (\n entry.intersectionRatio > 0 &&\n entry.target.dataset[attr] === undefined\n ) {\n entry.target.dataset[attr] = cleanupClipboardText(\n entry.target.dataset.clipboardTarget\n );\n }\n });\n });\n\n elements.forEach((elt) => {\n observer.observe(elt);\n });\n}\n\n// Using the document$ observable is particularly important if you are using instant loading since\n// it will not result in a page refresh in the browser\n// See `How to integrate with third-party JavaScript libraries` guideline:\n// https://squidfunk.github.io/mkdocs-material/customization/?h=javascript#additional-javascript\ndocument$.subscribe(function () {\n setCopyText();\n});\n\n// Use client-side redirects for anchors that have moved.\n// Other redirects should use `redirect_maps` in the `mkdocs.yml` file instead.\n(function () {\n // (there are no redirects yet)\n let redirect_maps = {};\n\n // The prefix for the site, see `site_dir` in `mkdocs.yml`\n let site_dir = \"ty\";\n\n function get_path() {\n var path = window.location.pathname;\n\n // Trim the site prefix\n if (path.startsWith(\"/\" + site_dir + \"/\")) {\n path = path.slice(site_dir.length + 2);\n }\n\n // Always include a trailing `/`\n if (!path.endsWith(\"/\")) {\n path = path + \"/\";\n }\n\n // Check for an anchor\n var anchor = window.location.hash.substring(1);\n if (!anchor) {\n return path;\n }\n\n return path + \"#\" + anchor;\n }\n\n let path = get_path();\n if (path && redirect_maps.hasOwnProperty(path)) {\n window.location.replace(\"/\" + site_dir + \"/\" + redirect_maps[path]);\n }\n})();\n"
},
{
"path": "docs/modules.md",
"content": "# Module discovery\n\n## First-party modules\n\nFirst-party modules are Python files that are part of your project source code.\n\nBy default, ty searches for first-party modules in the project's root directory or the `src`\ndirectory, if present.\n\nIf your project uses a different layout, configure the project's\n[`environment.root`](./reference/configuration.md#root) in your `pyproject.toml` or `ty.toml`. For example,\nif your project's code is in an `app/` directory:\n\n```text\nexample-pkg\n├── README.md\n├── pyproject.toml\n└── app\n └── example_pkg\n └── __init__.py\n```\n\nthen set [`environment.root`](./reference/configuration.md#root) in your `pyproject.toml` to `[\"./app\"]`:\n\n```toml title=\"pyproject.toml\"\n[tool.ty.environment]\nroot = [\"./app\"]\n```\n\nNote that a `./python` folder is automatically added to the project `root` if it exists,\nand is not itself a package (i.e. does not contain an `__init__.py` file or an\n`__init__.pyi` file).\n\n## Third-party modules\n\nThird-party modules are Python packages that are not part of your project or the standard library.\nThese are usually declared as dependencies in a `pyproject.toml` or `requirements.txt` file\nand installed using a package manager like uv or pip. Examples of popular third-party\nmodules are `requests`, `numpy` and `django`.\n\nty searches for third-party modules in the configured [Python environment](#python-environment).\n\n## Python environment\n\nThe Python environment is used for discovery of third-party modules.\n\nBy default, ty will attempt to discover a virtual environment.\n\nFirst, ty checks for an active virtual environment using the `VIRTUAL_ENV` environment variable. If\nnot set, ty will search for a `.venv` directory in the project root or working directory. ty only\nsupports discovery of virtual environments at this time.\n\n!!! note\n\n When using project management tools, such as uv or Poetry, the `run` command usually automatically\n activates the virtual environment and will be detected by ty.\n\nThe Python environment may be explicitly configured using the\n[`environment.python`](./reference/configuration.md#python) setting or\n[`--python`](./reference/cli.md#ty-check--python) flag.\n\nWhen setting the environment explicitly, non-virtual environments can be provided.\n"
},
{
"path": "docs/python-version.md",
"content": "# Python version\n\nThe Python version affects allowed syntax, type definitions of the standard library, and type\ndefinitions of first- and third-party modules that are conditional on the Python version.\n\nFor example, Python 3.10 introduced support for `match` statements and added the\n`sys.stdlib_module_names` symbol to the standard library. Syntactic features always\nneed to be available in the lowest supported Python version, but symbols may be used\nin a `sys.version_info` conditional branch:\n\n```python\nimport sys\n\n# `invalid-syntax` error if `python-version` is set to 3.9 or lower:\nmatch \"echo hello\".split():\n case [\"echo\", message]:\n print(message)\n case _:\n print(\"unknown command\")\n\n# `unresolved-attribute` error if `python-version` is set to 3.9 or lower:\nprint(sys.stdlib_module_names)\n\nif sys.version_info >= (3, 10):\n # ok, because the usage is guarded by a version check:\n print(sys.stdlib_module_names)\n```\n\nBy default, the lower bound of the project's [`requires-python`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#python-requires) field (from the `pyproject.toml`) is\nused as the target Python version, ensuring that features and symbols only available in newer Python\nversions are not used.\n\nIf the `requires-python` field is not available but a virtual environment *has* been\nconfigured or detected, ty will try to infer the Python version being used from the virtual\nenvironment's metadata.\n\nIf no virtual environment is present or inferring the Python version from the metadata fails,\nty will fall back to the latest stable Python version supported by ty (currently 3.14).\n\nThe Python version may also be explicitly specified using the\n[`python-version`](./reference/configuration.md#python-version) setting or the\n[`--python-version`](./reference/cli.md#ty-check--python-version) flag.\n"
},
{
"path": "docs/reference/cli.md",
"content": "\n\n# CLI Reference\n\n## ty\n\nAn extremely fast Python type checker.\n\nUsage
\n\n```\nty \n```\n\nCommands
\n\nty checkCheck a project for type errors
ty serverStart the language server
ty versionDisplay ty's version
ty explainExplain rules and other parts of ty
ty helpPrint this message or the help of the given subcommand(s)
\n\n## ty check\n\nCheck a project for type errors\n\nUsage
\n\n```\nty check [OPTIONS] [PATH]...\n```\n\nArguments
\n\nPATHSList of files or directories to check [default: the project root]
\n
\n\nOptions
\n\n--add-ignoreAdds ty: ignore comments to suppress all rule diagnostics
\n--color whenControl when colored output is used
\nPossible values:
\n\nauto: Display colors if the output goes to an interactive terminalalways: Always display colorsnever: Never display colors
--config, -c config-optionA TOML <KEY> = <VALUE> pair (such as you might find in a ty.toml configuration file)\noverriding a specific configuration option.
\nOverrides of individual settings using this option always take precedence\nover all configuration files.
\n--config-file pathThe path to a ty.toml file to use for configuration.
\nWhile ty configuration can be included in a pyproject.toml file, it is not allowed in this context.
\nMay also be set with the TY_CONFIG_FILE environment variable.
--error ruleTreat the given rule as having severity 'error'. Can be specified multiple times. Use 'all' to apply to all rules.
\n--error-on-warningUse exit code 1 if there are any warning-level diagnostics
\n--exclude excludeGlob patterns for files to exclude from type checking.
\nUses gitignore-style syntax to exclude files and directories from type checking. Supports patterns like tests/, *.tmp, **/__pycache__/**.
\n--exit-zeroAlways use exit code 0, even when there are error-level diagnostics
\n--extra-search-path pathAdditional path to use as a module-resolution source (can be passed multiple times).
\nThis is an advanced option that should usually only be used for first-party or third-party modules that are not installed into your Python environment in a conventional way. Use --python to point ty to your Python environment if it is in an unusual location.
\n--force-excludeEnforce exclusions, even for paths passed to ty directly on the command-line. Use --no-force-exclude to disable
\n--help, -hPrint help (see a summary with '-h')
\n--ignore ruleDisables the rule. Can be specified multiple times. Use 'all' to apply to all rules.
\n--no-progressHide all progress outputs.
\nFor example, spinners or progress bars.
\n--output-format output-formatThe format to use for printing diagnostic messages
\nMay also be set with the TY_OUTPUT_FORMAT environment variable.
Possible values:
\n\nfull: Print diagnostics verbosely, with context and helpful hints (default)concise: Print diagnostics concisely, one per linegitlab: Print diagnostics in the JSON format expected by GitLab Code Quality reportsgithub: Print diagnostics in the format used by GitHub Actions workflow error annotationsjunit: Print diagnostics as a JUnit-style XML report
--project projectRun the command within the given project directory.
\nAll pyproject.toml files will be discovered by walking up the directory tree from the given project directory, as will the project's virtual environment (.venv) unless the venv-path option is set.
\nOther command-line arguments (such as relative paths) will be resolved relative to the current working directory.
\n--python, --venv pathPath to your project's Python environment or interpreter.
\nty uses your Python environment to resolve third-party imports in your code.
\nThis can be a path to:
\n\n- A Python interpreter, e.g.
.venv/bin/python3 - A virtual environment directory, e.g. .venv - A system Python sys.prefix directory, e.g. /usr \n
\nIf you're using a project management tool such as uv or you have an activated Conda or virtual environment, you should not generally need to specify this option.
\n\n--python-platform, --platform platformTarget platform to assume when resolving types.
\nThis is used to specialize the type of sys.platform and will affect the visibility of platform-specific functions and attributes. If the value is set to all, no assumptions are made about the target platform. If unspecified, the current system's platform will be used.
\n--python-version, --target-version versionPython version to assume when resolving types.
\nThe Python version affects allowed syntax, type definitions of the standard library, and type definitions of first- and third-party modules that are conditional on the Python version.
\nIf a version is not specified on the command line or in a configuration file, ty will try the following techniques in order of preference to determine a value: 1. Check for the project.requires-python setting in a pyproject.toml file and use the minimum version from the specified range 2. Check for an activated or configured Python environment and attempt to infer the Python version of that environment 3. Fall back to the latest stable Python version supported by ty (see ty check --help output)
\nPossible values:
\n\n3.73.83.93.103.113.123.133.143.15
--quiet, -qUse quiet output (or -qq for silent output)
\n--respect-ignore-filesRespect file exclusions via .gitignore and other standard ignore files. Use --no-respect-ignore-files to disable
\n--typeshed, --custom-typeshed-dir pathCustom directory to use for stdlib typeshed stubs
\n--verbose, -vUse verbose output (or -vv and -vvv for more verbose output)
\n--warn ruleTreat the given rule as having severity 'warn'. Can be specified multiple times. Use 'all' to apply to all rules.
\n--watch, -WWatch files for changes and recheck files related to the changed files
\n
\n\n## ty server\n\nStart the language server\n\nUsage
\n\n```\nty server\n```\n\nOptions
\n\n--help, -hPrint help
\n
\n\n## ty version\n\nDisplay ty's version\n\nUsage
\n\n```\nty version [OPTIONS]\n```\n\nOptions
\n\n--help, -hPrint help
\n--output-format output-formatThe format in which to display the version information
\n[default: text]
Possible values:
\n\ntextjson
\n\n## ty generate-shell-completion\n\nGenerate shell completion\n\nUsage
\n\n```\nty generate-shell-completion \n```\n\nArguments
\n\n\n\nOptions
\n\n--help, -hPrint help
\n
\n\n## ty explain\n\nExplain rules and other parts of ty\n\nUsage
\n\n```\nty explain \n```\n\nCommands
\n\nty explain ruleExplain a rule (or all rules)
ty explain helpPrint this message or the help of the given subcommand(s)
\n\n### ty explain rule\n\nExplain a rule (or all rules)\n\nUsage
\n\n```\nty explain rule [OPTIONS] [RULE]\n```\n\nArguments
\n\nRULERule to explain
\nDefaults to all rules if omitted.
\n
\n\nOptions
\n\n--help, -hPrint help (see a summary with '-h')
\n--output-format output-formatOutput format
\n[default: text]
Possible values:
\n\ntextjson
\n\n### ty explain help\n\nPrint this message or the help of the given subcommand(s)\n\nUsage
\n\n```\nty explain help [COMMAND]\n```\n\n## ty help\n\nPrint this message or the help of the given subcommand(s)\n\nUsage
\n\n```\nty help [COMMAND]\n```\n\n"
},
{
"path": "docs/reference/configuration.md",
"content": "\n\n# Configuration\n## `rules`\n\nConfigures the enabled rules and their severity.\n\nThe keys are either rule names or `all` to set a default severity for all rules.\nSee [the rules documentation](https://ty.dev/rules) for a list of all available rules.\n\nValid severities are:\n\n* `ignore`: Disable the rule.\n* `warn`: Enable the rule and create a warning diagnostic.\n* `error`: Enable the rule and create an error diagnostic.\n ty will exit with a non-zero code if any error diagnostics are emitted.\n\n**Default value**: `{...}`\n\n**Type**: `dict[RuleName | \"all\", \"ignore\" | \"warn\" | \"error\"]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.rules]\n possibly-unresolved-reference = \"warn\"\n division-by-zero = \"ignore\"\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [rules]\n possibly-unresolved-reference = \"warn\"\n division-by-zero = \"ignore\"\n ```\n\n---\n\n## `analysis`\n\n### `allowed-unresolved-imports`\n\nA list of module glob patterns for which `unresolved-import` diagnostics should be suppressed.\n\nDetails on supported glob patterns:\n- `*` matches zero or more characters except `.`. For example, `foo.*` matches `foo.bar` but\n not `foo.bar.baz`; `foo*` matches `foo` and `foobar` but not `foo.bar` or `barfoo`; and `*foo`\n matches `foo` and `barfoo` but not `foo.bar` or `foobar`.\n- `**` matches any number of module components (e.g., `foo.**` matches `foo`, `foo.bar`, etc.)\n- Prefix a pattern with `!` to exclude matching modules\n\nWhen multiple patterns match, later entries take precedence.\n\nGlob patterns can be used in combinations with each other. For example, to suppress errors for\nany module where the first component contains the substring `test`, use `*test*.**`.\n\n**Default value**: `[]`\n\n**Type**: `list[str]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.analysis]\n # Suppress errors for all `test` modules except `test.foo`\n allowed-unresolved-imports = [\"test.**\", \"!test.foo\"]\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [analysis]\n # Suppress errors for all `test` modules except `test.foo`\n allowed-unresolved-imports = [\"test.**\", \"!test.foo\"]\n ```\n\n---\n\n### `replace-imports-with-any`\n\nA list of module glob patterns whose imports should be replaced with `typing.Any`.\n\nUnlike `allowed-unresolved-imports`, this setting replaces the module's type information\nwith `typing.Any` even if the module can be resolved. Import diagnostics are\nunconditionally suppressed for matching modules.\n\n- Prefix a pattern with `!` to exclude matching modules\n\nWhen multiple patterns match, later entries take precedence.\n\nGlob patterns can be used in combinations with each other. For example, to suppress errors for\nany module where the first component contains the substring `test`, use `*test*.**`.\n\nWhen multiple patterns match, later entries take precedence.\n\n**Default value**: `[]`\n\n**Type**: `list[str]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.analysis]\n # Replace all pandas and numpy imports with Any\n replace-imports-with-any = [\"pandas.**\", \"numpy.**\"]\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [analysis]\n # Replace all pandas and numpy imports with Any\n replace-imports-with-any = [\"pandas.**\", \"numpy.**\"]\n ```\n\n---\n\n### `respect-type-ignore-comments`\n\nWhether ty should respect `type: ignore` comments.\n\nWhen set to `false`, `type: ignore` comments are treated like any other normal\ncomment and can't be used to suppress ty errors (you have to use `ty: ignore` instead).\n\nSetting this option can be useful when using ty alongside other type checkers or when\nyou prefer using `ty: ignore` over `type: ignore`.\n\nDefaults to `true`.\n\n**Default value**: `true`\n\n**Type**: `bool`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.analysis]\n # Disable support for `type: ignore` comments\n respect-type-ignore-comments = false\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [analysis]\n # Disable support for `type: ignore` comments\n respect-type-ignore-comments = false\n ```\n\n---\n\n## `environment`\n\n### `extra-paths`\n\nUser-provided paths that should take first priority in module resolution.\n\nThis is an advanced option that should usually only be used for first-party or third-party\nmodules that are not installed into your Python environment in a conventional way.\nUse the `python` option to specify the location of your Python environment.\n\nThis option is similar to mypy's `MYPYPATH` environment variable and pyright's `stubPath`\nconfiguration setting.\n\n**Default value**: `[]`\n\n**Type**: `list[str]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.environment]\n extra-paths = [\"./shared/my-search-path\"]\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [environment]\n extra-paths = [\"./shared/my-search-path\"]\n ```\n\n---\n\n### `python`\n\nPath to your project's Python environment or interpreter.\n\nty uses the `site-packages` directory of your project's Python environment\nto resolve third-party (and, in some cases, first-party) imports in your code.\n\nThis can be a path to:\n\n- A Python interpreter, e.g. `.venv/bin/python3`\n- A virtual environment directory, e.g. `.venv`\n- A system Python [`sys.prefix`] directory, e.g. `/usr`\n\nIf you're using a project management tool such as uv, you should not generally need to\nspecify this option, as commands such as `uv run` will set the `VIRTUAL_ENV` environment\nvariable to point to your project's virtual environment. ty can also infer the location of\nyour environment from an activated Conda environment, and will look for a `.venv` directory\nin the project root if none of the above apply. Failing that, ty will look for a `python3`\nor `python` binary available in `PATH`.\n\n[`sys.prefix`]: https://docs.python.org/3/library/sys.html#sys.prefix\n\n**Default value**: `null`\n\n**Type**: `str`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.environment]\n python = \"./custom-venv-location/.venv\"\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [environment]\n python = \"./custom-venv-location/.venv\"\n ```\n\n---\n\n### `python-platform`\n\nSpecifies the target platform that will be used to analyze the source code.\nIf specified, ty will understand conditions based on comparisons with `sys.platform`, such\nas are commonly found in typeshed to reflect the differing contents of the standard library across platforms.\nIf `all` is specified, ty will assume that the source code can run on any platform.\n\nIf no platform is specified, ty will use the current platform:\n- `win32` for Windows\n- `darwin` for macOS\n- `android` for Android\n- `ios` for iOS\n- `linux` for everything else\n\n**Default value**: ``\n\n**Type**: `\"win32\" | \"darwin\" | \"android\" | \"ios\" | \"linux\" | \"all\" | str`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.environment]\n # Tailor type stubs and conditionalized type definitions to windows.\n python-platform = \"win32\"\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [environment]\n # Tailor type stubs and conditionalized type definitions to windows.\n python-platform = \"win32\"\n ```\n\n---\n\n### `python-version`\n\nSpecifies the version of Python that will be used to analyze the source code.\nThe version should be specified as a string in the format `M.m` where `M` is the major version\nand `m` is the minor (e.g. `\"3.0\"` or `\"3.6\"`).\nIf a version is provided, ty will generate errors if the source code makes use of language features\nthat are not supported in that version.\n\nIf a version is not specified, ty will try the following techniques in order of preference\nto determine a value:\n1. Check for the `project.requires-python` setting in a `pyproject.toml` file\n and use the minimum version from the specified range\n2. Check for an activated or configured Python environment\n and attempt to infer the Python version of that environment\n3. Fall back to the default value (see below)\n\nFor some language features, ty can also understand conditionals based on comparisons\nwith `sys.version_info`. These are commonly found in typeshed, for example,\nto reflect the differing contents of the standard library across Python versions.\n\n**Default value**: `\"3.14\"`\n\n**Type**: `\"3.7\" | \"3.8\" | \"3.9\" | \"3.10\" | \"3.11\" | \"3.12\" | \"3.13\" | \"3.14\" | .`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.environment]\n python-version = \"3.12\"\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [environment]\n python-version = \"3.12\"\n ```\n\n---\n\n### `root`\n\nThe root paths of the project, used for finding first-party modules.\n\nAccepts a list of directory paths searched in priority order (first has highest priority).\n\nIf left unspecified, ty will try to detect common project layouts and initialize `root` accordingly.\nThe project root (`.`) is always included. Additionally, the following directories are included\nif they exist and are not packages (i.e. they do not contain `__init__.py` or `__init__.pyi` files):\n\n* `./src`\n* `./` (if a `.//` directory exists)\n* `./python`\n\n**Default value**: `null`\n\n**Type**: `list[str]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.environment]\n # Multiple directories (priority order)\n root = [\"./src\", \"./lib\", \"./vendor\"]\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [environment]\n # Multiple directories (priority order)\n root = [\"./src\", \"./lib\", \"./vendor\"]\n ```\n\n---\n\n### `typeshed`\n\nOptional path to a \"typeshed\" directory on disk for us to use for standard-library types.\nIf this is not provided, we will fallback to our vendored typeshed stubs for the stdlib,\nbundled as a zip file in the binary\n\n**Default value**: `null`\n\n**Type**: `str`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.environment]\n typeshed = \"/path/to/custom/typeshed\"\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [environment]\n typeshed = \"/path/to/custom/typeshed\"\n ```\n\n---\n\n## `overrides`\n\nConfiguration override that applies to specific files based on glob patterns.\n\nAn override allows you to apply different rule configurations to specific\nfiles or directories. Multiple overrides can match the same file, with\nlater overrides take precedence. Override rules take precedence over global\nrules for matching files.\n\nFor example, to relax enforcement of rules in test files:\n\n```toml\n[[tool.ty.overrides]]\ninclude = [\"tests/**\", \"**/test_*.py\"]\n\n[tool.ty.overrides.rules]\npossibly-unresolved-reference = \"warn\"\n```\n\nOr, to ignore a rule in generated files but retain enforcement in an important file:\n\n```toml\n[[tool.ty.overrides]]\ninclude = [\"generated/**\"]\nexclude = [\"generated/important.py\"]\n\n[tool.ty.overrides.rules]\npossibly-unresolved-reference = \"ignore\"\n```\n\n\n### `exclude`\n\nA list of file and directory patterns to exclude from this override.\n\nPatterns follow a syntax similar to `.gitignore`.\nExclude patterns take precedence over include patterns within the same override.\n\nIf not specified, defaults to `[]` (excludes no files).\n\n**Default value**: `null`\n\n**Type**: `list[str]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [[tool.ty.overrides]]\n exclude = [\n \"generated\",\n \"*.proto\",\n \"tests/fixtures/**\",\n \"!tests/fixtures/important.py\" # Include this one file\n ]\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [[overrides]]\n exclude = [\n \"generated\",\n \"*.proto\",\n \"tests/fixtures/**\",\n \"!tests/fixtures/important.py\" # Include this one file\n ]\n ```\n\n---\n\n### `include`\n\nA list of file and directory patterns to include for this override.\n\nThe `include` option follows a similar syntax to `.gitignore` but reversed:\nIncluding a file or directory will make it so that it (and its contents)\nare affected by this override.\n\nIf not specified, defaults to `[\"**\"]` (matches all files).\n\n**Default value**: `null`\n\n**Type**: `list[str]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [[tool.ty.overrides]]\n include = [\n \"src\",\n \"tests\",\n ]\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [[overrides]]\n include = [\n \"src\",\n \"tests\",\n ]\n ```\n\n---\n\n### `rules`\n\nRule overrides for files matching the include/exclude patterns.\n\nThese rules will be merged with the global rules, with override rules\ntaking precedence for matching files. You can set rules to different\nseverity levels or disable them entirely.\n\n**Default value**: `{...}`\n\n**Type**: `dict[RuleName | \"all\", \"ignore\" | \"warn\" | \"error\"]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [[tool.ty.overrides]]\n include = [\"src\"]\n\n [tool.ty.overrides.rules]\n possibly-unresolved-reference = \"ignore\"\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [[overrides]]\n include = [\"src\"]\n\n [overrides.rules]\n possibly-unresolved-reference = \"ignore\"\n ```\n\n---\n\n## `overrides.analysis`\n\n#### `allowed-unresolved-imports`\n\nA list of module glob patterns for which `unresolved-import` diagnostics should be suppressed.\n\nDetails on supported glob patterns:\n- `*` matches zero or more characters except `.`. For example, `foo.*` matches `foo.bar` but\n not `foo.bar.baz`; `foo*` matches `foo` and `foobar` but not `foo.bar` or `barfoo`; and `*foo`\n matches `foo` and `barfoo` but not `foo.bar` or `foobar`.\n- `**` matches any number of module components (e.g., `foo.**` matches `foo`, `foo.bar`, etc.)\n- Prefix a pattern with `!` to exclude matching modules\n\nWhen multiple patterns match, later entries take precedence.\n\nGlob patterns can be used in combinations with each other. For example, to suppress errors for\nany module where the first component contains the substring `test`, use `*test*.**`.\n\n**Default value**: `[]`\n\n**Type**: `list[str]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.overrides.analysis]\n # Suppress errors for all `test` modules except `test.foo`\n allowed-unresolved-imports = [\"test.**\", \"!test.foo\"]\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [overrides.analysis]\n # Suppress errors for all `test` modules except `test.foo`\n allowed-unresolved-imports = [\"test.**\", \"!test.foo\"]\n ```\n\n---\n\n#### `replace-imports-with-any`\n\nA list of module glob patterns whose imports should be replaced with `typing.Any`.\n\nUnlike `allowed-unresolved-imports`, this setting replaces the module's type information\nwith `typing.Any` even if the module can be resolved. Import diagnostics are\nunconditionally suppressed for matching modules.\n\n- Prefix a pattern with `!` to exclude matching modules\n\nWhen multiple patterns match, later entries take precedence.\n\nGlob patterns can be used in combinations with each other. For example, to suppress errors for\nany module where the first component contains the substring `test`, use `*test*.**`.\n\nWhen multiple patterns match, later entries take precedence.\n\n**Default value**: `[]`\n\n**Type**: `list[str]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.overrides.analysis]\n # Replace all pandas and numpy imports with Any\n replace-imports-with-any = [\"pandas.**\", \"numpy.**\"]\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [overrides.analysis]\n # Replace all pandas and numpy imports with Any\n replace-imports-with-any = [\"pandas.**\", \"numpy.**\"]\n ```\n\n---\n\n#### `respect-type-ignore-comments`\n\nWhether ty should respect `type: ignore` comments.\n\nWhen set to `false`, `type: ignore` comments are treated like any other normal\ncomment and can't be used to suppress ty errors (you have to use `ty: ignore` instead).\n\nSetting this option can be useful when using ty alongside other type checkers or when\nyou prefer using `ty: ignore` over `type: ignore`.\n\nDefaults to `true`.\n\n**Default value**: `true`\n\n**Type**: `bool`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.overrides.analysis]\n # Disable support for `type: ignore` comments\n respect-type-ignore-comments = false\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [overrides.analysis]\n # Disable support for `type: ignore` comments\n respect-type-ignore-comments = false\n ```\n\n---\n\n## `src`\n\n### `exclude`\n\nA list of file and directory patterns to exclude from type checking.\n\nPatterns follow a syntax similar to `.gitignore`:\n\n- `./src/` matches only a directory\n- `./src` matches both files and directories\n- `src` matches files or directories named `src`\n- `*` matches any (possibly empty) sequence of characters (except `/`).\n- `**` matches zero or more path components.\n This sequence **must** form a single path component, so both `**a` and `b**` are invalid and will result in an error.\n A sequence of more than two consecutive `*` characters is also invalid.\n- `?` matches any single character except `/`\n- `[abc]` matches any character inside the brackets. Character sequences can also specify ranges of characters, as ordered by Unicode,\n so e.g. `[0-9]` specifies any character between `0` and `9` inclusive. An unclosed bracket is invalid.\n- `!pattern` negates a pattern (undoes the exclusion of files that would otherwise be excluded)\n\nAll paths are anchored relative to the project root (`src` only\nmatches `/src` and not `/test/src`).\nTo exclude any directory or file named `src`, use `**/src` instead.\n\nBy default, ty excludes commonly ignored directories:\n\n- `**/.bzr/`\n- `**/.direnv/`\n- `**/.eggs/`\n- `**/.git/`\n- `**/.git-rewrite/`\n- `**/.hg/`\n- `**/.mypy_cache/`\n- `**/.nox/`\n- `**/.pants.d/`\n- `**/.pytype/`\n- `**/.ruff_cache/`\n- `**/.svn/`\n- `**/.tox/`\n- `**/.venv/`\n- `**/__pypackages__/`\n- `**/_build/`\n- `**/buck-out/`\n- `**/dist/`\n- `**/node_modules/`\n- `**/venv/`\n\nYou can override any default exclude by using a negated pattern. For example,\nto re-include `dist` use `exclude = [\"!dist\"]`\n\n**Default value**: `null`\n\n**Type**: `list[str]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.src]\n exclude = [\n \"generated\",\n \"*.proto\",\n \"tests/fixtures/**\",\n \"!tests/fixtures/important.py\" # Include this one file\n ]\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [src]\n exclude = [\n \"generated\",\n \"*.proto\",\n \"tests/fixtures/**\",\n \"!tests/fixtures/important.py\" # Include this one file\n ]\n ```\n\n---\n\n### `include`\n\nA list of files and directories to check. The `include` option\nfollows a similar syntax to `.gitignore` but reversed:\nIncluding a file or directory will make it so that it (and its contents)\nare type checked.\n\n- `./src/` matches only a directory\n- `./src` matches both files and directories\n- `src` matches a file or directory named `src`\n- `*` matches any (possibly empty) sequence of characters (except `/`).\n- `**` matches zero or more path components.\n This sequence **must** form a single path component, so both `**a` and `b**` are invalid and will result in an error.\n A sequence of more than two consecutive `*` characters is also invalid.\n- `?` matches any single character except `/`\n- `[abc]` matches any character inside the brackets. Character sequences can also specify ranges of characters, as ordered by Unicode,\n so e.g. `[0-9]` specifies any character between `0` and `9` inclusive. An unclosed bracket is invalid.\n\nAll paths are anchored relative to the project root (`src` only\nmatches `/src` and not `/test/src`).\n\n`exclude` takes precedence over `include`.\n\n**Default value**: `null`\n\n**Type**: `list[str]`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.src]\n include = [\n \"src\",\n \"tests\",\n ]\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [src]\n include = [\n \"src\",\n \"tests\",\n ]\n ```\n\n---\n\n### `respect-ignore-files`\n\nWhether to automatically exclude files that are ignored by `.ignore`,\n`.gitignore`, `.git/info/exclude`, and global `gitignore` files.\nEnabled by default.\n\n**Default value**: `true`\n\n**Type**: `bool`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.src]\n respect-ignore-files = false\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [src]\n respect-ignore-files = false\n ```\n\n---\n\n### `root`\n\n!!! warning \"Deprecated\"\n This option has been deprecated. Use `environment.root` instead.\n\nThe root of the project, used for finding first-party modules.\n\nIf left unspecified, ty will try to detect common project layouts and initialize `src.root` accordingly.\nThe project root (`.`) is always included. Additionally, the following directories are included\nif they exist and are not packages (i.e. they do not contain `__init__.py` or `__init__.pyi` files):\n\n* `./src`\n* `./` (if a `.//` directory exists)\n* `./python`\n\n**Default value**: `null`\n\n**Type**: `str`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.src]\n root = \"./app\"\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [src]\n root = \"./app\"\n ```\n\n---\n\n## `terminal`\n\n### `error-on-warning`\n\nUse exit code 1 if there are any warning-level diagnostics.\n\nDefaults to `false`.\n\n**Default value**: `false`\n\n**Type**: `bool`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.terminal]\n # Error if ty emits any warning-level diagnostics.\n error-on-warning = true\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [terminal]\n # Error if ty emits any warning-level diagnostics.\n error-on-warning = true\n ```\n\n---\n\n### `output-format`\n\nThe format to use for printing diagnostic messages.\n\nDefaults to `full`.\n\n**Default value**: `full`\n\n**Type**: `full | concise | github | gitlab | junit`\n\n**Example usage**:\n\n=== \"pyproject.toml\"\n\n ```toml\n [tool.ty.terminal]\n output-format = \"concise\"\n ```\n\n=== \"ty.toml\"\n\n ```toml\n [terminal]\n output-format = \"concise\"\n ```\n\n---\n\n"
},
{
"path": "docs/reference/editor-settings.md",
"content": "# Editor settings\n\nThe editor settings supported by ty's language server, as well as the settings specific to [ty's VS\nCode extension][ty-vscode].\n\n## `configuration`\n\nIn-editor configuration of ty's settings. The inline settings always take precedence over the settings from configuration files,\nincluding the configuration specified with [`configurationFile`](#configurationfile).\n\nConsult [the configuration reference](../configuration.md) for a list of all supported configuration options.\n\n**Default value**: `null`\n\n**Type**: `object`\n\n**Example usage**:\n\n=== \"VS Code\"\n\n ```json\n {\n \"ty.configuration\": {\n \"rules\": {\n \"unresolved-reference\": \"warn\"\n }\n }\n }\n ```\n\n=== \"Neovim\"\n\n ```lua\n -- Neovim >=0.11:\n vim.lsp.config('ty', {\n settings = {\n ty = {\n configuration = {\n rules = {\n [\"unresolved-reference\"] = \"warn\"\n }\n }\n },\n },\n })\n\n -- Neovim <0.11:\n require('lspconfig').ty.setup({\n settings = {\n ty = {\n configuration = {\n rules = {\n [\"unresolved-reference\"] = \"warn\"\n }\n }\n },\n },\n })\n ```\n\n=== \"Zed\"\n\n ```json\n {\n \"lsp\": {\n \"ty\": {\n \"settings\": {\n \"configuration\": {\n \"rules\": {\n \"unresolved-reference\": \"warn\"\n }\n }\n }\n }\n }\n }\n ```\n\n## `configurationFile`\n\nThe path to a `ty.toml` configuration file. ty will use the specified configuration over any automatically discovered configuration.\nty will expand a tilde `~` at the start of a string to the user's home directory, as well as variables like `$A` or `${A}`.\n\n!!! info\n\n While ty configuration can be included in a `pyproject.toml` file, it is not allowed in this context.\n\n**Default value**: `null`\n\n**Type**: `string`\n\n**Example usage**:\n\n=== \"VS Code\"\n\n ```json\n {\n \"ty.configurationFile\": \"./.config/ty.toml\"\n }\n ```\n\n=== \"Neovim\"\n\n ```lua\n -- Neovim >=0.11:\n vim.lsp.config('ty', {\n settings = {\n ty = {\n configurationFile = \"./.config/ty.toml\"\n },\n },\n })\n\n -- Neovim <0.11:\n require('lspconfig').ty.setup({\n settings = {\n ty = {\n configurationFile = \"./.config/ty.toml\"\n },\n },\n })\n ```\n\n=== \"Zed\"\n\n ```json\n {\n \"lsp\": {\n \"ty\": {\n \"settings\": {\n \"configurationFile\": \"./.config/ty.toml\"\n }\n }\n }\n }\n ```\n\n______________________________________________________________________\n\n## `disableLanguageServices`\n\nWhether to disable the language services for the ty language server like code completion, hover,\ngo to definition, etc.\n\nThis is useful if you want to use ty exclusively for type checking and want to use another language\nserver for features like code completion, hover, go to definition, etc.\n\n**Default value**: `false`\n\n**Type**: `boolean`\n\n**Example usage**:\n\n=== \"VS Code\"\n\n ```json\n {\n \"ty.disableLanguageServices\": true\n }\n ```\n\n=== \"Neovim\"\n\n ```lua\n -- Neovim >=0.11:\n vim.lsp.config('ty', {\n settings = {\n ty = {\n disableLanguageServices = true,\n },\n },\n })\n\n -- Neovim <0.11:\n require('lspconfig').ty.setup({\n settings = {\n ty = {\n disableLanguageServices = true,\n },\n },\n })\n ```\n\n=== \"Zed\"\n\n ```json\n {\n \"lsp\": {\n \"ty\": {\n \"settings\": {\n \"disableLanguageServices\": true\n }\n }\n }\n }\n ```\n\n______________________________________________________________________\n\n## `diagnosticMode`\n\nDetermines the scope of the diagnostics reported by the language server.\n\nSetting this to `off` is useful if you want to use ty exclusively for the language server features\nlike code completion, hover, go to definition, etc.\n\n- `off`: Diagnostics are disabled.\n- `openFilesOnly`: Diagnostics are reported only for files that are currently open in the editor.\n- `workspace`: Diagnostics are reported for all files in the workspace.\n\n**Default value**: `\"openFilesOnly\"`\n\n**Type**: `\"off\" | \"workspace\" | \"openFilesOnly\"`\n\n**Example usage**:\n\n=== \"VS Code\"\n\n ```json\n {\n \"ty.diagnosticMode\": \"workspace\"\n }\n ```\n\n=== \"Neovim\"\n\n ```lua\n -- Neovim >=0.11:\n vim.lsp.config('ty', {\n settings = {\n ty = {\n diagnosticMode = 'workspace',\n },\n },\n })\n\n -- Neovim <0.11:\n require('lspconfig').ty.setup({\n settings = {\n ty = {\n diagnosticMode = 'workspace',\n },\n },\n })\n ```\n\n=== \"Zed\"\n\n ```json\n {\n \"lsp\": {\n \"ty\": {\n \"settings\": {\n \"diagnosticMode\": \"workspace\"\n }\n }\n }\n }\n ```\n\n______________________________________________________________________\n\n## `showSyntaxErrors`\n\nWhether to show syntax error diagnostics.\n\nThis is useful when using ty with other language servers, allowing the user to refer to syntax errors\nfrom only one source.\n\n**Default value**: `true`\n\n**Type**: `bool`\n\n**Example usage**:\n\n=== \"VS Code\"\n\n ```json\n {\n \"ty.showSyntaxErrors\": false\n }\n ```\n\n=== \"Neovim\"\n\n ```lua\n -- Neovim >=0.11:\n vim.lsp.config('ty', {\n settings = {\n ty = {\n showSyntaxErrors = false,\n },\n },\n })\n\n -- Neovim <0.11:\n require('lspconfig').ty.setup({\n settings = {\n ty = {\n showSyntaxErrors = false,\n },\n },\n })\n ```\n\n=== \"Zed\"\n\n ```json\n {\n \"lsp\": {\n \"ty\": {\n \"settings\": {\n \"showSyntaxErrors\": false\n }\n }\n }\n }\n ```\n\n______________________________________________________________________\n\n## `inlayHints`\n\nThese settings control the inline hints that ty provides in an editor.\n\n### `variableTypes`\n\nWhether to show the types of variables as inline hints.\n\n**Default value**: `true`\n\n**Type**: `boolean`\n\n**Example usage**:\n\n=== \"VS Code\"\n\n ```json\n {\n \"ty.inlayHints.variableTypes\": false\n }\n ```\n\n=== \"Neovim\"\n\n ```lua\n -- Neovim >=0.11:\n vim.lsp.config('ty', {\n settings = {\n ty = {\n inlayHints = {\n variableTypes = false,\n },\n },\n },\n })\n\n -- Neovim <0.11:\n require('lspconfig').ty.setup({\n settings = {\n ty = {\n inlayHints = {\n variableTypes = false,\n },\n },\n },\n })\n ```\n\n=== \"Zed\"\n\n ```json\n {\n \"lsp\": {\n \"ty\": {\n \"settings\": {\n \"inlayHints\": {\n \"variableTypes\": false\n }\n }\n }\n }\n }\n ```\n\n### `callArgumentNames`\n\nWhether to show argument names in call expressions as inline hints.\n\n**Default value**: `true`\n\n**Type**: `boolean`\n\n**Example usage**:\n\n=== \"VS Code\"\n\n ```json\n {\n \"ty.inlayHints.callArgumentNames\": false\n }\n ```\n\n=== \"Neovim\"\n\n ```lua\n -- Neovim >=0.11:\n vim.lsp.config('ty', {\n settings = {\n ty = {\n inlayHints = {\n callArgumentNames = false,\n },\n },\n },\n })\n\n -- Neovim <0.11:\n require('lspconfig').ty.setup({\n settings = {\n ty = {\n inlayHints = {\n callArgumentNames = false,\n },\n },\n },\n })\n ```\n\n=== \"Zed\"\n\n ```json\n {\n \"lsp\": {\n \"ty\": {\n \"settings\": {\n \"inlayHints\": {\n \"callArgumentNames\": false\n }\n }\n }\n }\n }\n ```\n\n______________________________________________________________________\n\n## `completions`\n\nThese settings control how code completions offered by ty work.\n\n### `autoImport`\n\nWhether to include auto-import suggestions in code completions. That is, code completions will\ninclude symbols not currently in scope but available in your environment.\n\n**Default value**: `true`\n\n**Type**: `boolean`\n\n**Example usage**:\n\n=== \"VS Code\"\n\n ```json\n {\n \"ty.completions.autoImport\": true\n }\n ```\n\n=== \"Neovim\"\n\n ```lua\n -- Neovim >=0.11:\n vim.lsp.config('ty', {\n settings = {\n ty = {\n completions = {\n autoImport = true,\n },\n },\n },\n })\n\n -- Neovim <0.11:\n require('lspconfig').ty.setup({\n settings = {\n ty = {\n completions = {\n autoImport = true,\n },\n },\n },\n })\n ```\n\n=== \"Zed\"\n\n ```json\n {\n \"lsp\": {\n \"ty\": {\n \"settings\": {\n \"completions\": {\n \"autoImport\": true\n }\n }\n }\n }\n }\n ```\n\n______________________________________________________________________\n\n## VS Code specific\n\nThe following settings are specific to [ty's VS Code extension][ty-vscode].\n\n### `importStrategy`\n\nStrategy for loading the `ty` executable.\n\n- `fromEnvironment` finds ty in the environment, falling back to the bundled version\n- `useBundled` uses the version bundled with the extension\n\n**Default value**: `\"fromEnvironment\"`\n\n**Type**: `\"fromEnvironment\" | \"useBundled\"`\n\n**Example usage**:\n\n```json\n{\n \"ty.importStrategy\": \"useBundled\"\n}\n```\n\n______________________________________________________________________\n\n### `interpreter`\n\nA list of paths to Python interpreters. Even though this is a list, only the first interpreter is\nused.\n\nThe interpreter path is used to find the `ty` executable when\n[`ty.importStrategy`](#importstrategy) is set to `fromEnvironment`.\n\n**Default value**: `[]`\n\n**Type**: `string[]`\n\n**Example usage**:\n\n```json\n{\n \"ty.interpreter\": [\"/home/user/.local/bin/python\"]\n}\n```\n\n______________________________________________________________________\n\n### `path`\n\nA list of path to `ty` executables.\n\nThe extension uses the first executable that exists. This setting takes precedence over the\n[`ty.importStrategy`](#importstrategy) setting.\n\n**Default value**: `[]`\n\n**Type**: `string[]`\n\n**Example usage**:\n\n```json\n{\n \"ty.path\": [\"/home/user/.local/bin/ty\"]\n}\n```\n\n______________________________________________________________________\n\n### `trace.server`\n\nThe detail level at which messages between the language server and the editor (client) are logged.\n\nThis setting is useful for debugging issues with the language server. Refer to the [troubleshooting\nguide](https://github.com/astral-sh/ty-vscode/blob/6cf16b4e87342a49f2bec1310a730cde8229e1d9/TROUBLESHOOTING.md)\nin [ty's VS Code extension][ty-vscode] for more information.\n\n**Default value**: `\"off\"`\n\n**Type**: `\"off\" | \"messages\" | \"verbose\"`\n\n**Example usage**:\n\n```json\n{\n \"ty.trace.server\": \"messages\"\n}\n```\n\n______________________________________________________________________\n\n## Initialization options\n\nThe following settings are required when ty is initialized in an editor. These settings are\nstatic so changing them requires restarting the editor to take effect.\n\nFor VS Code users, these settings are defined in the `ty.*` namespace as usual, but for other\neditors, they would need to be provided in a separate field of the configuration that corresponds to\nthe initialization options. Refer to the examples below for how to set these options in different\neditors.\n\n### `logFile`\n\nPath to the file to which the language server writes its log messages. By default, ty writes log messages to stderr.\n\n**Default value**: `null`\n\n**Type**: `string`\n\n**Example usage**:\n\n=== \"VS Code\"\n\n ```json\n {\n \"ty.logFile\": \"/path/to/ty.log\"\n }\n ```\n\n=== \"Neovim\"\n\n ```lua\n -- Neovim >=0.11:\n vim.lsp.config('ty', {\n init_options = {\n logFile = '/path/to/ty.log',\n },\n })\n\n -- Neovim <0.11:\n require('lspconfig').ty.setup({\n init_options = {\n logFile = '/path/to/ty.log',\n },\n })\n ```\n\n=== \"Zed\"\n\n ```json\n {\n \"lsp\": {\n \"ty\": {\n \"initialization_options\": {\n \"logFile\": \"/path/to/ty.log\"\n }\n }\n }\n }\n ```\n\n______________________________________________________________________\n\n### `logLevel`\n\nThe log level to use for the language server.\n\n**Default value**: `\"info\"`\n\n**Type**: `\"trace\" | \"debug\" | \"info\" | \"warn\" | \"error\"`\n\n**Example usage**:\n\n=== \"VS Code\"\n\n ```json\n {\n \"ty.logLevel\": \"debug\"\n }\n ```\n\n=== \"Neovim\"\n\n ```lua\n -- Neovim >=0.11:\n vim.lsp.config('ty', {\n init_options = {\n logLevel = 'debug',\n },\n })\n\n -- Neovim <0.11:\n require('lspconfig').ty.setup({\n init_options = {\n logLevel = 'debug',\n },\n })\n ```\n\n=== \"Zed\"\n\n ```json\n {\n \"lsp\": {\n \"ty\": {\n \"initialization_options\": {\n \"logLevel\": \"debug\"\n }\n }\n }\n }\n ```\n\n[ty-vscode]: https://marketplace.visualstudio.com/items?itemName=astral-sh.ty\n"
},
{
"path": "docs/reference/environment.md",
"content": "# Environment variables\n\nty defines and respects the following environment variables:\n\n### `TY_CONFIG_FILE`\n\nPath to a `ty.toml` configuration file to use.\n\nWhen set, ty will use this file for configuration instead of\ndiscovering configuration files automatically.\n\nEquivalent to the `--config-file` command-line argument.\n\n### `TY_LOG`\n\nIf set, ty will use this value as the log level for its `--verbose` output.\nAccepts any filter compatible with the `tracing_subscriber` crate.\n\nFor example:\n\n- `TY_LOG=ty=debug` is the equivalent of `-vv` to the command line\n- `TY_LOG=trace` will enable all trace-level logging.\n\nSee the [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax)\nfor more.\n\n### `TY_LOG_PROFILE`\n\nIf set to `\"1\"` or `\"true\"`, ty will enable flamegraph profiling.\nThis creates a `tracing.folded` file that can be used to generate flame graphs\nfor performance analysis.\n\n### `TY_MAX_PARALLELISM`\n\nSpecifies an upper limit for the number of tasks ty is allowed to run in parallel.\n\nFor example, how many files should be checked in parallel.\nThis isn't the same as a thread limit. ty may spawn additional threads\nwhen necessary, e.g. to watch for file system changes or a dedicated UI thread.\n\n### `TY_OUTPUT_FORMAT`\n\nThe format to use for printing diagnostic messages.\n\nWhen set, ty will use this format for output instead of the default.\n\nAccepts the same values as the `--output-format` command-line argument.\n\n## Externally-defined variables\n\nty also reads the following externally defined environment variables:\n\n### `CONDA_DEFAULT_ENV`\n\nUsed to determine the name of the active Conda environment.\n\n### `CONDA_PREFIX`\n\nUsed to detect the path of an active Conda environment.\nIf both `VIRTUAL_ENV` and `CONDA_PREFIX` are present, `VIRTUAL_ENV` will be preferred.\n\n### `PYTHONPATH`\n\nAdds additional directories to ty's search paths.\nThe format is the same as the shell’s PATH:\none or more directory pathnames separated by os appropriate pathsep\n(e.g. colons on Unix or semicolons on Windows).\n\n### `RAYON_NUM_THREADS`\n\nSpecifies an upper limit for the number of threads ty uses when performing work in parallel.\nEquivalent to `TY_MAX_PARALLELISM`.\n\nThis is a standard Rayon environment variable.\n\n### `VIRTUAL_ENV`\n\nUsed to detect an activated virtual environment.\n\n### `XDG_CONFIG_HOME`\n\nPath to user-level configuration directory on Unix systems.\n\n### `_CONDA_ROOT`\n\nUsed to determine the root install path of Conda.\n\n"
},
{
"path": "docs/reference/exit-codes.md",
"content": "# Exit codes\n\nThe ty command line interface uses the following exit codes:\n\n| Exit code | Description |\n| :-------- | :------------------------------------------------------- |\n| `0` | no violations with severity `error` or higher were found |\n| `1` | violations with severity `error` or higher were found |\n| `2` | invalid CLI options, invalid configuration, or IO errors |\n| `101` | internal error |\n\nty supports two command line arguments that change how exit codes work:\n\n- `--exit-zero`: ty will exit with `0` even if violations were found.\n- `--error-on-warning`: ty will exit with `1` if it finds any violations with severity `warning` or\n higher.\n"
},
{
"path": "docs/reference/rules.md",
"content": "\n\n# Rules\n\n## `abstract-method-in-final-class`\n\n\nDefault level: error ·\nAdded in 0.0.13 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for `@final` classes that have unimplemented abstract methods.\n\n**Why is this bad?**\n\nA class decorated with `@final` cannot be subclassed. If such a class has abstract\nmethods that are not implemented, the class can never be properly instantiated, as\nthe abstract methods can never be implemented (since subclassing is prohibited).\n\nAt runtime, instantiation of classes with unimplemented abstract methods is only\nprevented for classes that have `ABCMeta` (or a subclass of it) as their metaclass.\nHowever, type checkers also enforce this for classes that do not use `ABCMeta`, since\nthe intent for the class to be abstract is clear from the use of `@abstractmethod`.\n\n**Example**\n\n\n```python\nfrom abc import ABC, abstractmethod\nfrom typing import final\n\nclass Base(ABC):\n @abstractmethod\n def method(self) -> int: ...\n\n@final\nclass Derived(Base): # Error: `Derived` does not implement `method`\n pass\n```\n\n## `ambiguous-protocol-member`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.20 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for protocol classes with members that will lead to ambiguous interfaces.\n\n**Why is this bad?**\n\nAssigning to an undeclared variable in a protocol class leads to an ambiguous\ninterface which may lead to the type checker inferring unexpected things. It's\nrecommended to ensure that all members of a protocol class are explicitly declared.\n\n**Examples**\n\n\n```py\nfrom typing import Protocol\n\nclass BaseProto(Protocol):\n a: int # fine (explicitly declared as `int`)\n def method_member(self) -> int: ... # fine: a method definition using `def` is considered a declaration\n c = \"some variable\" # error: no explicit declaration, leading to ambiguity\n b = method_member # error: no explicit declaration, leading to ambiguity\n\n # error: this creates implicit assignments of `d` and `e` in the protocol class body.\n # Were they really meant to be considered protocol members?\n for d, e in enumerate(range(42)):\n pass\n\nclass SubProto(BaseProto, Protocol):\n a = 42 # fine (declared in superclass)\n```\n\n## `assert-type-unspellable-subtype`\n\n\nDefault level: error ·\nAdded in 0.0.14 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for `assert_type()` calls where the actual type\nis an unspellable subtype of the asserted type.\n\n**Why is this bad?**\n\n`assert_type()` is intended to ensure that the inferred type of a value\nis exactly the same as the asserted type. But in some situations, ty\nhas nonstandard extensions to the type system that allow it to infer\nmore precise types than can be expressed in user annotations. ty emits a\ndifferent error code to [`type-assertion-failure`](#type-assertion-failure) in these situations so\nthat users can easily differentiate between the two cases.\n\n**Example**\n\n\n```python\ndef _(x: int):\n assert_type(x, int) # fine\n if x:\n assert_type(x, int) # error: [assert-type-unspellable-subtype]\n # the actual type is `int & ~AlwaysFalsy`,\n # which excludes types like `Literal[0]`\n```\n\n## `byte-string-type-annotation`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for byte-strings in type annotation positions.\n\n**Why is this bad?**\n\nStatic analysis tools like ty can't analyze type annotations that use byte-string notation.\n\n**Examples**\n\n```python\ndef test(): -> b\"int\":\n ...\n```\n\nUse instead:\n```python\ndef test(): -> \"int\":\n ...\n```\n\n## `call-abstract-method`\n\n\nDefault level: error ·\nPreview (since 0.0.16) ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for calls to abstract `@classmethod`s or `@staticmethod`s\nwith \"trivial bodies\" when accessed on the class object itself.\n\n\"Trivial bodies\" are bodies that solely consist of `...`, `pass`,\na docstring, and/or `raise NotImplementedError`.\n\n**Why is this bad?**\n\nAn abstract method with a trivial body has no concrete implementation\nto execute, so calling such a method directly on the class will probably\nnot have the desired effect.\n\nIt is also unsound to call these methods directly on the class. Unlike\nother methods, ty permits abstract methods with trivial bodies to have\nnon-`None` return types even though they always return `None` at runtime.\nThis is because it is expected that these methods will always be\noverridden rather than being called directly. As a result of this\nexception to the normal rule, ty may infer an incorrect type if one of\nthese methods is called directly, which may then mean that type errors\nelsewhere in your code go undetected by ty.\n\nCalling abstract classmethods or staticmethods via `type[X]` is allowed,\nsince the actual runtime type could be a concrete subclass with an implementation.\n\n**Example**\n\n```python\nfrom abc import ABC, abstractmethod\n\nclass Foo(ABC):\n @classmethod\n @abstractmethod\n def method(cls) -> int: ...\n\nFoo.method() # Error: cannot call abstract classmethod\n```\n\n## `call-non-callable`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for calls to non-callable objects.\n\n**Why is this bad?**\n\nCalling a non-callable object will raise a `TypeError` at runtime.\n\n**Examples**\n\n```python\n4() # TypeError: 'int' object is not callable\n```\n\n## `call-top-callable`\n\n\nDefault level: error ·\nAdded in 0.0.7 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for calls to objects typed as `Top[Callable[..., T]]` (the infinite union of all\ncallable types with return type `T`).\n\n**Why is this bad?**\n\nWhen an object is narrowed to `Top[Callable[..., object]]` (e.g., via `callable(x)` or\n`isinstance(x, Callable)`), we know the object is callable, but we don't know its\nprecise signature. This type represents the set of all possible callable types\n(including, e.g., functions that take no arguments and functions that require arguments),\nso no specific set of arguments can be guaranteed to be valid.\n\n**Examples**\n\n```python\ndef f(x: object):\n if callable(x):\n x() # error: We know `x` is callable, but not what arguments it accepts\n```\n\n## `conflicting-argument-forms`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks whether an argument is used as both a value and a type form in a call.\n\n**Why is this bad?**\n\nSuch calls have confusing semantics and often indicate a logic error.\n\n**Examples**\n\n```python\nfrom typing import reveal_type\nfrom ty_extensions import is_singleton\n\nif flag:\n f = repr # Expects a value\nelse:\n f = is_singleton # Expects a type form\n\nf(int) # error\n```\n\n## `conflicting-declarations`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks whether a variable has been declared as two conflicting types.\n\n**Why is this bad**\n\nA variable with two conflicting declarations likely indicates a mistake.\nMoreover, it could lead to incorrect or ill-defined type inference for\nother code that relies on these variables.\n\n**Examples**\n\n```python\nif b:\n a: int\nelse:\n a: str\n\na = 1\n```\n\n## `conflicting-metaclass`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for class definitions where the metaclass of the class\nbeing created would not be a subclass of the metaclasses of\nall the class's bases.\n\n**Why is it bad?**\n\nSuch a class definition raises a `TypeError` at runtime.\n\n**Examples**\n\n```python\nclass M1(type): ...\nclass M2(type): ...\nclass A(metaclass=M1): ...\nclass B(metaclass=M2): ...\n\n# TypeError: metaclass conflict\nclass C(A, B): ...\n```\n\n## `cyclic-class-definition`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for class definitions in stub files that inherit\n(directly or indirectly) from themselves.\n\n**Why is it bad?**\n\nAlthough forward references are natively supported in stub files,\ninheritance cycles are still disallowed, as it is impossible to\nresolve a consistent [method resolution order] for a class that\ninherits from itself.\n\n**Examples**\n\n```python\n# foo.pyi\nclass A(B): ...\nclass B(A): ...\n```\n\n[method resolution order]: https://docs.python.org/3/glossary.html#term-method-resolution-order\n\n## `cyclic-type-alias-definition`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.29 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for type alias definitions that (directly or mutually) refer to themselves.\n\n**Why is it bad?**\n\nAlthough it is permitted to define a recursive type alias, it is not meaningful\nto have a type alias whose expansion can only result in itself, and is therefore not allowed.\n\n**Examples**\n\n```python\ntype Itself = Itself\n\ntype A = B\ntype B = A\n```\n\n## `dataclass-field-order`\n\n\nDefault level: error ·\nAdded in 0.0.15 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for dataclass definitions where required fields are defined after\nfields with default values.\n\n**Why is this bad?**\n\nIn dataclasses, all required fields (fields without default values) must be\ndefined before fields with default values. This is a Python requirement that\nwill raise a `TypeError` at runtime if violated.\n\n**Example**\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Example:\n x: int = 1 # Field with default value\n y: str # Error: Required field after field with default\n```\n\n## `deprecated`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.16 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for uses of deprecated items\n\n**Why is this bad?**\n\nDeprecated items should no longer be used.\n\n**Examples**\n\n```python\n@warnings.deprecated(\"use new_func instead\")\ndef old_func(): ...\n\nold_func() # emits [deprecated] diagnostic\n```\n\n## `division-by-zero`\n\n\nDefault level: ignore ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nIt detects division by zero.\n\n**Why is this bad?**\n\nDividing by zero raises a `ZeroDivisionError` at runtime.\n\n**Rule status**\n\nThis rule is currently disabled by default because of the number of\nfalse positives it can produce.\n\n**Examples**\n\n```python\n5 / 0\n```\n\n## `duplicate-base`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for class definitions with duplicate bases.\n\n**Why is this bad?**\n\nClass definitions with duplicate bases raise `TypeError` at runtime.\n\n**Examples**\n\n```python\nclass A: ...\n\n# TypeError: duplicate base class\nclass B(A, A): ...\n```\n\n## `duplicate-kw-only`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.12 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for dataclass definitions with more than one field\nannotated with `KW_ONLY`.\n\n**Why is this bad?**\n\n`dataclasses.KW_ONLY` is a special marker used to\nemulate the `*` syntax in normal signatures.\nIt can only be used once per dataclass.\n\nAttempting to annotate two different fields with\nit will lead to a runtime error.\n\n**Examples**\n\n```python\nfrom dataclasses import dataclass, KW_ONLY\n\n@dataclass\nclass A: # Crash at runtime\n b: int\n _1: KW_ONLY\n c: str\n _2: KW_ONLY\n d: bytes\n```\n\n## `empty-body`\n\n\nDefault level: error ·\nAdded in 0.0.14 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects functions with empty bodies that have a non-`None` return type annotation.\n\nThe errors reported by this rule have the same motivation as the [`invalid-return-type`](#invalid-return-type)\nrule. The diagnostic exists as a separate error code to allow users to disable this\nrule while prototyping code. While we strongly recommend enabling this rule if\npossible, users migrating from other type checkers may also find it useful to\ntemporarily disable this rule on some or all of their codebase if they find it\nresults in a large number of diagnostics.\n\n**Why is this bad?**\n\nA function with an empty body (containing only `...`, `pass`, or a docstring) will\nimplicitly return `None` at runtime. Returning `None` when the return type is non-`None`\nis unsound, and will lead to ty inferring incorrect types elsewhere.\n\nFunctions with empty bodies are permitted in certain contexts where they serve as\ndeclarations rather than implementations:\n\n- Functions in stub files (`.pyi`)\n- Methods in Protocol classes\n- Abstract methods decorated with `@abstractmethod`\n- Overload declarations decorated with `@overload`\n- Functions in `if TYPE_CHECKING` blocks\n\n**Examples**\n\n```python\ndef foo() -> int: ... # error: [empty-body]\n\ndef bar() -> str:\n \"\"\"A function that does nothing.\"\"\"\n pass # error: [empty-body]\n```\n\n## `escape-character-in-forward-annotation`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for forward annotations that contain escape characters.\n\n**Why is this bad?**\n\nStatic analysis tools like ty can't analyze type annotations that contain escape characters.\n\n**Example**\n\n\n```python\ndef foo() -> \"intt\\b\": ...\n```\n\n## `final-on-non-method`\n\n\nDefault level: error ·\nAdded in 0.0.20 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for `@final` decorators applied to non-method functions.\n\n**Why is this bad?**\n\nThe `@final` decorator is only meaningful on methods and classes.\nApplying it to a module-level function or a nested function has no\neffect and is likely a mistake.\n\n**Example**\n\n\n```python\nfrom typing import final\n\n# Error: @final is not allowed on non-method functions\n@final\ndef my_function() -> int:\n return 0\n```\n\n## `final-without-value`\n\n\nDefault level: error ·\nAdded in 0.0.15 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for `Final` symbols that are declared without a value and are never\nassigned a value in their scope.\n\n**Why is this bad?**\n\nA `Final` symbol must be initialized with a value at the time of declaration\nor in a subsequent assignment. At module or function scope, the assignment must\noccur in the same scope. In a class body, the assignment may occur in `__init__`.\n\n**Examples**\n\n```python\nfrom typing import Final\n\n# Error: `Final` symbol without a value\nMY_CONSTANT: Final[int]\n\n# OK: `Final` symbol with a value\nMY_CONSTANT: Final[int] = 1\n```\n\n## `fstring-type-annotation`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for f-strings in type annotation positions.\n\n**Why is this bad?**\n\nStatic analysis tools like ty can't analyze type annotations that use f-string notation.\n\n**Examples**\n\n```python\ndef test(): -> f\"int\":\n ...\n```\n\nUse instead:\n```python\ndef test(): -> \"int\":\n ...\n```\n\n## `ignore-comment-unknown-rule`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for `ty: ignore[code]` where `code` isn't a known lint rule.\n\n**Why is this bad?**\n\nA `ty: ignore[code]` directive with a `code` that doesn't match\nany known rule will not suppress any type errors, and is probably a mistake.\n\n**Examples**\n\n```py\na = 20 / 0 # ty: ignore[division-by-zer]\n```\n\nUse instead:\n\n```py\na = 20 / 0 # ty: ignore[division-by-zero]\n```\n\n## `implicit-concatenated-string-type-annotation`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for implicit concatenated strings in type annotation positions.\n\n**Why is this bad?**\n\nStatic analysis tools like ty can't analyze type annotations that use implicit concatenated strings.\n\n**Examples**\n\n```python\ndef test(): -> \"Literal[\" \"5\" \"]\":\n ...\n```\n\nUse instead:\n```python\ndef test(): -> \"Literal[5]\":\n ...\n```\n\n## `inconsistent-mro`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for classes with an inconsistent [method resolution order] (MRO).\n\n**Why is this bad?**\n\nClasses with an inconsistent MRO will raise a `TypeError` at runtime.\n\n**Examples**\n\n```python\nclass A: ...\nclass B(A): ...\n\n# TypeError: Cannot create a consistent method resolution order\nclass C(A, B): ...\n```\n\n[method resolution order]: https://docs.python.org/3/glossary.html#term-method-resolution-order\n\n## `index-out-of-bounds`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for attempts to use an out of bounds index to get an item from\na container.\n\n**Why is this bad?**\n\nUsing an out of bounds index will raise an `IndexError` at runtime.\n\n**Examples**\n\n```python\nt = (0, 1, 2)\nt[3] # IndexError: tuple index out of range\n```\n\n## `ineffective-final`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.33 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for calls to `final()` that type checkers cannot interpret.\n\n**Why is this bad?**\n\nThe `final()` function is designed to be used as a decorator. When called directly\nas a function (e.g., `final(type(...))`), type checkers will not understand the\napplication of `final` and will not prevent subclassing.\n\n**Example**\n\n\n```python\nfrom typing import final\n\n# Incorrect: type checkers will not prevent subclassing\nMyClass = final(type(\"MyClass\", (), {}))\n\n# Correct: use `final` as a decorator\n@final\nclass MyClass: ...\n```\n\n## `instance-layout-conflict`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.12 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for classes definitions which will fail at runtime due to\n\"instance memory layout conflicts\".\n\nThis error is usually caused by attempting to combine multiple classes\nthat define non-empty `__slots__` in a class's [Method Resolution Order]\n(MRO), or by attempting to combine multiple builtin classes in a class's\nMRO.\n\n**Why is this bad?**\n\nInheriting from bases with conflicting instance memory layouts\nwill lead to a `TypeError` at runtime.\n\nAn instance memory layout conflict occurs when CPython cannot determine\nthe memory layout instances of a class should have, because the instance\nmemory layout of one of its bases conflicts with the instance memory layout\nof one or more of its other bases.\n\nFor example, if a Python class defines non-empty `__slots__`, this will\nimpact the memory layout of instances of that class. Multiple inheritance\nfrom more than one different class defining non-empty `__slots__` is not\nallowed:\n\n```python\nclass A:\n __slots__ = (\"a\", \"b\")\n\nclass B:\n __slots__ = (\"a\", \"b\") # Even if the values are the same\n\n# TypeError: multiple bases have instance lay-out conflict\nclass C(A, B): ...\n```\n\nAn instance layout conflict can also be caused by attempting to use\nmultiple inheritance with two builtin classes, due to the way that these\nclasses are implemented in a CPython C extension:\n\n```python\nclass A(int, float): ... # TypeError: multiple bases have instance lay-out conflict\n```\n\nNote that pure-Python classes with no `__slots__`, or pure-Python classes\nwith empty `__slots__`, are always compatible:\n\n```python\nclass A: ...\nclass B:\n __slots__ = ()\nclass C:\n __slots__ = (\"a\", \"b\")\n\n# fine\nclass D(A, B, C): ...\n```\n\n**Known problems**\n\nClasses that have \"dynamic\" definitions of `__slots__` (definitions do not consist\nof string literals, or tuples of string literals) are not currently considered disjoint\nbases by ty.\n\nAdditionally, this check is not exhaustive: many C extensions (including several in\nthe standard library) define classes that use extended memory layouts and thus cannot\ncoexist in a single MRO. Since it is currently not possible to represent this fact in\nstub files, having a full knowledge of these classes is also impossible. When it comes\nto classes that do not define `__slots__` at the Python level, therefore, ty, currently\nonly hard-codes a number of cases where it knows that a class will produce instances with\nan atypical memory layout.\n\n**Further reading**\n\n- [CPython documentation: `__slots__`](https://docs.python.org/3/reference/datamodel.html#slots)\n- [CPython documentation: Method Resolution Order](https://docs.python.org/3/glossary.html#term-method-resolution-order)\n\n[Method Resolution Order]: https://docs.python.org/3/glossary.html#term-method-resolution-order\n\n## `invalid-argument-type`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects call arguments whose type is not assignable to the corresponding typed parameter.\n\n**Why is this bad?**\n\nPassing an argument of a type the function (or callable object) does not accept violates\nthe expectations of the function author and may cause unexpected runtime errors within the\nbody of the function.\n\n**Examples**\n\n```python\ndef func(x: int): ...\nfunc(\"foo\") # error: [invalid-argument-type]\n```\n\n## `invalid-assignment`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for assignments where the type of the value\nis not [assignable to] the type of the assignee.\n\n**Why is this bad?**\n\nSuch assignments break the rules of the type system and\nweaken a type checker's ability to accurately reason about your code.\n\n**Examples**\n\n```python\na: int = ''\n```\n\n[assignable to]: https://typing.python.org/en/latest/spec/glossary.html#term-assignable\n\n## `invalid-attribute-access`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for assignments to class variables from instances\nand assignments to instance variables from its class.\n\n**Why is this bad?**\n\nIncorrect assignments break the rules of the type system and\nweaken a type checker's ability to accurately reason about your code.\n\n**Examples**\n\n```python\nclass C:\n class_var: ClassVar[int] = 1\n instance_var: int\n\nC.class_var = 3 # okay\nC().class_var = 3 # error: Cannot assign to class variable\n\nC().instance_var = 3 # okay\nC.instance_var = 3 # error: Cannot assign to instance variable\n```\n\n## `invalid-await`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.19 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for `await` being used with types that are not [Awaitable].\n\n**Why is this bad?**\n\nSuch expressions will lead to `TypeError` being raised at runtime.\n\n**Examples**\n\n```python\nimport asyncio\n\nclass InvalidAwait:\n def __await__(self) -> int:\n return 5\n\nasync def main() -> None:\n await InvalidAwait() # error: [invalid-await]\n await 42 # error: [invalid-await]\n\nasyncio.run(main())\n```\n\n[Awaitable]: https://docs.python.org/3/library/collections.abc.html#collections.abc.Awaitable\n\n## `invalid-base`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for class definitions that have bases which are not instances of `type`.\n\n**Why is this bad?**\n\nClass definitions with bases like this will lead to `TypeError` being raised at runtime.\n\n**Examples**\n\n```python\nclass A(42): ... # error: [invalid-base]\n```\n\n## `invalid-context-manager`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for expressions used in `with` statements\nthat do not implement the context manager protocol.\n\n**Why is this bad?**\n\nSuch a statement will raise `TypeError` at runtime.\n\n**Examples**\n\n```python\n# TypeError: 'int' object does not support the context manager protocol\nwith 1:\n print(2)\n```\n\n## `invalid-dataclass`\n\n\nDefault level: error ·\nAdded in 0.0.12 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for invalid applications of the `@dataclass` decorator.\n\n**Why is this bad?**\n\nApplying `@dataclass` to a class that inherits from `NamedTuple`, `TypedDict`,\n`Enum`, or `Protocol` is invalid:\n\n- `NamedTuple` and `TypedDict` classes will raise an exception at runtime when\n instantiating the class.\n- `Enum` classes with `@dataclass` are [explicitly not supported].\n- `Protocol` classes define interfaces and cannot be instantiated.\n\n**Examples**\n\n```python\nfrom dataclasses import dataclass\nfrom typing import NamedTuple\n\n@dataclass # error: [invalid-dataclass]\nclass Foo(NamedTuple):\n x: int\n```\n\n[explicitly not supported]: https://docs.python.org/3/howto/enum.html#dataclass-support\n\n## `invalid-dataclass-override`\n\n\nDefault level: error ·\nAdded in 0.0.13 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for dataclass definitions that have both `frozen=True` and a custom `__setattr__` or\n`__delattr__` method defined.\n\n**Why is this bad?**\n\nFrozen dataclasses synthesize `__setattr__` and `__delattr__` methods which raise a\n`FrozenInstanceError` to emulate immutability.\n\nOverriding either of these methods raises a runtime error.\n\n**Examples**\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass(frozen=True)\nclass A:\n def __setattr__(self, name: str, value: object) -> None: ...\n```\n\n## `invalid-declaration`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for declarations where the inferred type of an existing symbol\nis not [assignable to] its post-hoc declared type.\n\n**Why is this bad?**\n\nSuch declarations break the rules of the type system and\nweaken a type checker's ability to accurately reason about your code.\n\n**Examples**\n\n```python\na = 1\na: str\n```\n\n[assignable to]: https://typing.python.org/en/latest/spec/glossary.html#term-assignable\n\n## `invalid-enum-member-annotation`\n\n\nDefault level: warn ·\nAdded in 0.0.20 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for enum members that have explicit type annotations.\n\n**Why is this bad?**\n\nThe [typing spec] states that type checkers should infer a literal type\nfor all enum members. An explicit type annotation on an enum member is\nmisleading because the annotated type will be incorrect — the actual\nruntime type is the enum class itself, not the annotated type.\n\nIn CPython's `enum` module, annotated assignments with values are still\ntreated as members at runtime, but the annotation will confuse readers of the code.\n\n**Examples**\n\n```python\nfrom enum import Enum\n\nclass Pet(Enum):\n CAT = 1 # OK\n DOG: int = 2 # Error: enum members should not be annotated\n```\n\nUse instead:\n```python\nfrom enum import Enum\n\nclass Pet(Enum):\n CAT = 1\n DOG = 2\n```\n\n**References**\n\n- [Typing spec: Enum members](https://typing.python.org/en/latest/spec/enums.html#enum-members)\n\n[typing spec]: https://typing.python.org/en/latest/spec/enums.html#enum-members\n\n## `invalid-exception-caught`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for exception handlers that catch non-exception classes.\n\n**Why is this bad?**\n\nCatching classes that do not inherit from `BaseException` will raise a `TypeError` at runtime.\n\n**Example**\n\n```python\ntry:\n 1 / 0\nexcept 1:\n ...\n```\n\nUse instead:\n```python\ntry:\n 1 / 0\nexcept ZeroDivisionError:\n ...\n```\n\n**References**\n\n- [Python documentation: except clause](https://docs.python.org/3/reference/compound_stmts.html#except-clause)\n- [Python documentation: Built-in Exceptions](https://docs.python.org/3/library/exceptions.html#built-in-exceptions)\n\n**Ruff rule**\n\n This rule corresponds to Ruff's [`except-with-non-exception-classes` (`B030`)](https://docs.astral.sh/ruff/rules/except-with-non-exception-classes)\n\n## `invalid-explicit-override`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.28 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for methods that are decorated with `@override` but do not override any method in a superclass.\n\n**Why is this bad?**\n\nDecorating a method with `@override` declares to the type checker that the intention is that it should\noverride a method from a superclass.\n\n**Example**\n\n\n```python\nfrom typing import override\n\nclass A:\n @override\n def foo(self): ... # Error raised here\n\nclass B(A):\n @override\n def ffooo(self): ... # Error raised here\n\nclass C:\n @override\n def __repr__(self): ... # fine: overrides `object.__repr__`\n\nclass D(A):\n @override\n def foo(self): ... # fine: overrides `A.foo`\n```\n\n## `invalid-frozen-dataclass-subclass`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.35 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for dataclasses with invalid frozen inheritance:\n- A frozen dataclass cannot inherit from a non-frozen dataclass.\n- A non-frozen dataclass cannot inherit from a frozen dataclass.\n\n**Why is this bad?**\n\nPython raises a `TypeError` at runtime when either of these inheritance\npatterns occurs.\n\n**Example**\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Base:\n x: int\n\n@dataclass(frozen=True)\nclass Child(Base): # Error raised here\n y: int\n\n@dataclass(frozen=True)\nclass FrozenBase:\n x: int\n\n@dataclass\nclass NonFrozenChild(FrozenBase): # Error raised here\n y: int\n```\n\n## `invalid-generic-class`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for the creation of invalid generic classes\n\n**Why is this bad?**\n\nThere are several requirements that you must follow when defining a generic class.\nMany of these result in `TypeError` being raised at runtime if they are violated.\n\n**Examples**\n\n```python\nfrom typing_extensions import Generic, TypeVar\n\nT = TypeVar(\"T\")\nU = TypeVar(\"U\", default=int)\n\n# error: class uses both PEP-695 syntax and legacy syntax\nclass C[U](Generic[T]): ...\n\n# error: type parameter with default comes before type parameter without default\nclass D(Generic[U, T]): ...\n```\n\n**References**\n\n- [Typing spec: Generics](https://typing.python.org/en/latest/spec/generics.html#introduction)\n\n## `invalid-generic-enum`\n\n\nDefault level: error ·\nAdded in 0.0.12 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for enum classes that are also generic.\n\n**Why is this bad?**\n\nEnum classes cannot be generic. Python does not support generic enums:\nattempting to create one will either result in an immediate `TypeError`\nat runtime, or will create a class that cannot be specialized in the way\nthat a normal generic class can.\n\n**Examples**\n\n```python\nfrom enum import Enum\nfrom typing import Generic, TypeVar\n\nT = TypeVar(\"T\")\n\n# error: enum class cannot be generic (class creation fails with `TypeError`)\nclass E[T](Enum):\n A = 1\n\n# error: enum class cannot be generic (class creation fails with `TypeError`)\nclass F(Enum, Generic[T]):\n A = 1\n\n# error: enum class cannot be generic -- the class creation does not immediately fail...\nclass G(Generic[T], Enum):\n A = 1\n\n# ...but this raises `KeyError`:\nx: G[int]\n```\n\n**References**\n\n- [Python documentation: Enum](https://docs.python.org/3/library/enum.html)\n\n## `invalid-ignore-comment`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for `type: ignore` and `ty: ignore` comments that are syntactically incorrect.\n\n**Why is this bad?**\n\nA syntactically incorrect ignore comment is probably a mistake and is useless.\n\n**Examples**\n\n```py\na = 20 / 0 # type: ignoree\n```\n\nUse instead:\n\n```py\na = 20 / 0 # type: ignore\n```\n\n## `invalid-key`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.17 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for subscript accesses with invalid keys and `TypedDict` construction with an\nunknown key.\n\n**Why is this bad?**\n\nSubscripting with an invalid key will raise a `KeyError` at runtime.\n\nCreating a `TypedDict` with an unknown key is likely a mistake; if the `TypedDict` is\n`closed=true` it also violates the expectations of the type.\n\n**Examples**\n\n```python\nfrom typing import TypedDict\n\nclass Person(TypedDict):\n name: str\n age: int\n\nalice = Person(name=\"Alice\", age=30)\nalice[\"height\"] # KeyError: 'height'\n\nbob: Person = { \"namee\": \"Bob\", \"age\": 30 } # typo!\n\ncarol = Person(name=\"Carol\", aeg=25) # typo!\n```\n\n## `invalid-legacy-positional-parameter`\n\n\nDefault level: warn ·\nAdded in 0.0.15 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\n\nChecks for parameters that appear to be attempting to use the legacy convention\nto specify that a parameter is positional-only, but do so incorrectly.\n\nThe \"legacy convention\" for specifying positional-only parameters was\nspecified in [PEP 484]. It states that parameters with names starting with\n`__` should be considered positional-only by type checkers. [PEP 570], introduced\nin Python 3.8, added dedicated syntax for specifying positional-only parameters,\nrendering the legacy convention obsolete. However, some codebases may still\nuse the legacy convention for compatibility with older Python versions.\n\n**Why is this bad?**\n\n\nIn most cases, a type checker will not consider a parameter to be positional-only\nif it comes after a positional-or-keyword parameter, even if its name starts with\n`__`. This may be unexpected to the author of the code.\n\n**Example**\n\n\n```python\ndef f(x, __y): # Error: `__y` is not considered positional-only\n pass\n```\n\nUse instead:\n\n```python\ndef f(__x, __y): # If you need compatibility with Python <=3.7\n pass\n```\n\nor:\n\n```python\ndef f(x, y, /): # Python 3.8+ syntax\n pass\n```\n\n**References**\n\n\n- [Typing spec: positional-only parameters (legacy syntax)](https://typing.python.org/en/latest/spec/historical.html#pos-only-double-underscore)\n- [Python glossary: parameters](https://docs.python.org/3/glossary.html#term-parameter)\n\n[PEP 484]: https://peps.python.org/pep-0484/#positional-only-arguments\n[PEP 570]: https://peps.python.org/pep-0570/\n\n## `invalid-legacy-type-variable`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for the creation of invalid legacy `TypeVar`s\n\n**Why is this bad?**\n\nThere are several requirements that you must follow when creating a legacy `TypeVar`.\n\n**Examples**\n\n```python\nfrom typing import TypeVar\n\nT = TypeVar(\"T\") # okay\nQ = TypeVar(\"S\") # error: TypeVar name must match the variable it's assigned to\nT = TypeVar(\"T\") # error: TypeVars should not be redefined\n\n# error: TypeVar must be immediately assigned to a variable\ndef f(t: TypeVar(\"U\")): ...\n```\n\n**References**\n\n- [Typing spec: Generics](https://typing.python.org/en/latest/spec/generics.html#introduction)\n\n## `invalid-match-pattern`\n\n\nDefault level: error ·\nAdded in 0.0.18 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for invalid match patterns.\n\n**Why is this bad?**\n\nMatching on invalid patterns will lead to a runtime error.\n\n**Examples**\n\n```python\nNotAClass = 42\n\nmatch x:\n case NotAClass(): # TypeError at runtime: must be a class\n ...\n```\n\n## `invalid-metaclass`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for arguments to `metaclass=` that are invalid.\n\n**Why is this bad?**\n\nPython allows arbitrary expressions to be used as the argument to `metaclass=`.\nThese expressions, however, need to be callable and accept the same arguments\nas `type.__new__`.\n\n**Example**\n\n\n```python\ndef f(): ...\n\n# TypeError: f() takes 0 positional arguments but 3 were given\nclass B(metaclass=f): ...\n```\n\n**References**\n\n- [Python documentation: Metaclasses](https://docs.python.org/3/reference/datamodel.html#metaclasses)\n\n## `invalid-method-override`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.20 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects method overrides that violate the [Liskov Substitution Principle] (\"LSP\").\n\nThe LSP states that an instance of a subtype should be substitutable for an instance of its supertype.\nApplied to Python, this means:\n1. All argument combinations a superclass method accepts\n must also be accepted by an overriding subclass method.\n2. The return type of an overriding subclass method must be a subtype\n of the return type of the superclass method.\n\n**Why is this bad?**\n\nViolating the Liskov Substitution Principle will lead to many of ty's assumptions and\ninferences being incorrect, which will mean that it will fail to catch many possible\ntype errors in your code.\n\n**Example**\n\n```python\nclass Super:\n def method(self, x) -> int:\n return 42\n\nclass Sub(Super):\n # Liskov violation: `str` is not a subtype of `int`,\n # but the supertype method promises to return an `int`.\n def method(self, x) -> str: # error: [invalid-override]\n return \"foo\"\n\ndef accepts_super(s: Super) -> int:\n return s.method(x=42)\n\naccepts_super(Sub()) # The result of this call is a string, but ty will infer\n # it to be an `int` due to the violation of the Liskov Substitution Principle.\n\nclass Sub2(Super):\n # Liskov violation: the superclass method can be called with a `x=`\n # keyword argument, but the subclass method does not accept it.\n def method(self, y) -> int: # error: [invalid-override]\n return 42\n\naccepts_super(Sub2()) # TypeError at runtime: method() got an unexpected keyword argument 'x'\n # ty cannot catch this error due to the violation of the Liskov Substitution Principle.\n```\n\n**Common issues**\n\n\n**Why does ty complain about my `__eq__` method?**\n\n\n`__eq__` and `__ne__` methods in Python are generally expected to accept arbitrary\nobjects as their second argument, for example:\n\n```python\nclass A:\n x: int\n\n def __eq__(self, other: object) -> bool:\n # gracefully handle an object of an unexpected type\n # without raising an exception\n if not isinstance(other, A):\n return False\n return self.x == other.x\n```\n\nIf `A.__eq__` here were annotated as only accepting `A` instances for its second argument,\nit would imply that you wouldn't be able to use `==` between instances of `A` and\ninstances of unrelated classes without an exception possibly being raised. While some\nclasses in Python do indeed behave this way, the strongly held convention is that it should\nbe avoided wherever possible. As part of this check, therefore, ty enforces that `__eq__`\nand `__ne__` methods accept `object` as their second argument.\n\n**Why does ty disagree with Ruff about how to write my method?**\n\n\nRuff has several rules that will encourage you to rename a parameter, or change its type\nsignature, if it thinks you're falling into a certain anti-pattern. For example, Ruff's\n[ARG002](https://docs.astral.sh/ruff/rules/unused-method-argument/) rule recommends that an\nunused parameter should either be removed or renamed to start with `_`. Applying either of\nthese suggestions can cause ty to start reporting an [`invalid-method-override`](#invalid-method-override) error if\nthe function in question is a method on a subclass that overrides a method on a superclass,\nand the change would cause the subclass method to no longer accept all argument combinations\nthat the superclass method accepts.\n\nThis can usually be resolved by adding [`@typing.override`][override] to your method\ndefinition. Ruff knows that a method decorated with `@typing.override` is intended to\noverride a method by the same name on a superclass, and avoids reporting rules like ARG002\nfor such methods; it knows that the changes recommended by ARG002 would violate the Liskov\nSubstitution Principle.\n\nCorrect use of `@override` is enforced by ty's [`invalid-explicit-override`](#invalid-explicit-override) rule.\n\n[Liskov Substitution Principle]: https://en.wikipedia.org/wiki/Liskov_substitution_principle\n[override]: https://docs.python.org/3/library/typing.html#typing.override\n\n## `invalid-named-tuple`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.19 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for invalidly defined `NamedTuple` classes.\n\n**Why is this bad?**\n\nAn invalidly defined `NamedTuple` class may lead to the type checker\ndrawing incorrect conclusions. It may also lead to `TypeError`s or\n`AttributeError`s at runtime.\n\n**Examples**\n\nA class definition cannot combine `NamedTuple` with other base classes\nin multiple inheritance; doing so raises a `TypeError` at runtime. The sole\nexception to this rule is `Generic[]`, which can be used alongside `NamedTuple`\nin a class's bases list.\n\n```pycon\n>>> from typing import NamedTuple\n>>> class Foo(NamedTuple, object): ...\nTypeError: can only inherit from a NamedTuple type and Generic\n```\n\nFurther, `NamedTuple` field names cannot start with an underscore:\n\n```pycon\n>>> from typing import NamedTuple\n>>> class Foo(NamedTuple):\n... _bar: int\nValueError: Field names cannot start with an underscore: '_bar'\n```\n\n`NamedTuple` classes also have certain synthesized attributes (like `_asdict`, `_make`,\n`_replace`, etc.) that cannot be overwritten. Attempting to assign to these attributes\nwithout a type annotation will raise an `AttributeError` at runtime.\n\n```pycon\n>>> from typing import NamedTuple\n>>> class Foo(NamedTuple):\n... x: int\n... _asdict = 42\nAttributeError: Cannot overwrite NamedTuple attribute _asdict\n```\n\n## `invalid-newtype`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.27 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for the creation of invalid `NewType`s\n\n**Why is this bad?**\n\nThere are several requirements that you must follow when creating a `NewType`.\n\n**Examples**\n\n```python\nfrom typing import NewType\n\ndef get_name() -> str: ...\n\nFoo = NewType(\"Foo\", int) # okay\nBar = NewType(get_name(), int) # error: The first argument to `NewType` must be a string literal\nBaz = NewType(\"Baz\", int | str) # error: invalid base for `typing.NewType`\n```\n\n## `invalid-overload`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for various invalid `@overload` usages.\n\n**Why is this bad?**\n\nThe `@overload` decorator is used to define functions and methods that accepts different\ncombinations of arguments and return different types based on the arguments passed. This is\nmainly beneficial for type checkers. But, if the `@overload` usage is invalid, the type\nchecker may not be able to provide correct type information.\n\n**Example**\n\n\nDefining only one overload:\n\n```py\nfrom typing import overload\n\n@overload\ndef foo(x: int) -> int: ...\ndef foo(x: int | None) -> int | None:\n return x\n```\n\nOr, not providing an implementation for the overloaded definition:\n\n```py\nfrom typing import overload\n\n@overload\ndef foo() -> None: ...\n@overload\ndef foo(x: int) -> int: ...\n```\n\n**References**\n\n- [Python documentation: `@overload`](https://docs.python.org/3/library/typing.html#typing.overload)\n\n## `invalid-parameter-default`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for default values that can't be\nassigned to the parameter's annotated type.\n\n**Why is this bad?**\n\nThis breaks the rules of the type system and\nweakens a type checker's ability to accurately reason about your code.\n\n**Examples**\n\n```python\ndef f(a: int = ''): ...\n```\n\n## `invalid-paramspec`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for the creation of invalid `ParamSpec`s\n\n**Why is this bad?**\n\nThere are several requirements that you must follow when creating a `ParamSpec`.\n\n**Examples**\n\n```python\nfrom typing import ParamSpec\n\nP1 = ParamSpec(\"P1\") # okay\nP2 = ParamSpec(\"S2\") # error: ParamSpec name must match the variable it's assigned to\n```\n\n**References**\n\n- [Typing spec: ParamSpec](https://typing.python.org/en/latest/spec/generics.html#paramspec)\n\n## `invalid-protocol`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for protocol classes that will raise `TypeError` at runtime.\n\n**Why is this bad?**\n\nAn invalidly defined protocol class may lead to the type checker inferring\nunexpected things. It may also lead to `TypeError`s at runtime.\n\n**Examples**\n\nA `Protocol` class cannot inherit from a non-`Protocol` class;\nthis raises a `TypeError` at runtime:\n\n```pycon\n>>> from typing import Protocol\n>>> class Foo(int, Protocol): ...\n...\nTraceback (most recent call last):\n File \"\", line 1, in \n class Foo(int, Protocol): ...\nTypeError: Protocols can only inherit from other protocols, got \n```\n\n## `invalid-raise`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\nChecks for `raise` statements that raise non-exceptions or use invalid\ncauses for their raised exceptions.\n\n**Why is this bad?**\n\nOnly subclasses or instances of `BaseException` can be raised.\nFor an exception's cause, the same rules apply, except that `None` is also\npermitted. Violating these rules results in a `TypeError` at runtime.\n\n**Examples**\n\n```python\ndef f():\n try:\n something()\n except NameError:\n raise \"oops!\" from f\n\ndef g():\n raise NotImplemented from 42\n```\n\nUse instead:\n```python\ndef f():\n try:\n something()\n except NameError as e:\n raise RuntimeError(\"oops!\") from e\n\ndef g():\n raise NotImplementedError from None\n```\n\n**References**\n\n- [Python documentation: The `raise` statement](https://docs.python.org/3/reference/simple_stmts.html#raise)\n- [Python documentation: Built-in Exceptions](https://docs.python.org/3/library/exceptions.html#built-in-exceptions)\n\n## `invalid-return-type`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects returned values that can't be assigned to the function's annotated return type.\n\nNote that the special case of a function with a non-`None` return type and an empty body\nis handled by the separate [`empty-body`](#empty-body) error code.\n\n**Why is this bad?**\n\nReturning an object of a type incompatible with the annotated return type\nis unsound, and will lead to ty inferring incorrect types elsewhere.\n\n**Examples**\n\n```python\ndef func() -> int:\n return \"a\" # error: [invalid-return-type]\n```\n\n## `invalid-super-argument`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects `super()` calls where:\n- the first argument is not a valid class literal, or\n- the second argument is not an instance or subclass of the first argument.\n\n**Why is this bad?**\n\n`super(type, obj)` expects:\n- the first argument to be a class,\n- and the second argument to satisfy one of the following:\n - `isinstance(obj, type)` is `True`\n - `issubclass(obj, type)` is `True`\n\nViolating this relationship will raise a `TypeError` at runtime.\n\n**Examples**\n\n```python\nclass A:\n ...\nclass B(A):\n ...\n\nsuper(A, B()) # it's okay! `A` satisfies `isinstance(B(), A)`\n\nsuper(A(), B()) # error: `A()` is not a class\n\nsuper(B, A()) # error: `A()` does not satisfy `isinstance(A(), B)`\nsuper(B, A) # error: `A` does not satisfy `issubclass(A, B)`\n```\n\n**References**\n\n- [Python documentation: super()](https://docs.python.org/3/library/functions.html#super)\n\n## `invalid-syntax-in-forward-annotation`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for string-literal annotations where the string cannot be\nparsed as a Python expression.\n\n**Why is this bad?**\n\nType annotations are expected to be Python expressions that\ndescribe the expected type of a variable, parameter, attribute or\n`return` statement.\n\nType annotations are permitted to be string-literal expressions, in\norder to enable forward references to names not yet defined.\nHowever, it must be possible to parse the contents of that string\nliteral as a normal Python expression.\n\n**Example**\n\n\n```python\ndef foo() -> \"intstance of C\":\n return 42\n\nclass C: ...\n```\n\nUse instead:\n\n```python\ndef foo() -> \"C\":\n return 42\n\nclass C: ...\n```\n\n**References**\n\n- [Typing spec: The meaning of annotations](https://typing.python.org/en/latest/spec/annotations.html#the-meaning-of-annotations)\n- [Typing spec: String annotations](https://typing.python.org/en/latest/spec/annotations.html#string-annotations)\n\n## `invalid-total-ordering`\n\n\nDefault level: error ·\nAdded in 0.0.10 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for classes decorated with `@functools.total_ordering` that don't\ndefine any ordering method (`__lt__`, `__le__`, `__gt__`, or `__ge__`).\n\n**Why is this bad?**\n\nThe `@total_ordering` decorator requires the class to define at least one\nordering method. If none is defined, Python raises a `ValueError` at runtime.\n\n**Example**\n\n\n```python\nfrom functools import total_ordering\n\n@total_ordering\nclass MyClass: # Error: no ordering method defined\n def __eq__(self, other: object) -> bool:\n return True\n```\n\nUse instead:\n\n```python\nfrom functools import total_ordering\n\n@total_ordering\nclass MyClass:\n def __eq__(self, other: object) -> bool:\n return True\n\n def __lt__(self, other: \"MyClass\") -> bool:\n return True\n```\n\n## `invalid-type-alias-type`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.6 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for the creation of invalid `TypeAliasType`s\n\n**Why is this bad?**\n\nThere are several requirements that you must follow when creating a `TypeAliasType`.\n\n**Examples**\n\n```python\nfrom typing import TypeAliasType\n\nIntOrStr = TypeAliasType(\"IntOrStr\", int | str) # okay\nNewAlias = TypeAliasType(get_name(), int) # error: TypeAliasType name must be a string literal\n```\n\n## `invalid-type-arguments`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.29 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for invalid type arguments in explicit type specialization.\n\n**Why is this bad?**\n\nProviding the wrong number of type arguments or type arguments that don't\nsatisfy the type variable's bounds or constraints will lead to incorrect\ntype inference and may indicate a misunderstanding of the generic type's\ninterface.\n\n**Examples**\n\n\nUsing legacy type variables:\n```python\nfrom typing import Generic, TypeVar\n\nT1 = TypeVar('T1', int, str)\nT2 = TypeVar('T2', bound=int)\n\nclass Foo1(Generic[T1]): ...\nclass Foo2(Generic[T2]): ...\n\nFoo1[bytes] # error: bytes does not satisfy T1's constraints\nFoo2[str] # error: str does not satisfy T2's bound\n```\n\nUsing PEP 695 type variables:\n```python\nclass Foo[T]: ...\nclass Bar[T, U]: ...\n\nFoo[int, str] # error: too many arguments\nBar[int] # error: too few arguments\n```\n\n## `invalid-type-checking-constant`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for a value other than `False` assigned to the `TYPE_CHECKING` variable, or an\nannotation not assignable from `bool`.\n\n**Why is this bad?**\n\nThe name `TYPE_CHECKING` is reserved for a flag that can be used to provide conditional\ncode seen only by the type checker, and not at runtime. Normally this flag is imported from\n`typing` or `typing_extensions`, but it can also be defined locally. If defined locally, it\nmust be assigned the value `False` at runtime; the type checker will consider its value to\nbe `True`. If annotated, it must be annotated as a type that can accept `bool` values.\n\n**Examples**\n\n```python\nTYPE_CHECKING: str\nTYPE_CHECKING = ''\n```\n\n## `invalid-type-form`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for expressions that are used as [type expressions]\nbut cannot validly be interpreted as such.\n\n**Why is this bad?**\n\nSuch expressions cannot be understood by ty.\nIn some cases, they might raise errors at runtime.\n\n**Examples**\n\n```python\nfrom typing import Annotated\n\na: type[1] # `1` is not a type\nb: Annotated[int] # `Annotated` expects at least two arguments\n```\n[type expressions]: https://typing.python.org/en/latest/spec/annotations.html#type-and-annotation-expressions\n\n## `invalid-type-guard-call`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.11 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for type guard function calls without a valid target.\n\n**Why is this bad?**\n\nThe first non-keyword non-variadic argument to a type guard function\nis its target and must map to a symbol.\n\nStarred (`is_str(*a)`), literal (`is_str(42)`) and other non-symbol-like\nexpressions are invalid as narrowing targets.\n\n**Examples**\n\n```python\nfrom typing import TypeIs\n\ndef f(v: object) -> TypeIs[int]: ...\n\nf() # Error\nf(*a) # Error\nf(10) # Error\n```\n\n## `invalid-type-guard-definition`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.11 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for type guard functions without\na first non-self-like non-keyword-only non-variadic parameter.\n\n**Why is this bad?**\n\nType narrowing functions must accept at least one positional argument\n(non-static methods must accept another in addition to `self`/`cls`).\n\nExtra parameters/arguments are allowed but do not affect narrowing.\n\n**Examples**\n\n```python\nfrom typing import TypeIs\n\ndef f() -> TypeIs[int]: ... # Error, no parameter\ndef f(*, v: object) -> TypeIs[int]: ... # Error, no positional arguments allowed\ndef f(*args: object) -> TypeIs[int]: ... # Error, expect variadic arguments\nclass C:\n def f(self) -> TypeIs[int]: ... # Error, only positional argument expected is `self`\n```\n\n## `invalid-type-variable-bound`\n\n\nDefault level: error ·\nAdded in 0.0.15 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for [type variables] whose bounds reference type variables.\n\n**Why is this bad?**\n\nThe bound of a type variable must be a concrete type.\n\n**Examples**\n\n```python\nT = TypeVar('T', bound=list['T']) # error: [invalid-type-variable-bound]\nU = TypeVar('U')\nT = TypeVar('T', bound=U) # error: [invalid-type-variable-bound]\n\ndef f[T: list[T]](): ... # error: [invalid-type-variable-bound]\ndef g[U, T: U](): ... # error: [invalid-type-variable-bound]\n```\n\n[type variable]: https://docs.python.org/3/library/typing.html#typing.TypeVar\n\n## `invalid-type-variable-constraints`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\n\nChecks for constrained [type variables] with only one constraint,\nor that those constraints reference type variables.\n\n**Why is this bad?**\n\n\nA constrained type variable must have at least two constraints.\n\n**Examples**\n\n\n```python\nfrom typing import TypeVar\n\nT = TypeVar('T', str) # invalid constrained TypeVar\n\nI = TypeVar('I', bound=int)\nU = TypeVar('U', list[I], int) # invalid constrained TypeVar\n```\n\nUse instead:\n\n```python\nT = TypeVar('T', str, int) # valid constrained TypeVar\n\n# or\n\nT = TypeVar('T', bound=str) # valid bound TypeVar\n\nU = TypeVar('U', list[int], int) # valid constrained Type\n```\n\n[type variables]: https://docs.python.org/3/library/typing.html#typing.TypeVar\n\n## `invalid-type-variable-default`\n\n\nDefault level: error ·\nAdded in 0.0.16 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for [type variables] whose default type is not compatible with\nthe type variable's bound or constraints.\n\n**Why is this bad?**\n\nIf a type variable has a bound, the default must be assignable to that\nbound (see: [bound rules]). If a type variable has constraints, the default\nmust be one of the constraints (see: [constraint rules]).\n\n**Examples**\n\n```python\nT = TypeVar(\"T\", bound=str, default=int) # error: [invalid-type-variable-default]\nU = TypeVar(\"U\", int, str, default=bytes) # error: [invalid-type-variable-default]\n```\n\n[type variables]: https://docs.python.org/3/library/typing.html#typing.TypeVar\n[bound rules]: https://typing.python.org/en/latest/spec/generics.html#bound-rules\n[constraint rules]: https://typing.python.org/en/latest/spec/generics.html#constraint-rules\n\n## `invalid-typed-dict-header`\n\n\nDefault level: error ·\nAdded in 0.0.14 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects errors in `TypedDict` class headers, such as unexpected arguments\nor invalid base classes.\n\n**Why is this bad?**\n\nThe typing spec states that `TypedDict`s are not permitted to have\ncustom metaclasses. Using `**` unpacking in a `TypedDict` header\nis also prohibited by ty, as it means that ty cannot statically determine\nwhether keys in the `TypedDict` are intended to be required or optional.\n\n**Example**\n\n```python\nfrom typing import TypedDict\n\nclass Foo(TypedDict, metaclass=whatever): # error: [invalid-typed-dict-header]\n ...\n\ndef f(x: dict):\n class Bar(TypedDict, **x): # error: [invalid-typed-dict-header]\n ...\n```\n\n## `invalid-typed-dict-statement`\n\n\nDefault level: error ·\nAdded in 0.0.9 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects statements other than annotated declarations in `TypedDict` class bodies.\n\n**Why is this bad?**\n\n`TypedDict` class bodies aren't allowed to contain any other types of statements. For\nexample, method definitions and field values aren't allowed. None of these will be\navailable on \"instances of the `TypedDict`\" at runtime (as `dict` is the runtime class of\nall \"`TypedDict` instances\").\n\n**Example**\n\n```python\nfrom typing import TypedDict\n\nclass Foo(TypedDict):\n def bar(self): # error: [invalid-typed-dict-statement]\n pass\n```\n\n## `isinstance-against-protocol`\n\n\nDefault level: error ·\nAdded in 0.0.14 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nReports invalid runtime checks against `Protocol` classes.\nThis includes explicit calls `isinstance()`/`issubclass()` against\nnon-runtime-checkable protocols, `issubclass()` calls against protocols\nthat have non-method members, and implicit `isinstance()` checks against\nnon-runtime-checkable protocols via pattern matching.\n\n**Why is this bad?**\n\nThese calls (implicit or explicit) raise `TypeError` at runtime.\n\n**Examples**\n\n```python\nfrom typing_extensions import Protocol, runtime_checkable\n\nclass HasX(Protocol):\n x: int\n\n@runtime_checkable\nclass HasY(Protocol):\n y: int\n\ndef f(arg: object, arg2: type):\n isinstance(arg, HasX) # error: [isinstance-against-protocol] (not runtime-checkable)\n issubclass(arg2, HasX) # error: [isinstance-against-protocol] (not runtime-checkable)\n\ndef g(arg: object):\n match arg:\n case HasX(): # error: [isinstance-against-protocol] (not runtime-checkable)\n pass\n\ndef h(arg2: type):\n isinstance(arg2, HasY) # fine (runtime-checkable)\n\n # `HasY` is runtime-checkable, but has non-method members,\n # so it still can't be used in `issubclass` checks)\n issubclass(arg2, HasY) # error: [isinstance-against-protocol]\n```\n\n**References**\n\n- [Typing documentation: `@runtime_checkable`](https://docs.python.org/3/library/typing.html#typing.runtime_checkable)\n\n## `isinstance-against-typed-dict`\n\n\nDefault level: error ·\nAdded in 0.0.15 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nReports runtime checks against `TypedDict` classes.\nThis includes explicit calls to `isinstance()`/`issubclass()` and implicit\nchecks performed by `match` class patterns.\n\n**Why is this bad?**\n\nUsing a `TypedDict` class in these contexts raises `TypeError` at runtime.\n\n**Examples**\n\n```python\nfrom typing_extensions import TypedDict\n\nclass Movie(TypedDict):\n name: str\n director: str\n\ndef f(arg: object, arg2: type):\n isinstance(arg, Movie) # error: [isinstance-against-typed-dict]\n issubclass(arg2, Movie) # error: [isinstance-against-typed-dict]\n\ndef g(arg: object):\n match arg:\n case Movie(): # error: [isinstance-against-typed-dict]\n pass\n```\n\n**References**\n\n- [Typing specification: `TypedDict`](https://typing.python.org/en/latest/spec/typeddict.html)\n\n## `missing-argument`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for missing required arguments in a call.\n\n**Why is this bad?**\n\nFailing to provide a required argument will raise a `TypeError` at runtime.\n\n**Examples**\n\n```python\ndef func(x: int): ...\nfunc() # TypeError: func() missing 1 required positional argument: 'x'\n```\n\n## `missing-typed-dict-key`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.20 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects missing required keys in `TypedDict` constructor calls.\n\n**Why is this bad?**\n\n`TypedDict` requires all non-optional keys to be provided during construction.\nMissing items can lead to a `KeyError` at runtime.\n\n**Example**\n\n```python\nfrom typing import TypedDict\n\nclass Person(TypedDict):\n name: str\n age: int\n\nalice: Person = {\"name\": \"Alice\"} # missing required key 'age'\n\nalice[\"age\"] # KeyError\n```\n\n## `no-matching-overload`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for calls to an overloaded function that do not match any of the overloads.\n\n**Why is this bad?**\n\nFailing to provide the correct arguments to one of the overloads will raise a `TypeError`\nat runtime.\n\n**Examples**\n\n```python\n@overload\ndef func(x: int): ...\n@overload\ndef func(x: bool): ...\nfunc(\"string\") # error: [no-matching-overload]\n```\n\n## `not-iterable`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for objects that are not iterable but are used in a context that requires them to be.\n\n**Why is this bad?**\n\nIterating over an object that is not iterable will raise a `TypeError` at runtime.\n\n**Examples**\n\n\n```python\nfor i in 34: # TypeError: 'int' object is not iterable\n pass\n```\n\n## `not-subscriptable`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for subscripting objects that do not support subscripting.\n\n**Why is this bad?**\n\nSubscripting an object that does not support it will raise a `TypeError` at runtime.\n\n**Examples**\n\n```python\n4[1] # TypeError: 'int' object is not subscriptable\n```\n\n## `override-of-final-method`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.29 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for methods on subclasses that override superclass methods decorated with `@final`.\n\n**Why is this bad?**\n\nDecorating a method with `@final` declares to the type checker that it should not be\noverridden on any subclass.\n\n**Example**\n\n\n```python\nfrom typing import final\n\nclass A:\n @final\n def foo(self): ...\n\nclass B(A):\n def foo(self): ... # Error raised here\n```\n\n## `override-of-final-variable`\n\n\nDefault level: error ·\nAdded in 0.0.16 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for class variables on subclasses that override a superclass variable\nthat has been declared as `Final`.\n\n**Why is this bad?**\n\nDeclaring a variable as `Final` indicates to the type checker that it should not be\noverridden on any subclass.\n\n**Example**\n\n\n```python\nfrom typing import Final\n\nclass A:\n X: Final[int] = 1\n\nclass B(A):\n X = 2 # Error raised here\n```\n\n## `parameter-already-assigned`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for calls which provide more than one argument for a single parameter.\n\n**Why is this bad?**\n\nProviding multiple values for a single parameter will raise a `TypeError` at runtime.\n\n**Examples**\n\n\n```python\ndef f(x: int) -> int: ...\n\nf(1, x=2) # Error raised here\n```\n\n## `positional-only-parameter-as-kwarg`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.22 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for keyword arguments in calls that match positional-only parameters of the callable.\n\n**Why is this bad?**\n\nProviding a positional-only parameter as a keyword argument will raise `TypeError` at runtime.\n\n**Example**\n\n\n```python\ndef f(x: int, /) -> int: ...\n\nf(x=1) # Error raised here\n```\n\n## `possibly-missing-attribute`\n\n\nDefault level: ignore ·\nAdded in 0.0.1-alpha.22 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for possibly missing attributes.\n\n**Why is this bad?**\n\nAttempting to access a missing attribute will raise an `AttributeError` at runtime.\n\n**Rule status**\n\nThis rule is currently disabled by default because of the number of\nfalse positives it can produce.\n\n**Examples**\n\n```python\nclass A:\n if b:\n c = 0\n\nA.c # AttributeError: type object 'A' has no attribute 'c'\n```\n\n## `possibly-missing-implicit-call`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.22 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for implicit calls to possibly missing methods.\n\n**Why is this bad?**\n\nExpressions such as `x[y]` and `x * y` call methods\nunder the hood (`__getitem__` and `__mul__` respectively).\nCalling a missing method will raise an `AttributeError` at runtime.\n\n**Examples**\n\n```python\nimport datetime\n\nclass A:\n if datetime.date.today().weekday() != 6:\n def __getitem__(self, v): ...\n\nA()[0] # TypeError: 'A' object is not subscriptable\n```\n\n## `possibly-missing-import`\n\n\nDefault level: ignore ·\nAdded in 0.0.1-alpha.22 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for imports of symbols that may be missing.\n\n**Why is this bad?**\n\nImporting a missing module or name will raise a `ModuleNotFoundError`\nor `ImportError` at runtime.\n\n**Rule status**\n\nThis rule is currently disabled by default because of the number of\nfalse positives it can produce.\n\n**Examples**\n\n```python\n# module.py\nimport datetime\n\nif datetime.date.today().weekday() != 6:\n a = 1\n\n# main.py\nfrom module import a # ImportError: cannot import name 'a' from 'module'\n```\n\n## `possibly-missing-submodule`\n\n\nDefault level: warn ·\nAdded in 0.0.23 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for accesses of submodules that might not've been imported.\n\n**Why is this bad?**\n\nWhen module `a` has a submodule `b`, `import a` isn't generally enough to let you access\n`a.b.` You either need to explicitly `import a.b`, or else you need the `__init__.py` file\nof `a` to include `from . import b`. Without one of those, `a.b` is an `AttributeError`.\n\n**Examples**\n\n```python\nimport html\nhtml.parser # AttributeError: module 'html' has no attribute 'parser'\n```\n\n## `possibly-unresolved-reference`\n\n\nDefault level: ignore ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for references to names that are possibly not defined.\n\n**Why is this bad?**\n\nUsing an undefined variable will raise a `NameError` at runtime.\n\n**Rule status**\n\nThis rule is currently disabled by default because of the number of\nfalse positives it can produce.\n\n**Example**\n\n\n```python\nfor i in range(0):\n x = i\n\nprint(x) # NameError: name 'x' is not defined\n```\n\n## `raw-string-type-annotation`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for raw-strings in type annotation positions.\n\n**Why is this bad?**\n\nStatic analysis tools like ty can't analyze type annotations that use raw-string notation.\n\n**Examples**\n\n```python\ndef test(): -> r\"int\":\n ...\n```\n\nUse instead:\n```python\ndef test(): -> \"int\":\n ...\n```\n\n## `redundant-cast`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects redundant `cast` calls where the value already has the target type.\n\n**Why is this bad?**\n\nThese casts have no effect and can be removed.\n\n**Example**\n\n```python\ndef f() -> int:\n return 10\n\ncast(int, f()) # Redundant\n```\n\n## `redundant-final-classvar`\n\n\nDefault level: warn ·\nAdded in 0.0.18 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for redundant combinations of the `ClassVar` and `Final` type qualifiers.\n\n**Why is this bad?**\n\nAn attribute that is marked `Final` in a class body is implicitly a class variable.\nMarking it as `ClassVar` is therefore redundant.\n\nNote that this diagnostic is not emitted for dataclass fields, where\n`ClassVar[Final[int]]` has a distinct meaning from `Final[int]`.\n\n**Examples**\n\n```python\nfrom typing import ClassVar, Final\n\nclass C:\n x: ClassVar[Final[int]] = 1 # redundant\n y: Final[ClassVar[int]] = 1 # redundant\n```\n\n## `shadowed-type-variable`\n\n\nDefault level: error ·\nAdded in 0.0.20 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for type variables in nested generic classes or functions that shadow type variables\nfrom an enclosing scope.\n\n**Why is this bad?**\n\nShadowing type variables makes the code confusing and is disallowed by the typing spec.\n\n**Examples**\n\n```python\nclass Outer[T]:\n # Error: `T` is already used by `Outer`\n class Inner[T]: ...\n\n # Error: `T` is already used by `Outer`\n def method[T](self, x: T) -> T: ...\n```\n\n**References**\n\n- [Typing spec: Generics](https://typing.python.org/en/latest/spec/generics.html#introduction)\n\n## `static-assert-error`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nMakes sure that the argument of `static_assert` is statically known to be true.\n\n**Why is this bad?**\n\nA `static_assert` call represents an explicit request from the user\nfor the type checker to emit an error if the argument cannot be verified\nto evaluate to `True` in a boolean context.\n\n**Examples**\n\n```python\nfrom ty_extensions import static_assert\n\nstatic_assert(1 + 1 == 3) # error: evaluates to `False`\n\nstatic_assert(int(2.0 * 3.0) == 6) # error: does not have a statically known truthiness\n```\n\n## `subclass-of-final-class`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for classes that subclass final classes.\n\n**Why is this bad?**\n\nDecorating a class with `@final` declares to the type checker that it should not be subclassed.\n\n**Example**\n\n\n```python\nfrom typing import final\n\n@final\nclass A: ...\nclass B(A): ... # Error raised here\n```\n\n## `super-call-in-named-tuple-method`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.30 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for calls to `super()` inside methods of `NamedTuple` classes.\n\n**Why is this bad?**\n\nUsing `super()` in a method of a `NamedTuple` class will raise an exception at runtime.\n\n**Examples**\n\n```python\nfrom typing import NamedTuple\n\nclass F(NamedTuple):\n x: int\n\n def method(self):\n super() # error: super() is not supported in methods of NamedTuple classes\n```\n\n**References**\n\n- [Python documentation: super()](https://docs.python.org/3/library/functions.html#super)\n\n## `too-many-positional-arguments`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for calls that pass more positional arguments than the callable can accept.\n\n**Why is this bad?**\n\nPassing too many positional arguments will raise `TypeError` at runtime.\n\n**Example**\n\n\n```python\ndef f(): ...\n\nf(\"foo\") # Error raised here\n```\n\n## `type-assertion-failure`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for `assert_type()` and `assert_never()` calls where the actual type\nis not the same as the asserted type.\n\n**Why is this bad?**\n\n`assert_type()` allows confirming the inferred type of a certain value.\n\n**Example**\n\n\n```python\ndef _(x: int):\n assert_type(x, int) # fine\n assert_type(x, str) # error: Actual type does not match asserted type\n```\n\n## `unavailable-implicit-super-arguments`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects invalid `super()` calls where implicit arguments like the enclosing class or first method argument are unavailable.\n\n**Why is this bad?**\n\nWhen `super()` is used without arguments, Python tries to find two things:\nthe nearest enclosing class and the first argument of the immediately enclosing function (typically self or cls).\nIf either of these is missing, the call will fail at runtime with a `RuntimeError`.\n\n**Examples**\n\n```python\nsuper() # error: no enclosing class or function found\n\ndef func():\n super() # error: no enclosing class or first argument exists\n\nclass A:\n f = super() # error: no enclosing function to provide the first argument\n\n def method(self):\n def nested():\n super() # error: first argument does not exist in this nested function\n\n lambda: super() # error: first argument does not exist in this lambda\n\n (super() for _ in range(10)) # error: argument is not available in generator expression\n\n super() # okay! both enclosing class and first argument are available\n```\n\n**References**\n\n- [Python documentation: super()](https://docs.python.org/3/library/functions.html#super)\n\n## `unbound-type-variable`\n\n\nDefault level: error ·\nAdded in 0.0.20 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for type variables that are used in a scope where they are not bound\nto any enclosing generic context.\n\n**Why is this bad?**\n\nUsing a type variable outside of a scope that binds it has no well-defined meaning.\n\n**Examples**\n\n```python\nfrom typing import TypeVar, Generic\n\nT = TypeVar(\"T\")\nS = TypeVar(\"S\")\n\nx: T # error: unbound type variable in module scope\n\nclass C(Generic[T]):\n x: list[S] = [] # error: S is not in this class's generic context\n```\n\n**References**\n\n- [Typing spec: Scoping rules for type variables](https://typing.python.org/en/latest/spec/generics.html#scoping-rules-for-type-variables)\n\n## `undefined-reveal`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for calls to `reveal_type` without importing it.\n\n**Why is this bad?**\n\nUsing `reveal_type` without importing it will raise a `NameError` at runtime.\n\n**Examples**\n\n```python\nreveal_type(1) # NameError: name 'reveal_type' is not defined\n```\n\n## `unknown-argument`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for keyword arguments in calls that don't match any parameter of the callable.\n\n**Why is this bad?**\n\nProviding an unknown keyword argument will raise `TypeError` at runtime.\n\n**Example**\n\n\n```python\ndef f(x: int) -> int: ...\n\nf(x=1, y=2) # Error raised here\n```\n\n## `unresolved-attribute`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for unresolved attributes.\n\n**Why is this bad?**\n\nAccessing an unbound attribute will raise an `AttributeError` at runtime.\nAn unresolved attribute is not guaranteed to exist from the type alone,\nso this could also indicate that the object is not of the type that the user expects.\n\n**Examples**\n\n```python\nclass A: ...\n\nA().foo # AttributeError: 'A' object has no attribute 'foo'\n```\n\n## `unresolved-global`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.15 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nDetects variables declared as `global` in an inner scope that have no explicit\nbindings or declarations in the global scope.\n\n**Why is this bad?**\n\nFunction bodies with `global` statements can run in any order (or not at all), which makes\nit hard for static analysis tools to infer the types of globals without\nexplicit definitions or declarations.\n\n**Example**\n\n```python\ndef f():\n global x # unresolved global\n x = 42\n\ndef g():\n print(x) # unresolved reference\n```\n\nUse instead:\n\n```python\nx: int\n\ndef f():\n global x\n x = 42\n\ndef g():\n print(x)\n```\n\nOr:\n\n```python\nx: int | None = None\n\ndef f():\n global x\n x = 42\n\ndef g():\n print(x)\n```\n\n## `unresolved-import`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for import statements for which the module cannot be resolved.\n\n**Why is this bad?**\n\nImporting a module that cannot be resolved will raise a `ModuleNotFoundError`\nat runtime.\n\n**Examples**\n\n```python\nimport foo # ModuleNotFoundError: No module named 'foo'\n```\n\n## `unresolved-reference`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for references to names that are not defined.\n\n**Why is this bad?**\n\nUsing an undefined variable will raise a `NameError` at runtime.\n\n**Example**\n\n\n```python\nprint(x) # NameError: name 'x' is not defined\n```\n\n## `unsupported-base`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.7 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for class definitions that have bases which are unsupported by ty.\n\n**Why is this bad?**\n\nIf a class has a base that is an instance of a complex type such as a union type,\nty will not be able to resolve the [method resolution order] (MRO) for the class.\nThis will lead to an inferior understanding of your codebase and unpredictable\ntype-checking behavior.\n\n**Examples**\n\n```python\nimport datetime\n\nclass A: ...\nclass B: ...\n\nif datetime.date.today().weekday() != 6:\n C = A\nelse:\n C = B\n\nclass D(C): ... # error: [unsupported-base]\n```\n\n[method resolution order]: https://docs.python.org/3/glossary.html#term-method-resolution-order\n\n## `unsupported-bool-conversion`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for bool conversions where the object doesn't correctly implement `__bool__`.\n\n**Why is this bad?**\n\nIf an exception is raised when you attempt to evaluate the truthiness of an object,\nusing the object in a boolean context will fail at runtime.\n\n**Examples**\n\n\n```python\nclass NotBoolable:\n __bool__ = None\n\nb1 = NotBoolable()\nb2 = NotBoolable()\n\nif b1: # exception raised here\n pass\n\nb1 and b2 # exception raised here\nnot b1 # exception raised here\nb1 < b2 < b1 # exception raised here\n```\n\n## `unsupported-dynamic-base`\n\n\nDefault level: ignore ·\nAdded in 0.0.12 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for dynamic class definitions (using `type()`) that have bases\nwhich are unsupported by ty.\n\nThis is equivalent to [`unsupported-base`](#unsupported-base) but applies to classes created\nvia `type()` rather than `class` statements.\n\n**Why is this bad?**\n\nIf a dynamically created class has a base that is an unsupported type\nsuch as `type[T]`, ty will not be able to resolve the\n[method resolution order] (MRO) for the class. This may lead to an inferior\nunderstanding of your codebase and unpredictable type-checking behavior.\n\n**Default level**\n\nThis rule is disabled by default because it will not cause a runtime error,\nand may be noisy on codebases that use `type()` in highly dynamic ways.\n\n**Examples**\n\n```python\ndef factory(base: type[Base]) -> type:\n # `base` has type `type[Base]`, not `type[Base]` itself\n return type(\"Dynamic\", (base,), {}) # error: [unsupported-dynamic-base]\n```\n\n[method resolution order]: https://docs.python.org/3/glossary.html#term-method-resolution-order\n\n## `unsupported-operator`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for binary expressions, comparisons, and unary expressions where\nthe operands don't support the operator.\n\n**Why is this bad?**\n\nAttempting to use an unsupported operator will raise a `TypeError` at\nruntime.\n\n**Examples**\n\n```python\nclass A: ...\n\nA() + A() # TypeError: unsupported operand type(s) for +: 'A' and 'A'\n```\n\n## `unused-awaitable`\n\n\nDefault level: warn ·\nPreview (since 0.0.21) ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for awaitable objects (such as coroutines) used as expression\nstatements without being awaited.\n\n**Why is this bad?**\n\nCalling an `async def` function returns a coroutine object. If the\ncoroutine is never awaited, the body of the async function will never\nexecute, which is almost always a bug. Python emits a\n`RuntimeWarning: coroutine was never awaited` at runtime in this case.\n\n**Examples**\n\n```python\nasync def fetch_data() -> str:\n return \"data\"\n\nasync def main() -> None:\n fetch_data() # Warning: coroutine is not awaited\n await fetch_data() # OK\n```\n\n## `unused-ignore-comment`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for `ty: ignore` directives that are no longer applicable.\n\n**Why is this bad?**\n\nA `ty: ignore` directive that no longer matches any diagnostic violations is likely\nincluded by mistake, and should be removed to avoid confusion.\n\n**Examples**\n\n```py\na = 20 / 2 # ty: ignore[division-by-zero]\n```\n\nUse instead:\n\n```py\na = 20 / 2\n```\n\n**Options**\n\nSet [`analysis.respect-type-ignore-comments`](https://docs.astral.sh/ty/reference/configuration/#respect-type-ignore-comments)\nto `false` to prevent this rule from reporting unused `type: ignore` comments.\n\n## `unused-type-ignore-comment`\n\n\nDefault level: warn ·\nAdded in 0.0.14 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for `type: ignore` directives that are no longer applicable.\n\n**Why is this bad?**\n\nA `type: ignore` directive that no longer matches any diagnostic violations is likely\nincluded by mistake, and should be removed to avoid confusion.\n\n**Examples**\n\n```py\na = 20 / 2 # type: ignore\n```\n\nUse instead:\n\n```py\na = 20 / 2\n```\n\n**Options**\n\n\nThis rule is skipped if [`analysis.respect-type-ignore-comments`](https://docs.astral.sh/ty/reference/configuration/#respect-type-ignore-comments)\nto `false`.\n\n## `useless-overload-body`\n\n\nDefault level: warn ·\nAdded in 0.0.1-alpha.22 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for various `@overload`-decorated functions that have non-stub bodies.\n\n**Why is this bad?**\n\nFunctions decorated with `@overload` are ignored at runtime; they are overridden\nby the implementation function that follows the series of overloads. While it is\nnot illegal to provide a body for an `@overload`-decorated function, it may indicate\na misunderstanding of how the `@overload` decorator works.\n\n**Example**\n\n\n```py\nfrom typing import overload\n\n@overload\ndef foo(x: int) -> int:\n return x + 1 # will never be executed\n\n@overload\ndef foo(x: str) -> str:\n return \"Oh no, got a string\" # will never be executed\n\ndef foo(x: int | str) -> int | str:\n raise Exception(\"unexpected type encountered\")\n```\n\nUse instead:\n\n```py\nfrom typing import assert_never, overload\n\n@overload\ndef foo(x: int) -> int: ...\n\n@overload\ndef foo(x: str) -> str: ...\n\ndef foo(x: int | str) -> int | str:\n if isinstance(x, int):\n return x + 1\n elif isinstance(x, str):\n return \"Oh no, got a string\"\n else:\n assert_never(x)\n```\n\n**References**\n\n- [Python documentation: `@overload`](https://docs.python.org/3/library/typing.html#typing.overload)\n\n## `zero-stepsize-in-slice`\n\n\nDefault level: error ·\nAdded in 0.0.1-alpha.1 ·\nRelated issues ·\nView source\n\n\n\n**What it does**\n\nChecks for step size 0 in slices.\n\n**Why is this bad?**\n\nA slice with a step size of zero will raise a `ValueError` at runtime.\n\n**Examples**\n\n```python\nl = list(range(10))\nl[1:10:0] # ValueError: slice step cannot be zero\n```\n\n"
},
{
"path": "docs/reference/typing-faq.md",
"content": "# Typing FAQ\n\nThis page answers some commonly asked questions about ty and Python's type system.\n\n## Why does ty report an error on my code?\n\nCheck the [documentation](https://docs.astral.sh/ty/reference/rules/) for the specific error code\nyou are seeing; it may explain the problem.\n\n## What is the `Unknown` type and when does it appear?\n\n`Unknown` is ty's way of representing a type that could not be fully inferred. It behaves the same\nway as `Any`, but appears implicitly, rather than through an explicit `Any` annotation:\n\n```py\nfrom missing_module import MissingClass # error: unresolved-import\n\nreveal_type(MissingClass) # Unknown\n```\n\nty also uses unions with `Unknown` to maintain the\n[gradual guarantee](../features/type-system.md#gradual-guarantee), which helps avoid false positive\nerrors in untyped code while still providing useful type information where possible.\n\nFor example, consider the following untyped `Message` class (which could come from a third-party\ndependency that you have no control over). ty treats the `data` attribute as having type\n`Unknown | None`, since there is no type annotation that restricts it further. The `Unknown` in the\nunion allows ty to avoid raising errors on the `msg.data = …` assignment. On the other hand, the\n`None` in the union reflects the fact that `data` *could* possibly be `None`, and requires code that\nuses `msg.data` to handle that case explicitly.\n\n```py\nclass Message:\n data = None\n\n def __init__(self, title):\n self.title = title\n\n\ndef receive(msg: Message):\n reveal_type(msg.data) # Unknown | None\n\n\nmsg = Message(\"Favorite color\")\nmsg.data = {\"color\": \"blue\"}\n```\n\n([Full example in the playground](https://play.ty.dev/862941a8-a3f6-4818-9ea1-d9d59b0bd2fa))\n\n## Why does ty show `int | float` when I annotate something as `float`?\n\nThe [Python typing specification](https://typing.python.org/en/latest/spec/special-types.html)\nincludes a special rule for numeric types where an `int` can be used wherever a `float` is expected:\n\n```py\ndef circle_area(radius: float) -> float:\n return 3.14 * radius * radius\n\ncircle_area(2) # OK: int is allowed where float is expected\n```\n\nThis rule is a special case, since `int` is not actually a subclass of `float`. To support this, ty\ntreats `float` annotations as meaning `int | float`. Unlike some other type checkers, ty makes this\nbehavior explicit in type hints and error messages. For example, if you\n[hover over the `radius` parameter](https://play.ty.dev/fdc144c6-031c-4af9-b520-a4c6ccde9261), ty\nwill show `int | float`.\n\nA similar rule applies to `complex`, which is treated as `int | float | complex`.\n\n!!! info\n\n These special rules for `float` and `complex` exist for a reason. In almost all cases, you\n probably want to accept both `int` and `float` when you annotate something as `float`.\n If you really need to accept *only* `float` and not `int`, you can use ty's `JustFloat`\n type. At the time of writing, this import needs to be guarded by a `TYPE_CHECKING` block:\n\n ```py\n from typing import TYPE_CHECKING\n\n if TYPE_CHECKING:\n from ty_extensions import JustFloat\n else:\n JustFloat = float\n\n def only_actual_floats_allowed(f: JustFloat) -> None: ...\n\n only_actual_floats_allowed(1.0) # OK\n only_actual_floats_allowed(1) # error: invalid-argument-type\n ```\n\n ([Full example in the playground](https://play.ty.dev/fb034780-3ba7-4c6a-9449-5b0f44128bab))\n\n If you need this for `complex`, you can use `ty_extensions.JustComplex` in a similar way.\n\n## Why can't I use `list[Subtype]` when a `list[Supertype]` is expected? { #invariant-generics }\n\nLet's say you have a class hierarchy with an `Entry` base class as well as `Directory` and `File` subclasses. Since\na `Directory` *is* an `Entry`, you can use it everywhere an `Entry` is expected.\nYou might therefore expect a `list[Directory]` to\nbe usable in any context where a `list[Entry]` is expected, but this is not\nthe case. The reason for this is mutability:\n\n```py\n# Setup of `Entry`, `Directory`, and `File` classes (1)\n\ndef modify(entries: list[Entry]):\n entries.append(File(\"README.txt\")) # mutation\n\ndirectories: list[Directory] = [Directory(\"Downloads\"), Directory(\"Documents\")]\nmodify(directories) # ty emits an error on this call\n```\n\n1. The full example might look like this:\n\n ```py\n from dataclasses import dataclass\n\n @dataclass\n class Entry:\n path: str\n def size_bytes(self) -> int: ...\n\n @dataclass\n class Directory(Entry):\n def children(self) -> list[Entry]: ...\n\n @dataclass\n class File(Entry):\n def content(self) -> bytes: ...\n\n def modify(entries: list[Entry]):\n entries.append(File(\"README.txt\")) # mutation\n\n directories: list[Directory] = [Directory(\"Downloads\"), Directory(\"Documents\")]\n modify(directories) # ty emits an error on this call\n ```\n\n You can try it out in [this playground example](https://play.ty.dev/01013e73-da54-40c4-a9c5-2af269abda9d).\n\nThe `modify` call mutates the contents of the `directories` list. After this call,\nit contains two directories *and one `File`*, which clearly violates the\n`list[Directory]` type annotation. If this call *were* allowed, subsequent code\nthat relies on the fact that `directories` only contains `Directory` instances might\nbreak at runtime:\n\n```py\nfor directory in directories:\n directory.children() # runtime: 'File' object has no attribute 'children'\n```\n\n!!! info\n\n In type system terminology, we say `list` is *invariant*, which means that\n just because `A` is a subtype of `B` does not mean that `list[A]` will be a\n subtype of `list[B]`. The same is true for other builtin collections such as\n `set` or `dict`. In contrast, read-only collections like `tuple` or\n `frozenset` are *covariant* in their type parameter. It is safe to assign a\n `frozenset[bool]` to a `frozenset[int]` because the contents cannot be\n mutated.\n\nYou might run into problems with invariance in situations where mutability isn't\nrequired:\n\n```py\ndef total_size_bytes(entries: list[Entry]) -> int:\n return sum(entry.size_bytes() for entry in entries)\n\n# inferred as `list[Directory]`\nmedia_entries = [Directory(\"Pictures\"), Directory(\"Videos\")]\n\n# still a type-check error, but should be fine in principle (no mutation occurs)\nsize = total_size_bytes(media_entries)\n```\n\nTo prevent this, you can adapt the signature of `total_size_bytes` to take an\nargument of type\n[`Sequence[Entry]`](https://docs.python.org/3/library/collections.abc.html#collections-abstract-base-classes)\ninstead. This type describes read-only sequences (that contain values of type\n`Entry`). `Sequence` is therefore covariant in its type parameter.\n\nIf you cannot adapt the signature of the function you are calling, you can also\nwiden the type of the argument by annotating `media_entries` as `list[Entry]`.\nIn some cases it's also a reasonable solution to create a copy of the list\n(`total_size_bytes(list(media_entries))`).\n\n!!! note\n\n If you are looking for a covariant alternative to `dict[str, V]`, you can use [`Mapping[str, V]`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping).\n\n## Why does ty say `Callable` has no attribute `__name__`?\n\nWhen you access `__name__`, `__qualname__`, `__module__`, or `__doc__` on a value typed as `Callable`,\nty reports an `unresolved-attribute` error. This is because not all callables have these attributes.\nFunctions do (including lambdas), but other callable objects do not. The `FileUpload` class below, for\nexample, is callable, but instances of `FileUpload` do not have a `__name__` attribute. Passing a\n`FileUpload` instance to `retry` would lead to an `AttributeError` at runtime.\n\n```py\nfrom typing import Callable\n\ndef retry(times: int, operation: Callable[[], bool]) -> bool:\n for i in range(times):\n # WRONG: `operation` does not necessarily have a `__name__` attribute\n print(f\"Calling {operation.__name__}, attempt {i + 1} of {times}\")\n if operation():\n return True\n return False\n\nclass FileUpload:\n def __init__(self, name: str) -> None:\n # …\n\n def __call__(self) -> bool:\n # …\n\nretry(3, FileUpload(\"image.png\"))\n```\n\nTo fix this, you could use `getattr` with a fall back to a default name when the\nattribute is not present (or use a `hasattr(…, \"__name__\")` check if you access\nit multiple times):\n\n```py\nname = getattr(operation, \"__name__\", \"operation\")\n```\n\nAlternatively, you could use an `isinstance(…, types.FunctionType)` check to narrow the type of\n`operation` to something that definitely has a `__name__` attribute:\n\n```py\nif isinstance(operation, FunctionType):\n print(f\"Calling {operation.__name__}, attempt {i + 1} of {times}\")\nelse:\n print(f\"Calling operation, attempt {i + 1} of {times}\")\n```\n\nYou can try various approaches in [this playground example](https://play.ty.dev/f6f7f35a-47c3-423d-be8d-33d03c61d40c).\nSee also [this discussion](https://github.com/astral-sh/ty/issues/1495) for some plans to improve\nthe developer experience around this in the future.\n\n!!! info\n\n ty has first-class support for intersection types. If you only want to accept function-like\n callables, you could define `FunctionLikeCallable` as an intersection of `Callable` and\n `types.FunctionType`:\n\n ```py\n from typing import Callable, TYPE_CHECKING\n from types import FunctionType\n\n if TYPE_CHECKING:\n from ty_extensions import Intersection\n\n type FunctionLikeCallable[**P, R] = Intersection[Callable[P, R], FunctionType]\n else:\n FunctionLikeCallable = Callable\n\n\n def retry(times: int, operation: FunctionLikeCallable[[], bool]) -> bool:\n ...\n ```\n\n You can check out the full example [here](https://play.ty.dev/7a1ea4ab-04e1-4271-adf5-ddc3a5d2fcfd),\n which demonstrates that `FileUpload` instances are no longer accepted by `retry`.\n\n## Does ty have a strict mode?\n\nNot yet. A stricter inference mode is tracked in\n[this issue](https://github.com/astral-sh/ty/issues/1240). In the meantime, you can consider using Ruff's\n[`flake8-annotations` rules](https://docs.astral.sh/ruff/rules/#flake8-annotations-ann) to enforce\nmore explicit type annotations in your code.\n\n## Why doesn't ty warn about missing type annotations?\n\nty does not report an error for unannotated function parameters, return types, or variables. When\nty encounters an unannotated symbol, it infers the type as [`Unknown`](#what-is-the-unknown-type-and-when-does-it-appear)\nwhile still providing useful diagnostics where possible.\n\nIf you are looking for the equivalent of mypy's\n[`disallow_untyped_defs`](https://mypy.readthedocs.io/en/stable/config_file.html#confval-disallow_untyped_defs)\n(error code: `no-untyped-def`), Ruff provides this as a set of opt-in lint rules via its\n[`flake8-annotations` (`ANN`)](https://docs.astral.sh/ruff/rules/#flake8-annotations-ann) rule\ngroup.\n\nSome rules you might find useful include:\n\n- [`ANN001`](https://docs.astral.sh/ruff/rules/missing-type-function-argument/): Missing type\n annotation for function argument\n- [`ANN002`](https://docs.astral.sh/ruff/rules/missing-type-args/): Missing type annotation for\n `*args`\n- [`ANN003`](https://docs.astral.sh/ruff/rules/missing-type-kwargs/): Missing type annotation for\n `**kwargs`\n- [`ANN201`](https://docs.astral.sh/ruff/rules/missing-return-type-undocumented-public-function/):\n Missing return type annotation for public function\n- [`ANN202`](https://docs.astral.sh/ruff/rules/missing-return-type-private-function/): Missing\n return type annotation for private function\n- [`RUF045`](https://docs.astral.sh/ruff/rules/implicit-class-var-in-dataclass/): Implicit class\n variable in dataclass\n\n## Why can't ty resolve my imports?\n\nImport resolution issues are often caused by a missing or incorrect environment configuration. When\nty reports *\"Cannot resolve imported module …\"*, check the following:\n\n1. **Virtual environment**: Make sure your virtual environment is discoverable. ty looks for an\n active virtual environment via `VIRTUAL_ENV` or a `.venv` directory in your project root. See the\n [module discovery](../modules.md#python-environment) documentation for more details.\n\n1. **Project structure**: If your source code is not in the project root or `src/` directory,\n configure [`environment.root`](./configuration.md#root) in your `pyproject.toml`:\n\n ```toml\n [tool.ty.environment]\n root = [\"./app\"]\n ```\n\n1. **Third-party packages**: Ensure dependencies are installed in your virtual environment. Run ty\n with `-v` to see the search paths being used.\n\n1. **Compiled extensions**: ty requires `.py` or `.pyi` files for type information. If a package\n contains only compiled extensions (`.so` or `.pyd` files), you'll need stub files (`.pyi`) for ty\n to understand the types. See also [this issue](https://github.com/astral-sh/ty/issues/487) which\n tracks improvements in this area.\n\n## Does ty support monorepos?\n\nty can work with monorepos, but automatic discovery of nested projects is limited. By default, ty\nuses the current working directory or the `--project` option to determine the project root.\n\nFor monorepos with multiple Python packages, you have a few options:\n\n1. **Run ty per-package**: Run `ty check` from each package directory, or use `--project` to specify\n the package:\n\n ```bash\n ty check --project packages/package-a\n ty check --project packages/package-b\n ```\n\n1. **Configure multiple source roots**: Use [`environment.root`](./configuration.md#root) to specify\n multiple source directories:\n\n ```toml\n [tool.ty.environment]\n root = [\"packages/package-a\", \"packages/package-b\"]\n ```\n\n This has the disadvantage of treating all packages as a single project, which may lead to cases\n in which ty thinks something is importable when it wouldn't be at runtime.\n\nYou can follow [this issue](https://github.com/astral-sh/ty/issues/819) to get updates on this\ntopic.\n\n## Does ty support PEP 723 inline-metadata scripts?\n\nIt depends on what you want to do. If you have a single inline-metadata script, you can type check\nit with ty by using uv's `--with-requirements` flag to install the dependencies specified in the\nscript header:\n\n```bash\nuvx --with-requirements script.py ty check script.py\n```\n\nIf you have multiple scripts in your workspace, ty does not yet recognize that they have different\ndependencies based on their inline metadata.\n\nYou can follow [this issue](https://github.com/astral-sh/ty/issues/691) for updates.\n\n## Is there a pre-commit hook for ty?\n\nNot yet. You can track progress in [this issue](https://github.com/astral-sh/ty/issues/269), which\nalso includes some suggested manual hooks you can use in the meantime.\n\n## Does ty support (mypy) plugins?\n\nNo. ty does not have a plugin system and there is currently no plan to add one.\n\nWe prefer extending the type system with well-specified features rather than relying on\ntype-checker-specific plugins. That said, we are considering adding support for popular third-party\nlibraries like pydantic, SQLAlchemy, attrs, or django directly into ty.\n\n## What is `Top[list[Unknown]]`, and why does it appear?\n\nThis type represents \"all possible lists of any element type\" (as opposed to `list[Unknown]`, which\nrepresents \"a list of some unknown element type\"). It usually arises from a check such as\n`if isinstance(x, list):`. If `x` was previously of type `Item | list[Item]`, you might expect this\ncheck to narrow the type to `list[Item]`, but ty respects the possibility that there could be a\ncommon subclass of both `Item` and `list` (which may not be a list of `Item`!), and so the narrowed\ntype is instead `(Item & Top[list[Unknown]]) | list[Item]`. This code can be made more robust by\ninstead checking `if instance(x, Item)`, or by declaring the `Item` type as `@typing.final`.\n\nSee also the [discussion\nhere](https://docs.astral.sh/ty/features/type-system/#top-and-bottom-materializations) and [in this\nissue](https://github.com/astral-sh/ty/issues/1578).\n"
},
{
"path": "docs/requirements.in",
"content": "black>=23.10.0\nmkdocs>=1.5.0\nmkdocs-material>=9.7.0\nmkdocs-redirects>=1.2.1\nmdformat>=0.7.17\nmdformat-mkdocs>=2.0.4\nmdformat-admon>=2.0.2\nmkdocs-redirects>=1.2.2\nmkdocs-git-revision-date-localized-plugin>=1.3.0\nmkdocs-llmstxt>=0.2.0\n"
},
{
"path": "docs/requirements.txt",
"content": "# This file was autogenerated by uv via the following command:\n# uv pip compile docs/requirements.in -o docs/requirements.txt --universal -p 3.12\nbabel==2.15.0\n # via\n # mkdocs-git-revision-date-localized-plugin\n # mkdocs-material\nbackrefs==6.1\n # via mkdocs-material\nbeautifulsoup4==4.13.4\n # via\n # markdownify\n # mkdocs-llmstxt\nblack==24.4.2\n # via -r docs/requirements.in\ncertifi==2024.7.4\n # via requests\ncharset-normalizer==3.3.2\n # via requests\nclick==8.1.7\n # via\n # black\n # mkdocs\ncolorama==0.4.6\n # via\n # click\n # mkdocs\n # mkdocs-material\nghp-import==2.1.0\n # via mkdocs\ngitdb==4.0.12\n # via gitpython\ngitpython==3.1.44\n # via mkdocs-git-revision-date-localized-plugin\nidna==3.7\n # via requests\njinja2==3.1.4\n # via\n # mkdocs\n # mkdocs-material\nlinkify-it-py==2.0.3\n # via markdown-it-py\nmarkdown==3.6\n # via\n # mkdocs\n # mkdocs-material\n # pymdown-extensions\nmarkdown-it-py==3.0.0\n # via\n # mdformat\n # mdformat-gfm\n # mdit-py-plugins\nmarkdownify==1.1.0\n # via mkdocs-llmstxt\nmarkupsafe==2.1.5\n # via\n # jinja2\n # mkdocs\nmdformat==0.7.22\n # via\n # -r docs/requirements.in\n # mdformat-admon\n # mdformat-gfm\n # mdformat-mkdocs\n # mdformat-tables\n # mkdocs-llmstxt\nmdformat-admon==2.0.6\n # via\n # -r docs/requirements.in\n # mdformat-mkdocs\nmdformat-gfm==0.3.6\n # via mdformat-mkdocs\nmdformat-mkdocs==3.0.0\n # via -r docs/requirements.in\nmdformat-tables==0.4.1\n # via mdformat-gfm\nmdit-py-plugins==0.4.1\n # via\n # mdformat-admon\n # mdformat-gfm\n # mdformat-mkdocs\nmdurl==0.1.2\n # via markdown-it-py\nmergedeep==1.3.4\n # via\n # mkdocs\n # mkdocs-get-deps\nmkdocs==1.6.0\n # via\n # -r docs/requirements.in\n # mkdocs-git-revision-date-localized-plugin\n # mkdocs-material\n # mkdocs-redirects\nmkdocs-get-deps==0.2.0\n # via mkdocs\nmkdocs-git-revision-date-localized-plugin==1.3.0\n # via -r docs/requirements.in\nmkdocs-llmstxt==0.2.0\n # via -r docs/requirements.in\nmkdocs-material==9.7.0\n # via -r docs/requirements.in\nmkdocs-material-extensions==1.3.1\n # via mkdocs-material\nmkdocs-redirects==1.2.2\n # via -r docs/requirements.in\nmore-itertools==10.3.0\n # via mdformat-mkdocs\nmypy-extensions==1.0.0\n # via black\npackaging==24.1\n # via\n # black\n # mkdocs\npaginate==0.5.6\n # via mkdocs-material\npathspec==0.12.1\n # via\n # black\n # mkdocs\nplatformdirs==4.2.2\n # via\n # black\n # mkdocs-get-deps\npygments==2.18.0\n # via mkdocs-material\npymdown-extensions==10.8.1\n # via mkdocs-material\npython-dateutil==2.9.0.post0\n # via ghp-import\npytz==2025.1\n # via mkdocs-git-revision-date-localized-plugin\npyyaml==6.0.1\n # via\n # mkdocs\n # mkdocs-get-deps\n # pymdown-extensions\n # pyyaml-env-tag\npyyaml-env-tag==0.1\n # via mkdocs\nrequests==2.32.3\n # via mkdocs-material\nsix==1.16.0\n # via\n # markdownify\n # python-dateutil\nsmmap==5.0.2\n # via gitdb\nsoupsieve==2.7\n # via beautifulsoup4\ntyping-extensions==4.14.0\n # via beautifulsoup4\nuc-micro-py==1.0.3\n # via linkify-it-py\nurllib3==2.2.2\n # via requests\nwatchdog==4.0.1\n # via mkdocs\n"
},
{
"path": "docs/rules.md",
"content": "# Rules\n\nRules are individual checks that ty performs to detect common issues in your code, such as\nincompatible assignments, missing imports, or invalid type annotations. Each rule focuses on a\nspecific pattern and can be turned on or off depending on your project’s needs.\n\n!!! tip\n\n See the [rules reference](./reference/rules.md) for an enumeration of all supported rules.\n\n## Rule levels\n\nEach rule has a configurable level:\n\n- `error`: violations are reported as errors and ty exits with an exit code of 1 if there's any.\n- `warn`: violations are reported as warnings. Depending on your configuration, ty exits with an exit code of 0 if there are only warning violations (default) or 1 when using `--error-on-warning`.\n- `ignore`: the rule is turned off\n\nYou can configure the level for each rule on the command line using the `--warn`, `--error`, and\n`--ignore` flags. For example:\n\n```shell\n\nty check \\\n --warn unused-ignore-comment \\ # Make `unused-ignore-comment` a warning\n --ignore redundant-cast \\ # Disable `redundant-cast`\n --error possibly-missing-attribute \\ # Error on `possibly-missing-attribute`\n --error possibly-missing-import # Error on `possibly-missing-import`\n```\n\nThe options can be repeated. Subsequent options override earlier options.\n\nRule levels can also be changed in the [`rules`](./reference/configuration.md#rules) section of a\n[configuration file](./configuration.md).\n\nFor example, the following is equivalent to the command above:\n\n```toml title=\"pyproject.toml\"\n[tool.ty.rules]\nunused-ignore-comment = \"warn\"\nredundant-cast = \"ignore\"\npossibly-missing-attribute = \"error\"\npossibly-missing-import = \"error\"\n```\n\nYou can also configure the level for all rules at once.\n\nOn the command line you can use `--error all`, `--warn all`, or `--ignore all`. For example:\n\n```shell\n\nty check --error all\n```\n\nYou can also configure this setting in the [`rules`](./reference/configuration.md#rules) section of a\n[configuration file](./configuration.md).\n\nFor example, the following is equivalent to the command above:\n\n```toml title=\"pyproject.toml\"\n[tool.ty.rules]\nall = \"error\"\n```\n"
},
{
"path": "docs/stylesheets/extra.css",
"content": ":root {\n --black: #261230;\n --white: #ffffff;\n --radiate: #d7ff64;\n --flare: #6340ac;\n --rock: #78876e;\n --galaxy: #261230;\n --space: #30173d;\n --comet: #6f5d6f;\n --cosmic: #de5fe9;\n --sun: #ffac2f;\n --electron: #46ebe1;\n --aurora: #46eb74;\n --constellation: #5f6de9;\n --neutron: #cff3cf;\n --proton: #f6afbc;\n --nebula: #cdcbfb;\n --supernova: #f1aff6;\n --starlight: #f4f4f1;\n --lunar: #fbf2fc;\n --asteroid: #e3cee3;\n --crater: #f0dfdf;\n}\n\n[data-md-color-scheme=\"astral-light\"] {\n --md-default-bg-color--dark: var(--black);\n --md-primary-fg-color: var(--galaxy);\n --md-typeset-a-color: var(--flare);\n --md-accent-fg-color: var(--cosmic);\n --md-default-fg-color--lightest: rgba(0, 0, 0, 0.14);\n}\n\n[data-md-color-scheme=\"astral-dark\"] {\n --md-default-bg-color: var(--galaxy);\n --md-default-fg-color: var(--white);\n --md-default-fg-color--light: var(--white);\n --md-default-fg-color--lighter: var(--white);\n --md-default-fg-color--lightest: rgba(255, 255, 255, 0.5);\n --md-primary-fg-color: var(--space);\n --md-primary-bg-color: var(--white);\n --md-accent-fg-color: var(--cosmic);\n\n --md-typeset-color: var(--white);\n --md-typeset-a-color: var(--radiate);\n --md-typeset-mark-color: var(--sun);\n\n --md-code-fg-color: var(--white);\n --md-code-bg-color: var(--space);\n\n --md-code-hl-comment-color: var(--asteroid);\n --md-code-hl-punctuation-color: var(--asteroid);\n --md-code-hl-generic-color: var(--supernova);\n --md-code-hl-variable-color: var(--starlight);\n --md-code-hl-string-color: var(--radiate);\n --md-code-hl-keyword-color: var(--supernova);\n --md-code-hl-operator-color: var(--supernova);\n --md-code-hl-number-color: var(--electron);\n --md-code-hl-special-color: var(--electron);\n --md-code-hl-function-color: var(--neutron);\n --md-code-hl-constant-color: var(--radiate);\n --md-code-hl-name-color: var(--md-code-fg-color);\n\n --md-typeset-del-color: hsla(6, 90%, 60%, 0.15);\n --md-typeset-ins-color: hsla(150, 90%, 44%, 0.15);\n\n --md-typeset-table-color: hsla(0, 0%, 100%, 0.12);\n --md-typeset-table-color--light: hsla(0, 0%, 100%, 0.035);\n}\n\n[data-md-color-scheme=\"astral-light\"] img[src$=\"#only-dark\"],\n[data-md-color-scheme=\"astral-light\"] img[src$=\"#gh-dark-mode-only\"] {\n display: none; /* Hide dark images in light mode */\n}\n\n[data-md-color-scheme=\"astral-light\"] img[src$=\"#only-light\"],\n[data-md-color-scheme=\"astral-light\"] img[src$=\"#gh-light-mode-only\"] {\n display: inline; /* Show light images in light mode */\n}\n\n[data-md-color-scheme=\"astral-dark\"] img[src$=\"#only-light\"],\n[data-md-color-scheme=\"astral-dark\"] img[src$=\"#gh-light-mode-only\"] {\n display: none; /* Hide light images in dark mode */\n}\n\n[data-md-color-scheme=\"astral-dark\"] img[src$=\"#only-dark\"],\n[data-md-color-scheme=\"astral-dark\"] img[src$=\"#gh-dark-mode-only\"] {\n display: inline; /* Show dark images in dark mode */\n}\n\n/* See: https://github.com/squidfunk/mkdocs-material/issues/175#issuecomment-616694465 */\n.md-typeset__table {\n min-width: 100%;\n}\n.md-typeset table:not([class]) {\n display: table;\n}\n\n/* See: https://github.com/astral-sh/ruff/issues/8519 */\n[data-md-color-scheme=\"astral-dark\"] details summary a {\n color: var(--flare);\n}\n\n/* See: https://github.com/astral-sh/ruff/issues/9046 */\n[data-md-color-scheme=\"astral-dark\"] div.admonition {\n color: var(--md-code-fg-color);\n background-color: var(--md-code-bg-color);\n}\n\n/* Prevent the shadow from the nav title from blurring the top link.\nThe box shadow isn't really doing anything anyway.\n\nThis is a consequence of the reduced nav spacing below. */\n.md-nav--primary .md-nav__title {\n box-shadow: none;\n}\n\n/* Omits the nav title \"ty\" entirely unless on a small screen, in which case\nthe nav title is needed for backwards navigation in the collapsible\nnav variant.\n\nSee https://github.com/astral-sh/uv/issues/5130 */\n@media screen and (min-width: 76.25em) {\n .md-nav__title {\n display: none;\n }\n}\n\n\n/* Always take the full screen for content, require scrolling to see the footer\nThis stops the size of the nav from jumping around when you visit a page without\na lot of content (i.e., an overview page). We don't apply this to sma screens\nbecause the nav is in a hamburger menu anyway\n*/\n@media screen and (min-width: 76.25em) {\n .md-main {\n min-height: 100vh;\n }\n}\n\n/* Tweak the formatting of the primary nav on a large screen */\n@media screen and (min-width: 76.25em) {\n .md-nav--primary .md-nav {\n font-size: 0.75rem;\n }\n /* Remove the bold from the section headings, use a larger font instead */\n .md-nav__item--section > .md-nav__link {\n font-weight: normal;\n font-size: 0.85rem;\n }\n /* Reducing spacing between nav items to fit more content \n First, disable `nav__link` spacing then use `nav__item` to enforce margins this reduces inconsistencies in the spacing. */\n .md-nav--primary .md-nav__link {\n margin: 0;\n }\n .md-nav--primary .md-nav__item {\n margin-top: 0.35em;\n }\n /* Use larger spacing for the sections headings */\n .md-nav--primary .md-nav__item--section {\n margin-bottom: 0.75em;\n margin-top: 1em;\n }\n /* Decrease the font size of items in a collapsible section */\n .md-nav__item--section> .md-nav > .md-nav__list > .md-nav__item > .md-nav > .md-nav__list {\n font-size: 0.725rem;\n }\n /* Increase top margin on the first item of a collapsible section */\n .md-nav__item--section> .md-nav > .md-nav__list > .md-nav__item > .md-nav > .md-nav__list > .md-nav__item:first-of-type {\n margin-top: 0.5em;\n }\n /* Increase bottom margin on the last item of a collapsible section */\n .md-nav__item--section> .md-nav > .md-nav__list > .md-nav__item > .md-nav > .md-nav__list > .md-nav__item:last-of-type {\n margin-bottom: 0.575em;\n }\n /* Increase the size of the first nav item to match the sections \n It has no children, so it is not considered a section */\n .md-nav--primary > .md-nav__list > .md-nav__item:first-of-type {\n font-size: 0.85rem;\n margin-bottom: 0.75em; \n }\n}\n\n/* Bold the active nav link for accessibility */\n.md-nav__link--active {\n font-weight: bold;\n}\n\n/* See: https://mkdocstrings.github.io/recipes/#prevent-selection-of-prompts-and-output-in-python-code-blocks */\n.highlight .gp, .highlight .go { /* Generic.Prompt, Generic.Output */\n user-select: none;\n}\n\n/* Styling for the generated CLI reference page */\n.cli-reference dd {\n margin-top: 0.1em;\n margin-bottom: 0.5em;\n}\n.cli-reference dd p {\n margin-block-start: 0.2em;\n margin-block-end: 0.3em;\n}\n.cli-reference ul {\n margin-bottom: 0.1em;\n}\nh3.cli-reference {\n font-size: 1.1em;\n margin: 0 0 0 0;\n}\n\n/* Styling for anchor link headers */\n.toclink {\n color: unset !important;\n}\n\n.toclink:hover {\n color: var(--md-accent-fg-color) !important;\n}\n\n/* Omit the first breadcrumb item, which is the \"Introduction\" */\n.md-path__list > .md-path__item:first-of-type {\n display: none;\n}\n.md-path__list > .md-path__item:nth-of-type(2):before {\n display: none;\n}\n\n/* Hide the modified date — its positioning is awkward but will require theme\nmodifications */\n.md-source-file__fact {\n visibility: hidden;\n}\n"
},
{
"path": "docs/suppression.md",
"content": "# Suppression\n\nRules can also be ignored in specific locations in your code (instead of disabling the rule\nentirely) to silence false positives or permissible violations.\n\n!!! note\n\n To disable a rule entirely, set it to the `ignore` level as described in [rule levels](rules.md/#rule-levels).\n\n## ty suppression comments\n\nTo suppress a rule violation inline add a `# ty: ignore[]` comment at the end of the line:\n\n```py\na = 10 + \"test\" # ty: ignore[unsupported-operator]\n```\n\nRule violations spanning multiple lines can be suppressed by adding the comment at the end of the\nviolation's first or last line:\n\n```py\ndef sum_three_numbers(a: int, b: int, c: int) -> int: ...\n\n# on the first line\n\nsum_three_numbers( # ty: ignore[missing-argument]\n 3,\n 2\n)\n\n# or, on the last line\n\nsum_three_numbers(\n 3,\n 2\n) # ty: ignore[missing-argument]\n```\n\nTo suppress multiple violations on a single line, enumerate each rule separated by a comma:\n\n```python\nsum_three_numbers(\"one\", 5) # ty: ignore[missing-argument, invalid-argument-type]\n```\n\n!!! note\n\n Enumerating rule names (e.g., `[rule1, rule2]`) is optional. However, we strongly recommend\n including suppressing specific rules to avoid accidental suppression of other errors.\n\n## Standard suppression comments\n\nty supports the standard [`type: ignore`](https://typing.python.org/en/latest/spec/directives.html#type-ignore-comments) comment\nformat introduced by PEP 484.\n\nty handles these similarly to `ty: ignore` comments, but suppresses all violations on that line,\neven when `type: ignore[code]` is used.\n\n```python\n# Ignore all typing errors on the next line\nsum_three_numbers(\"one\", 5) # type: ignore\n```\n\n## Multiple suppressions comments\n\nTo suppress a typing error on a line that already has a suppression comment from another tool,\nadd the `# ty: ignore` comment to the same line.\n\nFor example, to suppress a type error and disable formatting for a specific line:\n\n```python\nresult = calculate() # ty: ignore[invalid-argument-type] # fmt: skip\n\n# or\nresult = calculate() # fmt: off # ty: ignore[invalid-argument-type]\n```\n\n## Unused suppression comments\n\nIf the [`unused-ignore-comment`](./reference/rules.md#unused-ignore-comment) rule is enabled, ty\nwill report unused `ty: ignore` and `type: ignore` comments.\n\n`unused-ignore-comment` violations can only be suppressed using `# ty: ignore[unused-ignore-comment]`.\nThey cannot be suppressed using `# ty: ignore` without a rule code or `# type: ignore`.\n\n## `@no_type_check` directive\n\nty supports the\n[`@no_type_check`](https://typing.python.org/en/latest/spec/directives.html#no-type-check) decorator\nto suppress all violations inside a function.\n\n```python\nfrom typing import no_type_check\n\ndef sum_three_numbers(a: int, b: int, c: int) -> int:\n return a + b + c\n\n@no_type_check\ndef main():\n sum_three_numbers(1, 2) # no error for the missing argument\n```\n\nDecorating a class with `@no_type_check` isn't supported.\n"
},
{
"path": "docs/type-checking.md",
"content": "# Type checking\n\nAfter [installing ty](./installation.md), it's time to type check some code!\n\n## Running the type checker\n\nTo run the type checker, use the `check` command:\n\n```shell\nty check\n```\n\n!!! tip\n\n If you're in a project, you may need to use `uv run` or activate your virtual environment first\n for ty to find your dependencies.\n\n## Environment discovery\n\nThe type checker needs to discover your installed packages in order to check your use of imported\ndependencies.\n\nty will find installed packages in the active virtual environment (via `VIRTUAL_ENV`) or discover a\nvirtual environment named `.venv` in the project root or working directory. Failing that, ty will\nlook for a `python3` or `python` binary available in `PATH`. Alternatively, the `--python` flag can\nbe provided to ty to explicitly specify a path to a Python interpreter.\n\nSee the [module discovery](./modules.md) documentation for details.\n\n## File selection\n\nty will run on all Python files in the working directory (including subdirectories, recursively).\nIf used from a project, ty will run on all Python files in the project (starting in the directory\nwith the `pyproject.toml`).\n\nYou can also provide specific paths to check:\n\n```shell\nty check example.py\n```\n\nYou can also persistently configure [included and excluded files](./exclusions.md).\n\n## Rule selection and severity\n\nty's type checking diagnostics are often associated with a rule.\n\nty's type checking rules can be configured to your project's needs. See the [rules](./rules.md)\ndocumentation for details.\n\nYou can also suppress specific violations of rules using [suppression comments](./suppression.md).\n\n## Watch mode\n\nty can be run in an incremental watch mode:\n\n```shell\nty check --watch\n```\n\nty will watch files for changes and recheck any affected files — including files that depend on the\nchanged file. ty uses [fine-grained incrementality](./features/language-server.md#fine-grained-incrementality)\nto perform subsequent checks much faster than running `ty check` repeatedly.\n\n## The type system\n\nTo learn more about what makes type checking in ty unique, read about the\n[type system](./features/type-system.md).\n"
},
{
"path": "mkdocs.yml",
"content": "site_name: ty\ntheme:\n name: material\n logo: assets/logo-letter.svg\n favicon: assets/favicon.ico\n features:\n - navigation.path\n - navigation.instant\n - navigation.instant.prefetch\n - navigation.instant.progress\n - navigation.sections\n - navigation.indexes\n - navigation.tracking\n - content.code.annotate\n - toc.follow\n - navigation.footer\n - navigation.top\n - content.code.copy\n - content.tabs.link\n palette:\n # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#automatic-light-dark-mode\n - media: \"(prefers-color-scheme)\"\n toggle:\n icon: material/brightness-auto\n name: Switch to light mode\n - media: \"(prefers-color-scheme: light)\"\n scheme: astral-light\n toggle:\n icon: material/brightness-7\n name: Switch to dark mode\n - media: \"(prefers-color-scheme: dark)\"\n scheme: astral-dark\n toggle:\n icon: material/brightness-4\n name: Switch to system preference\n custom_dir: docs/.overrides\nrepo_url: https://github.com/astral-sh/ty\nrepo_name: ty\nsite_author: astral-sh\nsite_url: https://docs.astral.sh/ty/\nsite_dir: site/ty\nsite_description: ty is an extremely fast Python type checker.\nmarkdown_extensions:\n - admonition\n - pymdownx.details\n - pymdownx.snippets:\n - pymdownx.magiclink:\n - attr_list:\n - toc:\n anchorlink: true\n anchorlink_class: \"toclink\"\n - md_in_html:\n - pymdownx.inlinehilite:\n - pymdownx.superfences:\n - markdown.extensions.attr_list:\n - pymdownx.keys:\n - pymdownx.tasklist:\n custom_checkbox: true\n - pymdownx.highlight:\n anchor_linenums: true\n - pymdownx.tabbed:\n alternate_style: true\nplugins:\n - search\n - git-revision-date-localized:\n timezone: UTC # It can only be in UTC unless the ISO time can include timezone.\n - llmstxt:\n markdown_description: |\n ty is an extremely fast Python type checker and a language server written in Rust. \n It can type check large Python codebases in seconds, providing fast feedback\n during development.\n\n ty includes both a CLI (`ty check`) and a language server (`ty server`) for editor integration.\n\n When fetching documentation, use explicit `index.md` paths for directories, e.g.,\n `https://docs.astral.sh/ty/features/index.md`. This returns clean markdown instead\n of rendered HTML with JS/CSS.\n sections:\n Guides:\n - installation.md\n - type-checking.md\n - editors.md\n Concepts:\n - configuration.md\n - modules.md\n - python-version.md\n - exclusions.md\n - rules.md\n - suppression.md\n Features:\n - features/type-system.md\n - features/diagnostics.md\n - features/language-server.md\n Reference:\n - reference/configuration.md\n - reference/typing-faq.md\n - reference/rules.md\n - reference/cli.md\n - reference/exit-codes.md\n - reference/environment.md\n - reference/editor-settings.md\nextra_css:\n - stylesheets/extra.css\nextra_javascript:\n - js/extra.js\nextra:\n analytics:\n provider: fathom\n social:\n - icon: fontawesome/brands/github\n link: https://github.com/astral-sh/ty\n - icon: fontawesome/brands/discord\n link: https://discord.com/invite/astral-sh\n - icon: fontawesome/brands/python\n link: https://pypi.org/project/ty/\n - icon: fontawesome/brands/x-twitter\n link: https://x.com/astral_sh\nnav:\n - Introduction: index.md\n - Guides:\n - Installation: installation.md\n - Type checking: type-checking.md\n - Editor integration: editors.md\n - Concepts:\n - Configuration: configuration.md\n - Module discovery: modules.md\n - Python version: python-version.md\n - File exclusions: exclusions.md\n - Rules: rules.md\n - Suppression: suppression.md\n - Features:\n - Type system: features/type-system.md\n - Diagnostics: features/diagnostics.md\n - Language server: features/language-server.md\n - Reference:\n - Configuration: reference/configuration.md\n - Typing FAQ: reference/typing-faq.md\n - Rules: reference/rules.md\n - CLI: reference/cli.md\n - Exit codes: reference/exit-codes.md\n - Environment variables: reference/environment.md\n - Editor settings: reference/editor-settings.md\nvalidation:\n omitted_files: warn\n absolute_links: warn\n unrecognized_links: warn\n"
},
{
"path": "pyproject.toml",
"content": "[project]\nname = \"ty\"\nversion = \"0.0.24\"\nrequires-python = \">=3.8\"\ndependencies = []\ndescription = \"An extremely fast Python type checker, written in Rust.\"\nreadme = \"README.md\"\nauthors = [{ name = \"Astral Software Inc.\", email = \"hey@astral.sh\" }]\nkeywords = [\"ty\", \"typing\", \"analysis\", \"check\"]\nclassifiers = [\n \"Development Status :: 4 - Beta\",\n \"Environment :: Console\",\n \"Intended Audience :: Developers\",\n \"Operating System :: OS Independent\",\n \"License :: OSI Approved :: MIT License\",\n \"Programming Language :: Python\",\n \"Programming Language :: Python :: 3.8\",\n \"Programming Language :: Python :: 3.9\",\n \"Programming Language :: Python :: 3.10\",\n \"Programming Language :: Python :: 3.11\",\n \"Programming Language :: Python :: 3.12\",\n \"Programming Language :: Python :: 3.13\",\n \"Programming Language :: Python :: 3.14\",\n \"Programming Language :: Python :: 3 :: Only\",\n \"Programming Language :: Rust\",\n \"Topic :: Software Development :: Quality Assurance\",\n \"Topic :: Software Development :: Testing\",\n \"Topic :: Software Development :: Libraries\",\n \"Topic :: Software Development :: Libraries :: Python Modules\",\n]\n\n[project.urls]\nRepository = \"https://github.com/astral-sh/ty\"\nChangelog = \"https://github.com/astral-sh/ty/blob/main/CHANGELOG.md\"\nReleases = \"https://github.com/astral-sh/ty/releases\"\nDiscord = \"https://discord.gg/astral-sh\"\n\n[build-system]\nrequires = [\"maturin>=1.0,<2.0\"]\nbuild-backend = \"maturin\"\n\n[dependency-groups]\nrelease = [\"rooster\"]\n\n[tool.uv]\ncache-keys = [\n { file = \"pyproject.toml\" },\n { file = \"dist-workspace.toml\" },\n { file = \"ruff/Cargo.toml\" },\n { file = \"ruff/Cargo.lock\" },\n { file = \"**/*.rs\" },\n]\n\n[tool.uv.dependency-groups]\nrelease = {requires-python = \">=3.12\"}\n\n[tool.ruff]\nextend-exclude = [\"ruff\"]\nper-file-target-version = { \"scripts/**\" = \"py313\" }\n\n[tool.ruff.lint]\nselect = [\n \"E\", # pycodestyle (error)\n \"F\", # pyflakes\n \"B\", # bugbear\n \"B9\",\n \"C4\", # flake8-comprehensions\n \"SIM\", # flake8-simplify\n \"I\", # isort\n \"UP\", # pyupgrade\n \"PIE\", # flake8-pie\n \"PGH\", # pygrep-hooks\n \"PYI\", # flake8-pyi\n \"RUF\",\n]\n\nignore = [\n # only relevant if you run a script with `python -0`,\n # which seems unlikely for any of the scripts in this repo\n \"B011\",\n # Leave it to the formatter to split long lines and\n # the judgement of all of us.\n \"E501\",\n]\n\n[tool.ruff.lint.isort]\nrequired-imports = [\"from __future__ import annotations\"]\n\n[tool.maturin]\nbindings = \"bin\"\nmanifest-path = \"ruff/crates/ty/Cargo.toml\"\nmodule-name = \"ty\"\npython-source = \"python\"\nstrip = true\ninclude = [\n { path = \"dist-workspace.toml\", format = [\n \"sdist\",\n ] },\n { path = \"LICENSE\", format = \"sdist\" },\n]\n\n[tool.rooster]\nversion-files = [\n \"pyproject.toml\",\n { path = \"dist-workspace.toml\", field = \"workspace.version\", format = \"cargo\" },\n \"docs/installation.md\",\n]\nsubmodules = [\"ruff\"]\nrequire-labels = [{ submodule = \"ruff\", labels = [\"ty\"] }]\nignore-labels = [\n \"internal\",\n \"testing\",\n \"ci\",\n \"playground\",\n \"documentation\",\n \"release\",\n]\nchangelog-ignore-authors = [\"github-actions\"]\nmajor-labels = [] # We do not use the major version number yet\nminor-labels = [] # We do not use the minor version number yet\nversion-format = \"cargo\"\ntrim-title-prefixes = [\"[ty]\"]\n\n[tool.rooster.section-labels]\n\"Breaking changes\" = [\"breaking\"]\n\"Preview features\" = [\"preview\"]\n\"Bug fixes\" = [\"bug\"]\n\"LSP server\" = [\"server\"]\n\"CLI\" = [\"cli\"]\n\"Configuration\" = [\"configuration\"]\n"
},
{
"path": "python/ty/__init__.py",
"content": "from __future__ import annotations\n\nfrom ._find_ty import find_ty_bin\n\n__all__ = [\"find_ty_bin\"]\n"
},
{
"path": "python/ty/__main__.py",
"content": "from __future__ import annotations\n\nimport os\nimport sys\n\nfrom ty import find_ty_bin\n\n\ndef _run() -> None:\n ty = find_ty_bin()\n\n if sys.platform == \"win32\":\n import subprocess\n\n # Avoid emitting a traceback on interrupt\n try:\n completed_process = subprocess.run([ty, *sys.argv[1:]])\n except KeyboardInterrupt:\n sys.exit(2)\n\n sys.exit(completed_process.returncode)\n else:\n os.execvp(ty, [ty, *sys.argv[1:]])\n\n\nif __name__ == \"__main__\":\n _run()\n"
},
{
"path": "python/ty/_find_ty.py",
"content": "from __future__ import annotations\n\nimport os\nimport sys\nimport sysconfig\n\n\nclass TyNotFound(FileNotFoundError): ...\n\n\ndef find_ty_bin() -> str:\n \"\"\"Return the ty binary path.\"\"\"\n\n ty_exe = \"ty\" + sysconfig.get_config_var(\"EXE\")\n\n targets = [\n # The scripts directory for the current Python\n sysconfig.get_path(\"scripts\"),\n # The scripts directory for the base prefix\n sysconfig.get_path(\"scripts\", vars={\"base\": sys.base_prefix}),\n # Above the package root, e.g., from `pip install --prefix` or `uv run --with`\n (\n # On Windows, with module path `/Lib/site-packages/ty`\n _join(_matching_parents(_module_path(), \"Lib/site-packages/ty\"), \"Scripts\")\n if sys.platform == \"win32\"\n # On Unix, with module path `/lib/python3.13/site-packages/ty`\n else _join(\n _matching_parents(_module_path(), \"lib/python*/site-packages/ty\"),\n \"bin\",\n )\n ),\n # Adjacent to the package root, e.g., from `pip install --target`\n # with module path `/ty`\n _join(_matching_parents(_module_path(), \"ty\"), \"bin\"),\n # The user scheme scripts directory, e.g., `~/.local/bin`\n sysconfig.get_path(\"scripts\", scheme=_user_scheme()),\n ]\n\n seen = []\n for target in targets:\n if not target:\n continue\n if target in seen:\n continue\n seen.append(target)\n path = os.path.join(target, ty_exe)\n if os.path.isfile(path):\n return path\n\n locations = \"\\n\".join(f\" - {target}\" for target in seen)\n raise TyNotFound(\n f\"Could not find the ty binary in any of the following locations:\\n{locations}\\n\"\n )\n\n\ndef _module_path() -> str | None:\n path = os.path.dirname(__file__)\n return path\n\n\ndef _matching_parents(path: str | None, match: str) -> str | None:\n \"\"\"\n Return the parent directory of `path` after trimming a `match` from the end.\n The match is expected to contain `/` as a path separator, while the `path`\n is expected to use the platform's path separator (e.g., `os.sep`). The path\n components are compared case-insensitively and a `*` wildcard can be used\n in the `match`.\n \"\"\"\n from fnmatch import fnmatch\n\n if not path:\n return None\n parts = path.split(os.sep)\n match_parts = match.split(\"/\")\n if len(parts) < len(match_parts):\n return None\n\n if not all(\n fnmatch(part, match_part)\n for part, match_part in zip(reversed(parts), reversed(match_parts))\n ):\n return None\n\n return os.sep.join(parts[: -len(match_parts)])\n\n\ndef _join(path: str | None, *parts: str) -> str | None:\n if not path:\n return None\n return os.path.join(path, *parts)\n\n\ndef _user_scheme() -> str:\n if sys.version_info >= (3, 10):\n user_scheme = sysconfig.get_preferred_scheme(\"user\")\n elif os.name == \"nt\":\n user_scheme = \"nt_user\"\n elif sys.platform == \"darwin\" and sys._framework: # ty: ignore[unresolved-attribute]\n user_scheme = \"osx_framework_user\"\n else:\n user_scheme = \"posix_user\"\n return user_scheme\n"
},
{
"path": "python/ty/py.typed",
"content": "\n"
},
{
"path": "scripts/autogenerate_files.sh",
"content": "#!/usr/bin/env sh\n#\n# Generate files and copy documentation from Ruff.\n#\n# Usage\n#\n# ./scripts/autogenerate-files.sh\n#\nset -eu\n\nscript_root=\"$(realpath \"$(dirname \"$0\")\")\"\nproject_root=\"$(dirname \"$script_root\")\"\ncd \"$project_root\"\n\necho \"Updating lockfile...\"\nuv lock\n\necho \"Copying reference documentation from Ruff...\"\ncp ./ruff/crates/ty/docs/cli.md ./docs/reference/\ncp ./ruff/crates/ty/docs/configuration.md ./docs/reference/\ncp ./ruff/crates/ty/docs/rules.md ./docs/reference/\ncp ./ruff/crates/ty/docs/environment.md ./docs/reference/\n\necho \"Documentation has been copied from Ruff submodule\"\n"
},
{
"path": "scripts/release.sh",
"content": "#!/usr/bin/env sh\n#\n# Prepare a release.\n#\n# Usage\n#\n# ./scripts/release.sh [rooster-args ...]\n#\nset -eu\n\necho \"Checking Ruff submodule status...\"\nif git -C ruff diff --quiet; then\n echo \"Ruff submodule is clean; continuing...\"\nelse\n echo \"Ruff submodule has uncommitted changes; aborting!\"\n exit 1\nfi\n\nruff_head=$(git -C ruff rev-parse --abbrev-ref HEAD)\ncase \"${ruff_head}\" in\n \"HEAD\")\n echo \"Ruff submodule has detached HEAD; switching to main...\"\n git -C ruff checkout main > /dev/null 2>&1\n ;;\n \"main\")\n echo \"Ruff submodule is on main branch; continuing...\"\n ;;\n *)\n echo \"Ruff submodule is on branch ${ruff_head} but must be on main; aborting!\"\n exit 1\n ;;\nesac\n\n\n# Save the current typeshed source commit before updating ruff,\n# so we can generate a typeshed diff link for the changelog later.\ntypeshed_commit_file=\"ruff/crates/ty_vendored/vendor/typeshed/source_commit.txt\"\nold_typeshed_commit=\"\"\nif [ -f \"$typeshed_commit_file\" ]; then\n old_typeshed_commit=$(cat \"$typeshed_commit_file\")\nfi\n\necho \"Updating Ruff to the latest commit...\"\ngit -C ruff pull origin main\ngit add ruff\n\nscript_root=\"$(realpath \"$(dirname \"$0\")\")\"\nproject_root=\"$(dirname \"$script_root\")\"\n\necho \"Running rooster...\"\ncd \"$project_root\"\n\n# Generate the changelog and bump versions\nuv run --isolated --only-group release \\\n rooster release \"$@\"\n\n# If the typeshed source commit changed and the changelog mentions a typeshed\n# sync, append a link to the typeshed diff so reviewers can see what changed.\nif [ -n \"$old_typeshed_commit\" ] && [ -f \"$typeshed_commit_file\" ]; then\n new_typeshed_commit=$(cat \"$typeshed_commit_file\")\n if [ \"$old_typeshed_commit\" != \"$new_typeshed_commit\" ]; then\n typeshed_diff_link=\"[Typeshed diff](https://github.com/python/typeshed/compare/${old_typeshed_commit}...${new_typeshed_commit})\"\n # Match lines like \"- Sync vendored typeshed stubs ([#NNNN](...))\".\n # The pattern anchors on the trailing \"))$\" so it won't match lines\n # that already have a typeshed diff link appended.\n # Use a temp file instead of `sed -i` for macOS/Linux portability.\n sed \"s|\\(- Sync vendored typeshed stubs (.*)\\))$|\\1). ${typeshed_diff_link}|\" CHANGELOG.md > CHANGELOG.md.tmp\n mv CHANGELOG.md.tmp CHANGELOG.md\n fi\nfi\n\n\"${script_root}/autogenerate_files.sh\"\ngit add ./docs/reference\n"
},
{
"path": "scripts/transform_readme.py",
"content": "\"\"\"Transform the README.md to support a specific deployment target.\n\nBy default, we assume that our README.md will be rendered on GitHub. However,\nPyPI includes the README with different rendering.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport re\nimport tomllib\nimport urllib.parse\nfrom pathlib import Path\n\n# The benchmark SVG includes a CSS media query that adapts to light/dark mode.\n# PyPI doesn't support this, so we replace it with a light-only version.\n# See: https://github.com/pypi/warehouse/issues/11251\nBENCHMARK_URL = \"https://raw.githubusercontent.com/astral-sh/ty/main/docs/assets/ty-benchmark-cli.svg\"\nBENCHMARK_URL_LIGHT = \"https://raw.githubusercontent.com/astral-sh/ty/main/docs/assets/ty-benchmark-cli-light.svg\"\n\n\ndef main() -> None:\n \"\"\"Modify the README.md to support PyPI.\"\"\"\n # Read the current version from the `dist-workspace.toml`.\n with Path(\"dist-workspace.toml\").open(mode=\"rb\") as fp:\n # Parse the TOML.\n dist_workspace = tomllib.load(fp)\n if \"workspace\" in dist_workspace and \"version\" in dist_workspace[\"workspace\"]:\n version = dist_workspace[\"workspace\"][\"version\"]\n else:\n raise ValueError(\"Version not found in dist-workspace.toml\")\n\n content = Path(\"README.md\").read_text(encoding=\"utf8\")\n\n # Replace the benchmark image URL with the light-only version for PyPI.\n if BENCHMARK_URL not in content:\n msg = \"README.md is not in the expected format (benchmark image not found).\"\n raise ValueError(msg)\n content = content.replace(BENCHMARK_URL, BENCHMARK_URL_LIGHT)\n\n # Replace relative src=\"./...\" attributes with absolute GitHub raw URLs.\n def replace_src(match: re.Match) -> str:\n path = match.group(1).lstrip(\"./\")\n return f'src=\"https://raw.githubusercontent.com/astral-sh/ty/{version}/{path}\"'\n\n content = re.sub(r'src=\"(\\./[^\"]+)\"', replace_src, content)\n\n # Replace any relative URLs (e.g., `[CONTRIBUTING.md`) with absolute URLs.\n def replace(match: re.Match) -> str:\n url = match.group(1)\n if not url.startswith(\"http\"):\n url = urllib.parse.urljoin(\n f\"https://github.com/astral-sh/ty/blob/{version}/README.md\", url\n )\n return f\"]({url})\"\n\n content = re.sub(r\"]\\(([^)]+)\\)\", replace, content)\n\n # Replace any GitHub admonitions\n def replace(match: re.Match) -> str:\n name = match.group(1)\n return f\"> {name}:\"\n\n content = re.sub(r\"> \\[\\!(\\w*)\\]\", replace, content)\n\n with Path(\"README.md\").open(\"w\", encoding=\"utf8\") as fp:\n fp.write(content)\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "scripts/update_schemastore.py",
"content": "\"\"\"Update ty.json in schemastore.\n\nThis script will clone `astral-sh/schemastore`, update the schema and push the changes\nto a new branch tagged with the ty git hash. You should see a URL to create the PR\nto schemastore in the CLI.\n\nUsage:\n\n uv run --only-dev scripts/update_schemastore.py\n\"\"\"\n\nfrom __future__ import annotations\n\nimport enum\nimport json\nfrom pathlib import Path\nfrom subprocess import check_call, check_output\nfrom tempfile import TemporaryDirectory\nfrom typing import NamedTuple, assert_never\n\n# The remote URL for the `ty` repository.\nTY_REPO = \"https://github.com/astral-sh/ty\"\n\n# The path to the root of the `ty` repository.\nTY_ROOT = Path(__file__).parent.parent\n\n# The path to the JSON schema in the `ty` repository.\nTY_SCHEMA = TY_ROOT / \"ruff\" / \"ty.schema.json\"\n\n# The path to the JSON schema in the `schemastore` repository.\nTY_JSON = Path(\"schemas/json/ty.json\")\n\n\nclass SchemastoreRepos(NamedTuple):\n fork: str\n upstream: str\n\n\nclass GitProtocol(enum.Enum):\n SSH = \"ssh\"\n HTTPS = \"https\"\n\n def schemastore_repos(self) -> SchemastoreRepos:\n match self:\n case GitProtocol.SSH:\n return SchemastoreRepos(\n fork=\"git@github.com:astral-sh/schemastore.git\",\n upstream=\"git@github.com:SchemaStore/schemastore.git\",\n )\n case GitProtocol.HTTPS:\n return SchemastoreRepos(\n fork=\"https://github.com/astral-sh/schemastore.git\",\n upstream=\"https://github.com/SchemaStore/schemastore.git\",\n )\n case _:\n assert_never(self)\n\n\ndef update_schemastore(\n schemastore_path: Path, schemastore_repos: SchemastoreRepos\n) -> None:\n if not (schemastore_path / \".git\").is_dir():\n check_call(\n [\"git\", \"clone\", schemastore_repos.fork, schemastore_path, \"--depth=1\"],\n )\n check_call(\n [\n \"git\",\n \"remote\",\n \"add\",\n \"upstream\",\n schemastore_repos.upstream,\n ],\n cwd=schemastore_path,\n )\n\n # Create a new branch tagged with the current ty commit up to date with the latest\n # upstream schemastore\n check_call([\"git\", \"fetch\", \"upstream\"], cwd=schemastore_path)\n current_sha = check_output(\n [\"git\", \"rev-parse\", \"HEAD\"], text=True, cwd=TY_ROOT\n ).strip()\n branch = f\"update-ty-{current_sha}\"\n check_call(\n [\"git\", \"switch\", \"-c\", branch],\n cwd=schemastore_path,\n )\n check_call(\n [\"git\", \"reset\", \"--hard\", \"upstream/master\"],\n cwd=schemastore_path,\n )\n\n # Run npm ci\n src = schemastore_path / \"src\"\n check_call([\"npm\", \"ci\", \"--ignore-scripts\"], cwd=schemastore_path)\n\n # Update the schema and format appropriately\n schema = json.loads(TY_SCHEMA.read_text())\n schema[\"$id\"] = \"https://json.schemastore.org/ty.json\"\n (src / TY_JSON).write_text(\n json.dumps(dict(schema.items()), indent=2, ensure_ascii=False),\n )\n check_call(\n [\n \"../node_modules/prettier/bin/prettier.cjs\",\n \"--plugin\",\n \"prettier-plugin-sort-json\",\n \"--write\",\n TY_JSON,\n ],\n cwd=src,\n )\n\n # Check if the schema has changed\n # https://stackoverflow.com/a/9393642/3549270\n if check_output([\"git\", \"status\", \"-s\"], cwd=schemastore_path).strip():\n # Schema has changed, commit and push\n commit_url = f\"{TY_REPO}/commit/{current_sha}\"\n commit_body = f\"This updates ty's JSON schema to [{current_sha}]({commit_url})\"\n # https://stackoverflow.com/a/22909204/3549270\n check_call([\"git\", \"add\", (src / TY_JSON).as_posix()], cwd=schemastore_path)\n check_call(\n [\n \"git\",\n \"commit\",\n \"-m\",\n \"Update ty's JSON schema\",\n \"-m\",\n commit_body,\n ],\n cwd=schemastore_path,\n )\n # This should show the link to create a PR\n check_call(\n [\"git\", \"push\", \"--set-upstream\", \"origin\", branch, \"--force\"],\n cwd=schemastore_path,\n )\n else:\n print(\"No changes\")\n\n\ndef determine_git_protocol(argv: list[str] | None = None) -> GitProtocol:\n import argparse\n\n parser = argparse.ArgumentParser(\n description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter\n )\n parser.add_argument(\n \"--proto\",\n choices=[proto.value for proto in GitProtocol],\n default=\"https\",\n help=\"Protocol to use for git authentication\",\n )\n args = parser.parse_args(argv)\n return GitProtocol(args.proto)\n\n\ndef main() -> None:\n expected_ruff_revision = check_output(\n [\"git\", \"ls-tree\", \"main\", \"--format\", \"%(objectname)\", \"ruff\"], cwd=TY_ROOT\n ).strip()\n actual_ruff_revision = check_output(\n [\"git\", \"-C\", \"ruff\", \"rev-parse\", \"HEAD\"], cwd=TY_ROOT\n ).strip()\n\n if expected_ruff_revision != actual_ruff_revision:\n print(\n f\"The ruff submodule is at {actual_ruff_revision} but main expects {expected_ruff_revision}\"\n )\n match input(\n \"How do you want to proceed (u=reset submodule, n=abort, y=continue)? \"\n ):\n case \"u\":\n check_call(\n [\"git\", \"-C\", \"ruff\", \"reset\", \"--hard\", expected_ruff_revision],\n cwd=TY_ROOT,\n )\n case \"n\":\n return\n case \"y\":\n ...\n case command:\n print(f\"Invalid input '{command}', abort\")\n return\n\n schemastore_repos = determine_git_protocol().schemastore_repos()\n schemastore_existing = TY_ROOT / \"schemastore\"\n if schemastore_existing.is_dir():\n update_schemastore(schemastore_existing, schemastore_repos)\n else:\n with TemporaryDirectory(prefix=\"ty-schemastore-\") as temp_dir:\n update_schemastore(Path(temp_dir), schemastore_repos)\n\n\nif __name__ == \"__main__\":\n main()\n"
}
]