# pyformatter
[](https://github.com/RikGhosh487/pyformatter/actions)
[](https://github.com/RikGhosh487/pyformatter/actions)
[](https://www.python.org/downloads/release/python-3110/)
[](https://opensource.org/licenses/MIT)
**pyformatter** is a suite of Python formatting tools that automatically formats your docstrings and comments according to configurable style guidelines. It consists of two powerful formatters:
- **pydocfmt**: Formats Python docstrings with support for Google-style docstrings
- **pycommentfmt**: Formats Python comments to ensure proper line length and readability
---
## Key Features
### pydocfmt
- **Google-style docstring formatting**: Complete support for Google docstring conventions
- **Multi-line summary handling**: Intelligently formats long summaries that span multiple lines
- **Smart section parsing**: Properly handles Args, Returns, Raises, Examples, and other sections
- **Code block preservation**: Maintains formatting within Examples sections with automatic fencing
- **Type annotation support**: Handles parameter type annotations gracefully
- **Blank line management**: Ensures proper spacing between summary, description, and sections
### pycommentfmt
- **Intelligent comment wrapping**: Respects line length while preserving meaning
- **Inline vs block comment handling**: Different formatting strategies for different comment types
- **Special comment preservation**: Maintains pylint, mypy, and other tool directives
- **Smart spacing**: Ensures consistent spacing between code and comments
---
## Table of Contents
- [Key Features](#key-features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Command Line Usage](#command-line-usage)
- [pydocfmt](#pydocfmt)
- [pycommentfmt](#pycommentfmt)
- [Configuration](#configuration)
- [Examples](#examples)
- [Integration](#integration)
- [Pre-commit](#pre-commit)
- [Editor Integration](#editor-integration)
- [Security](#security)
- [Contributing](#contributing)
- [License](#license)
---
## Installation
Install pyformatter via pip:
```bash
pip install python-doc-formatter
```
Or install from source:
```bash
git clone https://github.com/RikGhosh487/pyformatter.git
cd pyformatter
pip install -e .
```
---
## Quick Start
Format all Python files in your project:
```bash
# Format docstrings
pydocfmt src/
# Format comments
pycommentfmt src/
# Check formatting without making changes
pydocfmt --check src/
pycommentfmt --check src/
```
---
## Command Line Usage
### pydocfmt
Format Python docstrings with intelligent Google-style docstring support.
```bash
pydocfmt [OPTIONS] [FILES/DIRECTORIES]
```
**Options:**
- `--line-length INTEGER`: Maximum line length for docstrings (default: 88)
- `--check`: Check if files are formatted correctly without modifying them
- `--include TEXT`: Regex pattern for files to include
- `--exclude TEXT`: Regex pattern for files to exclude
- `--help`: Show help message and exit
**Examples:**
```bash
# Format specific files
pydocfmt myfile.py another_file.py
# Format entire directory
pydocfmt src/
# Check formatting without changes
pydocfmt --check src/
# Custom line length
pydocfmt --line-length 100 src/
# Include/exclude patterns
pydocfmt --include ".*\.py$" --exclude "test_.*\.py$" src/
```
### pycommentfmt
Format Python comments to ensure proper line length and readability.
```bash
pycommentfmt [OPTIONS] [FILES/DIRECTORIES]
```
**Options:**
- `--line-length INTEGER`: Maximum line length for comments (default: 88)
- `--check`: Check if files are formatted correctly without modifying them
- `--include TEXT`: Regex pattern for files to include
- `--exclude TEXT`: Regex pattern for files to exclude
- `--help`: Show help message and exit
**Examples:**
```bash
# Format specific files
pycommentfmt myfile.py
# Format entire directory
pycommentfmt src/
# Check formatting without changes
pycommentfmt --check src/
# Custom line length
pycommentfmt --line-length 79 src/
```
---
## Configuration
pyformatter can be configured via `pyproject.toml`:
```toml
[tool.pydocfmt]
line_length = 88
exclude = '(^tests/data/|build/)'
[tool.pycommentfmt]
line_length = 88
exclude = '(^tests/data/|build/)'
```
**Configuration Options:**
- `line_length`: Maximum line length (default: 88)
- `exclude`: Regex pattern for files/directories to exclude
---
## Examples
### Before and After: pydocfmt
**Before:**
```python
def calculate_mean(numbers):
"""Calculate the arithmetic mean of a list of numbers.
This function calculates the arithmetic mean of a list of numbers and returns the result as a float value."""
return sum(numbers) / len(numbers)
```
**After:**
```python
def calculate_mean(numbers):
"""Calculate the arithmetic mean of a list of numbers.
This function calculates the arithmetic mean of a list of numbers and returns the
result as a float value.
"""
return sum(numbers) / len(numbers)
```
### Before and After: pycommentfmt
**Before:**
```python
# This is a very long comment that exceeds the line length limit and should be wrapped to multiple lines for better readability
x = 42
```
**After:**
```python
# This is a very long comment that exceeds the line length limit and should be
# wrapped to multiple lines for better readability
x = 42
```
---
## Integration
### Pre-commit
Add pyformatter to your `.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/RikGhosh487/pyformatter
rev: v0.1.0 # Use the ref you want to point at
hooks:
- id: pydocfmt
args: [--line-length=88]
- id: pycommentfmt
args: [--line-length=88]
```
**Available hooks:**
- `pydocfmt`: Format docstrings (modifies files)
- `pydocfmt-check`: Check docstring formatting (read-only)
- `pycommentfmt`: Format comments (modifies files)
- `pycommentfmt-check`: Check comment formatting (read-only)
**Common configurations:**
```yaml
# Basic usage
- id: pydocfmt
- id: pycommentfmt
# Custom line length
- id: pydocfmt
args: [--line-length=100]
# Check only (for CI)
- id: pydocfmt-check
- id: pycommentfmt-check
# With file exclusions
- id: pydocfmt
args: [--exclude=tests/.*]
```
### Editor Integration
pyformatter works great with:
- **VS Code**: Use with the Python extension
- **PyCharm**: Configure as an external tool
- **Vim/Neovim**: Integrate with formatting plugins
---
## Why pyformatter?
- **Uncompromising**: Consistent formatting across your entire codebase
- **Fast**: Efficiently processes large codebases
- **Configurable**: Adapt to your team's style preferences
- **Reliable**: Extensively tested with comprehensive test suite
- **Simple**: Easy to integrate into existing workflows
---
## Security
Security is important to us. If you discover a security vulnerability, please report it responsibly by following our [Security Policy](SECURITY.md).
For general security best practices when using pyformatter:
- Always review changes made by pyformatter before committing
- Keep pyformatter updated to the latest version
- When processing untrusted code, consider running pyformatter in an isolated environment
---
## Contributing
Contributions are welcome! We appreciate bug reports, feature requests, documentation improvements, and code contributions.
For detailed information on how to contribute, please see our [Contributing Guide](CONTRIBUTING.md).
**Quick Start for Contributors:**
1. Fork the repository and clone your fork
2. Set up the development environment: `pip install -e .[dev]`
3. Install pre-commit hooks: `pre-commit install`
4. Make your changes and add tests
5. Run the test suite: `python -m unittest discover -s tests -v`
6. Submit a pull request
For bug reports and feature requests, please [open an issue](https://github.com/RikGhosh487/pyformatter/issues).
---
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## Acknowledgments
Inspired by the excellent work of:
- [Black](https://github.com/psf/black) - The uncompromising Python code formatter
- [isort](https://github.com/PyCQA/isort) - A Python utility to sort imports
- [docformatter](https://github.com/PyCQA/docformatter) - Formats docstrings to follow conventions
---
*pyformatter: Because every comment and docstring deserves to be beautiful.*
Raw data
{
"_id": null,
"home_page": null,
"name": "python-doc-formatter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Rik Ghosh <rikghosh487@gmail.com>",
"keywords": "formatter, docstring, comment, python, code-quality, linting",
"author": null,
"author_email": "Rik Ghosh <rikghosh487@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/87/85/e6e5203038ab8c0421609629be4bf1bc541cb69e8cadf7942ac3d7798546/python_doc_formatter-0.1.1.tar.gz",
"platform": null,
"description": "# pyformatter\r\n\r\n[](https://github.com/RikGhosh487/pyformatter/actions)\r\n[](https://github.com/RikGhosh487/pyformatter/actions)\r\n[](https://www.python.org/downloads/release/python-3110/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n**pyformatter** is a suite of Python formatting tools that automatically formats your docstrings and comments according to configurable style guidelines. It consists of two powerful formatters:\r\n\r\n- **pydocfmt**: Formats Python docstrings with support for Google-style docstrings\r\n- **pycommentfmt**: Formats Python comments to ensure proper line length and readability\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n### pydocfmt\r\n- **Google-style docstring formatting**: Complete support for Google docstring conventions\r\n- **Multi-line summary handling**: Intelligently formats long summaries that span multiple lines\r\n- **Smart section parsing**: Properly handles Args, Returns, Raises, Examples, and other sections\r\n- **Code block preservation**: Maintains formatting within Examples sections with automatic fencing\r\n- **Type annotation support**: Handles parameter type annotations gracefully\r\n- **Blank line management**: Ensures proper spacing between summary, description, and sections\r\n\r\n### pycommentfmt\r\n- **Intelligent comment wrapping**: Respects line length while preserving meaning\r\n- **Inline vs block comment handling**: Different formatting strategies for different comment types\r\n- **Special comment preservation**: Maintains pylint, mypy, and other tool directives\r\n- **Smart spacing**: Ensures consistent spacing between code and comments\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n- [Key Features](#key-features)\r\n- [Installation](#installation)\r\n- [Quick Start](#quick-start)\r\n- [Command Line Usage](#command-line-usage)\r\n - [pydocfmt](#pydocfmt)\r\n - [pycommentfmt](#pycommentfmt)\r\n- [Configuration](#configuration)\r\n- [Examples](#examples)\r\n- [Integration](#integration)\r\n - [Pre-commit](#pre-commit)\r\n - [Editor Integration](#editor-integration)\r\n- [Security](#security)\r\n- [Contributing](#contributing)\r\n- [License](#license)\r\n\r\n---\r\n\r\n## Installation\r\n\r\nInstall pyformatter via pip:\r\n\r\n```bash\r\npip install python-doc-formatter\r\n```\r\n\r\nOr install from source:\r\n\r\n```bash\r\ngit clone https://github.com/RikGhosh487/pyformatter.git\r\ncd pyformatter\r\npip install -e .\r\n```\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\nFormat all Python files in your project:\r\n\r\n```bash\r\n# Format docstrings\r\npydocfmt src/\r\n\r\n# Format comments \r\npycommentfmt src/\r\n\r\n# Check formatting without making changes\r\npydocfmt --check src/\r\npycommentfmt --check src/\r\n```\r\n\r\n---\r\n\r\n## Command Line Usage\r\n\r\n### pydocfmt\r\n\r\nFormat Python docstrings with intelligent Google-style docstring support.\r\n\r\n```bash\r\npydocfmt [OPTIONS] [FILES/DIRECTORIES]\r\n```\r\n\r\n**Options:**\r\n- `--line-length INTEGER`: Maximum line length for docstrings (default: 88)\r\n- `--check`: Check if files are formatted correctly without modifying them\r\n- `--include TEXT`: Regex pattern for files to include\r\n- `--exclude TEXT`: Regex pattern for files to exclude\r\n- `--help`: Show help message and exit\r\n\r\n**Examples:**\r\n```bash\r\n# Format specific files\r\npydocfmt myfile.py another_file.py\r\n\r\n# Format entire directory\r\npydocfmt src/\r\n\r\n# Check formatting without changes\r\npydocfmt --check src/\r\n\r\n# Custom line length\r\npydocfmt --line-length 100 src/\r\n\r\n# Include/exclude patterns\r\npydocfmt --include \".*\\.py$\" --exclude \"test_.*\\.py$\" src/\r\n```\r\n\r\n### pycommentfmt\r\n\r\nFormat Python comments to ensure proper line length and readability.\r\n\r\n```bash\r\npycommentfmt [OPTIONS] [FILES/DIRECTORIES]\r\n```\r\n\r\n**Options:**\r\n- `--line-length INTEGER`: Maximum line length for comments (default: 88)\r\n- `--check`: Check if files are formatted correctly without modifying them\r\n- `--include TEXT`: Regex pattern for files to include\r\n- `--exclude TEXT`: Regex pattern for files to exclude\r\n- `--help`: Show help message and exit\r\n\r\n**Examples:**\r\n```bash\r\n# Format specific files\r\npycommentfmt myfile.py\r\n\r\n# Format entire directory\r\npycommentfmt src/\r\n\r\n# Check formatting without changes\r\npycommentfmt --check src/\r\n\r\n# Custom line length\r\npycommentfmt --line-length 79 src/\r\n```\r\n\r\n---\r\n\r\n## Configuration\r\n\r\npyformatter can be configured via `pyproject.toml`:\r\n\r\n```toml\r\n[tool.pydocfmt]\r\nline_length = 88\r\nexclude = '(^tests/data/|build/)'\r\n\r\n[tool.pycommentfmt]\r\nline_length = 88\r\nexclude = '(^tests/data/|build/)'\r\n```\r\n\r\n**Configuration Options:**\r\n- `line_length`: Maximum line length (default: 88)\r\n- `exclude`: Regex pattern for files/directories to exclude\r\n\r\n---\r\n\r\n## Examples\r\n\r\n### Before and After: pydocfmt\r\n\r\n**Before:**\r\n```python\r\ndef calculate_mean(numbers):\r\n \"\"\"Calculate the arithmetic mean of a list of numbers.\r\n \r\n This function calculates the arithmetic mean of a list of numbers and returns the result as a float value.\"\"\"\r\n return sum(numbers) / len(numbers)\r\n```\r\n\r\n**After:**\r\n```python\r\ndef calculate_mean(numbers):\r\n \"\"\"Calculate the arithmetic mean of a list of numbers.\r\n \r\n This function calculates the arithmetic mean of a list of numbers and returns the\r\n result as a float value.\r\n \"\"\"\r\n return sum(numbers) / len(numbers)\r\n```\r\n\r\n### Before and After: pycommentfmt\r\n\r\n**Before:**\r\n```python\r\n# This is a very long comment that exceeds the line length limit and should be wrapped to multiple lines for better readability\r\nx = 42\r\n```\r\n\r\n**After:**\r\n```python\r\n# This is a very long comment that exceeds the line length limit and should be\r\n# wrapped to multiple lines for better readability\r\nx = 42\r\n```\r\n\r\n---\r\n\r\n## Integration\r\n\r\n### Pre-commit\r\n\r\nAdd pyformatter to your `.pre-commit-config.yaml`:\r\n\r\n```yaml\r\nrepos:\r\n - repo: https://github.com/RikGhosh487/pyformatter\r\n rev: v0.1.0 # Use the ref you want to point at\r\n hooks:\r\n - id: pydocfmt\r\n args: [--line-length=88]\r\n - id: pycommentfmt\r\n args: [--line-length=88]\r\n```\r\n\r\n**Available hooks:**\r\n- `pydocfmt`: Format docstrings (modifies files)\r\n- `pydocfmt-check`: Check docstring formatting (read-only)\r\n- `pycommentfmt`: Format comments (modifies files)\r\n- `pycommentfmt-check`: Check comment formatting (read-only)\r\n\r\n**Common configurations:**\r\n```yaml\r\n# Basic usage\r\n- id: pydocfmt\r\n- id: pycommentfmt\r\n\r\n# Custom line length\r\n- id: pydocfmt\r\n args: [--line-length=100]\r\n\r\n# Check only (for CI)\r\n- id: pydocfmt-check\r\n- id: pycommentfmt-check\r\n\r\n# With file exclusions\r\n- id: pydocfmt\r\n args: [--exclude=tests/.*]\r\n```\r\n\r\n### Editor Integration\r\n\r\npyformatter works great with:\r\n- **VS Code**: Use with the Python extension\r\n- **PyCharm**: Configure as an external tool\r\n- **Vim/Neovim**: Integrate with formatting plugins\r\n\r\n---\r\n\r\n## Why pyformatter?\r\n\r\n- **Uncompromising**: Consistent formatting across your entire codebase\r\n- **Fast**: Efficiently processes large codebases\r\n- **Configurable**: Adapt to your team's style preferences\r\n- **Reliable**: Extensively tested with comprehensive test suite\r\n- **Simple**: Easy to integrate into existing workflows\r\n\r\n---\r\n\r\n## Security\r\n\r\nSecurity is important to us. If you discover a security vulnerability, please report it responsibly by following our [Security Policy](SECURITY.md).\r\n\r\nFor general security best practices when using pyformatter:\r\n- Always review changes made by pyformatter before committing\r\n- Keep pyformatter updated to the latest version\r\n- When processing untrusted code, consider running pyformatter in an isolated environment\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nContributions are welcome! We appreciate bug reports, feature requests, documentation improvements, and code contributions.\r\n\r\nFor detailed information on how to contribute, please see our [Contributing Guide](CONTRIBUTING.md).\r\n\r\n**Quick Start for Contributors:**\r\n1. Fork the repository and clone your fork\r\n2. Set up the development environment: `pip install -e .[dev]`\r\n3. Install pre-commit hooks: `pre-commit install`\r\n4. Make your changes and add tests\r\n5. Run the test suite: `python -m unittest discover -s tests -v`\r\n6. Submit a pull request\r\n\r\nFor bug reports and feature requests, please [open an issue](https://github.com/RikGhosh487/pyformatter/issues).\r\n\r\n---\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n---\r\n\r\n## Acknowledgments\r\n\r\nInspired by the excellent work of:\r\n- [Black](https://github.com/psf/black) - The uncompromising Python code formatter\r\n- [isort](https://github.com/PyCQA/isort) - A Python utility to sort imports\r\n- [docformatter](https://github.com/PyCQA/docformatter) - Formats docstrings to follow conventions\r\n\r\n---\r\n\r\n*pyformatter: Because every comment and docstring deserves to be beautiful.*\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python annotation formatter for line-wrapping and formatting python comments and docstrings",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://github.com/RikGhosh487/pyformatter/blob/main/CHANGELOG.md",
"Contributing": "https://github.com/RikGhosh487/pyformatter/blob/main/CONTRIBUTING.md",
"Homepage": "https://github.com/RikGhosh487/pyformatter",
"Issues": "https://github.com/RikGhosh487/pyformatter/issues",
"Repository": "https://github.com/RikGhosh487/pyformatter",
"Security": "https://github.com/RikGhosh487/pyformatter/blob/main/SECURITY.md"
},
"split_keywords": [
"formatter",
" docstring",
" comment",
" python",
" code-quality",
" linting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "64f5eb85ac244b278290c6fe146f86bf7ecdd03db49738250c1584b48404586e",
"md5": "06a4cafb6c23a53503162f6cbabe4544",
"sha256": "05ffea4ca08e0ab1c63a5bf9989555c5a2d07d0195b46bf0e09b2da9fb4b2908"
},
"downloads": -1,
"filename": "python_doc_formatter-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "06a4cafb6c23a53503162f6cbabe4544",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 15991,
"upload_time": "2025-07-31T18:48:43",
"upload_time_iso_8601": "2025-07-31T18:48:43.940445Z",
"url": "https://files.pythonhosted.org/packages/64/f5/eb85ac244b278290c6fe146f86bf7ecdd03db49738250c1584b48404586e/python_doc_formatter-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8785e6e5203038ab8c0421609629be4bf1bc541cb69e8cadf7942ac3d7798546",
"md5": "5598ae371cfe045db15425fbeb1ca361",
"sha256": "c696feb2bd383f99387fb903bbaa4522e762b28f63f32931c94a84b1ac5e5fdb"
},
"downloads": -1,
"filename": "python_doc_formatter-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "5598ae371cfe045db15425fbeb1ca361",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 19161,
"upload_time": "2025-07-31T18:48:45",
"upload_time_iso_8601": "2025-07-31T18:48:45.325511Z",
"url": "https://files.pythonhosted.org/packages/87/85/e6e5203038ab8c0421609629be4bf1bc541cb69e8cadf7942ac3d7798546/python_doc_formatter-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 18:48:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RikGhosh487",
"github_project": "pyformatter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "python-doc-formatter"
}
JSON
