def-form 0.3.0

Python function definition formatter

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:

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):

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

pip install def-form

Usage

Format code

• Format all Python files in a directory:

def-form format src/

• Format a specific file:

def-form format my_module.py

Check code without formatting

• Check if code follows formatting rules:

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:

def-form clean

Example

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

(.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

(.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

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

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:

[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'
]