docsig 0.57.0__tar.gz → 0.59.0__tar.gz

{docsig-0.57.0 → docsig-0.59.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.57.0
+Version: 0.59.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -19,7 +19,6 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: Sphinx (>=7.0.0,<8.0.0)
 Requires-Dist: arcon (>=0.4.0)
 Requires-Dist: astroid (>=3.0.1,<4.0.0)
-Requires-Dist: click (>=8.1.7,<9.0.0)
 Requires-Dist: pathspec (>=0.12.1,<0.13.0)
 Project-URL: Documentation, https://docsig.readthedocs.io/en/latest
 Project-URL: Repository, https://github.com/jshwi/docsig
@@ -170,7 +169,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.1.0 (docsig: 0.57.0, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
+    7.1.0 (docsig: 0.59.0, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
 
 And now use `flake8` to lint your files
 
@@ -253,11 +252,13 @@ pre-commit
 
 It can be added to your .pre-commit-config.yaml as follows:
 
+Standalone
+
 .. code-block:: yaml
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.57.0
+        rev: v0.59.0
         hooks:
           - id: docsig
             args:
@@ -266,3 +267,20 @@ It can be added to your .pre-commit-config.yaml as follows:
               - "--check-overridden"
               - "--check-protected"
 
+or integrated with ``flake8``
+
+.. code-block:: yaml
+
+    repos:
+      - repo: https://github.com/PyCQA/flake8
+        rev: "7.1.0"
+        hooks:
+          - id: flake8
+            additional_dependencies:
+              - docsig==0.59.0
+            args:
+              - "--sig-check-class"
+              - "--sig-check-dunders"
+              - "--sig-check-overridden"
+              - "--sig-check-protected"
+

{docsig-0.57.0 → docsig-0.59.0}/README.rst

@@ -143,7 +143,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.1.0 (docsig: 0.57.0, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
+    7.1.0 (docsig: 0.59.0, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
 
 And now use `flake8` to lint your files
 
@@ -226,11 +226,13 @@ pre-commit
 
 It can be added to your .pre-commit-config.yaml as follows:
 
+Standalone
+
 .. code-block:: yaml
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.57.0
+        rev: v0.59.0
         hooks:
           - id: docsig
             args:
@@ -238,3 +240,20 @@ It can be added to your .pre-commit-config.yaml as follows:
               - "--check-dunders"
               - "--check-overridden"
               - "--check-protected"
+
+or integrated with ``flake8``
+
+.. code-block:: yaml
+
+    repos:
+      - repo: https://github.com/PyCQA/flake8
+        rev: "7.1.0"
+        hooks:
+          - id: flake8
+            additional_dependencies:
+              - docsig==0.59.0
+            args:
+              - "--sig-check-class"
+              - "--sig-check-dunders"
+              - "--sig-check-overridden"
+              - "--sig-check-protected"

docsig-0.59.0/docsig/_core.py

@@ -0,0 +1,419 @@
+"""
+docsig._core
+============
+"""
+
+from __future__ import annotations as _
+
+import sys as _sys
+from pathlib import Path as _Path
+
+import astroid as _ast
+
+from . import _decorators
+from ._directives import Directives as _Directives
+from ._files import FILE_INFO as _FILE_INFO
+from ._files import Paths as _Paths
+from ._module import Ast as _Ast
+from ._module import Function as _Function
+from ._module import Parent as _Parent
+from ._report import Failure as _Failure
+from ._report import Failures as _Failures
+from ._utils import pretty_print_error as _pretty_print_error
+from ._utils import print_checks as _print_checks
+from ._utils import vprint as _vprint
+from .messages import TEMPLATE as _TEMPLATE
+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 _run_check(  # pylint: disable=too-many-arguments,too-many-locals
+    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,
+    ignore_typechecker: bool,
+    no_ansi: bool,
+    target: _Messages,
+    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 (
+                child.isinit
+                and not (
+                    (check_class or check_class_constructor)
+                    and not (parent.isprotected and not check_protected)
+                )
+            )
+            and not (child.isdunder and not check_dunders)
+            and not (child.docstring.bare and ignore_no_params)
+        ):
+            failure = _Failure(
+                child, target, check_property_returns, ignore_typechecker
+            )
+            if failure:
+                failures.append(failure)
+
+        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,
+                    ignore_typechecker,
+                    no_ansi,
+                    target,
+                    failures,
+                )
+    else:
+        # this is a class
+        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,
+                ignore_typechecker,
+                no_ansi,
+                target,
+                failures,
+            )
+
+
+def _get_failures(  # pylint: disable=too-many-locals,too-many-arguments
+    module: _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,
+    ignore_typechecker: bool,
+    check_protected_class_methods: bool,
+    no_ansi: bool,
+    target: _Messages,
+) -> _Failures:
+    failures = _Failures()
+    for top_level in module:
+        if (
+            not top_level.isprotected
+            or check_protected
+            or check_protected_class_methods
+        ):
+            _run_check(
+                top_level,
+                module,
+                check_class,
+                check_class_constructor,
+                check_dunders,
+                check_nested,
+                check_overridden,
+                check_protected,
+                check_property_returns,
+                ignore_no_params,
+                ignore_typechecker,
+                no_ansi,
+                target or _Messages(),
+                failures,
+            )
+
+    return failures
+
+
+def _report(
+    failures: _Failures, path: str | None = None, no_ansi: bool = False
+) -> None:
+    for failure in failures:
+        module = f"{path}:" if path is not None else ""
+        header = f"{module}{failure.lineno} in {failure.name}"
+        if not no_ansi and _sys.stdout.isatty():
+            header = f"\033[35m{header}\033[0m"
+
+        print(header)
+        for item in failure:
+            print(
+                "    "
+                + _TEMPLATE.format(
+                    ref=item.ref,
+                    description=item.description,
+                    symbolic=item.symbolic,
+                )
+            )
+            if item.hint:
+                print(f"    hint: {item.hint}")
+
+
+def runner(  # pylint: disable=too-many-locals,too-many-arguments
+    file: str | _Path,
+    disable: _Messages | None = None,
+    check_class: bool = False,
+    check_class_constructor: bool = False,
+    check_dunders: bool = False,
+    check_nested: bool = False,
+    check_overridden: bool = False,
+    check_protected: bool = False,
+    check_property_returns: bool = False,
+    ignore_no_params: bool = False,
+    ignore_args: bool = False,
+    ignore_kwargs: bool = False,
+    ignore_typechecker: bool = False,
+    check_protected_class_methods: bool = False,
+    no_ansi: bool = False,
+    verbose: bool = False,
+    target: _Messages | None = None,
+) -> tuple[_Failures, int]:
+    """Per path runner.
+
+    :param file: Path to check.
+    :param disable: Messages to disable.
+    :param check_class: Check class docstrings.
+    :param check_class_constructor: Check ``__init__`` methods. Note that this
+        is mutually incompatible with check_class.
+    :param check_dunders: Check dunder methods
+    :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.
+    :param ignore_no_params: Ignore docstrings where parameters are not
+        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 check_protected_class_methods: Check public methods belonging
+        to protected classes.
+    :param no_ansi: Disable ANSI output.
+    :param verbose: increase output verbosity.
+    :param target: List of errors to target.
+    :return: Exit status for whether test failed or not.
+    """
+    failures = _Failures()
+    path = _Path(file)
+    string = path.read_text(encoding="utf-8")
+    ast = _Ast.parse(string)
+    if ast.success:
+        _vprint(
+            _FILE_INFO.format(path=path, msg="Parsing Python code successful"),
+            verbose,
+        )
+        module = _Parent(
+            ast.module,
+            _Directives(string, disable or _Messages()),
+            path,
+            ignore_args,
+            ignore_kwargs,
+            check_class_constructor,
+        )
+        failures = _get_failures(
+            module,
+            check_class,
+            check_class_constructor,
+            check_dunders,
+            check_nested,
+            check_overridden,
+            check_protected,
+            check_property_returns,
+            ignore_no_params,
+            ignore_typechecker,
+            check_protected_class_methods,
+            no_ansi,
+            target or _Messages(),
+        )
+        return failures, 0
+
+    if path.name.endswith(".py"):
+        # pass by silently for files that do not end with .py,  may
+        # result in a 123 syntax error exit status in the future
+        print(path, file=_sys.stderr)
+        _pretty_print_error(type(ast.err), str(ast.err), no_ansi=no_ansi)
+        return failures, 1
+
+    _vprint(
+        _FILE_INFO.format(path=path, msg=str(ast.err)),
+        verbose,
+    )
+    return failures, 0
+
+
+@_decorators.parse_msgs
+@_decorators.handle_deprecations
+@_decorators.validate_args
+def docsig(  # pylint: disable=too-many-locals,too-many-arguments
+    *path: str | _Path,
+    string: str | None = None,
+    list_checks: bool = False,
+    check_class: bool = False,
+    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,
+    include_ignored: bool = False,
+    ignore_no_params: bool = False,
+    ignore_args: bool = False,
+    ignore_kwargs: bool = False,
+    ignore_typechecker: bool = False,
+    no_ansi: bool = False,
+    verbose: bool = False,
+    target: _Messages | None = None,
+    disable: _Messages | None = None,
+    exclude: str | None = None,
+) -> int:
+    """Package's core functionality.
+
+    Populate a sequence of module objects before iterating over their
+    top-level functions and classes.
+
+    If any of the functions within the module - and methods within its
+    classes - fail, print the resulting function string representation
+    and report.
+
+    :param path: Path(s) to check.
+    :param string: String to check.
+    :param list_checks: Display a list of all checks and their messages.
+    :param check_class: Check class docstrings.
+    :param check_class_constructor: Check ``__init__`` methods. Note that this
+        is mutually incompatible with check_class.
+    :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.
+    :param include_ignored: Check files even if they match a gitignore
+        pattern.
+    :param ignore_no_params: Ignore docstrings where parameters are not
+        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.
+    :param disable: List of errors to disable.
+    :param exclude: Regular expression of files and dirs to exclude from
+        checks.
+    :return: Exit status for whether test failed or not.
+    """
+    if list_checks:
+        return int(bool(_print_checks()))  # type: ignore
+
+    excludes = [_DEFAULT_EXCLUDES]
+    if exclude is not None:
+        excludes.append(exclude)
+
+    if string is None:
+        retcode = 0
+        paths = _Paths(
+            *tuple(_Path(i) for i in path),
+            excludes=excludes,
+            include_ignored=include_ignored,
+            verbose=verbose,
+        )
+        for file in paths:
+            failures, parse_retcode = runner(
+                file,
+                disable,
+                check_class,
+                check_class_constructor,
+                check_dunders,
+                check_nested,
+                check_overridden,
+                check_protected,
+                check_property_returns,
+                ignore_no_params,
+                ignore_args,
+                ignore_kwargs,
+                ignore_typechecker,
+                check_protected_class_methods,
+                no_ansi,
+                verbose,
+                target,
+            )
+            retcode = retcode or parse_retcode
+            if failures:
+                _report(failures, str(file), no_ansi)
+                retcode = 1
+
+        return retcode
+
+    ast = _Ast.parse(string)
+    if ast.success:
+        _vprint(
+            _FILE_INFO.format(
+                path="stdin", msg="Parsing Python code successful"
+            ),
+            verbose,
+        )
+        module = _Parent(
+            _ast.parse(string),
+            _Directives(string, messages=disable or _Messages()),
+            ignore_args=ignore_args,
+            ignore_kwargs=ignore_kwargs,
+            check_class_constructor=check_class_constructor,
+        )
+        failures = _get_failures(
+            module,
+            check_class,
+            check_class_constructor,
+            check_dunders,
+            check_nested,
+            check_overridden,
+            check_protected,
+            check_property_returns,
+            ignore_no_params,
+            ignore_typechecker,
+            check_protected_class_methods,
+            no_ansi,
+            target or _Messages(),
+        )
+        if failures:
+            _report(failures, no_ansi=no_ansi)
+            return 1
+
+        _vprint(_FILE_INFO.format(path="stdin", msg=str(ast.err)), verbose)
+
+    return 0

docsig-0.59.0/docsig/_files.py

@@ -0,0 +1,118 @@
+"""
+docsig._files
+=============
+"""
+
+from __future__ import annotations as _
+
+import os as _os
+import re as _re
+import typing as _t
+from pathlib import Path as _Path
+
+from pathspec import PathSpec as _PathSpec
+from pathspec.patterns import GitWildMatchPattern as _GitWildMatchPattern
+
+from ._utils import vprint as _vprint
+
+FILE_INFO = "{path}: {msg}"
+
+
+class _Gitignore(_PathSpec):
+    def _get_repo_relative_to(self, path: _Path) -> _Path | None:
+        if (path / ".git" / "HEAD").is_file():
+            return path
+
+        if str(path) == _os.path.abspath(_os.sep):
+            return None
+
+        return self._get_repo_relative_to(path.parent)
+
+    def __init__(self) -> None:
+        patterns = []
+        repo = self._get_repo_relative_to(_Path.cwd())
+        # only consider gitignore patterns valid if inside a git repo
+        # there might be stray gitignore files lying about
+        if repo is not None:
+            # add patterns from all gitignore files
+            # adjust patterns to account for their relative paths
+            for file in repo.rglob(".gitignore"):
+                for pattern in file.read_text(encoding="utf-8").splitlines():
+                    if pattern.startswith("#"):
+                        continue
+
+                    # if pattern starts with "/" then os.path.join will
+                    # consider it in the filesystem root, and it will
+                    # only ever return /pattern
+                    if pattern.startswith("/"):
+                        pattern = pattern[1:]
+
+                    # use os.path.dirname, so it joins without a leading
+                    # "./", like it does with pathlib parent
+                    # use os.path.join so trailing slash is preserved
+                    # replace sep with "/" as, even on windows,
+                    # gitignore patterns only ever use "/"
+                    patterns.append(
+                        _os.path.join(
+                            _os.path.dirname(file.relative_to(repo)),
+                            pattern.strip(),
+                        ).replace(_os.sep, "/")
+                    )
+
+        super().__init__(map(_GitWildMatchPattern, patterns))
+
+
+class Paths(_t.List[_Path]):  # pylint: disable=too-many-instance-attributes
+    """Collect a list of valid paths.
+
+    :param paths: Path(s) to parse ``Module``(s) from.
+    :param excludes: List pf regular expression of files and dirs to
+        exclude from checks.
+    :param include_ignored: Check files even if they match a gitignore
+        pattern.
+    :param verbose: increase output verbosity.
+    """
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        *paths: _Path,
+        excludes: list[str],
+        include_ignored: bool = False,
+        verbose: bool = False,
+    ) -> None:
+        super().__init__()
+        self._excludes = excludes
+        self._include_ignored = include_ignored
+        self._verbose = verbose
+        self._gitignore = _Gitignore()
+        for path in paths:
+            self._populate(path)
+
+        self.sort()
+
+    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 not self._include_ignored and self._gitignore.match_file(root):
+            _vprint(
+                FILE_INFO.format(path=root, msg="in gitignore, skipping"),
+                self._verbose,
+            )
+            return
+
+        if root.is_file():
+            self.append(root)
+
+        if root.is_dir():
+            for path in root.iterdir():
+                self._populate(path)