| Name | pydocstringformatter JSON |
| Version |
0.7.5
JSON |
| download |
| home_page | None |
| Summary | A tool to automatically format Python docstrings that tries to follow recommendations from PEP 8 and PEP 257. |
| upload_time | 2025-07-12 10:12:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| 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": null,
"name": "pydocstringformatter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "python, docstring, format",
"author": null,
"author_email": "Dani\u00ebl van Noord <13665637+DanielNoord@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/b0/37/f6d5ff68893c8b4ae194d6dd9df31be2cceacfae5256c840b9e216fd20de/pydocstringformatter-0.7.5.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.5",
"project_urls": {
"Bug Tracker": "https://github.com/DanielNoord/pydocstringformatter/issues",
"Releases": "https://github.com/DanielNoord/pydocstringformatter/releases",
"Repository": "https://github.com/DanielNoord/pydocstringformatter"
},
"split_keywords": [
"python",
" docstring",
" format"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "81ede70e413b537b7809badcd275a5f050301dafbe54efd1ae9d392ed2943c40",
"md5": "bdaa729a94937dae2f782679717f7016",
"sha256": "7daed355f11244f64571d119e49e7328365ea9b545f88256a47b550f213d23eb"
},
"downloads": -1,
"filename": "pydocstringformatter-0.7.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bdaa729a94937dae2f782679717f7016",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 31433,
"upload_time": "2025-07-12T10:12:44",
"upload_time_iso_8601": "2025-07-12T10:12:44.619303Z",
"url": "https://files.pythonhosted.org/packages/81/ed/e70e413b537b7809badcd275a5f050301dafbe54efd1ae9d392ed2943c40/pydocstringformatter-0.7.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b037f6d5ff68893c8b4ae194d6dd9df31be2cceacfae5256c840b9e216fd20de",
"md5": "e1d65da1c153a602ab758fcdae7ddd8c",
"sha256": "e9cbd134d6279360fd2bcaad94680cec02aa20a22560375c5ffd495fcfbcf92d"
},
"downloads": -1,
"filename": "pydocstringformatter-0.7.5.tar.gz",
"has_sig": false,
"md5_digest": "e1d65da1c153a602ab758fcdae7ddd8c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 30474,
"upload_time": "2025-07-12T10:12:46",
"upload_time_iso_8601": "2025-07-12T10:12:46.089738Z",
"url": "https://files.pythonhosted.org/packages/b0/37/f6d5ff68893c8b4ae194d6dd9df31be2cceacfae5256c840b9e216fd20de/pydocstringformatter-0.7.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 10:12:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DanielNoord",
"github_project": "pydocstringformatter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pydocstringformatter"
}
