docsig 0.82.1__tar.gz → 0.83.0__tar.gz

{docsig-0.82.1 → docsig-0.83.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.82.1
+Version: 0.83.0
 Summary: Check signature params for proper documentation
 License: MIT
 License-File: LICENSE
 Keywords: check,docs,docstring,params,signature
 Author: jshwi
-Author-email: stephen@jshwisolutions.com
+Author-email: s.whitlock@live.com
 Maintainer: jshwi
-Maintainer-email: stephen@jshwisolutions.com
+Maintainer-email: s.whitlock@live.com
 Requires-Python: >=3.10,<4.0
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -36,7 +36,7 @@ Description-Content-Type: text/x-rst
 
 |
 
-|License| |PyPI| |CI| |CodeQL| |pre-commit.ci status| |codecov.io| |readthedocs.org| |python3.10| |Black| |isort| |pylint| |Security Status| |Known Vulnerabilities|
+|License| |PyPI| |CI| |CodeQL| |pre-commit.ci status| |codecov.io| |readthedocs.org| |python3.10| |Black| |isort| |pylint| |Security Status|
 
 .. |License| image:: https://img.shields.io/badge/License-MIT-yellow.svg
    :target: https://opensource.org/licenses/MIT
@@ -74,9 +74,6 @@ Description-Content-Type: text/x-rst
 .. |Security Status| image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security Status
-.. |Known Vulnerabilities| image:: https://snyk.io/test/github/jshwi/docsig/badge.svg
-   :target: https://snyk.io/test/github/jshwi/docsig/badge.svg
-   :alt: Known Vulnerabilities
 
 Check Python signature params for proper documentation
 -------------------------------------------------------
@@ -175,6 +172,20 @@ Options can also be configured with the pyproject.toml file
         "SIG201",
     ]
 
+.. schema-info start
+
+.. _here: https://docsig.io/en/latest/usage/configuration/schema.html
+
+.. _schema: https://docsig.io/en/latest/usage/configuration/schema.json
+
+.. _validate-pyproject: https://github.com/abravalheri/validate-pyproject
+
+Configuration options can be found `here`_ or see the full JSON `schema`_
+
+You can validate your `docsig` configuration with `validate-pyproject`_
+
+.. schema-info end
+
 Flake8
 ******
 
@@ -184,7 +195,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.82.1, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.83.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
 
 And now use `flake8` to lint your files
 
@@ -270,7 +281,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.82.1
+        rev: v0.83.0
         hooks:
           - id: docsig
             args:
@@ -289,7 +300,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.82.1
+              - docsig==0.83.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.82.1 → docsig-0.83.0}/README.rst

@@ -7,7 +7,7 @@
 
 |
 
-|License| |PyPI| |CI| |CodeQL| |pre-commit.ci status| |codecov.io| |readthedocs.org| |python3.10| |Black| |isort| |pylint| |Security Status| |Known Vulnerabilities|
+|License| |PyPI| |CI| |CodeQL| |pre-commit.ci status| |codecov.io| |readthedocs.org| |python3.10| |Black| |isort| |pylint| |Security Status|
 
 .. |License| image:: https://img.shields.io/badge/License-MIT-yellow.svg
    :target: https://opensource.org/licenses/MIT
@@ -45,9 +45,6 @@
 .. |Security Status| image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security Status
-.. |Known Vulnerabilities| image:: https://snyk.io/test/github/jshwi/docsig/badge.svg
-   :target: https://snyk.io/test/github/jshwi/docsig/badge.svg
-   :alt: Known Vulnerabilities
 
 Check Python signature params for proper documentation
 -------------------------------------------------------
@@ -146,6 +143,20 @@ Options can also be configured with the pyproject.toml file
         "SIG201",
     ]
 
+.. schema-info start
+
+.. _here: https://docsig.io/en/latest/usage/configuration/schema.html
+
+.. _schema: https://docsig.io/en/latest/usage/configuration/schema.json
+
+.. _validate-pyproject: https://github.com/abravalheri/validate-pyproject
+
+Configuration options can be found `here`_ or see the full JSON `schema`_
+
+You can validate your `docsig` configuration with `validate-pyproject`_
+
+.. schema-info end
+
 Flake8
 ******
 
@@ -155,7 +166,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.82.1, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.83.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
 
 And now use `flake8` to lint your files
 
@@ -241,7 +252,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.82.1
+        rev: v0.83.0
         hooks:
           - id: docsig
             args:
@@ -260,7 +271,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.82.1
+              - docsig==0.83.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.82.1 → docsig-0.83.0}/docsig/_config.py

@@ -97,11 +97,10 @@ class _ArgumentParser(_argparse.ArgumentParser):
         return namespace, args
 
 
-def parse_args(args: _t.Sequence[str] | None = None) -> _argparse.Namespace:
-    """Parse CLI arguments and merge in config from pyproject.toml.
+def build_parser() -> _ArgumentParser:
+    """Build and return the argument parser.
 
-    :param args: Argument list to parse (defaults to sys.argv).
-    :return: Parsed namespace with config merged in.
+    :return: The argument parser.
     """
     parser = _ArgumentParser(
         description="Check signature params for proper documentation",
@@ -305,6 +304,16 @@ def parse_args(args: _t.Sequence[str] | None = None) -> _argparse.Namespace:
         metavar="STR",
         help="string to parse instead of files",
     )
+    return parser
+
+
+def parse_args(args: _t.Sequence[str] | None = None) -> _argparse.Namespace:
+    """Parse CLI arguments and merge in config from pyproject.toml.
+
+    :param args: Argument list to parse (defaults to sys.argv).
+    :return: Parsed namespace with config merged in.
+    """
+    parser = build_parser()
     return parser.parse_args(args)
 
 

{docsig-0.82.1 → docsig-0.83.0}/docsig/_core.py

@@ -11,6 +11,7 @@ import logging as _logging
 import sys as _sys
 import warnings as _warnings
 from pathlib import Path as _Path
+from pprint import pformat as _pformat
 
 from . import _decorators
 from ._check import run_checks as _run_checks
@@ -202,6 +203,8 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         excludes=excludes or [],
     )
     setup_logger(config.verbose)
+    logger = _logging.getLogger(__package__)
+    logger.debug(_pformat(config))
     if config.list_checks:
         return int(bool(_print_checks()))  # type: ignore
 

{docsig-0.82.1 → docsig-0.83.0}/docsig/_module.py

@@ -9,7 +9,6 @@ from __future__ import annotations as _
 
 import re as _re
 import typing as _t
-from enum import Enum as _Enum
 from pathlib import Path as _Path
 
 import astroid as _ast
@@ -32,12 +31,12 @@ class _Overloads(dict[str, "Function"]): ...
 class _Children(list[_t.Union["Parent", "Function"]]): ...
 
 
-class Error(_Enum):
-    """Represents an unrecoverable error."""
-
-    SYNTAX = 1
-    UNICODE = 2
-    RECURSION = 3
+ERRORS = (
+    _ast.AstroidSyntaxError,
+    UnicodeDecodeError,
+    RecursionError,
+    _ast.DuplicateBasesError,
+)
 
 
 class Parent:  # pylint: disable=too-many-instance-attributes
@@ -65,7 +64,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
         file: _Path | None = None,
         config: _Config | None = None,
         imports: _Imports | None = None,
-        error: Error | None = None,
+        error: type[BaseException] | None = None,
     ) -> None:
         super().__init__()
         self._error = error
@@ -127,14 +126,18 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                     if func.isoverloaded:
                         if (
                             func.name not in self._overloads
-                            or self._overloads[func.name].signature.rettype
+                            or self._overloads[
+                                func.name
+                            ].signature.returns.type
                             == _RetType.NONE
                         ):
                             self._overloads[func.name] = func
                     else:
                         if func.name in self._overloads:
                             func.overload(
-                                self._overloads[func.name].signature.rettype,
+                                self._overloads[
+                                    func.name
+                                ].signature.returns.type,
                             )
 
                         self._children.append(func)
@@ -157,7 +160,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
         return self._name.startswith("_")
 
     @property
-    def error(self) -> Error | None:
+    def error(self) -> type[BaseException] | None:
         """Unrecoverable error for this scope, if any."""
         return self._error
 
@@ -190,7 +193,7 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
         file: _Path | None = None,
         config: _Config | None = None,
         imports: _Imports | None = None,
-        error: Error | None = None,
+        error: type[BaseException] | None = None,
     ) -> None:
         super().__init__(
             node,

{docsig-0.82.1 → docsig-0.83.0}/docsig/_parsers.py

@@ -15,7 +15,7 @@ import astroid as _ast
 from ._config import Config as _Config
 from ._directives import Directives as _Directives
 from ._files import FILE_INFO as _FILE_INFO
-from ._module import Error as _Error
+from ._module import ERRORS as _ERRORS
 from ._module import Parent as _Parent
 
 
@@ -52,13 +52,14 @@ def parse_from_string(
             )
 
         parent = _Parent(node, directives, file, config)
-        logger.debug(_FILE_INFO, source_name, "Parsing Python code successful")
-    except _ast.AstroidSyntaxError as err:
-        logger.debug(_FILE_INFO, source_name, str(err).replace("\n", " "))
-        parent = _Parent(error=_Error.SYNTAX)
-    except RecursionError as err:
-        logger.debug(_FILE_INFO, source_name, str(err).replace("\n", " "))
-        parent = _Parent(error=_Error.RECURSION)
+        logger.debug(_FILE_INFO, source_name, "parsing python code successful")
+    except _ERRORS as err:
+        logger.debug(
+            _FILE_INFO,
+            source_name,
+            str(err).replace("\n", " ").lower(),
+        )
+        parent = _Parent(error=type(err))
 
     return parent
 
@@ -81,7 +82,7 @@ def parse_from_file(file: _Path, config: _Config) -> _Parent:
     except UnicodeDecodeError as err:
         logger = _logging.getLogger(__package__)
         logger.debug(_FILE_INFO, file, str(err).replace("\n", " "))
-        parent = _Parent(error=_Error.UNICODE)
+        parent = _Parent(error=type(err))
 
     if parent.error is not None and not file.name.endswith(".py"):
         parent = _Parent()

{docsig-0.82.1 → docsig-0.83.0}/docsig/_report.py

@@ -15,10 +15,9 @@ import sys as _sys
 import typing as _t
 from warnings import warn as _warn
 
-from astroid.nodes.scoped_nodes import scoped_nodes as _scoped_nodes
+import astroid as _ast
 
 from ._config import Config as _Config
-from ._module import Error as _Error
 from ._module import Function as _Function
 from ._stub import UNNAMED as _UNNAMED
 from ._stub import VALID_DESCRIPTION as _VALID_DESCRIPTION
@@ -75,7 +74,7 @@ class Failure(list[Failed]):
         if (
             self._func.parent is not None
             and self._func.parent.name
-            and not isinstance(self._func.parent, _scoped_nodes.Module)
+            and not isinstance(self._func.parent, _ast.nodes.Module)
         ):
             self._name = f"{self._func.parent.name}.{self._name}"
 
@@ -288,18 +287,18 @@ class Failure(list[Failed]):
             self._func.isproperty and not check_property_returns
         ):
             # no types, cannot know either way
-            if self._func.signature.rettype == _RetType.UNTYPED:
+            if self._func.signature.returns.type == _RetType.UNTYPED:
                 # confirm-return-needed
                 self._add(_E[501], hint=True)
             # return-type is none, so no return should be documented
-            elif self._func.docstring.returns:
-                if self._func.signature.rettype == _RetType.NONE:
+            elif self._func.docstring.returns.returns:
+                if self._func.signature.returns.type == _RetType.NONE:
                     # return-documented-for-none
                     self._add(_E[502])
-                if self._func.docstring.ret_description_missing:
+                if self._func.docstring.returns.description_missing:
                     self._add(_E[506])
             # return-type is some, so return should be documented
-            elif self._func.signature.returns:
+            elif self._func.signature.returns.returns:
                 # return-missing
                 lines = str(self._func.docstring.string).splitlines()
                 self._add(
@@ -310,7 +309,7 @@ class Failure(list[Failed]):
                         and ":param" not in lines[-1]
                     ),
                 )
-        elif self._func.docstring.returns:
+        elif self._func.docstring.returns.returns:
             # this method is init, so no return should be documented
             if self._func.isinit:
                 # class-return-documented
@@ -322,13 +321,15 @@ class Failure(list[Failed]):
 
     def _sig9xx_error(self) -> None:
         # invalid-syntax
-        if self._func.error == _Error.SYNTAX:
+        if self._func.error is _ast.AstroidSyntaxError:
             self._add(_E[901])
             self._retcode = 123
-        if self._func.error == _Error.UNICODE:
+        if self._func.error is UnicodeDecodeError:
             self._add(_E[902])
-        if self._func.error == _Error.RECURSION:
+        if self._func.error is RecursionError:
             self._add(_E[903])
+        if self._func.error is _ast.DuplicateBasesError:
+            self._add(_E[904])
 
     @property
     def name(self) -> str:

{docsig-0.82.1 → docsig-0.83.0}/docsig/_stub.py

@@ -9,6 +9,7 @@ from __future__ import annotations as _
 
 import re as _re
 import textwrap as _textwrap
+import typing as _t
 from collections import Counter as _Counter
 from enum import Enum as _Enum
 
@@ -80,8 +81,6 @@ class DocType(_Enum):
         return cls.UNKNOWN
 
 
-# todo: consider a parent object that can be used for returns that do
-# todo: not include the name attribute
 class Param:
     """Single parameter from a docstring or function signature.
 
@@ -152,6 +151,13 @@ class Param:
         return self._closing_token
 
 
+# single return from a docstring or function signature
+class _Return(_t.NamedTuple):
+    returns: bool = False
+    type: RetType = RetType.UNTYPED
+    description_missing: bool = False
+
+
 class Params(list[Param]):
     """A list-like collection of params.
 
@@ -218,9 +224,13 @@ class Params(list[Param]):
 
 
 class _Stub:
-    def __init__(self, ignore: _Ignore | None = None) -> None:
+    def __init__(
+        self,
+        returns: _Return | None = None,
+        ignore: _Ignore | None = None,
+    ) -> None:
         self._args = Params(ignore or _Ignore())
-        self._returns = False
+        self._returns = returns or _Return()
 
     @property
     def args(self) -> Params:
@@ -228,7 +238,7 @@ class _Stub:
         return self._args
 
     @property
-    def returns(self) -> bool:
+    def returns(self) -> _Return:
         """True if a return (or yield) is declared or documented."""
         return self._returns
 
@@ -236,20 +246,16 @@ class _Stub:
 class Signature(_Stub):
     """Parsed function signature (args and return type).
 
-    :param rettype: Kind of return (none, some, untyped).
     :param returns: True if return is declared in the signature.
     :param ignore: Configuration object for what to ignore.
     """
 
     def __init__(
         self,
-        rettype: RetType = RetType.NONE,
-        returns: bool = False,
+        returns: _Return | None = None,
         ignore: _Ignore | None = None,
     ) -> None:
-        super().__init__(ignore or _Ignore())
-        self._rettype = rettype
-        self._returns = returns
+        super().__init__(returns, ignore or _Ignore())
 
     @classmethod
     def from_ast(
@@ -264,8 +270,8 @@ class Signature(_Stub):
         :return: Signature with args and return type.
         """
         rettype = RetType.from_ast(node.returns)
-        returns = rettype == RetType.SOME
-        signature = cls(rettype, returns, ignore)
+        returns = _Return(rettype == RetType.SOME, rettype)
+        signature = cls(returns, ignore)
         # noinspection PyUnresolvedReferences
         for i in [
             a if isinstance(a, Param) else Param(name=a.name)
@@ -282,18 +288,12 @@ class Signature(_Stub):
 
         return signature
 
-    @property
-    def rettype(self) -> RetType:
-        """Return annotation kind (none, some, or untyped)."""
-        return self._rettype
-
     def overload(self, rettype: RetType) -> None:
         """Set this signature's return type (for overloads).
 
         :param rettype: Return type for the overloaded variant.
         """
-        self._rettype = rettype
-        self._returns = rettype != RetType.NONE
+        self._returns = _Return(rettype != RetType.NONE, rettype)
 
 
 class Docstring(_Stub):
@@ -301,7 +301,6 @@ class Docstring(_Stub):
 
     :param string: Raw docstring text after normalization.
     :param returns: True if a return or yield section is present.
-    :param ret_description_missing: True if return has no description.
     """
 
     @staticmethod
@@ -345,13 +344,10 @@ class Docstring(_Stub):
     def __init__(
         self,
         string: str | None = None,
-        returns: bool = False,
-        ret_description_missing: bool = False,
+        returns: _Return | None = None,
     ) -> None:
-        super().__init__()
+        super().__init__(returns)
         self._string = string
-        self._returns = returns
-        self._ret_description_missing = ret_description_missing
 
     @classmethod
     def from_ast(cls, node: _ast.Const) -> Docstring:
@@ -362,16 +358,16 @@ class Docstring(_Stub):
         """
         indent_anomaly = cls._indent_anomaly(node.value)
         string = cls._normalize_docstring(node.value)
-        # todo: we can start building return objects for more detailed
-        # todo: checks that are in common with the params class
         match = _re.search(
             r":(?:returns?|yields?):\s*(.*)",
             string,
             _re.IGNORECASE,
         )
-        returns = bool(match)
-        ret_description_missing = not match or not match.group(1)
-        docstring = cls(string, returns, ret_description_missing)
+        returns = _Return(
+            bool(match),
+            description_missing=not match or not match.group(1),
+        )
+        docstring = cls(string, returns)
         for match in _re.findall(
             r":([\w\s]+(?:\s\|\s[\w\s]+|\w+))([^\w\s])((?:.|\n)*?)(?=\n:|$)",
             string,
@@ -402,9 +398,8 @@ class Docstring(_Stub):
 
         Used when the function has a docstring but documents nothing.
         """
-        return self._string is not None and not self._args and not self.returns
-
-    @property
-    def ret_description_missing(self) -> bool:
-        """True if a return section exists but has no description."""
-        return self._ret_description_missing
+        return (
+            self._string is not None
+            and not self._args
+            and not self.returns.returns
+        )

{docsig-0.82.1 → docsig-0.83.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.82.1"
+__version__ = "0.83.0"

{docsig-0.82.1 → docsig-0.83.0}/docsig/messages.py

@@ -198,7 +198,7 @@ E = MessageMap(
         #: SIG4xx Parameters
         401: Message(
             "SIG401",
-            "param not indented correctly",
+            "parameter not indented correctly",
             "incorrect-indent",
         ),
         402: Message(
@@ -267,5 +267,10 @@ E = MessageMap(
             "maximum recursion depth exceeded",
             "recursion-error",
         ),
+        904: Message(
+            "SIG904",
+            "duplicates found in mros",
+            "duplicates-found-in-mros",
+        ),
     },
 )

docsig-0.83.0/docsig/plugin/__init__.py

@@ -0,0 +1,12 @@
+"""
+docsig.plugin
+=============
+"""
+
+from ._flake8 import Flake8
+from ._validate_pyproject import ValidatePyproject
+
+__all__ = [
+    "Flake8",
+    "ValidatePyproject",
+]

docsig-0.82.1/docsig/plugin.py → docsig-0.83.0/docsig/plugin/_flake8.py

@@ -1,32 +1,36 @@
 """
-docsig.plugin
-=============
+docsig.plugin._flake8
+=====================
 
 Flake8 plugin entry point that runs docsig checks and reports as flake8
 errors.
 """
 
-import ast
-import os
-import sys
-import typing as t
-from argparse import SUPPRESS, Namespace
-from pathlib import Path
-
-from ._config import Check as _Check
-from ._config import Config as _Config
-from ._config import Ignore as _Ignore
-from ._config import get_config as _get_config
-from ._config import merge_configs as _merge_configs
-from ._core import handle_deprecations, runner, setup_logger
-from ._version import __version__
-from .messages import FLAKE8, E
-
-Flake8Error = tuple[int, int, str, type[t.Any]]
-sys.path.append(os.path.abspath(os.getcwd()))
-
-
-class Docsig:
+import ast as _ast
+import os as _os
+import sys as _sys
+import typing as _t
+from argparse import SUPPRESS as _SUPPRESS
+from argparse import Namespace as _Namespace
+from pathlib import Path as _Path
+
+from .._config import Check as _Check
+from .._config import Config as _Config
+from .._config import Ignore as _Ignore
+from .._config import get_config as _get_config
+from .._config import merge_configs as _merge_configs
+from .._core import handle_deprecations as _handle_deprecations
+from .._core import runner as _runner
+from .._core import setup_logger as _setup_logger
+from .._version import __version__
+from ..messages import FLAKE8 as _FLAKE8
+from ..messages import E as _E
+
+_Flake8Error = tuple[int, int, str, type[_t.Any]]
+_sys.path.append(_os.path.abspath(_os.getcwd()))
+
+
+class Flake8:
     """Plugin that runs docsig on a file and yields flake8 errors.
 
     :param tree: Parsed AST module (unused; flake8 requires it for the
@@ -37,9 +41,9 @@ class Docsig:
     off_by_default = False
     name = __package__
     version = __version__
-    a = Namespace()
+    a = _Namespace()
 
-    def __init__(self, tree: ast.Module, filename: str) -> None:
+    def __init__(self, tree: _ast.Module, filename: str) -> None:
         _tree = tree  # noqa
         self.filename = filename
 
@@ -48,7 +52,7 @@ class Docsig:
     # might require that flake8 actually be installed, which is not a
     # requirement for this package
     @classmethod
-    def add_options(cls, parser: t.Any) -> None:
+    def add_options(cls, parser: _t.Any) -> None:
         """Register CLI and config opts with the flake8 option parser.
 
         :param parser: Flake8 option manager to extend.
@@ -132,18 +136,18 @@ class Docsig:
             "--sig-ignore-typechecker",
             action="store_true",
             parse_from_config=True,
-            help=SUPPRESS,
+            help=_SUPPRESS,
         )
 
     @classmethod
-    def parse_options(cls, a: Namespace) -> None:
+    def parse_options(cls, a: _Namespace) -> None:
         """Merge parsed options with pyproject config into class state.
 
         :param a: Argparse namespace from flake8.
         """
         if getattr(a, "sig_ignore_typechecker", False):
             a.extend_ignore = list(a.extend_ignore or [])
-            handle_deprecations(
+            _handle_deprecations(
                 getattr(a, "sig_ignore_typechecker", False),
                 a.extend_ignore,
                 ["SIG501", "SIG502", "SIG503", "SIG504", "SIG505", "SIG506"],
@@ -155,7 +159,7 @@ class Docsig:
             _get_config(__package__),
         )
 
-    def run(self) -> t.Generator[Flake8Error, None, None]:
+    def run(self) -> _t.Generator[_Flake8Error, None, None]:
         """Run docsig on the file and yield flake8 errors per failure.
 
         If both class and class-constructor checks are enabled,
@@ -167,15 +171,15 @@ class Docsig:
         """
         if self.a.check_class and self.a.check_class_constructor:
             line = "{msg}".format(
-                msg=FLAKE8.format(
-                    ref=E[5].ref,
-                    description=E[5].description,
-                    symbolic=E[5].symbolic,
+                msg=_FLAKE8.format(
+                    ref=_E[5].ref,
+                    description=_E[5].description,
+                    symbolic=_E[5].symbolic,
                 ),
             )
             yield 0, 0, line, self.__class__
         else:
-            setup_logger(self.a.verbose)
+            _setup_logger(self.a.verbose)
             check = _Check(
                 class_=self.a.check_class,
                 class_constructor=self.a.check_class_constructor,
@@ -196,14 +200,14 @@ class Docsig:
                 ignore=ignore,
                 verbose=self.a.verbose,
             )
-            results = runner(Path(self.filename), config)
+            results = _runner(_Path(self.filename), config)
             for result in results:
                 if not result.retcode:
                     continue
 
                 for info in result:
                     line = "{msg} '{name}'".format(
-                        msg=FLAKE8.format(
+                        msg=_FLAKE8.format(
                             ref=info.ref,
                             description=info.description,
                             symbolic=info.symbolic,

docsig-0.83.0/docsig/plugin/_validate_pyproject.py

@@ -0,0 +1,103 @@
+"""
+docsig.plugin._validate_pyproject
+=================================
+"""
+
+# pylint: disable=protected-access
+
+import typing as _t
+
+# noinspection PyFinal
+from argparse import SUPPRESS as _SUPPRESS
+from argparse import Action as _Action
+
+import docsig as _docsig
+
+from .._config import build_parser as _build_parser
+
+_ID = "https://docsig.io/en/latest/usage/configuration/schema.json"
+_SCHEMA = "http://json-schema.org/draft-07/schema#"
+_DESCRIPTION_EXCLUDE = ("comma separated ",)
+_NARGS = ("+", "*")
+_EXCLUDED_OPTIONS = ("help", "list-checks", "string", "version")
+
+
+class ValidatePyproject(dict[str, _t.Any]):
+    """Schema for the docsig tool section in pyproject.toml.
+
+    :param tool_name: The tool name to validate.
+    """
+
+    def __init__(self, tool_name: str = "docsig") -> None:
+        assert tool_name == "docsig", "Only docsig is supported."
+        self._parser = _build_parser()
+        super().__init__(
+            {
+                "$comment": _CMT,
+                "$id": _ID,
+                "$schema": _SCHEMA,
+                "type": "object",
+                "additionalProperties": False,
+            },
+        )
+        self._get_properties()
+        self._get_mutually_exclusive_options()
+
+    @staticmethod
+    def _skip_action(action: _Action, name: str) -> bool:
+        if not action.option_strings:
+            return True
+
+        if action.help == _SUPPRESS:
+            return True
+
+        if name in _EXCLUDED_OPTIONS:
+            return True
+
+        return False
+
+    def _get_properties(self) -> None:
+        self["properties"] = {}
+        for action in self._parser._actions:
+            name = action.dest.replace("_", "-")
+            if self._skip_action(action, name):
+                continue
+
+            self["properties"][name] = {"default": action.default}
+            if isinstance(action.default, bool):
+                self["properties"][name]["type"] = "boolean"
+            elif isinstance(action.default, list) or action.nargs in _NARGS:
+                self["properties"][name]["type"] = "array"
+                self["properties"][name]["items"] = {"type": "string"}
+            elif action.type is None:
+                self["properties"][name]["type"] = "string"
+
+            if action.help:
+                description = action.help
+                for exclude in _DESCRIPTION_EXCLUDE:
+                    description = description.replace(exclude, "")
+
+                self["properties"][name]["description"] = description
+
+    def _get_mutually_exclusive_options(self) -> None:
+        for group in self._parser._mutually_exclusive_groups:
+            names = []
+            for action in group._group_actions:
+                name = action.dest.replace("_", "-")
+                if self._skip_action(action, name):
+                    continue
+
+                names.append(name)
+
+            if len(names) > 1:
+                if "allOf" not in self:
+                    self["allOf"] = []
+
+                self["allOf"].append({"not": {"required": names}})
+
+
+_CMT = ValidatePyproject.__doc__.splitlines()[0].lower()[:-1]  # type: ignore
+
+# for
+# $ validate-pyproject --help
+ValidatePyproject.__doc__ = _docsig.__doc__

{docsig-0.82.1 → docsig-0.83.0}/pyproject.toml

@@ -11,7 +11,7 @@ line-length = 79
 allow_dirty = true
 commit = true
 commit_args = "-sS"
-current_version = "0.82.1"
+current_version = "0.83.0"
 message = "bump: version {current_version} → {new_version}"
 sign_tags = true
 tag = true
@@ -103,7 +103,7 @@ non_interactive = true
 
 [tool.poetry]
 authors = [
-  "jshwi <stephen@jshwisolutions.com>"
+  "jshwi <s.whitlock@live.com>"
 ]
 description = "Check signature params for proper documentation"
 documentation = "https://docsig.io/en/latest"
@@ -117,12 +117,12 @@ keywords = [
 ]
 license = "MIT"
 maintainers = [
-  "jshwi <stephen@jshwisolutions.com>"
+  "jshwi <s.whitlock@live.com>"
 ]
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.82.1"
+version = "0.83.0"
 
 [tool.poetry.dependencies]
 Sphinx = ">=7,<9"
@@ -146,15 +146,17 @@ tomli = "^2.0.1"
 tomli-w = "^1.0.0"
 towncrier = ">=23.11,<26.0"
 tox = "^4.15.0"
+validate-pyproject = {extras = ["all", "store"], version = "^0.25"}
 vulture = "^2.11"
 
 [tool.poetry.group.docs.dependencies]
 furo = ">=2024.4.27,<2026.0.0"
 myst-parser = ">=3.0.1,<5.0.0"
-pytest = "8.3.5"
+pytest = "9.0.3"
 pyyaml = "^6.0.1"
 roman-numerals = "4.1.0"
 sphinx-copybutton = "^0.5.2"
+sphinx-jsonschema = "^1.19.2"
 sphinx-markdown-builder = ">=0.5.5,<0.7.0"
 sphinx-sitemap = "^2.9.0"
 templatest = ">=0.10.1,<0.13.0"
@@ -163,7 +165,7 @@ templatest = ">=0.10.1,<0.13.0"
 flake8 = "^7.1.0"
 
 [tool.poetry.group.tests.dependencies]
-pytest = "^8.2.0"
+pytest = ">=8.2,<10.0"
 pytest-benchmark = ">=4,<6"
 pytest-cov = ">=5,<8"
 pytest-gitignore = "^1.3"
@@ -173,7 +175,10 @@ pytest-xdist = "^3.6.1"
 templatest = ">=0.10.1,<0.13.0"
 
 [tool.poetry.plugins."flake8.extension"]
-SIG = "docsig.plugin:Docsig"
+SIG = "docsig.plugin:Flake8"
+
+[tool.poetry.plugins."validate_pyproject.tool_schema"]
+docsig = "docsig.plugin:ValidatePyproject"
 
 [tool.poetry.scripts]
 docsig = "docsig.__main__:main"
@@ -225,6 +230,9 @@ name = "Changed"
 [tool.towncrier.fragment.deprecate]
 name = "Deprecated"
 
+[tool.towncrier.fragment.feat]
+name = "Feature"
+
 [tool.towncrier.fragment.fix]
 name = "Fixed"
 
@@ -239,7 +247,7 @@ name = "Security"
 
 [tool.vulture]
 exclude = [
-  "tests/_templates.py",
+  "tests/base_test.py",
   "tests/conftest.py"
 ]
 make_whitelist = true