docsig 0.82.0__tar.gz → 0.82.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.82.0
+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.0, 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.0
+        rev: v0.82.2
         hooks:
           - id: docsig
             args:
@@ -289,7 +289,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.82.0
+              - docsig==0.82.2
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.82.0 → 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.0, 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.0
+        rev: v0.82.2
         hooks:
           - id: docsig
             args:
@@ -260,7 +260,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.82.0
+              - docsig==0.82.2
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.82.0 → docsig-0.82.2}/docsig/_config.py

@@ -364,7 +364,7 @@ class Config:
     target: _Messages = _field(default_factory=_Messages)
     disable: _Messages = _field(default_factory=_Messages)
     exclude: list[str] = _field(default_factory=list)
-    excludes: list[str] | None = None
+    excludes: list[str] = _field(default_factory=list)
     list_checks: bool = False
     include_ignored: bool = False
     no_ansi: bool = False

{docsig-0.82.0 → docsig-0.82.2}/docsig/_core.py

@@ -199,7 +199,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         target=target or _Messages(),
         disable=disable,
         exclude=exclude_,
-        excludes=excludes,
+        excludes=excludes or [],
     )
     setup_logger(config.verbose)
     if config.list_checks:

{docsig-0.82.0 → docsig-0.82.2}/docsig/_decorators.py

@@ -12,8 +12,8 @@ from pathlib import Path as _Path
 
 from .messages import E as _E
 
-_FuncType = _t.Callable[..., _t.Union[int]]
-_WrappedFuncType = _t.Callable[..., _t.Union[str, int]]
+_FuncType = _t.Callable[..., int]
+_WrappedFuncType = _t.Callable[..., str | int]
 
 
 def parse_msgs(func: _WrappedFuncType) -> _WrappedFuncType:

{docsig-0.82.0 → docsig-0.82.2}/docsig/_directives.py

@@ -8,14 +8,13 @@ Parsing and storage for docsig comment directives.
 from __future__ import annotations as _
 
 import tokenize as _tokenize
-import typing as _t
 from io import StringIO as _StringIO
 
 from .messages import E as _E
 from .messages import Messages as _Messages
 
 
-class Comments(_t.List["Comment"]):
+class Comments(list["Comment"]):
     """List of comments."""
 
 
@@ -96,7 +95,7 @@ class Comment(_Messages):
         return None
 
 
-class Directives(_t.Dict[int, _t.Tuple[Comments, _Messages]]):
+class Directives(dict[int, tuple[Comments, _Messages]]):
     """Map line number to comments and disabled messages for that line.
 
     Keys are line numbers; values are tuples of comment directives and

{docsig-0.82.0 → docsig-0.82.2}/docsig/_files.py

@@ -10,7 +10,6 @@ from __future__ import annotations as _
 import logging as _logging
 import os as _os
 import re as _re
-import typing as _t
 from pathlib import Path as _Path
 
 from pathspec import PathSpec as _PathSpec
@@ -71,7 +70,7 @@ def _glob(path: _Path, pattern: str) -> bool:
     return _WcPath(str(path)).globmatch(pattern)  # type: ignore
 
 
-class Files(_t.List[_Path]):
+class Files(list[_Path]):
     """Collect paths to check (gitignore and exclude applied).
 
     :param paths: Path(s) to collect (files or directories).
@@ -93,7 +92,7 @@ class Files(_t.List[_Path]):
         for path in list(self):
             if str(path) != "." and (
                 any(_re.match(i, str(path)) for i in config.exclude)
-                or any(_glob(path, i) for i in config.excludes or [])
+                or any(_glob(path, i) for i in config.excludes)
             ):
                 logger.debug(FILE_INFO, path, "in exclude list, skipping")
                 self.remove(path)

{docsig-0.82.0 → 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
@@ -23,24 +22,21 @@ from ._stub import Signature as _Signature
 from .messages import Messages as _Messages
 
 
-class _Imports(_t.Dict[str, str]):
-    """Represents python imports."""
+class _Imports(dict[str, str]): ...
 
 
-class _Overloads(_t.Dict[str, "Function"]):
-    """Represents overloaded methods."""
+class _Overloads(dict[str, "Function"]): ...
 
 
-class _Children(_t.List[_t.Union["Parent", "Function"]]):
-    """Represents children of an object."""
+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
@@ -68,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
@@ -130,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)
@@ -160,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
 
@@ -193,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.0 → 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.0 → 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
@@ -36,7 +36,7 @@ _MIN_MATCH = 0.8
 _MAX_MATCH = 1.0
 
 
-class Failures(_t.List["Failure"]):
+class Failures(list["Failure"]):
     """Sequence of Failure instances (one per function checked)."""
 
 
@@ -52,7 +52,7 @@ class Failed(_t.NamedTuple):
     new: bool = False
 
 
-class Failure(_t.List[Failed]):
+class Failure(list[Failed]):
     """Collect docstring and signature failures for one function.
 
     Runs configured checks and appends Failed entries for each
@@ -288,18 +288,18 @@ class Failure(_t.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(_t.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(_t.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.0 → docsig-0.82.2}/docsig/_stub.py

@@ -81,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.
 
@@ -153,7 +151,14 @@ class Param:
         return self._closing_token
 
 
-class Params(_t.List[Param]):
+# 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.
 
     :param ignore: Configuration object for what to ignore.
@@ -219,9 +224,13 @@ class Params(_t.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:
@@ -229,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
 
@@ -237,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(
@@ -265,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)
@@ -283,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):
@@ -302,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
@@ -346,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:
@@ -363,19 +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(
-            ":(?:returns?|yields?):(.*)?",
+            r":(?:returns?|yields?):\s*(.*)",
             string,
             _re.IGNORECASE,
         )
-        returns = bool(match)
-        ret_description_missing = False
-        if match:
-            ret_description_missing = 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,
@@ -406,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.0 → docsig-0.82.2}/docsig/_utils.py

@@ -9,7 +9,6 @@ from __future__ import annotations as _
 
 import re as _re
 import sys as _sys
-import typing as _t
 from difflib import SequenceMatcher as _SequenceMatcher
 
 from .messages import TEMPLATE as _TEMPLATE
@@ -34,7 +33,7 @@ def almost_equal(str1: str, str2: str, mini: float, maxi: float) -> bool:
 
 
 def pretty_print_error(
-    exception_type: _t.Type[BaseException],
+    exception_type: type[BaseException],
     msg: str,
     no_ansi: bool,
 ) -> None:

{docsig-0.82.0 → 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.0"
+__version__ = "0.82.2"

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

@@ -24,7 +24,7 @@ NEW = """\
 """
 
 
-class Messages(_t.List["Message"]):
+class Messages(list["Message"]):
     """Sequence of Message instances, typically for one failure."""
 
 
@@ -41,7 +41,7 @@ class Message(_t.NamedTuple):
     symbolic: str = ""
 
     #: A hint, if any, suggesting why the error may have occurred.
-    hint: _t.Optional[str] = None
+    hint: str | None = None
 
     #: Whether this message is a new addition.
     new: bool = False
@@ -67,7 +67,7 @@ class Message(_t.NamedTuple):
         )
 
 
-class MessageMap(_t.Dict[int, Message]):
+class MessageMap(dict[int, Message]):
     """Mapping from integer key to Message (used for the E registry)."""
 
     def from_ref(self, ref: str) -> Message:
@@ -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.0 → docsig-0.82.2}/docsig/plugin.py

@@ -22,7 +22,7 @@ from ._core import handle_deprecations, runner, setup_logger
 from ._version import __version__
 from .messages import FLAKE8, E
 
-Flake8Error = t.Tuple[int, int, str, t.Type[t.Any]]
+Flake8Error = tuple[int, int, str, type[t.Any]]
 sys.path.append(os.path.abspath(os.getcwd()))
 
 

{docsig-0.82.0 → 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.0"
+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.0"
+version = "0.82.2"
 
 [tool.poetry.dependencies]
 Sphinx = ">=7,<9"
@@ -236,3 +236,14 @@ name = "Removed"
 
 [tool.towncrier.fragment.security]
 name = "Security"
+
+[tool.vulture]
+exclude = [
+  "tests/base_test.py",
+  "tests/conftest.py"
+]
+make_whitelist = true
+paths = [
+  "docsig",
+  "tests"
+]