Files
Micha Reiser e501689d12 [ty] Inherit project settings and overrides for PEP 723 scripts (#29793)
## Summary

This changes how ty handles script options. Up to now, scripts never
inherited any settings from the project. I think this is overly
pedantic. While I consider script isolation important in terms of
dependencies, I don't think the same is true for type checking or linter
settings. The main motivation for not-inheriting project settings is
that scripts can be shared. Checking them in isolation ensures that
everyone gets a consistent experience. I don't think this is something
most users care about in terms of linting and type checking scripts. Our
own scripts are a good example. We have multiple scripts and we have no
intention to share them outside this project. In fact, we've found it
very annoying to repeat the same ty configuration in every script.

I also ran an experiment in https://github.com/astral-sh/ruff/pull/29768
to understand the ecosystem impact of using ty's current configuration
inheritance in Ruff. Without project inheritance, 17 of 38 scripts in
the seven projects sampled had diagnostics. Not only would this be a
very disruptive change. I also think that it's very reasonable that you
want to enforce the same standard to both regular python files as well
as scripts.

This PR changes how ty resolve script settings to:

* If a script has a `tool.ty` section, ignore the project's
configuration. Users who prefer the current behavior can restore it by
adding an empty `tool.ty` section to their script (or check their script
outside the project).
* If a script has no `tool.ty` section, inherit the project's
configuration. This is the main change.
* If a script has no `tool.ty` section, and the script matches an
`overrides` entry, inherit the project and override settings, like we do
for any other file. This allows users to extend the project
configuration (except for `environment` settings).

An explicit `--config-file` still overrides any settings specified in
the script. Matching file overrides from that config also apply.

A script's `requires-python` takes precedence over the project's Python
version. An inline `environment.python-version` takes precedence over
`requires-python`.


Fixes astral-sh/ty#4083 and addresses the [ignored file override
reported in
ty#4566](https://github.com/astral-sh/ty/issues/4566#issuecomment-5762949445).


## Considerations

The main downside of this change is that changing a script's
`environment.root` from `[]` to `["."]` implies opting out of the
project's config inheritance, because it requires adding a `tool.ty`
section. I don't have a good solution to this, other that we could
consider adding a `extend` configuration option in the future, that
allows explicitly inheriting from another configuration. Which is
something users have asked for before (for projects).


The other nuanced decision in this PR is that script's inherit a
project's `environment.extra-paths`. I think this is okay, given that
the main use case is to override e.g. typing stubs. But I could see an
argument that a script should not inherit any of the search path related
settings.

## Test Plan

All script CLI tests passed, including the uv integration tests.
2026-11-04 16:36:21 +00:00

2.7 KiB

Scripts with PEP 723 metadata are single-file projects with their own dependencies. They inherit the enclosing project's rules and analysis settings unless they define a [tool.ty] table.

[environment]
python-version = "3.12"

[rules]
unresolved-reference = "error"

[analysis]
respect-type-ignore-comments = false

Inline settings

A script can change its rules, analysis, and environment settings.

# /// script
# [tool.ty.rules]
# all = "ignore"
# unresolved-reference = "error"
# [tool.ty.analysis]
# respect-type-ignore-comments = false
# ///

# error: [unresolved-reference]
print(missing)  # type: ignore

A metadata block without tool.ty

This project disables type: ignore comments, so the script reports both assignments.

# /// script
# dependencies = []
# ///

value: int = "not an int"  # error: [invalid-assignment]
# error: [invalid-assignment]
also_invalid: int = "not an int"  # type: ignore

Other Python source kinds

Script metadata is also recognized in stubs and extensionless Python files.

Stub

# /// script
# dependencies = []
# ///

value: Missing  # error: [unresolved-reference]

Extensionless file

script:

# /// script
# dependencies = []
# ///

# error: [unresolved-reference]
print(missing)

Invalid blocks

Invalid blocks do not establish script isolation, so the project configuration continues to apply.

Indented opening tag

if True:
    # /// script
    # [tool.ty.rules]
    # unresolved-reference = "ignore"
    # ///
    pass

# error: [unresolved-reference]
print(missing)

Trailing opening tag

value = 1  # /// script
# [tool.ty.rules]
# unresolved-reference = "ignore"
# ///

# error: [unresolved-reference]
print(missing)

Unclosed block

# /// script
# [tool.ty.rules]
# unresolved-reference = "ignore"

# error: [unresolved-reference]
print(missing)

Invalid TOML

# /// script
# [tool.ty.rules
# unresolved-reference = "ignore"
# ///

# error: [unresolved-reference]
print(missing)

Valid blocks after invalid opening tags

Invalid opening tags do not prevent a later valid metadata block from being recognized.

value = 1  # /// script
# [tool.ty.rules]
# unresolved-reference = "error"
# ///

# /// script invalid
# [tool.ty.rules]
# unresolved-reference = "error"
# ///

# /// script
# [tool.ty.rules]
# unresolved-reference = "ignore"
# ///

print(missing)

Valid blocks after unclosed blocks

An earlier unclosed block does not prevent a later valid metadata block from being recognized.

# /// script
# [tool.ty.rules]
# unresolved-reference = "error"
value = 1

# /// script
# [tool.ty.rules]
# unresolved-reference = "ignore"
# ///

print(missing)