docsig 0.81.2__tar.gz → 0.81.3__tar.gz

{docsig-0.81.2 → docsig-0.81.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.81.2
+Version: 0.81.3
 Summary: Check signature params for proper documentation
 License: MIT
 License-File: LICENSE
@@ -184,7 +184,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.81.2, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.81.3, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
 
 And now use `flake8` to lint your files
 
@@ -270,7 +270,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.81.2
+        rev: v0.81.3
         hooks:
           - id: docsig
             args:
@@ -289,7 +289,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.81.2
+              - docsig==0.81.3
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.81.2 → docsig-0.81.3}/README.rst

@@ -155,7 +155,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.81.2, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.81.3, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
 
 And now use `flake8` to lint your files
 
@@ -241,7 +241,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.81.2
+        rev: v0.81.3
         hooks:
           - id: docsig
             args:
@@ -260,7 +260,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.81.2
+              - docsig==0.81.3
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

docsig-0.81.3/docsig/_check.py

@@ -0,0 +1,82 @@
+"""
+docsig._check
+=============
+"""
+
+from __future__ import annotations as _
+
+from ._config import Config as _Config
+from ._module import Function as _Function
+from ._module import Parent as _Parent
+from ._report import Failure as _Failure
+from ._report import Failures as _Failures
+
+
+def _should_check_function(
+    child: _Function,
+    parent: _Parent,
+    config: _Config,
+) -> bool:
+    if child.isoverridden and not config.check.overridden:
+        return False
+
+    if child.isprotected and not config.check.protected:
+        return False
+
+    if child.isdunder and not config.check.dunders:
+        return False
+
+    if child.docstring.bare and config.ignore.no_params:
+        return False
+
+    if child.isinit and (
+        not (config.check.class_ or config.check.class_constructor)
+        or (parent.isprotected and not config.check.protected)
+    ):
+        return False
+
+    return True
+
+
+def _run_check(
+    child: _Parent,
+    parent: _Parent,
+    config: _Config,
+    failures: _Failures,
+) -> None:
+    if isinstance(child, _Function) and _should_check_function(
+        child,
+        parent,
+        config,
+    ):
+        failure = _Failure(child, config.target, config.check.property_returns)
+        if failure:
+            failures.append(failure)
+
+    # recurse for either class methods or, if enabled, nested functions
+    if not isinstance(child, _Function) or config.check.nested:
+        for func in child.children:
+            _run_check(func, child, config, failures)
+
+
+def run_checks(module: _Parent, config: _Config) -> _Failures:
+    """Run checks on the module and return a list of failures.
+
+    Traverse the module's functions and classes. A callable is checked
+    only if it is public or if configuration allows protected or
+    overridden members. Failures are collected and returned.
+
+    :param module: A module object that contains functions or classes.
+    :param config: Configuration object.
+    :return: A list of function and class failures.
+    """
+    failures = _Failures()
+    for top_level in module.children:
+        if (
+            not top_level.isprotected
+            or config.check.protected
+            or config.check.protected_class_methods
+        ):
+            _run_check(top_level, module, config, failures)
+
+    return failures

{docsig-0.81.2 → docsig-0.81.3}/docsig/_config.py

@@ -18,7 +18,7 @@ from pathlib import Path as _Path
 import tomli as _tomli
 
 from ._version import __version__
-from .messages import Messages
+from .messages import Messages as _Messages
 
 PYPROJECT_TOML = "pyproject.toml"
 
@@ -361,8 +361,8 @@ class Config:
 
     check: Check = _field(default_factory=Check)
     ignore: Ignore = _field(default_factory=Ignore)
-    target: Messages = _field(default_factory=Messages)
-    disable: Messages = _field(default_factory=Messages)
+    target: _Messages = _field(default_factory=_Messages)
+    disable: _Messages = _field(default_factory=_Messages)
     exclude: list[str] = _field(default_factory=list)
     excludes: list[str] | None = None
     list_checks: bool = False

{docsig-0.81.2 → docsig-0.81.3}/docsig/_core.py

@@ -18,6 +18,7 @@ from warnings import warn as _warn
 import astroid as _ast
 
 from . import _decorators
+from ._check import run_checks as _run_checks
 from ._config import Check as _Check
 from ._config import Config as _Config
 from ._config import Ignore as _Ignore
@@ -25,9 +26,7 @@ from ._directives import Directives as _Directives
 from ._files import FILE_INFO as _FILE_INFO
 from ._files import Paths as _Paths
 from ._module import Error as _Error
-from ._module import Function as _Function
 from ._module import Parent as _Parent
-from ._report import Failure as _Failure
 from ._report import Failures as _Failures
 from ._utils import print_checks as _print_checks
 from .messages import NEW as _NEW
@@ -70,57 +69,10 @@ def setup_logger(verbose: bool) -> None:
         logger.addHandler(stream_handler)
 
 
-def _should_check_function(
-    child: _Function,
-    parent: _Parent,
-    config: _Config,
-) -> bool:
-    if child.isoverridden and not config.check.overridden:
-        return False
-
-    if child.isprotected and not config.check.protected:
-        return False
-
-    if child.isdunder and not config.check.dunders:
-        return False
-
-    if child.docstring.bare and config.ignore.no_params:
-        return False
-
-    if child.isinit and (
-        not (config.check.class_ or config.check.class_constructor)
-        or (parent.isprotected and not config.check.protected)
-    ):
-        return False
-
-    return True
-
-
-def _run_check(
-    child: _Parent,
-    parent: _Parent,
-    config: _Config,
-    failures: _Failures,
-) -> None:
-    if isinstance(child, _Function) and _should_check_function(
-        child,
-        parent,
-        config,
-    ):
-        failure = _Failure(child, config.target, config.check.property_returns)
-        if failure:
-            failures.append(failure)
-
-    # recurse for either class methods or, if enabled, nested functions
-    if not isinstance(child, _Function) or config.check.nested:
-        for func in child.children:
-            _run_check(func, child, config, failures)
-
-
-def _from_file(path: _Path, config: _Config) -> _Parent:
+def _parse_from_file(path: _Path, config: _Config) -> _Parent:
     try:
         code = path.read_text(encoding="utf-8")
-        parent = _from_str(
+        parent = _parse_from_string(
             code,
             config,
             str(path)[:-3].replace(_os.sep, ".").replace("-", "_"),
@@ -137,7 +89,7 @@ def _from_file(path: _Path, config: _Config) -> _Parent:
     return parent
 
 
-def _from_str(
+def _parse_from_string(
     code: str,
     config: _Config,
     module_name: str = "",
@@ -169,23 +121,13 @@ def _from_str(
     except _ast.AstroidSyntaxError as err:
         logger.debug(_FILE_INFO, source_name, str(err).replace("\n", " "))
         parent = _Parent(error=_Error.SYNTAX)
+    except RecursionError as err:
+        logger.debug(_FILE_INFO, source_name, str(err).replace("\n", " "))
+        parent = _Parent(error=_Error.RECURSION)
 
     return parent
 
 
-def _get_failures(module: _Parent, config: _Config) -> _Failures:
-    failures = _Failures()
-    for top_level in module.children:
-        if (
-            not top_level.isprotected
-            or config.check.protected
-            or config.check.protected_class_methods
-        ):
-            _run_check(top_level, module, config, failures)
-
-    return failures
-
-
 def _report(
     failures: _Failures,
     config: _Config,
@@ -252,8 +194,8 @@ def runner(path: _Path, config: _Config) -> _Failures:
     :param config: Configuration object.
     :return: Collected failures for the file.
     """
-    module = _from_file(path, config)
-    return _get_failures(module, config)
+    module = _parse_from_file(path, config)
+    return _run_checks(module, config)
 
 
 @_decorators.parse_msgs
@@ -367,20 +309,20 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     if config.list_checks:
         return int(bool(_print_checks()))  # type: ignore
 
-    if string is None:
-        retcodes = [0]
-        paths = _Paths(
-            *path,
-            patterns=config.exclude,
-            excludes=config.excludes,
-            include_ignored=config.include_ignored,
-        )
-        for path_ in paths:
-            failures = runner(path_, config)
-            retcodes.append(_report(failures, config, str(path_)))
+    if string:
+        module = _parse_from_string(string, config)
+        failures = _run_checks(module, config)
+        return _report(failures, config)
 
-        return max(retcodes)
+    retcodes = [0]
+    paths = _Paths(
+        *path,
+        patterns=config.exclude,
+        excludes=config.excludes,
+        include_ignored=config.include_ignored,
+    )
+    for path_ in paths:
+        failures = runner(path_, config)
+        retcodes.append(_report(failures, config, str(path_)))
 
-    module = _from_str(string, config)
-    failures = _get_failures(module, config)
-    return _report(failures, config)
+    return max(retcodes)

{docsig-0.81.2 → docsig-0.81.3}/docsig/_directives.py

@@ -15,6 +15,10 @@ from .messages import E as _E
 from .messages import Messages as _Messages
 
 
+class Comments(_t.List["Comment"]):
+    """List of comments."""
+
+
 class Comment(_Messages):
     """A single comment directive.
 
@@ -73,10 +77,6 @@ class Comment(_Messages):
         return None
 
 
-class Comments(_t.List[Comment]):
-    """List of comments."""
-
-
 class Directives(_t.Dict[int, _t.Tuple[Comments, _Messages]]):
     """Map line number to comments and disabled messages for that line.
 

{docsig-0.81.2 → docsig-0.81.3}/docsig/_module.py

@@ -22,15 +22,24 @@ from ._stub import Signature as _Signature
 from .messages import Messages as _Messages
 
 
+class _Imports(_t.Dict[str, str]):
+    """Represents python imports."""
+
+
+class _Overloads(_t.Dict[str, "Function"]):
+    """Represents overloaded methods."""
+
+
+class _Children(_t.List[_t.Union["Parent", "Function"]]):
+    """Represents children of an object."""
+
+
 class Error(_Enum):
     """Represents an unrecoverable error."""
 
     SYNTAX = 1
     UNICODE = 2
-
-
-class _Imports(_t.Dict[str, str]):
-    """Represents python imports."""
+    RECURSION = 3
 
 
 class Parent:  # pylint: disable=too-many-instance-attributes
@@ -67,8 +76,8 @@ class Parent:  # pylint: disable=too-many-instance-attributes
         error: Error | None = None,
     ) -> None:
         super().__init__()
-        self._name = "module"
         self._error = error
+        self._directives = directives or _Directives()
         self._ignore_args = ignore_args
         self._ignore_kwargs = ignore_kwargs
         self._check_class_constructor = check_class_constructor
@@ -76,11 +85,12 @@ class Parent:  # pylint: disable=too-many-instance-attributes
         self._imports = imports or _Imports()
         self._overloads = _Overloads()
         if node is None:
+            self._name = "module"
             if not isinstance(self, Function) and error is not None:
                 self._children.append(Function(path, error=error))
         else:
             self._name = node.name
-            self._parse_ast(node, directives or _Directives(), path)
+            self._parse_ast(node, path)
 
     def _parse_ast(
         self,
@@ -90,19 +100,18 @@ class Parent:  # pylint: disable=too-many-instance-attributes
             | _ast.nodes.FunctionDef
             | _ast.nodes.NodeNG
         ),
-        directives: _Directives,
         path: _Path | None = None,
     ) -> None:
         # need to keep track of `comments` as, even though they are
         # resolved in the directive object, they are needed to notify
         # the user in the case that they are invalid
-        parent_comments, parent_disabled = directives.get(
+        parent_comments, parent_disabled = self._directives.get(
             node.lineno,
             (_Comments(), _Messages()),
         )
         if hasattr(node, "body"):
             for subnode in node.body:
-                comments, disabled = directives.get(
+                comments, disabled = self._directives.get(
                     subnode.lineno,
                     (_Comments(), _Messages()),
                 )
@@ -119,7 +128,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                     func = Function(
                         subnode,
                         comments,
-                        directives,
+                        self._directives,
                         disabled,
                         path,
                         self._ignore_args,
@@ -145,7 +154,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                     self._children.append(
                         Parent(
                             subnode,
-                            directives,
+                            self._directives,
                             path,
                             self._ignore_args,
                             self._ignore_kwargs,
@@ -154,7 +163,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                         ),
                     )
                 else:
-                    self._parse_ast(subnode, directives, path)
+                    self._parse_ast(subnode, path)
 
     @property
     def isprotected(self) -> bool:
@@ -364,11 +373,3 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
         :param rettype: Return type of the overloaded variant.
         """
         self._signature.overload(rettype)
-
-
-class _Overloads(_t.Dict[str, Function]):
-    """Represents overloaded methods."""
-
-
-class _Children(_t.List[_t.Union[Parent, Function]]):
-    """Represents children of an object."""

{docsig-0.81.2 → docsig-0.81.3}/docsig/_report.py

@@ -10,7 +10,7 @@ return the highest exit code.
 
 from __future__ import annotations as _
 
-import contextlib
+import contextlib as _contextlib
 import typing as _t
 
 from astroid.nodes.scoped_nodes import scoped_nodes as _scoped_nodes
@@ -32,6 +32,10 @@ _MIN_MATCH = 0.8
 _MAX_MATCH = 1.0
 
 
+class Failures(_t.List["Failure"]):
+    """Sequence of Failure instances (one per function checked)."""
+
+
 class Failed(_t.NamedTuple):
     """Single reported issue."""
 
@@ -139,7 +143,7 @@ class Failure(_t.List[Failed]):
             # then we know that they aren't almost equal, param1 is
             # missing and does need to be inserted in the docstring
             if is_equal:
-                with contextlib.suppress(IndexError):
+                with _contextlib.suppress(IndexError):
                     is_equal = to[count].name != from_[count + 1].name
 
             if not is_equal:
@@ -316,6 +320,8 @@ class Failure(_t.List[Failed]):
             self._retcode = 123
         if self._func.error == _Error.UNICODE:
             self._add(_E[902])
+        if self._func.error == _Error.RECURSION:
+            self._add(_E[903])
 
     @property
     def name(self) -> str:
@@ -331,7 +337,3 @@ class Failure(_t.List[Failed]):
     def retcode(self) -> int:
         """Exit code (non-zero if any check failed)."""
         return self._retcode
-
-
-class Failures(_t.List[Failure]):
-    """Sequence of Failure instances (one per function checked)."""

{docsig-0.81.2 → docsig-0.81.3}/docsig/_stub.py

@@ -100,11 +100,11 @@ class Param:
         indent: int = 0,
         closing_token: str = ":",
     ) -> None:
-        self.kind = kind
-        self.name = name
-        self.description = description
-        self.indent = indent
-        self.closing_token = closing_token
+        self._kind = kind
+        self._name = name
+        self._description = description
+        self._indent = indent
+        self._closing_token = closing_token
 
     def __eq__(self, other: object) -> bool:
         iseq = False
@@ -125,6 +125,31 @@ class Param:
         """True if the parameter name starts with an underscore."""
         return str(self.name).startswith("_")
 
+    @property
+    def kind(self) -> DocType:
+        """Type of the param."""
+        return self._kind
+
+    @property
+    def name(self) -> str | None:
+        """Name of the param."""
+        return self._name
+
+    @property
+    def description(self) -> str | None:
+        """Description of param."""
+        return self._description
+
+    @property
+    def indent(self) -> int:
+        """Number of spaces in the indent."""
+        return self._indent
+
+    @property
+    def closing_token(self) -> str:
+        """Token used to terminate the param name definition."""
+        return self._closing_token
+
 
 class Params(_t.List[Param]):
     """A list-like collection of params.

{docsig-0.81.2 → docsig-0.81.3}/docsig/_version.py

@@ -8,4 +8,4 @@ Allows for access to the version internally without cyclic imports
 caused by accessing it through __init__.
 """
 
-__version__ = "0.81.2"
+__version__ = "0.81.3"

{docsig-0.81.2 → docsig-0.81.3}/docsig/messages.py

@@ -6,7 +6,7 @@ Error message definitions (Message, MessageMap, E) and format templates
 for docstring-check output.
 """
 
-from __future__ import annotations
+from __future__ import annotations as _
 
 import typing as _t
 
@@ -24,6 +24,10 @@ NEW = """\
 """
 
 
+class Messages(_t.List["Message"]):
+    """Sequence of Message instances, typically for one failure."""
+
+
 class Message(_t.NamedTuple):
     """One docstring-check error (ref, description, symbolic, hint)."""
 
@@ -63,10 +67,6 @@ class Message(_t.NamedTuple):
         )
 
 
-class Messages(_t.List[Message]):
-    """Sequence of Message instances, typically for one failure."""
-
-
 class MessageMap(_t.Dict[int, Message]):
     """Mapping from integer key to Message (used for the E registry)."""
 
@@ -252,5 +252,10 @@ E = MessageMap(
             "failed to read file",
             "unicode-decode-error",
         ),
+        903: Message(
+            "SIG903",
+            "maximum recursion depth exceeded",
+            "recursion-error",
+        ),
     },
 )

{docsig-0.81.2 → docsig-0.81.3}/pyproject.toml

@@ -11,7 +11,7 @@ line-length = 79
 allow_dirty = true
 commit = true
 commit_args = "-sS"
-current_version = "0.81.2"
+current_version = "0.81.3"
 message = "bump: version {current_version} → {new_version}"
 sign_tags = true
 tag = true
@@ -122,7 +122,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.81.2"
+version = "0.81.3"
 
 [tool.poetry.dependencies]
 Sphinx = ">=7,<9"