docsig 0.81.2__tar.gz → 0.82.0__tar.gz

{docsig-0.81.2 → docsig-0.82.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.81.2
+Version: 0.82.0
 Summary: Check signature params for proper documentation
 License: MIT
 License-File: LICENSE
@@ -184,7 +184,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.81.2, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.82.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
 
 And now use `flake8` to lint your files
 
@@ -270,7 +270,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.81.2
+        rev: v0.82.0
         hooks:
           - id: docsig
             args:
@@ -289,7 +289,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.81.2
+              - docsig==0.82.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.81.2 → docsig-0.82.0}/README.rst

@@ -155,7 +155,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.81.2, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.82.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
 
 And now use `flake8` to lint your files
 
@@ -241,7 +241,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.81.2
+        rev: v0.82.0
         hooks:
           - id: docsig
             args:
@@ -260,7 +260,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.81.2
+              - docsig==0.82.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

docsig-0.82.0/docsig/_check.py

@@ -0,0 +1,82 @@
+"""
+docsig._check
+=============
+"""
+
+from __future__ import annotations as _
+
+from ._config import Config as _Config
+from ._module import Function as _Function
+from ._module import Parent as _Parent
+from ._report import Failure as _Failure
+from ._report import Failures as _Failures
+
+
+def _should_check_function(
+    function: _Function,
+    parent: _Parent,
+    config: _Config,
+) -> bool:
+    if function.isoverridden and not config.check.overridden:
+        return False
+
+    if function.isprotected and not config.check.protected:
+        return False
+
+    if function.isdunder and not config.check.dunders:
+        return False
+
+    if function.docstring.bare and config.ignore.no_params:
+        return False
+
+    if function.isinit and (
+        not (config.check.class_ or config.check.class_constructor)
+        or (parent.isprotected and not config.check.protected)
+    ):
+        return False
+
+    return True
+
+
+def _run_check(
+    child: _Parent,
+    parent: _Parent,
+    config: _Config,
+    failures: _Failures,
+) -> None:
+    if isinstance(child, _Function) and _should_check_function(
+        child,
+        parent,
+        config,
+    ):
+        failure = _Failure(child, config)
+        if failure:
+            failures.append(failure)
+
+    # recurse for either class methods or, if enabled, nested functions
+    if not isinstance(child, _Function) or config.check.nested:
+        for child_of_child in child.children:
+            _run_check(child_of_child, child, config, failures)
+
+
+def run_checks(module: _Parent, config: _Config) -> _Failures:
+    """Run checks on the module and return a list of failures.
+
+    Traverse the module's functions and classes. A callable is checked
+    only if it is public or if configuration allows protected or
+    overridden members. Failures are collected and returned.
+
+    :param module: A module object that contains functions or classes.
+    :param config: Configuration object.
+    :return: A list of function and class failures.
+    """
+    failures = _Failures()
+    for child in module.children:
+        if (
+            not child.isprotected
+            or config.check.protected
+            or config.check.protected_class_methods
+        ):
+            _run_check(child, module, config, failures)
+
+    return failures

{docsig-0.81.2 → docsig-0.82.0}/docsig/_config.py

@@ -18,7 +18,7 @@ from pathlib import Path as _Path
 import tomli as _tomli
 
 from ._version import __version__
-from .messages import Messages
+from .messages import Messages as _Messages
 
 PYPROJECT_TOML = "pyproject.toml"
 
@@ -361,8 +361,8 @@ class Config:
 
     check: Check = _field(default_factory=Check)
     ignore: Ignore = _field(default_factory=Ignore)
-    target: Messages = _field(default_factory=Messages)
-    disable: Messages = _field(default_factory=Messages)
+    target: _Messages = _field(default_factory=_Messages)
+    disable: _Messages = _field(default_factory=_Messages)
     exclude: list[str] = _field(default_factory=list)
     excludes: list[str] | None = None
     list_checks: bool = False

{docsig-0.81.2 → docsig-0.82.0}/docsig/_core.py

@@ -8,30 +8,21 @@ Entry point and orchestration for running docstring/signature checks.
 from __future__ import annotations as _
 
 import logging as _logging
-import os as _os
 import sys as _sys
 import warnings as _warnings
 from pathlib import Path as _Path
-from tokenize import TokenError as _TokenError
-from warnings import warn as _warn
-
-import astroid as _ast
 
 from . import _decorators
+from ._check import run_checks as _run_checks
 from ._config import Check as _Check
 from ._config import Config as _Config
 from ._config import Ignore as _Ignore
-from ._directives import Directives as _Directives
-from ._files import FILE_INFO as _FILE_INFO
-from ._files import Paths as _Paths
-from ._module import Error as _Error
-from ._module import Function as _Function
-from ._module import Parent as _Parent
-from ._report import Failure as _Failure
+from ._files import Files as _Files
+from ._parsers import parse_from_file as _parse_from_file
+from ._parsers import parse_from_string as _parse_from_string
 from ._report import Failures as _Failures
+from ._report import report as _report
 from ._utils import print_checks as _print_checks
-from .messages import NEW as _NEW
-from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E
 from .messages import Messages as _Messages
 
@@ -70,159 +61,6 @@ def setup_logger(verbose: bool) -> None:
         logger.addHandler(stream_handler)
 
 
-def _should_check_function(
-    child: _Function,
-    parent: _Parent,
-    config: _Config,
-) -> bool:
-    if child.isoverridden and not config.check.overridden:
-        return False
-
-    if child.isprotected and not config.check.protected:
-        return False
-
-    if child.isdunder and not config.check.dunders:
-        return False
-
-    if child.docstring.bare and config.ignore.no_params:
-        return False
-
-    if child.isinit and (
-        not (config.check.class_ or config.check.class_constructor)
-        or (parent.isprotected and not config.check.protected)
-    ):
-        return False
-
-    return True
-
-
-def _run_check(
-    child: _Parent,
-    parent: _Parent,
-    config: _Config,
-    failures: _Failures,
-) -> None:
-    if isinstance(child, _Function) and _should_check_function(
-        child,
-        parent,
-        config,
-    ):
-        failure = _Failure(child, config.target, config.check.property_returns)
-        if failure:
-            failures.append(failure)
-
-    # recurse for either class methods or, if enabled, nested functions
-    if not isinstance(child, _Function) or config.check.nested:
-        for func in child.children:
-            _run_check(func, child, config, failures)
-
-
-def _from_file(path: _Path, config: _Config) -> _Parent:
-    try:
-        code = path.read_text(encoding="utf-8")
-        parent = _from_str(
-            code,
-            config,
-            str(path)[:-3].replace(_os.sep, ".").replace("-", "_"),
-            path,
-        )
-    except UnicodeDecodeError as err:
-        logger = _logging.getLogger(__package__)
-        logger.debug(_FILE_INFO, path, str(err).replace("\n", " "))
-        parent = _Parent(error=_Error.UNICODE)
-
-    if parent.error is not None and not path.name.endswith(".py"):
-        parent = _Parent()
-
-    return parent
-
-
-def _from_str(
-    code: str,
-    config: _Config,
-    module_name: str = "",
-    path: _Path | None = None,
-) -> _Parent:
-    logger = _logging.getLogger(__package__)
-    source_name = path or "stdin"
-    try:
-        node = _ast.parse(code, module_name, str(path))
-        try:
-            directives = _Directives.from_text(code, config.disable)
-        except _TokenError as err:
-            directives = _Directives()
-            logger.debug(
-                _FILE_INFO,
-                source_name,
-                f"error parsing comments {err}".lower(),
-            )
-
-        parent = _Parent(
-            node,
-            directives,
-            path,
-            config.ignore.args,
-            config.ignore.kwargs,
-            config.check.class_constructor,
-        )
-        logger.debug(_FILE_INFO, source_name, "Parsing Python code successful")
-    except _ast.AstroidSyntaxError as err:
-        logger.debug(_FILE_INFO, source_name, str(err).replace("\n", " "))
-        parent = _Parent(error=_Error.SYNTAX)
-
-    return parent
-
-
-def _get_failures(module: _Parent, config: _Config) -> _Failures:
-    failures = _Failures()
-    for top_level in module.children:
-        if (
-            not top_level.isprotected
-            or config.check.protected
-            or config.check.protected_class_methods
-        ):
-            _run_check(top_level, module, config, failures)
-
-    return failures
-
-
-def _report(
-    failures: _Failures,
-    config: _Config,
-    path: str | None = None,
-) -> int:
-    retcodes = [0]
-    for failure in failures:
-        retcodes.append(failure.retcode)
-        path_prefix = f"{path}:" if path is not None else ""
-        header = f"{path_prefix}{failure.lineno} in {failure.name}"
-        if not config.no_ansi and _sys.stdout.isatty():
-            header = f"\033[35m{header}\033[0m"
-
-        print(header)
-        for item in failure:
-            extra = None
-            if item.hint:
-                extra = f"hint: {item.hint}"
-
-            if item.new:
-                extra = "warning: please remember to fix this or disable it"
-                _warn(_NEW.format(ref=item.ref), FutureWarning, stacklevel=3)
-
-            print(
-                "    "
-                + _TEMPLATE.format(
-                    ref=item.ref,
-                    description=item.description,
-                    symbolic=item.symbolic,
-                ),
-            )
-            if extra is not None:
-                print(f"    {extra}")
-
-    return max(retcodes)
-
-
 def handle_deprecations(
     ignore_typechecker: bool,
     disable: list,
@@ -245,15 +83,15 @@ def handle_deprecations(
         disable.extend(messages)
 
 
-def runner(path: _Path, config: _Config) -> _Failures:
+def runner(file: _Path, config: _Config) -> _Failures:
     """Run checks for a single file and return collected failures.
 
-    :param path: Path to the file to check.
+    :param file: Path to the file to check.
     :param config: Configuration object.
     :return: Collected failures for the file.
     """
-    module = _from_file(path, config)
-    return _get_failures(module, config)
+    module = _parse_from_file(file, config)
+    return _run_checks(module, config)
 
 
 @_decorators.parse_msgs
@@ -367,20 +205,16 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     if config.list_checks:
         return int(bool(_print_checks()))  # type: ignore
 
-    if string is None:
-        retcodes = [0]
-        paths = _Paths(
-            *path,
-            patterns=config.exclude,
-            excludes=config.excludes,
-            include_ignored=config.include_ignored,
-        )
-        for path_ in paths:
-            failures = runner(path_, config)
-            retcodes.append(_report(failures, config, str(path_)))
+    if string:
+        module = _parse_from_string(string, config)
+        failures = _run_checks(module, config)
+        return _report(failures, config)
 
-        return max(retcodes)
+    retcodes = [0]
+    files = _Files(path, config)
+    for file in files:
+        failures = runner(file, config)
+        retcode = _report(failures, config, str(file))
+        retcodes.append(retcode)
 
-    module = _from_str(string, config)
-    failures = _get_failures(module, config)
-    return _report(failures, config)
+    return max(retcodes)

{docsig-0.81.2 → docsig-0.82.0}/docsig/_directives.py

@@ -15,6 +15,10 @@ from .messages import E as _E
 from .messages import Messages as _Messages
 
 
+class Comments(_t.List["Comment"]):
+    """List of comments."""
+
+
 class Comment(_Messages):
     """A single comment directive.
 
@@ -23,12 +27,16 @@ class Comment(_Messages):
     """
 
     _valid_kinds = "enable", "disable"
+    _valid_flags = ("next",)
 
     def __init__(self, string: str, col: int) -> None:
         super().__init__()
         self._ismodule = col == 0
         parts = string.split("=")
-        self._kind = parts[0]
+        subparts = parts[0].split("-")
+        self._kind = subparts[0]
+        self._flag = None if len(subparts) == 1 else subparts[1]
+        self._isnext = self._flag == "next"
         if len(parts) == 1:
             self.extend(_E.all)
         else:
@@ -59,6 +67,21 @@ class Comment(_Messages):
         """Whether this is a disable directive."""
         return self._kind == self._valid_kinds[1]
 
+    @property
+    def isnext(self) -> bool:
+        """Whether this directive applies to the next line only."""
+        return self._isnext
+
+    @property
+    def isvalidflag(self) -> bool:
+        """Whether the directive flag (if any) is valid."""
+        return self._flag is None or self._flag in self._valid_flags
+
+    @property
+    def flag(self) -> str | None:
+        """Flag for this directive (e.g. next), or None."""
+        return self._flag
+
     @classmethod
     def parse(cls, comment: str, col: int) -> Comment | None:
         """Parse a comment into a docsig directive when present.
@@ -73,10 +96,6 @@ class Comment(_Messages):
         return None
 
 
-class Comments(_t.List[Comment]):
-    """List of comments."""
-
-
 class Directives(_t.Dict[int, _t.Tuple[Comments, _Messages]]):
     """Map line number to comments and disabled messages for that line.
 
@@ -96,6 +115,9 @@ class Directives(_t.Dict[int, _t.Tuple[Comments, _Messages]]):
         directives = cls()
         fin = _StringIO(text)
         comments = Comments()
+        enable_next = False
+        next_comments = Comments(comments)
+        next_messages = _Messages(messages)
         for line in _tokenize.generate_tokens(fin.readline):
             # do nothing for these line types
             if line.type in (_tokenize.NAME, _tokenize.OP, _tokenize.DEDENT):
@@ -119,12 +141,30 @@ class Directives(_t.Dict[int, _t.Tuple[Comments, _Messages]]):
                             i for i in messages if i not in comment
                         )
 
+                    # if directive has a 'next' flag then alter the
+                    # module level scope, not the inline scope (which
+                    # behaves similar to next), so that inline
+                    # directives are included and not overwritten
+                    if comment.isnext and not enable_next:
+                        enable_next = True
+                        next_comments = Comments(comments)
+                        next_messages = _Messages(messages)
+
                     # if module level directive, then make changes
                     # globally
                     if comment.ismodule:
                         comments = scoped_comments
                         messages = scoped_messages
 
+            # if in a 'next' module level scope and the line type is a
+            # newline (not a comment to allow 'next' directives to be
+            # stacked) then leave the 'next' module level scope and
+            # reset the global messages to before the 'next' directive
+            elif enable_next and line.type != _tokenize.NL:
+                enable_next = False
+                comments = next_comments
+                messages = next_messages
+
             # check that a scoped message has not updated this first, as
             # they take precedence over global messages
             if lineno not in directives:

{docsig-0.81.2 → docsig-0.82.0}/docsig/_files.py

@@ -17,6 +17,8 @@ from pathspec import PathSpec as _PathSpec
 from pathspec.patterns import GitWildMatchPattern as _GitWildMatchPattern
 from wcmatch.pathlib import Path as _WcPath
 
+from ._config import Config as _Config
+
 FILE_INFO = "%s: %s"
 
 
@@ -69,55 +71,46 @@ def _glob(path: _Path, pattern: str) -> bool:
     return _WcPath(str(path)).globmatch(pattern)  # type: ignore
 
 
-class Paths(_t.List[_Path]):
+class Files(_t.List[_Path]):
     """Collect paths to check (gitignore and exclude applied).
 
     :param paths: Path(s) to collect (files or directories).
-    :param patterns: List pf regular expression of files and dirs to
-        exclude from checks.
-    :param excludes: Files or dirs to exclude from checks.
-    :param include_ignored: Check files even if they match a gitignore
-        pattern.
+    :param config: Configuration object.
     """
 
     def __init__(
         self,
-        *paths: _Path | str,
-        patterns: list[str],
-        excludes: list[str] | None = None,
-        include_ignored: bool = False,
+        paths: tuple[str | _Path, ...],
+        config: _Config,
     ) -> None:
         super().__init__()
-        self._include_ignored = include_ignored
+        self._include_ignored = config.include_ignored
         self._gitignore = _Gitignore()
-        self._logger = _logging.getLogger(__package__)
+        logger = _logging.getLogger(__package__)
         for path in paths:
             self._populate(_Path(path))
 
         for path in list(self):
             if str(path) != "." and (
-                any(_re.match(i, str(path)) for i in patterns)
-                or any(_glob(path, i) for i in excludes or [])
+                any(_re.match(i, str(path)) for i in config.exclude)
+                or any(_glob(path, i) for i in config.excludes or [])
             ):
-                self._logger.debug(
-                    FILE_INFO,
-                    path,
-                    "in exclude list, skipping",
-                )
+                logger.debug(FILE_INFO, path, "in exclude list, skipping")
                 self.remove(path)
 
         self.sort()
 
     def _populate(self, root: _Path) -> None:
+        logger = _logging.getLogger(__package__)
         if not root.exists():
             if root.is_symlink():
-                self._logger.debug(FILE_INFO, root, "broken link, skipping")
+                logger.debug(FILE_INFO, root, "broken link, skipping")
                 return
 
             raise FileNotFoundError(root)
 
         if not self._include_ignored and self._gitignore.match_file(root):
-            self._logger.debug(FILE_INFO, root, "in gitignore, skipping")
+            logger.debug(FILE_INFO, root, "in gitignore, skipping")
             return
 
         if root.is_file():

{docsig-0.81.2 → docsig-0.82.0}/docsig/_module.py

@@ -14,6 +14,7 @@ from pathlib import Path as _Path
 
 import astroid as _ast
 
+from ._config import Config as _Config
 from ._directives import Comments as _Comments
 from ._directives import Directives as _Directives
 from ._stub import Docstring as _Docstring
@@ -22,15 +23,24 @@ from ._stub import Signature as _Signature
 from .messages import Messages as _Messages
 
 
+class _Imports(_t.Dict[str, str]):
+    """Represents python imports."""
+
+
+class _Overloads(_t.Dict[str, "Function"]):
+    """Represents overloaded methods."""
+
+
+class _Children(_t.List[_t.Union["Parent", "Function"]]):
+    """Represents children of an object."""
+
+
 class Error(_Enum):
     """Represents an unrecoverable error."""
 
     SYNTAX = 1
     UNICODE = 2
-
-
-class _Imports(_t.Dict[str, str]):
-    """Represents python imports."""
+    RECURSION = 3
 
 
 class Parent:  # pylint: disable=too-many-instance-attributes
@@ -38,12 +48,8 @@ class Parent:  # pylint: disable=too-many-instance-attributes
 
     :param node: AST node for this scope.
     :param directives: Directives and excluded errors per line.
-    :param path: Path for this scope (or None).
-    :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 file: Path for this scope (or None).
+    :param config: Configuration object.
     :param imports: Imports in this scope.
     :param error: Unrecoverable error for this scope, if any.
     """
@@ -59,28 +65,25 @@ class Parent:  # pylint: disable=too-many-instance-attributes
             | None
         ) = None,
         directives: _Directives | None = None,
-        path: _Path | None = None,
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
-        check_class_constructor: bool = False,
+        file: _Path | None = None,
+        config: _Config | None = None,
         imports: _Imports | None = None,
         error: Error | None = None,
     ) -> None:
         super().__init__()
-        self._name = "module"
         self._error = error
-        self._ignore_args = ignore_args
-        self._ignore_kwargs = ignore_kwargs
-        self._check_class_constructor = check_class_constructor
+        self._directives = directives or _Directives()
+        self._config = config or _Config()
         self._children = _Children()
         self._imports = imports or _Imports()
         self._overloads = _Overloads()
         if node is None:
+            self._name = "module"
             if not isinstance(self, Function) and error is not None:
-                self._children.append(Function(path, error=error))
+                self._children.append(Function(file, error=error))
         else:
             self._name = node.name
-            self._parse_ast(node, directives or _Directives(), path)
+            self._parse_ast(node, file)
 
     def _parse_ast(
         self,
@@ -90,19 +93,18 @@ class Parent:  # pylint: disable=too-many-instance-attributes
             | _ast.nodes.FunctionDef
             | _ast.nodes.NodeNG
         ),
-        directives: _Directives,
-        path: _Path | None = None,
+        file: _Path | None = None,
     ) -> None:
         # need to keep track of `comments` as, even though they are
         # resolved in the directive object, they are needed to notify
         # the user in the case that they are invalid
-        parent_comments, parent_disabled = directives.get(
+        parent_comments, parent_disabled = self._directives.get(
             node.lineno,
             (_Comments(), _Messages()),
         )
         if hasattr(node, "body"):
             for subnode in node.body:
-                comments, disabled = directives.get(
+                comments, disabled = self._directives.get(
                     subnode.lineno,
                     (_Comments(), _Messages()),
                 )
@@ -119,12 +121,10 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                     func = Function(
                         subnode,
                         comments,
-                        directives,
+                        self._directives,
                         disabled,
-                        path,
-                        self._ignore_args,
-                        self._ignore_kwargs,
-                        self._check_class_constructor,
+                        file,
+                        self._config,
                         self._imports,
                     )
                     if func.isoverloaded:
@@ -145,16 +145,14 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                     self._children.append(
                         Parent(
                             subnode,
-                            directives,
-                            path,
-                            self._ignore_args,
-                            self._ignore_kwargs,
-                            self._check_class_constructor,
+                            self._directives,
+                            file,
+                            self._config,
                             self._imports,
                         ),
                     )
                 else:
-                    self._parse_ast(subnode, directives, path)
+                    self._parse_ast(subnode, file)
 
     @property
     def isprotected(self) -> bool:
@@ -179,12 +177,8 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
     :param comments: Comment directives for this function.
     :param directives: Directives keyed by line.
     :param messages: Disabled checks for this function.
-    :param path: Path for this function (or None).
-    :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.
+    :param file: Path for this function (or None).
+    :param config: Configuration object.
     :param imports: Imports in this scope.
     :param error: Unrecoverable error for this function, if any.
     """
@@ -196,20 +190,16 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
         comments: _Comments | None = None,
         directives: _Directives | None = None,
         messages: _Messages | None = None,
-        path: _Path | None = None,
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
-        check_class_constructor: bool = False,
+        file: _Path | None = None,
+        config: _Config | None = None,
         imports: _Imports | None = None,
         error: Error | None = None,
     ) -> None:
         super().__init__(
             node,
             directives or _Directives(),
-            path,
-            ignore_args,
-            ignore_kwargs,
-            check_class_constructor,
+            file,
+            config,
             imports,
         )
         self._comments = comments or _Comments()
@@ -232,10 +222,9 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
 
             self._signature = self._signature.from_ast(
                 node,
-                ignore_args,
-                ignore_kwargs,
+                self._config.ignore,
             )
-            if self.isinit and not check_class_constructor:
+            if self.isinit and not self._config.check.class_constructor:
                 # docstring for __init__ is expected on the class
                 # docstring
                 relevant_doc_node = self._parent.doc_node
@@ -364,11 +353,3 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
         :param rettype: Return type of the overloaded variant.
         """
         self._signature.overload(rettype)
-
-
-class _Overloads(_t.Dict[str, Function]):
-    """Represents overloaded methods."""
-
-
-class _Children(_t.List[_t.Union[Parent, Function]]):
-    """Represents children of an object."""

docsig-0.82.0/docsig/_parsers.py

@@ -0,0 +1,89 @@
+"""
+docsig._parsers
+===============
+"""
+
+from __future__ import annotations as _
+
+import logging as _logging
+import os as _os
+from pathlib import Path as _Path
+from tokenize import TokenError as _TokenError
+
+import astroid as _ast
+
+from ._config import Config as _Config
+from ._directives import Directives as _Directives
+from ._files import FILE_INFO as _FILE_INFO
+from ._module import Error as _Error
+from ._module import Parent as _Parent
+
+
+def parse_from_string(
+    code: str,
+    config: _Config,
+    module_name: str = "",
+    file: _Path | None = None,
+) -> _Parent:
+    """Build a Parent from a string of Python code.
+
+    Parses AST and comment directives (AST does not include comments,
+    so directives are parsed separately). On syntax error, returns a
+    Parent with an error set.
+
+    :param code: Python source to parse.
+    :param config: Configuration object.
+    :param module_name: Module name, or empty string.
+    :param file: Path for the source (or None for stdin).
+    :return: Parent for the parsed code or syntax error.
+    """
+    logger = _logging.getLogger(__package__)
+    source_name = file or "stdin"
+    try:
+        node = _ast.parse(code, module_name, str(file))
+        try:
+            directives = _Directives.from_text(code, config.disable)
+        except _TokenError as err:
+            directives = _Directives()
+            logger.debug(
+                _FILE_INFO,
+                source_name,
+                f"error parsing comments {err}".lower(),
+            )
+
+        parent = _Parent(node, directives, file, config)
+        logger.debug(_FILE_INFO, source_name, "Parsing Python code successful")
+    except _ast.AstroidSyntaxError as err:
+        logger.debug(_FILE_INFO, source_name, str(err).replace("\n", " "))
+        parent = _Parent(error=_Error.SYNTAX)
+    except RecursionError as err:
+        logger.debug(_FILE_INFO, source_name, str(err).replace("\n", " "))
+        parent = _Parent(error=_Error.RECURSION)
+
+    return parent
+
+
+def parse_from_file(file: _Path, config: _Config) -> _Parent:
+    """Build a Parent from a file containing Python code.
+
+    Reads the file and delegates to parse_from_string. On UnicodeError,
+    returns a Parent with a Unicode error. On syntax error and a non-.py
+    path, returns an empty Parent (not treated as Python).
+
+    :param file: Path to the file to parse.
+    :param config: Configuration object.
+    :return: Parent for the parsed file or an error/empty Parent.
+    """
+    try:
+        code = file.read_text(encoding="utf-8")
+        module_name = str(file)[:-3].replace(_os.sep, ".").replace("-", "_")
+        parent = parse_from_string(code, config, module_name, file)
+    except UnicodeDecodeError as err:
+        logger = _logging.getLogger(__package__)
+        logger.debug(_FILE_INFO, file, str(err).replace("\n", " "))
+        parent = _Parent(error=_Error.UNICODE)
+
+    if parent.error is not None and not file.name.endswith(".py"):
+        parent = _Parent()
+
+    return parent

{docsig-0.81.2 → docsig-0.82.0}/docsig/_report.py

@@ -10,11 +10,14 @@ return the highest exit code.
 
 from __future__ import annotations as _
 
-import contextlib
+import contextlib as _contextlib
+import sys as _sys
 import typing as _t
+from warnings import warn as _warn
 
 from astroid.nodes.scoped_nodes import scoped_nodes as _scoped_nodes
 
+from ._config import Config as _Config
 from ._module import Error as _Error
 from ._module import Function as _Function
 from ._stub import UNNAMED as _UNNAMED
@@ -24,14 +27,19 @@ from ._stub import Params as _Params
 from ._stub import RetType as _RetType
 from ._utils import almost_equal as _almost_equal
 from ._utils import sentence_tokenizer as _sentence_tokenizer
+from .messages import NEW as _NEW
+from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E
 from .messages import Message as _Message
-from .messages import Messages as _Messages
 
 _MIN_MATCH = 0.8
 _MAX_MATCH = 1.0
 
 
+class Failures(_t.List["Failure"]):
+    """Sequence of Failure instances (one per function checked)."""
+
+
 class Failed(_t.NamedTuple):
     """Single reported issue."""
 
@@ -51,21 +59,17 @@ class Failure(_t.List[Failed]):
     violation.
 
     :param func: Function under check.
-    :param target: List of errors to target.
-    :param check_property_returns: Run return checks on properties.
+    :param config: Configuration object.
     """
 
-    def __init__(
-        self,
-        func: _Function,
-        target: _Messages,
-        check_property_returns: bool,
-    ) -> None:
+    def __init__(self, func: _Function, config: _Config) -> None:
         super().__init__()
         self._retcode = 0
         self._func = func
-        if target:
-            self._func.messages.extend(i for i in _E.all if i not in target)
+        if config.target:
+            self._func.messages.extend(
+                i for i in _E.all if i not in config.target
+            )
 
         self._name = self._func.name
         if (
@@ -89,7 +93,7 @@ class Failure(_t.List[Failed]):
                     sig = self._func.signature.args.get(index)
                     self._sig4xx_parameters(doc, sig)
 
-                self._sig5xx_returns(check_property_returns)
+                self._sig5xx_returns(config.check.property_returns)
 
         self.sort()
 
@@ -139,7 +143,7 @@ class Failure(_t.List[Failed]):
             # then we know that they aren't almost equal, param1 is
             # missing and does need to be inserted in the docstring
             if is_equal:
-                with contextlib.suppress(IndexError):
+                with _contextlib.suppress(IndexError):
                     is_equal = to[count].name != from_[count + 1].name
 
             if not is_equal:
@@ -157,6 +161,13 @@ class Failure(_t.List[Failed]):
                 else:
                     # unknown-inline-directive
                     self._add(_E[2], directive=comment.kind)
+            elif not comment.isvalidflag:
+                if comment.ismodule:
+                    # unknown-module-directive-flag
+                    self._add(_E[6], directive=comment.kind, flag=comment.flag)
+                else:
+                    # unknown-inline-directive-flag
+                    self._add(_E[7], directive=comment.kind, flag=comment.flag)
             else:
                 for rule in comment:
                     if not rule.isknown:
@@ -316,6 +327,8 @@ class Failure(_t.List[Failed]):
             self._retcode = 123
         if self._func.error == _Error.UNICODE:
             self._add(_E[902])
+        if self._func.error == _Error.RECURSION:
+            self._add(_E[903])
 
     @property
     def name(self) -> str:
@@ -333,5 +346,48 @@ class Failure(_t.List[Failed]):
         return self._retcode
 
 
-class Failures(_t.List[Failure]):
-    """Sequence of Failure instances (one per function checked)."""
+def report(
+    failures: Failures,
+    config: _Config,
+    file: str | None = None,
+) -> int:
+    """Print failures to stdout and return the highest exit code.
+
+    Iterates over failures, prints each with path, line header, and
+    messages, then returns the maximum retcode (0 or non-zero).
+
+    :param failures: Failures to print (one Failure per function).
+    :param config: Config for ANSI and formatting.
+    :param file: Module path when failures came from a file (optional).
+    :return: Exit code (non-zero if any check failed).
+    """
+    retcodes = [0]
+    for failure in failures:
+        retcodes.append(failure.retcode)
+        path_prefix = f"{file}:" if file is not None else ""
+        header = f"{path_prefix}{failure.lineno} in {failure.name}"
+        if not config.no_ansi and _sys.stdout.isatty():
+            header = f"\033[35m{header}\033[0m"
+
+        print(header)
+        for item in failure:
+            extra = None
+            if item.hint:
+                extra = f"hint: {item.hint}"
+
+            if item.new:
+                extra = "warning: please remember to fix this or disable it"
+                _warn(_NEW.format(ref=item.ref), FutureWarning, stacklevel=3)
+
+            print(
+                "    "
+                + _TEMPLATE.format(
+                    ref=item.ref,
+                    description=item.description,
+                    symbolic=item.symbolic,
+                ),
+            )
+            if extra is not None:
+                print(f"    {extra}")
+
+    return max(retcodes)

{docsig-0.81.2 → docsig-0.82.0}/docsig/_stub.py

@@ -16,6 +16,8 @@ from enum import Enum as _Enum
 import astroid as _ast
 import sphinx.ext.napoleon as _s
 
+from ._config import Ignore as _Ignore
+
 # no function will accidentally have this name
 UNNAMED = "-1000"
 
@@ -100,11 +102,11 @@ class Param:
         indent: int = 0,
         closing_token: str = ":",
     ) -> None:
-        self.kind = kind
-        self.name = name
-        self.description = description
-        self.indent = indent
-        self.closing_token = closing_token
+        self._kind = kind
+        self._name = name
+        self._description = description
+        self._indent = indent
+        self._closing_token = closing_token
 
     def __eq__(self, other: object) -> bool:
         iseq = False
@@ -125,33 +127,52 @@ class Param:
         """True if the parameter name starts with an underscore."""
         return str(self.name).startswith("_")
 
+    @property
+    def kind(self) -> DocType:
+        """Type of the param."""
+        return self._kind
+
+    @property
+    def name(self) -> str | None:
+        """Name of the param."""
+        return self._name
+
+    @property
+    def description(self) -> str | None:
+        """Description of param."""
+        return self._description
+
+    @property
+    def indent(self) -> int:
+        """Number of spaces in the indent."""
+        return self._indent
+
+    @property
+    def closing_token(self) -> str:
+        """Token used to terminate the param name definition."""
+        return self._closing_token
+
 
 class Params(_t.List[Param]):
     """A list-like collection of params.
 
-    :param ignore_args: Ignore args prefixed with an asterisk.
-    :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
+    :param ignore: Configuration object for what to ignore.
     """
 
-    def __init__(
-        self,
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
-    ) -> None:
+    def __init__(self, ignore: _Ignore) -> None:
         super().__init__()
-        self._ignore_args = ignore_args
-        self._ignore_kwargs = ignore_kwargs
+        self._ignore = ignore
         self._duplicates: list[Param] = []
 
     def append(self, value: Param) -> None:
         if not value.isprotected and any(
             (
                 value.kind == DocType.PARAM,
-                (value.kind == DocType.ARG and not self._ignore_args),
+                (value.kind == DocType.ARG and not self._ignore.args),
                 (
                     value.kind == DocType.KWARG
                     and not (
-                        self._ignore_kwargs
+                        self._ignore.kwargs
                         or any(i.kind == DocType.KWARG for i in self)
                     )
                 ),
@@ -198,12 +219,8 @@ class Params(_t.List[Param]):
 
 
 class _Stub:
-    def __init__(
-        self,
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
-    ) -> None:
-        self._args = Params(ignore_args, ignore_kwargs)
+    def __init__(self, ignore: _Ignore | None = None) -> None:
+        self._args = Params(ignore or _Ignore())
         self._returns = False
 
     @property
@@ -222,18 +239,16 @@ class Signature(_Stub):
 
     :param rettype: Kind of return (none, some, untyped).
     :param returns: True if return is declared in the signature.
-    :param ignore_args: Ignore args prefixed with an asterisk.
-    :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
+    :param ignore: Configuration object for what to ignore.
     """
 
     def __init__(
         self,
         rettype: RetType = RetType.NONE,
         returns: bool = False,
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
+        ignore: _Ignore | None = None,
     ) -> None:
-        super().__init__(ignore_args, ignore_kwargs)
+        super().__init__(ignore or _Ignore())
         self._rettype = rettype
         self._returns = returns
 
@@ -241,19 +256,17 @@ class Signature(_Stub):
     def from_ast(
         cls,
         node: _ast.nodes.Module | _ast.nodes.ClassDef | _ast.nodes.FunctionDef,
-        ignore_args: bool = False,
-        ignore_kwargs: bool = False,
+        ignore: _Ignore,
     ) -> Signature:
         """Build Signature from a function or class AST node.
 
         :param node: AST node (function, class, or module).
-        :param ignore_args: Ignore args prefixed with an asterisk.
-        :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
+        :param ignore: Configuration object for what to ignore.
         :return: Signature with args and return type.
         """
         rettype = RetType.from_ast(node.returns)
         returns = rettype == RetType.SOME
-        signature = cls(rettype, returns, ignore_args, ignore_kwargs)
+        signature = cls(rettype, returns, ignore)
         # noinspection PyUnresolvedReferences
         for i in [
             a if isinstance(a, Param) else Param(name=a.name)

{docsig-0.81.2 → docsig-0.82.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.81.2"
+__version__ = "0.82.0"

{docsig-0.81.2 → docsig-0.82.0}/docsig/messages.py

@@ -6,7 +6,7 @@ Error message definitions (Message, MessageMap, E) and format templates
 for docstring-check output.
 """
 
-from __future__ import annotations
+from __future__ import annotations as _
 
 import typing as _t
 
@@ -24,6 +24,10 @@ NEW = """\
 """
 
 
+class Messages(_t.List["Message"]):
+    """Sequence of Message instances, typically for one failure."""
+
+
 class Message(_t.NamedTuple):
     """One docstring-check error (ref, description, symbolic, hint)."""
 
@@ -63,10 +67,6 @@ class Message(_t.NamedTuple):
         )
 
 
-class Messages(_t.List[Message]):
-    """Sequence of Message instances, typically for one failure."""
-
-
 class MessageMap(_t.Dict[int, Message]):
     """Mapping from integer key to Message (used for the E registry)."""
 
@@ -125,6 +125,16 @@ E = MessageMap(
             "both mutually exclusive class options configured",
             "mutually-exclusive-options",
         ),
+        6: Message(
+            "SIG006",
+            "unknown module comment flag for {directive} '{flag}'",
+            "unknown-module-directive-flag",
+        ),
+        7: Message(
+            "SIG007",
+            "unknown inline comment flag for {directive} '{flag}'",
+            "unknown-inline-directive-flag",
+        ),
         #: SIG1xx Missing
         101: Message(
             "SIG101",
@@ -252,5 +262,10 @@ E = MessageMap(
             "failed to read file",
             "unicode-decode-error",
         ),
+        903: Message(
+            "SIG903",
+            "maximum recursion depth exceeded",
+            "recursion-error",
+        ),
     },
 )

{docsig-0.81.2 → docsig-0.82.0}/pyproject.toml

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