docsig 0.52.0__tar.gz → 0.53.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.52.0
+Version: 0.53.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -17,7 +17,6 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: Pygments (>=2.13.0,<3.0.0)
 Requires-Dist: Sphinx (>=7.0.0,<8.0.0)
 Requires-Dist: arcon (>=0.4.0)
 Requires-Dist: astroid (>=3.0.1,<4.0.0)
@@ -108,10 +107,9 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a]
-                           [-k] [-I] [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST]
-                           [-e PATTERN]
-                           [path [path ...]]
+    usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a] [-k] [-T]
+                  [-I] [-n] [-v] [-s STR] [-d LIST] [-t LIST] [-e PATTERN]
+                  [path [path ...]]
 
     Check signature params for proper documentation
 
@@ -123,41 +121,35 @@ Commandline
       -V, --version                        show program's version number and exit
       -l, --list-checks                    display a list of all checks and their messages
       -c, --check-class                    check class docstrings
-      -C, --check-class-constructor        check __init__ methods. Note: mutually
-                                           incompatible with -c
+      -C, --check-class-constructor        check __init__ methods. Note: mutually incompatible
+                                           with -c
       -D, --check-dunders                  check dunder methods
-      -m, --check-protected-class-methods  check public methods belonging to protected
-                                           classes
+      -m, --check-protected-class-methods  check public methods belonging to protected classes
       -N, --check-nested                   check nested functions and classes
       -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
-      -I, --include-ignored                check files even if they match a gitignore
-                                           pattern
+      -T, --ignore-typechecker             ignore checking return values
+      -I, --include-ignored                check files even if they match a gitignore pattern
       -n, --no-ansi                        disable ansi output
-      -S, --summary                        print a summarised report
       -v, --verbose                        increase output verbosity
       -s STR, --string STR                 string to parse instead of files
       -d LIST, --disable LIST              comma separated list of rules to disable
       -t LIST, --target LIST               comma separated list of rules to target
-      -e PATTERN, --exclude PATTERN        regular expression of files or dirs to exclude
-                                           from checks
+      -e PATTERN, --exclude PATTERN        regular expression of files or dirs to exclude from
+                                           checks
 
 Options can also be configured with the pyproject.toml file
 
-If you find the output is too verbose then the report can be configured to display a summary
-
 .. code-block:: toml
 
     [tool.docsig]
     check-dunders = false
     check-overridden = false
     check-protected = false
-    summary = true
     disable = [
         "E101",
         "E102",
@@ -187,7 +179,7 @@ API
     ...     :param param3: About param3.
     ...     '''
     ...     """
-    >>> docsig(string=string, summary=True, no_ansi=True)
+    >>> docsig(string=string, no_ansi=True)
     0
 
 .. code-block:: python
@@ -201,7 +193,7 @@ API
     ...     :param param3: About param3.
     ...     '''
     ... """
-    >>> docsig(string=string, summary=True, no_ansi=True)
+    >>> docsig(string=string, no_ansi=True)
     2 in function
         E102: includes parameters that do not exist (params-do-not-exist)
     1
@@ -229,7 +221,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.52.0
+        rev: v0.53.0
         hooks:
           - id: docsig
             args:
@@ -237,5 +229,4 @@ It can be added to your .pre-commit-config.yaml as follows:
               - "--check-dunders"
               - "--check-overridden"
               - "--check-protected"
-              - "--summary"
 

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

@@ -79,10 +79,9 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a]
-                           [-k] [-I] [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST]
-                           [-e PATTERN]
-                           [path [path ...]]
+    usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a] [-k] [-T]
+                  [-I] [-n] [-v] [-s STR] [-d LIST] [-t LIST] [-e PATTERN]
+                  [path [path ...]]
 
     Check signature params for proper documentation
 
@@ -94,41 +93,35 @@ Commandline
       -V, --version                        show program's version number and exit
       -l, --list-checks                    display a list of all checks and their messages
       -c, --check-class                    check class docstrings
-      -C, --check-class-constructor        check __init__ methods. Note: mutually
-                                           incompatible with -c
+      -C, --check-class-constructor        check __init__ methods. Note: mutually incompatible
+                                           with -c
       -D, --check-dunders                  check dunder methods
-      -m, --check-protected-class-methods  check public methods belonging to protected
-                                           classes
+      -m, --check-protected-class-methods  check public methods belonging to protected classes
       -N, --check-nested                   check nested functions and classes
       -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
-      -I, --include-ignored                check files even if they match a gitignore
-                                           pattern
+      -T, --ignore-typechecker             ignore checking return values
+      -I, --include-ignored                check files even if they match a gitignore pattern
       -n, --no-ansi                        disable ansi output
-      -S, --summary                        print a summarised report
       -v, --verbose                        increase output verbosity
       -s STR, --string STR                 string to parse instead of files
       -d LIST, --disable LIST              comma separated list of rules to disable
       -t LIST, --target LIST               comma separated list of rules to target
-      -e PATTERN, --exclude PATTERN        regular expression of files or dirs to exclude
-                                           from checks
+      -e PATTERN, --exclude PATTERN        regular expression of files or dirs to exclude from
+                                           checks
 
 Options can also be configured with the pyproject.toml file
 
-If you find the output is too verbose then the report can be configured to display a summary
-
 .. code-block:: toml
 
     [tool.docsig]
     check-dunders = false
     check-overridden = false
     check-protected = false
-    summary = true
     disable = [
         "E101",
         "E102",
@@ -158,7 +151,7 @@ API
     ...     :param param3: About param3.
     ...     '''
     ...     """
-    >>> docsig(string=string, summary=True, no_ansi=True)
+    >>> docsig(string=string, no_ansi=True)
     0
 
 .. code-block:: python
@@ -172,7 +165,7 @@ API
     ...     :param param3: About param3.
     ...     '''
     ... """
-    >>> docsig(string=string, summary=True, no_ansi=True)
+    >>> docsig(string=string, no_ansi=True)
     2 in function
         E102: includes parameters that do not exist (params-do-not-exist)
     1
@@ -200,7 +193,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.52.0
+        rev: v0.53.0
         hooks:
           - id: docsig
             args:
@@ -208,4 +201,3 @@ It can be added to your .pre-commit-config.yaml as follows:
               - "--check-dunders"
               - "--check-overridden"
               - "--check-protected"
-              - "--summary"

{docsig-0.52.0 → docsig-0.53.0}/docsig/_config.py

@@ -3,10 +3,10 @@ docsig._config
 ==============
 """
 
+from argparse import SUPPRESS as _SUPPRESS
 from argparse import HelpFormatter as _HelpFormatter
 from pathlib import Path as _Path
 
-import click as _click
 from arcon import ArgumentParser as _ArgumentParser
 
 from ._version import __version__
@@ -18,7 +18,6 @@ class Parser(_ArgumentParser):
     def __init__(self) -> None:
         super().__init__(
             version=__version__,
-            prog=_click.style(__package__, fg="cyan"),
             formatter_class=lambda prog: _HelpFormatter(
                 prog, max_help_position=45
             ),
@@ -109,6 +108,12 @@ class Parser(_ArgumentParser):
             action="store_true",
             help="ignore kwargs prefixed with two asterisks",
         )
+        self.add_argument(
+            "-T",
+            "--ignore-typechecker",
+            action="store_true",
+            help="ignore checking return values",
+        )
         self.add_argument(
             "-I",
             "--include-ignored",
@@ -121,12 +126,6 @@ class Parser(_ArgumentParser):
             action="store_true",
             help="disable ansi output",
         )
-        self.add_argument(
-            "-S",
-            "--summary",
-            action="store_true",
-            help="print a summarised report",
-        )
         self.add_argument(
             "-v",
             "--verbose",
@@ -158,3 +157,11 @@ class Parser(_ArgumentParser):
             metavar="PATTERN",
             help="regular expression of files or dirs to exclude from checks",
         )
+
+        # deprecated
+        self.add_argument(
+            "-S",
+            "--summary",
+            action="store_true",
+            help=_SUPPRESS,
+        )

{docsig-0.52.0 → docsig-0.53.0}/docsig/_core.py

@@ -8,38 +8,36 @@ from __future__ import annotations as _
 from pathlib import Path as _Path
 
 from . import _decorators
-from ._display import Display as _Display
-from ._display import Failure as _Failure
-from ._display import Failures as _Failures
-from ._display import FuncStr as _FuncStr
 from ._module import Function as _Function
 from ._module import Modules as _Modules
 from ._module import Parent as _Parent
+from ._report import Failure as _Failure
+from ._report import Failures as _Failures
 from ._report import Report as _Report
 from ._utils import print_checks as _print_checks
 from .messages import Messages as _Messages
 
 _DEFAULT_EXCLUDES = """\
 (?x)^(
-  |\\.?venv
-  |\\.git
-  |\\.hg
-  |\\.idea
-  |\\.mypy_cache
-  |\\.nox
-  |\\.pytest_cache
-  |\\.svn
-  |\\.tox
-  |\\.vscode
-  |_?build
-  |__pycache__
-  |dist
-  |node_modules
+    |\\.?venv
+    |\\.git
+    |\\.hg
+    |\\.idea
+    |\\.mypy_cache
+    |\\.nox
+    |\\.pytest_cache
+    |\\.svn
+    |\\.tox
+    |\\.vscode
+    |_?build
+    |__pycache__
+    |dist
+    |node_modules
 )$
 """
 
 
-def _run_check(  # pylint: disable=too-many-arguments
+def _run_check(  # pylint: disable=too-many-arguments,too-many-locals
     child: _Parent,
     parent: _Parent,
     check_class: bool,
@@ -50,6 +48,7 @@ def _run_check(  # pylint: disable=too-many-arguments
     check_protected: bool,
     check_property_returns: bool,
     ignore_no_params: bool,
+    ignore_typechecker: bool,
     no_ansi: bool,
     targets: _Messages,
     failures: _Failures,
@@ -67,11 +66,15 @@ def _run_check(  # pylint: disable=too-many-arguments
             and not (child.isdunder and not check_dunders)
             and not (child.docstring.bare and ignore_no_params)
         ):
-            report = _Report(
-                child, targets, child.messages, check_property_returns
+            failure = _Failure(
+                child,
+                targets,
+                child.messages,
+                check_property_returns,
+                ignore_typechecker,
             )
-            if report:
-                failures.append(_Failure(child, _FuncStr(child), report))
+            if failure:
+                failures.append(failure)
 
         if check_nested:
             for func in child:
@@ -86,6 +89,7 @@ def _run_check(  # pylint: disable=too-many-arguments
                     check_protected,
                     check_property_returns,
                     ignore_no_params,
+                    ignore_typechecker,
                     no_ansi,
                     targets,
                     failures,
@@ -104,6 +108,7 @@ def _run_check(  # pylint: disable=too-many-arguments
                 check_protected,
                 check_property_returns,
                 ignore_no_params,
+                ignore_typechecker,
                 no_ansi,
                 targets,
                 failures,
@@ -111,6 +116,7 @@ def _run_check(  # pylint: disable=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,
@@ -128,8 +134,8 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     ignore_no_params: bool = False,
     ignore_args: bool = False,
     ignore_kwargs: bool = False,
+    ignore_typechecker: bool = False,
     no_ansi: bool = False,
-    summary: bool = False,
     verbose: bool = False,
     targets: _Messages | None = None,
     disable: _Messages | None = None,
@@ -163,8 +169,8 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         documented
     :param ignore_args: Ignore args prefixed with an asterisk.
     :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
+    :param ignore_typechecker: Ignore checking return values.
     :param no_ansi: Disable ANSI output.
-    :param summary: Print a summarised report.
     :param verbose: increase output verbosity.
     :param targets: List of errors to target.
     :param disable: List of errors to disable.
@@ -191,7 +197,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         no_ansi=no_ansi,
         verbose=verbose,
     )
-    display = _Display(no_ansi)
+    report = _Report()
     for module in modules:
         for top_level in module:
             if (
@@ -211,16 +217,13 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
                     check_protected,
                     check_property_returns,
                     ignore_no_params,
+                    ignore_typechecker,
                     no_ansi,
                     targets or _Messages(),
                     failures,
                 )
                 if failures:
-                    display[top_level.path].append(failures)
-
-    if summary:
-        display.summarise()
-    else:
-        display.report()
+                    report[top_level.path].append(failures)
 
-    return max(int(bool(display)), modules.retcode)
+    report.print(no_ansi)
+    return max(int(bool(report)), modules.retcode)

{docsig-0.52.0 → docsig-0.53.0}/docsig/_decorators.py

@@ -9,6 +9,7 @@ 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
 
@@ -34,6 +35,28 @@ 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.52.0 → docsig-0.53.0}/docsig/_main.py

@@ -37,8 +37,9 @@ def main() -> str | int:
         ignore_no_params=p.args.ignore_no_params,
         ignore_args=p.args.ignore_args,
         ignore_kwargs=p.args.ignore_kwargs,
+        ignore_typechecker=p.args.ignore_typechecker,
         no_ansi=p.args.no_ansi,
-        summary=p.args.summary,
+        summary=p.args.summary,  # deprecated
         verbose=p.args.verbose,
         targets=p.args.target,
         disable=p.args.disable,

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

@@ -20,6 +20,7 @@ from pathspec.patterns import GitWildMatchPattern as _GitWildMatchPattern
 from ._directives import Comment as _Comment
 from ._directives import Directives as _Directives
 from ._stub import Docstring as _Docstring
+from ._stub import RetType as _RetType
 from ._stub import Signature as _Signature
 from ._utils import pretty_print_error as _pretty_print_error
 from ._utils import vprint as _vprint
@@ -356,7 +357,7 @@ class Function(Parent):
         """Comments, if any, belonging to this function."""
         return self._comments
 
-    def overload(self, rettype: str | None) -> None:
+    def overload(self, rettype: _RetType) -> None:
         """Overload function with new signature return type.
 
         :param rettype: Return type of overloaded signature.

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

@@ -5,11 +5,14 @@ docsig._report
 
 from __future__ import annotations as _
 
+import sys as _sys
 import typing as _t
 
+import click as _click
+
 from ._module import Function as _Function
-from ._stub import RETURN as _RETURN
 from ._stub import Param as _Param
+from ._stub import RetType as _RetType
 from ._utils import almost_equal as _almost_equal
 from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E
@@ -20,21 +23,23 @@ _MIN_MATCH = 0.8
 _MAX_MATCH = 1.0
 
 
-class Report(_t.List[str]):
+class Failure(_t.List[str]):
     """Compile and produce report.
 
     :param func: Function object.
     :param targets: List of errors to target.
     :param disable: List of errors to disable.
     :param check_property_returns: Run return checks on properties.
+    :param ignore_typechecker: Ignore checking return values.
     """
 
-    def __init__(
+    def __init__(  # pylint: disable=too-many-arguments
         self,
         func: _Function,
         targets: _Messages,
         disable: _Messages,
         check_property_returns: bool,
+        ignore_typechecker: bool,
     ) -> None:
         super().__init__()
         self._disable = list(disable)
@@ -47,8 +52,14 @@ class Report(_t.List[str]):
 
         self._errors = _Messages()
         self._func = func
-        self._no_prop_return = func.isproperty and not check_property_returns
-        self._no_returns = func.isinit or self._no_prop_return
+        self._no_prop_return = (
+            func.isproperty
+            and not check_property_returns
+            and not ignore_typechecker
+        )
+        self._no_returns = (
+            func.isinit or self._no_prop_return or ignore_typechecker
+        )
         self._invalid_directive()
         self._invalid_directive_options()
         self._missing_class_docstring()
@@ -116,7 +127,7 @@ class Report(_t.List[str]):
     def _extra_return(self) -> None:
         if (
             self._func.docstring.returns
-            and self._func.signature.rettype == "None"
+            and self._func.signature.rettype == _RetType.NONE
             and not self._no_returns
         ):
             self._add(_E[104])
@@ -126,8 +137,11 @@ class Report(_t.List[str]):
             self._add(_E[108], hint=True)
 
     def _return_not_typed(self) -> None:
-        if self._func.signature.rettype is None and not self._no_returns:
-            self._add(_E[109])
+        if (
+            self._func.signature.rettype == _RetType.UNTYPED
+            and not self._no_returns
+        ):
+            self._add(_E[109], hint=True)
 
     def _missing_return(self) -> None:
         hint = False
@@ -137,7 +151,7 @@ class Report(_t.List[str]):
             and not self._no_returns
         ):
             docstring = self._func.docstring.string
-            if docstring is not None and _RETURN in docstring:
+            if docstring is not None and "return" in docstring:
                 hint = True
 
             self._add(_E[105], hint=hint)
@@ -188,11 +202,43 @@ class Report(_t.List[str]):
                         option=rule.description,
                     )
 
-    def get_report(self, prefix: str = "") -> str:
-        """Get report compiled as a string.
+    @property
+    def func(self) -> _Function:
+        """Function this failure belongs to."""
+        return self._func
+
+
+class Failures(_t.List[Failure]):
+    """Sequence of failed functions."""
 
-        :param prefix: Prefix report.
-        :return: Current report.
+
+class Report(_t.Dict[str, _t.List[Failures]]):
+    """Collect and display report."""
+
+    def __getitem__(self, key: str) -> list[Failures]:
+        if key not in super().__iter__():
+            super().__setitem__(key, [])
+
+        return super().__getitem__(key)
+
+    def print(self, no_ansi: bool) -> None:
+        """Display report summary if any checks have failed.
+
+        :param no_ansi: Disable ANSI output.
         """
-        report = f"\n{prefix}".join(self)
-        return f"{report}\n"
+        for key, value in self.items():
+            for failures in value:
+                for failure in failures:
+                    header = f"{key}{failure.func.lineno}"
+                    function = failure.func.name
+                    if failure.func.parent.name:
+                        function = f"{failure.func.parent.name}.{function}"
+
+                    header += f" in {function}"
+                    _click.echo(
+                        "{}\n    {}".format(
+                            _click.style(header, fg="magenta"),
+                            "\n    ".join(failure),
+                        ),
+                        color=not no_ansi and _sys.stdout.isatty(),
+                    )

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

@@ -9,16 +9,11 @@ import re as _re
 import textwrap as _textwrap
 import typing as _t
 from collections import Counter as _Counter
+from enum import Enum as _Enum
 
 import astroid as _ast
 import sphinx.ext.napoleon as _s
 
-PARAM = "param"
-KEYWORD = "keyword"
-KEY = "key"
-RETURN = "return"
-ARG = "arg"
-
 
 # noinspection PyTypeChecker
 class _GoogleDocstring(str):
@@ -51,10 +46,66 @@ class _RawDocstring(str):
         )
 
 
+class RetType(_Enum):
+    """Defines the possible types of a return annotation."""
+
+    NONE = 1
+    SOME = 2
+    UNTYPED = 3
+
+    @classmethod
+    def from_ast(cls, returns: _ast.NodeNG | None) -> RetType:
+        """Construct a return type object from an AST node.
+
+        :param returns: Ast node or None.
+        :return: Constructed return type.
+        """
+        if isinstance(returns, _ast.Const) and returns.value is None:
+            return cls.NONE
+
+        if isinstance(
+            returns,
+            (
+                _ast.Const,
+                _ast.Name,
+                _ast.Attribute,
+                _ast.Subscript,
+                _ast.BinOp,
+            ),
+        ):
+            return cls.SOME
+
+        return cls.UNTYPED
+
+
+class DocType(_Enum):
+    """Defines the possible types of a docstring."""
+
+    PARAM = 1
+    ARG = 2
+    KWARG = 3
+    UNKNOWN = 4
+
+    @classmethod
+    def from_str(cls, docstring: str) -> DocType:
+        """Construct a doc type object from a docstring.
+
+        :param docstring: Docstring string.
+        :return: Constructed doc type.
+        """
+        try:
+            return cls[docstring.upper()]
+        except KeyError:
+            if docstring in ("key", "keyword"):
+                return cls.KWARG
+
+        return cls.UNKNOWN
+
+
 class Param(_t.NamedTuple):
     """A tuple of param types and their names."""
 
-    kind: str = PARAM
+    kind: DocType = DocType.PARAM
     name: str | None = None
     description: str | None = None
     indent: int = 0
@@ -64,7 +115,7 @@ class Param(_t.NamedTuple):
             return False
 
         args = self, other
-        return all(i.kind == KEY for i in args) or (
+        return all(i.kind == DocType.KWARG for i in args) or (
             self.name == other.name and all(i.name is not None for i in args)
         )
 
@@ -79,7 +130,6 @@ class Param(_t.NamedTuple):
 
 class _Matches(_t.List[Param]):
     _pattern = _re.compile(":(.*?):")
-    _normalize = {KEYWORD: KEY}
 
     def __init__(self, string: str) -> None:
         super().__init__()
@@ -90,9 +140,7 @@ class _Matches(_t.List[Param]):
                 name = description = None
                 kinds = match[0].split()
                 if kinds:
-                    kind = kinds[0]
-                    for substring, replace in self._normalize.items():
-                        kind = kind.replace(substring, replace)
+                    kind = DocType.from_str(kinds[0])
 
                     if len(kinds) > 1:
                         name = kinds[1]
@@ -121,12 +169,12 @@ class _Params(_t.List[Param]):
     # pylint: disable=too-many-boolean-expressions
     def append(self, value: Param) -> None:
         if not value.isprotected and (
-            value.kind == PARAM
-            or (value.kind == ARG and not self._ignore_args)
+            value.kind == DocType.PARAM
+            or (value.kind == DocType.ARG and not self._ignore_args)
             or (
-                value.kind == KEY
+                value.kind == DocType.KWARG
                 and not self._ignore_kwargs
-                and not any(i.kind == KEY for i in self)
+                and not any(i.kind == DocType.KWARG for i in self)
             )
         ):
             super().append(value)
@@ -203,45 +251,19 @@ class Signature(_Stub):
             for a in [
                 *arguments.posonlyargs,
                 *arguments.args,
-                Param(ARG, name=arguments.vararg),
+                Param(DocType.ARG, name=arguments.vararg),
                 *arguments.kwonlyargs,
-                Param(KEY, name=arguments.kwarg),
+                Param(DocType.KWARG, name=arguments.kwarg),
             ]
             if a is not None and a.name
         ]:
             self.args.append(i)
 
-        self._rettype = (
-            returns if isinstance(returns, str) else self._get_rettype(returns)
-        )
-        self._returns = str(self._rettype) != "None"
-
-    def _get_rettype(self, returns: _ast.NodeNG | None) -> str | None:
-        if isinstance(returns, _ast.Name):
-            return returns.name
-
-        if isinstance(returns, _ast.Attribute):
-            return returns.attrname
-
-        if isinstance(returns, _ast.Const):
-            return str(returns.value)
-
-        if isinstance(returns, _ast.Subscript):
-            return "{}[{}]".format(
-                self._get_rettype(returns.value),
-                self._get_rettype(returns.slice),
-            )
-
-        if isinstance(returns, _ast.BinOp):
-            return "{} | {}".format(
-                self._get_rettype(returns.left),
-                self._get_rettype(returns.right),
-            )
-
-        return None
+        self._rettype = RetType.from_ast(returns)
+        self._returns = self._rettype == RetType.SOME
 
     @property
-    def rettype(self) -> str | None:
+    def rettype(self) -> RetType:
         """Function's return value.
 
         If a function is typed to return None, return str(None). If no
@@ -249,15 +271,13 @@ class Signature(_Stub):
         """
         return self._rettype
 
-    def overload(self, rettype: str | None) -> None:
+    def overload(self, rettype: RetType) -> None:
         """Overload signature with a ret type.
 
         :param rettype: Return type of overloaded signature.
         """
-        self._rettype = (
-            rettype if isinstance(rettype, str) else self._get_rettype(rettype)
-        )
-        self._returns = str(rettype) != "None"
+        self._rettype = rettype
+        self._returns = rettype != RetType.NONE
 
 
 class Docstring(_Stub):

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

{docsig-0.52.0 → docsig-0.53.0}/docsig/messages.py

@@ -159,6 +159,7 @@ E = MessageMap(
             "E109",
             "cannot determine whether a return statement should exist or not",
             "confirm-return-needed",
+            "annotate type to indicate whether return documentation needed",
         ),
         110: Message(
             "E110",

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

@@ -16,6 +16,9 @@ exclude = '''
 '''
 line-length = 79
 
+[tool.codespell]
+ignore-words-list = "astroid"
+
 [tool.coverage.report]
 exclude_lines = [
   "@_t.overload"
@@ -31,7 +34,6 @@ omit = [
 [tool.docsig]
 check-class = true
 check-protected-class-methods = true
-summary = true
 
 [tool.isort]
 ensure_newline_before_comments = true
@@ -63,10 +65,9 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.52.0"
+version = "0.53.0"
 
 [tool.poetry.dependencies]
-Pygments = "^2.13.0"
 Sphinx = "^7.0.0"
 arcon = ">=0.4.0"
 astroid = "^3.0.1"
@@ -82,11 +83,12 @@ pre-commit = "^3.3.3"
 pyaud = "^7.5.0"
 pytest-randomly = "^3.13.0"
 pytest-sugar = "^1.0.0"
-pytest-xdist = "^3.5.0"
+pytest-xdist = "^3.6.1"
 restview = "^3.0.0"
 sphinx-immaterial = "^0.11.9"
 sphinx-toolbox = "^3.5.0"
 templatest = "^0.10.1"
+tox = "^4.15.0"
 
 [tool.poetry.scripts]
 docsig = "docsig.__main__:main"
@@ -110,6 +112,7 @@ exclude = '''
 (?x)^(
   | docs\/conf\.py
   | whitelist\.py
+  | scripts\/update_readme\.py
 )$
 '''
 

docsig-0.52.0/docsig/_display.py

@@ -1,232 +0,0 @@
-"""
-docsig._display
-===============
-"""
-
-from __future__ import annotations as _
-
-import sys as _sys
-import typing as _t
-from collections import UserString as _UserString
-
-import click as _click
-from pygments import highlight as _highlight
-from pygments.formatters.terminal256 import (
-    Terminal256Formatter as _Terminal256Formatter,
-)
-
-# noinspection PyUnresolvedReferences
-from pygments.lexers.python import PythonLexer as _PythonLexer
-
-from ._module import Function as _Function
-from ._report import Report as _Report
-from ._stub import ARG as _ARG
-from ._stub import KEY as _KEY
-from ._stub import Param as _Param
-
-TAB = "    "
-
-
-def syntax(obj: _t.Any) -> str:
-    """Get code representation with syntax highlighting.
-
-    :param obj: Any object, represented as ``__str__``.
-    :return: Colored string or string as was supplied.
-    """
-    return _highlight(
-        obj, _PythonLexer(), _Terminal256Formatter(style="monokai")
-    ).strip()
-
-
-class FuncStr(_UserString):
-    """String representation for function.
-
-    :param func: Represents a function with signature and docstring
-        parameters.
-    """
-
-    CHECK = "\u2713"
-    CROSS = "\u2716"
-    TRIPLE_QUOTES = '"""'
-
-    def __init__(self, func: _Function) -> None:
-        super().__init__(func.name)
-        self._parent_name = func.parent.name
-        self._isinit = func.isinit
-        self.data = ""
-        self._is_string = func.docstring.string is not None
-        if self._isinit:
-            self.data += TAB
-
-        self.data += syntax(f"def {func.name}(")
-        if self._is_string:
-            self._docstring = syntax(f"{TAB}{self.TRIPLE_QUOTES}")
-        else:
-            self._docstring = f"{TAB}{_click.style('...', fg='red')}\n"
-
-        self._mark = _click.style(self.CHECK, fg="green")
-        for index in range(len(func)):
-            arg = func.signature.args.get(index)
-            doc = func.docstring.args.get(index)
-            self.add_param(arg, doc, arg != doc)
-            if index + 1 != len(func):
-                self.add_comma()
-
-        self.set_mark()
-        if func.docstring.returns and func.signature.returns:
-            self.add_return()
-        elif (
-            func.docstring.returns
-            and not func.signature.returns
-            or func.signature.returns
-            and not func.docstring.returns
-        ):
-            self.add_return(failed=True)
-
-        self.close_sig(func.signature.rettype)
-        self.close_docstring()
-        self.render()
-
-    def _cat_docstring(self, string: str) -> None:
-        if self._is_string:
-            self._docstring += string
-
-    def set_mark(self, failed: bool = False) -> None:
-        """Set mark to a cross or a check.
-
-        :param failed: Boolean to test that check failed.
-        """
-        self._mark = (
-            _click.style(self.CROSS, fg="red")
-            if failed
-            else _click.style(self.CHECK, fg="green")
-        )
-
-    def add_param(
-        self, sig: _Param, doc: _Param, failed: bool = False
-    ) -> None:
-        """Add parameters to docstring.
-
-        :param sig: Signature argument.
-        :param doc: Docstring argument.
-        :param failed: Boolean to test that check failed.
-        """
-        self.set_mark(failed)
-        sig_name = sig.name
-        if sig.kind == _KEY:
-            sig_name = f"**{sig_name}"
-
-        if sig.kind == _ARG:
-            sig_name = f"*{sig_name}"
-
-        self.data += f"{self._mark}{sig_name}"
-        doc_name = doc.name
-        if doc.kind == _KEY:
-            doc_name = "(**)"
-
-        self._cat_docstring(f"\n{TAB}:{doc.kind} {doc_name}: {self._mark}")
-
-    def add_return(self, failed: bool = False) -> None:
-        """Add return statement to docstring.
-
-        :param failed: Boolean to test that check failed.
-        """
-        self.set_mark(failed)
-        self._cat_docstring(f"\n{TAB}:return: {self._mark}")
-
-    def close_sig(self, arg: str | None) -> None:
-        """Close function signature.
-
-        :param arg: Signature argument.
-        """
-        if arg is not None:
-            self.data += f"{syntax(') -> ')}{self._mark}{arg}{syntax(':')}"
-        else:
-            self.data += "{}{}{}".format(
-                syntax(")"),
-                _click.style("?", fg="red"),
-                syntax(":"),
-            )
-
-    def add_comma(self) -> None:
-        """Add comma between parenthesis."""
-        self.data += syntax(", ")
-
-    def close_docstring(self) -> None:
-        """Close docstring."""
-        self._cat_docstring(f"\n{TAB}{syntax(self.TRIPLE_QUOTES)}\n")
-
-    def render(self) -> None:
-        """Render final string by adding docstring to function."""
-        if self._isinit:
-            self.data = (
-                syntax(f"class {self._parent_name}:")
-                + f"\n{self._docstring}"
-                + f"\n{self.data}\n"
-            )
-        else:
-            self.data += f"\n{self._docstring}"
-
-
-class Failure(_t.NamedTuple):
-    """Failed function data."""
-
-    func: _Function
-    func_str: FuncStr
-    report: _Report
-
-
-class Failures(_t.List[Failure]):
-    """Sequence of failed functions."""
-
-
-class Display(_t.Dict[str, _t.List[Failures]]):
-    """Collect and display report.
-
-    :param no_ansi: Disable ANSI output.
-    """
-
-    def __init__(self, no_ansi: bool = False) -> None:
-        super().__init__()
-        self._ansi = not no_ansi and _sys.stdout.isatty()
-
-    def __getitem__(self, key: str) -> list[Failures]:
-        if key not in super().__iter__():
-            super().__setitem__(key, [])
-
-        return super().__getitem__(key)
-
-    def report(self) -> None:
-        """Display report if any checks have failed."""
-        for key, value in self.items():
-            for failures in value:
-                for failure in failures:
-                    header = f"{key}{failure.func.lineno}"
-                    if failure.func.parent.name:
-                        header += f" in {failure.func.parent.name}"
-
-                    _click.echo(
-                        _click.style(header, fg="magenta"), color=self._ansi
-                    )
-                    _click.echo(len(header) * "-", color=self._ansi)
-                    _click.echo(failure.func_str, color=self._ansi)
-                    _click.echo(failure.report.get_report(), color=self._ansi)
-
-    def summarise(self) -> None:
-        """Display report summary if any checks have failed."""
-        for key, value in self.items():
-            for failures in value:
-                for failure in failures:
-                    header = f"{key}{failure.func.lineno}"
-                    function = failure.func.name
-                    if failure.func.parent.name:
-                        function = f"{failure.func.parent.name}.{function}"
-
-                    header += f" in {function}"
-                    _click.echo(
-                        "{}\n    {}".format(
-                            _click.style(header, fg="magenta"),
-                            failure.report.get_report("    ").strip(),
-                        ),
-                        color=self._ansi,
-                    )