language-servers/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff.git synced 2025-08-08 20:58:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3
ruff/crates/ty/docs/cli.md
Zanie Blue 6b64630635
Update --python to accept paths to executables in virtual environments (#17954) 
## Summary

Updates the `--python` flag to accept Python executables in virtual
environments. Notably, we do not query the executable and it _must_ be
in a canonical location in a virtual environment. This is pretty naive,
but solves for the trivial case of `ty check --python .venv/bin/python3`
which will be a common mistake (and `ty check --python $(which python)`)

I explored this while trying to understand Python discovery in ty in
service of https://github.com/astral-sh/ty/issues/272, I'm not attached
to it, but figure it's worth sharing.

As an alternative, we can add more variants to the
`SearchPathValidationError` and just improve the _error_ message, i.e.,
by hinting that this looks like a virtual environment and suggesting the
concrete alternative path they should provide. We'll probably want to do
that for some other cases anyway (e.g., `3.13` as described in the
linked issue)

This functionality is also briefly mentioned in
https://github.com/astral-sh/ty/issues/193

Closes https://github.com/astral-sh/ty/issues/318

## Test Plan

e.g.,

```
uv run ty check --python .venv/bin/python3
```

needs test coverage still
2025-05-12 15:39:04 -05:00

7.7 KiB
Raw Blame History

CLI Reference

ty

An extremely fast Python type checker.

Usage

ty <COMMAND>

Commands

ty check

Check a project for type errors

ty server

Start the language server

ty version

Display ty's version

ty help

Print this message or the help of the given subcommand(s)

ty check

Check a project for type errors

Usage

ty check [OPTIONS] [PATH]...

Arguments

PATHS

List of files or directories to check [default: the project root]

Options

--color when

Control when colored output is used

Possible values:

  • auto: Display colors if the output goes to an interactive terminal
  • always: Always display colors
  • never: Never display colors
--config, -c config-option

A TOML <KEY> = <VALUE> pair

--error rule

Treat the given rule as having severity 'error'. Can be specified multiple times.

--error-on-warning

Use exit code 1 if there are any warning-level diagnostics

--exit-zero

Always use exit code 0, even when there are error-level diagnostics

--extra-search-path path

Additional path to use as a module-resolution source (can be passed multiple times)

--help, -h

Print help (see a summary with '-h')

--ignore rule

Disables the rule. Can be specified multiple times.

--output-format output-format

The format to use for printing diagnostic messages

Possible values:

  • full: Print diagnostics verbosely, with context and helpful hints
  • concise: Print diagnostics concisely, one per line
--project project

Run the command within the given project directory.

All 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.

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

--python path

Path to the Python environment.

ty uses the Python environment to resolve type information and third-party dependencies.

If not specified, ty will attempt to infer it from the VIRTUAL_ENV environment variable or discover a .venv directory in the project root or working directory.

If a path to a Python interpreter is provided, e.g., .venv/bin/python3, ty will attempt to find an environment two directories up from the interpreter's path, e.g., .venv. At this time, ty does not invoke the interpreter to determine the location of the environment. This means that ty will not resolve dynamic executables such as a shim.

ty will search in the resolved environments's site-packages directories for type information and third-party imports.

--python-platform, --platform platform

Target platform to assume when resolving types.

This 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.

--python-version, --target-version version

Python version to assume when resolving types

Possible values:

  • 3.7
  • 3.8
  • 3.9
  • 3.10
  • 3.11
  • 3.12
  • 3.13
--respect-ignore-files

Respect file exclusions via .gitignore and other standard ignore files. Use --no-respect-gitignore to disable

--typeshed, --custom-typeshed-dir path

Custom directory to use for stdlib typeshed stubs

--verbose, -v

Use verbose output (or -vv and -vvv for more verbose output)

--warn rule

Treat the given rule as having severity 'warn'. Can be specified multiple times.

--watch, -W

Watch files for changes and recheck files related to the changed files

ty server

Start the language server

Usage

ty server

Options

--help, -h

Print help

ty version

Display ty's version

Usage

ty version

Options

--help, -h

Print help

ty generate-shell-completion

Generate shell completion

Usage

ty generate-shell-completion <SHELL>

Arguments

SHELL

Options

--help, -h

Print help

ty help

Print this message or the help of the given subcommand(s)

Usage

ty help [COMMAND]