mirror of
https://github.com/astral-sh/ruff.git
synced 2026-11-21 12:16:15 +08:00
## 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.
2.7 KiB
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)