rspec/rules/S4487/python/rule.adoc

== Why is this an issue?

Private attributes which are written but never read are a clear case of dead store. Changing their value is useless and most probably indicates a serious error in the code.


Python has no real private attribute. Every attribute is accessible. There are however two conventions indicating that an attribute is not meant to be "public":

* attributes with a name starting with a single underscore (ex: ``++_myattribute++``) should be seen as non-public and might change without prior notice. They should not be used by third-party libraries or software. It is ok to use those methods inside the library defining them but it should be done with caution.
* "class-private" attributes have a name which starts with at least two underscores and ends with at most one underscore. These attribute's names will be automatically mangled to avoid collision with subclasses' attributes. For example ``++__myattribute++`` will be renamed as ``++_classname__myattribute++``, where ``++classname++`` is the attribute's class name without its leading underscore(s). They shouldn't be used outside of the class defining the attribute.

This rule raises an issue when a class-private attribute (two leading underscores, max one underscore at the end) is never read inside the class. It optionally raises an issue on unread attributes prefixed with a single underscore. Both class attribute and instance attributes will raise an issue.

=== Noncompliant code example

[source,python]
----
class Noncompliant:
    _class_attr = 0  # Noncompliant if enable_single_underscore_issues is enabled
    __mangled_class_attr = 1  # Noncompliant

    def __init__(self, value):
        self._attr = 0  # Noncompliant if enable_single_underscore_issues is enabled
        self.__mangled_attr = 1  # Noncompliant

    def compute(self, x):
        return x * x
----

=== Compliant solution

[source,python]
----
class Compliant:
    _class_attr = 0
    __mangled_class_attr = 1

    def __init__(self, value):
        self._attr = 0
        self.__mangled_attr = 1

    def compute(self, x):
        return x * Compliant._class_attr * Compliant.__mangled_class_attr * self._attr * self.__mangled_attr
----

== Resources

* https://docs.python.org/3.8/tutorial/classes.html#private-variables[Python documentation – Private Variables]
* https://www.python.org/dev/peps/pep-0008/#designing-for-inheritance[PEP 8 – Style Guide for Python Code]

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

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

=== Message

Remove this unread private attribute 'xxxx' or refactor the code to use its value.


=== Highlighting

* primary: first attribute assignment
* secondary: other statements changing its value
message: 'Also modified here.'


=== Parameters

.enableSingleUnderscoreIssues
****
_Boolean_

----
False
----

Enable issues on unread attributes with a single underscore prefix
****


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

include::../comments-and-links.adoc[]
endif::env-github,rspecator-view[]