docsig 0.85.0__tar.gz → 0.85.2__tar.gz

{docsig-0.85.0 → docsig-0.85.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docsig
-Version: 0.85.0
+Version: 0.85.2
 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.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.85.2, 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 +281,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.85.0
+        rev: v0.85.2
         hooks:
           - id: docsig
             args:
@@ -300,7 +300,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.85.0
+              - docsig==0.85.2
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.85.0 → docsig-0.85.2}/README.rst

@@ -166,7 +166,7 @@ ensure your installation has registered `docsig`
 .. code-block:: console
 
     $ flake8 --version
-    7.3.0 (docsig: 0.85.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin
+    7.3.0 (docsig: 0.85.2, 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 +252,7 @@ Standalone
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.85.0
+        rev: v0.85.2
         hooks:
           - id: docsig
             args:
@@ -271,7 +271,7 @@ or integrated with ``flake8``
         hooks:
           - id: flake8
             additional_dependencies:
-              - docsig==0.85.0
+              - docsig==0.85.2
             args:
               - "--sig-check-class"
               - "--sig-check-dunders"

{docsig-0.85.0 → docsig-0.85.2}/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.0 → docsig-0.85.2}/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.0 → docsig-0.85.2}/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

{docsig-0.85.0 → docsig-0.85.2}/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.0 → docsig-0.85.2}/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.0 → docsig-0.85.2}/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
 
@@ -104,7 +117,11 @@ class Directives(dict[int, tuple[Comments, _Messages]]):
     """
 
     @classmethod
-    def from_text(cls, text: str, messages: _Messages) -> Directives:
+    def from_text(  # pylint: disable=too-many-locals
+        cls,
+        text: str,
+        messages: _Messages,
+    ) -> Directives:
         """Build a directives map from docsig directives in the code.
 
         :param text: Python source code to scan for directives.
@@ -117,6 +134,8 @@ class Directives(dict[int, tuple[Comments, _Messages]]):
         enable_next = False
         next_comments = Comments(comments)
         next_messages = _Messages(messages)
+        pending_inline: tuple[Comments, _Messages] | None = None
+        pending_inline_lineno: int | None = None
         for line in _tokenize.generate_tokens(fin.readline):
             # do nothing for these line types
             if line.type in (_tokenize.NAME, _tokenize.OP, _tokenize.DEDENT):
@@ -154,6 +173,14 @@ class Directives(dict[int, tuple[Comments, _Messages]]):
                     if comment.ismodule:
                         comments = scoped_comments
                         messages = scoped_messages
+                    else:
+                        # defer scoped state for the next line without
+                        # changing module-level messages
+                        pending_inline = (
+                            Comments(scoped_comments),
+                            _Messages(scoped_messages),
+                        )
+                        pending_inline_lineno = lineno
 
             # if in a 'next' module level scope and the line type is a
             # newline (not a comment to allow 'next' directives to be
@@ -164,6 +191,17 @@ class Directives(dict[int, tuple[Comments, _Messages]]):
                 comments = next_comments
                 messages = next_messages
 
+            # inherit deferred inline scope on the first line after
+            # the comment (e.g. an indented def on the following line)
+            if (
+                pending_inline is not None
+                and pending_inline_lineno is not None
+                and lineno > pending_inline_lineno
+            ):
+                scoped_comments, scoped_messages = pending_inline
+                pending_inline = None
+                pending_inline_lineno = None
+
             # check that a scoped message has not updated this first, as
             # they take precedence over global messages
             if lineno not in directives:

{docsig-0.85.0 → docsig-0.85.2}/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.0 → docsig-0.85.2}/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
 

{docsig-0.85.0 → docsig-0.85.2}/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.0 → docsig-0.85.2}/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.0 → docsig-0.85.2}/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
@@ -324,10 +322,13 @@ class Failure(list[Failed]):
         if self._func.error is _ast.AstroidSyntaxError:
             self._add(_E[901])
             self._retcode = 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])
 

{docsig-0.85.0 → docsig-0.85.2}/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.0 → docsig-0.85.2}/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.0"
+__version__ = "0.85.2"

{docsig-0.85.0 → docsig-0.85.2}/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.0 → docsig-0.85.2}/pyproject.toml

@@ -11,7 +11,7 @@ line-length = 79
 allow_dirty = true
 commit = true
 commit_args = "-sS"
-current_version = "0.85.0"
+current_version = "0.85.2"
 message = "bump: version {current_version} → {new_version}"
 sign_tags = true
 tag = true
@@ -122,7 +122,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.85.0"
+version = "0.85.2"
 
 [tool.poetry.dependencies]
 Sphinx = ">=7,<9"