docsig 0.43.0__tar.gz → 0.44.1__tar.gz

{docsig-0.43.0 → docsig-0.44.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.43.0
+Version: 0.44.1
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Requires-Dist: Pygments (>=2.13.0,<3.0.0)
-Requires-Dist: Sphinx (>=4.3.2,<7.0.0)
+Requires-Dist: Sphinx (>=7.0.0,<8.0.0)
 Requires-Dist: arcon (>=0.3.1,<0.4.0)
 Requires-Dist: astroid (>=3.0.1,<4.0.0)
 Requires-Dist: object-colors (>=2.1.0,<3.0.0)
@@ -540,7 +540,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.43.0
+        rev: v0.44.1
         hooks:
           - id: docsig
             args:

{docsig-0.43.0 → docsig-0.44.1}/README.rst

@@ -512,7 +512,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.43.0
+        rev: v0.44.1
         hooks:
           - id: docsig
             args:

{docsig-0.43.0 → docsig-0.44.1}/docsig/_core.py

@@ -4,15 +4,13 @@ docsig._core
 """
 from __future__ import annotations as _
 
-import sys as _sys
-from os import environ as _e
 from pathlib import Path as _Path
 
+from . import _decorators
 from ._display import Display as _Display
 from ._display import Failure as _Failure
 from ._display import Failures as _Failures
 from ._display import FuncStr as _FuncStr
-from ._display import color as _color
 from ._message import Message as _Message
 from ._module import Modules as _Modules
 from ._module import Parent as _Parent
@@ -21,42 +19,11 @@ from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E
 
 
-def pretty_print_error() -> None:
-    """Print user friendly commandline error if debug not enabled."""
-    if _e.get("DOCSIG_DEBUG", None) != "1":
-        _sys.excepthook = lambda x, y, _: print(
-            f"{_color.red.bold.get(x.__name__)}: {y}"
-        )
-
-
 def _print_checks() -> None:
     for msg in _E.values():
         print(msg.fstring(_TEMPLATE))
 
 
-def _check_required_args(path: tuple[str | _Path, ...], string: str | None):
-    if not path and not string:
-        raise ValueError(
-            "the following arguments are required: path(s) or string",
-        )
-
-
-def _check_provided_lists(
-    disabled_args: list[_Message], target_args: list[_Message]
-) -> None:
-    for message in disabled_args:
-        if not message.isknown:
-            raise ValueError(
-                f"unknown option to disable '{message.description}'",
-            )
-
-    for message in target_args:
-        if not message.isknown:
-            raise ValueError(
-                f"unknown option to target '{message.description}'",
-            )
-
-
 def _run_check(  # pylint: disable=too-many-arguments
     parent: _Parent,
     check_class: bool,
@@ -94,6 +61,8 @@ def _run_check(  # pylint: disable=too-many-arguments
     return failures
 
 
+@_decorators.parse_msgs
+@_decorators.validate_args
 def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     *path: str | _Path,
     string: str | None = None,
@@ -110,8 +79,8 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     ignore_kwargs: bool = False,
     no_ansi: bool = False,
     summary: bool = False,
-    targets: list[str] | None = None,
-    disable: list[str] | None = None,
+    targets: list[_Message] | None = None,
+    disable: list[_Message] | None = None,
 ) -> int:
     """Package's core functionality.
 
@@ -147,13 +116,9 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     if list_checks:
         return int(bool(_print_checks()))  # type: ignore
 
-    _check_required_args(path, string)
-    disabled_args = list(_E.fromcodes(disable or []))
-    target_args = list(_E.fromcodes(targets or []))
-    _check_provided_lists(disabled_args, target_args)
     modules = _Modules(
         *tuple(_Path(i) for i in path),
-        disable=disabled_args,
+        disable=disable or [],
         string=string,
         ignore_args=ignore_args,
         ignore_kwargs=ignore_kwargs,
@@ -177,7 +142,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
                     check_property_returns,
                     ignore_no_params,
                     no_ansi,
-                    target_args,
+                    targets or [],
                 )
                 if failures:
                     display[top_level.path].append(failures)

docsig-0.44.1/docsig/_decorators.py

@@ -0,0 +1,81 @@
+"""
+docsig._decorators
+==================
+"""
+from __future__ import annotations as _
+
+import sys as _sys
+import typing as _t
+from pathlib import Path as _Path
+
+from .messages import E as _E
+
+_FuncType = _t.Callable[..., _t.Union[int]]
+_WrappedFuncType = _t.Callable[..., _t.Union[str, int]]
+
+
+def parse_msgs(func: _WrappedFuncType) -> _WrappedFuncType:
+    """Parse error codes or symbolic messages into message objects.
+
+    :param func: Function to wrap.
+    :return: Wrapped function.
+    """
+
+    def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> str | int:
+        disable = list(_E.fromcodes(kwargs.get("disable", []))) or None
+        targets = list(_E.fromcodes(kwargs.get("targets", []))) or None
+        kwargs["disable"] = disable
+        kwargs["targets"] = targets
+        return func(*args, **kwargs)
+
+    return _wrapper
+
+
+def validate_args(func: _FuncType) -> _WrappedFuncType:
+    """Confirm args passed to function are valid.
+
+    :param func: Function to wrap.
+    :return: Wrapped function.
+    """
+
+    def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> str | int:
+        stderr = []
+        if not kwargs.get("list_checks", False):
+            if not args and not kwargs.get("string"):
+                stderr.append(
+                    "the following arguments are required: path(s) or string"
+                )
+
+            for message in kwargs.get("disable") or []:
+                if not message.isknown:
+                    stderr.append(
+                        f"unknown option to disable '{message.description}'"
+                    )
+
+            for message in kwargs.get("targets") or []:
+                if not message.isknown:
+                    stderr.append(
+                        f"unknown option to target '{message.description}'",
+                    )
+
+            if kwargs.get("check_class") and kwargs.get(
+                "check_class_constructor"
+            ):
+                stderr.append(
+                    "argument to check class constructor not allowed with"
+                    " argument to check class"
+                )
+                # if we don't make it past this condition then we are
+                # running this using the python interpreter
+                if _sys.stdin and _sys.stdin.isatty():
+                    # otherwise, it is impossible to reach here by
+                    # passing both commandline args as argparse won't
+                    # allow it, therefore, this must be an issue with
+                    # the pyproject.toml configuration
+                    stderr.append(
+                        "please check your pyproject.toml configuration"
+                    )
+
+        return "\n".join(stderr) if stderr else func(*args, **kwargs)
+
+    return _wrapper

docsig-0.44.1/docsig/_hooks.py

@@ -0,0 +1,16 @@
+"""
+docsig._hooks
+=============
+"""
+import sys as _sys
+from os import environ as _e
+
+from ._display import color as _color
+
+
+def pretty_print_error() -> None:
+    """Print user friendly commandline error if debug not enabled."""
+    if _e.get("DOCSIG_DEBUG", None) != "1":
+        _sys.excepthook = lambda x, y, _: print(
+            f"{_color.red.bold.get(x.__name__)}: {y}"
+        )

{docsig-0.43.0 → docsig-0.44.1}/docsig/_main.py

@@ -4,12 +4,14 @@ docsig._main
 
 Contains package entry point.
 """
+from __future__ import annotations as _
+
 from ._config import Parser as _Parser
 from ._core import docsig as _docsig
-from ._core import pretty_print_error as _pretty_print_error
+from ._hooks import pretty_print_error as _pretty_print_error
 
 
-def main() -> int:
+def main() -> str | int:
     """Main function for package.
 
     Collect config and arguments for the commandline.
@@ -37,5 +39,5 @@ def main() -> int:
         no_ansi=parser.args.no_ansi,
         summary=parser.args.summary,
         targets=parser.args.target,
-        disable=parser.args.disable
+        disable=parser.args.disable,
     )

{docsig-0.43.0 → docsig-0.44.1}/docsig/_module.py

@@ -43,8 +43,13 @@ class Parent(_t.List[_Function]):
         self._path = f"{path}:" if path is not None else ""
         overloads = []
         returns = None
+        parent_comments, parent_disabled = directives.get(
+            node.lineno, ([], [])
+        )
         for subnode in node.body:
             comments, disabled = directives.get(subnode.lineno, ([], []))
+            comments.extend(parent_comments)
+            disabled.extend(parent_disabled)
             if isinstance(subnode, _ast.FunctionDef):
                 func = _Function(
                     subnode,

{docsig-0.43.0 → docsig-0.44.1}/docsig/_version.py

@@ -7,4 +7,4 @@ Contains the version of this package.
 Allows for access to the version internally without cyclic imports
 caused by accessing it through __init__.
 """
-__version__ = "0.43.0"
+__version__ = "0.44.1"

{docsig-0.43.0 → docsig-0.44.1}/pyproject.toml

@@ -18,8 +18,10 @@ line-length = 79
 
 [tool.constcheck]
 ignore_strings = [
+  "disable",
   "store",
   "store_true",
+  "targets",
   "utf-8"
 ]
 
@@ -70,11 +72,11 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.43.0"
+version = "0.44.1"
 
 [tool.poetry.dependencies]
 Pygments = "^2.13.0"
-Sphinx = ">=4.3.2,<7.0.0"
+Sphinx = "^7.0.0"
 arcon = "^0.3.1"
 astroid = "^3.0.1"
 object-colors = "^2.1.0"
@@ -86,7 +88,7 @@ bump2version = "^1.0.1"
 deptry = "^0.12.0"
 ipython = "^8.12.0"
 pre-commit = "^3.3.3"
-pyaud = "^7.2.2"
+pyaud = "^7.3.0"
 pytest = "^7.4.0"
 pytest-randomly = "^3.13.0"
 pytest-sugar = "^0.9.6"