[flake8-pyi] Implement PYI046

crates/ruff/resources/test/fixtures/flake8_pyi/PYI046.py

@@ -0,0 +1,18 @@
+import typing
+from typing import Protocol
+
+
+class _Foo(Protocol):
+    bar: int
+
+
+class _Bar(typing.Protocol):
+    bar: int
+
+
+# OK
+class _UsedPrivateProtocol(Protocol):
+    bar: int
+
+
+def uses__UsedPrivateProtocol(arg: _UsedPrivateProtocol) -> None: ...

crates/ruff/resources/test/fixtures/flake8_pyi/PYI046.pyi

@@ -0,0 +1,18 @@
+import typing
+from typing import Protocol
+
+
+class _Foo(object, Protocol):
+    bar: int
+
+
+class _Bar(typing.Protocol):
+    bar: int
+
+
+# OK
+class _UsedPrivateProtocol(Protocol):
+    bar: int
+
+
+def uses__UsedPrivateProtocol(arg: _UsedPrivateProtocol) -> None: ...

crates/ruff/src/checkers/ast/analyze/bindings.rs

@@ -11,6 +11,7 @@ pub(crate) fn bindings(checker: &mut Checker) {
         Rule::UnaliasedCollectionsAbcSetImport,
         Rule::UnconventionalImportAlias,
         Rule::UnusedVariable,
+        Rule::UnusedPrivateProtocol,
     ]) {
         return;
     }
@@ -63,6 +64,13 @@ pub(crate) fn bindings(checker: &mut Checker) {
                     checker.diagnostics.push(diagnostic);
                 }
             }
+            if checker.enabled(Rule::UnusedPrivateProtocol) {
+                if let Some(diagnostic) =
+                    flake8_pyi::rules::unused_private_protocol(checker, binding)
+                {
+                    checker.diagnostics.push(diagnostic);
+                }
+            }
         }
     }
 }

crates/ruff/src/checkers/ast/mod.rs

@@ -722,16 +722,27 @@ where
                     BindingFlags::empty(),
                 );
             }
-            Stmt::ClassDef(ast::StmtClassDef { name, .. }) => {
+            Stmt::ClassDef(ast::StmtClassDef { name, bases, .. }) => {
+                let mut flags = BindingFlags::empty();
                 let scope_id = self.semantic.scope_id;
                 self.deferred.scopes.push(scope_id);
                 self.semantic.pop_scope();
                 self.semantic.pop_definition();
+
+                if name.starts_with('_') {
+                    if bases
+                        .iter()
+                        .any(|base| self.semantic.match_typing_expr(base, "Protocol"))
+                    {
+                        flags |= BindingFlags::PRIVATE_TYPE_PROTOCOL;
+                    }
+                }
+
                 self.add_binding(
                     name,
                     stmt.identifier(),
                     BindingKind::ClassDefinition(scope_id),
-                    BindingFlags::empty(),
+                    flags,
                 );
             }
             _ => {}

crates/ruff/src/codes.rs

@@ -649,6 +649,7 @@ pub fn code_to_rule(linter: Linter, code: &str) -> Option<(RuleGroup, Rule)> {
         (Flake8Pyi, "043") => (RuleGroup::Unspecified, rules::flake8_pyi::rules::TSuffixedTypeAlias),
         (Flake8Pyi, "044") => (RuleGroup::Unspecified, rules::flake8_pyi::rules::FutureAnnotationsInStub),
         (Flake8Pyi, "045") => (RuleGroup::Unspecified, rules::flake8_pyi::rules::IterMethodReturnIterable),
+        (Flake8Pyi, "046") => (RuleGroup::Unspecified, rules::flake8_pyi::rules::UnusedPrivateProtocol),
         (Flake8Pyi, "048") => (RuleGroup::Unspecified, rules::flake8_pyi::rules::StubBodyMultipleStatements),
         (Flake8Pyi, "050") => (RuleGroup::Unspecified, rules::flake8_pyi::rules::NoReturnArgumentAnnotationInStub),
         (Flake8Pyi, "052") => (RuleGroup::Unspecified, rules::flake8_pyi::rules::UnannotatedAssignmentInStub),

crates/ruff/src/rules/flake8_pyi/mod.rs

@@ -93,6 +93,8 @@ mod tests {
     #[test_case(Rule::TypeAliasWithoutAnnotation, Path::new("PYI026.pyi"))]
     #[test_case(Rule::UnsupportedMethodCallOnAll, Path::new("PYI056.py"))]
     #[test_case(Rule::UnsupportedMethodCallOnAll, Path::new("PYI056.pyi"))]
+    #[test_case(Rule::UnusedPrivateProtocol, Path::new("PYI046.py"))]
+    #[test_case(Rule::UnusedPrivateProtocol, Path::new("PYI046.pyi"))]
     fn rules(rule_code: Rule, path: &Path) -> Result<()> {
         let snapshot = format!("{}_{}", rule_code.noqa_code(), path.to_string_lossy());
         let diagnostics = test_path(

crates/ruff/src/rules/flake8_pyi/rules/mod.rs

@@ -29,6 +29,7 @@ pub(crate) use unnecessary_literal_union::*;
 pub(crate) use unrecognized_platform::*;
 pub(crate) use unrecognized_version_info::*;
 pub(crate) use unsupported_method_call_on_all::*;
+pub(crate) use unused_private_type_declaration::*;
 
 mod any_eq_ne_annotation;
 mod bad_version_info_comparison;
@@ -61,3 +62,4 @@ mod unnecessary_literal_union;
 mod unrecognized_platform;
 mod unrecognized_version_info;
 mod unsupported_method_call_on_all;
+mod unused_private_type_declaration;

crates/ruff/src/rules/flake8_pyi/rules/unused_private_type_declaration.rs

@@ -0,0 +1,62 @@
+use ruff_diagnostics::{Diagnostic, Violation};
+use ruff_macros::{derive_message_formats, violation};
+use ruff_python_semantic::Binding;
+
+use crate::checkers::ast::Checker;
+
+/// ## What it does
+/// Checks for the presence of unused private `typing.Protocol` definitions.
+///
+/// ## Why is this bad?
+/// A private `typing.Protocol` that is defined but not used is likely a mistake, and should
+/// be removed to avoid confusion.
+///
+/// ## Example
+/// ```python
+/// import typing
+///
+/// class _PrivateProtocol(typing.Protocol):
+///     foo: int
+/// ```
+///
+/// Use instead:
+/// ```python
+/// import typing
+///
+/// class _PrivateProtocol(typing.Protocol):
+///     foo: int
+///
+/// def func(arg: _PrivateProtocol) -> None: ...
+/// ```
+#[violation]
+pub struct UnusedPrivateProtocol {
+    name: String,
+}
+
+impl Violation for UnusedPrivateProtocol {
+    #[derive_message_formats]
+    fn message(&self) -> String {
+        let UnusedPrivateProtocol { name } = self;
+        format!("Protocol `{name}` is never used")
+    }
+}
+
+/// PYI046
+pub(crate) fn unused_private_protocol(checker: &Checker, binding: &Binding) -> Option<Diagnostic> {
+    if !binding.kind.is_class_definition() {
+        return None;
+    }
+    if !binding.is_private_protocol() {
+        return None;
+    }
+    if binding.is_used() {
+        return None;
+    }
+
+    Some(Diagnostic::new(
+        UnusedPrivateProtocol {
+            name: binding.name(checker.locator()).to_string(),
+        },
+        binding.range,
+    ))
+}

crates/ruff/src/rules/flake8_pyi/snapshots/ruff__rules__flake8_pyi__tests__PYI046_PYI046.py.snap

@@ -0,0 +1,4 @@
+---
+source: crates/ruff/src/rules/flake8_pyi/mod.rs
+---
+

crates/ruff/src/rules/flake8_pyi/snapshots/ruff__rules__flake8_pyi__tests__PYI046_PYI046.pyi.snap

@@ -0,0 +1,18 @@
+---
+source: crates/ruff/src/rules/flake8_pyi/mod.rs
+---
+PYI046.pyi:5:7: PYI046 Protocol `_Foo` is never used
+  |
+5 | class _Foo(object, Protocol):
+  |       ^^^^ PYI046
+6 |     bar: int
+  |
+
+PYI046.pyi:9:7: PYI046 Protocol `_Bar` is never used
+   |
+ 9 | class _Bar(typing.Protocol):
+   |       ^^^^ PYI046
+10 |     bar: int
+   |
+
+

crates/ruff_python_semantic/src/binding.rs

@@ -94,6 +94,11 @@ impl<'a> Binding<'a> {
         )
     }
 
+    /// Return `true` if this [`Binding`] represents a `typing.Protocol` definition.
+    pub const fn is_private_protocol(&self) -> bool {
+        self.flags.intersects(BindingFlags::PRIVATE_TYPE_PROTOCOL)
+    }
+
     /// Return `true` if this binding redefines the given binding.
     pub fn redefines(&self, existing: &'a Binding) -> bool {
         match &self.kind {
@@ -264,6 +269,17 @@ bitflags! {
         /// __all__ = [1]
         /// ```
         const INVALID_ALL_OBJECT = 1 << 6;
+
+        /// The binding represents a private `typing.Protocol`.
+        ///
+        /// For example, the binding could be `_PrivateProtocol` in:
+        /// ```python
+        /// import typing
+        ///
+        /// class _PrivateProtocol(typing.Protocol):
+        ///     foo: int
+        /// ```
+        const PRIVATE_TYPE_PROTOCOL = 1 << 7;
     }
 }