docsig 0.44.1__tar.gz → 0.44.3__tar.gz

{docsig-0.44.1 → docsig-0.44.3}/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.44.3/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.1
+Name: docsig
+Version: 0.44.3
+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,<0.4.0)
+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]
+                             [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
+
+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.44.3
+        hooks:
+          - id: docsig
+            args:
+              - "--check-class"
+              - "--check-dunders"
+              - "--check-overridden"
+              - "--check-protected"
+              - "--summary"
+

docsig-0.44.3/README.rst

@@ -0,0 +1,211 @@
+|
+
+.. 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]
+                             [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
+
+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.44.3
+        hooks:
+          - id: docsig
+            args:
+              - "--check-class"
+              - "--check-dunders"
+              - "--check-overridden"
+              - "--check-protected"
+              - "--summary"

{docsig-0.44.1 → docsig-0.44.3}/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.1 → docsig-0.44.3}/docsig/__main__.py

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

{docsig-0.44.1 → docsig-0.44.3}/docsig/_config.py

@@ -2,6 +2,7 @@
 docsig._config
 ==============
 """
+
 from argparse import HelpFormatter as _HelpFormatter
 from pathlib import Path as _Path
 

{docsig-0.44.1 → docsig-0.44.3}/docsig/_core.py

@@ -2,6 +2,7 @@
 docsig._core
 ============
 """
+
 from __future__ import annotations as _
 
 from pathlib import Path as _Path

{docsig-0.44.1 → docsig-0.44.3}/docsig/_decorators.py

@@ -2,8 +2,10 @@
 docsig._decorators
 ==================
 """
+
 from __future__ import annotations as _
 
+import functools as _functools
 import sys as _sys
 import typing as _t
 from pathlib import Path as _Path
@@ -21,6 +23,7 @@ def parse_msgs(func: _WrappedFuncType) -> _WrappedFuncType:
     :return: Wrapped function.
     """
 
+    @_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
@@ -38,6 +41,7 @@ def validate_args(func: _FuncType) -> _WrappedFuncType:
     :return: Wrapped function.
     """
 
+    @_functools.wraps(func)
     def _wrapper(*args: str | _Path, **kwargs: _t.Any) -> str | int:
         stderr = []
         if not kwargs.get("list_checks", False):

{docsig-0.44.1 → docsig-0.44.3}/docsig/_directives.py

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

{docsig-0.44.1 → docsig-0.44.3}/docsig/_display.py

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

{docsig-0.44.1 → docsig-0.44.3}/docsig/_function.py

@@ -2,6 +2,7 @@
 docsig._function
 ================
 """
+
 from __future__ import annotations as _
 
 import re as _re
@@ -330,7 +331,18 @@ 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",
+            # todo: this should be inferred as various import styles or
+            # todo: aliases won't be recognised
+            # todo:
+            # todo: it appears overloaded is inferred, if it isn't, look
+            # todo: at that too
+            "cached_property",
+        ]
+        return self.ismethod and any(
+            self._decorated_with(i) for i in valid_properties
+        )
 
     @property
     def isoverloaded(self) -> bool:

{docsig-0.44.1 → docsig-0.44.3}/docsig/_hooks.py

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

{docsig-0.44.1 → docsig-0.44.3}/docsig/_main.py

@@ -4,6 +4,7 @@ docsig._main
 
 Contains package entry point.
 """
+
 from __future__ import annotations as _
 
 from ._config import Parser as _Parser

{docsig-0.44.1 → docsig-0.44.3}/docsig/_message.py

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

{docsig-0.44.1 → docsig-0.44.3}/docsig/_module.py

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

{docsig-0.44.1 → docsig-0.44.3}/docsig/_report.py

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

{docsig-0.44.1 → docsig-0.44.3}/docsig/_utils.py

@@ -2,6 +2,7 @@
 docsig._utils
 =============
 """
+
 from __future__ import annotations as _
 
 from difflib import SequenceMatcher as _SequenceMatcher

{docsig-0.44.1 → docsig-0.44.3}/docsig/_version.py

@@ -7,4 +7,5 @@ Contains the version of this package.
 Allows for access to the version internally without cyclic imports
 caused by accessing it through __init__.
 """
-__version__ = "0.44.1"
+
+__version__ = "0.44.3"

{docsig-0.44.1 → docsig-0.44.3}/docsig/messages.py

@@ -22,6 +22,7 @@ docsig.messages
 | E203: unknown module comment option for {directive} '{option}'
 | E204: unknown inline comment option for {directive} '{option}'
 """
+
 from ._message import Message as _Message
 from ._message import Messages as _Messages
 

{docsig-0.44.1 → docsig-0.44.3}/pyproject.toml

@@ -72,7 +72,7 @@ maintainers = [
 name = "docsig"
 readme = "README.rst"
 repository = "https://github.com/jshwi/docsig"
-version = "0.44.1"
+version = "0.44.3"
 
 [tool.poetry.dependencies]
 Pygments = "^2.13.0"
@@ -85,13 +85,12 @@ typing-extensions = "^4.8.0"
 
 [tool.poetry.dev-dependencies]
 bump2version = "^1.0.1"
-deptry = "^0.12.0"
+deptry = "^0.14.2"
 ipython = "^8.12.0"
 pre-commit = "^3.3.3"
-pyaud = "^7.3.0"
-pytest = "^7.4.0"
+pyaud = "^7.5.0"
 pytest-randomly = "^3.13.0"
-pytest-sugar = "^0.9.6"
+pytest-sugar = "^1.0.0"
 pytest-xdist = "^3.5.0"
 restview = "^3.0.0"
 sphinx-immaterial = "^0.11.9"
@@ -106,6 +105,7 @@ audit = [
   "about-tests",
   "commit-policy",
   "const",
+  "copyright-year",
   "docs",
   "files",
   "format",