diff --git a/crates/ty/docs/cli.md b/crates/ty/docs/cli.md index c802775260510..c9af1572f4458 100644 --- a/crates/ty/docs/cli.md +++ b/crates/ty/docs/cli.md @@ -75,8 +75,12 @@ over all configuration files.

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

--python, --venv path

Path to your project's Python environment or interpreter.

ty uses your Python environment to resolve third-party imports in your code.

+

This can be a path to:

+

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

-

This option can be used to point to virtual or system Python environments.

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

diff --git a/crates/ty/docs/configuration.md b/crates/ty/docs/configuration.md index 87240b7f2b387..170c2e1ae35a2 100644 --- a/crates/ty/docs/configuration.md +++ b/crates/ty/docs/configuration.md @@ -159,6 +159,12 @@ Path to your project's Python environment or interpreter. ty uses the `site-packages` directory of your project's Python environment to resolve third-party (and, in some cases, first-party) imports in your code. +This can be a path to: + +- A Python interpreter, e.g. `.venv/bin/python3` +- A virtual environment directory, e.g. `.venv` +- A system Python [`sys.prefix`] directory, e.g. `/usr` + If you're using a project management tool such as uv, you should not generally need to specify this option, as commands such as `uv run` will set the `VIRTUAL_ENV` environment variable to point to your project's virtual environment. ty can also infer the location of @@ -166,10 +172,7 @@ your environment from an activated Conda environment, and will look for a `.venv in the project root if none of the above apply. Failing that, ty will look for a `python3` or `python` binary available in `PATH`. -Passing a path to a Python executable is supported, but passing a path to a dynamic executable -(such as a shim) is not currently supported. - -This option can be used to point to virtual or system Python environments. +[`sys.prefix`]: https://docs.python.org/3/library/sys.html#sys.prefix **Default value**: `null` diff --git a/crates/ty/src/args.rs b/crates/ty/src/args.rs index 1c9912c4e2654..1e9d054849090 100644 --- a/crates/ty/src/args.rs +++ b/crates/ty/src/args.rs @@ -71,10 +71,16 @@ pub(crate) struct CheckCommand { /// /// ty uses your Python environment to resolve third-party imports in your code. /// + /// This can be a path to: + /// + /// - A Python interpreter, e.g. `.venv/bin/python3` + /// - A virtual environment directory, e.g. `.venv` + /// - A system Python [`sys.prefix`] directory, e.g. `/usr` + /// /// If 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. /// - /// This option can be used to point to virtual or system Python environments. + /// [`sys.prefix`]: https://docs.python.org/3/library/sys.html#sys.prefix #[arg(long, value_name = "PATH", alias = "venv")] pub(crate) python: Option, diff --git a/crates/ty_project/src/metadata/options.rs b/crates/ty_project/src/metadata/options.rs index f10613edcc5e9..19a08885fb1d8 100644 --- a/crates/ty_project/src/metadata/options.rs +++ b/crates/ty_project/src/metadata/options.rs @@ -683,6 +683,12 @@ pub struct EnvironmentOptions { /// ty uses the `site-packages` directory of your project's Python environment /// to resolve third-party (and, in some cases, first-party) imports in your code. /// + /// This can be a path to: + /// + /// - A Python interpreter, e.g. `.venv/bin/python3` + /// - A virtual environment directory, e.g. `.venv` + /// - A system Python [`sys.prefix`] directory, e.g. `/usr` + /// /// If you're using a project management tool such as uv, you should not generally need to /// specify this option, as commands such as `uv run` will set the `VIRTUAL_ENV` environment /// variable to point to your project's virtual environment. ty can also infer the location of @@ -690,10 +696,7 @@ pub struct EnvironmentOptions { /// in the project root if none of the above apply. Failing that, ty will look for a `python3` /// or `python` binary available in `PATH`. /// - /// Passing a path to a Python executable is supported, but passing a path to a dynamic executable - /// (such as a shim) is not currently supported. - /// - /// This option can be used to point to virtual or system Python environments. + /// [`sys.prefix`]: https://docs.python.org/3/library/sys.html#sys.prefix #[serde(skip_serializing_if = "Option::is_none")] #[option( default = r#"null"#, diff --git a/ty.schema.json b/ty.schema.json index c3ff157d42052..3bf31abc9b8ba 100644 --- a/ty.schema.json +++ b/ty.schema.json @@ -112,7 +112,7 @@ } }, "python": { - "description": "Path 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\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\nPassing a path to a Python executable is supported, but passing a path to a dynamic executable\n(such as a shim) is not currently supported.\n\nThis option can be used to point to virtual or system Python environments.", + "description": "Path 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", "anyOf": [ { "$ref": "#/definitions/RelativePathBuf"