| Name | pymend JSON |
| Version |
1.0.10
JSON |
| download |
| home_page | |
| Summary | Generate, fix and convert docstrings. |
| upload_time | 2023-10-12 15:38:27 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | GPL-3.0-or-later |
| keywords |
docstring
pymend
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
******
pymend
******
Create, update or convert docstrings in existing Python files, managing
several styles.
Project Status
==============
**Test Status**
|Build| |Documentation Status| |Downloads|
|License: GPL v3| |Code style: black| |linting: pylint| |Ruff| |Checked
with pyright| |pre-commit|
**Supported Versions**
|Supports Python39|
|Supports Python310|
|Supports Python311|
|Supports Python312|
.. **Code Coverage**
.. .. image:: https://coveralls.io/repos/github/wagnerpeer/pymend/badge.svg?branch=enhancement%2Fcoveralls
.. :target: https://coveralls.io/github/wagnerpeer/pymend?branch=enhancement%2Fcoveralls
.. :alt: Test coverage (Coveralls)
Description
===========
Command-line program to generate, update or transform docstrings python
source code.
The app will parse the requested source files for docstrings as well as
function signatures and class bodies.
This information is combined to build up complete docstrings for every
function and class including place holders for types and descriptions
where none could be found elsewhere.
The output format of the docstrings can be chosen between google, numpy,
reST and epydoc. This means that the tool can also be used to transform
docstrings in the file from one format into another.
Note however that not all section types are supported for all docstring
styles.
Partially because they have not been added yet, but also because not
every style officially supports the sections from all others.
To get further information please refer to the
`documentation <https://pymend.readthedocs.io/en/latest/?badge=latest>`__.
The tool offers the choice between generating patch files or directly
overwriting the python source files.
Start quickly
=============
- install from PyPi
.. code:: sh
$ pip install pymend
- install from sources:
.. code:: sh
$ pip install git+https://github.com/JanEricNitschke/pymend.git
or
$ git clone https://github.com/JanEricNitschke/pymend.git
$ cd pymend
$ python setup.py install
- run from the command line:
.. code:: sh
$ pymend myfile.py # will generate a patch
$ pymend -w myfile.py # will overwrite the file
- get help:
.. code:: sh
$ pymend -h
Example
-------
To see how pymend looks in action lets consider this example file `example.py`:
.. code-block:: python
"""_summary_."""
def my_func(param0, param01: int, param1: str = "Some value", param2: List[str] = {}):
"""_summary_.
Args:
param0 (_type_): _description_
param01 (int): _description_
param1 (str, optional): _description_. Defaults to "Some value".
param2 (List[str], optional): _description_. Defaults to {}.
"""
pass
def my_single_return_func1() -> str:
"""_summary_.
Returns
-------
int
Wrong
"""
pass
def my_multi_return_func() -> Tuple[int, str, bool]:
"""_summary_.
Returns
-------
x :
Some integer
y : str
Some string
z : bool
Some bool
"""
pass
class A:
def method(self, param1, param2=None) -> int:
pass
Now let's use Pyment:
.. code-block:: sh
$ pyment example.py
This produces the following patch file `example.py.patch`:
.. code-block:: patch
# Patch generated by Pymend v1.0.10
--- a/example.py
+++ b/example.py
@@ -2,11 +2,16 @@
def my_func(param0, param01: int, param1: str = "Some value", param2: List[str] = {}):
"""_summary_.
- Args:
- param0 (_type_): _description_
- param01 (int): _description_
- param1 (str, optional): _description_. Defaults to "Some value".
- param2 (List[str], optional): _description_. Defaults to {}.
+ Parameters
+ ----------
+ param0 : _type_
+ _description_
+ param01 : int
+ _description_
+ param1 : str
+ _description_. Defaults to "Some value".
+ param2 : List[str]
+ _description_. Defaults to {}.
"""
pass
@@ -16,7 +21,7 @@
Returns
-------
- int
+ str
Wrong
"""
pass
@@ -27,7 +32,7 @@
Returns
-------
- x :
+ x : _type_
Some integer
y : str
Some string
@@ -37,5 +42,21 @@
pass
class A:
+ """_summary_.
+
+ Methods
+ -------
+ method(param1, param2=None)
+ _description_
+ """
def method(self, param1, param2=None) -> int:
+ """_summary_.
+
+ Parameters
+ ----------
+ param1 : _type_
+ _description_
+ param2 : _type_
+ _description_ (Default value = None)
+ """
pass
Calling pyment directly with
.. code-block:: sh
$ pyment --write example.py
print outs this information about changed files
.. code-block:: sh
$ Modified docstrings of elements (my_func, my_single_return_func1, my_multi_return_func, A, method) in file example.py.
and results in the final file (the same we would have gotten when applying the patch):
.. code-block:: python
"""_summary_."""
def my_func(param0, param01: int, param1: str = "Some value", param2: List[str] = {}):
"""_summary_.
Parameters
----------
param0 : _type_
_description_
param01 : int
_description_
param1 : str
_description_. Defaults to "Some value".
param2 : List[str]
_description_. Defaults to {}.
"""
pass
def my_single_return_func1() -> str:
"""_summary_.
Returns
-------
str
Wrong
"""
pass
def my_multi_return_func() -> Tuple[int, str, bool]:
"""_summary_.
Returns
-------
x : _type_
Some integer
y : str
Some string
z : bool
Some bool
"""
pass
class A:
"""_summary_.
Methods
-------
method(param1, param2=None)
_description_
"""
def method(self, param1, param2=None) -> int:
"""_summary_.
Parameters
----------
param1 : _type_
_description_
param2 : _type_
_description_ (Default value = None)
"""
pass
Pre-commit
==========
To use pymend in a `pre-commit <https://pre-commit.com/>`__ hook just
add the following to your ``.pre-commit-config.yaml``
.. code:: yaml
repos:
- repo: https://github.com/JanEricNitschke/pymend
rev: "v1.0.10"
hooks:
- id: pymend
language: python
args: ["--write", "--check"]
Acknowledgements
================
This project was inspired by and is originally based upon
`pyment <https://github.com/dadadel/pyment/>`__. The intended
functionality as well as the main entry point remain largerly unchanged.
However additional functionality has been added in the form of ast
traversal for extracting function and class information.
The docstring parsing has been replaced completely with code taken from
the awesome
`docstring_parser <https://github.com/rr-/docstring_parser>`__ project,
specifically `this
fork <https://github.com/jsh9/docstring_parser_fork>`__.
So far only minor modifications have been made to the docstring parsing
functionality. Mainly the addition of the “Methods” section for numpydoc
style docstrings. Additionally the the code has been linted as well as
type hinted.
The code for configuration and file handling as well as the structure of the documentation
is more or less taken directly from `black <https://github.com/psf/black/>`__.
.. |Build| image:: https://github.com/JanEricNitschke/pymend/actions/workflows/build.yaml/badge.svg
:target: https://github.com/JanEricNitschke/pymend/workflows/build.yaml
.. |Documentation Status| image:: https://readthedocs.org/projects/pymend/badge/?version=latest
:target: https://pymend.readthedocs.io/en/latest/?badge=latest
.. |Downloads| image:: https://static.pepy.tech/personalized-badge/pymend?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads
:target: https://www.pepy.tech/projects/pymend
.. |License: GPL v3| image:: https://img.shields.io/badge/License-GPLv3-blue.svg
:target: https://github.com/JanEricNitschke/pymend/blob/main/LICENSE
.. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
.. |linting: pylint| image:: https://img.shields.io/badge/linting-pylint-yellowgreen
:target: https://github.com/pylint-dev/pylint
.. |Ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json
:target: https://github.com/charliermarsh/ruff
.. |Checked with pyright| image:: https://microsoft.github.io/pyright/img/pyright_badge.svg
:target: https://microsoft.github.io/pyright/
.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit
:target: https://github.com/pre-commit/pre-commit
.. |Supports Python39| image:: https://img.shields.io/badge/python-3.9-blue.svg
:target: https://www.python.org/downloads/release/python-390/
.. |Supports Python310| image:: https://img.shields.io/badge/python-3.10-blue.svg
:target: https://www.python.org/downloads/release/python-3100/
.. |Supports Python311| image:: https://img.shields.io/badge/python-3.11-blue.svg
:target: https://www.python.org/downloads/release/python-3110/
.. |Supports Python312| image:: https://img.shields.io/badge/python-3.12-blue.svg
:target: https://www.python.org/downloads/release/python-3120/
Raw data
{
"_id": null,
"home_page": "",
"name": "pymend",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Jan-Eric Nitschke <janericnitschke@gmail.com>",
"keywords": "docstring,pymend",
"author": "",
"author_email": "Jan-Eric Nitschke <janericnitschke@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ed/68/0c545914d829f7519df5e379c336fdbaea32110c1be63f1ff4c3bf673eda/pymend-1.0.10.tar.gz",
"platform": null,
"description": "******\npymend\n******\n\nCreate, update or convert docstrings in existing Python files, managing\nseveral styles.\n\nProject Status\n==============\n\n**Test Status**\n\n|Build| |Documentation Status| |Downloads|\n\n|License: GPL v3| |Code style: black| |linting: pylint| |Ruff| |Checked\nwith pyright| |pre-commit|\n\n**Supported Versions**\n\n|Supports Python39|\n|Supports Python310|\n|Supports Python311|\n|Supports Python312|\n\n\n.. **Code Coverage**\n\n.. .. image:: https://coveralls.io/repos/github/wagnerpeer/pymend/badge.svg?branch=enhancement%2Fcoveralls\n.. :target: https://coveralls.io/github/wagnerpeer/pymend?branch=enhancement%2Fcoveralls\n.. :alt: Test coverage (Coveralls)\n\nDescription\n===========\n\nCommand-line program to generate, update or transform docstrings python\nsource code.\n\nThe app will parse the requested source files for docstrings as well as\nfunction signatures and class bodies.\n\nThis information is combined to build up complete docstrings for every\nfunction and class including place holders for types and descriptions\nwhere none could be found elsewhere.\n\nThe output format of the docstrings can be chosen between google, numpy,\nreST and epydoc. This means that the tool can also be used to transform\ndocstrings in the file from one format into another.\n\nNote however that not all section types are supported for all docstring\nstyles.\n\nPartially because they have not been added yet, but also because not\nevery style officially supports the sections from all others.\n\nTo get further information please refer to the\n`documentation <https://pymend.readthedocs.io/en/latest/?badge=latest>`__.\n\nThe tool offers the choice between generating patch files or directly\noverwriting the python source files.\n\nStart quickly\n=============\n\n- install from PyPi\n\n.. code:: sh\n\n $ pip install pymend\n\n- install from sources:\n\n.. code:: sh\n\n $ pip install git+https://github.com/JanEricNitschke/pymend.git\n or\n $ git clone https://github.com/JanEricNitschke/pymend.git\n $ cd pymend\n $ python setup.py install\n\n- run from the command line:\n\n.. code:: sh\n\n $ pymend myfile.py # will generate a patch\n $ pymend -w myfile.py # will overwrite the file\n\n- get help:\n\n.. code:: sh\n\n $ pymend -h\n\nExample\n-------\n\nTo see how pymend looks in action lets consider this example file `example.py`:\n\n.. code-block:: python\n\n \"\"\"_summary_.\"\"\"\n def my_func(param0, param01: int, param1: str = \"Some value\", param2: List[str] = {}):\n \"\"\"_summary_.\n\n Args:\n param0 (_type_): _description_\n param01 (int): _description_\n param1 (str, optional): _description_. Defaults to \"Some value\".\n param2 (List[str], optional): _description_. Defaults to {}.\n \"\"\"\n pass\n\n\n def my_single_return_func1() -> str:\n \"\"\"_summary_.\n\n Returns\n -------\n int\n Wrong\n \"\"\"\n pass\n\n\n def my_multi_return_func() -> Tuple[int, str, bool]:\n \"\"\"_summary_.\n\n Returns\n -------\n x :\n Some integer\n y : str\n Some string\n z : bool\n Some bool\n \"\"\"\n pass\n\n class A:\n def method(self, param1, param2=None) -> int:\n pass\n\nNow let's use Pyment:\n\n.. code-block:: sh\n\n $ pyment example.py\n\nThis produces the following patch file `example.py.patch`:\n\n.. code-block:: patch\n\n # Patch generated by Pymend v1.0.10\n\n --- a/example.py\n +++ b/example.py\n @@ -2,11 +2,16 @@\n def my_func(param0, param01: int, param1: str = \"Some value\", param2: List[str] = {}):\n \"\"\"_summary_.\n\n - Args:\n - param0 (_type_): _description_\n - param01 (int): _description_\n - param1 (str, optional): _description_. Defaults to \"Some value\".\n - param2 (List[str], optional): _description_. Defaults to {}.\n + Parameters\n + ----------\n + param0 : _type_\n + _description_\n + param01 : int\n + _description_\n + param1 : str\n + _description_. Defaults to \"Some value\".\n + param2 : List[str]\n + _description_. Defaults to {}.\n \"\"\"\n pass\n\n @@ -16,7 +21,7 @@\n\n Returns\n -------\n - int\n + str\n Wrong\n \"\"\"\n pass\n @@ -27,7 +32,7 @@\n\n Returns\n -------\n - x :\n + x : _type_\n Some integer\n y : str\n Some string\n @@ -37,5 +42,21 @@\n pass\n\n class A:\n + \"\"\"_summary_.\n +\n + Methods\n + -------\n + method(param1, param2=None)\n + _description_\n + \"\"\"\n def method(self, param1, param2=None) -> int:\n + \"\"\"_summary_.\n +\n + Parameters\n + ----------\n + param1 : _type_\n + _description_\n + param2 : _type_\n + _description_ (Default value = None)\n + \"\"\"\n pass\n\nCalling pyment directly with\n\n.. code-block:: sh\n\n $ pyment --write example.py\n\nprint outs this information about changed files\n\n.. code-block:: sh\n\n $ Modified docstrings of elements (my_func, my_single_return_func1, my_multi_return_func, A, method) in file example.py.\n\nand results in the final file (the same we would have gotten when applying the patch):\n\n.. code-block:: python\n\n \"\"\"_summary_.\"\"\"\n def my_func(param0, param01: int, param1: str = \"Some value\", param2: List[str] = {}):\n \"\"\"_summary_.\n\n Parameters\n ----------\n param0 : _type_\n _description_\n param01 : int\n _description_\n param1 : str\n _description_. Defaults to \"Some value\".\n param2 : List[str]\n _description_. Defaults to {}.\n \"\"\"\n pass\n\n\n def my_single_return_func1() -> str:\n \"\"\"_summary_.\n\n Returns\n -------\n str\n Wrong\n \"\"\"\n pass\n\n\n def my_multi_return_func() -> Tuple[int, str, bool]:\n \"\"\"_summary_.\n\n Returns\n -------\n x : _type_\n Some integer\n y : str\n Some string\n z : bool\n Some bool\n \"\"\"\n pass\n\n class A:\n \"\"\"_summary_.\n\n Methods\n -------\n method(param1, param2=None)\n _description_\n \"\"\"\n def method(self, param1, param2=None) -> int:\n \"\"\"_summary_.\n\n Parameters\n ----------\n param1 : _type_\n _description_\n param2 : _type_\n _description_ (Default value = None)\n \"\"\"\n pass\n\n\n\nPre-commit\n==========\n\nTo use pymend in a `pre-commit <https://pre-commit.com/>`__ hook just\nadd the following to your ``.pre-commit-config.yaml``\n\n.. code:: yaml\n\n repos:\n - repo: https://github.com/JanEricNitschke/pymend\n rev: \"v1.0.10\"\n hooks:\n - id: pymend\n language: python\n args: [\"--write\", \"--check\"]\n\nAcknowledgements\n================\n\nThis project was inspired by and is originally based upon\n`pyment <https://github.com/dadadel/pyment/>`__. The intended\nfunctionality as well as the main entry point remain largerly unchanged.\nHowever additional functionality has been added in the form of ast\ntraversal for extracting function and class information.\n\nThe docstring parsing has been replaced completely with code taken from\nthe awesome\n`docstring_parser <https://github.com/rr-/docstring_parser>`__ project,\nspecifically `this\nfork <https://github.com/jsh9/docstring_parser_fork>`__.\n\nSo far only minor modifications have been made to the docstring parsing\nfunctionality. Mainly the addition of the \u201cMethods\u201d section for numpydoc\nstyle docstrings. Additionally the the code has been linted as well as\ntype hinted.\n\nThe code for configuration and file handling as well as the structure of the documentation\nis more or less taken directly from `black <https://github.com/psf/black/>`__.\n\n.. |Build| image:: https://github.com/JanEricNitschke/pymend/actions/workflows/build.yaml/badge.svg\n :target: https://github.com/JanEricNitschke/pymend/workflows/build.yaml\n.. |Documentation Status| image:: https://readthedocs.org/projects/pymend/badge/?version=latest\n :target: https://pymend.readthedocs.io/en/latest/?badge=latest\n.. |Downloads| image:: https://static.pepy.tech/personalized-badge/pymend?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads\n :target: https://www.pepy.tech/projects/pymend\n.. |License: GPL v3| image:: https://img.shields.io/badge/License-GPLv3-blue.svg\n :target: https://github.com/JanEricNitschke/pymend/blob/main/LICENSE\n.. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n.. |linting: pylint| image:: https://img.shields.io/badge/linting-pylint-yellowgreen\n :target: https://github.com/pylint-dev/pylint\n.. |Ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json\n :target: https://github.com/charliermarsh/ruff\n.. |Checked with pyright| image:: https://microsoft.github.io/pyright/img/pyright_badge.svg\n :target: https://microsoft.github.io/pyright/\n.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\n :target: https://github.com/pre-commit/pre-commit\n.. |Supports Python39| image:: https://img.shields.io/badge/python-3.9-blue.svg\n :target: https://www.python.org/downloads/release/python-390/\n.. |Supports Python310| image:: https://img.shields.io/badge/python-3.10-blue.svg\n :target: https://www.python.org/downloads/release/python-3100/\n.. |Supports Python311| image:: https://img.shields.io/badge/python-3.11-blue.svg\n :target: https://www.python.org/downloads/release/python-3110/\n.. |Supports Python312| image:: https://img.shields.io/badge/python-3.12-blue.svg\n :target: https://www.python.org/downloads/release/python-3120/\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Generate, fix and convert docstrings.",
"version": "1.0.10",
"project_urls": {
"Bug Tracker": "https://github.com/JanEricNitschke/pymend/issues",
"Documentation": "https://pymend.readthedocs.io/en/latest/",
"GitHub": "https://github.com/JanEricNitschke/pymend",
"Homepage": "https://github.com/JanEricNitschke/pymend"
},
"split_keywords": [
"docstring",
"pymend"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cc0307c27c464a34699b10035a967e6960bf618dc465808da1b80227ccd4980a",
"md5": "c2ea505759d9846ed49d4bc6f570ca8a",
"sha256": "68512540e6e94926f5b4d25b891fe6bc934ad0554e26e4c19bf395fe292bea5d"
},
"downloads": -1,
"filename": "pymend-1.0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2ea505759d9846ed49d4bc6f570ca8a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 70645,
"upload_time": "2023-10-12T15:38:25",
"upload_time_iso_8601": "2023-10-12T15:38:25.408302Z",
"url": "https://files.pythonhosted.org/packages/cc/03/07c27c464a34699b10035a967e6960bf618dc465808da1b80227ccd4980a/pymend-1.0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ed680c545914d829f7519df5e379c336fdbaea32110c1be63f1ff4c3bf673eda",
"md5": "d573d3c2943747c944b48a53bc8ea64a",
"sha256": "dc27eb2999b7f232d547d1691c5e941c35076ecccf6c265722e1254624c23bbe"
},
"downloads": -1,
"filename": "pymend-1.0.10.tar.gz",
"has_sig": false,
"md5_digest": "d573d3c2943747c944b48a53bc8ea64a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 94822,
"upload_time": "2023-10-12T15:38:27",
"upload_time_iso_8601": "2023-10-12T15:38:27.460191Z",
"url": "https://files.pythonhosted.org/packages/ed/68/0c545914d829f7519df5e379c336fdbaea32110c1be63f1ff4c3bf673eda/pymend-1.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-12 15:38:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JanEricNitschke",
"github_project": "pymend",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pymend"
}
