Pipeline¶

The formatting pipeline consists of four stages applied in order: normalize → sort → align → print. Each stage operates on the behave-model Project in place.

Normalize¶

Cleans whitespace, standardizes indentation, normalizes tag names (ensures @ prefix), strips trailing whitespace from comments, and ensures table cells are stripped. This stage never changes semantics.

behave_format.pipeline.normalize ¶

Normalize stage — clean whitespace and standardize structure.

This stage operates on a behave-model Project in place. It NEVER changes semantics: only whitespace, indentation, and structural consistency are normalized.

normalize_project ¶

normalize_project(project: Project) -> Project

Normalize whitespace and structure across the entire project.

Parameters:

Name	Type	Description	Default
`project`	`Project`	The project to normalize (mutated in place).	required

Returns:

Type	Description
`Project`	The same project, normalized.

Source code in behave_format/pipeline/normalize.py

def normalize_project(project: Project) -> Project:
    """Normalize whitespace and structure across the entire project.

    Args:
        project: The project to normalize (mutated in place).

    Returns:
        The same project, normalized.
    """
    for feature in project.features:
        _normalize_feature(feature)
    project.global_tags.sort(key=lambda t: t.name)
    return project

Sort¶

Orders tags, features, and scenarios. By default only tags are sorted alphabetically. Feature and scenario sorting are opt-in via Settings.

behave_format.pipeline.sort ¶

Sort stage — order tags, features, and scenarios.

Sorting is configurable via Settings. By default only tags are sorted alphabetically. Feature and scenario sorting are opt-in.

sort_project ¶

sort_project(project: Project, settings: Settings) -> Project

Apply sorting rules to the project.

Parameters:

Name	Type	Description	Default
`project`	`Project`	The project to sort (mutated in place).	required
`settings`	`Settings`	Formatter settings controlling sort behavior.	required

Returns:

Type	Description
`Project`	The same project, sorted.

Source code in behave_format/pipeline/sort.py

def sort_project(project: Project, settings: Settings) -> Project:
    """Apply sorting rules to the project.

    Args:
        project: The project to sort (mutated in place).
        settings: Formatter settings controlling sort behavior.

    Returns:
        The same project, sorted.
    """
    if settings.sort_tags:
        _sort_all_tags(project)

    if settings.sort_features:
        project.features.sort(key=lambda f: f.name)

    if settings.sort_scenarios:
        for feature in project.features:
            feature.scenarios.sort(key=lambda s: s.name)
            for rule in feature.rules:
                rule.scenarios.sort(key=lambda s: s.name)

    return project

Align¶

Ensures tables are rectangular (pads short rows, truncates long rows) and removes trailing whitespace. This stage operates on the model before printing.

behave_format.pipeline.align ¶

Align stage — table alignment and trailing whitespace removal.

This stage ensures tables are properly aligned and no trailing whitespace remains in any text content. It operates on the model before printing.

align_project ¶

align_project(project: Project) -> Project

Apply alignment rules to the project.

Parameters:

Name	Type	Description	Default
`project`	`Project`	The project to align (mutated in place).	required

Returns:

Type	Description
`Project`	The same project, aligned.

Source code in behave_format/pipeline/align.py

def align_project(project: Project) -> Project:
    """Apply alignment rules to the project.

    Args:
        project: The project to align (mutated in place).

    Returns:
        The same project, aligned.
    """
    for feature in project.features:
        _align_feature(feature)
    return project

align_feature ¶

align_feature(feature: Feature) -> Feature

Apply alignment rules to a single feature.

Parameters:

Name	Type	Description	Default
`feature`	`Feature`	The feature to align (mutated in place).	required

Returns:

Type	Description
`Feature`	The same feature, aligned.

Source code in behave_format/pipeline/align.py

def align_feature(feature: Feature) -> Feature:
    """Apply alignment rules to a single feature.

    Args:
        feature: The feature to align (mutated in place).

    Returns:
        The same feature, aligned.
    """
    _align_feature(feature)
    return feature

Rules¶

Defines a Rule type (callable that transforms a Project with Settings) and an apply_rules function for applying a sequence of rules in order.

behave_format.pipeline.rules ¶

Formatting rules registry.

Each rule is a callable that transforms the project at a specific stage of the pipeline. Rules are applied in order.

apply_rules ¶

apply_rules(project: Project, settings: Settings, rules: list[Rule]) -> Project

Apply a list of formatting rules to the project.

Parameters:

Name	Type	Description	Default
`project`	`Project`	The project to format.	required
`settings`	`Settings`	Formatter settings.	required
`rules`	`list[Rule]`	Ordered list of rule callables.	required

Returns:

Type	Description
`Project`	The formatted project.

Source code in behave_format/pipeline/rules.py

def apply_rules(project: Project, settings: Settings, rules: list[Rule]) -> Project:
    """Apply a list of formatting rules to the project.

    Args:
        project: The project to format.
        settings: Formatter settings.
        rules: Ordered list of rule callables.

    Returns:
        The formatted project.
    """
    for rule in rules:
        project = rule(project, settings)
    return project