docsig 0.40.0__tar.gz → 0.42.0__tar.gz

{docsig-0.40.0 → docsig-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.40.0
+Version: 0.42.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -18,8 +18,8 @@ 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: arcon (>=0,<1)
-Requires-Dist: astroid (>=2.11.6,<3.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)
 Requires-Dist: typing-extensions (>=4.8.0,<5.0.0)
 Project-URL: Documentation, https://docsig.readthedocs.io/en/latest
@@ -105,31 +105,36 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-v] [-c] [-D] [-o] [-p] [-P] [-i] [-a] [-k] [-n] [-S] [-s STR]
-                             [-d LIST] [-t LIST]
+    usage: docsig [-h] [-v] [-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
 
     positional arguments:
-      path                          directories or files to check
+      path                                 directories or files to check
 
     optional arguments:
-      -h, --help                    show this help message and exit
-      -v, --version                 show program's version number and exit
-      -c, --check-class             check class docstrings
-      -D, --check-dunders           check dunder methods
-      -o, --check-overridden        check overridden methods
-      -p, --check-protected         check protected functions and classes
-      -P, --check-property-returns  check property return values
-      -i, --ignore-no-params        ignore docstrings where parameters are not documented
-      -a, --ignore-args             ignore args prefixed with an asterisk
-      -k, --ignore-kwargs           ignore kwargs prefixed with two asterisks
-      -n, --no-ansi                 disable ansi output
-      -S, --summary                 print a summarised report
-      -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
+      -h, --help                           show this help message and exit
+      -v, --version                        show program's version number and exit
+      -c, --check-class                    check class docstrings
+      -C, --check-class-constructor        check __init__ methods. Note: mutually
+                                           incompatible with -c
+      -D, --check-dunders                  check dunder methods
+      -m, --check-protected-class-methods  check public methods belonging to protected
+                                           classes
+      -o, --check-overridden               check overridden methods
+      -p, --check-protected                check protected functions and classes
+      -P, --check-property-returns         check property return values
+      -i, --ignore-no-params               ignore docstrings where parameters are not
+                                           documented
+      -a, --ignore-args                    ignore args prefixed with an asterisk
+      -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
+      -n, --no-ansi                        disable ansi output
+      -S, --summary                        print a summarised report
+      -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
 
 Options can also be configured with the pyproject.toml file
 
@@ -195,7 +200,7 @@ API
         :param param3: ✖
         """
     <BLANKLINE>
-    E102: includes parameters that do not exist
+    E102: includes parameters that do not exist (params-do-not-exist)
     <BLANKLINE>
     1
 
@@ -244,7 +249,7 @@ To disable individual function checks add an inline comment similar to the examp
         :param param3: ✖
         """
     <BLANKLINE>
-    E102: includes parameters that do not exist
+    E102: includes parameters that do not exist (params-do-not-exist)
     <BLANKLINE>
     18
     --
@@ -255,7 +260,7 @@ To disable individual function checks add an inline comment similar to the examp
         :param None: ✖
         """
     <BLANKLINE>
-    E103: parameters missing
+    E103: parameters missing (params-missing)
     <BLANKLINE>
     1
 
@@ -331,7 +336,7 @@ To disable multiple function checks add a module level disable and enable commen
         :param None: ✖
         """
     <BLANKLINE>
-    E103: parameters missing
+    E103: parameters missing (params-missing)
     <BLANKLINE>
     1
 
@@ -378,7 +383,7 @@ The same can be done for disabling individual rules
         :return: ✖
         """
     <BLANKLINE>
-    E105: return missing from docstring
+    E105: return missing from docstring (return-missing)
     <BLANKLINE>
     20
     --
@@ -390,9 +395,9 @@ The same can be done for disabling individual rules
         :param None: ✖
         """
     <BLANKLINE>
-    E102: includes parameters that do not exist
-    E106: duplicate parameters found
-    E107: parameter appears to be incorrectly documented
+    E102: includes parameters that do not exist (params-do-not-exist)
+    E106: duplicate parameters found (duplicate-params-found)
+    E107: parameter appears to be incorrectly documented (param-incorrectly-documented)
     <BLANKLINE>
     1
 
@@ -441,16 +446,44 @@ Module level directives will be evaluated separately to inline directives and pr
         :param param3: ✖
         """
     <BLANKLINE>
-    E102: includes parameters that do not exist
-    E106: duplicate parameters found
+    E102: includes parameters that do not exist (params-do-not-exist)
+    E106: duplicate parameters found (duplicate-params-found)
     <BLANKLINE>
     1
 
 Classes
 *******
-Checking a class docstring is not enabled by default, as this check is opinionated, and won't suite everyone
+Checking a class docstring is not enabled by default, as there are two mutually exclusive choices to choose from.
 
-This check will check documentation of ``__init__`` under the class docstring, and not under ``__init__`` itself
+This check will either check the documentation of ``__init__``, or check documentation of ``__init__`` under the class docstring, and not under ``__init__`` itself
+
+.. code-block:: python
+
+    >>> string = """
+    ... class Klass:
+    ...     def __init__(self, param1, param2) -> None:
+    ...         '''
+    ...
+    ...         :param param1: About param1.
+    ...         :param param2: About param2.
+    ...         :param param3: About param3.
+    ...         '''
+    ... """
+    >>> docsig(string=string, check_class_constructor=True)
+    3 in Klass
+    ----------
+    class Klass:
+        """
+        :param param1: ✓
+        :param param2: ✓
+        :param param3: ✖
+        """
+    <BLANKLINE>
+        def __init__(✓param1, ✓param2, ✖None) -> ✓None:
+    <BLANKLINE>
+    E102: includes parameters that do not exist (params-do-not-exist)
+    <BLANKLINE>
+    1
 
 .. code-block:: python
 
@@ -477,12 +510,19 @@ This check will check documentation of ``__init__`` under the class docstring, a
     <BLANKLINE>
         def __init__(✓param1, ✓param2, ✖None) -> ✓None:
     <BLANKLINE>
-    E102: includes parameters that do not exist
+    E102: includes parameters that do not exist (params-do-not-exist)
     <BLANKLINE>
     1
 
 Checking class docstrings can be permanently enabled in the pyproject.toml file
 
+.. code-block:: toml
+
+    [tool.docsig]
+    check-class-constructor = true
+
+Or
+
 .. code-block:: toml
 
     [tool.docsig]
@@ -499,7 +539,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.40.0
+        rev: v0.42.0
         hooks:
           - id: docsig
             args:

{docsig-0.40.0 → docsig-0.42.0}/README.rst

@@ -77,31 +77,36 @@ Commandline
 
 .. code-block:: console
 
-    usage: docsig [-h] [-v] [-c] [-D] [-o] [-p] [-P] [-i] [-a] [-k] [-n] [-S] [-s STR]
-                             [-d LIST] [-t LIST]
+    usage: docsig [-h] [-v] [-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
 
     positional arguments:
-      path                          directories or files to check
+      path                                 directories or files to check
 
     optional arguments:
-      -h, --help                    show this help message and exit
-      -v, --version                 show program's version number and exit
-      -c, --check-class             check class docstrings
-      -D, --check-dunders           check dunder methods
-      -o, --check-overridden        check overridden methods
-      -p, --check-protected         check protected functions and classes
-      -P, --check-property-returns  check property return values
-      -i, --ignore-no-params        ignore docstrings where parameters are not documented
-      -a, --ignore-args             ignore args prefixed with an asterisk
-      -k, --ignore-kwargs           ignore kwargs prefixed with two asterisks
-      -n, --no-ansi                 disable ansi output
-      -S, --summary                 print a summarised report
-      -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
+      -h, --help                           show this help message and exit
+      -v, --version                        show program's version number and exit
+      -c, --check-class                    check class docstrings
+      -C, --check-class-constructor        check __init__ methods. Note: mutually
+                                           incompatible with -c
+      -D, --check-dunders                  check dunder methods
+      -m, --check-protected-class-methods  check public methods belonging to protected
+                                           classes
+      -o, --check-overridden               check overridden methods
+      -p, --check-protected                check protected functions and classes
+      -P, --check-property-returns         check property return values
+      -i, --ignore-no-params               ignore docstrings where parameters are not
+                                           documented
+      -a, --ignore-args                    ignore args prefixed with an asterisk
+      -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
+      -n, --no-ansi                        disable ansi output
+      -S, --summary                        print a summarised report
+      -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
 
 Options can also be configured with the pyproject.toml file
 
@@ -167,7 +172,7 @@ API
         :param param3: ✖
         """
     <BLANKLINE>
-    E102: includes parameters that do not exist
+    E102: includes parameters that do not exist (params-do-not-exist)
     <BLANKLINE>
     1
 
@@ -216,7 +221,7 @@ To disable individual function checks add an inline comment similar to the examp
         :param param3: ✖
         """
     <BLANKLINE>
-    E102: includes parameters that do not exist
+    E102: includes parameters that do not exist (params-do-not-exist)
     <BLANKLINE>
     18
     --
@@ -227,7 +232,7 @@ To disable individual function checks add an inline comment similar to the examp
         :param None: ✖
         """
     <BLANKLINE>
-    E103: parameters missing
+    E103: parameters missing (params-missing)
     <BLANKLINE>
     1
 
@@ -303,7 +308,7 @@ To disable multiple function checks add a module level disable and enable commen
         :param None: ✖
         """
     <BLANKLINE>
-    E103: parameters missing
+    E103: parameters missing (params-missing)
     <BLANKLINE>
     1
 
@@ -350,7 +355,7 @@ The same can be done for disabling individual rules
         :return: ✖
         """
     <BLANKLINE>
-    E105: return missing from docstring
+    E105: return missing from docstring (return-missing)
     <BLANKLINE>
     20
     --
@@ -362,9 +367,9 @@ The same can be done for disabling individual rules
         :param None: ✖
         """
     <BLANKLINE>
-    E102: includes parameters that do not exist
-    E106: duplicate parameters found
-    E107: parameter appears to be incorrectly documented
+    E102: includes parameters that do not exist (params-do-not-exist)
+    E106: duplicate parameters found (duplicate-params-found)
+    E107: parameter appears to be incorrectly documented (param-incorrectly-documented)
     <BLANKLINE>
     1
 
@@ -413,16 +418,44 @@ Module level directives will be evaluated separately to inline directives and pr
         :param param3: ✖
         """
     <BLANKLINE>
-    E102: includes parameters that do not exist
-    E106: duplicate parameters found
+    E102: includes parameters that do not exist (params-do-not-exist)
+    E106: duplicate parameters found (duplicate-params-found)
     <BLANKLINE>
     1
 
 Classes
 *******
-Checking a class docstring is not enabled by default, as this check is opinionated, and won't suite everyone
+Checking a class docstring is not enabled by default, as there are two mutually exclusive choices to choose from.
 
-This check will check documentation of ``__init__`` under the class docstring, and not under ``__init__`` itself
+This check will either check the documentation of ``__init__``, or check documentation of ``__init__`` under the class docstring, and not under ``__init__`` itself
+
+.. code-block:: python
+
+    >>> string = """
+    ... class Klass:
+    ...     def __init__(self, param1, param2) -> None:
+    ...         '''
+    ...
+    ...         :param param1: About param1.
+    ...         :param param2: About param2.
+    ...         :param param3: About param3.
+    ...         '''
+    ... """
+    >>> docsig(string=string, check_class_constructor=True)
+    3 in Klass
+    ----------
+    class Klass:
+        """
+        :param param1: ✓
+        :param param2: ✓
+        :param param3: ✖
+        """
+    <BLANKLINE>
+        def __init__(✓param1, ✓param2, ✖None) -> ✓None:
+    <BLANKLINE>
+    E102: includes parameters that do not exist (params-do-not-exist)
+    <BLANKLINE>
+    1
 
 .. code-block:: python
 
@@ -449,12 +482,19 @@ This check will check documentation of ``__init__`` under the class docstring, a
     <BLANKLINE>
         def __init__(✓param1, ✓param2, ✖None) -> ✓None:
     <BLANKLINE>
-    E102: includes parameters that do not exist
+    E102: includes parameters that do not exist (params-do-not-exist)
     <BLANKLINE>
     1
 
 Checking class docstrings can be permanently enabled in the pyproject.toml file
 
+.. code-block:: toml
+
+    [tool.docsig]
+    check-class-constructor = true
+
+Or
+
 .. code-block:: toml
 
     [tool.docsig]
@@ -471,7 +511,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.40.0
+        rev: v0.42.0
         hooks:
           - id: docsig
             args:

{docsig-0.40.0 → docsig-0.42.0}/docsig/_config.py

@@ -53,6 +53,12 @@ class Parser(_ArgumentParser):
             action="store_true",
             help="check dunder methods",
         )
+        self.add_argument(
+            "-m",
+            "--check-protected-class-methods",
+            action="store_true",
+            help="check public methods belonging to protected classes",
+        )
         self.add_argument(
             "-o",
             "--check-overridden",
@@ -90,7 +96,10 @@ class Parser(_ArgumentParser):
             help="ignore kwargs prefixed with two asterisks",
         )
         self.add_argument(
-            "-n", "--no-ansi", action="store_true", help="disable ansi output"
+            "-n",
+            "--no-ansi",
+            action="store_true",
+            help="disable ansi output",
         )
         self.add_argument(
             "-S",

{docsig-0.40.0 → docsig-0.42.0}/docsig/_core.py

@@ -13,9 +13,11 @@ 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 E as _E
 
 
 def pretty_print_error() -> None:
@@ -36,14 +38,18 @@ def _run_check(  # pylint: disable=too-many-arguments
     check_property_returns: bool,
     ignore_no_params: bool,
     no_ansi: bool,
-    targets: list[str],
+    targets: list[_Message],
 ) -> _Failures:
     failures = _Failures()
     for func in parent:
         if not (func.isoverridden and not check_overridden) and (
             not (func.isprotected and not check_protected)
             and not (
-                func.isinit and not (check_class or check_class_constructor)
+                func.isinit
+                and not (
+                    (check_class or check_class_constructor)
+                    and not (parent.isprotected and not check_protected)
+                )
             )
             and not (func.isdunder and not check_dunders)
             and not (func.docstring.bare and ignore_no_params)
@@ -59,12 +65,13 @@ def _run_check(  # pylint: disable=too-many-arguments
     return failures
 
 
-def docsig(  # pylint: disable=too-many-locals
+def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     *path: _Path,
     string: str | None = None,
     check_class: bool = False,
     check_class_constructor: bool = False,
     check_dunders: bool = False,
+    check_protected_class_methods: bool = False,
     check_overridden: bool = False,
     check_protected: bool = False,
     check_property_returns: bool = False,
@@ -91,6 +98,8 @@ def docsig(  # pylint: disable=too-many-locals
     :param check_class_constructor: Check ``__init__`` methods. Note that this
         is mutually incompatible with check_class.
     :param check_dunders: Check dunder methods
+    :param check_protected_class_methods: Check public methods belonging
+        to protected classes.
     :param check_overridden: Check overridden methods
     :param check_protected: Check protected functions and classes.
     :param check_property_returns: Run return checks on properties.
@@ -104,9 +113,23 @@ def docsig(  # pylint: disable=too-many-locals
     :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}'",
+            )
+
     modules = _Modules(
         *path,
-        disable=disable or [],
+        disable=disabled_args,
         string=string,
         ignore_args=ignore_args,
         ignore_kwargs=ignore_kwargs,
@@ -115,7 +138,11 @@ def docsig(  # pylint: disable=too-many-locals
     display = _Display(no_ansi)
     for module in modules:
         for top_level in module:
-            if not top_level.isprotected or check_protected:
+            if (
+                not top_level.isprotected
+                or check_protected
+                or check_protected_class_methods
+            ):
                 failures = _run_check(
                     top_level,
                     check_class,
@@ -126,7 +153,7 @@ def docsig(  # pylint: disable=too-many-locals
                     check_property_returns,
                     ignore_no_params,
                     no_ansi,
-                    targets or [],
+                    target_args,
                 )
                 if failures:
                     display[top_level.path].append(failures)

{docsig-0.40.0 → docsig-0.42.0}/docsig/_directives.py

@@ -11,14 +11,11 @@ from io import StringIO as _StringIO
 
 from typing_extensions import Self as _Self
 
-from . import messages as _messages
+from ._message import Message as _Message
+from .messages import E as _E
 
-ERRORS = tuple(
-    i for i in dir(_messages) if not i.startswith("__") and i.startswith("E1")
-)
 
-
-class _Rules(_t.List[str]):
+class _Rules(_t.List[_Message]):
     def __init__(self, kind: str) -> None:
         super().__init__()
         self._unknown = []
@@ -26,19 +23,21 @@ class _Rules(_t.List[str]):
         delimiter = _re.search(r"\W+", kind)
         if delimiter and delimiter[0] == "=":
             self._kind, option = kind.split("=")
+            message = _E.fromref(option)
             if "," in option:
                 values = option.split(",")
                 for value in values:
-                    if value in ERRORS:
-                        self.append(value)
+                    message = _E.fromref(value)
+                    if message.isknown:
+                        self.append(message)
                     else:
-                        self._unknown.append(value)
-            elif option not in ERRORS:
-                self._unknown.append(option)
+                        self._unknown.append(message)
+            elif message.isknown:
+                self.append(message)
             else:
-                self.append(option)
+                self._unknown.append(message)
         else:
-            self.extend(ERRORS)
+            self.extend(_E.all(1))
 
     @property
     def kind(self) -> str:
@@ -46,7 +45,7 @@ class _Rules(_t.List[str]):
         return self._kind
 
     @property
-    def unknown(self) -> list[str]:
+    def unknown(self) -> list[_Message]:
         """List of unknown directive options if any."""
         return self._unknown
 
@@ -110,7 +109,9 @@ class Directive:
         return None
 
 
-class Directives(_t.Dict[int, _t.Tuple[_t.List[Directive], _t.List[str]]]):
+class Directives(
+    _t.Dict[int, _t.Tuple[_t.List[Directive], _t.List[_Message]]]
+):
     """Data for directives:
 
     Dict like object with the line number of directive as the key and
@@ -120,7 +121,7 @@ class Directives(_t.Dict[int, _t.Tuple[_t.List[Directive], _t.List[str]]]):
     :param disable: List of checks to disable.
     """
 
-    def __init__(self, text: str, disable: list[str]) -> None:
+    def __init__(self, text: str, disable: list[_Message]) -> None:
         super().__init__()
         fin = _StringIO(text)
         module_disables = list(disable)

{docsig-0.40.0 → docsig-0.42.0}/docsig/_function.py

@@ -13,6 +13,7 @@ import astroid as _ast
 import sphinx.ext.napoleon as _s
 
 from ._directives import Directive as _Directive
+from ._message import Message as _Message
 from ._utils import isprotected as _isprotected
 
 PARAM = "param"
@@ -286,7 +287,7 @@ class Function:  # pylint: disable=too-many-arguments
         self,
         node: _ast.FunctionDef,
         directives: _t.List[_Directive],
-        disabled: list[str],
+        disabled: list[_Message],
         ignore_args: bool = False,
         ignore_kwargs: bool = False,
         check_class_constructor: bool = False,
@@ -402,7 +403,7 @@ class Function:  # pylint: disable=too-many-arguments
         return self._docstring
 
     @property
-    def disabled(self) -> list[str]:
+    def disabled(self) -> list[_Message]:
         """List of disabled checks specific to this function."""
         return self._disabled
 

{docsig-0.40.0 → docsig-0.42.0}/docsig/_main.py

@@ -24,6 +24,9 @@ def main() -> int:
         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_overridden=parser.args.check_overridden,
         check_protected=parser.args.check_protected,
         check_property_returns=parser.args.check_property_returns,

docsig-0.42.0/docsig/_message.py

@@ -0,0 +1,69 @@
+"""
+docsig._message
+===============
+"""
+from __future__ import annotations as _
+
+import typing as _t
+
+UNKNOWN = "E000"
+
+
+class Message(_t.NamedTuple):
+    """Message type for errors."""
+
+    code: str
+    description: str
+    symbolic: str = ""
+    hint: _t.Optional[str] = None
+
+    @property
+    def isknown(self) -> bool:
+        """Whether this is a known error."""
+        return self.code != UNKNOWN
+
+    def fstring(self, template: str) -> str:
+        """Return values as a format string.
+
+        :param template: String to interpolate values.
+        :return: Formatted string.
+        """
+        return template.format(
+            code=self.code,
+            description=self.description,
+            symbolic=self.symbolic,
+        )
+
+
+class Messages(_t.Dict[int, Message]):
+    """Object for storing and retrieving message objects."""
+
+    def fromref(self, ref: str) -> Message:
+        """Get a message by its code or symbolic reference.
+
+        :param ref: Code or symbolic reference.
+        :return: Message if valid ref else an unknown message type.
+        """
+        for value in self.values():
+            if ref in (value.code, value.symbolic):
+                return value
+
+        return Message(UNKNOWN, ref)
+
+    def fromcodes(self, refs: list[str]) -> tuple[Message, ...]:
+        """Get tuple of message types from codes or symbolic references.
+
+        :param refs: Tuple of codes or symbolic references.
+        :return: Tuple of message types.
+        """
+        return tuple(self.fromref(i) for i in refs)
+
+    def all(self, category: int) -> tuple[Message, ...]:
+        """Get all messages belonging to a category.
+
+        :param category: Index of message category.
+        :return: Tuple of all message objects belonging to category.
+        """
+        return tuple(
+            v for k, v in self.items() if str(k).startswith(str(category))
+        )

{docsig-0.40.0 → docsig-0.42.0}/docsig/_module.py

@@ -11,6 +11,7 @@ import astroid as _ast
 
 from ._directives import Directives as _Directives
 from ._function import Function as _Function
+from ._message import Message as _Message
 from ._utils import isprotected as _isprotected
 
 
@@ -87,7 +88,7 @@ class _Module(_t.List[Parent]):
     def __init__(  # pylint: disable=too-many-arguments
         self,
         string: str,
-        disable: list[str],
+        disable: list[_Message],
         path: _Path | None = None,
         ignore_args: bool = False,
         ignore_kwargs: bool = False,
@@ -129,10 +130,10 @@ class Modules(_t.List[_Module]):
         be on the class level docstring.
     """
 
-    def __init__(
+    def __init__(  # pylint: disable=too-many-arguments
         self,
         *paths: _Path,
-        disable: list[str],
+        disable: list[_Message],
         string: str | None = None,
         ignore_args: bool = False,
         ignore_kwargs: bool = False,

{docsig-0.40.0 → docsig-0.42.0}/docsig/_report.py

@@ -6,12 +6,13 @@ from __future__ import annotations as _
 
 import typing as _t
 
-from . import messages as _messages
-from ._directives import ERRORS as _ERRORS
 from ._function import RETURN as _RETURN
 from ._function import Function as _Function
 from ._function import Param as _Param
+from ._message import Message as _Message
 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
@@ -20,43 +21,36 @@ _MAX_MATCH = 1.0
 class _MessageSequence(_t.List[str]):
     def __init__(
         self,
-        targets: list[str] | None = None,
-        disable: list[str] | None = None,
+        targets: list[_Message],
+        disable: list[_Message],
     ) -> None:
         super().__init__()
-        self._disable = disable or []
-        self._disabled = False
+        self._disable = list(disable)
         if targets:
-            errors = list(_ERRORS)
+            errors = list(_E.all(1))
             for target in targets:
                 errors.remove(target)
 
             self._disable.extend(errors)
 
-        self._errors: list[str] = []
+        self._errors: list[_Message] = []
 
-    def add(self, value: str, **kwargs) -> None:
+    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.
         """
-        # if the last code to be disabled was an error then all
-        # following hints are disabled until a new error is evaluated
-        if value.startswith("E"):
-            self._disabled = False
-            self._errors.append(value)
-
-        if value in self._disable:
-            self._disabled = True
-
-        message = getattr(_messages, value)
+        self._errors.append(value)
+        message = value.fstring(_TEMPLATE)
         if kwargs:
             message = message.format(**kwargs)
 
-        if not self._disabled and not (
-            value.startswith("E") and message in self
-        ):
+        if hint:
+            message += f"\nhint: {value.hint}"
+
+        if value not in self._disable and message not in self:
             super().append(message)
 
 
@@ -72,8 +66,8 @@ class Report(_MessageSequence):
     def __init__(
         self,
         func: _Function,
-        targets: list[str],
-        disable: list[str],
+        targets: list[_Message],
+        disable: list[_Message],
         check_property_returns: bool,
     ) -> None:
         super().__init__(targets, disable)
@@ -90,32 +84,32 @@ class Report(_MessageSequence):
         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("E101")
+            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("E102")
+            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("E113")
+            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("E114")
+            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("E103")
+            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("E106")
+            self.add(_E[106])
 
     def extra_return(self) -> None:
         """Check that return is not documented when there is none."""
@@ -124,30 +118,31 @@ class Report(_MessageSequence):
             and self._func.signature.rettype == "None"
             and not self._no_returns
         ):
-            self.add("E104")
+            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("E108")
-            self.add("H101")
+            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("E109")
+            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
         ):
-            self.add("E105")
             docstring = self._func.docstring.string
             if docstring is not None and _RETURN in docstring:
-                self.add("H102")
+                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.
@@ -156,7 +151,7 @@ class Report(_MessageSequence):
         :param doc: Docstring argument.
         """
         if sig.name is None and doc.name is None:
-            self.add("E107")
+            self.add(_E[107])
 
     def not_equal(self, sig: _Param, doc: _Param) -> None:
         """Final catch-all.
@@ -168,13 +163,12 @@ class Report(_MessageSequence):
         :param doc: Docstring argument.
         """
         if sig.name is not None and doc.name is not None and not self._errors:
-            self.add("E110")
+            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("E111")
-            self.add("H103")
+            self.add(_E[111], hint=True)
 
     def misspelled(self, sig: _Param, doc: _Param) -> None:
         """Test whether there is a spelling error in documentation.
@@ -192,7 +186,7 @@ class Report(_MessageSequence):
             and not self._errors
             and _almost_equal(sig.name, doc.name, _MIN_MATCH, _MAX_MATCH)
         ):
-            self.add("E112")
+            self.add(_E[112])
 
     def description_syntax(self, doc: _Param) -> None:
         """Test whether docstring description has correct spacing.
@@ -200,7 +194,7 @@ class Report(_MessageSequence):
         :param doc: Docstring argument.
         """
         if doc.description is not None and not doc.description.startswith(" "):
-            self.add("E115")
+            self.add(_E[115])
 
     def indent_syntax(self, doc: _Param) -> None:
         """Test whether docstring description is indented correctly.
@@ -208,22 +202,24 @@ class Report(_MessageSequence):
         :param doc: Docstring argument.
         """
         if doc.indent > 0:
-            self.add("E116")
+            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 = f"E20{1 if directive.ismodule else 2}"
+                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 = f"E20{3 if directive.ismodule else 4}"
+                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)
+                    self.add(
+                        err, directive=directive.kind, option=rule.description
+                    )
 
     def get_report(self, prefix: str = "") -> str:
         """Get report compiled as a string.
@@ -231,13 +227,14 @@ class Report(_MessageSequence):
         :param prefix: Prefix report.
         :return: Current report.
         """
-        return f"\n{prefix}".join(self) + "\n"
+        report = f"\n{prefix}".join(self)
+        return f"{report}\n"
 
 
 def generate_report(
     func: _Function,
-    targets: list[str],
-    disable: list[str],
+    targets: list[_Message],
+    disable: list[_Message],
     check_property_returns: bool,
 ) -> Report:
     """Generate report if function or method has failed.

{docsig-0.40.0 → docsig-0.42.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.40.0"
+__version__ = "0.42.0"

docsig-0.42.0/docsig/messages.py

@@ -0,0 +1,140 @@
+"""
+docsig.messages
+===============
+| E101: parameters out of order
+| E102: includes parameters that do not exist
+| E103: parameters missing
+| E104: return statement documented for None
+| E105: return missing from docstring
+| E106: duplicate parameters found
+| E107: parameter appears to be incorrectly documented
+| E108: return statement documented for property
+| E109: cannot determine whether a return statement should exist or not
+| E110: documented parameter not equal to its respective argument
+| E111: return statement documented for class
+| E112: spelling error found in documented parameter
+| E113: function is missing a docstring
+| E114: class is missing a docstring
+| E115: syntax error in description
+| E116: param not indented correctly
+| E201: unknown module comment directive '{directive}'
+| E202: unknown inline comment directive '{directive}'
+| E203: unknown module comment option for {directive} '{option}'
+| E204: unknown inline comment option for {directive} '{option}'
+"""
+from ._message import Message as _Message
+from ._message import Messages as _Messages
+
+TEMPLATE = "{code}: {description} ({symbolic})"
+
+
+# Exxx: Error
+E = _Messages(
+    {
+        # E1xx: Docstring
+        101: _Message(
+            "E101",
+            "parameters out of order",
+            "params-out-of-order",
+        ),
+        102: _Message(
+            "E102",
+            "includes parameters that do not exist",
+            "params-do-not-exist",
+        ),
+        103: _Message(
+            "E103",
+            "parameters missing",
+            "params-missing",
+        ),
+        104: _Message(
+            "E104",
+            "return statement documented for None",
+            "return-documented-for-none",
+        ),
+        105: _Message(
+            "E105",
+            "return missing from docstring",
+            "return-missing",
+            "it is possible a syntax error could be causing this",
+        ),
+        106: _Message(
+            "E106",
+            "duplicate parameters found",
+            "duplicate-params-found",
+        ),
+        107: _Message(
+            "E107",
+            "parameter appears to be incorrectly documented",
+            "param-incorrectly-documented",
+        ),
+        108: _Message(
+            "E108",
+            "return statement documented for property",
+            "return-documented-for-property",
+            "documentation is sufficient as a getter is the value returned",
+        ),
+        109: _Message(
+            "E109",
+            "cannot determine whether a return statement should exist or not",
+            "confirm-return-needed",
+        ),
+        110: _Message(
+            "E110",
+            "documented parameter not equal to its respective argument",
+            "param-not-equal-to-arg",
+        ),
+        111: _Message(
+            "E111",
+            "return statement documented for class",
+            "class-return-documented",
+            "a class does not return a value during instantiation",
+        ),
+        112: _Message(
+            "E112",
+            "spelling error found in documented parameter",
+            "spelling-error",
+        ),
+        113: _Message(
+            "E113",
+            "function is missing a docstring",
+            "function-doc-missing",
+        ),
+        114: _Message(
+            "E114",
+            "class is missing a docstring",
+            "class-doc-missing",
+        ),
+        115: _Message(
+            "E115",
+            "syntax error in description",
+            "syntax-error-in-description",
+        ),
+        116: _Message(
+            "E116",
+            "param not indented correctly",
+            "incorrect-indent",
+        ),
+        # E2xx: Config
+        201: _Message(
+            "E201",
+            "unknown module comment directive '{directive}'",
+            "unknown-module-directive",
+        ),
+        202: _Message(
+            "E202",
+            "unknown inline comment directive '{directive}'",
+            "unknown-inline-directive",
+        ),
+        203: _Message(
+            "E203",
+            "unknown module comment option for {directive} '{option}'",
+            "unknown-module-directive-option",
+        ),
+        204: _Message(
+            "E204",
+            "unknown inline comment option for {directive} '{option}'",
+            "unknown-module-directive-option",
+        ),
+    }
+)

{docsig-0.40.0 → docsig-0.42.0}/pyproject.toml

@@ -15,7 +15,6 @@ exclude = '''
 )/
 '''
 line-length = 79
-skip-magic-trailing-comma = true
 
 [tool.constcheck]
 ignore_strings = [
@@ -38,6 +37,7 @@ omit = [
 
 [tool.docsig]
 check-class = true
+check-protected-class-methods = true
 summary = true
 
 [tool.isort]
@@ -70,13 +70,13 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.40.0"
+version = "0.42.0"
 
 [tool.poetry.dependencies]
 Pygments = "^2.13.0"
 Sphinx = ">=4.3.2,<7.0.0"
-arcon = "^0"
-astroid = "^2.11.6"
+arcon = "^0.3.1"
+astroid = "^3.0.1"
 object-colors = "^2.1.0"
 python = "^3.8"
 typing-extensions = "^4.8.0"
@@ -87,7 +87,6 @@ deptry = "^0.12.0"
 ipython = "^8.12.0"
 pre-commit = "^3.3.3"
 pyaud = "^7.2.0"
-pylint = "2.15.10"
 pytest = "^7.4.0"
 pytest-randomly = "^3.13.0"
 pytest-sugar = "^0.9.6"
@@ -118,10 +117,10 @@ audit = [
   "unused"
 ]
 exclude = '''
-  (?x)^(
-    | docs\/conf\.py
-    | whitelist\.py
-  )$
+(?x)^(
+  | docs\/conf\.py
+  | whitelist\.py
+)$
 '''
 
 [tool.pytest.ini_options]

docsig-0.40.0/docsig/messages.py

@@ -1,54 +0,0 @@
-"""
-docsig.messages
-===============
-| E101: parameters out of order
-| E102: includes parameters that do not exist
-| E103: parameters missing
-| E104: return statement documented for None
-| E105: return missing from docstring
-| E106: duplicate parameters found
-| E107: parameter appears to be incorrectly documented
-| E108: return statement documented for property
-| E109: cannot determine whether a return statement should exist or not
-| E110: documented parameter not equal to its respective argument
-| E111: return statement documented for class
-| E112: spelling error found in documented parameter
-| E113: function is missing a docstring
-| E114: class is missing a docstring
-| E115: syntax error in description
-| E116: param not indented correctly
-| E201: unknown module comment directive '{directive}'
-| E202: unknown inline comment directive '{directive}'
-| E203: unknown module comment option for {directive} '{option}'
-| E204: unknown inline comment option for {directive} '{option}'
-"""
-# Exxx: Error
-# E1xx: Docstring
-E101 = "E101: parameters out of order"
-E102 = "E102: includes parameters that do not exist"
-E103 = "E103: parameters missing"
-E104 = "E104: return statement documented for None"
-E105 = "E105: return missing from docstring"
-E106 = "E106: duplicate parameters found"
-E107 = "E107: parameter appears to be incorrectly documented"
-E108 = "E108: return statement documented for property"
-E109 = "E109: cannot determine whether a return statement should exist or not"
-E110 = "E110: documented parameter not equal to its respective argument"
-E111 = "E111: return statement documented for class"
-E112 = "E112: spelling error found in documented parameter"
-E113 = "E113: function is missing a docstring"
-E114 = "E114: class is missing a docstring"
-E115 = "E115: syntax error in description"
-E116 = "E116: param not indented correctly"
-
-# E2xx: Config
-E201 = "E201: unknown module comment directive '{directive}'"
-E202 = "E202: unknown inline comment directive '{directive}'"
-E203 = "E203: unknown module comment option for {directive} '{option}'"
-E204 = "E204: unknown inline comment option for {directive} '{option}'"
-
-# Hxxx: Hint
-# H1xx: Docstring
-H101 = "hint: documentation is sufficient as a getter is the value returned"
-H102 = "hint: it is possible a syntax error could be causing this"
-H103 = "hint: a class does not return a value during instantiation"