# format-docstring
A Python formatter to automatically format numpy-style docstrings.
______________________________________________________________________
**Table of Contents:**
<!--TOC-->
- [1. Overview](#1-overview)
- [2. Before vs After Examples](#2-before-vs-after-examples)
- [2.1. Long lines are wrapped to fit line length limit](#21-long-lines-are-wrapped-to-fit-line-length-limit)
- [2.2. One-line summaries are formatted to fit line length limit](#22-one-line-summaries-are-formatted-to-fit-line-length-limit)
- [2.3. Minor typos can be automatically fixed](#23-minor-typos-can-be-automatically-fixed)
- [2.4. Default value declarations are standardized](#24-default-value-declarations-are-standardized)
- [2.5. Single backticks are converted to double backticks (rST syntax)](#25-single-backticks-are-converted-to-double-backticks-rst-syntax)
- [2.6. Docstring parameters and returns stay in sync with signatures](#26-docstring-parameters-and-returns-stay-in-sync-with-signatures)
- [3. Installation](#3-installation)
- [4. Usage](#4-usage)
- [4.1. Command Line Interface](#41-command-line-interface)
- [4.2. Pre-commit Hook](#42-pre-commit-hook)
- [4.3. Opting Out of Formatting](#43-opting-out-of-formatting)
- [5. Configuration](#5-configuration)
- [5.1. Command-Line Options](#51-command-line-options)
- [5.2. Usage Examples](#52-usage-examples)
- [5.3. `pyproject.toml` Configuration](#53-pyprojecttoml-configuration)
- [6. Caveat](#6-caveat)
<!--TOC-->
______________________________________________________________________
## 1. Overview
`format-docstring` is a tool that automatically formats and wraps docstring
content in Python files and Jupyter notebooks.
Baseline reflow corresponds to the common docstring cleanups offered by
general-purpose formatters: splitting one-line docstrings into the canonical
multi-line layout (triple quotes, blank line, summary), normalizing
indentation, and wrapping text at a fixed column width without applying extra
heuristics.
| Feature | `format-docstring` | [docformatter] | [pydocstringformatter] | [Ruff] | [Black] |
| ----------------------------------------- | ------------------ | -------------- | ---------------------- | ------ | ------- |
| Docstring wrapping | ✅ | ❌ | ❌ | ❌ | ❌ |
| Compatible with line length linter (E501) | ✅ | ❌ | ❌ | N/A | N/A |
| Fixes common docstring typos | ✅ | ❌ | ❌ | ❌ | ❌ |
## 2. Before vs After Examples
### 2.1. Long lines are wrapped to fit line length limit
```diff
def example_function(param1, param2, option='default'):
- """This summary line is intentionally very long and exceeds the line length limit to demonstrate that format-docstring will automatically wrap it across multiple lines while preserving code structure.
+ """
+ This summary line is intentionally very long and exceeds the line length
+ limit to demonstrate that format-docstring will automatically wrap it
+ across multiple lines while preserving code structure.
Parameters
----------
- param1 : str
- This parameter description is also intentionally long to show how parameter descriptions get wrapped when they exceed the configured line length limit
- param2 : int
- Another long parameter description that demonstrates the wrapping behavior for parameter documentation in NumPy-style docstrings
+ param1 : str
+ This parameter description is also intentionally long to show how
+ parameter descriptions get wrapped when they exceed the configured
+ line length limit
+ param2 : int
+ Another long parameter description that demonstrates the wrapping
+ behavior for parameter documentation in NumPy-style docstrings
option : str, optional
Short description (not wrapped)
Returns
-------
dict
- The return value wrapped, because it is a very long line that exceeds line length limit by a lot.
+ The return value wrapped, because it is a very long line that exceeds
+ line length limit by a lot.
Examples
--------
Within the "Examples" section, code with >>> prompts are preserved without
wrapping:
>>> result = example_function('test', 42, option='custom_value_with_a_very_long_name_that_exceeds_line_length')
>>> print(result)
{'status': 'success'}
rST tables are preserved without wrapping:
=========== ================== ===============================
Format Wrapped Preserved
=========== ================== ===============================
Text Yes No (in tables, code, lists)
Params Yes Signature lines preserved
=========== ================== ===============================
Contents following double colons (`::`) are preserved::
P(B|A) P(A)
P(A|B) = -------------
P(B)
Even if there isn't an extra blank line after `::`, the contents are still
preserved::
_______
σ = √ Var(X)
Regular bullet lists are also preserved:
- First bullet point that is intentionally long but not wrapped
- Second point also stays on one line regardless of length
"""
```
### 2.2. One-line summaries are formatted to fit line length limit
```diff
def my_function():
- """Contents are short, but with quotation marks this exceeds length limit."""
+ """
+ Contents are short, but with quotation marks this exceeds length limit.
+ """
pass
```
### 2.3. Minor typos can be automatically fixed
```diff
def mu_function():
"""
Minor typos in section titles or "signatures" can be fixed.
- Parameter
- ----
+ Parameters
+ ----------
arg1 : str
Arg 1
arg2 : bool
Arg 2
- arg3: int
+ arg3 : int
Arg 3
- arg4 : int
+ arg4 : int
Arg 4
- ReTurn
- ----------
+ Returns
+ -------
int
The return value
"""
pass
```
or, Google-style section headers can be fixed:
```diff
def my_function():
"""
My function
- Args:
- ----
+ Parameters
+ ----------
arg1 : str
Arg 1
...
"""
pass
```
### 2.4. Default value declarations are standardized
```diff
def example_function(arg1, arg2, arg3, arg4):
"""
Parameters
----------
- arg1 : int default 10
+ arg1 : int, default=10
First argument
- arg2 : str, default "hello"
+ arg2 : str, default="hello"
Second argument
- arg3 : bool, default is True
+ arg3 : bool, default=True
Third argument
- arg4 : float default: 3.14
+ arg4 : float, default=3.14
Fourth argument
"""
pass
```
### 2.5. Single backticks are converted to double backticks (rST syntax)
```diff
def process_data(data):
"""
- Process data using the `transform` function.
+ Process data using the ``transform`` function.
Parameters
----------
data : dict
- Input data with keys `id`, `value`, and `timestamp`.
+ Input data with keys ``id``, ``value``, and ``timestamp``.
Returns
-------
dict
- Processed data with key `result`.
+ Processed data with key ``result``.
"""
```
### 2.6. Docstring parameters and returns stay in sync with signatures
```diff
from typing import List, Optional
def create_user(
user: Optional[str] = None,
roles: List["Role"] | None = None,
retries: int = 0,
serializer: "Serializer" | None = None,
something_else: tuple[int, ...] = (
"1",
'2',
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
),
) -> None:
"""
Parameters
----------
- user : str
+ user : Optional[str], default=None
Login name.
- roles : list
+ roles : List["Role"] | None, default=None
Assigned roles.
- retries : int
+ retries : int, default=0
Number of retry attempts.
- serializer : Serializer, optional
+ serializer : "Serializer" | None, default=None
Custom serializer instance.
- something_else : tuple[int, ...]
+ something_else : tuple[int, ...], default=("1", '2', 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
"""
pass
```
And return type hint:
```diff
def build_mapping() -> dict[str, str]:
"""
Returns
-------
- str
+ dict[str, str]
Mapping of values.
"""
```
For tuple return annotations, tuple elements are split across multiple
signature lines only when the docstring already adopted that layout:
```diff
def compute_values() -> tuple[int, str, list[str]]:
"""
Returns
-------
- float
+ int
First element.
- str
+ str
Second element.
- List[str]
+ list[str]
Third element.
"""
```
Annotations and defaults are extracted from the actual function signature, so
docstring signature lines reflect the ground truth. Defaulted parameters omit
redundant `, optional`, forward references keep their original quoting, and
return signatures track tuple splitting conventions already present in the
docstring.
## 3. Installation
```bash
pip install format-docstring
```
## 4. Usage
### 4.1. Command Line Interface
**For Python files:**
```bash
format-docstring path/to/file.py
format-docstring path/to/directory/
```
**For Jupyter notebooks:**
```bash
format-docstring-jupyter path/to/notebook.ipynb
format-docstring-jupyter path/to/directory/
```
### 4.2. Pre-commit Hook
To use `format-docstring` as a pre-commit hook, add this to your
`.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/jsh9/format-docstring
rev: <LATEST_VERSION>
hooks:
- id: format-docstring
name: Format docstrings in .py files
args: [--line-length=79]
- id: format-docstring-jupyter
name: Format docstrings in .ipynb files
args: [--line-length=79]
```
Then install the pre-commit hook:
```bash
pre-commit install
```
### 4.3. Opting Out of Formatting
Add a comment containing `no-format-docstring` on the same line as the closing
triple quotes to prevent the formatter from touching that docstring:
`""" ... """ # no-format-docstring`.
You can combine this "no-format-docstring" with other directives like "noqa".
Tip: If you only want to keep specific formatter changes inside a docstring,
first run `format-docstring`, accept the parts you like, revert the edits you
dislike, and then add an inline `# no-format-docstring` comment so future runs
leave that docstring untouched.
## 5. Configuration
### 5.1. Command-Line Options
- `--line-length INTEGER`: Maximum line length for wrapping docstrings
(default: 79)
- `--docstring-style CHOICE`: Docstring style to target (`numpy` or `google`,
default: `numpy`). Note: Currently only `numpy` style is fully supported.
- `--fix-rst-backticks BOOL`: Automatically fix single backticks to double
backticks per rST syntax (default: True)
- `--verbose CHOICE`: Logging detail level (`default` keeps the existing
behaviour, `diff` prints unified diffs when rewrites happen)
- `--exclude TEXT`: Regex pattern to exclude files/directories (default:
`\.git|\.tox|\.pytest_cache`)
- `--config PATH`: Path to a `pyproject.toml` config file. If not specified,
the tool automatically searches for `pyproject.toml` in parent directories.
Command-line options take precedence over config file settings.
- `--version`: Show version information
- `--help`: Show help message
### 5.2. Usage Examples
```bash
# Format a single file with default settings
format-docstring my_module.py
# Format all Python files in a directory with custom line length
format-docstring --line-length 72 src/
# Format Jupyter notebooks excluding certain directories
format-docstring-jupyter --exclude "\.git|\.venv|__pycache__" notebooks/
# Preview changes with unified diffs
format-docstring --verbose diff src/
# Use a specific config file
format-docstring --config path/to/pyproject.toml src/
# CLI options override config file settings
format-docstring --config pyproject.toml --line-length 100 src/
# Disable backtick fixing
format-docstring --fix-rst-backticks=False my_module.py
```
### 5.3. `pyproject.toml` Configuration
You can configure default values in your `pyproject.toml`. CLI arguments will
override these settings:
```toml
[tool.format_docstring]
line_length = 79
docstring_style = "numpy"
fix_rst_backticks = true
exclude = "\\.git|\\.venv|__pycache__"
verbose = "default" # or "diff" to print unified diffs
```
**Available options:**
- `line_length` (int): Maximum line length for wrapping docstrings (default:
79\)
- `docstring_style` (str): Docstring style, either `"numpy"` or `"google"`
(default: `"numpy"`)
- `fix_rst_backticks` (bool): Automatically fix single backticks to double
backticks per rST syntax (default: `true`)
- `exclude` (str): Regex pattern to exclude files/directories (default:
`"\\.git|\\.tox|\\.pytest_cache"`)
- `verbose` (str): Logging detail level (`"default"` or `"diff"`)
The tool searches for `pyproject.toml` starting from the target file/directory
and walking up the parent directories until one is found.
## 6. Caveat
This tool assumes the docstrings are written in **mostly** the correct format,
because it needs those formatting cues (such as section headers and `------`)
to parse docstrings.
If the docstrings are far from perfectly formatted, it's recommended that you
use AI coding assistants to rewrite the docstrings first.
[black]: https://github.com/psf/black
[docformatter]: https://github.com/PyCQA/docformatter
[pydocstringformatter]: https://github.com/DanielNoord/pydocstringformatter
[ruff]: https://github.com/astral-sh/ruff
Raw data
{
"_id": null,
"home_page": null,
"name": "format-docstring",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "jsh9 <25124332+jsh9@users.noreply.github.com>",
"keywords": "formatter, code-style, docstring, python",
"author": null,
"author_email": "jsh9 <25124332+jsh9@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/0f/46/1c8f33d0903c308cd85c87db17eee28b033805d27db477bba5825c6346c8/format_docstring-0.2.2.tar.gz",
"platform": null,
"description": "# format-docstring\n\nA Python formatter to automatically format numpy-style docstrings.\n\n______________________________________________________________________\n\n**Table of Contents:**\n\n<!--TOC-->\n\n- [1. Overview](#1-overview)\n- [2. Before vs After Examples](#2-before-vs-after-examples)\n - [2.1. Long lines are wrapped to fit line length limit](#21-long-lines-are-wrapped-to-fit-line-length-limit)\n - [2.2. One-line summaries are formatted to fit line length limit](#22-one-line-summaries-are-formatted-to-fit-line-length-limit)\n - [2.3. Minor typos can be automatically fixed](#23-minor-typos-can-be-automatically-fixed)\n - [2.4. Default value declarations are standardized](#24-default-value-declarations-are-standardized)\n - [2.5. Single backticks are converted to double backticks (rST syntax)](#25-single-backticks-are-converted-to-double-backticks-rst-syntax)\n - [2.6. Docstring parameters and returns stay in sync with signatures](#26-docstring-parameters-and-returns-stay-in-sync-with-signatures)\n- [3. Installation](#3-installation)\n- [4. Usage](#4-usage)\n - [4.1. Command Line Interface](#41-command-line-interface)\n - [4.2. Pre-commit Hook](#42-pre-commit-hook)\n - [4.3. Opting Out of Formatting](#43-opting-out-of-formatting)\n- [5. Configuration](#5-configuration)\n - [5.1. Command-Line Options](#51-command-line-options)\n - [5.2. Usage Examples](#52-usage-examples)\n - [5.3. `pyproject.toml` Configuration](#53-pyprojecttoml-configuration)\n- [6. Caveat](#6-caveat)\n\n<!--TOC-->\n\n______________________________________________________________________\n\n## 1. Overview\n\n`format-docstring` is a tool that automatically formats and wraps docstring\ncontent in Python files and Jupyter notebooks.\n\nBaseline reflow corresponds to the common docstring cleanups offered by\ngeneral-purpose formatters: splitting one-line docstrings into the canonical\nmulti-line layout (triple quotes, blank line, summary), normalizing\nindentation, and wrapping text at a fixed column width without applying extra\nheuristics.\n\n| Feature | `format-docstring` | [docformatter] | [pydocstringformatter] | [Ruff] | [Black] |\n| ----------------------------------------- | ------------------ | -------------- | ---------------------- | ------ | ------- |\n| Docstring wrapping | \u2705 | \u274c | \u274c | \u274c | \u274c |\n| Compatible with line length linter (E501) | \u2705 | \u274c | \u274c | N/A | N/A |\n| Fixes common docstring typos | \u2705 | \u274c | \u274c | \u274c | \u274c |\n\n## 2. Before vs After Examples\n\n### 2.1. Long lines are wrapped to fit line length limit\n\n```diff\ndef example_function(param1, param2, option='default'):\n- \"\"\"This summary line is intentionally very long and exceeds the line length limit to demonstrate that format-docstring will automatically wrap it across multiple lines while preserving code structure.\n+ \"\"\"\n+ This summary line is intentionally very long and exceeds the line length\n+ limit to demonstrate that format-docstring will automatically wrap it\n+ across multiple lines while preserving code structure.\n\n Parameters\n ----------\n- param1 : str\n- This parameter description is also intentionally long to show how parameter descriptions get wrapped when they exceed the configured line length limit\n- param2 : int\n- Another long parameter description that demonstrates the wrapping behavior for parameter documentation in NumPy-style docstrings\n+ param1 : str\n+ This parameter description is also intentionally long to show how\n+ parameter descriptions get wrapped when they exceed the configured\n+ line length limit\n+ param2 : int\n+ Another long parameter description that demonstrates the wrapping\n+ behavior for parameter documentation in NumPy-style docstrings\n option : str, optional\n Short description (not wrapped)\n\n Returns\n -------\n dict\n- The return value wrapped, because it is a very long line that exceeds line length limit by a lot.\n+ The return value wrapped, because it is a very long line that exceeds\n+ line length limit by a lot.\n\n Examples\n --------\n Within the \"Examples\" section, code with >>> prompts are preserved without\n wrapping:\n\n >>> result = example_function('test', 42, option='custom_value_with_a_very_long_name_that_exceeds_line_length')\n >>> print(result)\n {'status': 'success'}\n\n rST tables are preserved without wrapping:\n\n =========== ================== ===============================\n Format Wrapped Preserved\n =========== ================== ===============================\n Text Yes No (in tables, code, lists)\n Params Yes Signature lines preserved\n =========== ================== ===============================\n\n Contents following double colons (`::`) are preserved::\n\n P(B|A) P(A)\n P(A|B) = -------------\n P(B)\n\n Even if there isn't an extra blank line after `::`, the contents are still\n preserved::\n _______\n \u03c3 = \u221a Var(X)\n\n Regular bullet lists are also preserved:\n\n - First bullet point that is intentionally long but not wrapped\n - Second point also stays on one line regardless of length\n \"\"\"\n```\n\n### 2.2. One-line summaries are formatted to fit line length limit\n\n```diff\ndef my_function():\n- \"\"\"Contents are short, but with quotation marks this exceeds length limit.\"\"\"\n+ \"\"\"\n+ Contents are short, but with quotation marks this exceeds length limit.\n+ \"\"\"\n pass\n```\n\n### 2.3. Minor typos can be automatically fixed\n\n```diff\ndef mu_function():\n \"\"\"\n Minor typos in section titles or \"signatures\" can be fixed.\n\n- Parameter\n- ----\n+ Parameters\n+ ----------\n arg1 : str\n Arg 1\n arg2 : bool\n Arg 2\n- arg3: int\n+ arg3 : int\n Arg 3\n- arg4 : int\n+ arg4 : int\n Arg 4\n\n- ReTurn\n- ----------\n+ Returns\n+ -------\n int\n The return value\n \"\"\"\n pass\n```\n\nor, Google-style section headers can be fixed:\n\n```diff\ndef my_function():\n \"\"\"\n My function\n\n- Args:\n- ----\n+ Parameters\n+ ----------\n arg1 : str\n Arg 1\n\n ...\n \"\"\"\n pass\n```\n\n### 2.4. Default value declarations are standardized\n\n```diff\ndef example_function(arg1, arg2, arg3, arg4):\n \"\"\"\n Parameters\n ----------\n- arg1 : int default 10\n+ arg1 : int, default=10\n First argument\n- arg2 : str, default \"hello\"\n+ arg2 : str, default=\"hello\"\n Second argument\n- arg3 : bool, default is True\n+ arg3 : bool, default=True\n Third argument\n- arg4 : float default: 3.14\n+ arg4 : float, default=3.14\n Fourth argument\n \"\"\"\n pass\n```\n\n### 2.5. Single backticks are converted to double backticks (rST syntax)\n\n```diff\ndef process_data(data):\n \"\"\"\n- Process data using the `transform` function.\n+ Process data using the ``transform`` function.\n\n Parameters\n ----------\n data : dict\n- Input data with keys `id`, `value`, and `timestamp`.\n+ Input data with keys ``id``, ``value``, and ``timestamp``.\n\n Returns\n -------\n dict\n- Processed data with key `result`.\n+ Processed data with key ``result``.\n \"\"\"\n```\n\n### 2.6. Docstring parameters and returns stay in sync with signatures\n\n```diff\nfrom typing import List, Optional\n\n\ndef create_user(\n user: Optional[str] = None,\n roles: List[\"Role\"] | None = None,\n retries: int = 0,\n serializer: \"Serializer\" | None = None,\n something_else: tuple[int, ...] = (\n \"1\",\n '2',\n 3,\n 4,\n 5,\n 6,\n 7,\n 8,\n 9,\n 10,\n 11,\n 12,\n ),\n) -> None:\n \"\"\"\n Parameters\n ----------\n- user : str\n+ user : Optional[str], default=None\n Login name.\n- roles : list\n+ roles : List[\"Role\"] | None, default=None\n Assigned roles.\n- retries : int\n+ retries : int, default=0\n Number of retry attempts.\n- serializer : Serializer, optional\n+ serializer : \"Serializer\" | None, default=None\n Custom serializer instance.\n- something_else : tuple[int, ...]\n+ something_else : tuple[int, ...], default=(\"1\", '2', 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)\n \"\"\"\n pass\n```\n\nAnd return type hint:\n\n```diff\ndef build_mapping() -> dict[str, str]:\n \"\"\"\n Returns\n -------\n- str\n+ dict[str, str]\n Mapping of values.\n \"\"\"\n```\n\nFor tuple return annotations, tuple elements are split across multiple\nsignature lines only when the docstring already adopted that layout:\n\n```diff\ndef compute_values() -> tuple[int, str, list[str]]:\n \"\"\"\n Returns\n -------\n- float\n+ int\n First element.\n- str\n+ str\n Second element.\n- List[str]\n+ list[str]\n Third element.\n \"\"\"\n```\n\nAnnotations and defaults are extracted from the actual function signature, so\ndocstring signature lines reflect the ground truth. Defaulted parameters omit\nredundant `, optional`, forward references keep their original quoting, and\nreturn signatures track tuple splitting conventions already present in the\ndocstring.\n\n## 3. Installation\n\n```bash\npip install format-docstring\n```\n\n## 4. Usage\n\n### 4.1. Command Line Interface\n\n**For Python files:**\n\n```bash\nformat-docstring path/to/file.py\nformat-docstring path/to/directory/\n```\n\n**For Jupyter notebooks:**\n\n```bash\nformat-docstring-jupyter path/to/notebook.ipynb\nformat-docstring-jupyter path/to/directory/\n```\n\n### 4.2. Pre-commit Hook\n\nTo use `format-docstring` as a pre-commit hook, add this to your\n`.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n - repo: https://github.com/jsh9/format-docstring\n rev: <LATEST_VERSION>\n hooks:\n - id: format-docstring\n name: Format docstrings in .py files\n args: [--line-length=79]\n - id: format-docstring-jupyter\n name: Format docstrings in .ipynb files\n args: [--line-length=79]\n```\n\nThen install the pre-commit hook:\n\n```bash\npre-commit install\n```\n\n### 4.3. Opting Out of Formatting\n\nAdd a comment containing `no-format-docstring` on the same line as the closing\ntriple quotes to prevent the formatter from touching that docstring:\n`\"\"\" ... \"\"\" # no-format-docstring`.\n\nYou can combine this \"no-format-docstring\" with other directives like \"noqa\".\n\nTip: If you only want to keep specific formatter changes inside a docstring,\nfirst run `format-docstring`, accept the parts you like, revert the edits you\ndislike, and then add an inline `# no-format-docstring` comment so future runs\nleave that docstring untouched.\n\n## 5. Configuration\n\n### 5.1. Command-Line Options\n\n- `--line-length INTEGER`: Maximum line length for wrapping docstrings\n (default: 79)\n- `--docstring-style CHOICE`: Docstring style to target (`numpy` or `google`,\n default: `numpy`). Note: Currently only `numpy` style is fully supported.\n- `--fix-rst-backticks BOOL`: Automatically fix single backticks to double\n backticks per rST syntax (default: True)\n- `--verbose CHOICE`: Logging detail level (`default` keeps the existing\n behaviour, `diff` prints unified diffs when rewrites happen)\n- `--exclude TEXT`: Regex pattern to exclude files/directories (default:\n `\\.git|\\.tox|\\.pytest_cache`)\n- `--config PATH`: Path to a `pyproject.toml` config file. If not specified,\n the tool automatically searches for `pyproject.toml` in parent directories.\n Command-line options take precedence over config file settings.\n- `--version`: Show version information\n- `--help`: Show help message\n\n### 5.2. Usage Examples\n\n```bash\n# Format a single file with default settings\nformat-docstring my_module.py\n\n# Format all Python files in a directory with custom line length\nformat-docstring --line-length 72 src/\n\n# Format Jupyter notebooks excluding certain directories\nformat-docstring-jupyter --exclude \"\\.git|\\.venv|__pycache__\" notebooks/\n\n# Preview changes with unified diffs\nformat-docstring --verbose diff src/\n\n# Use a specific config file\nformat-docstring --config path/to/pyproject.toml src/\n\n# CLI options override config file settings\nformat-docstring --config pyproject.toml --line-length 100 src/\n\n# Disable backtick fixing\nformat-docstring --fix-rst-backticks=False my_module.py\n```\n\n### 5.3. `pyproject.toml` Configuration\n\nYou can configure default values in your `pyproject.toml`. CLI arguments will\noverride these settings:\n\n```toml\n[tool.format_docstring]\nline_length = 79\ndocstring_style = \"numpy\"\nfix_rst_backticks = true\nexclude = \"\\\\.git|\\\\.venv|__pycache__\"\nverbose = \"default\" # or \"diff\" to print unified diffs\n```\n\n**Available options:**\n\n- `line_length` (int): Maximum line length for wrapping docstrings (default:\n 79\\)\n- `docstring_style` (str): Docstring style, either `\"numpy\"` or `\"google\"`\n (default: `\"numpy\"`)\n- `fix_rst_backticks` (bool): Automatically fix single backticks to double\n backticks per rST syntax (default: `true`)\n- `exclude` (str): Regex pattern to exclude files/directories (default:\n `\"\\\\.git|\\\\.tox|\\\\.pytest_cache\"`)\n- `verbose` (str): Logging detail level (`\"default\"` or `\"diff\"`)\n\nThe tool searches for `pyproject.toml` starting from the target file/directory\nand walking up the parent directories until one is found.\n\n## 6. Caveat\n\nThis tool assumes the docstrings are written in **mostly** the correct format,\nbecause it needs those formatting cues (such as section headers and `------`)\nto parse docstrings.\n\nIf the docstrings are far from perfectly formatted, it's recommended that you\nuse AI coding assistants to rewrite the docstrings first.\n\n[black]: https://github.com/psf/black\n[docformatter]: https://github.com/PyCQA/docformatter\n[pydocstringformatter]: https://github.com/DanielNoord/pydocstringformatter\n[ruff]: https://github.com/astral-sh/ruff\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python formatter to wrap/adjust docstring lines",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/your/repo",
"Issues": "https://github.com/your/repo/issues",
"Repository": "https://github.com/your/repo.git"
},
"split_keywords": [
"formatter",
" code-style",
" docstring",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "62a6bd0d625b218e97eb3213c1551501d6f1592889c1d477da98dd6e3c1b6842",
"md5": "b59a497b99e2ac68f5d1cc06321e2ccb",
"sha256": "4f44720111c6ef6f6f4724e43de8ecbe80db1f2842a7ddc19d9b388258e05459"
},
"downloads": -1,
"filename": "format_docstring-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b59a497b99e2ac68f5d1cc06321e2ccb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 35637,
"upload_time": "2025-10-20T23:24:59",
"upload_time_iso_8601": "2025-10-20T23:24:59.183280Z",
"url": "https://files.pythonhosted.org/packages/62/a6/bd0d625b218e97eb3213c1551501d6f1592889c1d477da98dd6e3c1b6842/format_docstring-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0f461c8f33d0903c308cd85c87db17eee28b033805d27db477bba5825c6346c8",
"md5": "db1e1eadd601887d98f8c5e9cceeea36",
"sha256": "a2b80ed7cc9583068ec55a51948410ff27eee5b5c0e5036229694110ee7115dc"
},
"downloads": -1,
"filename": "format_docstring-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "db1e1eadd601887d98f8c5e9cceeea36",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 79860,
"upload_time": "2025-10-20T23:25:00",
"upload_time_iso_8601": "2025-10-20T23:25:00.071798Z",
"url": "https://files.pythonhosted.org/packages/0f/46/1c8f33d0903c308cd85c87db17eee28b033805d27db477bba5825c6346c8/format_docstring-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 23:25:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your",
"github_project": "repo",
"github_not_found": true,
"lcname": "format-docstring"
}
JSON
