Metadata-Version: 2.5
Name: def-form
Version: 0.3.0
Summary: Formatter for functions
Project-URL: Homepage, https://github.com/TopNik073/def-form
Project-URL: Repository, https://github.com/TopNik073/def-form
Project-URL: Issues, https://github.com/TopNik073/def-form/issues
Author: TopNik073
License-Expression: MIT
License-File: LICENSE
Keywords: code-formatting,docstrings,formatter,functions,python
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.2.1
Requires-Dist: libcst>=1.8.2
Requires-Dist: rich>=14.3.1
Requires-Dist: tomli>=2.4.0
Description-Content-Type: text/markdown

<p align="center" style="padding-top: 30px;">
  <img src="https://raw.githubusercontent.com/TopNik073/def-form/main/assets/logo-transparent.png" alt="def-form logo" width="300"><br>
  <span style="font-size: 18px;">Python function definition formatter</span>
</p>

<p align="center">
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" style="margin: 0 5px; border: none;"></a>
  <a href="https://pypi.org/project/def-form/"><img src="https://img.shields.io/pypi/v/def-form.svg" alt="PyPI version" style="margin: 0 5px; border: none;"></a>
  <a href="https://pypi.org/project/def-form/"><img src="https://img.shields.io/pypi/dm/def-form.svg" alt="PyPI downloads" style="margin: 0 5px; border: none;"></a>
  <a href="https://coveralls.io/github/TopNik073/def-form?branch=main"><img src="https://coveralls.io/repos/github/TopNik073/def-form/badge.svg?branch=main" alt="Coverage Status" style="margin: 0 5px; border: none;"></a>
</p>

## Overview

`def-form` is a code formatting tool that focuses specifically on Python function definitions. It helps maintain consistent formatting of function signatures by automatically organizing arguments vertically when they exceed specified thresholds.

Long signatures are hard to scan, and different people break them differently — or not at all. `def-form` makes that choice for you and applies it everywhere: every definition past your threshold gets one argument per line, with a trailing comma.

**Before:**

```python
def get_user(session: Session, user_id: int) -> User:
    ...


def create_user(session: Session, name: str, email: str, is_admin: bool = False) -> User:
    ...


class UserRepository:
    def search(self, query: str, *filters: str, limit: int = 20, **options) -> list[User]:
        ...
```

**After** `def-form format` (with `max_inline_args = 2`):

```python
def get_user(session: Session, user_id: int) -> User:
    ...


def create_user(
    session: Session,
    name: str,
    email: str,
    is_admin: bool = False,
) -> User:
    ...


class UserRepository:
    def search(
        self,
        query: str,
        *filters: str,
        limit: int = 20,
        **options,
    ) -> list[User]:
        ...
```

`get_user` is left alone — it stays within the limits. Definitions that are already formatted this way are left untouched too, and a `# def-form: skip` comment excludes a single definition.

## Features

- **Automatic argument formatting**: Converts inline function arguments to vertical format based on configurable rules
- **CI/CD integration**: Provides both `format` and `check` commands for use in development pipelines
- **Configuration file support**: Uses `pyproject.toml` for project-specific settings
- **Customizable thresholds**: Control when arguments should be formatted vertically

## Installation

```bash
pip install def-form
```

## Usage

### Format code

* Format all Python files in a directory:

```bash
def-form format src/
```

* Format a specific file:

```bash
def-form format my_module.py
```

### Check code without formatting

* Check if code follows formatting rules:

```bash
def-form check src/
```

### Clear the cache

Files that pass are remembered in `.def_form_cache/`, so unchanged files are skipped on the next run. To drop what was remembered:

```bash
def-form clean
```

### Example

You can check your code with `check` command and see the result

```text
(.venv) user@MacBook-Pro def-form % def-form check test_file.py
Checking test_file.py

                           Configuration                           
 ───────────────────────────────────────────────────────────────── 
  Config Path:       /Users/user/Documents/def-form/pyproject.toml  
  Max Inline Args:   2                                             
  Max Def Length:    100                                           
  Indent Size:       4 spaces                                      
  Show Skipped:      No                                            
  Cache:             Yes                                           
  Excluded:          .venv, tests/cases, build                     
 ───────────────────────────────────────────────────────────────── 

Found 1 errors in 1 files

/Users/user/Documents/def-form/test_file.py:19
  • Invalid multiline function parameters indentation (expected 4 spaces)

           Summary           
 ─────────────────────────── 
  Files processed:     1     
  Files with issues:   1     
  Total errors:        1     
  Success rate:        0.0%  
 ─────────────────────────── 

Code style violations found
```

Or use `format`
```text
(.venv) user@MacBook-Pro def-form % def-form format test_file.py
Formatting test_file.py

                           Configuration                           
 ───────────────────────────────────────────────────────────────── 
  Config Path:       /Users/user/Documents/def-form/pyproject.toml  
  Max Inline Args:   2                                             
  Max Def Length:    100                                           
  Indent Size:       4 spaces                                      
  Show Skipped:      No                                            
  Cache:             Yes                                           
  Excluded:          build, .venv, tests/cases                     
 ───────────────────────────────────────────────────────────────── 

Found 1 errors in 1 files

/Users/user/Documents/def-form/test_file.py:19
  • Invalid multiline function parameters indentation (expected 4 spaces)

           Summary           
 ─────────────────────────── 
  Files processed:     1     
  Files with issues:   1     
  Total errors:        1     
  Success rate:        0.0%  
 ─────────────────────────── 

Formatting completed
```

## Command line options

There is global options

```text
Usage: def-form [OPTIONS] COMMAND [ARGS]...

Options:
  --verbose  Enable verbose output
  --quiet    Disable all output
  --help     Show this message and exit.

Commands:
  check
  clean
  format
```

And specific options for check/format

```text
Usage: def-form format [OPTIONS] [PATH]

Options:
  --config FILE              Path to pyproject.toml configuration file
  --no-cache                 Process every file, ignoring the cache
  --show-skipped             Show skipped files and directories
  --exclude PATH             Paths to exclude from processing
  --indent-size INTEGER      Indent size in spaces (default: 4)
  --max-inline-args INTEGER  Maximum number of inline arguments
  --max-def-length INTEGER   Maximum length of function definition
  --help                     Show this message and exit.
```

## Configuration

Create a pyproject.toml file in your project root:

```toml
[tool.def-form]
max_def_length = 100  # Maximum allowed characters in a single-line function definition
max_inline_args = 2   # Maximum number of arguments allowed in inline format
indent_size = 4       # Indent for arguments in spaces
cache = true          # Skip files that already passed and have not changed since
exclude = [           # Files or directories you want to exclude
    '.venv',
    'migrations'
]
```
