From 42b297bf4430ef36b84fd6f4a8cc966ec6ec32c5 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 6 Oct 2025 13:20:00 +0100 Subject: [PATCH] [ty] Improve documentation for `extra-paths` and `python` config settings (#20717) Co-authored-by: Micha Reiser --- crates/ty/docs/cli.md | 12 ++++----- crates/ty/docs/configuration.md | 30 +++++++++++++++++------ crates/ty/src/args.rs | 21 +++++++--------- crates/ty_project/src/metadata/options.rs | 30 +++++++++++++++++------ ty.schema.json | 4 +-- 5 files changed, 61 insertions(+), 36 deletions(-) diff --git a/crates/ty/docs/cli.md b/crates/ty/docs/cli.md index 7bf076ee27..83de0b3d6d 100644 --- a/crates/ty/docs/cli.md +++ b/crates/ty/docs/cli.md @@ -54,7 +54,8 @@ over all configuration files.

--exclude exclude

Glob patterns for files to exclude from type checking.

Uses gitignore-style syntax to exclude files and directories from type checking. Supports patterns like tests/, *.tmp, **/__pycache__/**.

--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)

+
--extra-search-path path

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

+

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

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

@@ -67,11 +68,10 @@ over all configuration files.

--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, --venv 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 or CONDA_PREFIX environment variables, 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 environment's site-packages directories for type information and third-party imports.

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

+

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 d7debe12a3..248e0f547c 100644 --- a/crates/ty/docs/configuration.md +++ b/crates/ty/docs/configuration.md @@ -32,9 +32,14 @@ division-by-zero = "ignore" ### `extra-paths` -List of user-provided paths that should take first priority in the module resolution. -Examples in other type checkers are mypy's `MYPYPATH` environment variable, -or pyright's `stubPath` configuration setting. +User-provided paths that should take first priority in module resolution. + +This 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 the `python` option to specify the location of your Python environment. + +This option is similar to mypy's `MYPYPATH` environment variable and pyright's `stubPath` +configuration setting. **Default value**: `[]` @@ -51,12 +56,21 @@ extra-paths = ["./shared/my-search-path"] ### `python` -Path to the Python installation from which ty resolves type information and third-party dependencies. +Path to your project's Python environment or interpreter. -ty will search in the path's `site-packages` directories for type information and -third-party imports. +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 option is commonly used to specify the path to a virtual environment. +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 your environment from an activated Conda environment, and will look for +a `.venv` directory in the project root if none of the above apply. + +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. **Default value**: `null` @@ -66,7 +80,7 @@ This option is commonly used to specify the path to a virtual environment. ```toml [tool.ty.environment] -python = "./.venv" +python = "./custom-venv-location/.venv" ``` --- diff --git a/crates/ty/src/args.rs b/crates/ty/src/args.rs index 45912a67aa..8ec32c8c63 100644 --- a/crates/ty/src/args.rs +++ b/crates/ty/src/args.rs @@ -51,21 +51,14 @@ pub(crate) struct CheckCommand { #[arg(long, value_name = "PROJECT")] pub(crate) project: Option, - /// Path to the Python environment. + /// Path to your project's Python environment or interpreter. /// - /// ty uses the Python environment to resolve type information and third-party dependencies. + /// ty uses your Python environment to resolve third-party imports in your code. /// - /// If not specified, ty will attempt to infer it from the `VIRTUAL_ENV` or `CONDA_PREFIX` - /// environment variables, or discover a `.venv` directory in the project root or working - /// directory. + /// 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. /// - /// 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 environment's `site-packages` directories for type - /// information and third-party imports. + /// This option can be used to point to virtual or system Python environments. #[arg(long, value_name = "PATH", alias = "venv")] pub(crate) python: Option, @@ -74,6 +67,10 @@ pub(crate) struct CheckCommand { pub(crate) typeshed: Option, /// Additional path to use as a module-resolution source (can be passed multiple times). + /// + /// This 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. #[arg(long, value_name = "PATH")] pub(crate) extra_search_path: Option>, diff --git a/crates/ty_project/src/metadata/options.rs b/crates/ty_project/src/metadata/options.rs index c0e0cfeb91..36709174df 100644 --- a/crates/ty_project/src/metadata/options.rs +++ b/crates/ty_project/src/metadata/options.rs @@ -550,9 +550,14 @@ pub struct EnvironmentOptions { )] pub python_platform: Option>, - /// List of user-provided paths that should take first priority in the module resolution. - /// Examples in other type checkers are mypy's `MYPYPATH` environment variable, - /// or pyright's `stubPath` configuration setting. + /// User-provided paths that should take first priority in module resolution. + /// + /// This 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 the `python` option to specify the location of your Python environment. + /// + /// This option is similar to mypy's `MYPYPATH` environment variable and pyright's `stubPath` + /// configuration setting. #[serde(skip_serializing_if = "Option::is_none")] #[option( default = r#"[]"#, @@ -576,18 +581,27 @@ pub struct EnvironmentOptions { )] pub typeshed: Option, - /// Path to the Python installation from which ty resolves type information and third-party dependencies. + /// Path to your project's Python environment or interpreter. /// - /// ty will search in the path's `site-packages` directories for type information and - /// third-party imports. + /// 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 option is commonly used to specify the path to a virtual environment. + /// 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 your environment from an activated Conda environment, and will look for + /// a `.venv` directory in the project root if none of the above apply. + /// + /// 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. #[serde(skip_serializing_if = "Option::is_none")] #[option( default = r#"null"#, value_type = "str", example = r#" - python = "./.venv" + python = "./custom-venv-location/.venv" "# )] pub python: Option, diff --git a/ty.schema.json b/ty.schema.json index f7b2b1095d..b8c5fcbef2 100644 --- a/ty.schema.json +++ b/ty.schema.json @@ -62,7 +62,7 @@ "type": "object", "properties": { "extra-paths": { - "description": "List of user-provided paths that should take first priority in the module resolution. Examples in other type checkers are mypy's `MYPYPATH` environment variable, or pyright's `stubPath` configuration setting.", + "description": "User-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 modules that are not installed into your Python environment in a conventional way. Use 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` configuration setting.", "type": [ "array", "null" @@ -72,7 +72,7 @@ } }, "python": { - "description": "Path to the Python installation from which ty resolves type information and third-party dependencies.\n\nty will search in the path's `site-packages` directories for type information and third-party imports.\n\nThis option is commonly used to specify the path to a virtual environment.", + "description": "Path to your project's Python environment or interpreter.\n\nty 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.\n\nIf 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 your environment from an activated Conda environment, and will look for a `.venv` directory in the project root if none of the above apply.\n\nPassing a path to a Python executable is supported, but passing a path to a dynamic executable (such as a shim) is not currently supported.\n\nThis option can be used to point to virtual or system Python environments.", "type": [ "string", "null"