rspec/rules/S5720/python/rule.adoc

This rule raises an issue when the first parameter of an instance method is not called "self".

== Why is this an issue?

Instance methods, i.e. methods not annotated with ``++@classmethod++`` or ``++@staticmethod++``, are expected to have at least one parameter. This parameter will reference the object instance on which the method is called. By convention, this first parameter is named "self".

Naming the first parameter something different from "self" is not recommended as it could lead to confusion. It might indicate that the "self" parameter was forgotten, in which case calling the method will most probably fail.

Note also that creating methods which are used as static methods without the ``++@staticmethod++`` decorator is a bad practice. Calling these methods on an instance will raise a ``++TypeError++``. Either move the method out of the class or decorate it with ``++@staticmethod++``.


=== Exceptions

This rule will accept "cls" or "mcs" as first parameter's name for class and metaclasses methods.

No issue will be raised for the following methods: ``++__init_subclass__++``, ``++__class_getitem__++`` and ``++__new__++``, as these methods' first parameter is a class.

This rule may be parameterized to prevent raising issues on methods decorated with specific decorators. These decorators can be added to this rule's `ignoredDecorators` parameter.

For example, with `ignoredDecorators` set to "myDecorator".

[source,python]
----
class MyClass(ABC):
    @myDecorator
    def method(arg):  # No issue will be raised.
        pass
----


== How to fix it

Make sure to have a "self" parameter on instance methods and annotate static methods with the `@staticmethod` decorator.

=== Code examples

==== Noncompliant code example

[source,python,diff-id=1,diff-type=noncompliant]
----
class MyClass:
    def send_request(request):  # Noncompliant: the "self" parameter is missing.
        print("send_request")

class ClassWithStaticMethod:
    def static_method(param):  # Noncompliant: the "@staticmethod" decorator is missing.
        print(param)

ClassWithStaticMethod().static_method(42)  # The method is available on the instance but calling it will raise a TypeError.
----


==== Compliant solution

[source,python,diff-id=1,diff-type=compliant]
----
class MyClass:
    def send_request(self, request):
        print("send_request")

class ClassWithStaticMethod:
    @staticmethod
    def static_method(param):
        print(param)

ClassWithStaticMethod().static_method(42)
----


== Resources

=== Documentation

* Python Documentation - https://docs.python.org/3.8/tutorial/classes.html#method-objects[Method Objects]

=== Standards

* PEP8 - https://www.python.org/dev/peps/pep-0008/#function-and-method-arguments[Function and Method Arguments]

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Rename XXX to "self" or add the missing "self" parameter.


=== Parameters

.ignoredDecorators
****

----
abstractmethod
----

Comma-separated list of decorators which will disable this rule.
****


=== Highlighting

Instance method's first parameter


'''
== Comments And Links
(visible only on this page)

=== on 10 Mar 2020, 17:51:21 Nicolas Harraudeau wrote:
Exceptions to this rule which are not worth mentioning in the RSPEC:

* No issue will be raised on zope.Interface methods
* No issue will be raised on methods in classes nested in other methods. It is common to name "self" otherwise to avoid the confusion

----
class A:
    def meth(self):
        class B:
            def nested(this): # Ok
                pass
----

endif::env-github,rspecator-view[]