docsig 0.53.2__tar.gz → 0.54.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.53.2
+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.2
+        rev: v0.54.0
         hooks:
           - id: docsig
             args:

{docsig-0.53.2 → 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.2
+        rev: v0.54.0
         hooks:
           - id: docsig
             args:

{docsig-0.53.2 → 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,13 +82,41 @@ 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)
-                self._incorrect(doc)
-                if arg != doc:
-                    self._order(arg, doc)
-                    self._misspelled(arg, doc)
-                    self._not_equal(arg, doc)
+
+                if doc.name == _UNNAMED:
+                    # 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
+                    self._add(_E[107])
+
+                elif arg != doc:
+                    if any(
+                        arg.name == i.name for i in self._func.docstring.args
+                    ) or any(
+                        doc.name == i.name for i in self._func.signature.args
+                    ):
+                        # parameters out of order
+                        self._add(_E[101])
+
+                    elif (
+                        arg.name is not None
+                        and doc.name is not None
+                        and not self._errors
+                        and _almost_equal(
+                            arg.name, doc.name, _MIN_MATCH, _MAX_MATCH
+                        )
+                    ):
+                        # spelling error found in documented parameter
+                        self._add(_E[112])
+
+                    elif arg.name is not None and doc.name is not None:
+                        # documented parameter not equal to its
+                        # respective argument
+                        self._add(_E[110])
 
         self.sort()
 
@@ -103,12 +132,6 @@ class Failure(_t.List[str]):
         if value not in self._disable and message not in self:
             super().append(message)
 
-    def _order(self, sig: _Param, doc: _Param) -> None:
-        if any(sig.name == i.name for i in self._func.docstring.args) or any(
-            doc.name == i.name for i in self._func.signature.args
-        ):
-            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
@@ -132,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:
@@ -185,32 +220,10 @@ class Failure(_t.List[str]):
 
             self._add(_E[105], hint=hint)
 
-    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
-    def _not_equal(self, sig: _Param, doc: _Param) -> None:
-        if sig.name is not None and doc.name is not None and not self._errors:
-            self._add(_E[110])
-
     def _class_return(self) -> None:
         if self._func.docstring.returns and self._func.isinit:
             self._add(_E[111], hint=True)
 
-    def _misspelled(self, sig: _Param, doc: _Param) -> None:
-        if (
-            sig.name is not None
-            and doc.name is not None
-            and not self._errors
-            and _almost_equal(sig.name, doc.name, _MIN_MATCH, _MAX_MATCH)
-        ):
-            self._add(_E[112])
-
     def _description_syntax(self, doc: _Param) -> None:
         if doc.description is not None and not doc.description.startswith(" "):
             self._add(_E[115])
@@ -219,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.2 → 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.2 → 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.2"
+__version__ = "0.54.0"

{docsig-0.53.2 → 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.2 → docsig-0.54.0}/pyproject.toml

@@ -5,15 +5,6 @@ requires = [
 ]
 
 [tool.black]
-exclude = '''
-/(
-  | \.git
-  | \.mypy_cache
-  | _build
-  | build
-  | dist
-)/
-'''
 line-length = 79
 
 [tool.codespell]
@@ -32,10 +23,21 @@ omit = [
   "whitelist.py"
 ]
 
+[tool.deptry.per_rule_ignores]
+DEP004 = ["yaml"]
+
+[tool.docformatter]
+in-place = true
+wrap-summaries = 72
+
 [tool.docsig]
 check-class = true
 check-protected-class-methods = true
 
+[tool.flynt]
+line-length = 79
+transform-concats = true
+
 [tool.isort]
 ensure_newline_before_comments = true
 force_grid_wrap = 0
@@ -45,6 +47,14 @@ multi_line_output = 3
 profile = "black"
 use_parentheses = true
 
+[tool.mypy]
+exclude = [
+  "whitelist\\.py"
+]
+ignore_missing_imports = true
+install_types = true
+non_interactive = true
+
 [tool.poetry]
 authors = [
   "jshwi <stephen@jshwisolutions.com>"
@@ -66,7 +76,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.53.2"
+version = "0.54.0"
 
 [tool.poetry.dependencies]
 Sphinx = "^7.0.0"
@@ -76,57 +86,62 @@ click = "^8.1.7"
 pathspec = "^0.12.1"
 python = "^3.8"
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
+black = "^24.4.2"
 bump2version = "^1.0.1"
 deptry = "^0.16.1"
+docformatter = "^1.7.5"
+flynt = "^1.0.1"
+isort = "^5.13.2"
+mypy = "^1.10.0"
+pre-commit = "^3.3.3"
+pylint = "^3.1.0"
+tox = "^4.15.0"
+vulture = "^2.11"
+
+[tool.poetry.group.docs.dependencies]
 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 = "^8.2.0"
+pyyaml = "^6.0.1"
+sphinx-copybutton = "^0.5.2"
+sphinx-markdown-builder = ">=0.5.5,<0.7.0"
+templatest = "^0.10.1"
+
+[tool.poetry.group.tests.dependencies]
+pytest = "^8.2.0"
+pytest-benchmark = "^4.0.0"
+pytest-cov = "^5.0.0"
+pytest-randomly = "^3.15.0"
 pytest-sugar = "^1.0.0"
 pytest-xdist = "^3.6.1"
-restview = "^3.0.0"
-sphinx-copybutton = "^0.5.2"
-sphinx-toolbox = "^3.5.0"
 templatest = "^0.10.1"
-tox = "^4.15.0"
 
 [tool.poetry.scripts]
 docsig = "docsig.__main__:main"
 
-[tool.pyaud]
-audit = [
-  "commit-policy",
-  "copyright-year",
-  "format",
-  "format-docs",
-  "format-str",
-  "imports",
-  "lint",
-  "test",
-  "typecheck",
-  "unused",
-  "whitelist"
+[tool.pylint.options]
+disable = [
+  "consider-using-f-string",
+  "fixme"
 ]
-exclude = '''
-(?x)^(
-  | docs\/conf\.py
-  | whitelist\.py
-  | scripts\/.*
-)$
-'''
+ignore-patterns = [
+  'conf\.py',
+  'whitelist\.py'
+]
+min-similarity-lines = 9
 
 [tool.pytest.ini_options]
 addopts = [
   "--color=yes",
   "--cov-report=term-missing",
   "--durations=5",
-  "-n=auto",
   "-vv"
 ]
 filterwarnings = "ignore::DeprecationWarning"
+markers = [
+  "benchmark: Marks tests as benchmarks"
+]
 norecursedirs = [
   ".git",
   ".idea",