docsig 0.85.1__tar.gz → 0.86.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.85.1
+Version: 0.86.0
 Summary: Check signature params for proper documentation
 License: MIT
 License-File: LICENSE
@@ -195,7 +195,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.85.1, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    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
 
 And now use `flake8` to lint your files
 
@@ -212,9 +212,9 @@ avoid any potential conflicts with other plugins
 .. code-block:: ini
 
     [flake8]
-    sig-check-dunders = True
-    sig-check-overridden = True
-    sig-check-protected = True
+    sig-check-dunders = true
+    sig-check-overridden = true
+    sig-check-protected = true
 
 ..
    end flake8
@@ -281,7 +281,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.85.1
+        rev: v0.86.0
         hooks:
           - id: docsig
             args:
@@ -300,7 +300,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.85.1
+              - docsig==0.86.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.85.1 → docsig-0.86.0}/README.rst

@@ -166,7 +166,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.85.1, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    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
 
 And now use `flake8` to lint your files
 
@@ -183,9 +183,9 @@ avoid any potential conflicts with other plugins
 .. code-block:: ini
 
     [flake8]
-    sig-check-dunders = True
-    sig-check-overridden = True
-    sig-check-protected = True
+    sig-check-dunders = true
+    sig-check-overridden = true
+    sig-check-protected = true
 
 ..
    end flake8
@@ -252,7 +252,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.85.1
+        rev: v0.86.0
         hooks:
           - id: docsig
             args:
@@ -271,7 +271,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.85.1
+              - docsig==0.86.0
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.85.1 → docsig-0.86.0}/docsig/__init__.py

@@ -5,4 +5,9 @@ from ._core import docsig
 from ._main import main
 from ._version import __version__
 
-__all__ = ["__version__", "docsig", "main", "messages"]
+__all__ = [
+    "__version__",
+    "docsig",
+    "main",
+    "messages",
+]

{docsig-0.85.1 → docsig-0.86.0}/docsig/_check.py

@@ -3,8 +3,6 @@ docsig._check
 =============
 """
 
-from __future__ import annotations as _
-
 from ._config import Config as _Config
 from ._module import Function as _Function
 from ._module import Parent as _Parent

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

@@ -5,8 +5,6 @@ docsig._config
 Config dataclasses, pyproject.toml loader, and commandline.
 """
 
-from __future__ import annotations as _
-
 import argparse as _argparse
 import os as _os
 import re as _re
@@ -149,17 +147,10 @@ def build_parser() -> _ArgumentParser:
         help="check class docstrings",
         dest="check_class",
     )
-    group.add_argument(
-        "-C",
-        action="store_true",
-        help=_argparse.SUPPRESS,
-        dest="check_class_constructor",
-    )
     group.add_argument(
         "--check-class-constructor",
         action="store_true",
         help="check __init__ methods",
-        dest="check_class_constructor",
     )
     parser.add_argument(
         "-D",

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

@@ -5,8 +5,6 @@ docsig._core
 Entry point and orchestration for running docstring/signature checks.
 """
 
-from __future__ import annotations as _
-
 import logging as _logging
 import sys as _sys
 import warnings as _warnings
@@ -175,6 +173,9 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     if exclude is not None:
         exclude_.append(exclude)
 
+    # while some params could be taken out for one time use (such as
+    # verbose), bundling all the configuration together makes it easier
+    # to report what args were provided in verbose mode
     check = _Check(
         class_=check_class,
         class_constructor=check_class_constructor,

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

@@ -3,8 +3,6 @@ docsig._decorators
 ==================
 """
 
-from __future__ import annotations as _
-
 import functools as _functools
 import sys as _sys
 import typing as _t

{docsig-0.85.1 → docsig-0.86.0}/docsig/_directives.py

@@ -36,10 +36,23 @@ class Comment(_Messages):
         self._kind = subparts[0]
         self._flag = None if len(subparts) == 1 else subparts[1]
         self._isnext = self._flag == "next"
-        if len(parts) == 1:
-            self.extend(_E.all)
-        else:
-            self.extend(_E.from_ref(i) for i in parts[1].split(","))
+
+        # if the flag is not valid, the preceding directive is not valid
+        # either
+        # at first it seems like the directive should be valid, i.e.
+        # `docsig: disable-next: SIG101` should still at least disable
+        # `SIG101`, but this causes more problems than it solves, at the
+        # module level
+        # disabling the check for the whole file is likely
+        # unexpected, confusing, and the opposite of what was intended
+        # better not disable the commented function than disable the
+        # whole file
+        # note that no directive flag at all is still a valid flag
+        if self.isvalidflag:
+            if len(parts) == 1:
+                self.extend(_E.all)
+            else:
+                self.extend(_E.from_ref(i) for i in parts[1].split(","))
 
     @property
     def kind(self) -> str:
@@ -90,7 +103,7 @@ class Comment(_Messages):
         :return: Comment instance if valid; None otherwise.
         """
         if comment[1:].strip().startswith(f"{__package__}:"):
-            return cls(comment.split(":")[1].strip(), col)
+            return cls(comment.split(":", maxsplit=1)[1].strip(), col)
 
         return None
 

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

@@ -5,8 +5,6 @@ docsig._files
 Path collection and filtering for files to check.
 """
 
-from __future__ import annotations as _
-
 import logging as _logging
 import os as _os
 import re as _re

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

@@ -5,8 +5,6 @@ docsig._main
 CLI entry point that parses args and runs docsig.
 """
 
-from __future__ import annotations as _
-
 import sys as _sys
 import warnings as _warnings
 
@@ -18,7 +16,6 @@ from ._hooks import excepthook as _excepthook
 def _warn_on_deprecated_short_flags() -> None:
     deprecated_short_flags = {
         "-c": "--check-class",
-        "-C": "--check-class-constructor",
         "-D": "--check-dunders",
         "-o": "--check-overridden",
         "-p": "--check-protected",

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

@@ -5,8 +5,6 @@ docsig._module
 AST-backed modules, classes, and functions for docstring checking.
 """
 
-from __future__ import annotations as _
-
 import re as _re
 import typing as _t
 from pathlib import Path as _Path
@@ -38,6 +36,8 @@ ERRORS = (
     _ast.DuplicateBasesError,
 )
 
+_DEFAULT_NAME = "module"
+
 
 class Parent:  # pylint: disable=too-many-instance-attributes
     """Container for functions or methods (module, class, or function).
@@ -74,8 +74,14 @@ class Parent:  # pylint: disable=too-many-instance-attributes
         self._imports = imports or _Imports()
         self._overloads = _Overloads()
         if node is None:
-            self._name = "module"
+            # this is either an empty module object (name it module)
+            # or an error preventing the module from being parsed
+            self._name = _DEFAULT_NAME
             if not isinstance(self, Function) and error is not None:
+                # the only "function" belonging to the module can be
+                # 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))
         else:
             self._name = node.name

{docsig-0.85.1 → docsig-0.86.0}/docsig/_parsers.py

@@ -3,8 +3,6 @@ docsig._parsers
 ===============
 """
 
-from __future__ import annotations as _
-
 import logging as _logging
 import os as _os
 from pathlib import Path as _Path
@@ -79,11 +77,16 @@ def parse_from_file(file: _Path, config: _Config) -> _Parent:
         code = file.read_text(encoding="utf-8")
         module_name = str(file)[:-3].replace(_os.sep, ".").replace("-", "_")
         parent = parse_from_string(code, config, module_name, file)
+
     except UnicodeDecodeError as err:
         logger = _logging.getLogger(__package__)
         logger.debug(_FILE_INFO, file, str(err).replace("\n", " "))
         parent = _Parent(error=type(err))
 
+    # not all python files end with .py, but considering this isn't a
+    # *.py file and there was an error parsing the file it's likely not
+    # meant to bea a python file
+    # return empty parent without the error
     if parent.error is not None and not file.name.endswith(".py"):
         parent = _Parent()
 

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

@@ -8,8 +8,6 @@ issue), Failures (sequence of failures), and report() to print them and
 return the highest exit code.
 """
 
-from __future__ import annotations as _
-
 import contextlib as _contextlib
 import sys as _sys
 import typing as _t
@@ -63,7 +61,7 @@ class Failure(list[Failed]):
 
     def __init__(self, func: _Function, config: _Config) -> None:
         super().__init__()
-        self._retcode = 0
+        self._retcode = [0]
         self._func = func
         if config.target:
             self._func.messages.extend(
@@ -102,7 +100,7 @@ class Failure(list[Failed]):
         hint: bool = False,
         **kwargs: _t.Any,
     ) -> None:
-        self._retcode = int(not value.new)
+        self._retcode.append(int(not value.new))
         failed = Failed(
             self._name,
             value.ref,
@@ -323,11 +321,14 @@ class Failure(list[Failed]):
         # invalid-syntax
         if self._func.error is _ast.AstroidSyntaxError:
             self._add(_E[901])
-            self._retcode = 123
+            self._retcode.append(123)
+        # unicode-decode-error
         if self._func.error is UnicodeDecodeError:
             self._add(_E[902])
+        # recursion-error
         if self._func.error is RecursionError:
             self._add(_E[903])
+        # duplicates-found-in-mros
         if self._func.error is _ast.DuplicateBasesError:
             self._add(_E[904])
 
@@ -344,7 +345,7 @@ class Failure(list[Failed]):
     @property
     def retcode(self) -> int:
         """Exit code (non-zero if any check failed)."""
-        return self._retcode
+        return max(self._retcode)
 
 
 def report(

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

@@ -5,8 +5,6 @@ docsig._utils
 Shared helpers.
 """
 
-from __future__ import annotations as _
-
 import re as _re
 import sys as _sys
 from difflib import SequenceMatcher as _SequenceMatcher

{docsig-0.85.1 → docsig-0.86.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.85.1"
+__version__ = "0.86.0"

{docsig-0.85.1 → docsig-0.86.0}/docsig/messages.py

@@ -6,8 +6,6 @@ Error message definitions (Message, MessageMap, E) and format templates
 for docstring-check output.
 """
 
-from __future__ import annotations as _
-
 import typing as _t
 
 #: Error code for unknown errors.
@@ -19,9 +17,8 @@ TEMPLATE = "{ref}: {description} ({symbolic})"
 #: Flake8 template to format message strings.
 FLAKE8 = "{ref} {description} ({symbolic})"
 
-NEW = """\
-{ref} is a new violation and will error in a future version\
-"""
+#: Template for future messages that don't raise a violation yet
+NEW = "{ref} is a new violation and will error in a future version"
 
 
 class Messages(list["Message"]):

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

@@ -11,7 +11,7 @@ line-length = 79
 allow_dirty = true
 commit = true
 commit_args = "-sS"
-current_version = "0.85.1"
+current_version = "0.86.0"
 message = "bump: version {current_version} → {new_version}"
 sign_tags = true
 tag = true
@@ -27,11 +27,6 @@ filename = "pyproject.toml"
 replace = 'version = "{new_version}"'
 search = 'version = "{current_version}"'
 
-[[tool.bumpversion.files]]
-filename = "package.json"
-replace = '"version": "{new_version}"'
-search = '"version": "{current_version}"'
-
 [[tool.bumpversion.files]]
 filename = "README.rst"
 replace = "rev: v{new_version}"
@@ -122,7 +117,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.85.1"
+version = "0.86.0"
 
 [tool.poetry.dependencies]
 Sphinx = ">=7,<9"