From 2e75cfbfe7fa79b71f76499d80058597e4c9d83b Mon Sep 17 00:00:00 2001 From: Calum Young <32770960+calumy@users.noreply.github.com> Date: Wed, 28 Aug 2024 13:20:40 +0100 Subject: [PATCH] Format `PYI` examples in docs as `.pyi`-file snippets (#13116) --- .../flake8_pyi/rules/any_eq_ne_annotation.rs | 4 +-- .../rules/bad_version_info_comparison.rs | 18 ++++------- .../rules/collections_named_tuple.rs | 5 ++-- .../rules/complex_assignment_in_stub.rs | 7 ++--- .../rules/complex_if_statement_in_stub.rs | 10 +++---- .../rules/custom_type_var_return_type.rs | 9 ++---- .../flake8_pyi/rules/docstring_in_stubs.rs | 4 +-- .../rules/ellipsis_in_non_empty_class_body.rs | 4 +-- .../flake8_pyi/rules/exit_annotations.rs | 6 ++-- .../rules/no_return_argument_annotation.rs | 4 +-- .../flake8_pyi/rules/non_empty_stub_body.rs | 4 +-- .../flake8_pyi/rules/non_self_return_type.rs | 11 ++----- .../rules/numeric_literal_too_long.rs | 4 +-- .../flake8_pyi/rules/pass_in_class_body.rs | 4 +-- .../rules/pass_statement_stub_body.rs | 4 +-- .../rules/pre_pep570_positional_argument.rs | 4 +-- .../flake8_pyi/rules/prefix_type_params.rs | 4 +-- .../rules/quoted_annotation_in_stub.rs | 4 +-- .../rules/redundant_final_literal.rs | 4 +-- .../rules/redundant_literal_union.rs | 4 +-- .../rules/redundant_numeric_union.rs | 4 +-- .../rules/flake8_pyi/rules/simple_defaults.rs | 20 ++++++------- .../rules/str_or_repr_defined_in_stub.rs | 2 +- .../rules/string_or_bytes_too_long.rs | 4 +-- .../rules/stub_body_multiple_statements.rs | 4 +-- .../flake8_pyi/rules/type_alias_naming.rs | 8 ++--- .../flake8_pyi/rules/type_comment_in_stub.rs | 4 +-- .../unaliased_collections_abc_set_import.rs | 4 +-- .../rules/unnecessary_literal_union.rs | 4 +-- .../rules/unnecessary_type_union.rs | 4 +-- .../flake8_pyi/rules/unrecognized_platform.rs | 14 ++++----- .../rules/unrecognized_version_info.rs | 30 ++++++++----------- .../rules/unsupported_method_call_on_all.rs | 4 +-- .../rules/unused_private_type_definition.rs | 21 +++++-------- docs/requirements-insiders.txt | 3 ++ docs/requirements.txt | 3 ++ scripts/check_docs_formatted.py | 22 ++++++++++---- 37 files changed, 125 insertions(+), 148 deletions(-) diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/any_eq_ne_annotation.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/any_eq_ne_annotation.rs index d2038aecbec86..df6244fb2c988 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/any_eq_ne_annotation.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/any_eq_ne_annotation.rs @@ -27,14 +27,14 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// class Foo: /// def __eq__(self, obj: typing.Any) -> bool: ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// class Foo: /// def __eq__(self, obj: object) -> bool: ... /// ``` diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/bad_version_info_comparison.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/bad_version_info_comparison.rs index c8c5834605af9..2c189c963c80a 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/bad_version_info_comparison.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/bad_version_info_comparison.rs @@ -34,19 +34,17 @@ use crate::registry::Rule; /// ``` /// /// ## Example -/// ```python +/// ```pyi /// import sys /// -/// if sys.version_info > (3, 8): -/// ... +/// if sys.version_info > (3, 8): ... /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// import sys /// -/// if sys.version_info >= (3, 9): -/// ... +/// if sys.version_info >= (3, 9): ... /// ``` #[violation] pub struct BadVersionInfoComparison; @@ -70,27 +68,23 @@ impl Violation for BadVersionInfoComparison { /// /// ## Example /// -/// ```python +/// ```pyi /// import sys /// /// if sys.version_info < (3, 10): -/// /// def read_data(x, *, preserve_order=True): ... /// /// else: -/// /// def read_data(x): ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// if sys.version_info >= (3, 10): -/// /// def read_data(x): ... /// /// else: -/// /// def read_data(x, *, preserve_order=True): ... /// ``` #[violation] diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/collections_named_tuple.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/collections_named_tuple.rs index e0939087f35d2..4f63b454d7ecf 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/collections_named_tuple.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/collections_named_tuple.rs @@ -21,17 +21,16 @@ use crate::checkers::ast::Checker; /// precisely. /// /// ## Example -/// ```python +/// ```pyi /// from collections import namedtuple /// /// person = namedtuple("Person", ["name", "age"]) /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// from typing import NamedTuple /// -/// /// class Person(NamedTuple): /// name: str /// age: int diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/complex_assignment_in_stub.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/complex_assignment_in_stub.rs index 5f33284ee9ce7..711698f7857ac 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/complex_assignment_in_stub.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/complex_assignment_in_stub.rs @@ -20,27 +20,24 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// from typing import TypeAlias /// /// a = b = int /// -/// /// class Klass: ... /// -/// /// Klass.X: TypeAlias = int /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// from typing import TypeAlias /// /// a: TypeAlias = int /// b: TypeAlias = int /// -/// /// class Klass: /// X: TypeAlias = int /// ``` diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/complex_if_statement_in_stub.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/complex_if_statement_in_stub.rs index 6a8fe34dfa4b4..06abeecc38b0a 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/complex_if_statement_in_stub.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/complex_if_statement_in_stub.rs @@ -16,19 +16,17 @@ use crate::checkers::ast::Checker; /// analyze your code. /// /// ## Example -/// ```python +/// ```pyi /// import sys /// -/// if (3, 10) <= sys.version_info < (3, 12): -/// ... +/// if (3, 10) <= sys.version_info < (3, 12): ... /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// import sys /// -/// if sys.version_info >= (3, 10) and sys.version_info < (3, 12): -/// ... +/// if sys.version_info >= (3, 10) and sys.version_info < (3, 12): ... /// ``` /// /// ## References diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/custom_type_var_return_type.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/custom_type_var_return_type.rs index 07b5e093b824a..900ea4d3fdf6e 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/custom_type_var_return_type.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/custom_type_var_return_type.rs @@ -25,27 +25,22 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// class Foo: /// def __new__(cls: type[_S], *args: str, **kwargs: int) -> _S: ... -/// /// def foo(self: _S, arg: bytes) -> _S: ... -/// /// @classmethod /// def bar(cls: type[_S], arg: int) -> _S: ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// from typing import Self /// -/// /// class Foo: /// def __new__(cls, *args: str, **kwargs: int) -> Self: ... -/// /// def foo(self, arg: bytes) -> Self: ... -/// /// @classmethod /// def bar(cls, arg: int) -> Self: ... /// ``` diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/docstring_in_stubs.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/docstring_in_stubs.rs index 4eceb88fdeb91..e03d359b963e0 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/docstring_in_stubs.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/docstring_in_stubs.rs @@ -15,7 +15,7 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// def func(param: int) -> str: /// """This is a docstring.""" /// ... @@ -23,7 +23,7 @@ use crate::checkers::ast::Checker; /// /// Use instead: /// -/// ```python +/// ```pyi /// def func(param: int) -> str: ... /// ``` #[violation] diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/ellipsis_in_non_empty_class_body.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/ellipsis_in_non_empty_class_body.rs index 4ad5b51f7a916..938a40730e7d8 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/ellipsis_in_non_empty_class_body.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/ellipsis_in_non_empty_class_body.rs @@ -15,14 +15,14 @@ use crate::fix; /// is redundant. /// /// ## Example -/// ```python +/// ```pyi /// class Foo: /// ... /// value: int /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// class Foo: /// value: int /// ``` diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/exit_annotations.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/exit_annotations.rs index c2ea9df8e5a4f..71e2d162a93bf 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/exit_annotations.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/exit_annotations.rs @@ -24,10 +24,9 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// from types import TracebackType /// -/// /// class Foo: /// def __exit__( /// self, typ: BaseException, exc: BaseException, tb: TracebackType @@ -36,10 +35,9 @@ use crate::checkers::ast::Checker; /// /// Use instead: /// -/// ```python +/// ```pyi /// from types import TracebackType /// -/// /// class Foo: /// def __exit__( /// self, diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/no_return_argument_annotation.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/no_return_argument_annotation.rs index 8ebaab9edb49a..f7decb5e5384f 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/no_return_argument_annotation.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/no_return_argument_annotation.rs @@ -22,14 +22,14 @@ use crate::settings::types::PythonVersion::Py311; /// members). /// /// ## Example -/// ```python +/// ```pyi /// from typing import NoReturn /// /// def foo(x: NoReturn): ... /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// from typing import Never /// /// def foo(x: Never): ... diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/non_empty_stub_body.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/non_empty_stub_body.rs index 14d117791b33f..2324a9cb20f63 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/non_empty_stub_body.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/non_empty_stub_body.rs @@ -15,13 +15,13 @@ use crate::checkers::ast::Checker; /// for this purpose. /// /// ## Example -/// ```python +/// ```pyi /// def double(x: int) -> int: /// return x * 2 /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// def double(x: int) -> int: ... /// ``` /// diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/non_self_return_type.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/non_self_return_type.rs index 652e7632d952b..eaf028ffa761e 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/non_self_return_type.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/non_self_return_type.rs @@ -51,30 +51,23 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// class Foo: /// def __new__(cls, *args: Any, **kwargs: Any) -> Foo: ... -/// /// def __enter__(self) -> Foo: ... -/// /// async def __aenter__(self) -> Foo: ... -/// /// def __iadd__(self, other: Foo) -> Foo: ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// from typing_extensions import Self /// -/// /// class Foo: /// def __new__(cls, *args: Any, **kwargs: Any) -> Self: ... -/// /// def __enter__(self) -> Self: ... -/// /// async def __aenter__(self) -> Self: ... -/// /// def __iadd__(self, other: Foo) -> Self: ... /// ``` /// ## References diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/numeric_literal_too_long.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/numeric_literal_too_long.rs index 9930f6c19e0e9..11e70892fbb47 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/numeric_literal_too_long.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/numeric_literal_too_long.rs @@ -20,13 +20,13 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// def foo(arg: int = 693568516352839939918568862861217771399698285293568) -> None: ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// def foo(arg: int = ...) -> None: ... /// ``` #[violation] diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/pass_in_class_body.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/pass_in_class_body.rs index b6c2fbc365fa3..06e13a6090fae 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/pass_in_class_body.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/pass_in_class_body.rs @@ -15,14 +15,14 @@ use crate::fix; /// stubs. /// /// ## Example -/// ```python +/// ```pyi /// class MyClass: /// x: int /// pass /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// class MyClass: /// x: int /// ``` diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/pass_statement_stub_body.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/pass_statement_stub_body.rs index 940b6afca3133..ce2dd53b61be9 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/pass_statement_stub_body.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/pass_statement_stub_body.rs @@ -13,12 +13,12 @@ use crate::checkers::ast::Checker; /// in stub files. /// /// ## Example -/// ```python +/// ```pyi /// def foo(bar: int) -> list[int]: pass /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// def foo(bar: int) -> list[int]: ... /// ``` /// diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/pre_pep570_positional_argument.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/pre_pep570_positional_argument.rs index d24a284978d10..135dab0647746 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/pre_pep570_positional_argument.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/pre_pep570_positional_argument.rs @@ -17,13 +17,13 @@ use crate::settings::types::PythonVersion; /// /// ## Example /// -/// ```python +/// ```pyi /// def foo(__x: int) -> None: ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// def foo(x: int, /) -> None: ... /// ``` /// diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/prefix_type_params.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/prefix_type_params.rs index 1770ecf2eb5df..a1f696d39990a 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/prefix_type_params.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/prefix_type_params.rs @@ -33,14 +33,14 @@ impl fmt::Display for VarKind { /// internal to the stub. /// /// ## Example -/// ```python +/// ```pyi /// from typing import TypeVar /// /// T = TypeVar("T") /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// from typing import TypeVar /// /// _T = TypeVar("_T") diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/quoted_annotation_in_stub.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/quoted_annotation_in_stub.rs index a3cc1e400bb03..4e6cf0e00856f 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/quoted_annotation_in_stub.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/quoted_annotation_in_stub.rs @@ -16,13 +16,13 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// def function() -> "int": ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// def function() -> int: ... /// ``` /// diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_final_literal.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_final_literal.rs index 8f93ba0d5d968..b3243ab125561 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_final_literal.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_final_literal.rs @@ -16,13 +16,13 @@ use crate::fix::snippet::SourceCodeSnippet; /// /// ## Example /// -/// ```python +/// ```pyi /// x: Final[Literal[42]] /// y: Final[Literal[42]] = 42 /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// x: Final = 42 /// y: Final = 42 /// ``` diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_literal_union.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_literal_union.rs index dfb28cb9bc025..282e17d71c19f 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_literal_union.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_literal_union.rs @@ -24,14 +24,14 @@ use crate::fix::snippet::SourceCodeSnippet; /// supertypes of `"A"` and `1` respectively. /// /// ## Example -/// ```python +/// ```pyi /// from typing import Literal /// /// x: Literal["A", b"B"] | str /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// from typing import Literal /// /// x: Literal[b"B"] | str diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_numeric_union.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_numeric_union.rs index 3a64c72530b98..00c4296fa658b 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_numeric_union.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/redundant_numeric_union.rs @@ -27,13 +27,13 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// def foo(x: float | int | str) -> None: ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// def foo(x: float | str) -> None: ... /// ``` /// diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/simple_defaults.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/simple_defaults.rs index e14246f0e5de6..a16bee59b5264 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/simple_defaults.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/simple_defaults.rs @@ -31,13 +31,13 @@ use crate::settings::types::PythonVersion; /// /// ## Example /// -/// ```python +/// ```pyi /// def foo(arg: list[int] = list(range(10_000))) -> None: ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// def foo(arg: list[int] = ...) -> None: ... /// ``` /// @@ -77,13 +77,13 @@ impl AlwaysFixableViolation for TypedArgumentDefaultInStub { /// /// ## Example /// -/// ```python +/// ```pyi /// def foo(arg=[]) -> None: ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// def foo(arg=...) -> None: ... /// ``` /// @@ -122,12 +122,12 @@ impl AlwaysFixableViolation for ArgumentDefaultInStub { /// or varies according to the current platform or Python version. /// /// ## Example -/// ```python +/// ```pyi /// foo: str = "..." /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// foo: str = ... /// ``` /// @@ -176,12 +176,12 @@ impl Violation for UnannotatedAssignmentInStub { /// runtime counterparts. /// /// ## Example -/// ```python +/// ```pyi /// __all__: list[str] /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// __all__: list[str] = ["foo", "bar"] /// ``` #[violation] @@ -210,12 +210,12 @@ impl Violation for UnassignedSpecialVariableInStub { /// to a normal variable assignment. /// /// ## Example -/// ```python +/// ```pyi /// Vector = list[float] /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// from typing import TypeAlias /// /// Vector: TypeAlias = list[float] diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/str_or_repr_defined_in_stub.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/str_or_repr_defined_in_stub.rs index 9d40deaa2f447..ed50e59850afd 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/str_or_repr_defined_in_stub.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/str_or_repr_defined_in_stub.rs @@ -19,7 +19,7 @@ use crate::fix::edits::delete_stmt; /// /// ## Example /// -/// ```python +/// ```pyi /// class Foo: /// def __repr__(self) -> str: ... /// ``` diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/string_or_bytes_too_long.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/string_or_bytes_too_long.rs index 1d7a85b2470e2..fdec385be88ec 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/string_or_bytes_too_long.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/string_or_bytes_too_long.rs @@ -23,13 +23,13 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// def foo(arg: str = "51 character stringgggggggggggggggggggggggggggggggg") -> None: ... /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// def foo(arg: str = ...) -> None: ... /// ``` #[violation] diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/stub_body_multiple_statements.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/stub_body_multiple_statements.rs index 34d33fea62334..608603d31654e 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/stub_body_multiple_statements.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/stub_body_multiple_statements.rs @@ -16,7 +16,7 @@ use crate::checkers::ast::Checker; /// /// ## Example /// -/// ```python +/// ```pyi /// def function(): /// x = 1 /// y = 2 @@ -25,7 +25,7 @@ use crate::checkers::ast::Checker; /// /// Use instead: /// -/// ```python +/// ```pyi /// def function(): ... /// ``` #[violation] diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/type_alias_naming.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/type_alias_naming.rs index d9b47cb35ac22..937b7ac5cd1cc 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/type_alias_naming.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/type_alias_naming.rs @@ -13,12 +13,12 @@ use crate::checkers::ast::Checker; /// to distinguish them from other variables. /// /// ## Example -/// ```python +/// ```pyi /// type_alias_name: TypeAlias = int /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// TypeAliasName: TypeAlias = int /// ``` #[violation] @@ -45,14 +45,14 @@ impl Violation for SnakeCaseTypeAlias { /// be avoided. /// /// ## Example -/// ```python +/// ```pyi /// from typing import TypeAlias /// /// _MyTypeT: TypeAlias = int /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// from typing import TypeAlias /// /// _MyType: TypeAlias = int diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/type_comment_in_stub.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/type_comment_in_stub.rs index c21558f590ee0..f250fc419f22f 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/type_comment_in_stub.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/type_comment_in_stub.rs @@ -16,12 +16,12 @@ use ruff_macros::{derive_message_formats, violation}; /// stub files are not executed at runtime. The one exception is `# type: ignore`. /// /// ## Example -/// ```python +/// ```pyi /// x = 1 # type: int /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// x: int = 1 /// ``` #[violation] diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/unaliased_collections_abc_set_import.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/unaliased_collections_abc_set_import.rs index ec8e40a22d7d7..24aa32e1ad85f 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/unaliased_collections_abc_set_import.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/unaliased_collections_abc_set_import.rs @@ -21,12 +21,12 @@ use crate::renamer::Renamer; /// `set` builtin. /// /// ## Example -/// ```python +/// ```pyi /// from collections.abc import Set /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// from collections.abc import Set as AbstractSet /// ``` /// diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/unnecessary_literal_union.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/unnecessary_literal_union.rs index da0c2383b30b5..ed062c8e266ef 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/unnecessary_literal_union.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/unnecessary_literal_union.rs @@ -15,14 +15,14 @@ use crate::checkers::ast::Checker; /// `Literal["foo"] | Literal[42]`, but is clearer and more concise. /// /// ## Example -/// ```python +/// ```pyi /// from typing import Literal /// /// field: Literal[1] | Literal[2] | str /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// from typing import Literal /// /// field: Literal[1, 2] | str diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/unnecessary_type_union.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/unnecessary_type_union.rs index 3799ae8763bf0..1d4128bd563f5 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/unnecessary_type_union.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/unnecessary_type_union.rs @@ -17,12 +17,12 @@ use crate::checkers::ast::Checker; /// annotation, but is cleaner and more concise. /// /// ## Example -/// ```python +/// ```pyi /// field: type[int] | type[float] | str /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// field: type[int | float] | str /// ``` #[violation] diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/unrecognized_platform.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/unrecognized_platform.rs index e10d70d5e8374..8bb38d86431ac 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/unrecognized_platform.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/unrecognized_platform.rs @@ -20,7 +20,7 @@ use crate::registry::Rule; /// `if sys.platform == "linux"`. /// /// ## Example -/// ```python +/// ```pyi /// if sys.platform.startswith("linux"): /// # Linux specific definitions /// ... @@ -30,7 +30,7 @@ use crate::registry::Rule; /// ``` /// /// Instead, use a simple string comparison, such as `==` or `!=`: -/// ```python +/// ```pyi /// if sys.platform == "linux": /// # Linux specific definitions /// ... @@ -64,15 +64,13 @@ impl Violation for UnrecognizedPlatformCheck { /// The list of known platforms is: "linux", "win32", "cygwin", "darwin". /// /// ## Example -/// ```python -/// if sys.platform == "linus": -/// ... +/// ```pyi +/// if sys.platform == "linus": ... /// ``` /// /// Use instead: -/// ```python -/// if sys.platform == "linux": -/// ... +/// ```pyi +/// if sys.platform == "linux": ... /// ``` /// /// ## References diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/unrecognized_version_info.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/unrecognized_version_info.rs index cfefc15d2d303..96185b2f56584 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/unrecognized_version_info.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/unrecognized_version_info.rs @@ -17,19 +17,17 @@ use crate::registry::Rule; /// For example, comparing against a string can lead to unexpected behavior. /// /// ## Example -/// ```python +/// ```pyi /// import sys /// -/// if sys.version_info[0] == "2": -/// ... +/// if sys.version_info[0] == "2": ... /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// import sys /// -/// if sys.version_info[0] == 2: -/// ... +/// if sys.version_info[0] == 2: ... /// ``` /// /// ## References @@ -58,19 +56,17 @@ impl Violation for UnrecognizedVersionInfoCheck { /// and minor versions. /// /// ## Example -/// ```python +/// ```pyi /// import sys /// -/// if sys.version_info >= (3, 4, 3): -/// ... +/// if sys.version_info >= (3, 4, 3): ... /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// import sys /// -/// if sys.version_info >= (3, 4): -/// ... +/// if sys.version_info >= (3, 4): ... /// ``` /// /// ## References @@ -96,19 +92,17 @@ impl Violation for PatchVersionComparison { /// behavior. /// /// ## Example -/// ```python +/// ```pyi /// import sys /// -/// if sys.version_info[:2] == (3,): -/// ... +/// if sys.version_info[:2] == (3,): ... /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// import sys /// -/// if sys.version_info[0] == 3: -/// ... +/// if sys.version_info[0] == 3: ... /// ``` /// /// ## References diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/unsupported_method_call_on_all.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/unsupported_method_call_on_all.rs index 3266dd4862d33..5697c0d0a4d59 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/unsupported_method_call_on_all.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/unsupported_method_call_on_all.rs @@ -16,7 +16,7 @@ use crate::checkers::ast::Checker; /// `__all__`, which is known to be supported by all major type checkers. /// /// ## Example -/// ```python +/// ```pyi /// import sys /// /// __all__ = ["A", "B"] @@ -29,7 +29,7 @@ use crate::checkers::ast::Checker; /// ``` /// /// Use instead: -/// ```python +/// ```pyi /// import sys /// /// __all__ = ["A"] diff --git a/crates/ruff_linter/src/rules/flake8_pyi/rules/unused_private_type_definition.rs b/crates/ruff_linter/src/rules/flake8_pyi/rules/unused_private_type_definition.rs index 0407986ccb928..2a75d7e55cbef 100644 --- a/crates/ruff_linter/src/rules/flake8_pyi/rules/unused_private_type_definition.rs +++ b/crates/ruff_linter/src/rules/flake8_pyi/rules/unused_private_type_definition.rs @@ -16,7 +16,7 @@ use crate::checkers::ast::Checker; /// should either be used, made public, or removed to avoid confusion. /// /// ## Example -/// ```python +/// ```pyi /// import typing /// import typing_extensions /// @@ -50,24 +50,21 @@ impl Violation for UnusedPrivateTypeVar { /// /// ## Example /// -/// ```python +/// ```pyi /// import typing /// -/// /// class _PrivateProtocol(typing.Protocol): /// foo: int /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// import typing /// -/// /// class _PrivateProtocol(typing.Protocol): /// foo: int /// -/// /// def func(arg: _PrivateProtocol) -> None: ... /// ``` #[violation] @@ -93,7 +90,7 @@ impl Violation for UnusedPrivateProtocol { /// /// ## Example /// -/// ```python +/// ```pyi /// import typing /// /// _UnusedTypeAlias: typing.TypeAlias = int @@ -101,12 +98,11 @@ impl Violation for UnusedPrivateProtocol { /// /// Use instead: /// -/// ```python +/// ```pyi /// import typing /// /// _UsedTypeAlias: typing.TypeAlias = int /// -/// /// def func(arg: _UsedTypeAlias) -> _UsedTypeAlias: ... /// ``` #[violation] @@ -132,24 +128,21 @@ impl Violation for UnusedPrivateTypeAlias { /// /// ## Example /// -/// ```python +/// ```pyi /// import typing /// -/// /// class _UnusedPrivateTypedDict(typing.TypedDict): /// foo: list[int] /// ``` /// /// Use instead: /// -/// ```python +/// ```pyi /// import typing /// -/// /// class _UsedPrivateTypedDict(typing.TypedDict): /// foo: set[str] /// -/// /// def func(arg: _UsedPrivateTypedDict) -> _UsedPrivateTypedDict: ... /// ``` #[violation] diff --git a/docs/requirements-insiders.txt b/docs/requirements-insiders.txt index 4dc3397b3e2f9..b0641f5e15e82 100644 --- a/docs/requirements-insiders.txt +++ b/docs/requirements-insiders.txt @@ -6,3 +6,6 @@ mkdocs-redirects==1.2.1 mdformat==0.7.17 mdformat-mkdocs==3.0.0 mdformat-admon==2.0.6 +# Using a commit from pygments main branch so we get +# https://github.com/pygments/pygments/pull/2773 before it's been released +pygments @ git+https://github.com/pygments/pygments.git@67b460fdde6d9a00342b5102b37b3a8399f0e8ef diff --git a/docs/requirements.txt b/docs/requirements.txt index f8daa571dfe2f..6e6f57010d766 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -6,3 +6,6 @@ mkdocs-redirects==1.2.1 mdformat==0.7.17 mdformat-mkdocs==3.0.0 mdformat-admon==2.0.6 +# Using a commit from pygments main branch so we get +# https://github.com/pygments/pygments/pull/2773 before it's been released +pygments @ git+https://github.com/pygments/pygments.git@67b460fdde6d9a00342b5102b37b3a8399f0e8ef diff --git a/scripts/check_docs_formatted.py b/scripts/check_docs_formatted.py index 4a3a70ca5eae6..c262722056267 100755 --- a/scripts/check_docs_formatted.py +++ b/scripts/check_docs_formatted.py @@ -10,13 +10,13 @@ import textwrap from pathlib import Path from re import Match -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, Literal if TYPE_CHECKING: from collections.abc import Sequence SNIPPED_RE = re.compile( - r"(?P^(?P *)```\s*python\n)" + r"(?P^(?P *)```(?:\s*(?P\w+))?\n)" r"(?P.*?)" r"(?P^(?P=indent)```\s*$)", re.DOTALL | re.MULTILINE, @@ -120,12 +120,12 @@ class InvalidInput(ValueError): """Raised when ruff fails to parse file.""" -def format_str(code: str) -> str: +def format_str(code: str, extension: Literal["py", "pyi"]) -> str: """Format a code block with ruff by writing to a temporary file.""" # Run ruff to format the tmp file try: completed_process = subprocess.run( - ["ruff", "format", "-"], + ["ruff", "format", "--stdin-filename", f"file.{extension}", "-"], check=True, capture_output=True, text=True, @@ -149,9 +149,21 @@ def format_contents(src: str) -> tuple[str, Sequence[CodeBlockError]]: errors: list[CodeBlockError] = [] def _snipped_match(match: Match[str]) -> str: + language = match["language"] + extension: Literal["py", "pyi"] + match language: + case "python": + extension = "py" + case "pyi": + extension = "pyi" + case _: + # We are only interested in checking the formatting of py or pyi code + # blocks so we can return early if the language is not one of these. + return f'{match["before"]}{match["code"]}{match["after"]}' + code = textwrap.dedent(match["code"]) try: - code = format_str(code) + code = format_str(code, extension) except InvalidInput as e: errors.append(CodeBlockError(e)) except NotImplementedError as e: