Add consider-narrowing-parameter check (R1738)

custom_dict.txt

@@ -1,6 +1,7 @@
 abc
 abcmeta
 abspath
+abstractmethod
 abstractproperty
 analyse
 analysed

doc/data/messages/c/consider-narrowing-parameter/bad.py

@@ -0,0 +1,10 @@
+def _print_color(fruit):  # [consider-narrowing-parameter]
+    print("This fruit is", fruit.color)
+    print("I like", fruit.color)
+
+
+class Apple:
+    color = "red"
+
+
+_print_color(Apple())

doc/data/messages/c/consider-narrowing-parameter/details.rst

@@ -0,0 +1,18 @@
+Passing a whole object when only one part of it is needed ties the function
+to the object's structure for no benefit: this is sometimes called *stamp
+coupling*. Callers must build (or know about) the whole object even when they
+only have the one value the function really needs. Accepting the value itself
+(*data coupling*) keeps the function independent.
+
+By default only private and nested functions are checked, because narrowing a
+public signature is a breaking change for callers: set
+``suggest-narrowing-public-parameters`` to ``yes`` to check public functions
+and methods too.
+
+Functions whose signature is imposed by a convention or a framework can be
+excluded with the ``ignored-function-names`` option — for example visitor
+callbacks, or pytest test functions whose parameters are fixtures injected by
+name::
+
+    [REFACTORING]
+    ignored-function-names=(visit_|leave_|test_|pytest_).*

doc/data/messages/c/consider-narrowing-parameter/good.py

@@ -0,0 +1,10 @@
+def _print_color(color):
+    print("This fruit is", color)
+    print("I like", color)
+
+
+class Apple:
+    color = "red"
+
+
+_print_color(Apple().color)

doc/user_guide/checkers/features.rst

@@ -949,6 +949,10 @@ Refactoring checker Messages
 :use-yield-from (R1737): *Use 'yield from' directly instead of yielding each element one by one*
   Yielding directly from the iterator is faster and arguably cleaner code than
   yielding each element one by one in the loop.
+:consider-narrowing-parameter (R1738): *Parameter '%s' is only used as '%s.%s'; consider accepting the attribute value directly*
+  Emitted when a function or method parameter is only ever used to access a
+  single attribute, meaning the function could accept that attribute's value
+  directly and reduce coupling with the caller.
 :unnecessary-negation (C0117): *Consider changing "%s" to "%s"*
   Used when a boolean expression contains an unneeded negation, e.g. when two
   negation operators cancel each other out.

doc/user_guide/configuration/all-options.rst

@@ -1245,6 +1245,13 @@ Standard Checkers
 
 ``Refactoring`` **Checker**
 ---------------------------
+--ignored-function-names
+""""""""""""""""""""""""
+*Regular expression matching names of functions or methods whose signature is imposed by a convention or a protocol (for example visitor callbacks such as '(visit|leave)_.*'), and that 'consider-narrowing-parameter' should not be raised for.*
+
+**Default:** ``""``
+
+
 --max-nested-blocks
 """""""""""""""""""
 *Maximum number of nested blocks for function / method body*
@@ -1267,6 +1274,13 @@ Standard Checkers
 **Default:**  ``True``
 
 
+--suggest-narrowing-public-parameters
+"""""""""""""""""""""""""""""""""""""
+*Let 'consider-narrowing-parameter' be raised for public functions and methods too. By default only private (single leading underscore) and nested functions are checked, because narrowing a public signature is a breaking change for callers.*
+
+**Default:**  ``False``
+
+
 
 .. raw:: html
 
@@ -1278,12 +1292,16 @@ Standard Checkers
 .. code-block:: toml
 
    [tool.pylint.refactoring]
+   ignored-function-names = ""
+
    max-nested-blocks = 5
 
    never-returning-functions = ["sys.exit", "argparse.parse_error"]
 
    suggest-join-with-non-empty-separator = true
 
+   suggest-narrowing-public-parameters = false
+
 
 
 .. raw:: html

doc/user_guide/messages/messages_overview.rst

@@ -595,6 +595,7 @@ All messages in the refactor category:
    refactor/consider-alternative-union-syntax
    refactor/consider-math-not-float
    refactor/consider-merging-isinstance
+   refactor/consider-narrowing-parameter
    refactor/consider-refactoring-into-while-condition
    refactor/consider-swap-variables
    refactor/consider-using-alias

doc/whatsnew/fragments/11236.new_check

@@ -0,0 +1,8 @@
+Added the ``consider-narrowing-parameter`` check: emitted when a private or
+nested function only ever uses a single attribute of one of its parameters,
+meaning it could accept the attribute value directly. Use the
+``suggest-narrowing-public-parameters`` option to also check public functions,
+and ``ignored-function-names`` to exclude functions whose signature is imposed
+by a convention.
+
+Refs #11236

examples/pylintrc

@@ -480,6 +480,18 @@ notes-rgx=
 
 [REFACTORING]
 
+# Regular expression matching names of functions or methods whose signature is
+# imposed by a convention or a protocol (for example visitor callbacks such as
+# '(visit|leave)_.*'), and that 'consider-narrowing-parameter' should not be
+# raised for.
+ignored-function-names=
+
+# Let 'consider-narrowing-parameter' be raised for public functions and
+# methods too. By default only private (single leading underscore) and nested
+# functions are checked, because narrowing a public signature is a breaking
+# change for callers.
+suggest-narrowing-public-parameters=no
+
 # Maximum number of nested blocks for function / method body
 max-nested-blocks=5