Fix flake8 doc styles (#1218)

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+### 41.5.3 [#1218](https://github.com/openfisca/openfisca-core/pull/1218)
+
+#### Technical changes
+
+- Fix `flake8` doc linting:
+    - Add format "google"
+    - Fix per-file skips
+- Fix failing lints
+
 ### 41.5.2 [#1217](https://github.com/openfisca/openfisca-core/pull/1217)
 
 #### Technical changes

openfisca_core/entities/__init__.py

@@ -21,10 +21,10 @@
 #
 # See: https://www.python.org/dev/peps/pep-0008/#imports
 
-from . import typing
+from . import types
 from .entity import Entity
 from .group_entity import GroupEntity
 from .helpers import build_entity, find_role
 from .role import Role
 
-__all__ = ["Entity", "GroupEntity", "Role", "build_entity", "find_role", "typing"]
+__all__ = ["Entity", "GroupEntity", "Role", "build_entity", "find_role", "types"]

openfisca_core/entities/_core_entity.py

@@ -8,7 +8,7 @@
 from abc import abstractmethod
 
 from .role import Role
-from .typing import Entity
+from .types import Entity
 
 
 class _CoreEntity:
@@ -36,17 +36,23 @@ class _CoreEntity:
     def __init__(self, key: str, plural: str, label: str, doc: str, *args: Any) -> None:
         ...
 
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.key})"
+
     def set_tax_benefit_system(self, tax_benefit_system: TaxBenefitSystem) -> None:
+        """An Entity belongs to a TaxBenefitSystem."""
         self._tax_benefit_system = tax_benefit_system
 
     def get_variable(
         self,
         variable_name: str,
         check_existence: bool = False,
     ) -> Variable | None:
+        """Get a ``variable_name`` from ``variables``."""
         return self._tax_benefit_system.get_variable(variable_name, check_existence)
 
     def check_variable_defined_for_entity(self, variable_name: str) -> None:
+        """Check if ``variable_name`` is defined for ``self``."""
         variable: Variable | None
         entity: Entity
 
@@ -66,5 +72,6 @@ def check_variable_defined_for_entity(self, variable_name: str) -> None:
             raise ValueError(os.linesep.join(message))
 
     def check_role_validity(self, role: Any) -> None:
+        """Check if a ``role`` is an instance of Role."""
         if role is not None and not isinstance(role, Role):
             raise ValueError(f"{role} is not a valid role")

openfisca_core/entities/helpers.py

@@ -4,7 +4,7 @@
 
 from .entity import Entity
 from .group_entity import GroupEntity
-from .typing import Role
+from .types import Role
 
 
 def build_entity(
@@ -17,8 +17,62 @@ def build_entity(
     class_override=None,
     containing_entities=(),
 ):
+    """Build a SingleEntity or a GroupEntity.
+
+    Args:
+        key: Key to identify the :class:`.Entity`. or :class:`.GroupEntity`.
+        plural: ``key``, pluralised.
+        label: A summary description.
+        doc: A full description.
+        roles: A list of :class:`.Role`, if it's a :class:`.GroupEntity`.
+        is_person: If is an individual, or not.
+        class_override: ?
+        containing_entities: Keys of contained entities.
+
+    Returns:
+        :obj:`.Entity` or :obj:`.GroupEntity`:
+        :obj:`.Entity`: When ``is_person`` is True.
+        :obj:`.GroupEntity`: When ``is_person`` is False.
+
+    Raises:
+        ValueError if ``roles`` is not a sequence.
+
+    Examples:
+        >>> from openfisca_core import entities
+
+        >>> build_entity(
+        ...     "syndicate",
+        ...     "syndicates",
+        ...     "Banks loaning jointly.",
+        ...     roles = [],
+        ...     containing_entities = (),
+        ...     )
+        GroupEntity(syndicate)
+
+        >>> build_entity(
+        ...     "company",
+        ...     "companies",
+        ...     "A small or medium company.",
+        ...     is_person = True,
+        ...     )
+        Entity(company)
+
+        >>> role = entities.Role({"key": "key"}, object())
+
+        >>> build_entity(
+        ...     "syndicate",
+        ...     "syndicates",
+        ...     "Banks loaning jointly.",
+        ...     roles = role,
+        ...     )
+        Traceback (most recent call last):
+        TypeError: 'Role' object is not iterable
+
+    """
+
     if is_person:
         return Entity(key, plural, label, doc)
+
     else:
         return GroupEntity(
             key, plural, label, doc, roles, containing_entities=containing_entities
@@ -31,15 +85,15 @@ def find_role(
     """Find a Role in a GroupEntity.
 
     Args:
-        group_entity (GroupEntity): The entity to search in.
+        roles (Iterable[Role]): The roles to search.
         key (str): The key of the role to find. Defaults to `None`.
         total (int | None): The `max` attribute of the role to find.
 
     Returns:
         Role | None: The role if found, else `None`.
 
     Examples:
-        >>> from openfisca_core.entities.typing import RoleParams
+        >>> from openfisca_core.entities.types import RoleParams
 
         >>> principal = RoleParams(
         ...     key="principal",

openfisca_core/entities/role.py

@@ -6,7 +6,7 @@
 import dataclasses
 import textwrap
 
-from .typing import Entity
+from .types import Entity
 
 
 class Role:

openfisca_core/projectors/helpers.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from openfisca_core.entities.typing import Entity, GroupEntity, Role
+
+from openfisca_core.entities.types import Entity, GroupEntity, Role
 
 from openfisca_core import entities, projectors
 

openfisca_core/projectors/typing.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
-from openfisca_core.entities.typing import Entity, GroupEntity
 from typing import Protocol
 
+from openfisca_core.entities.types import Entity, GroupEntity
+
 
 class Population(Protocol):
     @property

openfisca_tasks/lint.mk

@@ -19,6 +19,7 @@ check-style: $(shell git ls-files "*.py")
 ## Run linters to check for syntax and style errors in the doc.
 lint-doc: \
 	lint-doc-commons \
+	lint-doc-entities \
 	lint-doc-types \
 	;
 

openfisca_tasks/test_code.mk

@@ -31,7 +31,7 @@ test-code: test-core test-country test-extension
 ## Run openfisca-core tests.
 test-core: $(shell pytest --quiet --quiet --collect-only 2> /dev/null | cut -f 1 -d ":")
 	@$(call print_help,$@:)
-	@pytest --quiet --capture=no --xdoctest --xdoctest-verbose=0 \
+	@pytest --capture=no --xdoctest --xdoctest-verbose=0 \
 		openfisca_core/commons \
 		openfisca_core/entities \
 		openfisca_core/holders \

setup.cfg

@@ -8,19 +8,27 @@
 # W503/504:         We break lines before binary operators (Knuth's style).
 
 [flake8]
+convention          = google
+docstring_style     = google
 extend-ignore       = D
 ignore              = E203, E501, F405, RST301, W503
 in-place            = true
 include-in-doctest  = openfisca_core/commons openfisca_core/entities openfisca_core/holders openfisca_core/periods openfisca_core/projectors openfisca_core/types
 max-line-length     = 88
-per-file-ignores    = */typing.py:D101,D102,E704, */__init__.py:F401
+per-file-ignores    = */types.py:D101,D102,E704, */test_*.py:D101,D102,D103, */__init__.py:F401
 rst-directives      = attribute, deprecated, seealso, versionadded, versionchanged
 rst-roles           = any, attr, class, exc, func, meth, mod, obj
 strictness          = short
 
+[pylint.MASTER]
+load-plugins        = pylint_per_file_ignores
+
 [pylint.message_control]
 disable             = all
-enable              = C0115,C0116,R0401
+enable              = C0115, C0116, R0401
+per-file-ignores    =
+    types.py:C0115,C0116
+    /tests/:C0116
 score               = no
 
 [isort]

setup.py

@@ -40,33 +40,34 @@
 ]
 
 api_requirements = [
-    "Flask >=2.2.3, < 3.0",
-    "Flask-Cors >=3.0.10, < 4.0",
-    "gunicorn >=21.0, < 22.0",
-    "Werkzeug >=2.2.3, < 3.0",
+    "Flask >=2.2.3, <3.0",
+    "Flask-Cors >=3.0.10, <4.0",
+    "gunicorn >=21.0, <22.0",
+    "Werkzeug >=2.2.3, <3.0",
 ]
 
 dev_requirements = [
-    "black >=23.1.0, < 24.0",
-    "coverage >=6.5.0, < 7.0",
-    "darglint >=1.8.1, < 2.0",
-    "flake8 >=6.0.0, < 7.0.0",
-    "flake8-bugbear >=23.3.23, < 24.0",
-    "flake8-docstrings >=1.7.0, < 2.0",
-    "flake8-print >=5.0.0, < 6.0",
-    "flake8-rst-docstrings >=0.3.0, < 0.4.0",
-    "idna >=3.4, < 4.0",
-    "isort >=5.12.0, < 6.0",
-    "mypy >=1.1.1, < 2.0",
-    "openapi-spec-validator >=0.7.1, < 0.8.0",
-    "pycodestyle >=2.10.0, < 3.0",
-    "pylint >=2.17.1, < 3.0",
-    "xdoctest >=1.1.1, < 2.0",
+    "black >=23.1.0, <24.0",
+    "coverage >=6.5.0, <7.0",
+    "darglint >=1.8.1, <2.0",
+    "flake8 >=6.0.0, <7.0.0",
+    "flake8-bugbear >=23.3.23, <24.0",
+    "flake8-docstrings >=1.7.0, <2.0",
+    "flake8-print >=5.0.0, <6.0",
+    "flake8-rst-docstrings >=0.3.0, <0.4.0",
+    "idna >=3.4, <4.0",
+    "isort >=5.12.0, <6.0",
+    "mypy >=1.1.1, <2.0",
+    "openapi-spec-validator >=0.7.1, <0.8.0",
+    "pycodestyle >=2.10.0, <3.0",
+    "pylint >=2.17.1, <3.0",
+    "pylint-per-file-ignores >=1.3.2, <2.0",
+    "xdoctest >=1.1.1, <2.0",
 ] + api_requirements
 
 setup(
     name="OpenFisca-Core",
-    version="41.5.2",
+    version="41.5.3",
     author="OpenFisca Team",
     author_email="[email protected]",
     classifiers=[
@@ -102,12 +103,12 @@
         "web-api": api_requirements,
         "dev": dev_requirements,
         "ci": [
-            "build >=0.10.0, < 0.11.0",
-            "coveralls >=3.3.1, < 4.0",
-            "twine >=5.1.1, < 6.0",
-            "wheel >=0.40.0, < 0.41.0",
+            "build >=0.10.0, <0.11.0",
+            "coveralls >=3.3.1, <4.0",
+            "twine >=5.1.1, <6.0",
+            "wheel >=0.40.0, <0.41.0",
         ],
-        "tracker": ["OpenFisca-Tracker >=0.4.0, < 0.5.0"],
+        "tracker": ["OpenFisca-Tracker >=0.4.0, <0.5.0"],
     },
     include_package_data=True,  # Will read MANIFEST.in
     install_requires=general_requirements,