docsig 0.82.1__tar.gz → 0.82.2__tar.gz

{docsig-0.82.1 → docsig-0.82.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.82.1
+Version: 0.82.2
 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.82.1, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.82.2, 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.82.1
+        rev: v0.82.2
         hooks:
           - id: docsig
             args:
@@ -289,7 +289,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.82.1
+              - docsig==0.82.2
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.82.1 → docsig-0.82.2}/README.rst

@@ -155,7 +155,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.82.1, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.82.2, 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.82.1
+        rev: v0.82.2
         hooks:
           - id: docsig
             args:
@@ -260,7 +260,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.82.1
+              - docsig==0.82.2
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.82.1 → docsig-0.82.2}/docsig/_module.py

@@ -9,7 +9,6 @@ from __future__ import annotations as _
 
 import re as _re
 import typing as _t
-from enum import Enum as _Enum
 from pathlib import Path as _Path
 
 import astroid as _ast
@@ -32,12 +31,12 @@ class _Overloads(dict[str, "Function"]): ...
 class _Children(list[_t.Union["Parent", "Function"]]): ...
 
 
-class Error(_Enum):
-    """Represents an unrecoverable error."""
-
-    SYNTAX = 1
-    UNICODE = 2
-    RECURSION = 3
+ERRORS = (
+    _ast.AstroidSyntaxError,
+    UnicodeDecodeError,
+    RecursionError,
+    _ast.DuplicateBasesError,
+)
 
 
 class Parent:  # pylint: disable=too-many-instance-attributes
@@ -65,7 +64,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
         file: _Path | None = None,
         config: _Config | None = None,
         imports: _Imports | None = None,
-        error: Error | None = None,
+        error: type[BaseException] | None = None,
     ) -> None:
         super().__init__()
         self._error = error
@@ -127,14 +126,18 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                     if func.isoverloaded:
                         if (
                             func.name not in self._overloads
-                            or self._overloads[func.name].signature.rettype
+                            or self._overloads[
+                                func.name
+                            ].signature.returns.type
                             == _RetType.NONE
                         ):
                             self._overloads[func.name] = func
                     else:
                         if func.name in self._overloads:
                             func.overload(
-                                self._overloads[func.name].signature.rettype,
+                                self._overloads[
+                                    func.name
+                                ].signature.returns.type,
                             )
 
                         self._children.append(func)
@@ -157,7 +160,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
         return self._name.startswith("_")
 
     @property
-    def error(self) -> Error | None:
+    def error(self) -> type[BaseException] | None:
         """Unrecoverable error for this scope, if any."""
         return self._error
 
@@ -190,7 +193,7 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
         file: _Path | None = None,
         config: _Config | None = None,
         imports: _Imports | None = None,
-        error: Error | None = None,
+        error: type[BaseException] | None = None,
     ) -> None:
         super().__init__(
             node,

{docsig-0.82.1 → docsig-0.82.2}/docsig/_parsers.py

@@ -15,7 +15,7 @@ import astroid as _ast
 from ._config import Config as _Config
 from ._directives import Directives as _Directives
 from ._files import FILE_INFO as _FILE_INFO
-from ._module import Error as _Error
+from ._module import ERRORS as _ERRORS
 from ._module import Parent as _Parent
 
 
@@ -53,12 +53,9 @@ def parse_from_string(
 
         parent = _Parent(node, directives, file, config)
         logger.debug(_FILE_INFO, source_name, "Parsing Python code successful")
-    except _ast.AstroidSyntaxError as err:
+    except _ERRORS 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)
+        parent = _Parent(error=type(err))
 
     return parent
 
@@ -81,7 +78,7 @@ def parse_from_file(file: _Path, config: _Config) -> _Parent:
     except UnicodeDecodeError as err:
         logger = _logging.getLogger(__package__)
         logger.debug(_FILE_INFO, file, str(err).replace("\n", " "))
-        parent = _Parent(error=_Error.UNICODE)
+        parent = _Parent(error=type(err))
 
     if parent.error is not None and not file.name.endswith(".py"):
         parent = _Parent()

{docsig-0.82.1 → docsig-0.82.2}/docsig/_report.py

@@ -15,10 +15,10 @@ import sys as _sys
 import typing as _t
 from warnings import warn as _warn
 
+import astroid as _ast
 from astroid.nodes.scoped_nodes import scoped_nodes as _scoped_nodes
 
 from ._config import Config as _Config
-from ._module import Error as _Error
 from ._module import Function as _Function
 from ._stub import UNNAMED as _UNNAMED
 from ._stub import VALID_DESCRIPTION as _VALID_DESCRIPTION
@@ -288,18 +288,18 @@ class Failure(list[Failed]):
             self._func.isproperty and not check_property_returns
         ):
             # no types, cannot know either way
-            if self._func.signature.rettype == _RetType.UNTYPED:
+            if self._func.signature.returns.type == _RetType.UNTYPED:
                 # confirm-return-needed
                 self._add(_E[501], hint=True)
             # return-type is none, so no return should be documented
-            elif self._func.docstring.returns:
-                if self._func.signature.rettype == _RetType.NONE:
+            elif self._func.docstring.returns.returns:
+                if self._func.signature.returns.type == _RetType.NONE:
                     # return-documented-for-none
                     self._add(_E[502])
-                if self._func.docstring.ret_description_missing:
+                if self._func.docstring.returns.description_missing:
                     self._add(_E[506])
             # return-type is some, so return should be documented
-            elif self._func.signature.returns:
+            elif self._func.signature.returns.returns:
                 # return-missing
                 lines = str(self._func.docstring.string).splitlines()
                 self._add(
@@ -310,7 +310,7 @@ class Failure(list[Failed]):
                         and ":param" not in lines[-1]
                     ),
                 )
-        elif self._func.docstring.returns:
+        elif self._func.docstring.returns.returns:
             # this method is init, so no return should be documented
             if self._func.isinit:
                 # class-return-documented
@@ -322,13 +322,15 @@ class Failure(list[Failed]):
 
     def _sig9xx_error(self) -> None:
         # invalid-syntax
-        if self._func.error == _Error.SYNTAX:
+        if self._func.error is _ast.AstroidSyntaxError:
             self._add(_E[901])
             self._retcode = 123
-        if self._func.error == _Error.UNICODE:
+        if self._func.error is UnicodeDecodeError:
             self._add(_E[902])
-        if self._func.error == _Error.RECURSION:
+        if self._func.error is RecursionError:
             self._add(_E[903])
+        if self._func.error is _ast.DuplicateBasesError:
+            self._add(_E[904])
 
     @property
     def name(self) -> str:

{docsig-0.82.1 → docsig-0.82.2}/docsig/_stub.py

@@ -9,6 +9,7 @@ from __future__ import annotations as _
 
 import re as _re
 import textwrap as _textwrap
+import typing as _t
 from collections import Counter as _Counter
 from enum import Enum as _Enum
 
@@ -80,8 +81,6 @@ class DocType(_Enum):
         return cls.UNKNOWN
 
 
-# todo: consider a parent object that can be used for returns that do
-# todo: not include the name attribute
 class Param:
     """Single parameter from a docstring or function signature.
 
@@ -152,6 +151,13 @@ class Param:
         return self._closing_token
 
 
+# single return from a docstring or function signature
+class _Return(_t.NamedTuple):
+    returns: bool = False
+    type: RetType = RetType.UNTYPED
+    description_missing: bool = False
+
+
 class Params(list[Param]):
     """A list-like collection of params.
 
@@ -218,9 +224,13 @@ class Params(list[Param]):
 
 
 class _Stub:
-    def __init__(self, ignore: _Ignore | None = None) -> None:
+    def __init__(
+        self,
+        returns: _Return | None = None,
+        ignore: _Ignore | None = None,
+    ) -> None:
         self._args = Params(ignore or _Ignore())
-        self._returns = False
+        self._returns = returns or _Return()
 
     @property
     def args(self) -> Params:
@@ -228,7 +238,7 @@ class _Stub:
         return self._args
 
     @property
-    def returns(self) -> bool:
+    def returns(self) -> _Return:
         """True if a return (or yield) is declared or documented."""
         return self._returns
 
@@ -236,20 +246,16 @@ class _Stub:
 class Signature(_Stub):
     """Parsed function signature (args and return type).
 
-    :param rettype: Kind of return (none, some, untyped).
     :param returns: True if return is declared in the signature.
     :param ignore: Configuration object for what to ignore.
     """
 
     def __init__(
         self,
-        rettype: RetType = RetType.NONE,
-        returns: bool = False,
+        returns: _Return | None = None,
         ignore: _Ignore | None = None,
     ) -> None:
-        super().__init__(ignore or _Ignore())
-        self._rettype = rettype
-        self._returns = returns
+        super().__init__(returns, ignore or _Ignore())
 
     @classmethod
     def from_ast(
@@ -264,8 +270,8 @@ class Signature(_Stub):
         :return: Signature with args and return type.
         """
         rettype = RetType.from_ast(node.returns)
-        returns = rettype == RetType.SOME
-        signature = cls(rettype, returns, ignore)
+        returns = _Return(rettype == RetType.SOME, rettype)
+        signature = cls(returns, ignore)
         # noinspection PyUnresolvedReferences
         for i in [
             a if isinstance(a, Param) else Param(name=a.name)
@@ -282,18 +288,12 @@ class Signature(_Stub):
 
         return signature
 
-    @property
-    def rettype(self) -> RetType:
-        """Return annotation kind (none, some, or untyped)."""
-        return self._rettype
-
     def overload(self, rettype: RetType) -> None:
         """Set this signature's return type (for overloads).
 
         :param rettype: Return type for the overloaded variant.
         """
-        self._rettype = rettype
-        self._returns = rettype != RetType.NONE
+        self._returns = _Return(rettype != RetType.NONE, rettype)
 
 
 class Docstring(_Stub):
@@ -301,7 +301,6 @@ class Docstring(_Stub):
 
     :param string: Raw docstring text after normalization.
     :param returns: True if a return or yield section is present.
-    :param ret_description_missing: True if return has no description.
     """
 
     @staticmethod
@@ -345,13 +344,10 @@ class Docstring(_Stub):
     def __init__(
         self,
         string: str | None = None,
-        returns: bool = False,
-        ret_description_missing: bool = False,
+        returns: _Return | None = None,
     ) -> None:
-        super().__init__()
+        super().__init__(returns)
         self._string = string
-        self._returns = returns
-        self._ret_description_missing = ret_description_missing
 
     @classmethod
     def from_ast(cls, node: _ast.Const) -> Docstring:
@@ -362,16 +358,16 @@ class Docstring(_Stub):
         """
         indent_anomaly = cls._indent_anomaly(node.value)
         string = cls._normalize_docstring(node.value)
-        # todo: we can start building return objects for more detailed
-        # todo: checks that are in common with the params class
         match = _re.search(
             r":(?:returns?|yields?):\s*(.*)",
             string,
             _re.IGNORECASE,
         )
-        returns = bool(match)
-        ret_description_missing = not match or not match.group(1)
-        docstring = cls(string, returns, ret_description_missing)
+        returns = _Return(
+            bool(match),
+            description_missing=not match or not match.group(1),
+        )
+        docstring = cls(string, returns)
         for match in _re.findall(
             r":([\w\s]+(?:\s\|\s[\w\s]+|\w+))([^\w\s])((?:.|\n)*?)(?=\n:|$)",
             string,
@@ -402,9 +398,8 @@ class Docstring(_Stub):
 
         Used when the function has a docstring but documents nothing.
         """
-        return self._string is not None and not self._args and not self.returns
-
-    @property
-    def ret_description_missing(self) -> bool:
-        """True if a return section exists but has no description."""
-        return self._ret_description_missing
+        return (
+            self._string is not None
+            and not self._args
+            and not self.returns.returns
+        )

{docsig-0.82.1 → docsig-0.82.2}/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.82.1"
+__version__ = "0.82.2"

{docsig-0.82.1 → docsig-0.82.2}/docsig/messages.py

@@ -267,5 +267,10 @@ E = MessageMap(
             "maximum recursion depth exceeded",
             "recursion-error",
         ),
+        904: Message(
+            "SIG904",
+            "duplicates found in mros",
+            "duplicates-found-in-mros",
+        ),
     },
 )

{docsig-0.82.1 → docsig-0.82.2}/pyproject.toml

@@ -11,7 +11,7 @@ line-length = 79
 allow_dirty = true
 commit = true
 commit_args = "-sS"
-current_version = "0.82.1"
+current_version = "0.82.2"
 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.82.1"
+version = "0.82.2"
 
 [tool.poetry.dependencies]
 Sphinx = ">=7,<9"
@@ -239,7 +239,7 @@ name = "Security"
 
 [tool.vulture]
 exclude = [
-  "tests/_templates.py",
+  "tests/base_test.py",
   "tests/conftest.py"
 ]
 make_whitelist = true