|
.. image:: https://raw.githubusercontent.com/jshwi/docsig/master/docs/static/docsig.svg
:alt: docsig logo
:width: 50%
:align: center
|
|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
.. |PyPI| image:: https://img.shields.io/pypi/v/docsig
:target: https://pypi.org/project/docsig/
:alt: PyPI
.. |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
.. |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
.. |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
.. |codecov.io| image:: https://codecov.io/gh/jshwi/docsig/branch/master/graph/badge.svg
:target: https://codecov.io/gh/jshwi/docsig
:alt: codecov.io
.. |readthedocs.org| image:: https://readthedocs.org/projects/docsig/badge/?version=latest
:target: https://docsig.readthedocs.io/en/latest/?badge=latest
:alt: readthedocs.org
.. |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
.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Black
.. |isort| image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
:target: https://pycqa.github.io/isort/
:alt: isort
.. |docformatter| image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg
:target: https://github.com/PyCQA/docformatter
:alt: docformatter
.. |pylint| image:: https://img.shields.io/badge/linting-pylint-yellowgreen
:target: https://github.com/PyCQA/pylint
:alt: pylint
.. |Security Status| image:: https://img.shields.io/badge/security-bandit-yellow.svg
:target: https://github.com/PyCQA/bandit
:alt: Security Status
.. |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
.. |docsig| 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://docsig.readthedocs.io/en/latest/development/contributing.html>`__
Installation
------------
.. code-block:: console
$ pip install docsig
Usage
-----
Commandline
***********
.. code-block:: console
usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a] [-k] [-T]
[-I] [-n] [-v] [-s STR] [-d LIST] [-t LIST] [-e PATTERN] [-E PATH [PATH ...]]
[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
-N, --check-nested check nested functions and 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
-T, --ignore-typechecker
ignore checking return values
-I, --include-ignored
check files even if they match a gitignore pattern
-n, --no-ansi disable ansi output
-v, --verbose increase output verbosity
-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 PATTERN, --exclude PATTERN
regular expression of files or dirs to exclude from checks
-E PATH [PATH ...], --excludes PATH [PATH ...]
path glob patterns to exclude from checks
Options can also be configured with the pyproject.toml file
.. code-block:: toml
[tool.docsig]
check-dunders = false
check-overridden = false
check-protected = false
disable = [
"SIG101",
"SIG102",
"SIG402",
]
target = [
"SIG202",
"SIG203",
"SIG201",
]
Flake8
******
``docsig`` can also be used as a ``flake8`` plugin. Install ``flake8`` and
ensure your installation has registered `docsig`
.. code-block:: console
$ flake8 --version
7.1.0 (docsig: 0.66.0, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin
And now use `flake8` to lint your files
.. code-block:: console
$ flake8 example.py
example.py:1:1: SIG202 includes parameters that do not exist (params-do-not-exist) 'function'
With ``flake8`` the pyproject.toml config will still be the base config, though the
`ini files <https://flake8.pycqa.org/en/latest/user/configuration.html#configuration-locations>`_ ``flake8`` gets it config from will override the pyproject.toml config.
For ``flake8`` all args and config options are prefixed with ``sig`` to
avoid any potential conflicts with other plugins
.. code-block:: ini
[flake8]
sig-check-dunders = True
sig-check-overridden = True
sig-check-protected = True
..
end flake8
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, no_ansi=True)
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, no_ansi=True)
2 in function
SIG202: includes parameters that do not exist (params-do-not-exist)
1
A full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/usage/messages.html>`__
Message Control
***************
If you have been using ``docsig`` prior to ``v0.56.0``, please see
`updated messages <https://docsig.readthedocs.io/en/latest/deprecated/messages.html>`_
`Documentation on message control <https://docsig.readthedocs.io/en/latest/usage/message-control.html>`_
Classes
*******
`Documenting classes <https://docsig.readthedocs.io/en/latest/usage/configuration.html#classes>`_
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:
Standalone
.. code-block:: yaml
repos:
- repo: https://github.com/jshwi/docsig
rev: v0.66.0
hooks:
- id: docsig
args:
- "--check-class"
- "--check-dunders"
- "--check-overridden"
- "--check-protected"
or integrated with ``flake8``
.. code-block:: yaml
repos:
- repo: https://github.com/PyCQA/flake8
rev: "7.1.0"
hooks:
- id: flake8
additional_dependencies:
- docsig==0.66.0
args:
- "--sig-check-class"
- "--sig-check-dunders"
- "--sig-check-overridden"
- "--sig-check-protected"
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/docsig/",
"name": "docsig",
"maintainer": "jshwi",
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.1",
"maintainer_email": "stephen@jshwisolutions.com",
"keywords": "check, docs, docstring, params, signature",
"author": "jshwi",
"author_email": "stephen@jshwisolutions.com",
"download_url": "https://files.pythonhosted.org/packages/5b/ed/33614863211c470f0f14ae734589f82c768efc51cc1150d802d147cd1015/docsig-0.66.0.tar.gz",
"platform": null,
"description": "|\n\n.. image:: https://raw.githubusercontent.com/jshwi/docsig/master/docs/static/docsig.svg\n :alt: docsig logo\n :width: 50%\n :align: center\n\n|\n\n|License| |PyPI| |CI| |CodeQL| |pre-commit.ci status| |codecov.io| |readthedocs.org| |python3.8| |Black| |isort| |docformatter| |pylint| |Security Status| |Known Vulnerabilities| |docsig|\n\n.. |License| image:: https://img.shields.io/badge/License-MIT-yellow.svg\n :target: https://opensource.org/licenses/MIT\n :alt: License\n.. |PyPI| image:: https://img.shields.io/pypi/v/docsig\n :target: https://pypi.org/project/docsig/\n :alt: PyPI\n.. |CI| image:: https://github.com/jshwi/docsig/actions/workflows/build.yaml/badge.svg\n :target: https://github.com/jshwi/docsig/actions/workflows/build.yaml\n :alt: CI\n.. |CodeQL| image:: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml/badge.svg\n :target: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml\n :alt: CodeQL\n.. |pre-commit.ci status| image:: https://results.pre-commit.ci/badge/github/jshwi/docsig/master.svg\n :target: https://results.pre-commit.ci/latest/github/jshwi/docsig/master\n :alt: pre-commit.ci status\n.. |codecov.io| image:: https://codecov.io/gh/jshwi/docsig/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/jshwi/docsig\n :alt: codecov.io\n.. |readthedocs.org| image:: https://readthedocs.org/projects/docsig/badge/?version=latest\n :target: https://docsig.readthedocs.io/en/latest/?badge=latest\n :alt: readthedocs.org\n.. |python3.8| image:: https://img.shields.io/badge/python-3.8-blue.svg\n :target: https://www.python.org/downloads/release/python-380\n :alt: python3.8\n.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Black\n.. |isort| image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336\n :target: https://pycqa.github.io/isort/\n :alt: isort\n.. |docformatter| image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg\n :target: https://github.com/PyCQA/docformatter\n :alt: docformatter\n.. |pylint| image:: https://img.shields.io/badge/linting-pylint-yellowgreen\n :target: https://github.com/PyCQA/pylint\n :alt: pylint\n.. |Security Status| image:: https://img.shields.io/badge/security-bandit-yellow.svg\n :target: https://github.com/PyCQA/bandit\n :alt: Security Status\n.. |Known Vulnerabilities| image:: https://snyk.io/test/github/jshwi/docsig/badge.svg\n :target: https://snyk.io/test/github/jshwi/docsig/badge.svg\n :alt: Known Vulnerabilities\n.. |docsig| image:: https://snyk.io/advisor/python/docsig/badge.svg\n :target: https://snyk.io/advisor/python/docsig\n :alt: docsig\n\nCheck signature params for proper documentation\n-----------------------------------------------\n\nSupports reStructuredText (``Sphinx``), ``NumPy``, and ``Google``\n\nContributing\n------------\nIf you are interested in contributing to ``docsig`` please read about contributing `here <https://docsig.readthedocs.io/en/latest/development/contributing.html>`__\n\nInstallation\n------------\n\n.. code-block:: console\n\n $ pip install docsig\n\nUsage\n-----\n\nCommandline\n***********\n\n.. code-block:: console\n\n usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a] [-k] [-T]\n [-I] [-n] [-v] [-s STR] [-d LIST] [-t LIST] [-e PATTERN] [-E PATH [PATH ...]]\n [path [path ...]]\n\n Check signature params for proper documentation\n\n positional arguments:\n path directories or files to check\n\n optional arguments:\n -h, --help show this help message and exit\n -V, --version show program's version number and exit\n -l, --list-checks display a list of all checks and their messages\n -c, --check-class check class docstrings\n -C, --check-class-constructor\n check __init__ methods. Note: mutually incompatible with -c\n -D, --check-dunders check dunder methods\n -m, --check-protected-class-methods\n check public methods belonging to protected classes\n -N, --check-nested check nested functions and classes\n -o, --check-overridden\n check overridden methods\n -p, --check-protected\n check protected functions and classes\n -P, --check-property-returns\n check property return values\n -i, --ignore-no-params\n ignore docstrings where parameters are not documented\n -a, --ignore-args ignore args prefixed with an asterisk\n -k, --ignore-kwargs ignore kwargs prefixed with two asterisks\n -T, --ignore-typechecker\n ignore checking return values\n -I, --include-ignored\n check files even if they match a gitignore pattern\n -n, --no-ansi disable ansi output\n -v, --verbose increase output verbosity\n -s STR, --string STR string to parse instead of files\n -d LIST, --disable LIST\n comma separated list of rules to disable\n -t LIST, --target LIST\n comma separated list of rules to target\n -e PATTERN, --exclude PATTERN\n regular expression of files or dirs to exclude from checks\n -E PATH [PATH ...], --excludes PATH [PATH ...]\n path glob patterns to exclude from checks\n\nOptions can also be configured with the pyproject.toml file\n\n.. code-block:: toml\n\n [tool.docsig]\n check-dunders = false\n check-overridden = false\n check-protected = false\n disable = [\n \"SIG101\",\n \"SIG102\",\n \"SIG402\",\n ]\n target = [\n \"SIG202\",\n \"SIG203\",\n \"SIG201\",\n ]\n\nFlake8\n******\n\n``docsig`` can also be used as a ``flake8`` plugin. Install ``flake8`` and\nensure your installation has registered `docsig`\n\n.. code-block:: console\n\n $ flake8 --version\n 7.1.0 (docsig: 0.66.0, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin\n\nAnd now use `flake8` to lint your files\n\n.. code-block:: console\n\n $ flake8 example.py\n example.py:1:1: SIG202 includes parameters that do not exist (params-do-not-exist) 'function'\n\nWith ``flake8`` the pyproject.toml config will still be the base config, though the\n`ini files <https://flake8.pycqa.org/en/latest/user/configuration.html#configuration-locations>`_ ``flake8`` gets it config from will override the pyproject.toml config.\nFor ``flake8`` all args and config options are prefixed with ``sig`` to\navoid any potential conflicts with other plugins\n\n.. code-block:: ini\n\n [flake8]\n sig-check-dunders = True\n sig-check-overridden = True\n sig-check-protected = True\n\n..\n end flake8\n\nAPI\n***\n\n.. code-block:: python\n\n >>> from docsig import docsig\n\n.. code-block:: python\n\n >>> string = \"\"\"\n ... def function(param1, param2, param3) -> None:\n ... '''\n ...\n ... :param param1: About param1.\n ... :param param2: About param2.\n ... :param param3: About param3.\n ... '''\n ... \"\"\"\n >>> docsig(string=string, no_ansi=True)\n 0\n\n.. code-block:: python\n\n >>> string = \"\"\"\n ... def function(param1, param2) -> None:\n ... '''\n ...\n ... :param param1: About param1.\n ... :param param2: About param2.\n ... :param param3: About param3.\n ... '''\n ... \"\"\"\n >>> docsig(string=string, no_ansi=True)\n 2 in function\n SIG202: includes parameters that do not exist (params-do-not-exist)\n 1\n\nA full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/usage/messages.html>`__\n\nMessage Control\n***************\n\nIf you have been using ``docsig`` prior to ``v0.56.0``, please see\n`updated messages <https://docsig.readthedocs.io/en/latest/deprecated/messages.html>`_\n\n`Documentation on message control <https://docsig.readthedocs.io/en/latest/usage/message-control.html>`_\n\nClasses\n*******\n\n`Documenting classes <https://docsig.readthedocs.io/en/latest/usage/configuration.html#classes>`_\n\npre-commit\n**********\n\n``docsig`` can be used as a `pre-commit <https://pre-commit.com>`_ hook\n\nIt can be added to your .pre-commit-config.yaml as follows:\n\nStandalone\n\n.. code-block:: yaml\n\n repos:\n - repo: https://github.com/jshwi/docsig\n rev: v0.66.0\n hooks:\n - id: docsig\n args:\n - \"--check-class\"\n - \"--check-dunders\"\n - \"--check-overridden\"\n - \"--check-protected\"\n\nor integrated with ``flake8``\n\n.. code-block:: yaml\n\n repos:\n - repo: https://github.com/PyCQA/flake8\n rev: \"7.1.0\"\n hooks:\n - id: flake8\n additional_dependencies:\n - docsig==0.66.0\n args:\n - \"--sig-check-class\"\n - \"--sig-check-dunders\"\n - \"--sig-check-overridden\"\n - \"--sig-check-protected\"\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Check signature params for proper documentation",
"version": "0.66.0",
"project_urls": {
"Documentation": "https://docsig.readthedocs.io/en/latest",
"Homepage": "https://pypi.org/project/docsig/",
"Repository": "https://github.com/jshwi/docsig"
},
"split_keywords": [
"check",
" docs",
" docstring",
" params",
" signature"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2e4d9113dacf543abc74cd227e5da1d92f6d1648410dbc6b190edb714e1148b7",
"md5": "e9ef6d523567dc4b383cda7240b3247f",
"sha256": "8fa9cd40c650d25232860c999d0c044fe8440826c4144f4bcc711f843951771a"
},
"downloads": -1,
"filename": "docsig-0.66.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9ef6d523567dc4b383cda7240b3247f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.1",
"size": 29592,
"upload_time": "2024-12-24T06:07:43",
"upload_time_iso_8601": "2024-12-24T06:07:43.537312Z",
"url": "https://files.pythonhosted.org/packages/2e/4d/9113dacf543abc74cd227e5da1d92f6d1648410dbc6b190edb714e1148b7/docsig-0.66.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5bed33614863211c470f0f14ae734589f82c768efc51cc1150d802d147cd1015",
"md5": "0d49c955b5c7ab323d5613f14b2f923f",
"sha256": "211c7d5244c3eee7af4793861275e1d0cb1aa4daae9da0512ef672ed0d4251b2"
},
"downloads": -1,
"filename": "docsig-0.66.0.tar.gz",
"has_sig": false,
"md5_digest": "0d49c955b5c7ab323d5613f14b2f923f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.1",
"size": 26691,
"upload_time": "2024-12-24T06:07:46",
"upload_time_iso_8601": "2024-12-24T06:07:46.537632Z",
"url": "https://files.pythonhosted.org/packages/5b/ed/33614863211c470f0f14ae734589f82c768efc51cc1150d802d147cd1015/docsig-0.66.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-24 06:07:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jshwi",
"github_project": "docsig",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "docsig"
}
JSON
