docsig 0.66.1__tar.gz → 0.67.0__tar.gz

{docsig-0.66.1 → docsig-0.67.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Stephen Whitlock
+Copyright (c) 2025 Stephen Whitlock
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{docsig-0.66.1 → docsig-0.67.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.66.1
+Version: 0.67.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -181,7 +181,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.1.0 (docsig: 0.66.1, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
+    7.1.0 (docsig: 0.67.0, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
 
 And now use `flake8` to lint your files
 
@@ -270,7 +270,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.66.1
+        rev: v0.67.0
         hooks:
           - id: docsig
             args:
@@ -289,7 +289,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.66.1
+              - docsig==0.67.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.66.1 → docsig-0.67.0}/README.rst

@@ -153,7 +153,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.1.0 (docsig: 0.66.1, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
+    7.1.0 (docsig: 0.67.0, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
 
 And now use `flake8` to lint your files
 
@@ -242,7 +242,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.66.1
+        rev: v0.67.0
         hooks:
           - id: docsig
             args:
@@ -261,7 +261,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.66.1
+              - docsig==0.67.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.66.1 → docsig-0.67.0}/docsig/_report.py

@@ -133,7 +133,10 @@ class Failure(_t.List[Failed]):
             # parameter, that way there are no assumptions that the
             # parameters must be out of order
             for count, arg in enumerate(self._func.docstring.args):
-                if arg in self._func.docstring.args.duplicates:
+                if (
+                    arg in self._func.docstring.args.duplicates
+                    and self._func.docstring.args.count(arg) > 1
+                ):
                     self._func.docstring.args.pop(count)
 
             # duplicate-params-found
@@ -224,6 +227,8 @@ class Failure(_t.List[Failed]):
                 if self._func.signature.rettype == _RetType.NONE:
                     # return-documented-for-none
                     self._add(_E[502])
+                if self._func.docstring.ret_description_missing:
+                    self._add(_E[506])
             # return type is some, so return should be documented
             elif self._func.signature.returns:
                 # return-missing

{docsig-0.66.1 → docsig-0.67.0}/docsig/_stub.py

@@ -77,14 +77,31 @@ class DocType(_Enum):
         return cls.UNKNOWN
 
 
-class Param(_t.NamedTuple):
-    """A tuple of param types and their names."""
+#: todo: consider a parent object that can be used for returns that do
+#: todo: not include the name attribute
+class Param:
+    """A tuple of param types and their names.
+
+    :param kind: The type of the parameter.
+    :param name: The name of the parameter.
+    :param description: The description of the parameter.
+    :param indent: The number that the parameter is indented.
+    :param closing_token: The token used for closing the parameter.
+    """
 
-    kind: DocType = DocType.PARAM
-    name: str | None = None
-    description: str | None = None
-    indent: int = 0
-    closing_token: str = ":"
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        kind: DocType = DocType.PARAM,
+        name: str | None = None,
+        description: str | None = None,
+        indent: int = 0,
+        closing_token: str = ":",
+    ) -> None:
+        self.kind = kind
+        self.name = name
+        self.description = description
+        self.indent = indent
+        self.closing_token = closing_token
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, Param):
@@ -265,6 +282,8 @@ class Docstring(_Stub):
 
     :param string: The raw docstring.
     :param returns: Whether this docstring has a return.
+    :param ret_description_missing: Whether description for return is
+        missing from this docstrings.
     """
 
     @staticmethod
@@ -298,11 +317,15 @@ class Docstring(_Stub):
         )
 
     def __init__(
-        self, string: str | None = None, returns: bool = False
+        self,
+        string: str | None = None,
+        returns: bool = False,
+        ret_description_missing: bool = False,
     ) -> None:
         super().__init__()
         self._string = string
         self._returns = returns
+        self._ret_description_missing = ret_description_missing
 
     @classmethod
     def from_ast(cls, node: _ast.Const) -> Docstring:
@@ -313,8 +336,15 @@ class Docstring(_Stub):
         """
         indent_anomaly = cls._indent_anomaly(node.value)
         string = cls._normalize_docstring(node.value)
-        returns = bool(_re.search(r":returns?:", string))
-        docstring = cls(string, returns)
+        # 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?:(.*)?", string)
+        returns = bool(match)
+        ret_description_missing = False
+        if match:
+            ret_description_missing = not match.group(1)
+
+        docstring = cls(string, returns, ret_description_missing)
         for match in _re.findall(
             r":(.*?)([^\w\s])((?:.|\n)*?)(?=\n:|$)", string
         ):
@@ -345,3 +375,8 @@ class Docstring(_Stub):
         Docstring has to exist for docstring to be considered bare.
         """
         return self._string is not None and not self._args and not self.returns
+
+    @property
+    def ret_description_missing(self) -> bool:
+        """Is return description missing?"""
+        return self._ret_description_missing

{docsig-0.66.1 → docsig-0.67.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.66.1"
+__version__ = "0.67.0"

{docsig-0.66.1 → docsig-0.67.0}/docsig/messages.py

@@ -254,6 +254,12 @@ E = MessageMap(
             "return-documented-for-property",
             "documentation is sufficient as a getter is the value returned",
         ),
+        506: Message(
+            "SIG506",
+            "SIG506",
+            "description missing from return",
+            "return-description-missing",
+        ),
         #: SIG9xx Error
         901: Message(
             "SIG901",

{docsig-0.66.1 → docsig-0.67.0}/pyproject.toml

@@ -11,7 +11,7 @@ line-length = 79
 allow_dirty = true
 commit = true
 commit_args = "-sS"
-current_version = "0.66.1"
+current_version = "0.67.0"
 message = "bump: version {current_version} → {new_version}"
 sign_tags = true
 tag = true
@@ -131,7 +131,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.66.1"
+version = "0.67.0"
 
 [tool.poetry.dependencies]
 Sphinx = "^7.0.0"