docsig 0.44.2__tar.gz → 0.45.0__tar.gz

{docsig-0.44.2 → docsig-0.45.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Stephen Whitlock
+Copyright (c) 2024 Stephen Whitlock
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docsig-0.45.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.1
+Name: docsig
+Version: 0.45.0
+Summary: Check signature params for proper documentation
+Home-page: https://pypi.org/project/docsig/
+License: MIT
+Keywords: check,docs,docstring,params,signature
+Author: jshwi
+Author-email: stephen@jshwisolutions.com
+Maintainer: jshwi
+Maintainer-email: stephen@jshwisolutions.com
+Requires-Python: >=3.8,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: Pygments (>=2.13.0,<3.0.0)
+Requires-Dist: Sphinx (>=7.0.0,<8.0.0)
+Requires-Dist: arcon (>=0.3.1)
+Requires-Dist: astroid (>=3.0.1,<4.0.0)
+Requires-Dist: object-colors (>=2.1.0,<3.0.0)
+Requires-Dist: typing-extensions (>=4.8.0,<5.0.0)
+Project-URL: Documentation, https://docsig.readthedocs.io/en/latest
+Project-URL: Repository, https://github.com/jshwi/docsig
+Description-Content-Type: text/x-rst
+
+|
+
+.. image:: https://raw.githubusercontent.com/jshwi/docsig/master/docs/static/docsig.svg
+   :alt: docsig logo
+   :width: 50%
+   :align: center
+
+|
+
+.. 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
+   :target: https://pypi.org/project/docsig/
+   :alt: PyPI
+.. 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
+   :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
+   :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
+   :target: https://codecov.io/gh/jshwi/docsig
+   :alt: codecov.io
+.. 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
+   :target: https://www.python.org/downloads/release/python-380
+   :alt: python3.8
+.. 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
+   :target: https://pycqa.github.io/isort/
+   :alt: isort
+.. 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
+   :target: https://github.com/PyCQA/pylint
+   :alt: pylint
+.. 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
+   :target: https://snyk.io/test/github/jshwi/docsig/badge.svg
+   :alt: Known Vulnerabilities
+.. image:: https://snyk.io/advisor/python/docsig/badge.svg
+   :target: https://snyk.io/advisor/python/docsig
+   :alt: docsig
+
+Check signature params for proper documentation
+-----------------------------------------------
+
+Supports reStructuredText (``Sphinx``), ``NumPy``, and ``Google``
+
+Contributing
+------------
+If you are interested in contributing to ``docsig`` please read about contributing `here <https://github.com/jshwi/docsig/blob/master/CONTRIBUTING.md>`__
+
+Installation
+------------
+
+.. code-block:: console
+
+    $ pip install docsig
+
+Usage
+-----
+
+Commandline
+***********
+
+.. code-block:: console
+
+    usage: docsig [-h] [-v] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
+                             [-n] [-S] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
+                             [path [path ...]]
+
+    Check signature params for proper documentation
+
+    positional arguments:
+      path                                 directories or files to check
+
+    optional arguments:
+      -h, --help                           show this help message and exit
+      -v, --version                        show program's version number and exit
+      -l, --list-checks                    display a list of all checks and their messages
+      -c, --check-class                    check class docstrings
+      -C, --check-class-constructor        check __init__ methods. Note: mutually
+                                           incompatible with -c
+      -D, --check-dunders                  check dunder methods
+      -m, --check-protected-class-methods  check public methods belonging to protected
+                                           classes
+      -o, --check-overridden               check overridden methods
+      -p, --check-protected                check protected functions and classes
+      -P, --check-property-returns         check property return values
+      -i, --ignore-no-params               ignore docstrings where parameters are not
+                                           documented
+      -a, --ignore-args                    ignore args prefixed with an asterisk
+      -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
+      -n, --no-ansi                        disable ansi output
+      -S, --summary                        print a summarised report
+      -s STR, --string STR                 string to parse instead of files
+      -d LIST, --disable LIST              comma separated list of rules to disable
+      -t LIST, --target LIST               comma separated list of rules to target
+      -e EXCLUDE, --exclude EXCLUDE        regular expression of files or dirs to exclude
+                                           from checks
+
+Options can also be configured with the pyproject.toml file
+
+If you find the output is too verbose then the report can be configured to display a summary
+
+.. code-block:: toml
+
+    [tool.docsig]
+    check-dunders = false
+    check-overridden = false
+    check-protected = false
+    summary = true
+    disable = [
+        "E101",
+        "E102",
+        "E103",
+    ]
+    target = [
+        "E102",
+        "E103",
+        "E104",
+    ]
+
+API
+***
+
+.. code-block:: python
+
+    >>> from docsig import docsig
+
+.. code-block:: python
+
+    >>> string = """
+    ... def function(param1, param2, param3) -> None:
+    ...     '''
+    ...
+    ...     :param param1: About param1.
+    ...     :param param2: About param2.
+    ...     :param param3: About param3.
+    ...     '''
+    ...     """
+    >>> docsig(string=string)
+    0
+
+.. code-block:: python
+
+    >>> string = """
+    ... def function(param1, param2) -> None:
+    ...     '''
+    ...
+    ...     :param param1: About param1.
+    ...     :param param2: About param2.
+    ...     :param param3: About param3.
+    ...     '''
+    ... """
+    >>> docsig(string=string)
+    2
+    -
+    def function(✓param1, ✓param2, ✖None) -> ✓None:
+        """
+        :param param1: ✓
+        :param param2: ✓
+        :param param3: ✖
+        """
+    <BLANKLINE>
+    E102: includes parameters that do not exist (params-do-not-exist)
+    <BLANKLINE>
+    1
+
+A full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/docsig.html#docsig-messages>`__
+
+Message Control
+***************
+
+`Documentation on message control <https://github.com/jshwi/docsig/blob/master/docs/examples/message-control.rst>`_
+
+Classes
+*******
+
+`Documenting classes <https://github.com/jshwi/docsig/blob/master/docs/examples/classes.rst>`_
+
+pre-commit
+**********
+
+``docsig`` can be used as a `pre-commit <https://pre-commit.com>`_ hook
+
+It can be added to your .pre-commit-config.yaml as follows:
+
+.. code-block:: yaml
+
+    repos:
+      - repo: https://github.com/jshwi/docsig
+        rev: v0.45.0
+        hooks:
+          - id: docsig
+            args:
+              - "--check-class"
+              - "--check-dunders"
+              - "--check-overridden"
+              - "--check-protected"
+              - "--summary"
+

docsig-0.45.0/README.rst

@@ -0,0 +1,213 @@
+|
+
+.. image:: https://raw.githubusercontent.com/jshwi/docsig/master/docs/static/docsig.svg
+   :alt: docsig logo
+   :width: 50%
+   :align: center
+
+|
+
+.. 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
+   :target: https://pypi.org/project/docsig/
+   :alt: PyPI
+.. 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
+   :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
+   :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
+   :target: https://codecov.io/gh/jshwi/docsig
+   :alt: codecov.io
+.. 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
+   :target: https://www.python.org/downloads/release/python-380
+   :alt: python3.8
+.. 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
+   :target: https://pycqa.github.io/isort/
+   :alt: isort
+.. 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
+   :target: https://github.com/PyCQA/pylint
+   :alt: pylint
+.. 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
+   :target: https://snyk.io/test/github/jshwi/docsig/badge.svg
+   :alt: Known Vulnerabilities
+.. image:: https://snyk.io/advisor/python/docsig/badge.svg
+   :target: https://snyk.io/advisor/python/docsig
+   :alt: docsig
+
+Check signature params for proper documentation
+-----------------------------------------------
+
+Supports reStructuredText (``Sphinx``), ``NumPy``, and ``Google``
+
+Contributing
+------------
+If you are interested in contributing to ``docsig`` please read about contributing `here <https://github.com/jshwi/docsig/blob/master/CONTRIBUTING.md>`__
+
+Installation
+------------
+
+.. code-block:: console
+
+    $ pip install docsig
+
+Usage
+-----
+
+Commandline
+***********
+
+.. code-block:: console
+
+    usage: docsig [-h] [-v] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
+                             [-n] [-S] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
+                             [path [path ...]]
+
+    Check signature params for proper documentation
+
+    positional arguments:
+      path                                 directories or files to check
+
+    optional arguments:
+      -h, --help                           show this help message and exit
+      -v, --version                        show program's version number and exit
+      -l, --list-checks                    display a list of all checks and their messages
+      -c, --check-class                    check class docstrings
+      -C, --check-class-constructor        check __init__ methods. Note: mutually
+                                           incompatible with -c
+      -D, --check-dunders                  check dunder methods
+      -m, --check-protected-class-methods  check public methods belonging to protected
+                                           classes
+      -o, --check-overridden               check overridden methods
+      -p, --check-protected                check protected functions and classes
+      -P, --check-property-returns         check property return values
+      -i, --ignore-no-params               ignore docstrings where parameters are not
+                                           documented
+      -a, --ignore-args                    ignore args prefixed with an asterisk
+      -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
+      -n, --no-ansi                        disable ansi output
+      -S, --summary                        print a summarised report
+      -s STR, --string STR                 string to parse instead of files
+      -d LIST, --disable LIST              comma separated list of rules to disable
+      -t LIST, --target LIST               comma separated list of rules to target
+      -e EXCLUDE, --exclude EXCLUDE        regular expression of files or dirs to exclude
+                                           from checks
+
+Options can also be configured with the pyproject.toml file
+
+If you find the output is too verbose then the report can be configured to display a summary
+
+.. code-block:: toml
+
+    [tool.docsig]
+    check-dunders = false
+    check-overridden = false
+    check-protected = false
+    summary = true
+    disable = [
+        "E101",
+        "E102",
+        "E103",
+    ]
+    target = [
+        "E102",
+        "E103",
+        "E104",
+    ]
+
+API
+***
+
+.. code-block:: python
+
+    >>> from docsig import docsig
+
+.. code-block:: python
+
+    >>> string = """
+    ... def function(param1, param2, param3) -> None:
+    ...     '''
+    ...
+    ...     :param param1: About param1.
+    ...     :param param2: About param2.
+    ...     :param param3: About param3.
+    ...     '''
+    ...     """
+    >>> docsig(string=string)
+    0
+
+.. code-block:: python
+
+    >>> string = """
+    ... def function(param1, param2) -> None:
+    ...     '''
+    ...
+    ...     :param param1: About param1.
+    ...     :param param2: About param2.
+    ...     :param param3: About param3.
+    ...     '''
+    ... """
+    >>> docsig(string=string)
+    2
+    -
+    def function(✓param1, ✓param2, ✖None) -> ✓None:
+        """
+        :param param1: ✓
+        :param param2: ✓
+        :param param3: ✖
+        """
+    <BLANKLINE>
+    E102: includes parameters that do not exist (params-do-not-exist)
+    <BLANKLINE>
+    1
+
+A full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/docsig.html#docsig-messages>`__
+
+Message Control
+***************
+
+`Documentation on message control <https://github.com/jshwi/docsig/blob/master/docs/examples/message-control.rst>`_
+
+Classes
+*******
+
+`Documenting classes <https://github.com/jshwi/docsig/blob/master/docs/examples/classes.rst>`_
+
+pre-commit
+**********
+
+``docsig`` can be used as a `pre-commit <https://pre-commit.com>`_ hook
+
+It can be added to your .pre-commit-config.yaml as follows:
+
+.. code-block:: yaml
+
+    repos:
+      - repo: https://github.com/jshwi/docsig
+        rev: v0.45.0
+        hooks:
+          - id: docsig
+            args:
+              - "--check-class"
+              - "--check-dunders"
+              - "--check-overridden"
+              - "--check-protected"
+              - "--summary"

{docsig-0.44.2 → docsig-0.45.0}/docsig/__init__.py

@@ -1,4 +1,5 @@
 """Check signature params for proper documentation."""
+
 from . import messages
 from ._core import docsig
 from ._main import main

{docsig-0.44.2 → docsig-0.45.0}/docsig/__main__.py

@@ -4,6 +4,7 @@ docsig.__main__
 
 Module entry point.
 """
+
 import sys as _sys
 
 from docsig import main

{docsig-0.44.2 → docsig-0.45.0}/docsig/_config.py

@@ -2,6 +2,7 @@
 docsig._config
 ==============
 """
+
 from argparse import HelpFormatter as _HelpFormatter
 from pathlib import Path as _Path
 
@@ -132,3 +133,8 @@ class Parser(_ArgumentParser):
             metavar="LIST",
             help="comma separated list of rules to target",
         )
+        self.add_argument(
+            "-e",
+            "--exclude",
+            help="regular expression of files or dirs to exclude from checks",
+        )

{docsig-0.44.2 → docsig-0.45.0}/docsig/_core.py

@@ -2,6 +2,7 @@
 docsig._core
 ============
 """
+
 from __future__ import annotations as _
 
 from pathlib import Path as _Path
@@ -18,6 +19,25 @@ from ._report import generate_report as _generate_report
 from .messages import TEMPLATE as _TEMPLATE
 from .messages import E as _E
 
+_DEFAULT_EXCLUDES = """\
+(?x)^(
+  |\\.?venv
+  |\\.git
+  |\\.hg
+  |\\.idea
+  |\\.mypy_cache
+  |\\.nox
+  |\\.pytest_cache
+  |\\.svn
+  |\\.tox
+  |\\.vscode
+  |_?build
+  |__pycache__
+  |dist
+  |node_modules
+)$
+"""
+
 
 def _print_checks() -> None:
     for msg in _E.values():
@@ -81,6 +101,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     summary: bool = False,
     targets: list[_Message] | None = None,
     disable: list[_Message] | None = None,
+    exclude: str | None = None,
 ) -> int:
     """Package's core functionality.
 
@@ -111,15 +132,22 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     :param summary: Print a summarised report.
     :param targets: List of errors to target.
     :param disable: List of errors to disable.
+    :param exclude: Regular expression of files and dirs to exclude from
+        checks.
     :return: Exit status for whether test failed or not.
     """
     if list_checks:
         return int(bool(_print_checks()))  # type: ignore
 
+    excludes = [_DEFAULT_EXCLUDES]
+    if exclude is not None:
+        excludes.append(exclude)
+
     modules = _Modules(
         *tuple(_Path(i) for i in path),
         disable=disable or [],
         string=string,
+        excludes=excludes,
         ignore_args=ignore_args,
         ignore_kwargs=ignore_kwargs,
         check_class_constructor=check_class_constructor,

{docsig-0.44.2 → docsig-0.45.0}/docsig/_decorators.py

@@ -2,6 +2,7 @@
 docsig._decorators
 ==================
 """
+
 from __future__ import annotations as _
 
 import functools as _functools

{docsig-0.44.2 → docsig-0.45.0}/docsig/_directives.py

@@ -2,6 +2,7 @@
 docsig._disable
 ===============
 """
+
 from __future__ import annotations as _
 
 import re as _re

{docsig-0.44.2 → docsig-0.45.0}/docsig/_display.py

@@ -2,6 +2,7 @@
 docsig._display
 ===============
 """
+
 from __future__ import annotations as _
 
 import typing as _t

{docsig-0.44.2 → docsig-0.45.0}/docsig/_function.py

@@ -2,6 +2,7 @@
 docsig._function
 ================
 """
+
 from __future__ import annotations as _
 
 import re as _re
@@ -318,7 +319,9 @@ class Function:  # pylint: disable=too-many-arguments
     def _decorated_with(self, name: str) -> bool:
         if self._node.decorators is not None:
             for dec in self._node.decorators.nodes:
-                return isinstance(dec, _ast.Name) and dec.name == name
+                return (isinstance(dec, _ast.Name) and dec.name == name) or (
+                    isinstance(dec, _ast.Attribute) and dec.attrname == name
+                )
 
         return False
 
@@ -330,7 +333,13 @@ class Function:  # pylint: disable=too-many-arguments
     @property
     def isproperty(self) -> bool:
         """Boolean value for whether function is a property."""
-        return self.ismethod and self._decorated_with("property")
+        valid_properties = [
+            "property",
+            "cached_property",
+        ]
+        return self.ismethod and any(
+            self._decorated_with(i) for i in valid_properties
+        )
 
     @property
     def isoverloaded(self) -> bool:

{docsig-0.44.2 → docsig-0.45.0}/docsig/_hooks.py

@@ -2,6 +2,7 @@
 docsig._hooks
 =============
 """
+
 import sys as _sys
 from os import environ as _e
 

{docsig-0.44.2 → docsig-0.45.0}/docsig/_main.py

@@ -4,6 +4,7 @@ docsig._main
 
 Contains package entry point.
 """
+
 from __future__ import annotations as _
 
 from ._config import Parser as _Parser
@@ -40,4 +41,5 @@ def main() -> str | int:
         summary=parser.args.summary,
         targets=parser.args.target,
         disable=parser.args.disable,
+        exclude=parser.args.exclude,
     )

{docsig-0.44.2 → docsig-0.45.0}/docsig/_message.py

@@ -2,6 +2,7 @@
 docsig._message
 ===============
 """
+
 from __future__ import annotations as _
 
 import typing as _t