docsig 0.82.2__tar.gz → 0.83.0__tar.gz

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

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.82.2
+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.2, 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.2
+        rev: v0.83.0
         hooks:
           - id: docsig
             args:
@@ -289,7 +300,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.82.2
+              - docsig==0.83.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.82.2 → 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.2, 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.2
+        rev: v0.83.0
         hooks:
           - id: docsig
             args:
@@ -260,7 +271,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.82.2
+              - docsig==0.83.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.82.2 → 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.2 → 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.2 → docsig-0.83.0}/docsig/_parsers.py

@@ -52,9 +52,13 @@ def parse_from_string(
             )
 
         parent = _Parent(node, directives, file, config)
-        logger.debug(_FILE_INFO, source_name, "Parsing Python code successful")
+        logger.debug(_FILE_INFO, source_name, "parsing python code successful")
     except _ERRORS as err:
-        logger.debug(_FILE_INFO, source_name, str(err).replace("\n", " "))
+        logger.debug(
+            _FILE_INFO,
+            source_name,
+            str(err).replace("\n", " ").lower(),
+        )
         parent = _Parent(error=type(err))
 
     return parent

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

@@ -16,7 +16,6 @@ import typing as _t
 from warnings import warn as _warn
 
 import astroid as _ast
-from astroid.nodes.scoped_nodes import scoped_nodes as _scoped_nodes
 
 from ._config import Config as _Config
 from ._module import Function as _Function
@@ -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}"
 

{docsig-0.82.2 → 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.2"
+__version__ = "0.83.0"

{docsig-0.82.2 → 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(

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.2/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.2 → 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.2"
+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.2"
+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"