docsig 0.80.0__tar.gz → 0.80.1__tar.gz

{docsig-0.80.0 → docsig-0.80.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.80.0
+Version: 0.80.1
 Summary: Check signature params for proper documentation
 License: MIT
 License-File: LICENSE
@@ -116,7 +116,7 @@ Commandline
                   [--check-property-returns] [--check-protected]
                   [--check-protected-class-methods] [--ignore-args] [--ignore-kwargs]
                   [--ignore-no-params] [-d LIST] [-t LIST] [-e PATTERN] [-E PATH [PATH ...]]
-                  [-i] [-s STR]
+                  [-I] [-s STR]
                   [path [path ...]]
 
     Check signature params for proper documentation
@@ -152,7 +152,7 @@ Commandline
                             regular expression of files or dirs to exclude from checks
       -E PATH [PATH ...], --excludes PATH [PATH ...]
                             path glob patterns to exclude from checks
-      -i, --include-ignored
+      -I, --include-ignored
                             check files even if they match a gitignore pattern
       -s STR, --string STR  string to parse instead of files
 
@@ -184,7 +184,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.80.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.80.1, 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.80.0
+        rev: v0.80.1
         hooks:
           - id: docsig
             args:
@@ -289,7 +289,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.80.0
+              - docsig==0.80.1
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.80.0 → docsig-0.80.1}/README.rst

@@ -87,7 +87,7 @@ Commandline
                   [--check-property-returns] [--check-protected]
                   [--check-protected-class-methods] [--ignore-args] [--ignore-kwargs]
                   [--ignore-no-params] [-d LIST] [-t LIST] [-e PATTERN] [-E PATH [PATH ...]]
-                  [-i] [-s STR]
+                  [-I] [-s STR]
                   [path [path ...]]
 
     Check signature params for proper documentation
@@ -123,7 +123,7 @@ Commandline
                             regular expression of files or dirs to exclude from checks
       -E PATH [PATH ...], --excludes PATH [PATH ...]
                             path glob patterns to exclude from checks
-      -i, --include-ignored
+      -I, --include-ignored
                             check files even if they match a gitignore pattern
       -s STR, --string STR  string to parse instead of files
 
@@ -155,7 +155,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.80.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.80.1, 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.80.0
+        rev: v0.80.1
         hooks:
           - id: docsig
             args:
@@ -260,7 +260,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.80.0
+              - docsig==0.80.1
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.80.0 → docsig-0.80.1}/docsig/_config.py

@@ -16,7 +16,7 @@ from pathlib import Path as _Path
 import tomli as _tomli
 
 from ._version import __version__
-from .messages import Messages as _Messages
+from .messages import Messages
 
 PYPROJECT_TOML = "pyproject.toml"
 
@@ -133,45 +133,101 @@ def parse_args(args: _t.Sequence[str] | None = None) -> _argparse.Namespace:
         help="increase output verbosity",
     )
     group = parser.add_mutually_exclusive_group(required=False)
+    group.add_argument(
+        "-c",
+        action="store_true",
+        help=_argparse.SUPPRESS,
+        dest="check_class",
+    )
     group.add_argument(
         "--check-class",
         action="store_true",
         help="check class docstrings",
+        dest="check_class",
+    )
+    group.add_argument(
+        "-C",
+        action="store_true",
+        help=_argparse.SUPPRESS,
+        dest="check_class_constructor",
     )
     group.add_argument(
         "--check-class-constructor",
         action="store_true",
         help="check __init__ methods",
+        dest="check_class_constructor",
+    )
+    parser.add_argument(
+        "-D",
+        action="store_true",
+        help=_argparse.SUPPRESS,
+        dest="check_dunders",
     )
     parser.add_argument(
         "--check-dunders",
         action="store_true",
         help="check dunder methods",
+        dest="check_dunders",
+    )
+    parser.add_argument(
+        "-N",
+        action="store_true",
+        help=_argparse.SUPPRESS,
+        dest="check_nested",
     )
     parser.add_argument(
         "--check-nested",
         action="store_true",
         help="check nested functions and classes",
+        dest="check_nested",
+    )
+    parser.add_argument(
+        "-o",
+        action="store_true",
+        help=_argparse.SUPPRESS,
+        dest="check_overridden",
     )
     parser.add_argument(
         "--check-overridden",
         action="store_true",
         help="check overridden methods",
+        dest="check_overridden",
+    )
+    parser.add_argument(
+        "-P",
+        action="store_true",
+        help=_argparse.SUPPRESS,
+        dest="check_property_returns",
     )
     parser.add_argument(
         "--check-property-returns",
         action="store_true",
         help="check property return values",
+        dest="check_property_returns",
+    )
+    parser.add_argument(
+        "-p",
+        action="store_true",
+        help=_argparse.SUPPRESS,
+        dest="check_protected",
     )
     parser.add_argument(
         "--check-protected",
         action="store_true",
         help="check protected functions and classes",
+        dest="check_protected",
+    )
+    parser.add_argument(
+        "-m",
+        action="store_true",
+        help=_argparse.SUPPRESS,
+        dest="check_protected_class_methods",
     )
     parser.add_argument(
         "--check-protected-class-methods",
         action="store_true",
         help="check public methods belonging to protected classes",
+        dest="check_protected_class_methods",
     )
     parser.add_argument(
         "--ignore-args",
@@ -183,10 +239,22 @@ def parse_args(args: _t.Sequence[str] | None = None) -> _argparse.Namespace:
         action="store_true",
         help="ignore kwargs prefixed with two asterisks",
     )
+    parser.add_argument(
+        "-i",
+        action="store_true",
+        help=_argparse.SUPPRESS,
+        dest="ignore_no_params",
+    )
     parser.add_argument(
         "--ignore-no-params",
         action="store_true",
         help="ignore docstrings where parameters are not documented",
+        dest="ignore_no_params",
+    )
+    parser.add_argument(
+        "--ignore-typechecker",
+        action="store_true",
+        help=_argparse.SUPPRESS,
     )
     parser.add_argument(
         "-d",
@@ -220,7 +288,7 @@ def parse_args(args: _t.Sequence[str] | None = None) -> _argparse.Namespace:
         help="path glob patterns to exclude from checks",
     )
     parser.add_argument(
-        "-i",
+        "-I",
         "--include-ignored",
         action="store_true",
         help="check files even if they match a gitignore pattern",
@@ -287,11 +355,11 @@ class Config:
     takes a single config object instead of many parameters.
     """
 
-    check: Check
-    ignore: Ignore
-    target: _Messages = _field(default_factory=list)
-    disable: _Messages = _field(default_factory=list)
-    exclude: str | None = None
+    check: Check = _field(default_factory=Check)
+    ignore: Ignore = _field(default_factory=Ignore)
+    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
     include_ignored: bool = False

{docsig-0.80.0 → docsig-0.80.1}/docsig/_core.py

@@ -9,6 +9,7 @@ import logging as _logging
 import os as _os
 import sys as _sys
 import typing as _t
+import warnings as _warnings
 from pathlib import Path as _Path
 
 import astroid as _ast
@@ -27,8 +28,28 @@ from ._report import Failure as _Failure
 from ._report import Failures as _Failures
 from ._utils import print_checks as _print_checks
 from .messages import TEMPLATE as _TEMPLATE
+from .messages import E as _E
 from .messages import Messages as _Messages
 
+_DEFAULT_EXCLUDES = """\
+(?x)^(
+    |\\.?venv[\\\\/].*
+    |\\.git[\\\\/].*
+    |\\.hg[\\\\/].*
+    |\\.idea[\\\\/].*
+    |\\.mypy_cache[\\\\/].*
+    |\\.nox[\\\\/].*
+    |\\.pytest_cache[\\\\/].*
+    |\\.svn[\\\\/].*
+    |\\.tox[\\\\/].*
+    |\\.vscode[\\\\/].*
+    |_?build[\\\\/].*
+    |.*[\\\\/]__pycache__[\\\\/].*
+    |dist[\\\\/].*
+    |node_modules[\\\\/].*
+)$
+"""
+
 
 def setup_logger(verbose: bool) -> None:
     """Setup docsig logger.
@@ -96,17 +117,10 @@ def _run_check(
             _run_check(func, child, config, failures)
 
 
-def _derive_module_name(file_path: str | _Path) -> str:
-    converted = _os.path.splitext(str(file_path))[0]
-    converted = converted.replace(_os.sep, ".")
-    converted = converted.replace("-", "_")
-    return converted
-
-
 def _from_file(path: _Path, config: _Config) -> _Parent:
     try:
         code = path.read_text(encoding="utf-8")
-        parent = _parse_from_string(
+        parent = _from_str(
             context={
                 "code": code,
                 "module_name": _derive_module_name(path),
@@ -126,7 +140,7 @@ def _from_file(path: _Path, config: _Config) -> _Parent:
     return parent
 
 
-def _parse_from_string(
+def _from_str(
     context: dict[str, _t.Any],
     config: _Config,
     path: _Path | None = None,
@@ -150,8 +164,8 @@ def _parse_from_string(
     return parent
 
 
-def _run_checks(module: _Parent, config: _Config) -> _Failures:
-    failures: _Failures = []
+def _get_failures(module: _Parent, config: _Config) -> _Failures:
+    failures = _Failures()
     for top_level in module.children:
         if (
             not top_level.isprotected
@@ -192,6 +206,56 @@ def _report(
     return max(retcodes)
 
 
+def _run_docsig(
+    *path: str | _Path,
+    string: str | None = None,
+    config: _Config,
+) -> int:
+    setup_logger(config.verbose)
+    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_)))
+
+        return max(retcodes)
+
+    module = _from_str({"code": string}, config)
+    failures = _get_failures(module, config)
+    return _report(failures, config)
+
+
+def handle_deprecations(
+    ignore_typechecker: bool,
+    disable: list,
+    messages: list,
+    stacklevel: int,
+) -> None:
+    """Warn for deprecated arguments.
+
+    :param ignore_typechecker: Whether using or not.
+    :param disable: List to add messages to.
+    :param messages: Messages.
+    :param stacklevel: Warning stacklevel.
+    """
+    if ignore_typechecker:
+        _warnings.warn(
+            "ignore-typechecker is deprecated, use disable for SIG5xx instead",
+            category=FutureWarning,
+            stacklevel=stacklevel,
+        )
+        disable.extend(messages)
+
+
 def runner(path: _Path, config: _Config) -> _Failures:
     """Per path runner.
 
@@ -200,7 +264,7 @@ def runner(path: _Path, config: _Config) -> _Failures:
     :return: Exit status for whether the test failed or not.
     """
     module = _from_file(path, config)
-    return _run_checks(module, config)
+    return _get_failures(module, config)
 
 
 @_decorators.parse_msgs
@@ -221,6 +285,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     ignore_no_params: bool = False,
     ignore_args: bool = False,
     ignore_kwargs: bool = False,
+    ignore_typechecker: bool = False,  # deprecated
     no_ansi: bool = False,
     verbose: bool = False,
     target: _Messages | None = None,
@@ -256,6 +321,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         documented
     :param ignore_args: Ignore args prefixed with an asterisk.
     :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
+    :param ignore_typechecker: Ignore checking return values.
     :param no_ansi: Disable ANSI output.
     :param verbose: Increase output verbosity.
     :param target: List of errors to target.
@@ -265,6 +331,24 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     :param excludes: Files or dirs to exclude from checks.
     :return: Exit status for whether a test failed or not.
     """
+    disable = disable or _Messages()
+    handle_deprecations(
+        ignore_typechecker,
+        disable,
+        [
+            _E[501],
+            _E[502],
+            _E[503],
+            _E[504],
+            _E[505],
+            _E[506],
+        ],
+        stacklevel=5,
+    )
+    exclude_ = [_DEFAULT_EXCLUDES]
+    if exclude is not None:
+        exclude_.append(exclude)
+
     check = _Check(
         class_=check_class,
         class_constructor=check_class_constructor,
@@ -287,30 +371,16 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         ignore=ignore,
         no_ansi=no_ansi,
         verbose=verbose,
-        target=target or [],
-        disable=disable or [],
-        exclude=exclude,
+        target=target or _Messages(),
+        disable=disable,
+        exclude=exclude_,
         excludes=excludes,
     )
-    setup_logger(config.verbose)
-    if config.list_checks:
-        return int(bool(_print_checks()))  # type: ignore
+    return _run_docsig(*path, string=string, config=config)
 
-    if string:
-        module = _parse_from_string({"code": string}, config)
-        failures = _run_checks(module, config)
-        return _report(failures, config)
 
-    retcodes = [0]
-    paths = _Paths(
-        *path,
-        patterns=config.exclude,
-        excludes=config.excludes,
-        include_ignored=config.include_ignored,
-    )
-    for path_ in paths:
-        failures = runner(path_, config)
-        retcode = _report(failures, config, str(path_))
-        retcodes.append(retcode)
-
-    return max(retcodes)
+def _derive_module_name(file_path: str | _Path) -> str:
+    converted = _os.path.splitext(str(file_path))[0]
+    converted = converted.replace(_os.sep, ".")
+    converted = converted.replace("-", "_")
+    return converted

{docsig-0.80.0 → docsig-0.80.1}/docsig/_directives.py

@@ -12,8 +12,6 @@ from io import StringIO as _StringIO
 from .messages import E as _E
 from .messages import Messages as _Messages
 
-Comments: _t.TypeAlias = _t.List["Comment"]
-
 
 class Comment(_Messages):
     """Represents a comment directive.
@@ -74,6 +72,10 @@ class Comment(_Messages):
         return None
 
 
+class Comments(_t.List[Comment]):
+    """List of comments."""
+
+
 class Directives(_t.Dict[int, _t.Tuple[Comments, _Messages]]):
     """Data for directives:
 
@@ -100,7 +102,7 @@ class Directives(_t.Dict[int, _t.Tuple[Comments, _Messages]]):
         """
         directives = cls()
         fin = _StringIO(text)
-        comments: Comments = []
+        comments = Comments()
         for line in _tokenize.generate_tokens(fin.readline):
             # do nothing for these line types
             if line.type in (_tokenize.NAME, _tokenize.OP, _tokenize.DEDENT):
@@ -110,8 +112,8 @@ class Directives(_t.Dict[int, _t.Tuple[Comments, _Messages]]):
             # scope, but do not update the global comments and messages
             # unless it is confirmed that the comment is a module level
             # directive
-            scoped_comments: Comments = list(comments)
-            scoped_messages = list(messages)
+            scoped_comments = Comments(comments)
+            scoped_messages = _Messages(messages)
             lineno, col = line.start
             if line.type == _tokenize.COMMENT:
                 comment = Comment.parse(line.string, col)
@@ -120,7 +122,7 @@ class Directives(_t.Dict[int, _t.Tuple[Comments, _Messages]]):
                     if comment.disable:
                         scoped_messages.extend(comment)
                     elif comment.enable:
-                        scoped_messages = list(
+                        scoped_messages = _Messages(
                             i for i in messages if i not in comment
                         )
 

{docsig-0.80.0 → docsig-0.80.1}/docsig/_files.py

@@ -16,24 +16,6 @@ from pathspec.patterns import GitWildMatchPattern as _GitWildMatchPattern
 from wcmatch.pathlib import Path as _WcPath
 
 FILE_INFO = "%s: %s"
-_DEFAULT_EXCLUDES = """\
-(?x)^(
-    |\\.?venv[\\\\/].*
-    |\\.git[\\\\/].*
-    |\\.hg[\\\\/].*
-    |\\.idea[\\\\/].*
-    |\\.mypy_cache[\\\\/].*
-    |\\.nox[\\\\/].*
-    |\\.pytest_cache[\\\\/].*
-    |\\.svn[\\\\/].*
-    |\\.tox[\\\\/].*
-    |\\.vscode[\\\\/].*
-    |_?build[\\\\/].*
-    |.*[\\\\/]__pycache__[\\\\/].*
-    |dist[\\\\/].*
-    |node_modules[\\\\/].*
-)$
-"""
 
 
 class _Gitignore(_PathSpec):
@@ -99,15 +81,13 @@ class Paths(_t.List[_Path]):
     def __init__(
         self,
         *paths: _Path | str,
-        patterns: str | None = None,
+        patterns: list[str],
         excludes: list[str] | None = None,
         include_ignored: bool = False,
     ) -> None:
         super().__init__()
-        exclude = [_DEFAULT_EXCLUDES]
-        if patterns is not None:
-            exclude.append(patterns)
-
+        self._patterns = patterns
+        self._excludes = excludes or []
         self._include_ignored = include_ignored
         self._gitignore = _Gitignore()
         self._logger = _logging.getLogger(__package__)
@@ -116,8 +96,8 @@ class Paths(_t.List[_Path]):
 
         for path in list(self):
             if str(path) != "." and (
-                any(_re.match(i, str(path)) for i in exclude)
-                or any(_glob(path, i) for i in excludes or [])
+                any(_re.match(i, str(path)) for i in self._patterns)
+                or any(_glob(path, i) for i in self._excludes)
             ):
                 self._logger.debug(
                     FILE_INFO,

docsig-0.80.1/docsig/_main.py

@@ -0,0 +1,62 @@
+"""
+docsig._main
+============
+
+Contains package entry point.
+"""
+
+from __future__ import annotations as _
+
+import sys as _sys
+import warnings as _warnings
+
+from ._config import parse_args as _parse_args
+from ._core import docsig as _docsig
+from ._hooks import excepthook as _excepthook
+
+
+def _warn_on_deprecated_short_flags() -> None:
+    deprecated_short_flags = {
+        "-c": "--check-class",
+        "-C": "--check-class-constructor",
+        "-D": "--check-dunders",
+        "-m": "--check-protected-class-methods",
+        "-N": "--check-nested",
+        "-o": "--check-overridden",
+        "-p": "--check-protected",
+        "-P": "--check-property-returns",
+        "-i": "--ignore-no-params",
+    }
+    raw_args = _sys.argv[1:]
+    expanded_flags = []
+    for arg in raw_args:
+        if arg.startswith("--") or not arg.startswith("-") or arg == "-":
+            expanded_flags.append(arg)
+        elif len(arg) > 2:
+            expanded_flags.extend([f"-{ch}" for ch in arg[1:]])
+        else:
+            expanded_flags.append(arg)
+
+    used_flags = set(expanded_flags)
+    for short, long in deprecated_short_flags.items():
+        if short in used_flags:
+            _warnings.warn(
+                f"short option '{short}' is deprecated, use '{long}' instead",
+                category=FutureWarning,
+                stacklevel=2,
+            )
+
+
+def main() -> str | int:
+    """Main function for package.
+
+    Collect config and arguments for the commandline.
+
+    :return: Exit status for whether the test failed or not.
+    """
+    _warn_on_deprecated_short_flags()
+    a = _parse_args()
+    _excepthook(a.no_ansi)
+    kwargs = vars(a)
+    path = kwargs.pop("path")
+    return _docsig(*path, **kwargs)

{docsig-0.80.0 → docsig-0.80.1}/docsig/_module.py

@@ -19,10 +19,6 @@ from ._stub import RetType as _RetType
 from ._stub import Signature as _Signature
 from .messages import Messages as _Messages
 
-_Imports: _t.TypeAlias = dict[str, str]
-_Overloads: _t.TypeAlias = _t.Dict[str, "Function"]
-_Children: _t.TypeAlias = _t.List[_t.Union["Parent", "Function"]]
-
 
 class Error(_Enum):
     """Represents an unrecoverable error."""
@@ -31,6 +27,10 @@ class Error(_Enum):
     UNICODE = 2
 
 
+class _Imports(_t.Dict[str, str]):
+    """Represents python imports."""
+
+
 class Parent:  # pylint: disable=too-many-instance-attributes
     """Represents an object that contains functions or methods.
 
@@ -66,21 +66,20 @@ class Parent:  # pylint: disable=too-many-instance-attributes
         error: Error | None = None,
     ) -> None:
         super().__init__()
+        self._name = "module"
         self._error = error
-        self._directives = directives or _Directives()
         self._ignore_args = ignore_args
         self._ignore_kwargs = ignore_kwargs
         self._check_class_constructor = check_class_constructor
-        self._children: _Children = []
-        self._imports: _Imports = imports or {}
-        self._overloads: _Overloads = {}
+        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))
         else:
             self._name = node.name
-            self._parse_ast(node, path)
+            self._parse_ast(node, directives or _Directives(), path)
 
     def _parse_ast(
         self,
@@ -90,20 +89,21 @@ class Parent:  # pylint: disable=too-many-instance-attributes
             | _ast.nodes.FunctionDef
             | _ast.nodes.NodeNG
         ),
+        directives: _Directives,
         path: _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 = self._directives.get(
+        parent_comments, parent_disabled = directives.get(
             node.lineno,
-            ([], []),
+            (_Comments(), _Messages()),
         )
         if hasattr(node, "body"):
             for subnode in node.body:
-                comments, disabled = self._directives.get(
+                comments, disabled = directives.get(
                     subnode.lineno,
-                    ([], []),
+                    (_Comments(), _Messages()),
                 )
                 comments.extend(parent_comments)
                 disabled.extend(parent_disabled)
@@ -118,7 +118,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                     func = Function(
                         subnode,
                         comments,
-                        self._directives,
+                        directives,
                         disabled,
                         path,
                         self._ignore_args,
@@ -144,7 +144,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                     self._children.append(
                         Parent(
                             subnode,
-                            self._directives,
+                            directives,
                             path,
                             self._ignore_args,
                             self._ignore_kwargs,
@@ -153,7 +153,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                         ),
                     )
                 else:
-                    self._parse_ast(subnode, path)
+                    self._parse_ast(subnode, directives, path)
 
     @property
     def isprotected(self) -> bool:
@@ -211,8 +211,8 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
             check_class_constructor,
             imports,
         )
-        self._comments = comments or []
-        self._messages = messages or []
+        self._comments = comments or _Comments()
+        self._messages = messages or _Messages()
         self._parent = None
         self._decorators = None
         self._signature = _Signature()
@@ -366,3 +366,11 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
         :param rettype: The return type of the overloaded signature.
         """
         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.80.0 → docsig-0.80.1}/docsig/_report.py

@@ -18,6 +18,7 @@ from ._stub import Param as _Param
 from ._stub import Params as _Params
 from ._stub import RetType as _RetType
 from ._utils import almost_equal as _almost_equal
+from ._utils import has_bad_return as _has_bad_return
 from ._utils import sentence_tokenizer as _sentence_tokenizer
 from .messages import E as _E
 from .messages import Message as _Message
@@ -27,9 +28,6 @@ _MIN_MATCH = 0.8
 _MAX_MATCH = 1.0
 
 
-Failures: _t.TypeAlias = _t.List["Failure"]
-
-
 class Failed(_t.NamedTuple):
     """Report info object."""
 
@@ -58,9 +56,19 @@ class Failure(_t.List[Failed]):
         super().__init__()
         self._retcode = 0
         self._func = func
+        self._docstring_len = len(self._func.docstring.args)
         if target:
             self._func.messages.extend(i for i in _E.all if i not in target)
 
+        self._name = self._func.name
+        if (
+            self._func.parent is not None
+            and self._func.parent.name
+            and not isinstance(self._func.parent, _scoped_nodes.Module)
+        ):
+            self._name = f"{self._func.parent.name}.{self._func.name}"
+
+        self._check_property_returns = check_property_returns
         if self._func.error is not None:
             self._sig9xx_error()
         else:
@@ -75,23 +83,18 @@ 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()
 
         self.sort()
 
-    def _add(
-        self,
-        value: _Message,
-        hint: bool = False,
-        **kwargs: _t.Any,
-    ) -> None:
+    def _add(self, value: _Message, hint: bool = False, **kwargs) -> None:
         self._retcode = 1
         failed = Failed(
-            self.name,
+            self._name,
             value.ref,
             value.description.format(**kwargs),
             value.symbolic,
-            self.lineno,
+            self._func.lineno,
             value.hint if hint else None,
         )
         if value not in self._func.messages and failed not in self:
@@ -216,9 +219,9 @@ class Failure(_t.List[Failed]):
             # bad-closing-token
             self._add(_E[304], token=doc.closing_token, hint=True)
         if doc.description is not None and not all(
-            i.strip()[0].isupper()
+            stripped[0].isupper()
             for i in _sentence_tokenizer(doc.description)
-            if i and not any(i.startswith(x) for x in (":", ".", "`"))
+            if i and (stripped := i.strip())[0].isalpha()
         ):
             # description is not capitalized
             self._add(_E[305])
@@ -231,7 +234,7 @@ class Failure(_t.List[Failed]):
             if (
                 sig.name in self._func.docstring.args.names
                 or doc.name in self._func.signature.args.names
-            ) and len(self._func.docstring.args) > 1:
+            ) and self._docstring_len > 1:
                 # params-out-of-order
                 self._add(_E[402])
             elif (
@@ -246,9 +249,9 @@ class Failure(_t.List[Failed]):
                     # param-not-equal-to-arg
                     self._add(_E[404])
 
-    def _sig5xx_returns(self, check_property_returns: bool) -> None:
+    def _sig5xx_returns(self) -> None:
         if not self._func.isinit and not (
-            self._func.isproperty and not check_property_returns
+            self._func.isproperty and not self._check_property_returns
         ):
             # no types, cannot know either way
             if self._func.signature.rettype == _RetType.UNTYPED:
@@ -264,14 +267,9 @@ class Failure(_t.List[Failed]):
             # return-type is some, so return should be documented
             elif self._func.signature.returns:
                 # return-missing
-                lines = str(self._func.docstring.string).splitlines()
                 self._add(
                     _E[503],
-                    hint=(
-                        len(lines) > 1
-                        and "return" in lines[-1]
-                        and ":param" not in lines[-1]
-                    ),
+                    hint=_has_bad_return(str(self._func.docstring.string)),
                 )
         elif self._func.docstring.returns:
             # this method is init, so no return should be documented
@@ -279,7 +277,7 @@ class Failure(_t.List[Failed]):
                 # class-return-documented
                 self._add(_E[504], hint=True)
             # method is property and not set to document property
-            elif self._func.isproperty and not check_property_returns:
+            elif self._func.isproperty and not self._check_property_returns:
                 # return-documented-for-property
                 self._add(_E[505], hint=True)
 
@@ -294,14 +292,7 @@ class Failure(_t.List[Failed]):
     @property
     def name(self) -> str:
         """Function name."""
-        if (
-            self._func.parent is not None
-            and self._func.parent.name
-            and not isinstance(self._func.parent, _scoped_nodes.Module)
-        ):
-            return f"{self._func.parent.name}.{self._func.name}"
-
-        return self._func.name
+        return self._name
 
     @property
     def lineno(self) -> int:
@@ -312,3 +303,7 @@ class Failure(_t.List[Failed]):
     def retcode(self) -> int:
         """How to exit the program."""
         return self._retcode
+
+
+class Failures(_t.List[Failure]):
+    """Sequence of failed functions."""

{docsig-0.80.0 → docsig-0.80.1}/docsig/_stub.py

@@ -80,7 +80,7 @@ class DocType(_Enum):
 # todo: consider a parent object that can be used for returns that do
 # todo: not include the name attribute
 class Param:
-    """Represents a docstring or signature param.
+    """A tuple of param types and their names.
 
     :param kind: The type of the parameter.
     :param name: The name of the parameter.
@@ -98,11 +98,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
@@ -123,31 +123,6 @@ class Param:
         """Boolean value for whether this parameter is protected."""
         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.

{docsig-0.80.0 → docsig-0.80.1}/docsig/_utils.py

@@ -54,6 +54,25 @@ def print_checks() -> None:
         print(msg.fstring(_TEMPLATE))
 
 
+def has_bad_return(string: str) -> bool:
+    """Search for return documented with poor syntax.
+
+    Put this here in case the function increases in complexity.
+
+    Do more than search the docstring for the word return as return
+    statements come last, so only search the last line params can also
+    come last, so make sure it is not a param declaration.
+
+    :param string: Docstring to check.
+    :return: Boolean value indicating if a function has a bad return
+        statement.
+    """
+    lines = string.splitlines()
+    return (
+        len(lines) > 1 and "return" in lines[-1] and ":param" not in lines[-1]
+    )
+
+
 def sentence_tokenizer(text: str) -> list[str]:
     """Split text into sentences.
 

{docsig-0.80.0 → docsig-0.80.1}/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.80.0"
+__version__ = "0.80.1"

{docsig-0.80.0 → docsig-0.80.1}/docsig/messages.py

@@ -17,9 +17,6 @@ TEMPLATE = "{ref}: {description} ({symbolic})"
 FLAKE8 = "{ref} {description} ({symbolic})"
 
 
-Messages: _t.TypeAlias = _t.List["Message"]
-
-
 class Message(_t.NamedTuple):
     """Represents an error message."""
 
@@ -57,6 +54,10 @@ class Message(_t.NamedTuple):
         )
 
 
+class Messages(_t.List[Message]):
+    """List of messages."""
+
+
 class MessageMap(_t.Dict[int, Message]):
     """Messages mapped under an integer version of their codes."""
 
@@ -78,12 +79,12 @@ class MessageMap(_t.Dict[int, Message]):
         :param refs: List of codes or symbolic references.
         :return: List of message types.
         """
-        return list(self.from_ref(i) for i in refs)
+        return Messages(self.from_ref(i) for i in refs)
 
     @property
     def all(self) -> Messages:
         """Get all messages that aren't a config error."""
-        return list(v for k, v in self.items() if len(str(k)) > 1)
+        return Messages(v for k, v in self.items() if len(str(k)) > 1)
 
 
 # SIGxxx: Error
@@ -142,7 +143,7 @@ E = MessageMap(
             "parameters missing",
             "params-missing",
         ),
-        #: SIG3xx Parameters
+        #: SIG3xx Description
         301: Message(
             "SIG301",
             "description missing from parameter",
@@ -169,7 +170,7 @@ E = MessageMap(
             "description does not begin with a capital letter",
             "description-not-capitalized",
         ),
-        #: SIG4xx Description
+        #: SIG4xx Parameters
         401: Message(
             "SIG401",
             "param not indented correctly",

{docsig-0.80.0 → docsig-0.80.1}/docsig/plugin.py

@@ -1,25 +1,23 @@
 """Flake8 implementation of docsig."""
 
-import ast as _ast
-import os as _os
-import sys as _sys
-import typing as _t
-from argparse import Namespace as _Namespace
-from pathlib import Path as _Path
+import ast
+import os
+import sys
+import typing as t
+from argparse import SUPPRESS, Namespace
+from pathlib import Path
 
 from ._config import Check as _Check
 from ._config import Config as _Config
 from ._config import Ignore as _Ignore
 from ._config import get_config as _get_config
 from ._config import merge_configs as _merge_configs
-from ._core import runner as _runner
-from ._core import setup_logger as _setup_logger
+from ._core import handle_deprecations, runner, setup_logger
 from ._version import __version__
-from .messages import FLAKE8 as _FLAKE8
-from .messages import E as _E
+from .messages import FLAKE8, E
 
-_Flake8Error = _t.Tuple[int, int, str, _t.Type[_t.Any]]
-_sys.path.append(_os.path.abspath(_os.getcwd()))
+Flake8Error = t.Tuple[int, int, str, t.Type]
+sys.path.append(os.path.abspath(os.getcwd()))
 
 
 class Docsig:
@@ -32,9 +30,9 @@ class Docsig:
     off_by_default = False
     name = __package__
     version = __version__
-    a = _Namespace()
+    a = Namespace()
 
-    def __init__(self, tree: _ast.Module, filename: str) -> None:
+    def __init__(self, tree: ast.Module, filename: str) -> None:
         _tree = tree  # noqa
         self.filename = filename
 
@@ -43,17 +41,11 @@ class Docsig:
     # might require that flake8 actually be installed, which is not a
     # requirement for this package
     @classmethod
-    def add_options(cls, parser: _t.Any) -> None:
+    def add_options(cls, parser: t.Any) -> None:
         """Add flake8 commandline and config options.
 
         :param parser: Flake8 option manager.
         """
-        parser.add_option(
-            "--sig-verbose",
-            action="store_true",
-            parse_from_config=True,
-            help="increase output verbosity",
-        )
         parser.add_option(
             "--sig-check-class",
             action="store_true",
@@ -64,10 +56,7 @@ class Docsig:
             "--sig-check-class-constructor",
             action="store_true",
             parse_from_config=True,
-            help=(
-                "check __init__ methods (mutually incompatible with"
-                " --sig-check-class)"
-            ),
+            help="check __init__ methods. Note: mutually incompatible with -c",
         )
         parser.add_option(
             "--sig-check-dunders",
@@ -75,6 +64,12 @@ class Docsig:
             parse_from_config=True,
             help="check dunder methods",
         )
+        parser.add_option(
+            "--sig-check-protected-class-methods",
+            action="store_true",
+            parse_from_config=True,
+            help="check public methods belonging to protected classes",
+        )
         parser.add_option(
             "--sig-check-nested",
             action="store_true",
@@ -88,22 +83,22 @@ class Docsig:
             help="check overridden methods",
         )
         parser.add_option(
-            "--sig-check-property-returns",
+            "--sig-check-protected",
             action="store_true",
             parse_from_config=True,
-            help="check property return values",
+            help="check protected functions and classes",
         )
         parser.add_option(
-            "--sig-check-protected",
+            "--sig-check-property-returns",
             action="store_true",
             parse_from_config=True,
-            help="check protected functions and classes",
+            help="check property return values",
         )
         parser.add_option(
-            "--sig-check-protected-class-methods",
+            "--sig-ignore-no-params",
             action="store_true",
             parse_from_config=True,
-            help="check public methods belonging to protected classes",
+            help="ignore docstrings where parameters are not documented",
         )
         parser.add_option(
             "--sig-ignore-args",
@@ -118,39 +113,54 @@ class Docsig:
             help="ignore kwargs prefixed with two asterisks",
         )
         parser.add_option(
-            "--sig-ignore-no-params",
+            "--sig-ignore-typechecker",
             action="store_true",
             parse_from_config=True,
-            help="ignore docstrings where parameters are not documented",
+            help=SUPPRESS,
+        )
+        parser.add_option(
+            "--sig-verbose",
+            action="store_true",
+            parse_from_config=True,
+            help="increase output verbosity",
         )
 
     @classmethod
-    def parse_options(cls, a: _Namespace) -> None:
+    def parse_options(cls, a: Namespace) -> None:
         """Parse flake8 options into an instance-accessible dict.
 
         :param a: Argparse namespace.
         """
+        if getattr(a, "sig_ignore_typechecker", False):
+            a.extend_ignore = list(a.extend_ignore or [])
+            handle_deprecations(
+                getattr(a, "sig_ignore_typechecker", False),
+                a.extend_ignore,
+                ["SIG501", "SIG502", "SIG503", "SIG504", "SIG505", "SIG506"],
+                stacklevel=8,
+            )
+
         cls.a.__dict__ = _merge_configs(
             {k.replace("sig_", ""): v for k, v in a.__dict__.items()},
             _get_config(__package__),
         )
 
-    def run(self) -> _t.Generator[_Flake8Error, None, None]:
+    def run(self) -> t.Generator[Flake8Error, None, None]:
         """Run docsig and possibly yield a flake8 error.
 
         :return: Flake8 error, if there is one.
         """
         if self.a.check_class and self.a.check_class_constructor:
             line = "{msg}".format(
-                msg=_FLAKE8.format(
-                    ref=_E[5].ref,
-                    description=_E[5].description,
-                    symbolic=_E[5].symbolic,
+                msg=FLAKE8.format(
+                    ref=E[5].ref,
+                    description=E[5].description,
+                    symbolic=E[5].symbolic,
                 ),
             )
             yield 0, 0, line, self.__class__
         else:
-            _setup_logger(self.a.verbose)
+            setup_logger(self.a.verbose)
             check = _Check(
                 class_=self.a.check_class,
                 class_constructor=self.a.check_class_constructor,
@@ -171,11 +181,11 @@ class Docsig:
                 ignore=ignore,
                 verbose=self.a.verbose,
             )
-            results = _runner(_Path(self.filename), config)
+            results = runner(Path(self.filename), config)
             for result in results:
                 for info in result:
                     line = "{msg} '{name}'".format(
-                        msg=_FLAKE8.format(
+                        msg=FLAKE8.format(
                             ref=info.ref,
                             description=info.description,
                             symbolic=info.symbolic,

{docsig-0.80.0 → docsig-0.80.1}/pyproject.toml

@@ -11,7 +11,7 @@ line-length = 79
 allow_dirty = true
 commit = true
 commit_args = "-sS"
-current_version = "0.80.0"
+current_version = "0.80.1"
 message = "bump: version {current_version} → {new_version}"
 sign_tags = true
 tag = true
@@ -61,6 +61,7 @@ fail_under = 100
 
 [tool.coverage.run]
 omit = [
+  "*/sitecustomize.py",
   "docs/conf.py",
   "docsig/__main__.py",
   "whitelist.py"
@@ -121,7 +122,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.80.0"
+version = "0.80.1"
 
 [tool.poetry.dependencies]
 Sphinx = ">=7,<9"

docsig-0.80.0/docsig/_main.py

@@ -1,26 +0,0 @@
-"""
-docsig._main
-============
-
-Contains package entry point.
-"""
-
-from __future__ import annotations as _
-
-from ._config import parse_args as _parse_args
-from ._core import docsig as _docsig
-from ._hooks import excepthook as _excepthook
-
-
-def main() -> str | int:
-    """Main function for package.
-
-    Collect config and arguments for the commandline.
-
-    :return: Exit status for whether the test failed or not.
-    """
-    a = _parse_args()
-    _excepthook(a.no_ansi)
-    kwargs = vars(a)
-    path = kwargs.pop("path")
-    return _docsig(*path, **kwargs)