| Name | pydocstringformatter JSON |
| Version |
0.7.3
JSON |
| download |
| home_page | |
| Summary | A tool to automatically format Python docstrings that tries to follow recommendations from PEP 8 and PEP 257. |
| upload_time | 2023-01-02 15:09:30 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
python
docstring
format
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.python.org/pypi/pydocstringformatter/)
[](https://codecov.io/gh/DanielNoord/pydocstringformatter)
[](https://github.com/DanielNoord/pydocstringformatter/actions/workflows/tests.yaml)
[](https://results.pre-commit.ci/latest/github/DanielNoord/pydocstringformatter/main)
[](https://pydocstringformatter.readthedocs.io/en/latest/?badge=latest)
# Pydocstringformatter
A tool to automatically format Python docstrings to follow recommendations from
[`PEP 8`](https://www.python.org/dev/peps/pep-0008/) and
[`PEP 257`](https://www.python.org/dev/peps/pep-0257/) (or other supported style
guides.)
See [What it does](#what-it-does) for currently supported auto-formatting.
### Rationale
This project is heavily inspired by
[`docformatter`](https://github.com/PyCQA/docformatter).
When this project was started `docformatter` did not meet all of the requirements the
[`pylint`](https://github.com/PyCQA/pylint) project had for its docstring formatter and
was no longer actively maintained (this has changed since then). Therefore, some
contributors of `pylint` got together and started working on our own formatter to
fulfill our needs.
When asked we defined the objective of the tool as:
_"A docstring formatter that follows PEP8 and PEP257 but makes some of the more
'controversial' elements of the PEPs optional"_
See
[the original answer](https://github.com/DanielNoord/pydocstringformatter/issues/38).
As such, the biggest difference between the two is that `pydocstringformatter` fixes
some of the open issues we found in `docformatter`. In general, the output of both
formatters (and any other docstring formatter) should be relatively similar.
## How to install
```shell
pip install pydocstringformatter
```
## Usage
[`Click here`](https://pydocstringformatter.readthedocs.io/en/latest/usage.html) for a
full Usage overview.
### Configuration
Pydocstringformatter will also read any configuration added to the
`[tool.pydocstringformatter]` section of a `pyproject.toml` file.
For example:
```toml
[tool.pydocstringformatter]
write = true
exclude = "**/my_dir/**,**/my_other_dir/**"
# Or:
exclude = ["**/my_dir/**", "**/my_other_dir/**"]
strip-whitespaces = true
split-summary-body = false
numpydoc-section-hyphen-length = false
```
#### Style
Pydocstringformatter can be configured to use a specific style. The default is `pep257`
but we support other styles as well. These can also be used at the same time. For
example with:
```console
pydocstringformatter --style=pep257 --style=numpydoc myfile.py
```
## Pre-commit
Pydocstringformatter can also be used as a [pre-commit hook](https://pre-commit.com).
Add the following to your `.pre-commit-config.yaml` file:
```yaml
- repo: https://github.com/DanielNoord/pydocstringformatter
rev: SPECIFY VERSION HERE
hooks:
- id: pydocstringformatter
```
## What it does
The following examples show some of the changes pydocstringformatter will apply. For a
full overview of all potential changes you can check out the
[`Usage`](https://pydocstringformatter.readthedocs.io/en/latest/usage.html) page which
shows an up to date list of all formatters and their description.
```python
# Bad
'''
my docstring'''
""" my
multi-line docstring """
"""my title
===========
my docstring
"""
# Good
"""My docstring."""
"""My
multi-line docstring.
"""
"""My title
===========
My docstring
"""
# With --summary-quotes-same-line
# Bad
"""
My
multi-line docstring
"""
# Good
"""My
multi-line docstring
"""
```
## Development
For development and contributing guidelines please see
[`Development`](https://pydocstringformatter.readthedocs.io/en/latest/development.html).
Raw data
{
"_id": null,
"home_page": "",
"name": "pydocstringformatter",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "python,docstring,format",
"author": "",
"author_email": "Dani\u00ebl van Noord <13665637+DanielNoord@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/b3/51/5c21963eb7bdba245ec808fdb0ef8abc0cd87ef674f2b6ba1fd76f3a0ffa/pydocstringformatter-0.7.3.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/pypi/pydocstringformatter/)\n[](https://codecov.io/gh/DanielNoord/pydocstringformatter)\n[](https://github.com/DanielNoord/pydocstringformatter/actions/workflows/tests.yaml)\n[](https://results.pre-commit.ci/latest/github/DanielNoord/pydocstringformatter/main)\n[](https://pydocstringformatter.readthedocs.io/en/latest/?badge=latest)\n\n# Pydocstringformatter\n\nA tool to automatically format Python docstrings to follow recommendations from\n[`PEP 8`](https://www.python.org/dev/peps/pep-0008/) and\n[`PEP 257`](https://www.python.org/dev/peps/pep-0257/) (or other supported style\nguides.)\n\nSee [What it does](#what-it-does) for currently supported auto-formatting.\n\n### Rationale\n\nThis project is heavily inspired by\n[`docformatter`](https://github.com/PyCQA/docformatter).\n\nWhen this project was started `docformatter` did not meet all of the requirements the\n[`pylint`](https://github.com/PyCQA/pylint) project had for its docstring formatter and\nwas no longer actively maintained (this has changed since then). Therefore, some\ncontributors of `pylint` got together and started working on our own formatter to\nfulfill our needs.\n\nWhen asked we defined the objective of the tool as:\n\n_\"A docstring formatter that follows PEP8 and PEP257 but makes some of the more\n'controversial' elements of the PEPs optional\"_\n\nSee\n[the original answer](https://github.com/DanielNoord/pydocstringformatter/issues/38).\n\nAs such, the biggest difference between the two is that `pydocstringformatter` fixes\nsome of the open issues we found in `docformatter`. In general, the output of both\nformatters (and any other docstring formatter) should be relatively similar.\n\n## How to install\n\n```shell\npip install pydocstringformatter\n```\n\n## Usage\n\n[`Click here`](https://pydocstringformatter.readthedocs.io/en/latest/usage.html) for a\nfull Usage overview.\n\n### Configuration\n\nPydocstringformatter will also read any configuration added to the\n`[tool.pydocstringformatter]` section of a `pyproject.toml` file.\n\nFor example:\n\n```toml\n[tool.pydocstringformatter]\nwrite = true\nexclude = \"**/my_dir/**,**/my_other_dir/**\"\n# Or:\nexclude = [\"**/my_dir/**\", \"**/my_other_dir/**\"]\nstrip-whitespaces = true\nsplit-summary-body = false\nnumpydoc-section-hyphen-length = false\n```\n\n#### Style\n\nPydocstringformatter can be configured to use a specific style. The default is `pep257`\nbut we support other styles as well. These can also be used at the same time. For\nexample with:\n\n```console\npydocstringformatter --style=pep257 --style=numpydoc myfile.py\n```\n\n## Pre-commit\n\nPydocstringformatter can also be used as a [pre-commit hook](https://pre-commit.com).\nAdd the following to your `.pre-commit-config.yaml` file:\n\n```yaml\n- repo: https://github.com/DanielNoord/pydocstringformatter\n rev: SPECIFY VERSION HERE\n hooks:\n - id: pydocstringformatter\n```\n\n## What it does\n\nThe following examples show some of the changes pydocstringformatter will apply. For a\nfull overview of all potential changes you can check out the\n[`Usage`](https://pydocstringformatter.readthedocs.io/en/latest/usage.html) page which\nshows an up to date list of all formatters and their description.\n\n```python\n# Bad\n'''\nmy docstring'''\n\n\"\"\" my\nmulti-line docstring \"\"\"\n\n\"\"\"my title\n===========\n\nmy docstring\n\"\"\"\n\n\n# Good\n\"\"\"My docstring.\"\"\"\n\n\"\"\"My\nmulti-line docstring.\n\"\"\"\n\n\"\"\"My title\n===========\n\nMy docstring\n\"\"\"\n\n# With --summary-quotes-same-line\n# Bad\n\"\"\"\nMy\nmulti-line docstring\n\"\"\"\n\n# Good\n\"\"\"My\nmulti-line docstring\n\"\"\"\n```\n\n## Development\n\nFor development and contributing guidelines please see\n[`Development`](https://pydocstringformatter.readthedocs.io/en/latest/development.html).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool to automatically format Python docstrings that tries to follow recommendations from PEP 8 and PEP 257.",
"version": "0.7.3",
"split_keywords": [
"python",
"docstring",
"format"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "c4fc10b54dd419cb4d840a444ab3db05",
"sha256": "3654f52c49fc729b49712d1e7c49384dfd253bdffeda4939e79dab31491c563f"
},
"downloads": -1,
"filename": "pydocstringformatter-0.7.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c4fc10b54dd419cb4d840a444ab3db05",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 31287,
"upload_time": "2023-01-02T15:09:28",
"upload_time_iso_8601": "2023-01-02T15:09:28.904701Z",
"url": "https://files.pythonhosted.org/packages/3a/38/b3a99e9cc66941e044ad3d40e90a72b1191925b8af13e3e4d8edc5c0eb87/pydocstringformatter-0.7.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "fcfe6f29ebc754d2fa8874f13f37c012",
"sha256": "dfcc07bec1706803d563275e282ef9e629b02dc19983ec6778d07a9f500bb62b"
},
"downloads": -1,
"filename": "pydocstringformatter-0.7.3.tar.gz",
"has_sig": false,
"md5_digest": "fcfe6f29ebc754d2fa8874f13f37c012",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24024,
"upload_time": "2023-01-02T15:09:30",
"upload_time_iso_8601": "2023-01-02T15:09:30.152872Z",
"url": "https://files.pythonhosted.org/packages/b3/51/5c21963eb7bdba245ec808fdb0ef8abc0cd87ef674f2b6ba1fd76f3a0ffa/pydocstringformatter-0.7.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-02 15:09:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "pydocstringformatter"
}
