# Docstringify
Flag missing docstrings and, optionally, generate them from signatures and type annotations.
## About
Given a file, `test.py`, with the following contents:
```python
def say_hello(name: str = 'World') -> None:
print(f'Hello, {name}!')
```
You can use Docstringify in three modes:
1. Flag missing docstrings:
```
test is missing a docstring
test.say_hello is missing a docstring
```
2. Suggest docstring templates based on type annotations:
```
test is missing a docstring
Hint:
"""__description__"""
test.say_hello is missing a docstring
Hint:
"""
__description__
Parameters
----------
name : str, default="World"
__description__
"""
```
3. Add docstring templates to source code files:
```python
"""__description__"""
def say_hello(name: str = 'World') -> None:
"""
__description__
Parameters
----------
name : str, default="World"
__description__
"""
print(f'Hello, {name}!')
```
## Usage
### Pre-commit hook
Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
```yaml
- repo: https://github.com/stefmolin/docstringify
rev: 1.1.0
hooks:
- id: docstringify
```
By default, all docstrings are required. If you want to be more lenient, you can set the threshold, which is the percentage of docstrings that must be present:
```yaml
- repo: https://github.com/stefmolin/docstringify
rev: 1.1.0
hooks:
- id: docstringify
args: [--threshold=0.75]
```
If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`):
```yaml
- repo: https://github.com/stefmolin/docstringify
rev: 1.1.0
hooks:
- id: docstringify
args: [--suggest-changes=numpydoc]
```
Use `--make-changes` to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
```yaml
- repo: https://github.com/stefmolin/docstringify
rev: 1.1.0
hooks:
- id: docstringify
args: [--make-changes=google]
```
If you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` – make sure you only operate on files that are in version control with this setting. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
```yaml
- repo: https://github.com/stefmolin/docstringify
rev: 1.1.0
hooks:
- id: docstringify
args: [--make-changes-inplace=numpydoc]
```
Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
### Command line
First, install the `docstringify` package from PyPI:
```shell
$ python -m pip install docstringify
```
Then, use the `docstringify` entry point on the file(s) of your choice:
```shell
$ docstringify /path/to/file [/path/to/another/file]
```
Run `docstringify --help` for more information.
### Python
First, install the `docstringify` package from PyPI:
```shell
$ python -m pip install docstringify
```
Then, use the `DocstringVisitor()` class on individual files to see spots where docstrings are missing:
```pycon
>>> from docstringify.traversal import DocstringVisitor
>>> visitor = DocstringVisitor('test.py')
>>> visitor.process_file()
test is missing a docstring
test.say_hello is missing a docstring
```
If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide a converter:
```pycon
>>> from docstringify.converters import NumpydocDocstringConverter
>>> from docstringify.traversal import DocstringVisitor
>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
>>> visitor.process_file()
test is missing a docstring
Hint:
"""__description__"""
test.say_hello is missing a docstring
Hint:
"""
__description__
Parameters
----------
name : str, default="World"
__description__
"""
```
To make changes to your files, you will need to use the `DocstringTransformer` instead. With the `DocstringTransformer`, the converter is required:
```pycon
>>> from docstringify.converters import GoogleDocstringConverter
>>> from docstringify.traversal import DocstringTransformer
>>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)
>>> transformer.process_file()
test is missing a docstring
test.say_hello is missing a docstring
Docstring templates written to /.../test_docstringify.py
```
If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`:
```pycon
>>> from docstringify.converters import GoogleDocstringConverter
>>> from docstringify.traversal import DocstringTransformer
>>> transformer = DocstringTransformer(
... 'test.py', converter=GoogleDocstringConverter, overwrite=True
... )
>>> transformer.process_file()
test is missing a docstring
test.say_hello is missing a docstring
Docstring templates written to /.../test.py
```
## Contributing
Please consult the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "docstringify",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ast, docstring generation, google-style docstring, numpydoc-style docstring, pre-commit",
"author": null,
"author_email": "Stefanie Molin <docstringify@stefaniemolin.com>",
"download_url": "https://files.pythonhosted.org/packages/ff/71/839eab2e80efe45bbb0e030c06183315f2152ecd9384612f8ef22f2d99a0/docstringify-1.1.1.tar.gz",
"platform": null,
"description": "# Docstringify\nFlag missing docstrings and, optionally, generate them from signatures and type annotations.\n\n## About\n\nGiven a file, `test.py`, with the following contents:\n\n```python\ndef say_hello(name: str = 'World') -> None:\n print(f'Hello, {name}!')\n```\n\nYou can use Docstringify in three modes:\n\n1. Flag missing docstrings:\n ```\n test is missing a docstring\n test.say_hello is missing a docstring\n ```\n2. Suggest docstring templates based on type annotations:\n ```\n test is missing a docstring\n Hint:\n \"\"\"__description__\"\"\"\n\n test.say_hello is missing a docstring\n Hint:\n \"\"\"\n __description__\n\n Parameters\n ----------\n name : str, default=\"World\"\n __description__\n \"\"\"\n ```\n3. Add docstring templates to source code files:\n ```python\n \"\"\"__description__\"\"\"\n\n def say_hello(name: str = 'World') -> None:\n \"\"\"\n __description__\n\n Parameters\n ----------\n name : str, default=\"World\"\n __description__\n \"\"\"\n print(f'Hello, {name}!')\n ```\n\n## Usage\n\n### Pre-commit hook\n\nAdd the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:\n\n```yaml\n- repo: https://github.com/stefmolin/docstringify\n rev: 1.1.0\n hooks:\n - id: docstringify\n```\n\nBy default, all docstrings are required. If you want to be more lenient, you can set the threshold, which is the percentage of docstrings that must be present:\n\n```yaml\n- repo: https://github.com/stefmolin/docstringify\n rev: 1.1.0\n hooks:\n - id: docstringify\n args: [--threshold=0.75]\n```\n\nIf you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `\"\"\"__description__\"\"\"`):\n\n```yaml\n- repo: https://github.com/stefmolin/docstringify\n rev: 1.1.0\n hooks:\n - id: docstringify\n args: [--suggest-changes=numpydoc]\n```\n\nUse `--make-changes` to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):\n\n```yaml\n- repo: https://github.com/stefmolin/docstringify\n rev: 1.1.0\n hooks:\n - id: docstringify\n args: [--make-changes=google]\n```\n\nIf you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` – make sure you only operate on files that are in version control with this setting. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:\n\n```yaml\n- repo: https://github.com/stefmolin/docstringify\n rev: 1.1.0\n hooks:\n - id: docstringify\n args: [--make-changes-inplace=numpydoc]\n```\n\nBe sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.\n\n### Command line\n\nFirst, install the `docstringify` package from PyPI:\n\n```shell\n$ python -m pip install docstringify\n```\n\nThen, use the `docstringify` entry point on the file(s) of your choice:\n\n```shell\n$ docstringify /path/to/file [/path/to/another/file]\n```\n\nRun `docstringify --help` for more information.\n\n### Python\n\nFirst, install the `docstringify` package from PyPI:\n\n```shell\n$ python -m pip install docstringify\n```\n\nThen, use the `DocstringVisitor()` class on individual files to see spots where docstrings are missing:\n\n```pycon\n>>> from docstringify.traversal import DocstringVisitor\n>>> visitor = DocstringVisitor('test.py')\n>>> visitor.process_file()\ntest is missing a docstring\ntest.say_hello is missing a docstring\n```\n\nIf you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide a converter:\n\n```pycon\n>>> from docstringify.converters import NumpydocDocstringConverter\n>>> from docstringify.traversal import DocstringVisitor\n>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)\n>>> visitor.process_file()\ntest is missing a docstring\nHint:\n\"\"\"__description__\"\"\"\n\ntest.say_hello is missing a docstring\nHint:\n\"\"\"\n__description__\n\nParameters\n----------\nname : str, default=\"World\"\n __description__\n\"\"\"\n\n```\n\nTo make changes to your files, you will need to use the `DocstringTransformer` instead. With the `DocstringTransformer`, the converter is required:\n\n```pycon\n>>> from docstringify.converters import GoogleDocstringConverter\n>>> from docstringify.traversal import DocstringTransformer\n>>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)\n>>> transformer.process_file()\ntest is missing a docstring\ntest.say_hello is missing a docstring\nDocstring templates written to /.../test_docstringify.py\n```\n\nIf you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`:\n\n```pycon\n>>> from docstringify.converters import GoogleDocstringConverter\n>>> from docstringify.traversal import DocstringTransformer\n>>> transformer = DocstringTransformer(\n... 'test.py', converter=GoogleDocstringConverter, overwrite=True\n... )\n>>> transformer.process_file()\ntest is missing a docstring\ntest.say_hello is missing a docstring\nDocstring templates written to /.../test.py\n```\n\n## Contributing\n\nPlease consult the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "Flag missing docstrings and, optionally, generate them from signatures and type annotations.",
"version": "1.1.1",
"project_urls": {
"Documentation": "https://github.com/stefmolin/docstringify",
"Homepage": "https://github.com/stefmolin/docstringify",
"Source": "https://github.com/stefmolin/docstringify"
},
"split_keywords": [
"ast",
" docstring generation",
" google-style docstring",
" numpydoc-style docstring",
" pre-commit"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d227d1571c8e1bd2122e13271b472b7c7da399aff1c01bc210c45a88fdf0c6a4",
"md5": "2c3e14559f6249b63b39ff40d5eb57b9",
"sha256": "b5323e4e29430b360418296d4a10d5734ab3b70890c3361507d33dc5cc9e475c"
},
"downloads": -1,
"filename": "docstringify-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c3e14559f6249b63b39ff40d5eb57b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22753,
"upload_time": "2025-07-13T22:43:30",
"upload_time_iso_8601": "2025-07-13T22:43:30.473728Z",
"url": "https://files.pythonhosted.org/packages/d2/27/d1571c8e1bd2122e13271b472b7c7da399aff1c01bc210c45a88fdf0c6a4/docstringify-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ff71839eab2e80efe45bbb0e030c06183315f2152ecd9384612f8ef22f2d99a0",
"md5": "50b6d225bdeb8e5af5458667750206e2",
"sha256": "6c57d051a94c2ff16d906d80ac16adc0e550c74eae3e5e47f6a8342c882131f4"
},
"downloads": -1,
"filename": "docstringify-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "50b6d225bdeb8e5af5458667750206e2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 44108,
"upload_time": "2025-07-13T22:43:32",
"upload_time_iso_8601": "2025-07-13T22:43:32.047636Z",
"url": "https://files.pythonhosted.org/packages/ff/71/839eab2e80efe45bbb0e030c06183315f2152ecd9384612f8ef22f2d99a0/docstringify-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 22:43:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stefmolin",
"github_project": "docstringify",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "docstringify"
}
JSON
