pants-ty 0.1.0

A Pants check backend for the Astral ty Python type checker.

pants-ty-plugin

pants-ty-plugin adds a Pants check backend for Astral ty.

It is designed for Pants 2.31.x and currently supports Linux and macOS. The backend installs ty as an external binary, then runs it with:

• a resolve-backed Python environment for third-party dependencies
• Pants source roots as --extra-search-path entries for first-party imports

That means ty can resolve imports that Pants already knows about.

Features

• pants check --only=ty ...
• skip_ty = true on Python targets
• ty.toml discovery
• [tool.ty] discovery from pyproject.toml
• resolve-aware --python
• source-root-aware --extra-search-path

Install

Option 1: vendor the plugin into a private repo

Copy only the Python package files from pants-plugins/pants_ty/ into your repo's pants-plugins/pants_ty/ directory:

• __init__.py
• register.py
• rules.py
• skip_field.py
• subsystem.py

Do not copy this plugin repo's development-only files:

• pants-plugins/BUILD
• pants-plugins/pants_ty/BUILD
• pants-plugins/lock.txt
• tests/
• this repo's pants.toml, pyproject.toml, or GitHub workflow files

Those files are only for developing and releasing pants-ty-plugin itself. A consuming repo should use its own resolves, lockfiles, and test setup.

Then configure:

[GLOBAL]
pants_version = "2.31.0"
backend_packages = [
  "pants.backend.python",
  "pants_ty",
]
pythonpath = ["%(buildroot)s/pants-plugins"]

If you accidentally copy the dev BUILD files too, you may see an error like:

UnrecognizedResolveNamesError: ... resolve ... pants-plugins

That means your consuming repo picked up this repo's internal development resolve. Remove the copied BUILD files and keep only the plugin Python modules.

Option 2: install as a published plugin

Once the package is published, use:

[GLOBAL]
plugins = ["pants-ty==0.1.0"]
backend_packages = [
  "pants.backend.python",
  "pants_ty",
]

Configure

Create either ty.toml or add [tool.ty] to pyproject.toml.

Example:

[tool.ty]
exclude = [".pants.d", "dist"]

Pants exposes the plugin options under [ty]:

[ty]
args = ["--output-format=concise"]
config_discovery = true

Useful commands:

pants help ty
pants check --only=ty ::
pants check --only=ty path/to/pkg::

To skip a target:

python_sources(
  name="lib",
  skip_ty=True,
)

Development

This repo uses Pants to lint, test, and dogfood the plugin itself.

ruff check pants-plugins tests
pants test ::
pants check ::

To build a distributable wheel and sdist:

python -m build

Repository layout

• pants-plugins/pants_ty: plugin source
• tests/pants_ty: unit and integration tests
• pants.toml: local development config
• pants.ci.toml: CI-specific Pants settings

Notes

• The Pants plugin API is not stable across minor versions. This repo currently targets Pants 2.31.x.
• The backend only resolves imports that Pants already knows through source roots and target resolves.