docsig 0.87.0__tar.gz → 0.88.0__tar.gz

{docsig-0.87.0 → docsig-0.88.0}/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.88.0/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.87.0 → docsig-0.88.0}/PKG-INFO

@@ -1,23 +1,22 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.87.0
+Version: 0.88.0
 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,<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 +35,7 @@ Description-Content-Type: text/x-rst
 
 |
 
-|License| |PyPI| |Jetbrains Plugin| |CI| |Jetbrains Build| |CodeQL| |pre-commit.ci status| |codecov.io| |readthedocs.org| |python3.10| |Black| |isort| |pylint| |Security Status|
+|License| |PyPI| |Jetbrains Plugin| |VS Code Extension| |CI| |Jetbrains Build| |VS Code 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
@@ -80,6 +79,12 @@ Description-Content-Type: text/x-rst
 .. |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
+.. |VS Code Build| image:: https://github.com/jshwi/docsig/actions/workflows/build-vscode-extension.yaml/badge.svg
+   :target: https://github.com/jshwi/docsig/actions/workflows/build-vscode-extension.yaml.yaml
+   :alt: Build
+.. |VS Code Extension| image:: https://img.shields.io/badge/vscode%20extension-v1.0.0-007ACC
+   :target: https://marketplace.visualstudio.com/items?itemName=jshwi.docsig
+   :alt: VS Code Extension Version
 
 Check Python signature params for proper documentation
 -------------------------------------------------------
@@ -119,7 +124,7 @@ Commandline
                   [--check-property-returns] [--check-protected]
                   [--check-protected-class-methods] [--ignore-args] [--ignore-kwargs]
                   [--ignore-no-params] [-d LIST] [-t LIST] [-e PATTERN] [-E PATH [PATH ...]]
-                  [-I] [-s STR]
+                  [-i] [-s STR]
                   [path [path ...]]
 
     Check signature params for proper documentation
@@ -155,7 +160,7 @@ Commandline
                             regular expression of files or dirs to exclude from checks
       -E PATH [PATH ...], --excludes PATH [PATH ...]
                             path glob patterns to exclude from checks
-      -I, --include-ignored
+      -i, --include-ignored
                             check files even if they match a gitignore pattern
       -s STR, --string STR  string to parse instead of files
 
@@ -201,7 +206,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    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
+    7.3.0 (docsig: 0.88.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
 
@@ -287,7 +292,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.87.0
+        rev: v0.88.0
         hooks:
           - id: docsig
             args:
@@ -306,7 +311,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.87.0
+              - docsig==0.88.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.87.0 → docsig-0.88.0}/README.rst

@@ -7,7 +7,7 @@
 
 |
 
-|License| |PyPI| |Jetbrains Plugin| |CI| |Jetbrains Build| |CodeQL| |pre-commit.ci status| |codecov.io| |readthedocs.org| |python3.10| |Black| |isort| |pylint| |Security Status|
+|License| |PyPI| |Jetbrains Plugin| |VS Code Extension| |CI| |Jetbrains Build| |VS Code 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
@@ -51,6 +51,12 @@
 .. |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
+.. |VS Code Build| image:: https://github.com/jshwi/docsig/actions/workflows/build-vscode-extension.yaml/badge.svg
+   :target: https://github.com/jshwi/docsig/actions/workflows/build-vscode-extension.yaml.yaml
+   :alt: Build
+.. |VS Code Extension| image:: https://img.shields.io/badge/vscode%20extension-v1.0.0-007ACC
+   :target: https://marketplace.visualstudio.com/items?itemName=jshwi.docsig
+   :alt: VS Code Extension Version
 
 Check Python signature params for proper documentation
 -------------------------------------------------------
@@ -90,7 +96,7 @@ Commandline
                   [--check-property-returns] [--check-protected]
                   [--check-protected-class-methods] [--ignore-args] [--ignore-kwargs]
                   [--ignore-no-params] [-d LIST] [-t LIST] [-e PATTERN] [-E PATH [PATH ...]]
-                  [-I] [-s STR]
+                  [-i] [-s STR]
                   [path [path ...]]
 
     Check signature params for proper documentation
@@ -126,7 +132,7 @@ Commandline
                             regular expression of files or dirs to exclude from checks
       -E PATH [PATH ...], --excludes PATH [PATH ...]
                             path glob patterns to exclude from checks
-      -I, --include-ignored
+      -i, --include-ignored
                             check files even if they match a gitignore pattern
       -s STR, --string STR  string to parse instead of files
 
@@ -172,7 +178,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    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
+    7.3.0 (docsig: 0.88.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
 
@@ -258,7 +264,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.87.0
+        rev: v0.88.0
         hooks:
           - id: docsig
             args:
@@ -277,7 +283,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.87.0
+              - docsig==0.88.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.87.0 → docsig-0.88.0}/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.87.0 → docsig-0.88.0}/docsig/_config.py

@@ -250,6 +250,12 @@ def build_parser() -> _ArgumentParser:
     )
     parser.add_argument(
         "-I",
+        action="store_true",
+        help=_argparse.SUPPRESS,
+        dest="include_ignored",
+    )
+    parser.add_argument(
+        "-i",
         "--include-ignored",
         action="store_true",
         help="check files even if they match a gitignore pattern",

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

@@ -21,6 +21,7 @@ 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
@@ -220,12 +221,12 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         failures = _run_checks(module, config)
         return _report(failures, config)
 
-    retcodes = [0]
+    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.87.0 → docsig-0.88.0}/docsig/_decorators.py

@@ -10,6 +10,7 @@ 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]
@@ -55,7 +56,7 @@ def validate_args(func: _FuncType) -> _WrappedFuncType:
     @_functools.wraps(func)
     def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> int:
         format_json = _os.getenv("_DOCSIG_FORMAT_JSON") is not None
-        retcode = 2
+        retcode = _RetCode(2)
         errors = []
         if not kwargs.get("list_checks", False):
             if not args and not kwargs.get("string"):
@@ -96,7 +97,7 @@ def validate_args(func: _FuncType) -> _WrappedFuncType:
             message = "\n".join(errors)
             if format_json:
                 obj = [  # pragma: no cover
-                    {"line": None, "message": message, "exit": retcode},
+                    {"line": None, "message": message, "exit": retcode.result},
                 ]
                 if format_json:  # pragma: no cover
                     print(_json.dumps(obj).strip())  # pragma: no cover
@@ -104,7 +105,7 @@ def validate_args(func: _FuncType) -> _WrappedFuncType:
             else:
                 print(message, file=_sys.stderr)
 
-            return retcode
+            return retcode.result
 
         return func(*args, **kwargs)
 

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

@@ -16,6 +16,7 @@ from ._hooks import excepthook as _excepthook
 
 def _warn_on_deprecated_short_flags() -> None:
     deprecated_short_flags = {
+        "-I": "--include-ignored",
         "-c": "--check-class",
         "-D": "--check-dunders",
         "-o": "--check-overridden",

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

@@ -35,6 +35,38 @@ _MIN_MATCH = 0.8
 _MAX_MATCH = 1.0
 
 
+def check_function(func: _Function, config: _Config) -> "Failure":
+    """Run configured checks for one function and return the result.
+
+    :param func: Function under check.
+    :param config: Configuration object.
+    :return: Collected diagnostics for the function.
+    """
+    return Failure(func, config)
+
+
+class RetCode:
+    """RetCode object.
+
+    :param code: Initial return code, if any, otherwise zero.
+    """
+
+    def __init__(self, code: int = 0) -> None:
+        self._data = [code]
+
+    def add(self, code: int) -> None:
+        """Add a return code.
+
+        :param code: Return code to add.
+        """
+        self._data.append(code)
+
+    @property
+    def result(self) -> int:
+        """Maximum return code."""
+        return max(self._data)
+
+
 class Failures(list["Failure"]):
     """Sequence of Failure instances (one per function checked)."""
 
@@ -63,7 +95,7 @@ class Failure(list[Failed]):
 
     def __init__(self, func: _Function, config: _Config) -> None:
         super().__init__()
-        self._retcode = [0]
+        self._retcode = RetCode()
         self._func = func
         if config.target:
             self._func.messages.extend(
@@ -80,7 +112,7 @@ class Failure(list[Failed]):
             self._name = f"{self._func.parent.name}.{self._name}"
 
         if self._func.error is not None:
-            self._retcode.append(2)
+            self._retcode.add(2)
             self._sig9xx_error()
         else:
             self._sig0xx_config()
@@ -104,7 +136,7 @@ class Failure(list[Failed]):
         include_hint: bool = False,
         **kwargs: _t.Any,
     ) -> None:
-        self._retcode.append(int(not value.new))
+        self._retcode.add(int(not value.new))
         failed = Failed(
             self._name,
             value.ref,
@@ -337,7 +369,7 @@ class Failure(list[Failed]):
         # invalid-syntax
         if self._func.error is _ast.AstroidSyntaxError:
             self._add(_E[901])
-            self._retcode.append(123)
+            self._retcode.add(123)
         # unicode-decode-error
         if self._func.error is UnicodeDecodeError:
             self._add(_E[902])
@@ -361,7 +393,7 @@ class Failure(list[Failed]):
     @property
     def retcode(self) -> int:
         """Exit code (non-zero if any check failed)."""
-        return max(self._retcode)
+        return self._retcode.result
 
 
 # TODO: make report json by default and wrap with a reporter for cli
@@ -381,11 +413,11 @@ def report(
     :return: Exit code (non-zero if any check failed).
     """
     format_json = _os.getenv("_DOCSIG_FORMAT_JSON") is not None
-    retcodes = [0]
+    retcodes = RetCode()
     output = []
     obj = []
     for failure in failures:
-        retcodes.append(failure.retcode)
+        retcodes.add(failure.retcode)
         path_prefix = f"{file}:" if file is not None else ""
         header = f"{path_prefix}{failure.lineno} in {failure.name}"
         if not config.no_ansi and _sys.stdout.isatty():
@@ -424,4 +456,4 @@ def report(
     elif output:
         print("\n".join(output))
 
-    return max(retcodes)
+    return retcodes.result

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

@@ -14,9 +14,9 @@ from collections import Counter as _Counter
 from enum import Enum as _Enum
 
 import astroid as _ast
-import sphinx.ext.napoleon as _s
 
 from ._config import Ignore as _Ignore
+from ._vendor.sphinx.ext import napoleon as _s
 
 # no function will accidentally have this name
 UNNAMED = "-1000"
@@ -330,9 +330,9 @@ class Docstring(_Stub):
         # convert Google and numpy style docstrings to parse docstrings
         # as restructured text
         return str(
-            _s.NumpyDocstring(
+            _s.NumpyDocstring(  # type: ignore
                 str(
-                    _s.GoogleDocstring(
+                    _s.GoogleDocstring(  # type: ignore
                         _textwrap.dedent(
                             "\n".join(string.splitlines()[1:]),
                         ).replace("*", ""),