docsig 0.53.3__tar.gz → 0.54.0__tar.gz

{docsig-0.53.3 → docsig-0.54.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.53.3
+Version: 0.54.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -222,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.3
+        rev: v0.54.0
         hooks:
           - id: docsig
             args:

{docsig-0.53.3 → docsig-0.54.0}/README.rst

@@ -194,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.3
+        rev: v0.54.0
         hooks:
           - id: docsig
             args:

{docsig-0.53.3 → docsig-0.54.0}/docsig/_report.py

@@ -12,6 +12,7 @@ import click as _click
 
 from ._module import Function as _Function
 from ._stub import UNNAMED as _UNNAMED
+from ._stub import VALID_DESCRIPTION as _VALID_DESCRIPTION
 from ._stub import Param as _Param
 from ._stub import RetType as _RetType
 from ._utils import almost_equal as _almost_equal
@@ -81,6 +82,7 @@ class Failure(_t.List[str]):
             for index in range(len(func)):
                 arg = func.signature.args.get(index)
                 doc = func.docstring.args.get(index)
+                self._no_description(doc)
                 self._description_syntax(doc)
                 self._indent_syntax(doc)
 
@@ -153,6 +155,18 @@ class Failure(_t.List[str]):
 
     def _missing(self) -> None:
         if len(self._func.signature.args) > len(self._func.docstring.args):
+            # append the parameters that are missing so that they are
+            # included in 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 are not
+            # documented accounted for
+            for count, arg in enumerate(self._func.signature.args, 1):
+                if count > len(self._func.docstring.args):
+                    self._func.docstring.args.append(
+                        _Param(arg.kind, arg.name, _VALID_DESCRIPTION, 0)
+                    )
+            # params-missing
             self._add(_E[103])
 
     def _duplicates(self) -> None:
@@ -218,6 +232,10 @@ class Failure(_t.List[str]):
         if doc.indent > 0:
             self._add(_E[116])
 
+    def _no_description(self, doc: _Param) -> None:
+        if doc.description is None:
+            self._add(_E[117])
+
     def _invalid_directive(self) -> None:
         for comment in self._func.comments:
             if not comment.isvalid:

{docsig-0.53.3 → docsig-0.54.0}/docsig/_stub.py

@@ -17,6 +17,9 @@ import sphinx.ext.napoleon as _s
 # no function will accidentally have this name
 UNNAMED = -1000
 
+# an example of valid parameter description
+VALID_DESCRIPTION = " A valid description."
+
 
 # noinspection PyTypeChecker
 class _GoogleDocstring(str):
@@ -134,7 +137,9 @@ class Param(_t.NamedTuple):
 class _Matches(_t.List[Param]):
     _pattern = _re.compile(":(.*?):")
 
-    def __init__(self, string: str, indent_anomaly: bool) -> None:
+    def __init__(
+        self, string: str, indent_anomaly: bool, missing_descriptions: bool
+    ) -> None:
         super().__init__()
         for line in string.splitlines():
             strip_line = line.lstrip()
@@ -152,7 +157,9 @@ class _Matches(_t.List[Param]):
                         name = UNNAMED
 
                     if len(match) > 1:
-                        description = match[1]
+                        second = match[1]
+                        if second != "" or not missing_descriptions:
+                            description = second
 
                     super().append(
                         Param(
@@ -326,6 +333,24 @@ class Docstring(_Stub):
         # look for spaces in odd intervals
         return bool(any(i % 2 != 0 for i in leading_spaces))
 
+    @staticmethod
+    def _missing_descriptions(string: str) -> bool:
+        # find out if parameter is missing a description
+        new = ""
+        for line in string.strip().splitlines()[2:]:
+            line = line.lstrip()
+            if not line.startswith(":"):
+                # it is not a parameter, it is a next line description
+                # append the next entry to the same line
+                new = f"{new[:-1]} "
+            new += f"{line}\n"
+        if not new:
+            return True
+
+        # if it ends with a colon, it's a parameter without a
+        # description
+        return any(i.endswith(":") for i in new.splitlines())
+
     def __init__(
         self,
         node: _ast.Const | None = None,
@@ -336,7 +361,11 @@ class Docstring(_Stub):
         self._string = None
         if node is not None:
             self._string = _RawDocstring(node.value)
-            for i in _Matches(self._string, self._indent_anomaly(node.value)):
+            for i in _Matches(
+                self._string,
+                self._indent_anomaly(node.value),
+                self._missing_descriptions(node.value),
+            ):
                 self._args.append(i)
 
         self._returns = self._string is not None and bool(

{docsig-0.53.3 → docsig-0.54.0}/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.3"
+__version__ = "0.54.0"

{docsig-0.53.3 → docsig-0.54.0}/docsig/messages.py

@@ -1,26 +1,6 @@
 """
 docsig.messages
 ===============
-| E101: parameters out of order
-| E102: includes parameters that do not exist
-| E103: parameters missing
-| E104: return statement documented for None
-| E105: return missing from docstring
-| E106: duplicate parameters found
-| E107: parameter appears to be incorrectly documented
-| E108: return statement documented for property
-| E109: cannot determine whether a return statement should exist or not
-| E110: documented parameter not equal to its respective argument
-| E111: return statement documented for class
-| E112: spelling error found in documented parameter
-| E113: function is missing a docstring
-| E114: class is missing a docstring
-| E115: syntax error in description
-| E116: param not indented correctly
-| E201: unknown module comment directive '{directive}'
-| E202: unknown inline comment directive '{directive}'
-| E203: unknown module comment option for {directive} '{option}'
-| E204: unknown inline comment option for {directive} '{option}'
 """
 
 from __future__ import annotations
@@ -157,7 +137,7 @@ E = MessageMap(
         ),
         109: Message(
             "E109",
-            "cannot determine whether a return statement should exist or not",
+            "cannot determine whether a return statement should exist",
             "confirm-return-needed",
             "annotate type to indicate whether return documentation needed",
         ),
@@ -197,6 +177,11 @@ E = MessageMap(
             "param not indented correctly",
             "incorrect-indent",
         ),
+        117: Message(
+            "E117",
+            "description missing from parameter",
+            "description-missing",
+        ),
         # E2xx: Config
         201: Message(
             "E201",

{docsig-0.53.3 → docsig-0.54.0}/pyproject.toml

@@ -76,7 +76,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.53.3"
+version = "0.54.0"
 
 [tool.poetry.dependencies]
 Sphinx = "^7.0.0"