docsig 0.44.3__tar.gz → 0.46.0__tar.gz

{docsig-0.44.3 → docsig-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.44.3
+Version: 0.46.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: Pygments (>=2.13.0,<3.0.0)
 Requires-Dist: Sphinx (>=7.0.0,<8.0.0)
-Requires-Dist: arcon (>=0.3.1,<0.4.0)
+Requires-Dist: arcon (>=0.4.0)
 Requires-Dist: astroid (>=3.0.1,<4.0.0)
 Requires-Dist: object-colors (>=2.1.0,<3.0.0)
 Requires-Dist: typing-extensions (>=4.8.0,<5.0.0)
@@ -106,8 +106,8 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-v] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
-                             [-n] [-S] [-s STR] [-d LIST] [-t LIST]
+    usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
+                             [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
                              [path [path ...]]
 
     Check signature params for proper documentation
@@ -117,7 +117,7 @@ Commandline
 
     optional arguments:
       -h, --help                           show this help message and exit
-      -v, --version                        show program's version number and exit
+      -V, --version                        show program's version number and exit
       -l, --list-checks                    display a list of all checks and their messages
       -c, --check-class                    check class docstrings
       -C, --check-class-constructor        check __init__ methods. Note: mutually
@@ -134,9 +134,12 @@ Commandline
       -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
       -n, --no-ansi                        disable ansi output
       -S, --summary                        print a summarised report
+      -v, --verbose                        increase output verbosity
       -s STR, --string STR                 string to parse instead of files
       -d LIST, --disable LIST              comma separated list of rules to disable
       -t LIST, --target LIST               comma separated list of rules to target
+      -e EXCLUDE, --exclude EXCLUDE        regular expression of files or dirs to exclude
+                                           from checks
 
 Options can also be configured with the pyproject.toml file
 
@@ -229,7 +232,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.44.3
+        rev: v0.46.0
         hooks:
           - id: docsig
             args:

{docsig-0.44.3 → docsig-0.46.0}/README.rst

@@ -77,8 +77,8 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-v] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
-                             [-n] [-S] [-s STR] [-d LIST] [-t LIST]
+    usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
+                             [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
                              [path [path ...]]
 
     Check signature params for proper documentation
@@ -88,7 +88,7 @@ Commandline
 
     optional arguments:
       -h, --help                           show this help message and exit
-      -v, --version                        show program's version number and exit
+      -V, --version                        show program's version number and exit
       -l, --list-checks                    display a list of all checks and their messages
       -c, --check-class                    check class docstrings
       -C, --check-class-constructor        check __init__ methods. Note: mutually
@@ -105,9 +105,12 @@ Commandline
       -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
       -n, --no-ansi                        disable ansi output
       -S, --summary                        print a summarised report
+      -v, --verbose                        increase output verbosity
       -s STR, --string STR                 string to parse instead of files
       -d LIST, --disable LIST              comma separated list of rules to disable
       -t LIST, --target LIST               comma separated list of rules to target
+      -e EXCLUDE, --exclude EXCLUDE        regular expression of files or dirs to exclude
+                                           from checks
 
 Options can also be configured with the pyproject.toml file
 
@@ -200,7 +203,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.44.3
+        rev: v0.46.0
         hooks:
           - id: docsig
             args:

{docsig-0.44.3 → docsig-0.46.0}/docsig/_config.py

@@ -23,6 +23,7 @@ class Parser(_ArgumentParser):
                 prog, max_help_position=45
             ),
             description="Check signature params for proper documentation",
+            version_short_form="-V",
         )
         self._add_arguments()
         self.args = self.parse_args()
@@ -114,6 +115,12 @@ class Parser(_ArgumentParser):
             action="store_true",
             help="print a summarised report",
         )
+        self.add_argument(
+            "-v",
+            "--verbose",
+            action="store_true",
+            help="increase output verbosity",
+        )
         self.add_argument(
             "-s",
             "--string",
@@ -133,3 +140,8 @@ class Parser(_ArgumentParser):
             metavar="LIST",
             help="comma separated list of rules to target",
         )
+        self.add_argument(
+            "-e",
+            "--exclude",
+            help="regular expression of files or dirs to exclude from checks",
+        )

{docsig-0.44.3 → docsig-0.46.0}/docsig/_core.py

@@ -19,6 +19,25 @@ from ._report import generate_report as _generate_report
 from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E
 
+_DEFAULT_EXCLUDES = """\
+(?x)^(
+  |\\.?venv
+  |\\.git
+  |\\.hg
+  |\\.idea
+  |\\.mypy_cache
+  |\\.nox
+  |\\.pytest_cache
+  |\\.svn
+  |\\.tox
+  |\\.vscode
+  |_?build
+  |__pycache__
+  |dist
+  |node_modules
+)$
+"""
+
 
 def _print_checks() -> None:
     for msg in _E.values():
@@ -80,8 +99,10 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     ignore_kwargs: bool = False,
     no_ansi: bool = False,
     summary: bool = False,
+    verbose: bool = False,
     targets: list[_Message] | None = None,
     disable: list[_Message] | None = None,
+    exclude: str | None = None,
 ) -> int:
     """Package's core functionality.
 
@@ -110,20 +131,29 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
     :param no_ansi: Disable ANSI output.
     :param summary: Print a summarised report.
+    :param verbose: increase output verbosity.
     :param targets: List of errors to target.
     :param disable: List of errors to disable.
+    :param exclude: Regular expression of files and dirs to exclude from
+        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)
+
     modules = _Modules(
         *tuple(_Path(i) for i in path),
         disable=disable or [],
         string=string,
+        excludes=excludes,
         ignore_args=ignore_args,
         ignore_kwargs=ignore_kwargs,
         check_class_constructor=check_class_constructor,
+        verbose=verbose,
     )
     display = _Display(no_ansi)
     for module in modules:

{docsig-0.44.3 → docsig-0.46.0}/docsig/_function.py

@@ -319,7 +319,9 @@ class Function:  # pylint: disable=too-many-arguments
     def _decorated_with(self, name: str) -> bool:
         if self._node.decorators is not None:
             for dec in self._node.decorators.nodes:
-                return isinstance(dec, _ast.Name) and dec.name == name
+                return (isinstance(dec, _ast.Name) and dec.name == name) or (
+                    isinstance(dec, _ast.Attribute) and dec.attrname == name
+                )
 
         return False
 
@@ -333,11 +335,6 @@ class Function:  # pylint: disable=too-many-arguments
         """Boolean value for whether function is a property."""
         valid_properties = [
             "property",
-            # todo: this should be inferred as various import styles or
-            # todo: aliases won't be recognised
-            # todo:
-            # todo: it appears overloaded is inferred, if it isn't, look
-            # todo: at that too
             "cached_property",
         ]
         return self.ismethod and any(

{docsig-0.44.3 → docsig-0.46.0}/docsig/_main.py

@@ -39,6 +39,8 @@ def main() -> str | int:
         ignore_kwargs=parser.args.ignore_kwargs,
         no_ansi=parser.args.no_ansi,
         summary=parser.args.summary,
+        verbose=parser.args.verbose,
         targets=parser.args.target,
         disable=parser.args.disable,
+        exclude=parser.args.exclude,
     )

{docsig-0.44.3 → docsig-0.46.0}/docsig/_module.py

@@ -5,15 +5,20 @@ docsig._module
 
 from __future__ import annotations as _
 
+import re as _re
 import typing as _t
 from pathlib import Path as _Path
 
 import astroid as _ast
+from astroid import AstroidSyntaxError as _AstroidSyntaxError
 
 from ._directives import Directives as _Directives
 from ._function import Function as _Function
 from ._message import Message as _Message
 from ._utils import isprotected as _isprotected
+from ._utils import vprint as _vprint
+
+_FILE_INFO = "{path}: {msg}"
 
 
 class Parent(_t.List[_Function]):
@@ -128,37 +133,87 @@ class Modules(_t.List[_Module]):
 
     :param paths: Path(s) to parse ``Module``(s) from.
     :param disable: List of checks to disable.
+    :param excludes: List pf regular expression of files and dirs to
+        exclude from checks.
     :param string: String to parse if provided.
     :param ignore_args: Ignore args prefixed with an asterisk.
     :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
     :param check_class_constructor: Check the class constructor's
         docstring. Otherwise, expect the constructor's documentation to
         be on the class level docstring.
+    :param verbose: increase output verbosity.
     """
 
+    # handle errors here before appending a module
+    def _add_module(  # pylint: disable=too-many-arguments
+        self,
+        disable: list[_Message],
+        string: str | None = None,
+        root: _Path | None = None,
+        ignore_args: bool = False,
+        ignore_kwargs: bool = False,
+        check_class_constructor: bool = False,
+    ) -> None:
+        try:
+            if root is not None:
+                string = root.read_text(encoding="utf-8")
+
+            self.append(
+                _Module(
+                    # empty string won't happen but keeps the
+                    # typechecker happy
+                    string or "",
+                    disable,
+                    root,
+                    ignore_args,
+                    ignore_kwargs,
+                    check_class_constructor,
+                )
+            )
+        except (_AstroidSyntaxError, UnicodeDecodeError) as err:
+            if root is not None and root.name.endswith(".py"):
+                # keep raising errors for .py files as was done prior to
+                # this change
+                # pass by silently for files that do not end with .py,
+                # which were not checked at all prior (these may result
+                # in a 123 syntax error exit status in the future)
+                # with this there should be no breaking change, and
+                # files that are supposed to be python, files evident by
+                # their suffix, will continue to fail
+                raise err
+
+            _vprint(
+                _FILE_INFO.format(
+                    path=root or "stdin", msg=str(err).replace("\n", " ")
+                ),
+                self._verbose,
+            )
+
     def __init__(  # pylint: disable=too-many-arguments
         self,
         *paths: _Path,
         disable: list[_Message],
+        excludes: list[str],
         string: str | None = None,
         ignore_args: bool = False,
         ignore_kwargs: bool = False,
         check_class_constructor: bool = False,
+        verbose: bool = False,
     ) -> None:
         super().__init__()
         self._disable = disable
+        self._excludes = excludes
         self._ignore_args = ignore_args
         self._ignore_kwargs = ignore_kwargs
         self.check_class_constructor = check_class_constructor
+        self._verbose = verbose
         if string is not None:
-            self.append(
-                _Module(
-                    string,
-                    disable,
-                    ignore_args=ignore_args,
-                    ignore_kwargs=ignore_kwargs,
-                    check_class_constructor=check_class_constructor,
-                )
+            self._add_module(
+                disable,
+                string=string,
+                ignore_args=ignore_args,
+                ignore_kwargs=ignore_kwargs,
+                check_class_constructor=check_class_constructor,
             )
         else:
             for path in paths:
@@ -168,16 +223,22 @@ class Modules(_t.List[_Module]):
         if not root.exists():
             raise FileNotFoundError(root)
 
-        if root.is_file() and root.name.endswith(".py"):
-            self.append(
-                _Module(
-                    root.read_text(encoding="utf-8"),
-                    self._disable,
-                    root,
-                    self._ignore_args,
-                    self._ignore_kwargs,
-                    self.check_class_constructor,
-                )
+        if str(root) != "." and any(
+            _re.match(i, root.name) for i in self._excludes
+        ):
+            _vprint(
+                _FILE_INFO.format(path=root, msg="in exclude list, skipping"),
+                self._verbose,
+            )
+            return
+
+        if root.is_file():
+            self._add_module(
+                self._disable,
+                root=root,
+                ignore_args=self._ignore_args,
+                ignore_kwargs=self._ignore_kwargs,
+                check_class_constructor=self.check_class_constructor,
             )
 
         if root.is_dir():

{docsig-0.44.3 → docsig-0.46.0}/docsig/_utils.py

@@ -28,3 +28,13 @@ def almost_equal(str1: str, str2: str, mini: float, maxi: float) -> bool:
     :return: Boolean result for whether both strings are almost equal.
     """
     return mini < _SequenceMatcher(a=str1, b=str2).ratio() < maxi
+
+
+def vprint(msg: str, verbose: bool = False) -> None:
+    """Print messages only if verbose is true.
+
+    :param msg: Message to print.
+    :param verbose: Whether verbose mode is enabled.
+    """
+    if verbose:
+        print(msg)

{docsig-0.44.3 → docsig-0.46.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.44.3"
+__version__ = "0.46.0"

{docsig-0.44.3 → docsig-0.46.0}/pyproject.toml

@@ -72,12 +72,12 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.44.3"
+version = "0.46.0"
 
 [tool.poetry.dependencies]
 Pygments = "^2.13.0"
 Sphinx = "^7.0.0"
-arcon = "^0.3.1"
+arcon = ">=0.4.0"
 astroid = "^3.0.1"
 object-colors = "^2.1.0"
 python = "^3.8"
@@ -85,7 +85,7 @@ typing-extensions = "^4.8.0"
 
 [tool.poetry.dev-dependencies]
 bump2version = "^1.0.1"
-deptry = "^0.14.2"
+deptry = "^0.16.1"
 ipython = "^8.12.0"
 pre-commit = "^3.3.3"
 pyaud = "^7.5.0"