docsig 0.45.0__tar.gz → 0.47.0__tar.gz

{docsig-0.45.0 → docsig-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.45.0
+Version: 0.47.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -19,7 +19,7 @@ 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.3.1)
+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)
@@ -106,8 +106,8 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-v] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
-                             [-n] [-S] [-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
@@ -117,7 +117,7 @@ Commandline
 
     optional arguments:
       -h, --help                           show this help message and exit
-      -v, --version                        show program's version number and exit
+      -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
@@ -125,6 +125,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
@@ -134,6 +135,7 @@ Commandline
       -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
       -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
@@ -231,7 +233,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.45.0
+        rev: v0.47.0
         hooks:
           - id: docsig
             args:

{docsig-0.45.0 → docsig-0.47.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] [-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
@@ -88,7 +88,7 @@ Commandline
 
     optional arguments:
       -h, --help                           show this help message and exit
-      -v, --version                        show program's version number and exit
+      -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
@@ -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
@@ -105,6 +106,7 @@ Commandline
       -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
       -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
@@ -202,7 +204,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.45.0
+        rev: v0.47.0
         hooks:
           - id: docsig
             args:

{docsig-0.45.0 → docsig-0.47.0}/docsig/_config.py

@@ -23,6 +23,7 @@ class Parser(_ArgumentParser):
                 prog, max_help_position=45
             ),
             description="Check signature params for proper documentation",
+            version_short_form="-V",
         )
         self._add_arguments()
         self.args = self.parse_args()
@@ -66,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",
@@ -114,6 +121,12 @@ class Parser(_ArgumentParser):
             action="store_true",
             help="print a summarised report",
         )
+        self.add_argument(
+            "-v",
+            "--verbose",
+            action="store_true",
+            help="increase output verbosity",
+        )
         self.add_argument(
             "-s",
             "--string",

{docsig-0.45.0 → docsig-0.47.0}/docsig/_core.py

@@ -13,6 +13,7 @@ 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
@@ -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
+                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,
@@ -99,6 +136,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     ignore_kwargs: bool = False,
     no_ansi: bool = False,
     summary: bool = False,
+    verbose: bool = False,
     targets: list[_Message] | None = None,
     disable: list[_Message] | None = None,
     exclude: str | None = None,
@@ -121,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.
@@ -130,6 +169,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
     :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.
     :param exclude: Regular expression of files and dirs to exclude from
@@ -151,6 +191,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         ignore_args=ignore_args,
         ignore_kwargs=ignore_kwargs,
         check_class_constructor=check_class_constructor,
+        verbose=verbose,
     )
     display = _Display(no_ansi)
     for module in modules:
@@ -160,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.45.0 → docsig-0.47.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()
 

{docsig-0.45.0 → docsig-0.47.0}/docsig/_main.py

@@ -31,6 +31,7 @@ def main() -> str | int:
         check_protected_class_methods=(
             parser.args.check_protected_class_methods
         ),
+        check_nested=parser.args.check_nested,
         check_overridden=parser.args.check_overridden,
         check_protected=parser.args.check_protected,
         check_property_returns=parser.args.check_property_returns,
@@ -39,6 +40,7 @@ def main() -> str | int:
         ignore_kwargs=parser.args.ignore_kwargs,
         no_ansi=parser.args.no_ansi,
         summary=parser.args.summary,
+        verbose=parser.args.verbose,
         targets=parser.args.target,
         disable=parser.args.disable,
         exclude=parser.args.exclude,

docsig-0.47.0/docsig/_module.py

@@ -0,0 +1,428 @@
+"""
+docsig._module
+==============
+"""
+
+from __future__ import annotations as _
+
+import re as _re
+import typing as _t
+from pathlib import Path as _Path
+
+import astroid as _ast
+from astroid import AstroidSyntaxError as _AstroidSyntaxError
+
+from ._directives import Directive as _Directive
+from ._directives import Directives as _Directives
+from ._message import Message as _Message
+from ._stub import Docstring as _Docstring
+from ._stub import Signature as _Signature
+from ._utils import vprint as _vprint
+
+_FILE_INFO = "{path}: {msg}"
+
+
+class Parent(_t.List["Parent"]):
+    """Represents an object that contains functions or methods.
+
+    :param node: Parent's abstract syntax tree.
+    :param directives: Data for directives and, subsequently, total of
+        errors which are excluded from function checks.
+    :param path: Path to base path representation on.
+    :param ignore_args: Ignore args prefixed with an asterisk.
+    :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
+    :param check_class_constructor: Check the class constructor's
+        docstring. Otherwise, expect the constructor's documentation to
+        be on the class level docstring.
+    """
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        node: _ast.Module | _ast.ClassDef | _ast.FunctionDef,
+        directives: _Directives,
+        path: _Path | None = None,
+        ignore_args: bool = False,
+        ignore_kwargs: bool = False,
+        check_class_constructor: bool = False,
+    ) -> None:
+        super().__init__()
+        self._name = node.name
+        self._path = f"{path}:" if path is not None else ""
+        overloads: list[str] = []
+        returns = None
+        self._parse_ast(
+            node,
+            directives,
+            path,
+            ignore_args,
+            ignore_kwargs,
+            check_class_constructor,
+            overloads,
+            returns,
+        )
+
+    def _parse_ast(  # pylint: disable=protected-access,too-many-arguments
+        self,
+        node,
+        directives,
+        path,
+        ignore_args,
+        ignore_kwargs,
+        check_class_constructor,
+        overloads,
+        returns,
+    ) -> None:
+        parent_comments, parent_disabled = directives.get(
+            node.lineno, ([], [])
+        )
+        if hasattr(node, "body"):
+            for subnode in node.body:
+                comments, disabled = directives.get(subnode.lineno, ([], []))
+                comments.extend(parent_comments)
+                disabled.extend(parent_disabled)
+                if isinstance(subnode, _ast.FunctionDef):
+                    func = Function(
+                        subnode,
+                        comments,
+                        directives,
+                        disabled,
+                        path,
+                        ignore_args,
+                        ignore_kwargs,
+                        check_class_constructor,
+                    )
+                    if func.isoverloaded:
+                        overloads.append(func.name)
+                        returns = func.signature.rettype
+                    else:
+                        if func.name in overloads:
+                            subnode.returns = returns
+                            # noinspection PyProtectedMember
+                            func._signature._rettype = (
+                                returns
+                                if isinstance(returns, str)
+                                else func._signature._get_rettype(returns)
+                            )
+                            # noinspection PyProtectedMember
+                            func._signature._returns = (
+                                str(func._signature._rettype) != "None"
+                            )
+
+                        self.append(func)
+                elif isinstance(subnode, _ast.ClassDef):
+                    self.append(
+                        Parent(
+                            subnode,
+                            directives,
+                            path,
+                            ignore_args,
+                            ignore_kwargs,
+                            check_class_constructor,
+                        )
+                    )
+                else:
+                    self._parse_ast(
+                        subnode,
+                        directives,
+                        path,
+                        ignore_args,
+                        ignore_kwargs,
+                        check_class_constructor,
+                        overloads,
+                        returns,
+                    )
+
+    @property
+    def path(self) -> str:
+        """Representation of path to parent."""
+        return self._path
+
+    @property
+    def isprotected(self) -> bool:
+        """Boolean value for whether class is protected."""
+        return self._name.startswith("_")
+
+
+class Function(Parent):
+    """Represents a function with signature and docstring parameters.
+
+    :param node: Function's abstract syntax tree.
+    :param comments: Comments in list form containing directives.
+    :param directives: Directive, if any, belonging to this function.
+    :param disabled: List of disabled checks specific to this function.
+    :param path: Path to base path representation on.
+    :param ignore_args: Ignore args prefixed with an asterisk.
+    :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
+    :param check_class_constructor: If the function is the class
+        constructor, use its own docstring. Otherwise, use the class
+        level docstring for the constructor function.
+    """
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        node: _ast.FunctionDef,
+        comments: _t.List[_Directive],
+        directives: _Directives,
+        disabled: list[_Message],
+        path: _Path | None = None,
+        ignore_args: bool = False,
+        ignore_kwargs: bool = False,
+        check_class_constructor: bool = False,
+    ) -> None:
+        super().__init__(
+            node,
+            directives,
+            path,
+            ignore_args,
+            ignore_kwargs,
+            check_class_constructor,
+        )
+        self._node = node
+        self._directives = comments
+        self._disabled = disabled
+        self._parent = node.parent.frame()
+        self._signature = _Signature(
+            node.args,
+            node.returns,
+            self.ismethod,
+            self.isstaticmethod,
+            ignore_args,
+            ignore_kwargs,
+        )
+        if self.isinit and not check_class_constructor:
+            # docstring for __init__ is expected on the class docstring
+            relevant_doc_node = self._parent.doc_node
+        else:
+            relevant_doc_node = node.doc_node
+        self._docstring = _Docstring(relevant_doc_node, ignore_kwargs)
+
+    def __len__(self) -> int:
+        """Length of the longest sequence of args."""
+        return max([len(self.signature.args), len(self.docstring.args)])
+
+    def _decorated_with(self, name: str) -> bool:
+        if self._node.decorators is not None:
+            for dec in self._node.decorators.nodes:
+                return (isinstance(dec, _ast.Name) and dec.name == name) or (
+                    isinstance(dec, _ast.Attribute) and dec.attrname == name
+                )
+
+        return False
+
+    @property
+    def ismethod(self) -> bool:
+        """Boolean value for whether function is a method."""
+        return isinstance(self._parent, _ast.ClassDef)
+
+    @property
+    def isproperty(self) -> bool:
+        """Boolean value for whether function is a property."""
+        valid_properties = [
+            "property",
+            "cached_property",
+        ]
+        return self.ismethod and any(
+            self._decorated_with(i) for i in valid_properties
+        )
+
+    @property
+    def isoverloaded(self) -> bool:
+        """Boolean value for whether function is a property."""
+        return self._decorated_with("overload")
+
+    @property
+    def isinit(self) -> bool:
+        """Boolean value for whether function is a class constructor."""
+        return self.ismethod and self.name == "__init__"
+
+    @property
+    def isoverridden(self) -> bool:
+        """Boolean value for whether function is overridden."""
+        if self.ismethod and not self.isinit:
+            for ancestor in self._parent.ancestors():
+                if self.name in ancestor and isinstance(
+                    ancestor[self.name], _ast.FunctionDef
+                ):
+                    return True
+
+        return False
+
+    @property
+    def isprotected(self) -> bool:
+        """Boolean value for whether function is protected."""
+        return super().isprotected and not self.isinit and not self.isdunder
+
+    @property
+    def isstaticmethod(self) -> bool:
+        """Boolean value for whether function is a static method."""
+        return self.ismethod and self._decorated_with("staticmethod")
+
+    @property
+    def isdunder(self) -> bool:
+        """Boolean value for whether function is a dunder method."""
+        return (
+            self.ismethod
+            and not self.isinit
+            and bool(_re.match(r"__(.*)__", self.name))
+        )
+
+    @property
+    def name(self) -> str:
+        """The name of the function."""
+        return self._node.name
+
+    @property
+    def parent(
+        self,
+    ) -> _ast.FunctionDef | _ast.Module | _ast.ClassDef | _ast.Lambda:
+        """Function's parent node."""
+        return self._parent
+
+    @property
+    def lineno(self) -> int:
+        """Line number of function declaration."""
+        return self._node.lineno or 0
+
+    @property
+    def signature(self) -> _Signature:
+        """The function's signature parameters."""
+        return self._signature
+
+    @property
+    def docstring(self) -> _Docstring:
+        """The function's docstring."""
+        return self._docstring
+
+    @property
+    def disabled(self) -> list[_Message]:
+        """List of disabled checks specific to this function."""
+        return self._disabled
+
+    @property
+    def directives(self) -> _t.List[_Directive]:
+        """Directive, if any, belonging to this function."""
+        return self._directives
+
+
+class Modules(_t.List[Parent]):
+    """Sequence of ``Module`` objects parsed from Python modules or str.
+
+    Recursively collect Python files from within all dirs that exist
+    under paths provided.
+
+    If string is provided, ignore paths.
+
+    :param paths: Path(s) to parse ``Module``(s) from.
+    :param disable: List of checks to disable.
+    :param excludes: List pf regular expression of files and dirs to
+        exclude from checks.
+    :param string: String to parse if provided.
+    :param ignore_args: Ignore args prefixed with an asterisk.
+    :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
+    :param check_class_constructor: Check the class constructor's
+        docstring. Otherwise, expect the constructor's documentation to
+        be on the class level docstring.
+    :param verbose: increase output verbosity.
+    """
+
+    # handle errors here before appending a module
+    def _add_module(  # pylint: disable=too-many-arguments
+        self,
+        disable: list[_Message],
+        string: str | None = None,
+        root: _Path | None = None,
+        ignore_args: bool = False,
+        ignore_kwargs: bool = False,
+        check_class_constructor: bool = False,
+    ) -> None:
+        try:
+            if root is not None:
+                string = root.read_text(encoding="utf-8")
+
+            # empty string won't happen but keeps the
+            # typechecker happy
+            string = string or ""
+            self.append(
+                Parent(
+                    _ast.parse(string),
+                    _Directives(string, disable),
+                    root,
+                    ignore_args,
+                    ignore_kwargs,
+                    check_class_constructor,
+                )
+            )
+        except (_AstroidSyntaxError, UnicodeDecodeError) as err:
+            if root is not None and root.name.endswith(".py"):
+                # keep raising errors for .py files as was done prior to
+                # this change
+                # pass by silently for files that do not end with .py,
+                # which were not checked at all prior (these may result
+                # in a 123 syntax error exit status in the future)
+                # with this there should be no breaking change, and
+                # files that are supposed to be python, files evident by
+                # their suffix, will continue to fail
+                raise err
+
+            _vprint(
+                _FILE_INFO.format(
+                    path=root or "stdin", msg=str(err).replace("\n", " ")
+                ),
+                self._verbose,
+            )
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        *paths: _Path,
+        disable: list[_Message],
+        excludes: list[str],
+        string: str | None = None,
+        ignore_args: bool = False,
+        ignore_kwargs: bool = False,
+        check_class_constructor: bool = False,
+        verbose: bool = False,
+    ) -> None:
+        super().__init__()
+        self._disable = disable
+        self._excludes = excludes
+        self._ignore_args = ignore_args
+        self._ignore_kwargs = ignore_kwargs
+        self.check_class_constructor = check_class_constructor
+        self._verbose = verbose
+        if string is not None:
+            self._add_module(
+                disable,
+                string=string,
+                ignore_args=ignore_args,
+                ignore_kwargs=ignore_kwargs,
+                check_class_constructor=check_class_constructor,
+            )
+        else:
+            for path in paths:
+                self._populate(path)
+
+    def _populate(self, root: _Path) -> None:
+        if not root.exists():
+            raise FileNotFoundError(root)
+
+        if str(root) != "." and any(
+            _re.match(i, root.name) for i in self._excludes
+        ):
+            _vprint(
+                _FILE_INFO.format(path=root, msg="in exclude list, skipping"),
+                self._verbose,
+            )
+            return
+
+        if root.is_file():
+            self._add_module(
+                self._disable,
+                root=root,
+                ignore_args=self._ignore_args,
+                ignore_kwargs=self._ignore_kwargs,
+                check_class_constructor=self.check_class_constructor,
+            )
+
+        if root.is_dir():
+            for path in root.iterdir():
+                self._populate(path)

{docsig-0.45.0 → docsig-0.47.0}/docsig/_report.py

@@ -7,10 +7,10 @@ from __future__ import annotations as _
 
 import typing as _t
 
-from ._function import RETURN as _RETURN
-from ._function import Function as _Function
-from ._function import Param as _Param
 from ._message import Message as _Message
+from ._module import Function as _Function
+from ._stub import RETURN as _RETURN
+from ._stub import Param as _Param
 from ._utils import almost_equal as _almost_equal
 from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E

docsig-0.45.0/docsig/_function.py → docsig-0.47.0/docsig/_stub.py

@@ -13,10 +13,6 @@ from collections import Counter as _Counter
 import astroid as _ast
 import sphinx.ext.napoleon as _s
 
-from ._directives import Directive as _Directive
-from ._message import Message as _Message
-from ._utils import isprotected as _isprotected
-
 PARAM = "param"
 KEYWORD = "keyword"
 KEY = "key"
@@ -151,7 +147,7 @@ class _Params(_t.List[Param]):
         return any(k for k, v in _Counter(self).items() if v > 1)
 
 
-class _DocSig:
+class _Stub:
     def __init__(
         self, ignore_args: bool = False, ignore_kwargs: bool = False
     ) -> None:
@@ -169,7 +165,18 @@ class _DocSig:
         return self._returns
 
 
-class _Signature(_DocSig):
+class Signature(_Stub):
+    """Represents a function signature.
+
+    :param arguments: Arguments provided to signature.
+    :param returns: Returns declared in signature.
+    :param ismethod: Whether this signature belongs to a method.
+    :param isstaticmethod: Whether this signature belongs to a static
+        method.
+    :param ignore_args: Ignore args prefixed with an asterisk.
+    :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
+    """
+
     def __init__(  # pylint: disable=too-many-arguments
         self,
         arguments: _ast.Arguments,
@@ -239,7 +246,14 @@ class _Signature(_DocSig):
         return self._rettype
 
 
-class _Docstring(_DocSig):
+class Docstring(_Stub):
+    """Represents a function docstring.
+
+    :param node: Docstring ast node.
+    :param ignore_args: Ignore args prefixed with an asterisk.
+    :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
+    """
+
     def __init__(
         self,
         node: _ast.Const | None = None,
@@ -269,154 +283,3 @@ class _Docstring(_DocSig):
         Docstring has to exist for docstring to be considered bare.
         """
         return self._string is not None and not self._args and not self.returns
-
-
-class Function:  # pylint: disable=too-many-arguments
-    """Represents a function with signature and docstring parameters.
-
-    :param node: Function's abstract syntax tree.
-    :param directives: Directive, if any, belonging to this function.
-    :param disabled: List of disabled checks specific to this function.
-    :param ignore_args: Ignore args prefixed with an asterisk.
-    :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
-    :param check_class_constructor: If the function is the class
-        constructor, use its own docstring. Otherwise, use the class
-        level docstring for the constructor function.
-    """
-
-    def __init__(  # pylint: disable=too-many-arguments
-        self,
-        node: _ast.FunctionDef,
-        directives: _t.List[_Directive],
-        disabled: list[_Message],
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
-        check_class_constructor: bool = False,
-    ) -> None:
-        self._node = node
-        self._directives = directives
-        self._disabled = disabled
-        self._parent = node.parent.frame()
-        self._signature = _Signature(
-            node.args,
-            node.returns,
-            self.ismethod,
-            self.isstaticmethod,
-            ignore_args,
-            ignore_kwargs,
-        )
-        if self.isinit and not check_class_constructor:
-            # docstring for __init__ is expected on the class docstring
-            relevant_doc_node = self._parent.doc_node
-        else:
-            relevant_doc_node = node.doc_node
-        self._docstring = _Docstring(relevant_doc_node, ignore_kwargs)
-
-    def __len__(self) -> int:
-        """Length of the longest sequence of args."""
-        return max([len(self.signature.args), len(self.docstring.args)])
-
-    def _decorated_with(self, name: str) -> bool:
-        if self._node.decorators is not None:
-            for dec in self._node.decorators.nodes:
-                return (isinstance(dec, _ast.Name) and dec.name == name) or (
-                    isinstance(dec, _ast.Attribute) and dec.attrname == name
-                )
-
-        return False
-
-    @property
-    def ismethod(self) -> bool:
-        """Boolean value for whether function is a method."""
-        return isinstance(self._parent, _ast.ClassDef)
-
-    @property
-    def isproperty(self) -> bool:
-        """Boolean value for whether function is a property."""
-        valid_properties = [
-            "property",
-            "cached_property",
-        ]
-        return self.ismethod and any(
-            self._decorated_with(i) for i in valid_properties
-        )
-
-    @property
-    def isoverloaded(self) -> bool:
-        """Boolean value for whether function is a property."""
-        return self._decorated_with("overload")
-
-    @property
-    def isinit(self) -> bool:
-        """Boolean value for whether function is a class constructor."""
-        return self.ismethod and self.name == "__init__"
-
-    @property
-    def isoverridden(self) -> bool:
-        """Boolean value for whether function is overridden."""
-        if self.ismethod and not self.isinit:
-            for ancestor in self._parent.ancestors():
-                if self.name in ancestor and isinstance(
-                    ancestor[self.name], _ast.FunctionDef
-                ):
-                    return True
-
-        return False
-
-    @property
-    def isprotected(self) -> bool:
-        """Boolean value for whether function is protected."""
-        return (
-            _isprotected(self.name) and not self.isinit and not self.isdunder
-        )
-
-    @property
-    def isstaticmethod(self) -> bool:
-        """Boolean value for whether function is a static method."""
-        return self.ismethod and self._decorated_with("staticmethod")
-
-    @property
-    def isdunder(self) -> bool:
-        """Boolean value for whether function is a dunder method."""
-        return (
-            self.ismethod
-            and not self.isinit
-            and bool(_re.match(r"__(.*)__", self.name))
-        )
-
-    @property
-    def name(self) -> str:
-        """The name of the function."""
-        return self._node.name
-
-    @property
-    def parent(
-        self,
-    ) -> _ast.FunctionDef | _ast.Module | _ast.ClassDef | _ast.Lambda:
-        """Function's parent node."""
-        return self._parent
-
-    @property
-    def lineno(self) -> int:
-        """Line number of function declaration."""
-        return self._node.lineno or 0
-
-    @property
-    def signature(self) -> _Signature:
-        """The function's signature parameters."""
-        return self._signature
-
-    @property
-    def docstring(self) -> _Docstring:
-        """The function's docstring."""
-        return self._docstring
-
-    @property
-    def disabled(self) -> list[_Message]:
-        """List of disabled checks specific to this function."""
-        return self._disabled
-
-    @property
-    def directives(self) -> _t.List[_Directive]:
-        """Directive, if any, belonging to this function."""
-        return self._directives

{docsig-0.45.0 → docsig-0.47.0}/docsig/_utils.py

@@ -8,15 +8,6 @@ from __future__ import annotations as _
 from difflib import SequenceMatcher as _SequenceMatcher
 
 
-def isprotected(name: str | None) -> bool:
-    """Confirm whether attribute is protected or not.
-
-    :param name: Name to check.
-    :return: Boolean value for whether attribute is protected or not.
-    """
-    return str(name).startswith("_")
-
-
 def almost_equal(str1: str, str2: str, mini: float, maxi: float) -> bool:
     """Show result for more than the minimum but less than the maximum.
 
@@ -28,3 +19,13 @@ def almost_equal(str1: str, str2: str, mini: float, maxi: float) -> bool:
     :return: Boolean result for whether both strings are almost equal.
     """
     return mini < _SequenceMatcher(a=str1, b=str2).ratio() < maxi
+
+
+def vprint(msg: str, verbose: bool = False) -> None:
+    """Print messages only if verbose is true.
+
+    :param msg: Message to print.
+    :param verbose: Whether verbose mode is enabled.
+    """
+    if verbose:
+        print(msg)

{docsig-0.45.0 → docsig-0.47.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.45.0"
+__version__ = "0.47.0"

{docsig-0.45.0 → docsig-0.47.0}/pyproject.toml

@@ -72,12 +72,12 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.45.0"
+version = "0.47.0"
 
 [tool.poetry.dependencies]
 Pygments = "^2.13.0"
 Sphinx = "^7.0.0"
-arcon = ">=0.3.1"
+arcon = ">=0.4.0"
 astroid = "^3.0.1"
 object-colors = "^2.1.0"
 python = "^3.8"

docsig-0.45.0/docsig/_module.py

@@ -1,229 +0,0 @@
-"""
-docsig._module
-==============
-"""
-
-from __future__ import annotations as _
-
-import re as _re
-import typing as _t
-from pathlib import Path as _Path
-
-import astroid as _ast
-from astroid import AstroidSyntaxError as _AstroidSyntaxError
-
-from ._directives import Directives as _Directives
-from ._function import Function as _Function
-from ._message import Message as _Message
-from ._utils import isprotected as _isprotected
-
-
-class Parent(_t.List[_Function]):
-    """Represents an object that contains functions or methods.
-
-    :param node: Parent's abstract syntax tree.
-    :param directives: Data for directives and, subsequently, total of
-        errors which are excluded from function checks.
-    :param path: Path to base path representation on.
-    :param ignore_args: Ignore args prefixed with an asterisk.
-    :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
-    :param check_class_constructor: Check the class constructor's
-        docstring. Otherwise, expect the constructor's documentation to
-        be on the class level docstring.
-    """
-
-    def __init__(  # pylint: disable=too-many-arguments
-        self,
-        node: _ast.Module | _ast.ClassDef,
-        directives: _Directives,
-        path: _Path | None = None,
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
-        check_class_constructor: bool = False,
-    ) -> None:
-        super().__init__()
-        self._name = node.name
-        self._path = f"{path}:" if path is not None else ""
-        overloads = []
-        returns = None
-        parent_comments, parent_disabled = directives.get(
-            node.lineno, ([], [])
-        )
-        for subnode in node.body:
-            comments, disabled = directives.get(subnode.lineno, ([], []))
-            comments.extend(parent_comments)
-            disabled.extend(parent_disabled)
-            if isinstance(subnode, _ast.FunctionDef):
-                func = _Function(
-                    subnode,
-                    comments,
-                    disabled,
-                    ignore_args,
-                    ignore_kwargs,
-                    check_class_constructor,
-                )
-                if func.isoverloaded:
-                    overloads.append(func.name)
-                    returns = func.signature.rettype
-                else:
-                    if func.name in overloads:
-                        subnode.returns = returns
-                        # noinspection PyProtectedMember
-                        func._signature._rettype = (
-                            returns
-                            if isinstance(returns, str)
-                            else func._signature._get_rettype(returns)
-                        )
-                        # noinspection PyProtectedMember
-                        func._signature._returns = (
-                            str(func._signature._rettype) != "None"
-                        )
-
-                    self.append(func)
-
-    @property
-    def path(self) -> str:
-        """Representation of path to parent."""
-        return self._path
-
-    @property
-    def isprotected(self) -> bool:
-        """Boolean value for whether class is protected."""
-        return _isprotected(self._name)
-
-
-class _Module(_t.List[Parent]):
-    def __init__(  # pylint: disable=too-many-arguments
-        self,
-        string: str,
-        disable: list[_Message],
-        path: _Path | None = None,
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
-        check_class_constructor: bool = False,
-    ) -> None:
-        super().__init__()
-        ast = _ast.parse(string)
-        directives = _Directives(string, disable)
-        self.append(Parent(ast, directives, path, ignore_args, ignore_kwargs))
-        for subnode in ast.body:
-            if isinstance(subnode, _ast.ClassDef):
-                self.append(
-                    Parent(
-                        subnode,
-                        directives,
-                        path,
-                        ignore_args,
-                        ignore_kwargs,
-                        check_class_constructor,
-                    )
-                )
-
-
-class Modules(_t.List[_Module]):
-    """Sequence of ``Module`` objects parsed from Python modules or str.
-
-    Recursively collect Python files from within all dirs that exist
-    under paths provided.
-
-    If string is provided, ignore paths.
-
-    :param paths: Path(s) to parse ``Module``(s) from.
-    :param disable: List of checks to disable.
-    :param excludes: List pf regular expression of files and dirs to
-        exclude from checks.
-    :param string: String to parse if provided.
-    :param ignore_args: Ignore args prefixed with an asterisk.
-    :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
-    :param check_class_constructor: Check the class constructor's
-        docstring. Otherwise, expect the constructor's documentation to
-        be on the class level docstring.
-    """
-
-    # handle errors here before appending a module
-    def _add_module(  # pylint: disable=too-many-arguments
-        self,
-        disable: list[_Message],
-        string: str | None = None,
-        root: _Path | None = None,
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
-        check_class_constructor: bool = False,
-    ) -> None:
-        try:
-            if root is not None:
-                string = root.read_text(encoding="utf-8")
-
-            self.append(
-                _Module(
-                    # empty string won't happen but keeps the
-                    # typechecker happy
-                    string or "",
-                    disable,
-                    root,
-                    ignore_args,
-                    ignore_kwargs,
-                    check_class_constructor,
-                )
-            )
-        except (_AstroidSyntaxError, UnicodeDecodeError) as err:
-            if root is not None and root.name.endswith(".py"):
-                # keep raising errors for .py files as was done prior to
-                # this change
-                # pass by silently for files that do not end with .py,
-                # which were not checked at all prior (these may result
-                # in a 123 syntax error exit status in the future)
-                # with this there should be no breaking change, and
-                # files that are supposed to be python, files evident by
-                # their suffix, will continue to fail
-                raise err
-
-    def __init__(  # pylint: disable=too-many-arguments
-        self,
-        *paths: _Path,
-        disable: list[_Message],
-        excludes: list[str],
-        string: str | None = None,
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
-        check_class_constructor: bool = False,
-    ) -> None:
-        super().__init__()
-        self._disable = disable
-        self._excludes = excludes
-        self._ignore_args = ignore_args
-        self._ignore_kwargs = ignore_kwargs
-        self.check_class_constructor = check_class_constructor
-        if string is not None:
-            self._add_module(
-                disable,
-                string=string,
-                ignore_args=ignore_args,
-                ignore_kwargs=ignore_kwargs,
-                check_class_constructor=check_class_constructor,
-            )
-        else:
-            for path in paths:
-                self._populate(path)
-
-    def _populate(self, root: _Path) -> None:
-        if not root.exists():
-            raise FileNotFoundError(root)
-
-        if str(root) != "." and any(
-            _re.match(i, root.name) for i in self._excludes
-        ):
-            return
-
-        if root.is_file():
-            self._add_module(
-                self._disable,
-                root=root,
-                ignore_args=self._ignore_args,
-                ignore_kwargs=self._ignore_kwargs,
-                check_class_constructor=self.check_class_constructor,
-            )
-
-        if root.is_dir():
-            for path in root.iterdir():
-                self._populate(path)