docsig 0.46.0__tar.gz → 0.48.0__tar.gz

{docsig-0.46.0 → docsig-0.48.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.46.0
+Version: 0.48.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -22,7 +22,6 @@ Requires-Dist: Sphinx (>=7.0.0,<8.0.0)
 Requires-Dist: arcon (>=0.4.0)
 Requires-Dist: astroid (>=3.0.1,<4.0.0)
 Requires-Dist: object-colors (>=2.1.0,<3.0.0)
-Requires-Dist: typing-extensions (>=4.8.0,<5.0.0)
 Project-URL: Documentation, https://docsig.readthedocs.io/en/latest
 Project-URL: Repository, https://github.com/jshwi/docsig
 Description-Content-Type: text/x-rst
@@ -106,8 +105,8 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
-                             [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
+    usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a]
+                             [-k] [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
                              [path [path ...]]
 
     Check signature params for proper documentation
@@ -125,6 +124,7 @@ Commandline
       -D, --check-dunders                  check dunder methods
       -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
@@ -138,7 +138,7 @@ Commandline
       -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 EXCLUDE, --exclude EXCLUDE        regular expression of files or dirs to exclude
+      -e PATTERN, --exclude PATTERN        regular expression of files or dirs to exclude
                                            from checks
 
 Options can also be configured with the pyproject.toml file
@@ -181,7 +181,7 @@ API
     ...     :param param3: About param3.
     ...     '''
     ...     """
-    >>> docsig(string=string)
+    >>> docsig(string=string, no_ansi=True)
     0
 
 .. code-block:: python
@@ -195,7 +195,7 @@ API
     ...     :param param3: About param3.
     ...     '''
     ... """
-    >>> docsig(string=string)
+    >>> docsig(string=string, no_ansi=True)
     2
     -
     def function(✓param1, ✓param2, ✖None) -> ✓None:
@@ -232,7 +232,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.46.0
+        rev: v0.48.0
         hooks:
           - id: docsig
             args:

{docsig-0.46.0 → docsig-0.48.0}/README.rst

@@ -77,8 +77,8 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
-                             [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
+    usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a]
+                             [-k] [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
                              [path [path ...]]
 
     Check signature params for proper documentation
@@ -96,6 +96,7 @@ Commandline
       -D, --check-dunders                  check dunder methods
       -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
@@ -109,7 +110,7 @@ Commandline
       -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 EXCLUDE, --exclude EXCLUDE        regular expression of files or dirs to exclude
+      -e PATTERN, --exclude PATTERN        regular expression of files or dirs to exclude
                                            from checks
 
 Options can also be configured with the pyproject.toml file
@@ -152,7 +153,7 @@ API
     ...     :param param3: About param3.
     ...     '''
     ...     """
-    >>> docsig(string=string)
+    >>> docsig(string=string, no_ansi=True)
     0
 
 .. code-block:: python
@@ -166,7 +167,7 @@ API
     ...     :param param3: About param3.
     ...     '''
     ... """
-    >>> docsig(string=string)
+    >>> docsig(string=string, no_ansi=True)
     2
     -
     def function(✓param1, ✓param2, ✖None) -> ✓None:
@@ -203,7 +204,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.46.0
+        rev: v0.48.0
         hooks:
           - id: docsig
             args:

{docsig-0.46.0 → docsig-0.48.0}/docsig/_config.py

@@ -67,6 +67,12 @@ class Parser(_ArgumentParser):
             action="store_true",
             help="check public methods belonging to protected classes",
         )
+        self.add_argument(
+            "-N",
+            "--check-nested",
+            action="store_true",
+            help="check nested functions and classes",
+        )
         self.add_argument(
             "-o",
             "--check-overridden",
@@ -143,5 +149,6 @@ class Parser(_ArgumentParser):
         self.add_argument(
             "-e",
             "--exclude",
+            metavar="PATTERN",
             help="regular expression of files or dirs to exclude from checks",
         )

{docsig-0.46.0 → docsig-0.48.0}/docsig/_core.py

@@ -13,9 +13,10 @@ from ._display import Failure as _Failure
 from ._display import Failures as _Failures
 from ._display import FuncStr as _FuncStr
 from ._message import Message as _Message
+from ._module import Function as _Function
 from ._module import Modules as _Modules
 from ._module import Parent as _Parent
-from ._report import generate_report as _generate_report
+from ._report import Report as _Report
 from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E
 
@@ -45,40 +46,75 @@ def _print_checks() -> None:
 
 
 def _run_check(  # pylint: disable=too-many-arguments
+    child: _Parent,
     parent: _Parent,
     check_class: bool,
     check_class_constructor: bool,
     check_dunders: bool,
+    check_nested: bool,
     check_overridden: bool,
     check_protected: bool,
     check_property_returns: bool,
     ignore_no_params: bool,
     no_ansi: bool,
     targets: list[_Message],
-) -> _Failures:
-    failures = _Failures()
-    for func in parent:
-        if not (func.isoverridden and not check_overridden) and (
-            not (func.isprotected and not check_protected)
+    failures: _Failures,
+) -> None:
+    if isinstance(child, _Function):
+        if not (child.isoverridden and not check_overridden) and (
+            not (child.isprotected and not check_protected)
             and not (
-                func.isinit
+                child.isinit
                 and not (
                     (check_class or check_class_constructor)
                     and not (parent.isprotected and not check_protected)
                 )
             )
-            and not (func.isdunder and not check_dunders)
-            and not (func.docstring.bare and ignore_no_params)
+            and not (child.isdunder and not check_dunders)
+            and not (child.docstring.bare and ignore_no_params)
         ):
-            report = _generate_report(
-                func, targets, func.disabled, check_property_returns
+            report = _Report(
+                child, targets, child.disabled, check_property_returns
             )
             if report:
                 failures.append(
-                    _Failure(func, _FuncStr(func, no_ansi), report)
+                    _Failure(child, _FuncStr(child, no_ansi), report)
                 )
 
-    return failures
+        if check_nested:
+            for func in child:
+                _run_check(
+                    func,
+                    child,
+                    check_class,
+                    check_class_constructor,
+                    check_dunders,
+                    check_nested,
+                    check_overridden,
+                    check_protected,
+                    check_property_returns,
+                    ignore_no_params,
+                    no_ansi,
+                    targets,
+                    failures,
+                )
+    else:
+        for func in child:
+            _run_check(
+                func,
+                child,
+                check_class,
+                check_class_constructor,
+                check_dunders,
+                check_nested,
+                check_overridden,
+                check_protected,
+                check_property_returns,
+                ignore_no_params,
+                no_ansi,
+                targets,
+                failures,
+            )
 
 
 @_decorators.parse_msgs
@@ -91,6 +127,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     check_class_constructor: bool = False,
     check_dunders: bool = False,
     check_protected_class_methods: bool = False,
+    check_nested: bool = False,
     check_overridden: bool = False,
     check_protected: bool = False,
     check_property_returns: bool = False,
@@ -122,6 +159,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     :param check_dunders: Check dunder methods
     :param check_protected_class_methods: Check public methods belonging
         to protected classes.
+    :param check_nested: Check nested functions and classes.
     :param check_overridden: Check overridden methods
     :param check_protected: Check protected functions and classes.
     :param check_property_returns: Run return checks on properties.
@@ -163,17 +201,21 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
                 or check_protected
                 or check_protected_class_methods
             ):
-                failures = _run_check(
+                failures = _Failures()
+                _run_check(
                     top_level,
+                    module,
                     check_class,
                     check_class_constructor,
                     check_dunders,
+                    check_nested,
                     check_overridden,
                     check_protected,
                     check_property_returns,
                     ignore_no_params,
                     no_ansi,
                     targets or [],
+                    failures,
                 )
                 if failures:
                     display[top_level.path].append(failures)

{docsig-0.46.0 → docsig-0.48.0}/docsig/_decorators.py

@@ -59,7 +59,7 @@ def validate_args(func: _FuncType) -> _WrappedFuncType:
             for message in kwargs.get("targets") or []:
                 if not message.isknown:
                     stderr.append(
-                        f"unknown option to target '{message.description}'",
+                        f"unknown option to target '{message.description}'"
                     )
 
             if kwargs.get("check_class") and kwargs.get(

{docsig-0.46.0 → docsig-0.48.0}/docsig/_directives.py

@@ -10,8 +10,6 @@ import tokenize as _tokenize
 import typing as _t
 from io import StringIO as _StringIO
 
-from typing_extensions import Self as _Self
-
 from ._message import Message as _Message
 from .messages import E as _E
 
@@ -96,7 +94,7 @@ class Directive:
         return self._kind == self._valid_kinds[1]
 
     @classmethod
-    def parse(cls, comment: str, col: int) -> _Self | None:
+    def parse(cls, comment: str, col: int) -> Directive | None:
         """Parse string into directive object if possible.
 
         :param comment: Comment to parse.

{docsig-0.46.0 → docsig-0.48.0}/docsig/_display.py

@@ -17,11 +17,11 @@ from pygments.formatters.terminal256 import (
 # noinspection PyUnresolvedReferences
 from pygments.lexers.python import PythonLexer as _PythonLexer
 
-from ._function import ARG as _ARG
-from ._function import KEY as _KEY
-from ._function import Function as _Function
-from ._function import Param as _Param
+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
 
 color = _Color()
 
@@ -209,15 +209,7 @@ class Failures(_t.List[Failure]):
     """Sequence of failed functions."""
 
 
-class _DisplaySequence(_t.Dict[str, _t.List[Failures]]):
-    def __getitem__(self, key: str) -> list[Failures]:
-        if key not in super().__iter__():
-            super().__setitem__(key, [])
-
-        return super().__getitem__(key)
-
-
-class Display(_DisplaySequence):
+class Display(_t.Dict[str, _t.List[Failures]]):
     """Collect and display report.
 
     :param no_ansi: Disable ANSI output.
@@ -227,6 +219,12 @@ class Display(_DisplaySequence):
         super().__init__()
         self._ansi = _ANSI(no_ansi)
 
+    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():
@@ -253,8 +251,8 @@ class Display(_DisplaySequence):
 
                     header += f" in {function}"
                     print(
-                        "{}\n\t{}".format(
+                        "{}\n    {}".format(
                             self._ansi.color(header, color.magenta),
-                            failure.report.get_report("\t").strip(),
+                            failure.report.get_report("    ").strip(),
                         )
                     )

docsig-0.48.0/docsig/_main.py

@@ -0,0 +1,45 @@
+"""
+docsig._main
+============
+
+Contains package entry point.
+"""
+
+from __future__ import annotations as _
+
+from ._config import Parser as _Parser
+from ._core import docsig as _docsig
+from ._hooks import pretty_print_error as _pretty_print_error
+
+
+def main() -> str | int:
+    """Main function for package.
+
+    Collect config and arguments for the commandline.
+
+    :return: Exit status for whether test failed or not.
+    """
+    p = _Parser()
+    _pretty_print_error()
+    return _docsig(
+        *p.args.path,
+        string=p.args.string,
+        list_checks=p.args.list_checks,
+        check_class=p.args.check_class,
+        check_class_constructor=p.args.check_class_constructor,
+        check_dunders=p.args.check_dunders,
+        check_protected_class_methods=p.args.check_protected_class_methods,
+        check_nested=p.args.check_nested,
+        check_overridden=p.args.check_overridden,
+        check_protected=p.args.check_protected,
+        check_property_returns=p.args.check_property_returns,
+        ignore_no_params=p.args.ignore_no_params,
+        ignore_args=p.args.ignore_args,
+        ignore_kwargs=p.args.ignore_kwargs,
+        no_ansi=p.args.no_ansi,
+        summary=p.args.summary,
+        verbose=p.args.verbose,
+        targets=p.args.target,
+        disable=p.args.disable,
+        exclude=p.args.exclude,
+    )