docsig 0.47.0__tar.gz → 0.49.0__tar.gz

{docsig-0.47.0 → docsig-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.47.0
+Version: 0.49.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -21,8 +21,7 @@ Requires-Dist: Pygments (>=2.13.0,<3.0.0)
 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: object-colors (>=2.1.0,<3.0.0)
-Requires-Dist: typing-extensions (>=4.8.0,<5.0.0)
+Requires-Dist: click (>=8.1.7,<9.0.0)
 Project-URL: Documentation, https://docsig.readthedocs.io/en/latest
 Project-URL: Repository, https://github.com/jshwi/docsig
 Description-Content-Type: text/x-rst
@@ -139,7 +138,7 @@ Commandline
       -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
+      -e PATTERN, --exclude PATTERN        regular expression of files or dirs to exclude
                                            from checks
 
 Options can also be configured with the pyproject.toml file
@@ -182,7 +181,7 @@ API
     ...     :param param3: About param3.
     ...     '''
     ...     """
-    >>> docsig(string=string)
+    >>> docsig(string=string, summary=True, no_ansi=True)
     0
 
 .. code-block:: python
@@ -196,18 +195,9 @@ API
     ...     :param param3: About param3.
     ...     '''
     ... """
-    >>> docsig(string=string)
-    2
-    -
-    def function(✓param1, ✓param2, ✖None) -> ✓None:
-        """
-        :param param1: ✓
-        :param param2: ✓
-        :param param3: ✖
-        """
-    <BLANKLINE>
-    E102: includes parameters that do not exist (params-do-not-exist)
-    <BLANKLINE>
+    >>> docsig(string=string, summary=True, no_ansi=True)
+    2 in function
+        E102: includes parameters that do not exist (params-do-not-exist)
     1
 
 A full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/docsig.html#docsig-messages>`__
@@ -233,7 +223,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.47.0
+        rev: v0.49.0
         hooks:
           - id: docsig
             args:

{docsig-0.47.0 → docsig-0.49.0}/README.rst

@@ -110,7 +110,7 @@ Commandline
       -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
+      -e PATTERN, --exclude PATTERN        regular expression of files or dirs to exclude
                                            from checks
 
 Options can also be configured with the pyproject.toml file
@@ -153,7 +153,7 @@ API
     ...     :param param3: About param3.
     ...     '''
     ...     """
-    >>> docsig(string=string)
+    >>> docsig(string=string, summary=True, no_ansi=True)
     0
 
 .. code-block:: python
@@ -167,18 +167,9 @@ API
     ...     :param param3: About param3.
     ...     '''
     ... """
-    >>> docsig(string=string)
-    2
-    -
-    def function(✓param1, ✓param2, ✖None) -> ✓None:
-        """
-        :param param1: ✓
-        :param param2: ✓
-        :param param3: ✖
-        """
-    <BLANKLINE>
-    E102: includes parameters that do not exist (params-do-not-exist)
-    <BLANKLINE>
+    >>> docsig(string=string, summary=True, no_ansi=True)
+    2 in function
+        E102: includes parameters that do not exist (params-do-not-exist)
     1
 
 A full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/docsig.html#docsig-messages>`__
@@ -204,7 +195,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.47.0
+        rev: v0.49.0
         hooks:
           - id: docsig
             args:

{docsig-0.47.0 → docsig-0.49.0}/docsig/_config.py

@@ -6,9 +6,9 @@ docsig._config
 from argparse import HelpFormatter as _HelpFormatter
 from pathlib import Path as _Path
 
+import click as _click
 from arcon import ArgumentParser as _ArgumentParser
 
-from ._display import color as _color
 from ._version import __version__
 
 
@@ -18,7 +18,7 @@ class Parser(_ArgumentParser):
     def __init__(self) -> None:
         super().__init__(
             version=__version__,
-            prog=_color.cyan.get(__package__),
+            prog=_click.style(__package__, fg="cyan"),
             formatter_class=lambda prog: _HelpFormatter(
                 prog, max_help_position=45
             ),
@@ -149,5 +149,6 @@ class Parser(_ArgumentParser):
         self.add_argument(
             "-e",
             "--exclude",
+            metavar="PATTERN",
             help="regular expression of files or dirs to exclude from checks",
         )

{docsig-0.47.0 → docsig-0.49.0}/docsig/_core.py

@@ -7,6 +7,8 @@ from __future__ import annotations as _
 
 from pathlib import Path as _Path
 
+import click as _click
+
 from . import _decorators
 from ._display import Display as _Display
 from ._display import Failure as _Failure
@@ -16,7 +18,7 @@ from ._message import Message as _Message
 from ._module import Function as _Function
 from ._module import Modules as _Modules
 from ._module import Parent as _Parent
-from ._report import generate_report as _generate_report
+from ._report import Report as _Report
 from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E
 
@@ -42,7 +44,7 @@ _DEFAULT_EXCLUDES = """\
 
 def _print_checks() -> None:
     for msg in _E.values():
-        print(msg.fstring(_TEMPLATE))
+        _click.echo(msg.fstring(_TEMPLATE))
 
 
 def _run_check(  # pylint: disable=too-many-arguments
@@ -73,13 +75,11 @@ def _run_check(  # pylint: disable=too-many-arguments
             and not (child.isdunder and not check_dunders)
             and not (child.docstring.bare and ignore_no_params)
         ):
-            report = _generate_report(
+            report = _Report(
                 child, targets, child.disabled, check_property_returns
             )
             if report:
-                failures.append(
-                    _Failure(child, _FuncStr(child, no_ansi), report)
-                )
+                failures.append(_Failure(child, _FuncStr(child), report))
 
         if check_nested:
             for func in child:

{docsig-0.47.0 → docsig-0.49.0}/docsig/_decorators.py

@@ -59,7 +59,7 @@ def validate_args(func: _FuncType) -> _WrappedFuncType:
             for message in kwargs.get("targets") or []:
                 if not message.isknown:
                     stderr.append(
-                        f"unknown option to target '{message.description}'",
+                        f"unknown option to target '{message.description}'"
                     )
 
             if kwargs.get("check_class") and kwargs.get(

{docsig-0.47.0 → docsig-0.49.0}/docsig/_directives.py

@@ -10,8 +10,6 @@ import tokenize as _tokenize
 import typing as _t
 from io import StringIO as _StringIO
 
-from typing_extensions import Self as _Self
-
 from ._message import Message as _Message
 from .messages import E as _E
 
@@ -96,7 +94,7 @@ class Directive:
         return self._kind == self._valid_kinds[1]
 
     @classmethod
-    def parse(cls, comment: str, col: int) -> _Self | None:
+    def parse(cls, comment: str, col: int) -> Directive | None:
         """Parse string into directive object if possible.
 
         :param comment: Comment to parse.

{docsig-0.47.0 → docsig-0.49.0}/docsig/_display.py

@@ -8,7 +8,7 @@ from __future__ import annotations as _
 import typing as _t
 from collections import UserString as _UserString
 
-from object_colors import Color as _Color
+import click as _click
 from pygments import highlight as _highlight
 from pygments.formatters.terminal256 import (
     Terminal256Formatter as _Terminal256Formatter,
@@ -23,39 +23,18 @@ from ._stub import ARG as _ARG
 from ._stub import KEY as _KEY
 from ._stub import Param as _Param
 
-color = _Color()
-
-color.populate_colors()
-
 TAB = "    "
 
 
-class _ANSI:
-    def __init__(self, no_ansi: bool = False) -> None:
-        self._no_ansi = no_ansi
-
-    def color(self, obj: _t.Any, color_obj: _Color) -> str:
-        """Get string with selected color.
-
-        :param obj: Any object, represented as ``__str__``.
-        :param color_obj: Instantiated ``Color`` object.
-        :return: Colored string or string as was supplied.
-        """
-        return str(obj) if self._no_ansi else color_obj.get(obj)
-
-    def syntax(self, obj: _t.Any) -> str:
-        """Get code representation with syntax highlighting.
+def syntax(obj: _t.Any) -> str:
+    """Get code representation with syntax highlighting.
 
-        :param obj: Any object, represented as ``__str__``.
-        :return: Colored string or string as was supplied.
-        """
-        return (
-            str(obj)
-            if self._no_ansi
-            else _highlight(
-                obj, _PythonLexer(), _Terminal256Formatter(style="monokai")
-            ).strip()
-        )
+    :param obj: Any object, represented as ``__str__``.
+    :return: Colored string or string as was supplied.
+    """
+    return _highlight(
+        obj, _PythonLexer(), _Terminal256Formatter(style="monokai")
+    ).strip()
 
 
 class FuncStr(_UserString):
@@ -63,16 +42,14 @@ class FuncStr(_UserString):
 
     :param func: Represents a function with signature and docstring
         parameters.
-    :param no_ansi: Disable ANSI output.
     """
 
     CHECK = "\u2713"
     CROSS = "\u2716"
     TRIPLE_QUOTES = '"""'
 
-    def __init__(self, func: _Function, no_ansi: bool = False) -> None:
+    def __init__(self, func: _Function) -> None:
         super().__init__(func.name)
-        self._ansi = _ANSI(no_ansi)
         self._parent_name = func.parent.name
         self._isinit = func.isinit
         self.data = ""
@@ -80,13 +57,13 @@ class FuncStr(_UserString):
         if self._isinit:
             self.data += TAB
 
-        self.data += self._ansi.syntax(f"def {func.name}(")
+        self.data += syntax(f"def {func.name}(")
         if self._is_string:
-            self._docstring = self._ansi.syntax(f"{TAB}{self.TRIPLE_QUOTES}")
+            self._docstring = syntax(f"{TAB}{self.TRIPLE_QUOTES}")
         else:
-            self._docstring = f"{TAB}{self._ansi.color('...', color.red)}\n"
+            self._docstring = f"{TAB}{_click.style('...', fg='red')}\n"
 
-        self._mark = self._ansi.color(self.CHECK, color.green)
+        self._mark = _click.style(self.CHECK, fg="green")
         for index in range(len(func)):
             arg = func.signature.args.get(index)
             doc = func.docstring.args.get(index)
@@ -119,9 +96,9 @@ class FuncStr(_UserString):
         :param failed: Boolean to test that check failed.
         """
         self._mark = (
-            self._ansi.color(self.CROSS, color.red)
+            _click.style(self.CROSS, fg="red")
             if failed
-            else self._ansi.color(self.CHECK, color.green)
+            else _click.style(self.CHECK, fg="green")
         )
 
     def add_param(
@@ -162,34 +139,27 @@ class FuncStr(_UserString):
         :param arg: Signature argument.
         """
         if arg is not None:
-            self.data += "{}{}{}{}".format(
-                self._ansi.syntax(") -> "),
-                self._mark,
-                arg,
-                self._ansi.syntax(":"),
-            )
+            self.data += f"{syntax(') -> ')}{self._mark}{arg}{syntax(':')}"
         else:
             self.data += "{}{}{}".format(
-                self._ansi.syntax(")"),
-                self._ansi.color("?", color.red),
-                self._ansi.syntax(":"),
+                syntax(")"),
+                _click.style("?", fg="red"),
+                syntax(":"),
             )
 
     def add_comma(self) -> None:
         """Add comma between parenthesis."""
-        self.data += self._ansi.syntax(", ")
+        self.data += syntax(", ")
 
     def close_docstring(self) -> None:
         """Close docstring."""
-        self._cat_docstring(
-            f"\n{TAB}{self._ansi.syntax(self.TRIPLE_QUOTES)}\n"
-        )
+        self._cat_docstring(f"\n{TAB}{syntax(self.TRIPLE_QUOTES)}\n")
 
     def render(self) -> None:
         """Render final string by adding docstring to function."""
         if self._isinit:
             self.data = (
-                self._ansi.syntax(f"class {self._parent_name}:")
+                syntax(f"class {self._parent_name}:")
                 + f"\n{self._docstring}"
                 + f"\n{self.data}\n"
             )
@@ -209,15 +179,7 @@ class Failures(_t.List[Failure]):
     """Sequence of failed functions."""
 
 
-class _DisplaySequence(_t.Dict[str, _t.List[Failures]]):
-    def __getitem__(self, key: str) -> list[Failures]:
-        if key not in super().__iter__():
-            super().__setitem__(key, [])
-
-        return super().__getitem__(key)
-
-
-class Display(_DisplaySequence):
+class Display(_t.Dict[str, _t.List[Failures]]):
     """Collect and display report.
 
     :param no_ansi: Disable ANSI output.
@@ -225,7 +187,13 @@ class Display(_DisplaySequence):
 
     def __init__(self, no_ansi: bool = False) -> None:
         super().__init__()
-        self._ansi = _ANSI(no_ansi)
+        self._ansi = not no_ansi
+
+    def __getitem__(self, key: str) -> list[Failures]:
+        if key not in super().__iter__():
+            super().__setitem__(key, [])
+
+        return super().__getitem__(key)
 
     def report(self) -> None:
         """Display report if any checks have failed."""
@@ -236,10 +204,12 @@ class Display(_DisplaySequence):
                     if failure.func.parent.name:
                         header += f" in {failure.func.parent.name}"
 
-                    print(self._ansi.color(header, color.magenta))
-                    print(len(header) * "-")
-                    print(failure.func_str)
-                    print(failure.report.get_report())
+                    _click.echo(
+                        _click.style(header, fg="magenta"), color=self._ansi
+                    )
+                    _click.echo(len(header) * "-", color=self._ansi)
+                    _click.echo(failure.func_str, color=self._ansi)
+                    _click.echo(failure.report.get_report(), color=self._ansi)
 
     def summarise(self) -> None:
         """Display report summary if any checks have failed."""
@@ -252,9 +222,10 @@ class Display(_DisplaySequence):
                         function = f"{failure.func.parent.name}.{function}"
 
                     header += f" in {function}"
-                    print(
-                        "{}\n\t{}".format(
-                            self._ansi.color(header, color.magenta),
-                            failure.report.get_report("\t").strip(),
-                        )
+                    _click.echo(
+                        "{}\n    {}".format(
+                            _click.style(header, fg="magenta"),
+                            failure.report.get_report("    ").strip(),
+                        ),
+                        color=self._ansi,
                     )

{docsig-0.47.0 → docsig-0.49.0}/docsig/_hooks.py

@@ -6,12 +6,12 @@ docsig._hooks
 import sys as _sys
 from os import environ as _e
 
-from ._display import color as _color
+import click as _click
 
 
 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}"
+            f"{_click.style(x.__name__, fg='red', bold=True)}: {y}"
         )

docsig-0.49.0/docsig/_main.py

@@ -0,0 +1,45 @@
+"""
+docsig._main
+============
+
+Contains package entry point.
+"""
+
+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
+
+
+def main() -> str | int:
+    """Main function for package.
+
+    Collect config and arguments for the commandline.
+
+    :return: Exit status for whether test failed or not.
+    """
+    p = _Parser()
+    _pretty_print_error()
+    return _docsig(
+        *p.args.path,
+        string=p.args.string,
+        list_checks=p.args.list_checks,
+        check_class=p.args.check_class,
+        check_class_constructor=p.args.check_class_constructor,
+        check_dunders=p.args.check_dunders,
+        check_protected_class_methods=p.args.check_protected_class_methods,
+        check_nested=p.args.check_nested,
+        check_overridden=p.args.check_overridden,
+        check_protected=p.args.check_protected,
+        check_property_returns=p.args.check_property_returns,
+        ignore_no_params=p.args.ignore_no_params,
+        ignore_args=p.args.ignore_args,
+        ignore_kwargs=p.args.ignore_kwargs,
+        no_ansi=p.args.no_ansi,
+        summary=p.args.summary,
+        verbose=p.args.verbose,
+        targets=p.args.target,
+        disable=p.args.disable,
+        exclude=p.args.exclude,
+    )

docsig-0.49.0/docsig/_report.py

@@ -0,0 +1,196 @@
+"""
+docsig._report
+==============
+"""
+
+from __future__ import annotations as _
+
+import typing as _t
+
+from ._message import Message as _Message
+from ._module import Function as _Function
+from ._stub import RETURN as _RETURN
+from ._stub import Param as _Param
+from ._utils import almost_equal as _almost_equal
+from .messages import TEMPLATE as _TEMPLATE
+from .messages import E as _E
+
+_MIN_MATCH = 0.8
+_MAX_MATCH = 1.0
+
+
+class Report(_t.List[str]):
+    """Compile and produce report.
+
+    :param func: Function object.
+    :param targets: List of errors to target.
+    :param disable: List of errors to disable.
+    :param check_property_returns: Run return checks on properties.
+    """
+
+    def __init__(
+        self,
+        func: _Function,
+        targets: list[_Message],
+        disable: list[_Message],
+        check_property_returns: bool,
+    ) -> None:
+        super().__init__()
+        self._disable = list(disable)
+        if targets:
+            errors = list(_E.all(1))
+            for target in targets:
+                errors.remove(target)
+
+            self._disable.extend(errors)
+
+        self._errors: list[_Message] = []
+        self._func = func
+        self._no_prop_return = func.isproperty and not check_property_returns
+        self._no_returns = func.isinit or self._no_prop_return
+        self._invalid_directive()
+        self._invalid_directive_options()
+        self._missing_class_docstring()
+        self._missing_func_docstring()
+        if func.docstring.string is not None:
+            self._return_not_typed()
+            self._exists()
+            self._missing()
+            self._duplicates()
+            self._extra_return()
+            self._missing_return()
+            self._property_return()
+            self._class_return()
+            for index in range(len(func)):
+                arg = func.signature.args.get(index)
+                doc = func.docstring.args.get(index)
+                self._description_syntax(doc)
+                self._indent_syntax(doc)
+                if arg != doc:
+                    self._order(arg, doc)
+                    self._incorrect(arg, doc)
+                    self._misspelled(arg, doc)
+                    self._not_equal(arg, doc)
+
+        self.sort()
+
+    def _add(self, value: _Message, hint: bool = False, **kwargs) -> None:
+        self._errors.append(value)
+        message = value.fstring(_TEMPLATE)
+        if kwargs:
+            message = message.format(**kwargs)
+
+        if hint:
+            message += f"\nhint: {value.hint}"
+
+        if value not in self._disable and message not in self:
+            super().append(message)
+
+    def _order(self, sig: _Param, doc: _Param) -> None:
+        if any(sig.name == i.name for i in self._func.docstring.args) or any(
+            doc.name == i.name for i in self._func.signature.args
+        ):
+            self._add(_E[101])
+
+    def _exists(self) -> None:
+        if len(self._func.docstring.args) > len(self._func.signature.args):
+            self._add(_E[102])
+
+    def _missing_func_docstring(self) -> None:
+        if not self._func.isinit and self._func.docstring.string is None:
+            self._add(_E[113])
+
+    def _missing_class_docstring(self) -> None:
+        if self._func.isinit and self._func.docstring.string is None:
+            self._add(_E[114])
+
+    def _missing(self) -> None:
+        if len(self._func.signature.args) > len(self._func.docstring.args):
+            self._add(_E[103])
+
+    def _duplicates(self) -> None:
+        if self._func.docstring.args.duplicated:
+            self._add(_E[106])
+
+    def _extra_return(self) -> None:
+        if (
+            self._func.docstring.returns
+            and self._func.signature.rettype == "None"
+            and not self._no_returns
+        ):
+            self._add(_E[104])
+
+    def _property_return(self) -> None:
+        if self._func.docstring.returns and self._no_prop_return:
+            self._add(_E[108], hint=True)
+
+    def _return_not_typed(self) -> None:
+        if self._func.signature.rettype is None and not self._no_returns:
+            self._add(_E[109])
+
+    def _missing_return(self) -> None:
+        hint = False
+        if (
+            self._func.signature.returns
+            and not self._func.docstring.returns
+            and not self._no_returns
+        ):
+            docstring = self._func.docstring.string
+            if docstring is not None and _RETURN in docstring:
+                hint = True
+
+            self._add(_E[105], hint=hint)
+
+    def _incorrect(self, sig: _Param, doc: _Param) -> None:
+        if sig.name is None and doc.name is None:
+            self._add(_E[107])
+
+    # final catch-all
+    def _not_equal(self, sig: _Param, doc: _Param) -> None:
+        if sig.name is not None and doc.name is not None and not self._errors:
+            self._add(_E[110])
+
+    def _class_return(self) -> None:
+        if self._func.docstring.returns and self._func.isinit:
+            self._add(_E[111], hint=True)
+
+    def _misspelled(self, sig: _Param, doc: _Param) -> None:
+        if (
+            sig.name is not None
+            and doc.name is not None
+            and not self._errors
+            and _almost_equal(sig.name, doc.name, _MIN_MATCH, _MAX_MATCH)
+        ):
+            self._add(_E[112])
+
+    def _description_syntax(self, doc: _Param) -> None:
+        if doc.description is not None and not doc.description.startswith(" "):
+            self._add(_E[115])
+
+    def _indent_syntax(self, doc: _Param) -> None:
+        if doc.indent > 0:
+            self._add(_E[116])
+
+    def _invalid_directive(self) -> None:
+        for directive in self._func.directives:
+            if not directive.isvalid:
+                err = _E[int(f"20{1 if directive.ismodule else 2}")]
+                self._add(err, directive=directive.kind)
+
+    def _invalid_directive_options(self) -> None:
+        for directive in self._func.directives:
+            if directive.rules.unknown:
+                err = _E[int(f"20{3 if directive.ismodule else 4}")]
+                for rule in directive.rules.unknown:
+                    self._add(
+                        err, directive=directive.kind, option=rule.description
+                    )
+
+    def get_report(self, prefix: str = "") -> str:
+        """Get report compiled as a string.
+
+        :param prefix: Prefix report.
+        :return: Current report.
+        """
+        report = f"\n{prefix}".join(self)
+        return f"{report}\n"

{docsig-0.47.0 → docsig-0.49.0}/docsig/_stub.py

@@ -20,16 +20,19 @@ RETURN = "return"
 ARG = "arg"
 
 
+# noinspection PyTypeChecker
 class _GoogleDocstring(str):
     def __new__(cls, string: str) -> _GoogleDocstring:
         return super().__new__(cls, str(_s.GoogleDocstring(string)))
 
 
+# noinspection PyTypeChecker
 class _NumpyDocstring(str):
     def __new__(cls, string: str) -> _NumpyDocstring:
         return super().__new__(cls, str(_s.NumpyDocstring(string)))
 
 
+# noinspection PyTypeChecker
 class _DocFmt(str):
     def __new__(cls, string: str) -> _DocFmt:
         return super().__new__(
@@ -40,6 +43,7 @@ class _DocFmt(str):
         )
 
 
+# noinspection PyTypeChecker
 class _RawDocstring(str):
     def __new__(cls, string: str) -> _RawDocstring:
         return super().__new__(

{docsig-0.47.0 → docsig-0.49.0}/docsig/_utils.py

@@ -7,6 +7,8 @@ from __future__ import annotations as _
 
 from difflib import SequenceMatcher as _SequenceMatcher
 
+import click as _click
+
 
 def almost_equal(str1: str, str2: str, mini: float, maxi: float) -> bool:
     """Show result for more than the minimum but less than the maximum.
@@ -28,4 +30,4 @@ def vprint(msg: str, verbose: bool = False) -> None:
     :param verbose: Whether verbose mode is enabled.
     """
     if verbose:
-        print(msg)
+        _click.echo(msg)

{docsig-0.47.0 → docsig-0.49.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.47.0"
+__version__ = "0.49.0"

{docsig-0.47.0 → docsig-0.49.0}/pyproject.toml

@@ -19,6 +19,7 @@ line-length = 79
 [tool.constcheck]
 ignore_strings = [
   "disable",
+  "red",
   "store",
   "store_true",
   "targets",
@@ -72,16 +73,15 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.47.0"
+version = "0.49.0"
 
 [tool.poetry.dependencies]
 Pygments = "^2.13.0"
 Sphinx = "^7.0.0"
 arcon = ">=0.4.0"
 astroid = "^3.0.1"
-object-colors = "^2.1.0"
+click = "^8.1.7"
 python = "^3.8"
-typing-extensions = "^4.8.0"
 
 [tool.poetry.dev-dependencies]
 bump2version = "^1.0.1"

docsig-0.47.0/docsig/_main.py

@@ -1,47 +0,0 @@
-"""
-docsig._main
-============
-
-Contains package entry point.
-"""
-
-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
-
-
-def main() -> str | int:
-    """Main function for package.
-
-    Collect config and arguments for the commandline.
-
-    :return: Exit status for whether test failed or not.
-    """
-    parser = _Parser()
-    _pretty_print_error()
-    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,
-        check_protected_class_methods=(
-            parser.args.check_protected_class_methods
-        ),
-        check_nested=parser.args.check_nested,
-        check_overridden=parser.args.check_overridden,
-        check_protected=parser.args.check_protected,
-        check_property_returns=parser.args.check_property_returns,
-        ignore_no_params=parser.args.ignore_no_params,
-        ignore_args=parser.args.ignore_args,
-        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.47.0/docsig/_report.py

@@ -1,275 +0,0 @@
-"""
-docsig._report
-==============
-"""
-
-from __future__ import annotations as _
-
-import typing as _t
-
-from ._message import Message as _Message
-from ._module import Function as _Function
-from ._stub import RETURN as _RETURN
-from ._stub import Param as _Param
-from ._utils import almost_equal as _almost_equal
-from .messages import TEMPLATE as _TEMPLATE
-from .messages import E as _E
-
-_MIN_MATCH = 0.8
-_MAX_MATCH = 1.0
-
-
-class _MessageSequence(_t.List[str]):
-    def __init__(
-        self,
-        targets: list[_Message],
-        disable: list[_Message],
-    ) -> None:
-        super().__init__()
-        self._disable = list(disable)
-        if targets:
-            errors = list(_E.all(1))
-            for target in targets:
-                errors.remove(target)
-
-            self._disable.extend(errors)
-
-        self._errors: list[_Message] = []
-
-    def add(self, value: _Message, hint: bool = False, **kwargs) -> None:
-        """Add an error to the container.
-
-        :param value: Value to add.
-        :param hint: Whether to print a hint or not.
-        :param kwargs: Variable(s) if format string.
-        """
-        self._errors.append(value)
-        message = value.fstring(_TEMPLATE)
-        if kwargs:
-            message = message.format(**kwargs)
-
-        if hint:
-            message += f"\nhint: {value.hint}"
-
-        if value not in self._disable and message not in self:
-            super().append(message)
-
-
-class Report(_MessageSequence):
-    """Compile and produce report.
-
-    :param func: Function object.
-    :param targets: List of errors to target.
-    :param disable: List of errors to disable.
-    :param check_property_returns: Run return checks on properties.
-    """
-
-    def __init__(
-        self,
-        func: _Function,
-        targets: list[_Message],
-        disable: list[_Message],
-        check_property_returns: bool,
-    ) -> None:
-        super().__init__(targets, disable)
-        self._func = func
-        self._no_prop_return = func.isproperty and not check_property_returns
-        self._no_returns = func.isinit or self._no_prop_return
-
-    def order(self, sig: _Param, doc: _Param) -> None:
-        """Test for documented parameters and their order.
-
-        :param sig: Signature argument.
-        :param doc: Docstring argument.
-        """
-        if any(sig.name == i.name for i in self._func.docstring.args) or any(
-            doc.name == i.name for i in self._func.signature.args
-        ):
-            self.add(_E[101])
-
-    def exists(self) -> None:
-        """Test that non-existing parameter is not documented."""
-        if len(self._func.docstring.args) > len(self._func.signature.args):
-            self.add(_E[102])
-
-    def missing_func_docstring(self) -> None:
-        """Test that docstring is not missing from func."""
-        if not self._func.isinit and self._func.docstring.string is None:
-            self.add(_E[113])
-
-    def missing_class_docstring(self) -> None:
-        """Test that docstring is not missing from class."""
-        if self._func.isinit and self._func.docstring.string is None:
-            self.add(_E[114])
-
-    def missing(self) -> None:
-        """Test that parameter is not missing from documentation."""
-        if len(self._func.signature.args) > len(self._func.docstring.args):
-            self.add(_E[103])
-
-    def duplicates(self) -> None:
-        """Test that there are no duplicate parameters in docstring."""
-        if self._func.docstring.args.duplicated:
-            self.add(_E[106])
-
-    def extra_return(self) -> None:
-        """Check that return is not documented when there is none."""
-        if (
-            self._func.docstring.returns
-            and self._func.signature.rettype == "None"
-            and not self._no_returns
-        ):
-            self.add(_E[104])
-
-    def property_return(self) -> None:
-        """Check that return is not documented for property."""
-        if self._func.docstring.returns and self._no_prop_return:
-            self.add(_E[108], hint=True)
-
-    def return_not_typed(self) -> None:
-        """Check that return is not documented when no type provided."""
-        if self._func.signature.rettype is None and not self._no_returns:
-            self.add(_E[109])
-
-    def missing_return(self) -> None:
-        """Check that return is documented when func returns value."""
-        hint = False
-        if (
-            self._func.signature.returns
-            and not self._func.docstring.returns
-            and not self._no_returns
-        ):
-            docstring = self._func.docstring.string
-            if docstring is not None and _RETURN in docstring:
-                hint = True
-
-            self.add(_E[105], hint=hint)
-
-    def incorrect(self, sig: _Param, doc: _Param) -> None:
-        """Test that proper syntax is used when documenting parameters.
-
-        :param sig: Signature argument.
-        :param doc: Docstring argument.
-        """
-        if sig.name is None and doc.name is None:
-            self.add(_E[107])
-
-    def not_equal(self, sig: _Param, doc: _Param) -> None:
-        """Final catch-all.
-
-        Only applies if no other errors, including disabled, have been
-        triggered
-
-        :param sig: Signature argument.
-        :param doc: Docstring argument.
-        """
-        if sig.name is not None and doc.name is not None and not self._errors:
-            self.add(_E[110])
-
-    def class_return(self) -> None:
-        """Check that return is not documented for __init__."""
-        if self._func.docstring.returns and self._func.isinit:
-            self.add(_E[111], hint=True)
-
-    def misspelled(self, sig: _Param, doc: _Param) -> None:
-        """Test whether there is a spelling error in documentation.
-
-        To avoid false positives also check whether doc param is almost
-        equal amongst its sibling params. If params are too similarly
-        named then this error won't be raised.
-
-        :param sig: Signature argument.
-        :param doc: Docstring argument.
-        """
-        if (
-            sig.name is not None
-            and doc.name is not None
-            and not self._errors
-            and _almost_equal(sig.name, doc.name, _MIN_MATCH, _MAX_MATCH)
-        ):
-            self.add(_E[112])
-
-    def description_syntax(self, doc: _Param) -> None:
-        """Test whether docstring description has correct spacing.
-
-        :param doc: Docstring argument.
-        """
-        if doc.description is not None and not doc.description.startswith(" "):
-            self.add(_E[115])
-
-    def indent_syntax(self, doc: _Param) -> None:
-        """Test whether docstring description is indented correctly.
-
-        :param doc: Docstring argument.
-        """
-        if doc.indent > 0:
-            self.add(_E[116])
-
-    def invalid_directive(self) -> None:
-        """Report on any invalid directives belonging to this func."""
-        for directive in self._func.directives:
-            if not directive.isvalid:
-                err = _E[int(f"20{1 if directive.ismodule else 2}")]
-                self.add(err, directive=directive.kind)
-
-    def invalid_directive_options(self) -> None:
-        """Report on any invalid directive options belonging to this."""
-        for directive in self._func.directives:
-            if directive.rules.unknown:
-                err = _E[int(f"20{3 if directive.ismodule else 4}")]
-                for rule in directive.rules.unknown:
-                    self.add(
-                        err, directive=directive.kind, option=rule.description
-                    )
-
-    def get_report(self, prefix: str = "") -> str:
-        """Get report compiled as a string.
-
-        :param prefix: Prefix report.
-        :return: Current report.
-        """
-        report = f"\n{prefix}".join(self)
-        return f"{report}\n"
-
-
-def generate_report(
-    func: _Function,
-    targets: list[_Message],
-    disable: list[_Message],
-    check_property_returns: bool,
-) -> Report:
-    """Generate report if function or method has failed.
-
-    :param func: Function object.
-    :param targets: List of errors to target.
-    :param disable: List of errors to disable.
-    :param check_property_returns: Run return checks on properties.
-    :return: Compiled report.
-    """
-    report = Report(func, targets, disable, check_property_returns)
-    report.invalid_directive()
-    report.invalid_directive_options()
-    report.missing_class_docstring()
-    report.missing_func_docstring()
-    if func.docstring.string is not None:
-        report.return_not_typed()
-        report.exists()
-        report.missing()
-        report.duplicates()
-        report.extra_return()
-        report.missing_return()
-        report.property_return()
-        report.class_return()
-        for index in range(len(func)):
-            arg = func.signature.args.get(index)
-            doc = func.docstring.args.get(index)
-            report.description_syntax(doc)
-            report.indent_syntax(doc)
-            if arg != doc:
-                report.order(arg, doc)
-                report.incorrect(arg, doc)
-                report.misspelled(arg, doc)
-                report.not_equal(arg, doc)
-
-    report.sort()
-    return report