docsig 0.42.1__tar.gz → 0.44.0__tar.gz

{docsig-0.42.1 → docsig-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.42.1
+Version: 0.44.0
 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)
@@ -105,9 +105,9 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-v] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k] [-n]
-                             [-S] [-s STR] [-d LIST] [-t LIST]
-                             path [path ...]
+    usage: docsig [-h] [-v] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
+                             [-n] [-S] [-s STR] [-d LIST] [-t LIST]
+                             [path [path ...]]
 
     Check signature params for proper documentation
 
@@ -117,6 +117,7 @@ Commandline
     optional arguments:
       -h, --help                           show this help message 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
                                            incompatible with -c
@@ -539,7 +540,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.42.1
+        rev: v0.44.0
         hooks:
           - id: docsig
             args:

{docsig-0.42.1 → docsig-0.44.0}/README.rst

@@ -77,9 +77,9 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-v] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k] [-n]
-                             [-S] [-s STR] [-d LIST] [-t LIST]
-                             path [path ...]
+    usage: docsig [-h] [-v] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
+                             [-n] [-S] [-s STR] [-d LIST] [-t LIST]
+                             [path [path ...]]
 
     Check signature params for proper documentation
 
@@ -89,6 +89,7 @@ Commandline
     optional arguments:
       -h, --help                           show this help message 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
                                            incompatible with -c
@@ -511,7 +512,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.42.1
+        rev: v0.44.0
         hooks:
           - id: docsig
             args:

{docsig-0.42.1 → docsig-0.44.0}/docsig/_config.py

@@ -29,11 +29,17 @@ class Parser(_ArgumentParser):
     def _add_arguments(self) -> None:
         self.add_argument(
             "path",
-            nargs="+",
+            nargs="*",
             action="store",
             type=_Path,
             help="directories or files to check",
         )
+        self.add_argument(
+            "-l",
+            "--list-checks",
+            action="store_true",
+            help="display a list of all checks and their messages",
+        )
         group = self.add_mutually_exclusive_group(required=False)
         group.add_argument(
             "-c",

{docsig-0.42.1 → docsig-0.44.0}/docsig/_core.py

@@ -4,28 +4,24 @@ 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
 from ._report import generate_report as _generate_report
+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 _run_check(  # pylint: disable=too-many-arguments
@@ -65,9 +61,12 @@ 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: _Path,
+    *path: str | _Path,
     string: str | None = None,
+    list_checks: bool = False,
     check_class: bool = False,
     check_class_constructor: bool = False,
     check_dunders: bool = False,
@@ -80,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.
 
@@ -94,6 +93,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
 
     :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.
@@ -113,23 +113,12 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     :param disable: List of errors to disable.
     :return: Exit status for whether test failed or not.
     """
-    disabled_args = list(_E.fromcodes(disable or []))
-    target_args = list(_E.fromcodes(targets or []))
-    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}'",
-            )
+    if list_checks:
+        return int(bool(_print_checks()))  # type: ignore
 
     modules = _Modules(
-        *path,
-        disable=disabled_args,
+        *tuple(_Path(i) for i in path),
+        disable=disable or [],
         string=string,
         ignore_args=ignore_args,
         ignore_kwargs=ignore_kwargs,
@@ -153,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.0/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.0/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.42.1 → docsig-0.44.0}/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.
@@ -21,6 +23,7 @@ def main() -> int:
     return _docsig(
         *parser.args.path,
         string=parser.args.string,
+        list_checks=parser.args.list_checks,
         check_class=parser.args.check_class,
         check_class_constructor=parser.args.check_class_constructor,
         check_dunders=parser.args.check_dunders,
@@ -36,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.42.1 → docsig-0.44.0}/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.42.1"
+__version__ = "0.44.0"

{docsig-0.42.1 → docsig-0.44.0}/docsig/messages.py

@@ -134,7 +134,7 @@ E = _Messages(
         204: _Message(
             "E204",
             "unknown inline comment option for {directive} '{option}'",
-            "unknown-module-directive-option",
+            "unknown-inline-directive-option",
         ),
     }
 )

{docsig-0.42.1 → docsig-0.44.0}/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.42.1"
+version = "0.44.0"
 
 [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.0"
+pyaud = "^7.3.0"
 pytest = "^7.4.0"
 pytest-randomly = "^3.13.0"
 pytest-sugar = "^0.9.6"
@@ -111,7 +113,6 @@ audit = [
   "format-str",
   "imports",
   "lint",
-  "params",
   "test",
   "typecheck",
   "unused"