docsig 0.53.0__tar.gz → 0.53.2__tar.gz

{docsig-0.53.0 → docsig-0.53.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.53.0
+Version: 0.53.2
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -90,7 +90,7 @@ Supports reStructuredText (``Sphinx``), ``NumPy``, and ``Google``
 
 Contributing
 ------------
-If you are interested in contributing to ``docsig`` please read about contributing `here <https://github.com/jshwi/docsig/blob/master/CONTRIBUTING.md>`__
+If you are interested in contributing to ``docsig`` please read about contributing `here <https://docsig.readthedocs.io/en/latest/development/contributing.html>`__
 
 Installation
 ------------
@@ -129,7 +129,8 @@ Commandline
       -o, --check-overridden               check overridden methods
       -p, --check-protected                check protected functions and classes
       -P, --check-property-returns         check property return values
-      -i, --ignore-no-params               ignore docstrings where parameters are not documented
+      -i, --ignore-no-params               ignore docstrings where parameters are not
+                                           documented
       -a, --ignore-args                    ignore args prefixed with an asterisk
       -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
       -T, --ignore-typechecker             ignore checking return values
@@ -198,17 +199,17 @@ API
         E102: includes parameters that do not exist (params-do-not-exist)
     1
 
-A full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/docsig.html#docsig-messages>`__
+A full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/usage/messages.html>`__
 
 Message Control
 ***************
 
-`Documentation on message control <https://github.com/jshwi/docsig/blob/master/docs/examples/message-control.rst>`_
+`Documentation on message control <https://docsig.readthedocs.io/en/latest/usage/message-control.html>`_
 
 Classes
 *******
 
-`Documenting classes <https://github.com/jshwi/docsig/blob/master/docs/examples/classes.rst>`_
+`Documenting classes <https://docsig.readthedocs.io/en/latest/usage/configuration.html#classes>`_
 
 pre-commit
 **********
@@ -221,7 +222,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.53.0
+        rev: v0.53.2
         hooks:
           - id: docsig
             args:

{docsig-0.53.0 → docsig-0.53.2}/README.rst

@@ -62,7 +62,7 @@ Supports reStructuredText (``Sphinx``), ``NumPy``, and ``Google``
 
 Contributing
 ------------
-If you are interested in contributing to ``docsig`` please read about contributing `here <https://github.com/jshwi/docsig/blob/master/CONTRIBUTING.md>`__
+If you are interested in contributing to ``docsig`` please read about contributing `here <https://docsig.readthedocs.io/en/latest/development/contributing.html>`__
 
 Installation
 ------------
@@ -101,7 +101,8 @@ Commandline
       -o, --check-overridden               check overridden methods
       -p, --check-protected                check protected functions and classes
       -P, --check-property-returns         check property return values
-      -i, --ignore-no-params               ignore docstrings where parameters are not documented
+      -i, --ignore-no-params               ignore docstrings where parameters are not
+                                           documented
       -a, --ignore-args                    ignore args prefixed with an asterisk
       -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
       -T, --ignore-typechecker             ignore checking return values
@@ -170,17 +171,17 @@ API
         E102: includes parameters that do not exist (params-do-not-exist)
     1
 
-A full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/docsig.html#docsig-messages>`__
+A full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/usage/messages.html>`__
 
 Message Control
 ***************
 
-`Documentation on message control <https://github.com/jshwi/docsig/blob/master/docs/examples/message-control.rst>`_
+`Documentation on message control <https://docsig.readthedocs.io/en/latest/usage/message-control.html>`_
 
 Classes
 *******
 
-`Documenting classes <https://github.com/jshwi/docsig/blob/master/docs/examples/classes.rst>`_
+`Documenting classes <https://docsig.readthedocs.io/en/latest/usage/configuration.html#classes>`_
 
 pre-commit
 **********
@@ -193,7 +194,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.53.0
+        rev: v0.53.2
         hooks:
           - id: docsig
             args:

{docsig-0.53.0 → docsig-0.53.2}/docsig/_module.py

@@ -152,7 +152,12 @@ class Parent(_t.List["Parent"]):
                         self._imports,
                     )
                     if func.isoverloaded:
-                        self._overloads[func.name] = func
+                        if (
+                            func.name not in self._overloads
+                            or self._overloads[func.name].signature.rettype
+                            == _RetType.NONE
+                        ):
+                            self._overloads[func.name] = func
                     else:
                         if func.name in self._overloads:
                             func.overload(

{docsig-0.53.0 → docsig-0.53.2}/docsig/_report.py

@@ -11,6 +11,7 @@ import typing as _t
 import click as _click
 
 from ._module import Function as _Function
+from ._stub import UNNAMED as _UNNAMED
 from ._stub import Param as _Param
 from ._stub import RetType as _RetType
 from ._utils import almost_equal as _almost_equal
@@ -65,10 +66,14 @@ class Failure(_t.List[str]):
         self._missing_class_docstring()
         self._missing_func_docstring()
         if func.docstring.string is not None:
-            self._return_not_typed()
+            # make sure these come first as they alter the function
+            # docstring object before it is analysed further
+            self._duplicates()
             self._exists()
+
+            # all further analysis below
+            self._return_not_typed()
             self._missing()
-            self._duplicates()
             self._extra_return()
             self._missing_return()
             self._property_return()
@@ -78,9 +83,9 @@ class Failure(_t.List[str]):
                 doc = func.docstring.args.get(index)
                 self._description_syntax(doc)
                 self._indent_syntax(doc)
+                self._incorrect(doc)
                 if arg != doc:
                     self._order(arg, doc)
-                    self._incorrect(arg, doc)
                     self._misspelled(arg, doc)
                     self._not_equal(arg, doc)
 
@@ -105,7 +110,16 @@ class Failure(_t.List[str]):
             self._add(_E[101])
 
     def _exists(self) -> None:
+        # pop the parameters that do not exist so that they are excluded
+        # from further analysis, that way there are no additional, and
+        # redundant, errors
+        # this will ensure that both signature and docstring are equal
+        # in length, with all parameters that do not exist accounted for
         if len(self._func.docstring.args) > len(self._func.signature.args):
+            for count, __ in enumerate(self._func.docstring.args, 1):
+                if count > len(self._func.signature.args):
+                    self._func.docstring.args.pop(count - 1)
+
             self._add(_E[102])
 
     def _missing_func_docstring(self) -> None:
@@ -121,7 +135,14 @@ class Failure(_t.List[str]):
             self._add(_E[103])
 
     def _duplicates(self) -> None:
+        # pop the duplicates so that they are considered a single
+        # parameter, that way there are no assumptions that the
+        # parameters must be out of order
         if self._func.docstring.args.duplicated:
+            for count, arg in enumerate(self._func.docstring.args):
+                if arg in self._func.docstring.args.duplicates:
+                    self._func.docstring.args.pop(count)
+
             self._add(_E[106])
 
     def _extra_return(self) -> None:
@@ -151,13 +172,25 @@ class Failure(_t.List[str]):
             and not self._no_returns
         ):
             docstring = self._func.docstring.string
-            if docstring is not None and "return" in docstring:
-                hint = True
+            # do more than just search the docstring for the word return
+            # as return statements come last, so only search the last
+            # line
+            # params can also come last, so make sure it is not a param
+            # declaration
+            if docstring is not None:
+                lines = docstring.splitlines()
+                if len(lines) > 1:
+                    if "return" in lines[-1] and ":param" not in lines[-1]:
+                        hint = True
 
             self._add(_E[105], hint=hint)
 
-    def _incorrect(self, sig: _Param, doc: _Param) -> None:
-        if sig.name is None and doc.name is None:
+    def _incorrect(self, doc: _Param) -> None:
+        # if the parameter does not have a name, but exists, then it
+        # must be incorrectly documented
+        # prior implementation relied on the docstring parameter
+        # equalling the signature parameter
+        if doc.name == _UNNAMED:
             self._add(_E[107])
 
     # final catch-all

{docsig-0.53.0 → docsig-0.53.2}/docsig/_stub.py

@@ -14,6 +14,9 @@ from enum import Enum as _Enum
 import astroid as _ast
 import sphinx.ext.napoleon as _s
 
+# no function will accidentally have this name
+UNNAMED = -1000
+
 
 # noinspection PyTypeChecker
 class _GoogleDocstring(str):
@@ -131,19 +134,22 @@ class Param(_t.NamedTuple):
 class _Matches(_t.List[Param]):
     _pattern = _re.compile(":(.*?):")
 
-    def __init__(self, string: str) -> None:
+    def __init__(self, string: str, indent_anomaly: bool) -> None:
         super().__init__()
         for line in string.splitlines():
             strip_line = line.lstrip()
             match = self._pattern.split(strip_line)[1:]
             if match:
-                name = description = None
+                description = None
                 kinds = match[0].split()
                 if kinds:
                     kind = DocType.from_str(kinds[0])
 
                     if len(kinds) > 1:
                         name = kinds[1]
+                    else:
+                        # name could not be parsed
+                        name = UNNAMED
 
                     if len(match) > 1:
                         description = match[1]
@@ -153,7 +159,7 @@ class _Matches(_t.List[Param]):
                             kind,
                             name,
                             description,
-                            len(line) - len(strip_line),
+                            int(indent_anomaly),
                         )
                     )
 
@@ -165,6 +171,7 @@ class _Params(_t.List[Param]):
         super().__init__()
         self._ignore_args = ignore_args
         self._ignore_kwargs = ignore_kwargs
+        self._duplicates: list[Param] = []
 
     # pylint: disable=too-many-boolean-expressions
     def append(self, value: Param) -> None:
@@ -195,8 +202,26 @@ class _Params(_t.List[Param]):
 
     @property
     def duplicated(self) -> bool:
-        """Boolean value for whether there are duplicate parameters."""
-        return any(k for k, v in _Counter(self).items() if v > 1)
+        """Boolean value for whether there are duplicate parameters.
+
+        Ensure only the names of the parameters are needed to be
+        considered duplicates. It is not relevant whether the
+        descriptions match.
+        """
+        for k, v in _Counter(i.name for i in self).items():
+            if v > 1:
+                for i in self:
+                    if i.name == k:
+                        # record the duplicates for later analysis
+                        self._duplicates.append(i)
+                        return True
+
+        return False
+
+    @property
+    def duplicates(self) -> list[Param]:
+        """Duplicated parameters."""
+        return self._duplicates
 
 
 class _Stub:
@@ -288,6 +313,19 @@ class Docstring(_Stub):
     :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
     """
 
+    @staticmethod
+    def _indent_anomaly(string: str) -> bool:
+        leading_spaces = []
+        for line in string.splitlines():
+            match = _re.match(r"^\s*", line)
+            if match is not None:
+                spaces = len(match.group())
+                if spaces > 0:
+                    leading_spaces.append(spaces)
+
+        # look for spaces in odd intervals
+        return bool(any(i % 2 != 0 for i in leading_spaces))
+
     def __init__(
         self,
         node: _ast.Const | None = None,
@@ -298,7 +336,7 @@ class Docstring(_Stub):
         self._string = None
         if node is not None:
             self._string = _RawDocstring(node.value)
-            for i in _Matches(self._string):
+            for i in _Matches(self._string, self._indent_anomaly(node.value)):
                 self._args.append(i)
 
         self._returns = self._string is not None and bool(

{docsig-0.53.0 → docsig-0.53.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.53.0"
+__version__ = "0.53.2"

{docsig-0.53.0 → docsig-0.53.2}/pyproject.toml

@@ -27,6 +27,7 @@ fail_under = 100
 
 [tool.coverage.run]
 omit = [
+  "docs/conf.py",
   "docsig/__main__.py",
   "whitelist.py"
 ]
@@ -65,7 +66,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.53.0"
+version = "0.53.2"
 
 [tool.poetry.dependencies]
 Sphinx = "^7.0.0"
@@ -78,14 +79,16 @@ python = "^3.8"
 [tool.poetry.dev-dependencies]
 bump2version = "^1.0.1"
 deptry = "^0.16.1"
+furo = "^2024.4.27"
 ipython = "^8.12.0"
+myst-parser = "^3.0.1"
 pre-commit = "^3.3.3"
 pyaud = "^7.5.0"
 pytest-randomly = "^3.13.0"
 pytest-sugar = "^1.0.0"
 pytest-xdist = "^3.6.1"
 restview = "^3.0.0"
-sphinx-immaterial = "^0.11.9"
+sphinx-copybutton = "^0.5.2"
 sphinx-toolbox = "^3.5.0"
 templatest = "^0.10.1"
 tox = "^4.15.0"
@@ -95,10 +98,8 @@ docsig = "docsig.__main__:main"
 
 [tool.pyaud]
 audit = [
-  "about-tests",
   "commit-policy",
   "copyright-year",
-  "files",
   "format",
   "format-docs",
   "format-str",
@@ -106,13 +107,14 @@ audit = [
   "lint",
   "test",
   "typecheck",
-  "unused"
+  "unused",
+  "whitelist"
 ]
 exclude = '''
 (?x)^(
   | docs\/conf\.py
   | whitelist\.py
-  | scripts\/update_readme\.py
+  | scripts\/.*
 )$
 '''