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 d2038aecbe..df6244fb2c 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 c8c5834605..2c189c963c 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 e0939087f3..4f63b454d7 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 5f33284ee9..711698f785 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 6a8fe34dfa..06abeecc38 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 07b5e093b8..900ea4d3fd 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 4eceb88fde..e03d359b96 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 4ad5b51f7a..938a40730e 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 c2ea9df8e5..71e2d162a9 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 8ebaab9edb..f7decb5e53 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 14d117791b..2324a9cb20 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 652e7632d9..eaf028ffa7 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 9930f6c19e..11e70892fb 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 b6c2fbc365..06e13a6090 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 940b6afca3..ce2dd53b61 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 d24a284978..135dab0647 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 1770ecf2eb..a1f696d399 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 a3cc1e400b..4e6cf0e008 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 8f93ba0d5d..b3243ab125 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 dfb28cb9bc..282e17d71c 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 3a64c72530..00c4296fa6 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 e14246f0e5..a16bee59b5 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 9d40deaa2f..ed50e59850 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 1d7a85b247..fdec385be8 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 34d33fea62..608603d316 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 d9b47cb35a..937b7ac5cd 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 c21558f590..f250fc419f 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 ec8e40a22d..24aa32e1ad 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 da0c2383b3..ed062c8e26 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 3799ae8763..1d4128bd56 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 e10d70d5e8..8bb38d8643 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 cfefc15d2d..96185b2f56 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 3266dd4862..5697c0d0a4 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 0407986ccb..2a75d7e55c 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 4dc3397b3e..b0641f5e15 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 f8daa571df..6e6f57010d 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 4a3a70ca5e..c262722056 100755 --- a/scripts/check_docs_formatted.py +++ b/scripts/check_docs_formatted.py @@ -10,13 +10,13 @@ import subprocess 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: