Improve docs on how to stop Ruff and ty disagreeing with each other (#21644)

## Summary

Lots of Ruff rules encourage you to make changes that might then cause
ty to start complaining about Liskov violations. Most of these Ruff
rules already refrain from complaining about a method if they see that
the method is decorated with `@override`, but this usually isn't
documented. This PR updates the docs of many Ruff rules to note that
they refrain from complaining about `@override`-decorated methods, and
also adds a similar note to the ty `invalid-method-override`
documentation.

Helps with
https://github.com/astral-sh/ty/issues/1644#issuecomment-3581663859

## Test Plan

- `uvx prek run -a` locally
- CI on this PR
This commit is contained in:
Alex Waygood
2025-11-27 08:18:21 +00:00
committed by GitHub
parent c7107a5a90
commit 792ec3e96e
14 changed files with 150 additions and 4 deletions

View File

@@ -2114,7 +2114,27 @@ declare_lint! {
/// be avoided wherever possible. As part of this check, therefore, ty enforces that `__eq__`
/// and `__ne__` methods accept `object` as their second argument.
///
/// ### Why does ty disagree with Ruff about how to write my method?
///
/// Ruff has several rules that will encourage you to rename a parameter, or change its type
/// signature, if it thinks you're falling into a certain anti-pattern. For example, Ruff's
/// [ARG002](https://docs.astral.sh/ruff/rules/unused-method-argument/) rule recommends that an
/// unused parameter should either be removed or renamed to start with `_`. Applying either of
/// these suggestions can cause ty to start reporting an `invalid-method-override` error if
/// the function in question is a method on a subclass that overrides a method on a superclass,
/// and the change would cause the subclass method to no longer accept all argument combinations
/// that the superclass method accepts.
///
/// This can usually be resolved by adding [`@typing.override`][override] to your method
/// definition. Ruff knows that a method decorated with `@typing.override` is intended to
/// override a method by the same name on a superclass, and avoids reporting rules like ARG002
/// for such methods; it knows that the changes recommended by ARG002 would violate the Liskov
/// Substitution Principle.
///
/// Correct use of `@override` is enforced by ty's `invalid-explicit-override` rule.
///
/// [Liskov Substitution Principle]: https://en.wikipedia.org/wiki/Liskov_substitution_principle
/// [override]: https://docs.python.org/3/library/typing.html#typing.override
pub(crate) static INVALID_METHOD_OVERRIDE = {
summary: "detects method definitions that violate the Liskov Substitution Principle",
status: LintStatus::stable("0.0.1-alpha.20"),