docsig 0.51.0__tar.gz → 0.52.0__tar.gz

{docsig-0.51.0 → docsig-0.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docsig
-Version: 0.51.0
+Version: 0.52.0
 Summary: Check signature params for proper documentation
 Home-page: https://pypi.org/project/docsig/
 License: MIT
@@ -36,49 +36,51 @@ Description-Content-Type: text/x-rst
 
 |
 
-.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
+|License| |PyPI| |CI| |CodeQL| |pre-commit.ci status| |codecov.io| |readthedocs.org| |python3.8| |Black| |isort| |docformatter| |pylint| |Security Status| |Known Vulnerabilities| |docsig|
+
+.. |License| image:: https://img.shields.io/badge/License-MIT-yellow.svg
    :target: https://opensource.org/licenses/MIT
    :alt: License
-.. image:: https://img.shields.io/pypi/v/docsig
+.. |PyPI| image:: https://img.shields.io/pypi/v/docsig
    :target: https://pypi.org/project/docsig/
    :alt: PyPI
-.. image:: https://github.com/jshwi/docsig/actions/workflows/build.yaml/badge.svg
+.. |CI| image:: https://github.com/jshwi/docsig/actions/workflows/build.yaml/badge.svg
    :target: https://github.com/jshwi/docsig/actions/workflows/build.yaml
    :alt: CI
-.. image:: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml/badge.svg
+.. |CodeQL| image:: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml/badge.svg
    :target: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml
    :alt: CodeQL
-.. image:: https://results.pre-commit.ci/badge/github/jshwi/docsig/master.svg
+.. |pre-commit.ci status| image:: https://results.pre-commit.ci/badge/github/jshwi/docsig/master.svg
    :target: https://results.pre-commit.ci/latest/github/jshwi/docsig/master
    :alt: pre-commit.ci status
-.. image:: https://codecov.io/gh/jshwi/docsig/branch/master/graph/badge.svg
+.. |codecov.io| image:: https://codecov.io/gh/jshwi/docsig/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/jshwi/docsig
    :alt: codecov.io
-.. image:: https://readthedocs.org/projects/docsig/badge/?version=latest
+.. |readthedocs.org| image:: https://readthedocs.org/projects/docsig/badge/?version=latest
    :target: https://docsig.readthedocs.io/en/latest/?badge=latest
    :alt: readthedocs.org
-.. image:: https://img.shields.io/badge/python-3.8-blue.svg
+.. |python3.8| image:: https://img.shields.io/badge/python-3.8-blue.svg
    :target: https://www.python.org/downloads/release/python-380
    :alt: python3.8
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black
    :alt: Black
-.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
+.. |isort| image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
    :target: https://pycqa.github.io/isort/
    :alt: isort
-.. image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg
+.. |docformatter| image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg
    :target: https://github.com/PyCQA/docformatter
    :alt: docformatter
-.. image:: https://img.shields.io/badge/linting-pylint-yellowgreen
+.. |pylint| image:: https://img.shields.io/badge/linting-pylint-yellowgreen
    :target: https://github.com/PyCQA/pylint
    :alt: pylint
-.. image:: https://img.shields.io/badge/security-bandit-yellow.svg
+.. |Security Status| image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security Status
-.. image:: https://snyk.io/test/github/jshwi/docsig/badge.svg
+.. |Known Vulnerabilities| image:: https://snyk.io/test/github/jshwi/docsig/badge.svg
    :target: https://snyk.io/test/github/jshwi/docsig/badge.svg
    :alt: Known Vulnerabilities
-.. image:: https://snyk.io/advisor/python/docsig/badge.svg
+.. |docsig| image:: https://snyk.io/advisor/python/docsig/badge.svg
    :target: https://snyk.io/advisor/python/docsig
    :alt: docsig
 
@@ -227,7 +229,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.51.0
+        rev: v0.52.0
         hooks:
           - id: docsig
             args:

{docsig-0.51.0 → docsig-0.52.0}/README.rst

@@ -7,49 +7,51 @@
 
 |
 
-.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
+|License| |PyPI| |CI| |CodeQL| |pre-commit.ci status| |codecov.io| |readthedocs.org| |python3.8| |Black| |isort| |docformatter| |pylint| |Security Status| |Known Vulnerabilities| |docsig|
+
+.. |License| image:: https://img.shields.io/badge/License-MIT-yellow.svg
    :target: https://opensource.org/licenses/MIT
    :alt: License
-.. image:: https://img.shields.io/pypi/v/docsig
+.. |PyPI| image:: https://img.shields.io/pypi/v/docsig
    :target: https://pypi.org/project/docsig/
    :alt: PyPI
-.. image:: https://github.com/jshwi/docsig/actions/workflows/build.yaml/badge.svg
+.. |CI| image:: https://github.com/jshwi/docsig/actions/workflows/build.yaml/badge.svg
    :target: https://github.com/jshwi/docsig/actions/workflows/build.yaml
    :alt: CI
-.. image:: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml/badge.svg
+.. |CodeQL| image:: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml/badge.svg
    :target: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml
    :alt: CodeQL
-.. image:: https://results.pre-commit.ci/badge/github/jshwi/docsig/master.svg
+.. |pre-commit.ci status| image:: https://results.pre-commit.ci/badge/github/jshwi/docsig/master.svg
    :target: https://results.pre-commit.ci/latest/github/jshwi/docsig/master
    :alt: pre-commit.ci status
-.. image:: https://codecov.io/gh/jshwi/docsig/branch/master/graph/badge.svg
+.. |codecov.io| image:: https://codecov.io/gh/jshwi/docsig/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/jshwi/docsig
    :alt: codecov.io
-.. image:: https://readthedocs.org/projects/docsig/badge/?version=latest
+.. |readthedocs.org| image:: https://readthedocs.org/projects/docsig/badge/?version=latest
    :target: https://docsig.readthedocs.io/en/latest/?badge=latest
    :alt: readthedocs.org
-.. image:: https://img.shields.io/badge/python-3.8-blue.svg
+.. |python3.8| image:: https://img.shields.io/badge/python-3.8-blue.svg
    :target: https://www.python.org/downloads/release/python-380
    :alt: python3.8
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black
    :alt: Black
-.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
+.. |isort| image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
    :target: https://pycqa.github.io/isort/
    :alt: isort
-.. image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg
+.. |docformatter| image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg
    :target: https://github.com/PyCQA/docformatter
    :alt: docformatter
-.. image:: https://img.shields.io/badge/linting-pylint-yellowgreen
+.. |pylint| image:: https://img.shields.io/badge/linting-pylint-yellowgreen
    :target: https://github.com/PyCQA/pylint
    :alt: pylint
-.. image:: https://img.shields.io/badge/security-bandit-yellow.svg
+.. |Security Status| image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security Status
-.. image:: https://snyk.io/test/github/jshwi/docsig/badge.svg
+.. |Known Vulnerabilities| image:: https://snyk.io/test/github/jshwi/docsig/badge.svg
    :target: https://snyk.io/test/github/jshwi/docsig/badge.svg
    :alt: Known Vulnerabilities
-.. image:: https://snyk.io/advisor/python/docsig/badge.svg
+.. |docsig| image:: https://snyk.io/advisor/python/docsig/badge.svg
    :target: https://snyk.io/advisor/python/docsig
    :alt: docsig
 
@@ -198,7 +200,7 @@ It can be added to your .pre-commit-config.yaml as follows:
 
     repos:
       - repo: https://github.com/jshwi/docsig
-        rev: v0.51.0
+        rev: v0.52.0
         hooks:
           - id: docsig
             args:

{docsig-0.51.0 → docsig-0.52.0}/docsig/_core.py

@@ -7,20 +7,17 @@ from __future__ import annotations as _
 
 from pathlib import Path as _Path
 
-import click as _click
-
 from . import _decorators
 from ._display import Display as _Display
 from ._display import Failure as _Failure
 from ._display import Failures as _Failures
 from ._display import FuncStr as _FuncStr
-from ._message import Message as _Message
 from ._module import Function as _Function
 from ._module import Modules as _Modules
 from ._module import Parent as _Parent
 from ._report import Report as _Report
-from .messages import TEMPLATE as _TEMPLATE
-from .messages import E as _E
+from ._utils import print_checks as _print_checks
+from .messages import Messages as _Messages
 
 _DEFAULT_EXCLUDES = """\
 (?x)^(
@@ -42,11 +39,6 @@ _DEFAULT_EXCLUDES = """\
 """
 
 
-def _print_checks() -> None:
-    for msg in _E.values():
-        _click.echo(msg.fstring(_TEMPLATE))
-
-
 def _run_check(  # pylint: disable=too-many-arguments
     child: _Parent,
     parent: _Parent,
@@ -59,7 +51,7 @@ def _run_check(  # pylint: disable=too-many-arguments
     check_property_returns: bool,
     ignore_no_params: bool,
     no_ansi: bool,
-    targets: list[_Message],
+    targets: _Messages,
     failures: _Failures,
 ) -> None:
     if isinstance(child, _Function):
@@ -76,7 +68,7 @@ def _run_check(  # pylint: disable=too-many-arguments
             and not (child.docstring.bare and ignore_no_params)
         ):
             report = _Report(
-                child, targets, child.disabled, check_property_returns
+                child, targets, child.messages, check_property_returns
             )
             if report:
                 failures.append(_Failure(child, _FuncStr(child), report))
@@ -99,6 +91,7 @@ def _run_check(  # pylint: disable=too-many-arguments
                     failures,
                 )
     else:
+        # this is a class
         for func in child:
             _run_check(
                 func,
@@ -138,8 +131,8 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     no_ansi: bool = False,
     summary: bool = False,
     verbose: bool = False,
-    targets: list[_Message] | None = None,
-    disable: list[_Message] | None = None,
+    targets: _Messages | None = None,
+    disable: _Messages | None = None,
     exclude: str | None = None,
 ) -> int:
     """Package's core functionality.
@@ -188,7 +181,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
 
     modules = _Modules(
         *tuple(_Path(i) for i in path),
-        disable=disable or [],
+        messages=disable or _Messages(),
         string=string,
         excludes=excludes,
         include_ignored=include_ignored,
@@ -219,7 +212,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
                     check_property_returns,
                     ignore_no_params,
                     no_ansi,
-                    targets or [],
+                    targets or _Messages(),
                     failures,
                 )
                 if failures:

{docsig-0.51.0 → docsig-0.52.0}/docsig/_decorators.py

@@ -25,8 +25,8 @@ def parse_msgs(func: _WrappedFuncType) -> _WrappedFuncType:
 
     @_functools.wraps(func)
     def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> str | int:
-        disable = list(_E.fromcodes(kwargs.get("disable", []))) or None
-        targets = list(_E.fromcodes(kwargs.get("targets", []))) or None
+        disable = _E.from_codes(kwargs.get("disable", [])) or None
+        targets = _E.from_codes(kwargs.get("targets", [])) or None
         kwargs["disable"] = disable
         kwargs["targets"] = targets
         return func(*args, **kwargs)

docsig-0.52.0/docsig/_directives.py

@@ -0,0 +1,134 @@
+"""
+docsig._disable
+===============
+"""
+
+from __future__ import annotations as _
+
+import tokenize as _tokenize
+import typing as _t
+from io import StringIO as _StringIO
+
+from .messages import E as _E
+from .messages import Messages as _Messages
+
+
+class Comment(_Messages):
+    """Represents a comment directive.
+
+    :param string: Text to construct comment from.
+    :param col: The column this directive is positioned at.
+    """
+
+    _valid_kinds = "enable", "disable"
+
+    def __init__(self, string: str, col: int) -> None:
+        super().__init__()
+        self._ismodule = col == 0
+        parts = string.split("=")
+        self._kind = parts[0]
+        if len(parts) == 1:
+            self.extend(_E.all(1))
+        else:
+            self.extend(_E.from_ref(i) for i in parts[1].split(","))
+
+    @property
+    def kind(self) -> str:
+        """The type of this directive."""
+        return self._kind
+
+    @property
+    def isvalid(self) -> bool:
+        """Whether this directive is valid or not."""
+        return self._kind in self._valid_kinds
+
+    @property
+    def ismodule(self) -> bool:
+        """Whether this is a module level directive or not."""
+        return self._ismodule
+
+    @property
+    def enable(self) -> bool:
+        """Whether this is an enable directive or not."""
+        return self._kind == self._valid_kinds[0]
+
+    @property
+    def disable(self) -> bool:
+        """Whether this is a disable directive or not."""
+        return self._kind == self._valid_kinds[1]
+
+    @classmethod
+    def parse(cls, comment: str, col: int) -> Comment | None:
+        """Parse string into directive object if possible.
+
+        :param comment: Comment to parse.
+        :param col: Column of comment to instantiate directive.
+        :return: Instantiated directive object if valid directive or
+            None if not a valid directive.
+        """
+        if comment[1:].strip().startswith(f"{__package__}:"):
+            return cls(comment.split(":")[1].strip(), col)
+
+        return None
+
+
+class _Comments(_t.List[Comment]):
+    """List of comments."""
+
+
+class Directives(_t.Dict[int, _t.Tuple[_Comments, _Messages]]):
+    """Data for directives:
+
+    Dict like object with the line number of directive as the key a
+    tuple containing comments and messages.
+
+    Comments can be either disable or enable comments, and messages are
+    what messages are to be disabled.
+
+    Comments influence what messages can be added to the list, but are
+    different in that they communicate the directive, but the messages
+    are the final product of messages to disable.
+
+    Comments are collected here for later analysis.
+
+    :param text: Python code.
+    :param messages: List of checks to disable.
+    """
+
+    def __init__(self, text: str, messages: _Messages) -> None:
+        super().__init__()
+        fin = _StringIO(text)
+        comments = _Comments()
+        for line in _tokenize.generate_tokens(fin.readline):
+            # do nothing for these lines types
+            if line.type in (_tokenize.NAME, _tokenize.OP, _tokenize.DEDENT):
+                continue
+
+            # inherit the comments and messages defined in the global
+            # scope, but do not update the global comments and messages
+            # unless it is confirmed that the comment is a module level
+            # directive
+            scoped_comments = _Comments(comments)
+            scoped_messages = _Messages(messages)
+            lineno, col = line.start
+            if line.type == _tokenize.COMMENT:
+                comment = Comment.parse(line.string, col)
+                if comment is not None:
+                    scoped_comments.append(comment)
+                    if comment.disable:
+                        scoped_messages.extend(comment)
+                    elif comment.enable:
+                        scoped_messages = _Messages(
+                            i for i in messages if i not in comment
+                        )
+
+                    # if module level directive then make changes
+                    # globally
+                    if comment.ismodule:
+                        messages = scoped_messages
+                        comments = scoped_comments
+
+            # check that a scoped message has not updated this first, as
+            # they take precedence over global messages
+            if lineno not in self:
+                self[lineno] = scoped_comments, scoped_messages

{docsig-0.51.0 → docsig-0.52.0}/docsig/_hooks.py

@@ -6,7 +6,7 @@ docsig._hooks
 import sys as _sys
 from os import environ as _e
 
-from ._utils import pretty_print_error
+from ._utils import pretty_print_error as _pretty_print_error
 
 
 def excepthook(no_ansi: bool = False) -> None:
@@ -15,6 +15,6 @@ def excepthook(no_ansi: bool = False) -> None:
     :param no_ansi: Disable ANSI output.
     """
     if _e.get("DOCSIG_DEBUG", None) != "1":
-        _sys.excepthook = lambda x, y, _: pretty_print_error(
+        _sys.excepthook = lambda x, y, _: _pretty_print_error(
             x, str(y), no_ansi
         )

{docsig-0.51.0 → docsig-0.52.0}/docsig/_module.py

@@ -17,13 +17,13 @@ from astroid import AstroidSyntaxError as _AstroidSyntaxError
 from pathspec import PathSpec as _PathSpec
 from pathspec.patterns import GitWildMatchPattern as _GitWildMatchPattern
 
-from ._directives import Directive as _Directive
+from ._directives import Comment as _Comment
 from ._directives import Directives as _Directives
-from ._message import Message as _Message
 from ._stub import Docstring as _Docstring
 from ._stub import Signature as _Signature
-from ._utils import pretty_print_error
+from ._utils import pretty_print_error as _pretty_print_error
 from ._utils import vprint as _vprint
+from .messages import Messages as _Messages
 
 _FILE_INFO = "{path}: {msg}"
 
@@ -84,6 +84,7 @@ class Parent(_t.List["Parent"]):
     :param check_class_constructor: Check the class constructor's
         docstring. Otherwise, expect the constructor's documentation to
         be on the class level docstring.
+    :param imports: Imports within this scope.
     """
 
     def __init__(  # pylint: disable=too-many-arguments
@@ -94,12 +95,13 @@ class Parent(_t.List["Parent"]):
         ignore_args: bool = False,
         ignore_kwargs: bool = False,
         check_class_constructor: bool = False,
+        imports: dict[str, str] | None = None,
     ) -> None:
         super().__init__()
         self._name = node.name
         self._path = f"{path}:" if path is not None else ""
-        overloads: list[str] = []
-        returns = None
+        self._overloads: dict[str, Function] = {}
+        self._imports = imports or {}
         self._parse_ast(
             node,
             directives,
@@ -107,10 +109,13 @@ class Parent(_t.List["Parent"]):
             ignore_args,
             ignore_kwargs,
             check_class_constructor,
-            overloads,
-            returns,
         )
 
+    def _parse_imports(self, names: list[tuple[str, str | None]]) -> None:
+        for name in names:
+            original, alias = name
+            self._imports[original] = alias or original
+
     def _parse_ast(  # pylint: disable=protected-access,too-many-arguments
         self,
         node,
@@ -119,9 +124,10 @@ class Parent(_t.List["Parent"]):
         ignore_args,
         ignore_kwargs,
         check_class_constructor,
-        overloads,
-        returns,
     ) -> None:
+        # need to keep track of `comments` as, even though they are
+        # resolved in directives object, they are needed to notify user
+        # in the case that they are invalid
         parent_comments, parent_disabled = directives.get(
             node.lineno, ([], [])
         )
@@ -130,7 +136,9 @@ class Parent(_t.List["Parent"]):
                 comments, disabled = directives.get(subnode.lineno, ([], []))
                 comments.extend(parent_comments)
                 disabled.extend(parent_disabled)
-                if isinstance(subnode, _ast.FunctionDef):
+                if isinstance(subnode, (_ast.Import, _ast.ImportFrom)):
+                    self._parse_imports(subnode.names)
+                elif isinstance(subnode, _ast.FunctionDef):
                     func = Function(
                         subnode,
                         comments,
@@ -140,22 +148,14 @@ class Parent(_t.List["Parent"]):
                         ignore_args,
                         ignore_kwargs,
                         check_class_constructor,
+                        self._imports,
                     )
                     if func.isoverloaded:
-                        overloads.append(func.name)
-                        returns = func.signature.rettype
+                        self._overloads[func.name] = func
                     else:
-                        if func.name in overloads:
-                            subnode.returns = returns
-                            # noinspection PyProtectedMember
-                            func._signature._rettype = (
-                                returns
-                                if isinstance(returns, str)
-                                else func._signature._get_rettype(returns)
-                            )
-                            # noinspection PyProtectedMember
-                            func._signature._returns = (
-                                str(func._signature._rettype) != "None"
+                        if func.name in self._overloads:
+                            func.overload(
+                                self._overloads[func.name].signature.rettype
                             )
 
                         self.append(func)
@@ -168,6 +168,7 @@ class Parent(_t.List["Parent"]):
                             ignore_args,
                             ignore_kwargs,
                             check_class_constructor,
+                            self._imports,
                         )
                     )
                 else:
@@ -178,8 +179,6 @@ class Parent(_t.List["Parent"]):
                         ignore_args,
                         ignore_kwargs,
                         check_class_constructor,
-                        overloads,
-                        returns,
                     )
 
     @property
@@ -199,25 +198,27 @@ class Function(Parent):
     :param node: Function's abstract syntax tree.
     :param comments: Comments in list form containing directives.
     :param directives: Directive, if any, belonging to this function.
-    :param disabled: List of disabled checks specific to this function.
+    :param messages: List of disabled checks specific to this function.
     :param path: Path to base path representation on.
     :param ignore_args: Ignore args prefixed with an asterisk.
     :param ignore_kwargs: Ignore kwargs prefixed with two asterisks.
     :param check_class_constructor: If the function is the class
         constructor, use its own docstring. Otherwise, use the class
         level docstring for the constructor function.
+    :param imports: Imports within this scope.
     """
 
     def __init__(  # pylint: disable=too-many-arguments
         self,
         node: _ast.FunctionDef,
-        comments: _t.List[_Directive],
+        comments: list[_Comment],
         directives: _Directives,
-        disabled: list[_Message],
+        messages: _Messages,
         path: _Path | None = None,
         ignore_args: bool = False,
         ignore_kwargs: bool = False,
         check_class_constructor: bool = False,
+        imports: dict[str, str] | None = None,
     ) -> None:
         super().__init__(
             node,
@@ -226,10 +227,11 @@ class Function(Parent):
             ignore_args,
             ignore_kwargs,
             check_class_constructor,
+            imports,
         )
         self._node = node
-        self._directives = comments
-        self._disabled = disabled
+        self._comments = comments
+        self._messages = messages
         self._parent = node.parent.frame()
         self._signature = _Signature(
             node.args,
@@ -251,6 +253,7 @@ class Function(Parent):
         return max([len(self.signature.args), len(self.docstring.args)])
 
     def _decorated_with(self, name: str) -> bool:
+        name = self._imports.get(name, name)
         if self._node.decorators is not None:
             for dec in self._node.decorators.nodes:
                 return (isinstance(dec, _ast.Name) and dec.name == name) or (
@@ -344,14 +347,21 @@ class Function(Parent):
         return self._docstring
 
     @property
-    def disabled(self) -> list[_Message]:
+    def messages(self) -> _Messages:
         """List of disabled checks specific to this function."""
-        return self._disabled
+        return self._messages
 
     @property
-    def directives(self) -> _t.List[_Directive]:
-        """Directive, if any, belonging to this function."""
-        return self._directives
+    def comments(self) -> list[_Comment]:
+        """Comments, if any, belonging to this function."""
+        return self._comments
+
+    def overload(self, rettype: str | None) -> None:
+        """Overload function with new signature return type.
+
+        :param rettype: Return type of overloaded signature.
+        """
+        self._signature.overload(rettype)
 
 
 class Modules(_t.List[Parent]):  # pylint: disable=too-many-instance-attributes
@@ -363,7 +373,7 @@ class Modules(_t.List[Parent]):  # pylint: disable=too-many-instance-attributes
     If string is provided, ignore paths.
 
     :param paths: Path(s) to parse ``Module``(s) from.
-    :param disable: List of checks to disable.
+    :param messages: List of checks to disable.
     :param excludes: List pf regular expression of files and dirs to
         exclude from checks.
     :param string: String to parse if provided.
@@ -381,7 +391,7 @@ class Modules(_t.List[Parent]):  # pylint: disable=too-many-instance-attributes
     # handle errors here before appending a module
     def _add_module(  # pylint: disable=too-many-arguments
         self,
-        disable: list[_Message],
+        messages: _Messages,
         string: str | None = None,
         root: _Path | None = None,
         ignore_args: bool = False,
@@ -398,7 +408,7 @@ class Modules(_t.List[Parent]):  # pylint: disable=too-many-instance-attributes
             self.append(
                 Parent(
                     _ast.parse(string),
-                    _Directives(string, disable),
+                    _Directives(string, messages),
                     root,
                     ignore_args,
                     ignore_kwargs,
@@ -418,7 +428,7 @@ class Modules(_t.List[Parent]):  # pylint: disable=too-many-instance-attributes
                 # may result in a 123 syntax error exit status in the
                 # future
                 _click.echo(root, file=_sys.stderr)
-                pretty_print_error(type(err), msg, no_ansi=self._no_ansi)
+                _pretty_print_error(type(err), msg, no_ansi=self._no_ansi)
                 self._retcode = 1
 
             _vprint(
@@ -429,7 +439,7 @@ class Modules(_t.List[Parent]):  # pylint: disable=too-many-instance-attributes
     def __init__(  # pylint: disable=too-many-arguments
         self,
         *paths: _Path,
-        disable: list[_Message],
+        messages: _Messages,
         excludes: list[str],
         string: str | None = None,
         include_ignored: bool = False,
@@ -440,19 +450,19 @@ class Modules(_t.List[Parent]):  # pylint: disable=too-many-instance-attributes
         verbose: bool = False,
     ) -> None:
         super().__init__()
-        self._disable = disable
+        self._messages = messages
         self._excludes = excludes
         self._include_ignored = include_ignored
         self._ignore_args = ignore_args
         self._ignore_kwargs = ignore_kwargs
-        self.check_class_constructor = check_class_constructor
+        self._check_class_constructor = check_class_constructor
         self._no_ansi = no_ansi
         self._verbose = verbose
         self._retcode = 0
         self._gitignore = _Gitignore()
         if string is not None:
             self._add_module(
-                disable,
+                messages,
                 string=string,
                 ignore_args=ignore_args,
                 ignore_kwargs=ignore_kwargs,
@@ -484,11 +494,11 @@ class Modules(_t.List[Parent]):  # pylint: disable=too-many-instance-attributes
 
         if root.is_file():
             self._add_module(
-                self._disable,
+                self._messages,
                 root=root,
                 ignore_args=self._ignore_args,
                 ignore_kwargs=self._ignore_kwargs,
-                check_class_constructor=self.check_class_constructor,
+                check_class_constructor=self._check_class_constructor,
             )
 
         if root.is_dir():

{docsig-0.51.0 → docsig-0.52.0}/docsig/_report.py

@@ -7,13 +7,14 @@ from __future__ import annotations as _
 
 import typing as _t
 
-from ._message import Message as _Message
 from ._module import Function as _Function
 from ._stub import RETURN as _RETURN
 from ._stub import Param as _Param
 from ._utils import almost_equal as _almost_equal
 from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E
+from .messages import Message as _Message
+from .messages import Messages as _Messages
 
 _MIN_MATCH = 0.8
 _MAX_MATCH = 1.0
@@ -31,8 +32,8 @@ class Report(_t.List[str]):
     def __init__(
         self,
         func: _Function,
-        targets: list[_Message],
-        disable: list[_Message],
+        targets: _Messages,
+        disable: _Messages,
         check_property_returns: bool,
     ) -> None:
         super().__init__()
@@ -44,7 +45,7 @@ class Report(_t.List[str]):
 
             self._disable.extend(errors)
 
-        self._errors: list[_Message] = []
+        self._errors = _Messages()
         self._func = func
         self._no_prop_return = func.isproperty and not check_property_returns
         self._no_returns = func.isinit or self._no_prop_return
@@ -172,18 +173,19 @@ class Report(_t.List[str]):
             self._add(_E[116])
 
     def _invalid_directive(self) -> None:
-        for directive in self._func.directives:
-            if not directive.isvalid:
-                err = _E[int(f"20{1 if directive.ismodule else 2}")]
-                self._add(err, directive=directive.kind)
+        for comment in self._func.comments:
+            if not comment.isvalid:
+                err = _E[int(f"20{1 if comment.ismodule else 2}")]
+                self._add(err, directive=comment.kind)
 
     def _invalid_directive_options(self) -> None:
-        for directive in self._func.directives:
-            if directive.rules.unknown:
-                err = _E[int(f"20{3 if directive.ismodule else 4}")]
-                for rule in directive.rules.unknown:
+        for comment in self._func.comments:
+            for rule in comment:
+                if not rule.isknown:
                     self._add(
-                        err, directive=directive.kind, option=rule.description
+                        _E[int(f"20{3 if comment.ismodule else 4}")],
+                        directive=comment.kind,
+                        option=rule.description,
                     )
 
     def get_report(self, prefix: str = "") -> str:

{docsig-0.51.0 → docsig-0.52.0}/docsig/_stub.py

@@ -249,6 +249,16 @@ class Signature(_Stub):
         """
         return self._rettype
 
+    def overload(self, rettype: str | None) -> None:
+        """Overload signature with a ret type.
+
+        :param rettype: Return type of overloaded signature.
+        """
+        self._rettype = (
+            rettype if isinstance(rettype, str) else self._get_rettype(rettype)
+        )
+        self._returns = str(rettype) != "None"
+
 
 class Docstring(_Stub):
     """Represents a function docstring.

{docsig-0.51.0 → docsig-0.52.0}/docsig/_utils.py

@@ -11,6 +11,9 @@ from difflib import SequenceMatcher as _SequenceMatcher
 
 import click as _click
 
+from .messages import TEMPLATE as _TEMPLATE
+from .messages import E as _E
+
 
 def almost_equal(str1: str, str2: str, mini: float, maxi: float) -> bool:
     """Show result for more than the minimum but less than the maximum.
@@ -49,3 +52,9 @@ def pretty_print_error(
         file=_sys.stderr,
         color=not no_ansi and _sys.stderr.isatty(),
     )
+
+
+def print_checks() -> None:
+    """Print all available checks."""
+    for msg in _E.values():
+        _click.echo(msg.fstring(_TEMPLATE))

{docsig-0.51.0 → docsig-0.52.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.51.0"
+__version__ = "0.52.0"

{docsig-0.51.0 → docsig-0.52.0}/docsig/messages.py

@@ -23,116 +23,196 @@ docsig.messages
 | E204: unknown inline comment option for {directive} '{option}'
 """
 
-from ._message import Message as _Message
-from ._message import Messages as _Messages
+from __future__ import annotations
 
+import typing as _t
+
+#: Error code for unknown errors.
+UNKNOWN = "E000"
+
+#: Default template to format message strings.
 TEMPLATE = "{code}: {description} ({symbolic})"
 
 
+class Message(_t.NamedTuple):
+    """Represents an error message."""
+
+    #: An error code the message can be referenced by.
+    code: str
+
+    #: A description of the error.
+    description: str
+
+    #: A shortened description the message can be referenced by.
+    symbolic: str = ""
+
+    #: A hint, if any, suggesting why the error may have occurred.
+    hint: _t.Optional[str] = None
+
+    @property
+    def isknown(self) -> bool:
+        """Whether this is a known error.
+
+        This might exist due to a typo or an attempt to retrieve an
+        error that does not exist.
+        """
+        return self.code != UNKNOWN
+
+    def fstring(self, template: str) -> str:
+        """Return message values as a string.
+
+        :param template: String to interpolate values.
+        :return: Formatted string.
+        """
+        return template.format(
+            code=self.code,
+            description=self.description,
+            symbolic=self.symbolic,
+        )
+
+
+class Messages(_t.List[Message]):
+    """List of messages."""
+
+
+class MessageMap(_t.Dict[int, Message]):
+    """Messages mapped under an integer version of their codes.."""
+
+    def from_ref(self, ref: str) -> Message:
+        """Get a message by its code or symbolic reference.
+
+        :param ref: Code or symbolic reference.
+        :return: Message if valid ref else an unknown message type.
+        """
+        for value in self.values():
+            if ref in (value.code, value.symbolic):
+                return value
+
+        return Message(UNKNOWN, ref)
+
+    def from_codes(self, refs: list[str]) -> Messages:
+        """Get list of message types from codes or symbolic references.
+
+        :param refs: List of codes or symbolic references.
+        :return: List of message types.
+        """
+        return Messages(self.from_ref(i) for i in refs)
+
+    def all(self, category: int) -> Messages:
+        """Get all messages belonging to a category.
+
+        :param category: Index of message category.
+        :return: List of all message objects belonging to category.
+        """
+        return Messages(
+            v for k, v in self.items() if str(k).startswith(str(category))
+        )
+
+
 # Exxx: Error
-E = _Messages(
+E = MessageMap(
     {
         # E1xx: Docstring
-        101: _Message(
+        101: Message(
             "E101",
             "parameters out of order",
             "params-out-of-order",
         ),
-        102: _Message(
+        102: Message(
             "E102",
             "includes parameters that do not exist",
             "params-do-not-exist",
         ),
-        103: _Message(
+        103: Message(
             "E103",
             "parameters missing",
             "params-missing",
         ),
-        104: _Message(
+        104: Message(
             "E104",
             "return statement documented for None",
             "return-documented-for-none",
         ),
-        105: _Message(
+        105: Message(
             "E105",
             "return missing from docstring",
             "return-missing",
             "it is possible a syntax error could be causing this",
         ),
-        106: _Message(
+        106: Message(
             "E106",
             "duplicate parameters found",
             "duplicate-params-found",
         ),
-        107: _Message(
+        107: Message(
             "E107",
             "parameter appears to be incorrectly documented",
             "param-incorrectly-documented",
         ),
-        108: _Message(
+        108: Message(
             "E108",
             "return statement documented for property",
             "return-documented-for-property",
             "documentation is sufficient as a getter is the value returned",
         ),
-        109: _Message(
+        109: Message(
             "E109",
             "cannot determine whether a return statement should exist or not",
             "confirm-return-needed",
         ),
-        110: _Message(
+        110: Message(
             "E110",
             "documented parameter not equal to its respective argument",
             "param-not-equal-to-arg",
         ),
-        111: _Message(
+        111: Message(
             "E111",
             "return statement documented for class",
             "class-return-documented",
             "a class does not return a value during instantiation",
         ),
-        112: _Message(
+        112: Message(
             "E112",
             "spelling error found in documented parameter",
             "spelling-error",
         ),
-        113: _Message(
+        113: Message(
             "E113",
             "function is missing a docstring",
             "function-doc-missing",
         ),
-        114: _Message(
+        114: Message(
             "E114",
             "class is missing a docstring",
             "class-doc-missing",
         ),
-        115: _Message(
+        115: Message(
             "E115",
             "syntax error in description",
             "syntax-error-in-description",
         ),
-        116: _Message(
+        116: Message(
             "E116",
             "param not indented correctly",
             "incorrect-indent",
         ),
         # E2xx: Config
-        201: _Message(
+        201: Message(
             "E201",
             "unknown module comment directive '{directive}'",
             "unknown-module-directive",
         ),
-        202: _Message(
+        202: Message(
             "E202",
             "unknown inline comment directive '{directive}'",
             "unknown-inline-directive",
         ),
-        203: _Message(
+        203: Message(
             "E203",
             "unknown module comment option for {directive} '{option}'",
             "unknown-module-directive-option",
         ),
-        204: _Message(
+        204: Message(
             "E204",
             "unknown inline comment option for {directive} '{option}'",
             "unknown-inline-directive-option",

{docsig-0.51.0 → docsig-0.52.0}/pyproject.toml

@@ -63,7 +63,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.51.0"
+version = "0.52.0"
 
 [tool.poetry.dependencies]
 Pygments = "^2.13.0"
@@ -96,7 +96,6 @@ audit = [
   "about-tests",
   "commit-policy",
   "copyright-year",
-  "docs",
   "files",
   "format",
   "format-docs",

docsig-0.51.0/docsig/_directives.py

@@ -1,159 +0,0 @@
-"""
-docsig._disable
-===============
-"""
-
-from __future__ import annotations as _
-
-import re as _re
-import tokenize as _tokenize
-import typing as _t
-from io import StringIO as _StringIO
-
-from ._message import Message as _Message
-from .messages import E as _E
-
-
-class _Rules(_t.List[_Message]):
-    def __init__(self, kind: str) -> None:
-        super().__init__()
-        self._unknown = []
-        self._kind = kind
-        delimiter = _re.search(r"\W+", kind)
-        if delimiter and delimiter[0] == "=":
-            self._kind, option = kind.split("=")
-            message = _E.fromref(option)
-            if "," in option:
-                values = option.split(",")
-                for value in values:
-                    message = _E.fromref(value)
-                    if message.isknown:
-                        self.append(message)
-                    else:
-                        self._unknown.append(message)
-            elif message.isknown:
-                self.append(message)
-            else:
-                self._unknown.append(message)
-        else:
-            self.extend(_E.all(1))
-
-    @property
-    def kind(self) -> str:
-        """The type of the directive these rules belong to."""
-        return self._kind
-
-    @property
-    def unknown(self) -> list[_Message]:
-        """List of unknown directive options if any."""
-        return self._unknown
-
-
-class Directive:
-    """Represents a comment directive.
-
-    :param kind: The type of this directive.
-    :param col: The column this directive is positioned at.
-    """
-
-    _valid_kinds = "enable", "disable"
-
-    def __init__(self, kind: str, col: int) -> None:
-        self._ismodule = col == 0
-        self._rules = _Rules(kind)
-        self._kind = self._rules.kind
-
-    @property
-    def kind(self) -> str:
-        """The type of this directive."""
-        return self._kind
-
-    @property
-    def isvalid(self) -> bool:
-        """Whether this directive is valid or not."""
-        return self._kind in self._valid_kinds
-
-    @property
-    def rules(self) -> _Rules:
-        """The rules, if any, associated with this directive."""
-        return self._rules
-
-    @property
-    def ismodule(self) -> bool:
-        """Whether this is a module level directive or not."""
-        return self._ismodule
-
-    @property
-    def enable(self) -> bool:
-        """Whether this is a enable directive or not."""
-        return self._kind == self._valid_kinds[0]
-
-    @property
-    def disable(self) -> bool:
-        """Whether this is a disable directive or not."""
-        return self._kind == self._valid_kinds[1]
-
-    @classmethod
-    def parse(cls, comment: str, col: int) -> Directive | None:
-        """Parse string into directive object if possible.
-
-        :param comment: Comment to parse.
-        :param col: Column of comment to instantiate directive.
-        :return: Instantiated directive object if valid directive or
-            None if not a valid directive.
-        """
-        if comment[1:].strip().startswith(f"{__package__}:"):
-            return cls(comment.split(":")[1].strip(), col)
-
-        return None
-
-
-class Directives(
-    _t.Dict[int, _t.Tuple[_t.List[Directive], _t.List[_Message]]]
-):
-    """Data for directives:
-
-    Dict like object with the line number of directive as the key and
-    total errors which are excluded from function checks.
-
-    :param text: Python code.
-    :param disable: List of checks to disable.
-    """
-
-    def __init__(self, text: str, disable: list[_Message]) -> None:
-        super().__init__()
-        fin = _StringIO(text)
-        module_disables = list(disable)
-        module_directives: list[Directive] = []
-        directive = None
-        for line in _tokenize.generate_tokens(fin.readline):
-            if line.type in (_tokenize.NAME, _tokenize.OP, _tokenize.DEDENT):
-                continue
-
-            lineno, col = line.start
-            if line.type == _tokenize.COMMENT:
-                # ensure previous directive as backup assignment because
-                # if this is just a regular comment it will override a
-                # valid module directive, making it None
-                directive = Directive.parse(line.string, col) or directive
-                if directive is not None:
-                    update_directives = [directive] + module_directives
-                    update = module_disables
-                    if directive.isvalid:
-                        if directive.disable:
-                            update = directive.rules + module_disables
-                        elif directive.enable:
-                            update = [
-                                i
-                                for i in module_disables
-                                if i not in directive.rules
-                            ]
-
-                    if directive.ismodule:
-                        module_disables = update
-                        module_directives = update_directives
-                    else:
-                        self[lineno] = update_directives, update
-
-            if lineno not in self:
-                self[lineno] = list(module_directives), list(module_disables)

docsig-0.51.0/docsig/_message.py

@@ -1,70 +0,0 @@
-"""
-docsig._message
-===============
-"""
-
-from __future__ import annotations as _
-
-import typing as _t
-
-UNKNOWN = "E000"
-
-
-class Message(_t.NamedTuple):
-    """Message type for errors."""
-
-    code: str
-    description: str
-    symbolic: str = ""
-    hint: _t.Optional[str] = None
-
-    @property
-    def isknown(self) -> bool:
-        """Whether this is a known error."""
-        return self.code != UNKNOWN
-
-    def fstring(self, template: str) -> str:
-        """Return values as a format string.
-
-        :param template: String to interpolate values.
-        :return: Formatted string.
-        """
-        return template.format(
-            code=self.code,
-            description=self.description,
-            symbolic=self.symbolic,
-        )
-
-
-class Messages(_t.Dict[int, Message]):
-    """Object for storing and retrieving message objects."""
-
-    def fromref(self, ref: str) -> Message:
-        """Get a message by its code or symbolic reference.
-
-        :param ref: Code or symbolic reference.
-        :return: Message if valid ref else an unknown message type.
-        """
-        for value in self.values():
-            if ref in (value.code, value.symbolic):
-                return value
-
-        return Message(UNKNOWN, ref)
-
-    def fromcodes(self, refs: list[str]) -> tuple[Message, ...]:
-        """Get tuple of message types from codes or symbolic references.
-
-        :param refs: Tuple of codes or symbolic references.
-        :return: Tuple of message types.
-        """
-        return tuple(self.fromref(i) for i in refs)
-
-    def all(self, category: int) -> tuple[Message, ...]:
-        """Get all messages belonging to a category.
-
-        :param category: Index of message category.
-        :return: Tuple of all message objects belonging to category.
-        """
-        return tuple(
-            v for k, v in self.items() if str(k).startswith(str(category))
-        )