docsig 0.49.2__tar.gz → 0.51.0__tar.gz

{docsig-0.49.2 → docsig-0.51.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.49.2
+Version: 0.51.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -22,6 +22,7 @@ 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
 Description-Content-Type: text/x-rst
@@ -106,8 +107,9 @@ Commandline
 .. code-block:: console
 
     usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a]
-                             [-k] [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
-                             [path [path ...]]
+                           [-k] [-I] [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST]
+                           [-e PATTERN]
+                           [path [path ...]]
 
     Check signature params for proper documentation
 
@@ -132,6 +134,8 @@ Commandline
                                            documented
       -a, --ignore-args                    ignore args prefixed with an asterisk
       -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
+      -I, --include-ignored                check files even if they match a gitignore
+                                           pattern
       -n, --no-ansi                        disable ansi output
       -S, --summary                        print a summarised report
       -v, --verbose                        increase output verbosity
@@ -223,7 +227,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.49.2
+        rev: v0.51.0
         hooks:
           - id: docsig
             args:

{docsig-0.49.2 → docsig-0.51.0}/README.rst

@@ -78,8 +78,9 @@ Commandline
 .. code-block:: console
 
     usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a]
-                             [-k] [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
-                             [path [path ...]]
+                           [-k] [-I] [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST]
+                           [-e PATTERN]
+                           [path [path ...]]
 
     Check signature params for proper documentation
 
@@ -104,6 +105,8 @@ Commandline
                                            documented
       -a, --ignore-args                    ignore args prefixed with an asterisk
       -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
+      -I, --include-ignored                check files even if they match a gitignore
+                                           pattern
       -n, --no-ansi                        disable ansi output
       -S, --summary                        print a summarised report
       -v, --verbose                        increase output verbosity
@@ -195,7 +198,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.49.2
+        rev: v0.51.0
         hooks:
           - id: docsig
             args:

{docsig-0.49.2 → docsig-0.51.0}/docsig/_config.py

@@ -109,6 +109,12 @@ class Parser(_ArgumentParser):
             action="store_true",
             help="ignore kwargs prefixed with two asterisks",
         )
+        self.add_argument(
+            "-I",
+            "--include-ignored",
+            action="store_true",
+            help="check files even if they match a gitignore pattern",
+        )
         self.add_argument(
             "-n",
             "--no-ansi",

{docsig-0.49.2 → docsig-0.51.0}/docsig/_core.py

@@ -131,6 +131,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     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,
@@ -163,6 +164,8 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     :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.
@@ -188,9 +191,11 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         disable=disable or [],
         string=string,
         excludes=excludes,
+        include_ignored=include_ignored,
         ignore_args=ignore_args,
         ignore_kwargs=ignore_kwargs,
         check_class_constructor=check_class_constructor,
+        no_ansi=no_ansi,
         verbose=verbose,
     )
     display = _Display(no_ansi)
@@ -225,4 +230,4 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     else:
         display.report()
 
-    return int(bool(display))
+    return max(int(bool(display)), modules.retcode)

docsig-0.51.0/docsig/_hooks.py

@@ -0,0 +1,20 @@
+"""
+docsig._hooks
+=============
+"""
+
+import sys as _sys
+from os import environ as _e
+
+from ._utils import pretty_print_error
+
+
+def excepthook(no_ansi: bool = False) -> None:
+    """Print user friendly commandline error if debug not enabled.
+
+    :param no_ansi: Disable ANSI output.
+    """
+    if _e.get("DOCSIG_DEBUG", None) != "1":
+        _sys.excepthook = lambda x, y, _: pretty_print_error(
+            x, str(y), no_ansi
+        )

{docsig-0.49.2 → docsig-0.51.0}/docsig/_main.py

@@ -9,7 +9,7 @@ from __future__ import annotations as _
 
 from ._config import Parser as _Parser
 from ._core import docsig as _docsig
-from ._hooks import pretty_print_error as _pretty_print_error
+from ._hooks import excepthook as _excepthook
 
 
 def main() -> str | int:
@@ -20,7 +20,7 @@ def main() -> str | int:
     :return: Exit status for whether test failed or not.
     """
     p = _Parser()
-    _pretty_print_error(p.args.no_ansi)
+    _excepthook(p.args.no_ansi)
     return _docsig(
         *p.args.path,
         string=p.args.string,
@@ -33,6 +33,7 @@ def main() -> str | int:
         check_overridden=p.args.check_overridden,
         check_protected=p.args.check_protected,
         check_property_returns=p.args.check_property_returns,
+        include_ignored=p.args.include_ignored,
         ignore_no_params=p.args.ignore_no_params,
         ignore_args=p.args.ignore_args,
         ignore_kwargs=p.args.ignore_kwargs,

{docsig-0.49.2 → docsig-0.51.0}/docsig/_module.py

@@ -5,23 +5,73 @@ docsig._module
 
 from __future__ import annotations as _
 
+import os as _os
 import re as _re
+import sys as _sys
 import typing as _t
 from pathlib import Path as _Path
 
 import astroid as _ast
+import click as _click
 from astroid import AstroidSyntaxError as _AstroidSyntaxError
+from pathspec import PathSpec as _PathSpec
+from pathspec.patterns import GitWildMatchPattern as _GitWildMatchPattern
 
 from ._directives import Directive as _Directive
 from ._directives import Directives as _Directives
 from ._message import Message as _Message
 from ._stub import Docstring as _Docstring
 from ._stub import Signature as _Signature
+from ._utils import pretty_print_error
 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 Parent(_t.List["Parent"]):
     """Represents an object that contains functions or methods.
 
@@ -304,7 +354,7 @@ class Function(Parent):
         return self._directives
 
 
-class Modules(_t.List[Parent]):
+class Modules(_t.List[Parent]):  # pylint: disable=too-many-instance-attributes
     """Sequence of ``Module`` objects parsed from Python modules or str.
 
     Recursively collect Python files from within all dirs that exist
@@ -317,11 +367,14 @@ class Modules(_t.List[Parent]):
     :param excludes: List pf regular expression of files and dirs to
         exclude from checks.
     :param string: String to parse if provided.
+    :param include_ignored: Check files even if they match a gitignore
+        pattern.
     :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 no_ansi: Disable ANSI output.
     :param verbose: increase output verbosity.
     """
 
@@ -352,22 +405,24 @@ class Modules(_t.List[Parent]):
                     check_class_constructor,
                 )
             )
+            _vprint(
+                _FILE_INFO.format(
+                    path=root or "stdin", msg="Parsing Python code successful"
+                ),
+                self._verbose,
+            )
         except (_AstroidSyntaxError, UnicodeDecodeError) as err:
+            msg = str(err).replace("\n", " ")
             if root is not None and root.name.endswith(".py"):
-                # keep raising errors for .py files as was done prior to
-                # this change
                 # pass by silently for files that do not end with .py,
-                # which were not checked at all prior (these may result
-                # in a 123 syntax error exit status in the future)
-                # with this there should be no breaking change, and
-                # files that are supposed to be python, files evident by
-                # their suffix, will continue to fail
-                raise err
+                # may result in a 123 syntax error exit status in the
+                # future
+                _click.echo(root, file=_sys.stderr)
+                pretty_print_error(type(err), msg, no_ansi=self._no_ansi)
+                self._retcode = 1
 
             _vprint(
-                _FILE_INFO.format(
-                    path=root or "stdin", msg=str(err).replace("\n", " ")
-                ),
+                _FILE_INFO.format(path=root or "stdin", msg=msg),
                 self._verbose,
             )
 
@@ -377,18 +432,24 @@ class Modules(_t.List[Parent]):
         disable: list[_Message],
         excludes: list[str],
         string: str | None = None,
+        include_ignored: bool = False,
         ignore_args: bool = False,
         ignore_kwargs: bool = False,
         check_class_constructor: bool = False,
+        no_ansi: bool = False,
         verbose: bool = False,
     ) -> None:
         super().__init__()
         self._disable = disable
         self._excludes = excludes
+        self._include_ignored = include_ignored
         self._ignore_args = ignore_args
         self._ignore_kwargs = ignore_kwargs
         self.check_class_constructor = check_class_constructor
+        self._no_ansi = no_ansi
         self._verbose = verbose
+        self._retcode = 0
+        self._gitignore = _Gitignore()
         if string is not None:
             self._add_module(
                 disable,
@@ -414,6 +475,13 @@ class Modules(_t.List[Parent]):
             )
             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._add_module(
                 self._disable,
@@ -426,3 +494,8 @@ class Modules(_t.List[Parent]):
         if root.is_dir():
             for path in root.iterdir():
                 self._populate(path)
+
+    @property
+    def retcode(self) -> int:
+        """Return code to propagate to main."""
+        return self._retcode

{docsig-0.49.2 → docsig-0.51.0}/docsig/_utils.py

@@ -5,6 +5,8 @@ docsig._utils
 
 from __future__ import annotations as _
 
+import sys as _sys
+import typing as _t
 from difflib import SequenceMatcher as _SequenceMatcher
 
 import click as _click
@@ -31,3 +33,19 @@ def vprint(msg: str, verbose: bool = False) -> None:
     """
     if verbose:
         _click.echo(msg)
+
+
+def pretty_print_error(
+    exception_type: _t.Type[BaseException], msg: str, no_ansi: bool
+) -> None:
+    """Print user-friendly exception.
+
+    :param exception_type: Type of the exception.
+    :param msg: The exception message.
+    :param no_ansi: Whether to in ANSI escape codes.
+    """
+    _click.echo(
+        f"{_click.style(exception_type.__name__, fg='red', bold=True)}: {msg}",
+        file=_sys.stderr,
+        color=not no_ansi and _sys.stderr.isatty(),
+    )

{docsig-0.49.2 → docsig-0.51.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.49.2"
+__version__ = "0.51.0"

{docsig-0.49.2 → docsig-0.51.0}/pyproject.toml

@@ -16,16 +16,6 @@ exclude = '''
 '''
 line-length = 79
 
-[tool.constcheck]
-ignore_strings = [
-  "disable",
-  "red",
-  "store",
-  "store_true",
-  "targets",
-  "utf-8"
-]
-
 [tool.coverage.report]
 exclude_lines = [
   "@_t.overload"
@@ -73,7 +63,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.49.2"
+version = "0.51.0"
 
 [tool.poetry.dependencies]
 Pygments = "^2.13.0"
@@ -81,6 +71,7 @@ Sphinx = "^7.0.0"
 arcon = ">=0.4.0"
 astroid = "^3.0.1"
 click = "^8.1.7"
+pathspec = "^0.12.1"
 python = "^3.8"
 
 [tool.poetry.dev-dependencies]
@@ -104,7 +95,6 @@ docsig = "docsig.__main__:main"
 audit = [
   "about-tests",
   "commit-policy",
-  "const",
   "copyright-year",
   "docs",
   "files",

docsig-0.49.2/docsig/_hooks.py

@@ -1,22 +0,0 @@
-"""
-docsig._hooks
-=============
-"""
-
-import sys as _sys
-from os import environ as _e
-
-import click as _click
-
-
-def pretty_print_error(no_ansi: bool = False) -> None:
-    """Print user friendly commandline error if debug not enabled.
-
-    :param no_ansi: Disable ANSI output.
-    """
-    if _e.get("DOCSIG_DEBUG", None) != "1":
-        _sys.excepthook = lambda x, y, _: _click.echo(
-            f"{_click.style(x.__name__, fg='red', bold=True)}: {y}",
-            file=_sys.stderr,
-            color=not no_ansi and _sys.stderr.isatty(),
-        )