Metadata-Version: 2.4
Name: pants-ty
Version: 0.1.0
Summary: A Pants check backend for the Astral ty Python type checker.
Author: Vasile Razdalovschi
License-Expression: MIT
Project-URL: Repository, https://github.com/vrazdalovschi/pants-ty-plugin
Project-URL: Issues, https://github.com/vrazdalovschi/pants-ty-plugin/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pantsbuild.pants<2.32,>=2.31
Dynamic: license-file

# pants-ty-plugin

`pants-ty-plugin` adds a Pants `check` backend for [Astral ty](https://docs.astral.sh/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:

```toml
[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:

```text
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:

```toml
[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:

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

Pants exposes the plugin options under `[ty]`:

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

Useful commands:

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

To skip a target:

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

## Development

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

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

To build a distributable wheel and sdist:

```bash
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.
