Formatter

The formatter module is the main orchestrator for the formatting pipeline. It provides four public functions that cover the two main operations: format (mutate in place) and render (format + produce text).

Module Reference

behave_format.pipeline.formatter

Formatter — the main orchestrator for the formatting pipeline.

The pipeline is

1. Normalize — clean whitespace, standardize structure
2. Sort — order tags, features, scenarios
3. Align — table alignment, trailing whitespace
4. Print — convert model to .feature text

format_project

format_project(project: Project, settings: Settings | None = None) -> Project

Format a behave-model Project in place.

Applies the full pipeline: normalize → sort → align. The project is mutated and returned.

Parameters:

Name	Type	Description	Default
project	Project	The project to format.	required
settings	Settings | None	Optional formatter settings. Defaults to Settings().	None

Returns:

Type	Description
Project	The same project, formatted.

Source code in behave_format/pipeline/formatter.py

def format_project(project: Project, settings: Settings | None = None) -> Project:
    """Format a behave-model Project in place.

    Applies the full pipeline: normalize → sort → align.
    The project is mutated and returned.

    Args:
        project: The project to format.
        settings: Optional formatter settings. Defaults to Settings().

    Returns:
        The same project, formatted.
    """
    if settings is None:
        settings = Settings()

    normalize_project(project)
    sort_project(project, settings)
    align_project(project)
    return project

format_feature

format_feature(feature: Feature, settings: Settings | None = None) -> Feature

Format a single Feature in place.

Parameters:

Name	Type	Description	Default
feature	Feature	The feature to format.	required
settings	Settings | None	Optional formatter settings. Defaults to Settings().	None

Returns:

Type	Description
Feature	The same feature, formatted.

Source code in behave_format/pipeline/formatter.py

def format_feature(feature: Feature, settings: Settings | None = None) -> Feature:
    """Format a single Feature in place.

    Args:
        feature: The feature to format.
        settings: Optional formatter settings. Defaults to Settings().

    Returns:
        The same feature, formatted.
    """
    if settings is None:
        settings = Settings()

    from behave_format.pipeline.normalize import _normalize_feature
    from behave_format.pipeline.sort import _sort_feature_tags

    _normalize_feature(feature)
    if settings.sort_tags:
        _sort_feature_tags(feature)
    align_feature(feature)
    return feature

render_feature

render_feature(feature: Feature, settings: Settings | None = None) -> str

Format and render a Feature as .feature text.

Parameters:

Name	Type	Description	Default
feature	Feature	The feature to format and print.	required
settings	Settings | None	Optional formatter settings.	None

Returns:

Type	Description
str	The formatted .feature file content as a string.

Source code in behave_format/pipeline/formatter.py

def render_feature(feature: Feature, settings: Settings | None = None) -> str:
    """Format and render a Feature as .feature text.

    Args:
        feature: The feature to format and print.
        settings: Optional formatter settings.

    Returns:
        The formatted .feature file content as a string.
    """
    format_feature(feature, settings)
    return print_feature(feature, indent=settings.indent if settings else 2) + "\n"

render_project

render_project(project: Project, settings: Settings | None = None) -> str

Format and render an entire Project as .feature text.

Features are separated by a single blank line.

Parameters:

Name	Type	Description	Default
project	Project	The project to format and print.	required
settings	Settings | None	Optional formatter settings.	None

Returns:

Type	Description
str	The formatted content for all features, joined by blank lines.

Source code in behave_format/pipeline/formatter.py

def render_project(project: Project, settings: Settings | None = None) -> str:
    """Format and render an entire Project as .feature text.

    Features are separated by a single blank line.

    Args:
        project: The project to format and print.
        settings: Optional formatter settings.

    Returns:
        The formatted content for all features, joined by blank lines.
    """
    format_project(project, settings)
    indent = settings.indent if settings else 2
    parts = [print_feature(f, indent=indent) for f in project.features]
    return "\n\n".join(parts) + "\n"

Functions

format_project

def format_project(project: Project, settings: Settings | None = None) -> Project

Applies the full pipeline (normalize → sort → align) to a behave-model Project. The project is mutated and returned.

from behave_format import format_project, Settings
from behave_model import load_project

project = load_project("features/")
format_project(project, Settings(indent=4))

render_project

def render_project(project: Project, settings: Settings | None = None) -> str

Formats the project and returns the formatted .feature text for all features, joined by blank lines.

from behave_format import render_project
from behave_model import load_project

project = load_project("features/")
text = render_project(project)
print(text)

format_feature

def format_feature(feature: Feature, settings: Settings | None = None) -> Feature

Formats a single Feature in place. Applies normalization and tag sorting. Alignment is handled at print time.

render_feature

def render_feature(feature: Feature, settings: Settings | None = None) -> str

Formats a single feature and returns the formatted .feature file content as a string.

from behave_format import render_feature, Settings
from behave_model import load_feature

feature = load_feature("features/login.feature")
text = render_feature(feature, Settings(indent=2))