docsig 0.86.0__tar.gz → 0.87.0__tar.gz

{docsig-0.86.0 → docsig-0.87.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.86.0
+Version: 0.87.0
 Summary: Check signature params for proper documentation
 License: MIT
 License-File: LICENSE
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: Sphinx (>=7,<9)
+Requires-Dist: Sphinx (>=7,<8.2)
 Requires-Dist: astroid (>=4.0.2,<5.0.0)
 Requires-Dist: pathspec (>=0.12.1,<1.2.0)
 Requires-Dist: tomli (>=2.0.1,<3.0.0)
@@ -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|
+|License| |PyPI| |Jetbrains Plugin| |CI| |Jetbrains Build| |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,6 +74,12 @@ 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
+.. |Jetbrains Plugin| image:: https://img.shields.io/jetbrains/plugin/v/32129.svg
+   :target: https://plugins.jetbrains.com/plugin/32129
+   :alt: Jetbrains Plugin
+.. |Jetbrains Build| image:: https://github.com/jshwi/docsig/actions/workflows/build-intellij-plugin.yaml/badge.svg
+   :target: https://github.com/jshwi/docsig/actions/workflows/build-intellij-plugin.yaml
+   :alt: Build
 
 Check Python signature params for proper documentation
 -------------------------------------------------------
@@ -87,7 +93,7 @@ Maintain accurate and up-to-date Python documentation by automatically checking
 that all parameters in function signatures match their docstring documentation.
 Use docsig as a standalone tool, integrate it with ``flake8``, or add it as a
 ``pre-commit`` hook to catch documentation issues before they reach your
-repository.
+repository. **docsig** is also available as a ``PyCharm`` plugin
 
 Contributing
 ------------
@@ -195,7 +201,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.86.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.87.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
 
@@ -281,7 +287,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.86.0
+        rev: v0.87.0
         hooks:
           - id: docsig
             args:
@@ -300,7 +306,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.86.0
+              - docsig==0.87.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.86.0 → docsig-0.87.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|
+|License| |PyPI| |Jetbrains Plugin| |CI| |Jetbrains Build| |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,6 +45,12 @@
 .. |Security Status| image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security Status
+.. |Jetbrains Plugin| image:: https://img.shields.io/jetbrains/plugin/v/32129.svg
+   :target: https://plugins.jetbrains.com/plugin/32129
+   :alt: Jetbrains Plugin
+.. |Jetbrains Build| image:: https://github.com/jshwi/docsig/actions/workflows/build-intellij-plugin.yaml/badge.svg
+   :target: https://github.com/jshwi/docsig/actions/workflows/build-intellij-plugin.yaml
+   :alt: Build
 
 Check Python signature params for proper documentation
 -------------------------------------------------------
@@ -58,7 +64,7 @@ Maintain accurate and up-to-date Python documentation by automatically checking
 that all parameters in function signatures match their docstring documentation.
 Use docsig as a standalone tool, integrate it with ``flake8``, or add it as a
 ``pre-commit`` hook to catch documentation issues before they reach your
-repository.
+repository. **docsig** is also available as a ``PyCharm`` plugin
 
 Contributing
 ------------
@@ -166,7 +172,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.86.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.87.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
 
@@ -252,7 +258,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.86.0
+        rev: v0.87.0
         hooks:
           - id: docsig
             args:
@@ -271,7 +277,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.86.0
+              - docsig==0.87.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.86.0 → docsig-0.87.0}/docsig/_config.py

@@ -6,7 +6,6 @@ Config dataclasses, pyproject.toml loader, and commandline.
 """
 
 import argparse as _argparse
-import os as _os
 import re as _re
 import typing as _t
 from dataclasses import dataclass as _dataclass
@@ -15,6 +14,7 @@ from pathlib import Path as _Path
 
 import tomli as _tomli
 
+from ._utils import get_parent_that_has as _get_parent_that_has
 from ._version import __version__
 from .messages import Messages as _Messages
 
@@ -26,31 +26,18 @@ def _split_comma(value: str) -> list[str]:
     return [i.replace("\\,", ",") for i in _re.split(r"(?<!\\),", value)]
 
 
-# attempt to locate a pyproject.toml file if one exists in parents
-def _find_pyproject_toml(path: _Path | None = None) -> _Path | None:
-    if not path:
-        path = _Path.cwd()
-
-    pyproject_toml = path / PYPROJECT_TOML
-    if pyproject_toml.is_file():
-        return pyproject_toml
-
-    if str(path) == _os.path.abspath(_os.sep):
-        return None
-
-    return _find_pyproject_toml(path.parent)
-
-
 def get_config(prog: str) -> dict[str, _t.Any]:
     """Return the program's tool-section config from pyproject.toml.
 
     :param prog: Program name.
     :return: Config dict, or empty dict if no config is found.
     """
-    pyproject_file = _find_pyproject_toml()
+    # attempt to locate a pyproject.toml file if one exists in parents
+    pyproject_file = _get_parent_that_has(PYPROJECT_TOML)
     if pyproject_file is None:
         return {}
 
+    pyproject_file /= PYPROJECT_TOML
     return {
         k.replace("-", "_"): v
         for k, v in _tomli.loads(pyproject_file.read_text())
@@ -220,17 +207,10 @@ def build_parser() -> _ArgumentParser:
         action="store_true",
         help="ignore kwargs prefixed with two asterisks",
     )
-    parser.add_argument(
-        "-i",
-        action="store_true",
-        help=_argparse.SUPPRESS,
-        dest="ignore_no_params",
-    )
     parser.add_argument(
         "--ignore-no-params",
         action="store_true",
         help="ignore docstrings where parameters are not documented",
-        dest="ignore_no_params",
     )
     parser.add_argument(
         "--ignore-typechecker",
@@ -336,6 +316,23 @@ class Ignore:
     kwargs: bool = False
 
 
+@_dataclass
+# pylint: disable-next=too-few-public-methods
+class Filters:
+    """Configuration for which paths to filter.
+
+    :param exclude: Regular expression of files and dirs to exclude from
+        checks.
+    :param excludes: Files or dirs to exclude from checks.
+    :param include_ignored: Check files even if they match a gitignore
+        pattern.
+    """
+
+    exclude: list[str] = _field(default_factory=list)
+    excludes: list[str] = _field(default_factory=list)
+    include_ignored: bool = False
+
+
 @_dataclass(frozen=True)
 # pylint: disable-next=too-many-instance-attributes,too-few-public-methods
 class Config:
@@ -347,11 +344,9 @@ class Config:
 
     check: Check = _field(default_factory=Check)
     ignore: Ignore = _field(default_factory=Ignore)
+    filters: Filters = _field(default_factory=Filters)
     target: _Messages = _field(default_factory=_Messages)
     disable: _Messages = _field(default_factory=_Messages)
-    exclude: list[str] = _field(default_factory=list)
-    excludes: list[str] = _field(default_factory=list)
     list_checks: bool = False
-    include_ignored: bool = False
     no_ansi: bool = False
     verbose: bool = False

{docsig-0.86.0 → docsig-0.87.0}/docsig/_core.py

@@ -15,12 +15,14 @@ from . import _decorators
 from ._check import run_checks as _run_checks
 from ._config import Check as _Check
 from ._config import Config as _Config
+from ._config import Filters as _Filters
 from ._config import Ignore as _Ignore
 from ._files import Files as _Files
 from ._parsers import parse_from_file as _parse_from_file
 from ._parsers import parse_from_string as _parse_from_string
 from ._report import Failures as _Failures
 from ._report import report as _report
+from ._utils import get_parent_that_has as _get_parent_that_has
 from ._utils import print_checks as _print_checks
 from .messages import E as _E
 from .messages import Messages as _Messages
@@ -191,22 +193,26 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         args=ignore_args,
         kwargs=ignore_kwargs,
     )
+    filters = _Filters(
+        include_ignored=include_ignored,
+        exclude=exclude_,
+        excludes=excludes or [],
+    )
     config = _Config(
         list_checks=list_checks,
-        include_ignored=include_ignored,
         check=check,
         ignore=ignore,
+        filters=filters,
         no_ansi=no_ansi,
         verbose=verbose,
         target=target or _Messages(),
         disable=disable,
-        exclude=exclude_,
-        excludes=excludes or [],
     )
     setup_logger(config.verbose)
     logger = _logging.getLogger(__package__)
     logger.debug(_pformat(config))
     if config.list_checks:
+        # noinspection PyNoneFunctionAssignment
         return int(bool(_print_checks()))  # type: ignore
 
     if string:
@@ -215,7 +221,8 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         return _report(failures, config)
 
     retcodes = [0]
-    files = _Files(path, config)
+    repo = _get_parent_that_has(".git/HEAD")
+    files = _Files(path, config.filters, repo)
     for file in files:
         failures = runner(file, config)
         retcode = _report(failures, config, str(file))

{docsig-0.86.0 → docsig-0.87.0}/docsig/_decorators.py

@@ -4,6 +4,8 @@ docsig._decorators
 """
 
 import functools as _functools
+import json as _json
+import os as _os
 import sys as _sys
 import typing as _t
 from pathlib import Path as _Path
@@ -11,7 +13,7 @@ from pathlib import Path as _Path
 from .messages import E as _E
 
 _FuncType = _t.Callable[..., int]
-_WrappedFuncType = _t.Callable[..., str | int]
+_WrappedFuncType = _t.Callable[..., int]
 
 
 def parse_msgs(func: _WrappedFuncType) -> _WrappedFuncType:
@@ -25,7 +27,7 @@ def parse_msgs(func: _WrappedFuncType) -> _WrappedFuncType:
     """
 
     @_functools.wraps(func)
-    def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> str | int:
+    def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> int:
         disable = _E.from_codes(kwargs.get("disable", [])) or None
         target = _E.from_codes(kwargs.get("target", [])) or None
         kwargs["disable"] = disable
@@ -35,6 +37,7 @@ def parse_msgs(func: _WrappedFuncType) -> _WrappedFuncType:
     return _wrapper
 
 
+# TODO: make report json by default and wrap with a reporter for cli
 def validate_args(func: _FuncType) -> _WrappedFuncType:
     """Validate arguments before calling the wrapped function.
 
@@ -50,30 +53,32 @@ def validate_args(func: _FuncType) -> _WrappedFuncType:
     """
 
     @_functools.wraps(func)
-    def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> str | int:
-        stderr = []
+    def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> int:
+        format_json = _os.getenv("_DOCSIG_FORMAT_JSON") is not None
+        retcode = 2
+        errors = []
         if not kwargs.get("list_checks", False):
             if not args and not kwargs.get("string"):
-                stderr.append(
+                errors.append(
                     "the following arguments are required: path(s) or string",
                 )
 
             for message in kwargs.get("disable") or []:
                 if not message.isknown:
-                    stderr.append(
+                    errors.append(
                         f"unknown option to disable '{message.description}'",
                     )
 
             for message in kwargs.get("target") or []:
                 if not message.isknown:
-                    stderr.append(
+                    errors.append(
                         f"unknown option to target '{message.description}'",
                     )
 
             if kwargs.get("check_class") and kwargs.get(
                 "check_class_constructor",
             ):
-                stderr.append(
+                errors.append(
                     "argument to check class constructor not allowed with"
                     " argument to check class",
                 )
@@ -84,10 +89,23 @@ def validate_args(func: _FuncType) -> _WrappedFuncType:
                     # passing both commandline args as argparse won't
                     # allow it, therefore, this must be an issue with
                     # the pyproject.toml configuration
-                    stderr.append(
+                    errors.append(
                         "please check your pyproject.toml configuration",
                     )
+        if errors:
+            message = "\n".join(errors)
+            if format_json:
+                obj = [  # pragma: no cover
+                    {"line": None, "message": message, "exit": retcode},
+                ]
+                if format_json:  # pragma: no cover
+                    print(_json.dumps(obj).strip())  # pragma: no cover
 
-        return "\n".join(stderr) if stderr else func(*args, **kwargs)
+            else:
+                print(message, file=_sys.stderr)
+
+            return retcode
+
+        return func(*args, **kwargs)
 
     return _wrapper

{docsig-0.86.0 → docsig-0.87.0}/docsig/_files.py

@@ -14,24 +14,14 @@ from pathspec import PathSpec as _PathSpec
 from pathspec.patterns import GitWildMatchPattern as _GitWildMatchPattern
 from wcmatch.pathlib import Path as _WcPath
 
-from ._config import Config as _Config
+from ._config import Filters as _Filters
 
 FILE_INFO = "%s: %s"
 
 
 class _Gitignore(_PathSpec):
-    def _get_repo_relative_to(self, path: _Path) -> _Path | None:
-        if (path / ".git" / "HEAD").is_file():
-            return path
-
-        if str(path) == _os.path.abspath(_os.sep):
-            return None
-
-        return self._get_repo_relative_to(path.parent)
-
-    def __init__(self) -> None:
+    def __init__(self, repo: _Path | None = None) -> None:
         patterns = []
-        repo = self._get_repo_relative_to(_Path.cwd())
         # only consider gitignore patterns valid if inside a git repo
         # there might be stray gitignore files lying about
         if repo is not None:
@@ -72,25 +62,27 @@ class Files(list[_Path]):
     """Collect paths to check (gitignore and exclude applied).
 
     :param paths: Path(s) to collect (files or directories).
-    :param config: Configuration object.
+    :param filters: Filters object.
+    :param repo: Path to the repo root.
     """
 
     def __init__(
         self,
         paths: tuple[str | _Path, ...],
-        config: _Config,
+        filters: _Filters,
+        repo: _Path | None = None,
     ) -> None:
         super().__init__()
-        self._include_ignored = config.include_ignored
-        self._gitignore = _Gitignore()
+        self._include_ignored = filters.include_ignored
+        self._gitignore = _Gitignore(repo)
         logger = _logging.getLogger(__package__)
         for path in paths:
             self._populate(_Path(path))
 
         for path in list(self):
             if str(path) != "." and (
-                any(_re.match(i, str(path)) for i in config.exclude)
-                or any(_glob(path, i) for i in config.excludes)
+                any(_re.match(i, str(path)) for i in filters.exclude)
+                or any(_glob(path, i) for i in filters.excludes)
             ):
                 logger.debug(FILE_INFO, path, "in exclude list, skipping")
                 self.remove(path)

{docsig-0.86.0 → docsig-0.87.0}/docsig/_main.py

@@ -5,6 +5,7 @@ docsig._main
 CLI entry point that parses args and runs docsig.
 """
 
+import os as _os
 import sys as _sys
 import warnings as _warnings
 
@@ -20,7 +21,6 @@ def _warn_on_deprecated_short_flags() -> None:
         "-o": "--check-overridden",
         "-p": "--check-protected",
         "-P": "--check-property-returns",
-        "-i": "--ignore-no-params",
     }
     raw_args = _sys.argv[1:]
     expanded_flags = []
@@ -47,6 +47,9 @@ def main() -> str | int:
 
     :return: Exit code (non-zero if any check failed).
     """
+    if _os.getenv("_DOCSIG_FORMAT_JSON"):
+        _warnings.simplefilter("ignore", FutureWarning)  # pragma: no cover
+
     _warn_on_deprecated_short_flags()
     a = _parse_args()
     _excepthook(a.no_ansi)

{docsig-0.86.0 → docsig-0.87.0}/docsig/_module.py

@@ -57,7 +57,6 @@ class Parent:  # pylint: disable=too-many-instance-attributes
             _ast.nodes.Module
             | _ast.nodes.ClassDef
             | _ast.nodes.FunctionDef
-            | _ast.nodes.NodeNG
             | None
         ) = None,
         directives: _Directives | None = None,
@@ -82,7 +81,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                 # later inspected to report on the module error (the
                 # report doesn't analyze modules or classes - it
                 # analyzes functions)
-                self._children.append(Function(file, error=error))
+                self._children.append(Function(error=error))
         else:
             self._name = node.name
             self._parse_ast(node, file)
@@ -101,13 +100,13 @@ class Parent:  # pylint: disable=too-many-instance-attributes
         # resolved in the directive object, they are needed to notify
         # the user in the case that they are invalid
         parent_comments, parent_disabled = self._directives.get(
-            node.lineno,
+            node.lineno or 0,
             (_Comments(), _Messages()),
         )
         if hasattr(node, "body"):
             for subnode in node.body:
                 comments, disabled = self._directives.get(
-                    subnode.lineno,
+                    subnode.lineno or 0,
                     (_Comments(), _Messages()),
                 )
                 comments.extend(parent_comments)
@@ -119,7 +118,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                     for name in subnode.names:
                         original, alias = name
                         self._imports[original] = alias or original
-                elif isinstance(subnode, _ast.FunctionDef):
+                elif isinstance(subnode, _ast.nodes.FunctionDef):
                     func = Function(
                         subnode,
                         comments,
@@ -147,7 +146,7 @@ class Parent:  # pylint: disable=too-many-instance-attributes
                             )
 
                         self._children.append(func)
-                elif isinstance(subnode, _ast.ClassDef):
+                elif isinstance(subnode, _ast.nodes.ClassDef):
                     self._children.append(
                         Parent(
                             subnode,
@@ -192,7 +191,7 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
     # pylint: disable-next=too-many-arguments,too-many-positional-arguments
     def __init__(
         self,
-        node: _ast.nodes.FunctionDef | _ast.nodes.NodeNG | None = None,
+        node: _ast.nodes.FunctionDef | None = None,
         comments: _Comments | None = None,
         directives: _Directives | None = None,
         messages: _Messages | None = None,
@@ -216,7 +215,7 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
         self._docstring = _Docstring()
         self._lineno = 0
         self._error = error
-        if node is not None:
+        if node is not None and node.parent is not None:
             self._parent = node.parent.frame()
             self._decorators = node.decorators
             self._lineno = node.lineno
@@ -230,7 +229,11 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
                 node,
                 self._config.ignore,
             )
-            if self.isinit and not self._config.check.class_constructor:
+            if (
+                self.isinit
+                and not self._config.check.class_constructor
+                and not isinstance(self._parent, _ast.nodes.Lambda)
+            ):
                 # docstring for __init__ is expected on the class
                 # docstring
                 relevant_doc_node = self._parent.doc_node
@@ -259,7 +262,7 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
     @property
     def ismethod(self) -> bool:
         """Whether this function is defined in a class (method)."""
-        return isinstance(self._parent, _ast.ClassDef)
+        return isinstance(self._parent, _ast.nodes.ClassDef)
 
     @property
     def isproperty(self) -> bool:
@@ -282,11 +285,16 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
     @property
     def isoverridden(self) -> bool:
         """Whether this function overrides a base class method."""
-        if self.ismethod and not self.isinit and self._parent is not None:
+        if (
+            self.ismethod
+            and not self.isinit
+            and self._parent is not None
+            and isinstance(self._parent, _ast.nodes.ClassDef)
+        ):
             for ancestor in self._parent.ancestors():
                 if self.name in ancestor and isinstance(
                     ancestor[self.name],
-                    _ast.FunctionDef,
+                    _ast.nodes.FunctionDef,
                 ):
                     return True
 
@@ -324,6 +332,7 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
         | _ast.nodes.Module
         | _ast.nodes.ClassDef
         | _ast.nodes.Lambda
+        | None
     ):
         """Function's parent node."""
         return self._parent
@@ -331,7 +340,7 @@ class Function(Parent):  # pylint: disable=too-many-instance-attributes
     @property
     def lineno(self) -> int:
         """Line number of function declaration."""
-        return self._lineno
+        return self._lineno or 0
 
     @property
     def signature(self) -> _Signature:

{docsig-0.86.0 → docsig-0.87.0}/docsig/_report.py

@@ -9,6 +9,8 @@ return the highest exit code.
 """
 
 import contextlib as _contextlib
+import json as _json
+import os as _os
 import sys as _sys
 import typing as _t
 from warnings import warn as _warn
@@ -71,12 +73,14 @@ class Failure(list[Failed]):
         self._name = self._func.name
         if (
             self._func.parent is not None
+            and hasattr(self._func.parent, "name")
             and self._func.parent.name
             and not isinstance(self._func.parent, _ast.nodes.Module)
         ):
             self._name = f"{self._func.parent.name}.{self._name}"
 
         if self._func.error is not None:
+            self._retcode.append(2)
             self._sig9xx_error()
         else:
             self._sig0xx_config()
@@ -97,7 +101,7 @@ class Failure(list[Failed]):
     def _add(
         self,
         value: _Message,
-        hint: bool = False,
+        include_hint: bool = False,
         **kwargs: _t.Any,
     ) -> None:
         self._retcode.append(int(not value.new))
@@ -107,7 +111,7 @@ class Failure(list[Failed]):
             value.description.format(**kwargs),
             value.symbolic,
             self.lineno,
-            value.hint if hint else None,
+            value.hint if include_hint else None,
             value.new,
         )
         if value not in self._func.messages and failed not in self:
@@ -223,9 +227,15 @@ class Failure(list[Failed]):
             self._add(_E[203])
 
     def _sig3xx_description(self, doc: _Param) -> None:
-        if doc.description is None and doc.name is not None:
+        # freeze result as it is a property and PyCharm complains
+        # `Member 'None' of 'str | None' does not have attribute
+        # 'startswith'` as property could theoretically have different
+        # result from doc.description is None to
+        # doc.description.startswith
+        doc_description = doc.description
+        if doc_description is None and doc.name is not None:
             self._add(_E[301])
-        elif doc.description is not None and not doc.description.startswith(
+        elif doc_description is not None and not doc_description.startswith(
             " ",
         ):
             # syntax-error-in-description
@@ -237,19 +247,19 @@ class Failure(list[Failed]):
             self._add(_E[303])
         elif doc.closing_token != ":":
             # bad-closing-token
-            self._add(_E[304], token=doc.closing_token, hint=True)
-        if doc.description is not None and not all(
+            self._add(_E[304], token=doc.closing_token, include_hint=True)
+        if doc_description is not None and not all(
             stripped[0].isupper()
-            for i in _sentence_tokenizer(doc.description)
+            for i in _sentence_tokenizer(doc_description)
             if i and (stripped := i.strip())[0].isalpha()
         ):
             # description is not capitalized
             self._add(_E[305])
         # description-missing-period
         if (
-            doc.description
-            and doc.description.strip()
-            and doc.description.strip()[-1]
+            doc_description
+            and doc_description.strip()
+            and doc_description.strip()[-1]
             not in (
                 "`",
                 ".",
@@ -258,22 +268,28 @@ class Failure(list[Failed]):
             self._add(_E[306])
 
     def _sig4xx_parameters(self, doc: _Param, sig: _Param) -> None:
+        # freeze result as it is a property and PyCharm complains
+        # `Expected type 'str', got 'str | None' instead ' in
+        # _almost_equal as property could theoretically have different
+        # result from sig.name is not None and doc.name is not None
+        sig_name = sig.name
+        doc_name = doc.name
         if doc.indent > 0:
             # incorrect-indent
             self._add(_E[401])
         elif doc != sig:
             if (
-                sig.name in self._func.docstring.args.names
-                or doc.name in self._func.signature.args.names
+                sig_name in self._func.docstring.args.names
+                or doc_name in self._func.signature.args.names
             ) and len(self._func.docstring.args) > 1:
                 # params-out-of-order
                 self._add(_E[402])
             elif (
-                doc.name != _UNNAMED
-                and sig.name is not None
-                and doc.name is not None
+                doc_name != _UNNAMED
+                and sig_name is not None
+                and doc_name is not None
             ):
-                if _almost_equal(sig.name, doc.name, _MIN_MATCH, _MAX_MATCH):
+                if _almost_equal(sig_name, doc_name, _MIN_MATCH, _MAX_MATCH):
                     # spelling-error
                     self._add(_E[403])
                 else:
@@ -287,7 +303,7 @@ class Failure(list[Failed]):
             # no types, cannot know either way
             if self._func.signature.returns.type == _RetType.UNTYPED:
                 # confirm-return-needed
-                self._add(_E[501], hint=True)
+                self._add(_E[501], include_hint=True)
             # return-type is none, so no return should be documented
             elif self._func.docstring.returns.returns:
                 if self._func.signature.returns.type == _RetType.NONE:
@@ -301,7 +317,7 @@ class Failure(list[Failed]):
                 lines = str(self._func.docstring.string).splitlines()
                 self._add(
                     _E[503],
-                    hint=(
+                    include_hint=(
                         len(lines) > 1
                         and "return" in lines[-1]
                         and ":param" not in lines[-1]
@@ -311,11 +327,11 @@ class Failure(list[Failed]):
             # this method is init, so no return should be documented
             if self._func.isinit:
                 # class-return-documented
-                self._add(_E[504], hint=True)
+                self._add(_E[504], include_hint=True)
             # method is property and not set to document property
             elif self._func.isproperty and not check_property_returns:
                 # return-documented-for-property
-                self._add(_E[505], hint=True)
+                self._add(_E[505], include_hint=True)
 
     def _sig9xx_error(self) -> None:
         # invalid-syntax
@@ -348,6 +364,7 @@ class Failure(list[Failed]):
         return max(self._retcode)
 
 
+# TODO: make report json by default and wrap with a reporter for cli
 def report(
     failures: Failures,
     config: _Config,
@@ -363,7 +380,10 @@ def report(
     :param file: Module path when failures came from a file (optional).
     :return: Exit code (non-zero if any check failed).
     """
+    format_json = _os.getenv("_DOCSIG_FORMAT_JSON") is not None
     retcodes = [0]
+    output = []
+    obj = []
     for failure in failures:
         retcodes.append(failure.retcode)
         path_prefix = f"{file}:" if file is not None else ""
@@ -371,7 +391,7 @@ def report(
         if not config.no_ansi and _sys.stdout.isatty():
             header = f"\033[35m{header}\033[0m"
 
-        print(header)
+        output.append(header)
         for item in failure:
             extra = None
             if item.hint:
@@ -381,15 +401,27 @@ def report(
                 extra = "warning: please remember to fix this or disable it"
                 _warn(_NEW.format(ref=item.ref), FutureWarning, stacklevel=3)
 
-            print(
-                "    "
-                + _TEMPLATE.format(
-                    ref=item.ref,
-                    description=item.description,
-                    symbolic=item.symbolic,
-                ),
+            msg = _TEMPLATE.format(
+                ref=item.ref,
+                description=item.description,
+                symbolic=item.symbolic,
             )
+            output.append(f"    {msg}")
             if extra is not None:
-                print(f"    {extra}")
+                output.append(f"    {extra}")
+
+            obj.append(
+                {
+                    "line": None if failure.retcode == 2 else item.lineno,
+                    "message": msg,
+                    "exit": failure.retcode,
+                },
+            )
+
+    if format_json:
+        print(_json.dumps(obj).strip())  # pragma: no cover
+
+    elif output:
+        print("\n".join(output))
 
     return max(retcodes)

{docsig-0.86.0 → docsig-0.87.0}/docsig/_stub.py

@@ -260,7 +260,7 @@ class Signature(_Stub):
     @classmethod
     def from_ast(
         cls,
-        node: _ast.nodes.Module | _ast.nodes.ClassDef | _ast.nodes.FunctionDef,
+        node: _ast.nodes.FunctionDef,
         ignore: _Ignore,
     ) -> Signature:
         """Build Signature from a function or class AST node.
@@ -368,6 +368,8 @@ class Docstring(_Stub):
             description_missing=not match or not match.group(1),
         )
         docstring = cls(string, returns)
+        # the suggestion is broken
+        # noinspection RegExpSingleCharAlternation
         for match in _re.findall(
             r":([\w\s]+(?:\s\|\s[\w\s]+|\w+))([^\w\s])((?:.|\n)*?)(?=\n:|$)",
             string,

{docsig-0.86.0 → docsig-0.87.0}/docsig/_utils.py

@@ -8,6 +8,7 @@ Shared helpers.
 import re as _re
 import sys as _sys
 from difflib import SequenceMatcher as _SequenceMatcher
+from pathlib import Path as _Path
 
 from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E
@@ -84,3 +85,25 @@ def sentence_tokenizer(text: str) -> list[str]:
         result.append(text[start:].strip())
 
     return result
+
+
+def get_parent_that_has(file: str, start: _Path | None = None) -> _Path | None:
+    """Find the parent directory that contains the given file.
+
+    Start from the current working directory and walk up to root. If
+    no required file is found, return None.
+
+    :param file: File to find.
+    :param start: Starting director.
+    :return: Parent directory containing the file or None if not found.
+    """
+    if start is None:
+        start = _Path.cwd()
+
+    if (start / file).is_file():
+        return start
+
+    if start.parent == start:
+        return None
+
+    return get_parent_that_has(file, start.parent)

{docsig-0.86.0 → docsig-0.87.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.86.0"
+__version__ = "0.87.0"

{docsig-0.86.0 → docsig-0.87.0}/pyproject.toml

@@ -11,7 +11,7 @@ line-length = 79
 allow_dirty = true
 commit = true
 commit_args = "-sS"
-current_version = "0.86.0"
+current_version = "0.87.0"
 message = "bump: version {current_version} → {new_version}"
 sign_tags = true
 tag = true
@@ -46,7 +46,7 @@ search = "- docsig=={current_version}"
 filename = "SECURITY.md"
 
 [tool.codespell]
-ignore-words-list = "astroid"
+ignore-words-list = "astroid,atLeast"
 
 [tool.coverage.report]
 exclude_lines = [
@@ -117,10 +117,10 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.86.0"
+version = "0.87.0"
 
 [tool.poetry.dependencies]
-Sphinx = ">=7,<9"
+Sphinx = ">=7,<8.2"
 astroid = "^4.0.2"
 pathspec = ">=0.12.1,<1.2.0"
 python = "^3.10"
@@ -159,6 +159,9 @@ templatest = ">=0.10.1,<0.13.0"
 [tool.poetry.group.flake8.dependencies]
 flake8 = "^7.1.0"
 
+[tool.poetry.group.plugin.dependencies]
+shiv = "^1.0.8"
+
 [tool.poetry.group.tests.dependencies]
 pytest = ">=8.2,<10.0"
 pytest-benchmark = ">=4,<6"
@@ -175,6 +178,9 @@ SIG = "docsig.plugin:Flake8"
 [tool.poetry.plugins."validate_pyproject.tool_schema"]
 docsig = "docsig.plugin:ValidatePyproject"
 
+[tool.poetry.requires-plugins]
+poetry-plugin-export = ">=1.8"
+
 [tool.poetry.scripts]
 docsig = "docsig.__main__:main"