docsig 0.86.1__tar.gz → 0.87.1__tar.gz

{docsig-0.86.1 → docsig-0.87.1}/LICENSE

@@ -19,3 +19,8 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+This project includes code derived from Sphinx (sphinx.ext.napoleon),
+licensed under the BSD 2-Clause License.
+
+See licenses/SPHINX_LICENSE for details.

docsig-0.87.1/LICENSES/SPHINX_LICENSE

@@ -0,0 +1,39 @@
+This project includes code derived from Sphinx (sphinx.ext.napoleon).
+
+Sphinx is a documentation generator: https://www.sphinx-doc.org/
+
+The original code is licensed under the BSD 2-Clause License.
+
+---
+
+License for Sphinx
+==================
+
+Unless otherwise indicated, all code in the Sphinx project is licenced under the
+two clause BSD licence below.
+
+Copyright (c) 2007-2025 by the Sphinx team (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

{docsig-0.86.1 → docsig-0.87.1}/PKG-INFO

@@ -1,23 +1,22 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.86.1
+Version: 0.87.1
 Summary: Check signature params for proper documentation
-License: MIT
+License-Expression: MIT
 License-File: LICENSE
+License-File: LICENSES/SPHINX_LICENSE
 Keywords: check,docs,docstring,params,signature
 Author: jshwi
 Author-email: s.whitlock@live.com
 Maintainer: jshwi
 Maintainer-email: s.whitlock@live.com
-Requires-Python: >=3.10,<4.0
-Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 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: 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 +35,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 +73,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 +92,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 +200,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.86.1, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.87.1, 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 +286,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.86.1
+        rev: v0.87.1
         hooks:
           - id: docsig
             args:
@@ -300,7 +305,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.86.1
+              - docsig==0.87.1
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.86.1 → docsig-0.87.1}/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.1, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.87.1, 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.1
+        rev: v0.87.1
         hooks:
           - id: docsig
             args:
@@ -271,7 +277,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.86.1
+              - docsig==0.87.1
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.86.1 → docsig-0.87.1}/docsig/_check.py

@@ -6,8 +6,8 @@ docsig._check
 from ._config import Config as _Config
 from ._module import Function as _Function
 from ._module import Parent as _Parent
-from ._report import Failure as _Failure
 from ._report import Failures as _Failures
+from ._report import check_function as _check_function
 
 
 def _should_check_function(
@@ -47,7 +47,7 @@ def _run_check(
         parent,
         config,
     ):
-        failure = _Failure(child, config)
+        failure = _check_function(child, config)
         if failure:
             failures.append(failure)
 

{docsig-0.86.1 → docsig-0.87.1}/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",

{docsig-0.86.1 → docsig-0.87.1}/docsig/_core.py

@@ -21,7 +21,9 @@ 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 RetCode as _RetCode
 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
@@ -211,6 +213,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     logger = _logging.getLogger(__package__)
     logger.debug(_pformat(config))
     if config.list_checks:
+        # noinspection PyNoneFunctionAssignment
         return int(bool(_print_checks()))  # type: ignore
 
     if string:
@@ -218,11 +221,12 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         failures = _run_checks(module, config)
         return _report(failures, config)
 
-    retcodes = [0]
-    files = _Files(path, config.filters)
+    retcodes = _RetCode()
+    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))
-        retcodes.append(retcode)
+        retcodes.add(retcode)
 
-    return max(retcodes)
+    return retcodes.result

{docsig-0.86.1 → docsig-0.87.1}/docsig/_decorators.py

@@ -4,10 +4,13 @@ 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
 
+from ._report import RetCode as _RetCode
 from .messages import E as _E
 
 _FuncType = _t.Callable[..., int]
@@ -35,6 +38,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.
 
@@ -51,29 +55,31 @@ def validate_args(func: _FuncType) -> _WrappedFuncType:
 
     @_functools.wraps(func)
     def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> int:
-        stderr = []
+        format_json = _os.getenv("_DOCSIG_FORMAT_JSON") is not None
+        retcode = _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,13 +90,22 @@ 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 stderr:
-            print("\n".join(stderr), file=_sys.stderr)
-            return 2
+        if errors:
+            message = "\n".join(errors)
+            if format_json:
+                obj = [  # pragma: no cover
+                    {"line": None, "message": message, "exit": retcode.result},
+                ]
+                if format_json:  # pragma: no cover
+                    print(_json.dumps(obj).strip())  # pragma: no cover
+
+            else:
+                print(message, file=_sys.stderr)
+
+            return retcode.result
 
         return func(*args, **kwargs)
 

{docsig-0.86.1 → docsig-0.87.1}/docsig/_files.py

@@ -20,18 +20,8 @@ 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:
@@ -73,16 +63,18 @@ class Files(list[_Path]):
 
     :param paths: Path(s) to collect (files or directories).
     :param filters: Filters object.
+    :param repo: Path to the repo root.
     """
 
     def __init__(
         self,
         paths: tuple[str | _Path, ...],
         filters: _Filters,
+        repo: _Path | None = None,
     ) -> None:
         super().__init__()
         self._include_ignored = filters.include_ignored
-        self._gitignore = _Gitignore()
+        self._gitignore = _Gitignore(repo)
         logger = _logging.getLogger(__package__)
         for path in paths:
             self._populate(_Path(path))

{docsig-0.86.1 → docsig-0.87.1}/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.1 → docsig-0.87.1}/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: