docsig 0.64.1__tar.gz → 0.66.0__tar.gz

{docsig-0.64.1 → docsig-0.66.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.64.1
+Version: 0.66.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.64.1, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
+    7.1.0 (docsig: 0.66.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.64.1
+        rev: v0.66.0
         hooks:
           - id: docsig
             args:
@@ -289,7 +289,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.64.1
+              - docsig==0.66.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.64.1 → docsig-0.66.0}/README.rst

@@ -153,7 +153,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.1.0 (docsig: 0.64.1, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
+    7.1.0 (docsig: 0.66.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.64.1
+        rev: v0.66.0
         hooks:
           - id: docsig
             args:
@@ -261,7 +261,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.64.1
+              - docsig==0.66.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.64.1 → docsig-0.66.0}/docsig/_config.py

@@ -254,13 +254,4 @@ def parse_args(args: _t.Sequence[str] | None = None) -> _a.Namespace:
         metavar="PATH",
         help="path glob patterns to exclude from checks",
     )
-
-    # deprecated
-    parser.add_argument(
-        "-S",
-        "--summary",
-        action="store_true",
-        help=_a.SUPPRESS,
-    )
-
     return parser.parse_args(args)

{docsig-0.64.1 → docsig-0.66.0}/docsig/_core.py

@@ -95,7 +95,7 @@ def _run_check(  # pylint: disable=too-many-arguments,too-many-locals
                 failures.append(failure)
 
         if check_nested:
-            for func in child:
+            for func in child.children:
                 _run_check(
                     func,
                     child,
@@ -114,7 +114,7 @@ def _run_check(  # pylint: disable=too-many-arguments,too-many-locals
                 )
     else:
         # this is a class
-        for func in child:
+        for func in child.children:
             _run_check(
                 func,
                 child,
@@ -134,28 +134,28 @@ def _run_check(  # pylint: disable=too-many-arguments,too-many-locals
 
 
 def _from_file(
-    root: _Path,
+    path: _Path,
     messages: _Messages,
     ignore_args: bool,
     ignore_kwargs: bool,
     check_class_constructor,
 ) -> _Parent:
     try:
-        string = root.read_text(encoding="utf-8")
+        string = path.read_text(encoding="utf-8")
         parent = _from_str(
             messages=messages,
             string=string,
-            root=root,
+            path=path,
             ignore_args=ignore_args,
             ignore_kwargs=ignore_kwargs,
             check_class_constructor=check_class_constructor,
         )
     except UnicodeDecodeError as err:
         logger = _logging.getLogger(__package__)
-        logger.debug(_FILE_INFO, root, str(err).replace("\n", " "))
+        logger.debug(_FILE_INFO, path, str(err).replace("\n", " "))
         parent = _Parent(error=_Error.UNICODE)
 
-    if parent.error is not None and not root.name.endswith(".py"):
+    if parent.error is not None and not path.name.endswith(".py"):
         parent = _Parent()
 
     return parent
@@ -167,23 +167,23 @@ def _from_str(  # pylint: disable=too-many-arguments
     ignore_args: bool,
     ignore_kwargs: bool,
     check_class_constructor,
-    root: _Path | None = None,
+    path: _Path | None = None,
 ) -> _Parent:
     logger = _logging.getLogger(__package__)
     try:
         parent = _Parent(
             _ast.parse(string),
             _Directives.from_text(string, messages),
-            root,
+            path,
             ignore_args,
             ignore_kwargs,
             check_class_constructor,
         )
         logger.debug(
-            _FILE_INFO, root or "stdin", "Parsing Python code successful"
+            _FILE_INFO, path or "stdin", "Parsing Python code successful"
         )
     except _ast.AstroidSyntaxError as err:
-        logger.debug(_FILE_INFO, root or "stdin", str(err).replace("\n", " "))
+        logger.debug(_FILE_INFO, path or "stdin", str(err).replace("\n", " "))
         parent = _Parent(error=_Error.SYNTAX)
 
     return parent
@@ -205,7 +205,7 @@ def _get_failures(  # pylint: disable=too-many-arguments
     target: _Messages,
 ) -> _Failures:
     failures = _Failures()
-    for top_level in module:
+    for top_level in module.children:
         if (
             not top_level.isprotected
             or check_protected
@@ -259,7 +259,7 @@ def _report(
 
 
 def runner(  # pylint: disable=too-many-locals,too-many-arguments
-    file: str | _Path,
+    path: _Path,
     disable: _Messages | None = None,
     check_class: bool = False,
     check_class_constructor: bool = False,
@@ -278,7 +278,7 @@ def runner(  # pylint: disable=too-many-locals,too-many-arguments
 ) -> _Failures:
     """Per path runner.
 
-    :param file: Path to check.
+    :param path: Path to check.
     :param disable: Messages to disable.
     :param check_class: Check class docstrings.
     :param check_class_constructor: Check ``__init__`` methods. Note
@@ -300,7 +300,7 @@ def runner(  # pylint: disable=too-many-locals,too-many-arguments
     :return: Exit status for whether test failed or not.
     """
     module = _from_file(
-        _Path(file),
+        path,
         disable or _Messages(),
         ignore_args,
         ignore_kwargs,
@@ -324,7 +324,6 @@ def runner(  # pylint: disable=too-many-locals,too-many-arguments
 
 
 @_decorators.parse_msgs
-@_decorators.handle_deprecations
 @_decorators.validate_args
 def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     *path: str | _Path,
@@ -392,21 +391,21 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     if list_checks:
         return int(bool(_print_checks()))  # type: ignore
 
-    patterns = [_DEFAULT_EXCLUDES]
+    exclude_ = [_DEFAULT_EXCLUDES]
     if exclude is not None:
-        patterns.append(exclude)
+        exclude_.append(exclude)
 
     if string is None:
         retcodes = [0]
         paths = _Paths(
             *path,
-            patterns=patterns,
-            excludes=excludes or [],
+            patterns=exclude_,
+            excludes=excludes,
             include_ignored=include_ignored,
         )
-        for file in paths:
+        for path_ in paths:
             failures = runner(
-                file,
+                path_,
                 disable,
                 check_class,
                 check_class_constructor,
@@ -423,7 +422,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
                 no_ansi,
                 target,
             )
-            retcodes.append(_report(failures, str(file), no_ansi))
+            retcodes.append(_report(failures, str(path_), no_ansi))
 
         return max(retcodes)
 

{docsig-0.64.1 → docsig-0.66.0}/docsig/_decorators.py

@@ -9,7 +9,6 @@ import functools as _functools
 import sys as _sys
 import typing as _t
 from pathlib import Path as _Path
-from warnings import warn as _warn
 
 from .messages import E as _E
 
@@ -35,28 +34,6 @@ def parse_msgs(func: _WrappedFuncType) -> _WrappedFuncType:
     return _wrapper
 
 
-def handle_deprecations(func: _WrappedFuncType) -> _WrappedFuncType:
-    """Allow, but warn, of deprecated arguments.
-
-    :param func: Function to wrap.
-    :return: Wrapped function.
-    """
-
-    @_functools.wraps(func)
-    def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> str | int:
-        if kwargs.pop("summary", None):
-            _warn(
-                "summary is deprecated and will be removed in a future"
-                " version",
-                category=DeprecationWarning,
-                stacklevel=4,
-            )
-
-        return func(*args, **kwargs)
-
-    return _wrapper
-
-
 def validate_args(func: _FuncType) -> _WrappedFuncType:
     """Confirm args passed to function are valid.
 

{docsig-0.64.1 → docsig-0.66.0}/docsig/_files.py

@@ -82,7 +82,7 @@ class Paths(_t.List[_Path]):
         self,
         *paths: _Path | str,
         patterns: list[str],
-        excludes: list[str],
+        excludes: list[str] | None = None,
         include_ignored: bool = False,
     ) -> None:
         super().__init__()

{docsig-0.64.1 → docsig-0.66.0}/docsig/_main.py

@@ -39,7 +39,6 @@ def main() -> str | int:
         ignore_kwargs=a.ignore_kwargs,
         ignore_typechecker=a.ignore_typechecker,
         no_ansi=a.no_ansi,
-        summary=a.summary,  # deprecated
         verbose=a.verbose,
         target=a.target,
         disable=a.disable,

{docsig-0.64.1 → docsig-0.66.0}/docsig/_module.py

@@ -31,7 +31,7 @@ class _Imports(_t.Dict[str, str]):
     """Represents python imports."""
 
 
-class Parent(_t.List["Parent"]):
+class Parent:  # pylint: disable=too-many-instance-attributes
     """Represents an object that contains functions or methods.
 
     :param node: Parent's abstract syntax tree.
@@ -64,13 +64,14 @@ class Parent(_t.List["Parent"]):
         self._ignore_args = ignore_args
         self._ignore_kwargs = ignore_kwargs
         self._check_class_constructor = check_class_constructor
+        self._children = _Children()
+        self._imports = imports or _Imports()
+        self._overloads = _Overloads()
         if node is None:
             if not isinstance(self, Function) and error is not None:
-                self.append(Function(path, error=error))
+                self._children.append(Function(path, error=error))
         else:
             self._name = node.name
-            self._overloads = _Overloads()
-            self._imports = imports or _Imports()
             self._parse_ast(node, directives or _Directives(), path)
 
     def _parse_ast(
@@ -121,9 +122,9 @@ class Parent(_t.List["Parent"]):
                                 self._overloads[func.name].signature.rettype
                             )
 
-                        self.append(func)
+                        self._children.append(func)
                 elif isinstance(subnode, _ast.ClassDef):
-                    self.append(
+                    self._children.append(
                         Parent(
                             subnode,
                             directives,
@@ -147,6 +148,11 @@ class Parent(_t.List["Parent"]):
         """Represents an unrecoverable error, if any."""
         return self._error
 
+    @property
+    def children(self) -> _Children:
+        """Children of this parent."""
+        return self._children
+
 
 class Function(Parent):
     """Represents a function with signature and docstring parameters.
@@ -337,3 +343,7 @@ class Function(Parent):
 
 class _Overloads(_t.Dict[str, Function]):
     """Represents overloaded methods."""
+
+
+class _Children(_t.List[_t.Union[Parent, Function]]):
+    """Represents children of object."""

{docsig-0.64.1 → docsig-0.66.0}/docsig/_report.py

@@ -180,6 +180,13 @@ class Failure(_t.List[Failed]):
         elif doc.name == _UNNAMED:
             # param-incorrectly-documented
             self._add(_E[303])
+        elif doc.closing_token != ":":
+            # bad-closing-token
+            self._add(
+                _E[304],
+                token=doc.closing_token,
+                hint=True,
+            )
 
     def _sig4xx_parameters(self, doc: _Param, sig: _Param) -> None:
         if doc.indent > 0:

{docsig-0.64.1 → docsig-0.66.0}/docsig/_stub.py

@@ -84,6 +84,7 @@ class Param(_t.NamedTuple):
     name: str | None = None
     description: str | None = None
     indent: int = 0
+    closing_token: str = ":"
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, Param):
@@ -314,7 +315,9 @@ class Docstring(_Stub):
         string = cls._normalize_docstring(node.value)
         returns = bool(_re.search(r":returns?:", string))
         docstring = cls(string, returns)
-        for match in _re.findall(r":(.*?):((?:.|\n)*?)(?=\n:|$)", string):
+        for match in _re.findall(
+            r":(.*?)([^\w\s])((?:.|\n)*?)(?=\n:|$)", string
+        ):
             if match:
                 kinds = match[0].split()
                 if kinds:
@@ -322,8 +325,9 @@ class Docstring(_Stub):
                         Param(
                             DocType.from_str(kinds[0]),
                             UNNAMED if len(kinds) == 1 else kinds[1],
-                            match[1] or None,
+                            match[2] or None,
                             int(indent_anomaly),
+                            match[1],
                         )
                     )
 

{docsig-0.64.1 → docsig-0.66.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.64.1"
+__version__ = "0.66.0"

{docsig-0.64.1 → docsig-0.66.0}/docsig/messages.py

@@ -187,6 +187,13 @@ E = MessageMap(
             "parameter appears to be incorrectly documented",
             "param-incorrectly-documented",
         ),
+        304: Message(
+            "SIG304",
+            "SIG304",
+            "bad token used to close parameter declaration '{token}'",
+            "bad-closing-token",
+            "close a parameter declaration with ':'",
+        ),
         #: SIG4xx Description
         401: Message(
             "SIG401",

{docsig-0.64.1 → docsig-0.66.0}/docsig/plugin.py

@@ -3,6 +3,7 @@
 import ast
 import typing as t
 from argparse import Namespace
+from pathlib import Path
 
 from ._config import get_config as _get_config
 from ._config import merge_configs as _merge_configs
@@ -147,7 +148,7 @@ class Docsig:
         else:
             setup_logger(self.a.verbose)
             results = runner(
-                self.filename,
+                Path(self.filename),
                 check_class=self.a.check_class,
                 check_class_constructor=self.a.check_class_constructor,
                 check_dunders=self.a.check_dunders,

{docsig-0.64.1 → docsig-0.66.0}/pyproject.toml

@@ -11,7 +11,7 @@ line-length = 79
 allow_dirty = true
 commit = true
 commit_args = "-sS"
-current_version = "0.64.1"
+current_version = "0.66.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.64.1"
+version = "0.66.0"
 
 [tool.poetry.dependencies]
 Sphinx = "^7.0.0"
@@ -143,7 +143,7 @@ wcmatch = ">=8.5.2,<11.0.0"
 
 [tool.poetry.group.dev.dependencies]
 black = "^24.4.2"
-bump-my-version = ">=0.24.1,<0.27.0"
+bump-my-version = ">=0.24.1,<0.30.0"
 deptry = ">=0.16.1,<0.21.0"
 docformatter = "^1.7.5"
 flynt = "^1.0.1"