Infrastructure Modernizer
Relevant source files
The following files were used as context for generating this wiki page:
The Infrastructure Modernizer is a specialized orchestration system designed to standardize pyproject.toml files across a workspace. It ensures that all governed projects adhere to a uniform format, specifically targeting build systems, development dependencies, and tool configurations such as Ruff, Coverage, and Pyrefly. The system supports auditing changes without writing to disk, rewriting dependency constraints based on uv.lock, and performing post-write validation to ensure build integrity.
Sources: src/flext_infra/deps/modernizer.py:28-35, src/flext_infra/deps/_modernizer_run.py:11-20
Architecture and Execution Flow
The modernizer operates as a service that resolves project paths within a workspace and iterates through relevant pyproject.toml files. It utilizes a mixin-based architecture to separate concerns such as selection logic, document state management, and constraint rewriting.
Execution Lifecycle
- Resolution: Identifies target
pyproject.tomlfiles, skipping specified directories like.venvornode_modules. - State Loading: Reads the current document state and payload from the target files.
- Modernization: Applies specific "Phases" (e.g., Ruff config, Coverage settings) to modify the TOML document.
- Constraint Rewriting: Optionally updates dependency versions to match the workspace
uv.lockfile. - Validation: Executes a
_run_build_checkto ensure the resulting files possess valid build backends (e.g.,hatchling.build).
Sources: src/flext_infra/deps/_modernizer_run.py:61-115, src/flext_infra/deps/modernizer.py:37-43
Modernization Process Flow
The following diagram illustrates the high-level logic for processing a workspace:
Configuration and Tooling Phases
The modernizer applies standardized configurations through discrete phases. These phases ensure that project-specific pyproject.toml files include required settings for static analysis and testing tools.
Ruff Configuration Phase
This phase enforces a standard Ruff setup, including lint selection, formatting styles, and isort configurations. It dynamically discovers local package namespaces to populate the known-first-party list, ensuring correct import sorting.
- Key Logic: Discovering python directories and workspace-attached namespaces to overlay onto the tool configuration.
- Cleanup: Automatically removes stale top-level
[lint]sections found in older configurations.
Sources: src/flext_infra/deps/phases/ensure_ruff.py:16-55, tests/unit/deps/test_modernizer_tooling.py:133-150
Coverage Phase
Ensures standardized code coverage reporting and execution settings. It differentiates between project kinds (e.g., core, integration) to set appropriate fail_under thresholds.
- Managed Fields:
fail_under,precision,show_missing,exclude_also, andomit.
Sources: src/flext_infra/deps/phases/ensure_coverage.py:10-25, tests/unit/deps/test_modernizer_coverage.py:46-59
Formatting Phase
Standardizes configuration for housekeeping tools including codespell, tomlsort, and yamlfix. It enforces strict ordering for TOML sections (e.g., build-system first) and removes hardcoded exclusions in codespell.
Sources: tests/unit/deps/test_modernizer_tooling.py:30-55, tests/unit/deps/test_modernizer_tooling.py:73-85
Dependency Management
The Infrastructure Modernizer provides advanced dependency synchronization features. It can align project dependencies with the workspace's locked state to prevent version drift.
Constraint Rewriting Policies
When rewrite_constraints is enabled, the modernizer extracts versions from uv.lock.
| Policy | Description |
|---|---|
FLOOR | Sets the minimum version constraint (e.g., package>=1.2.3) based on the lock file. |
EXACT | (Inferred from context) Standardizes on exact pinned versions. |
Sources: src/flext_infra/deps/modernizer.py:53-65, src/flext_infra/deps/_modernizer_run.py:84-90
Implementation Details: Ruff Phase
# src/flext_infra/deps/phases/ensure_ruff.py:71-85
phase = (
m.Infra.Deps.Toml.PhaseConfig
.Builder("ruff")
.table(c.Infra.RUFF)
.list(c.Infra.EXCLUDE, sorted(ruff_cfg.exclude))
.value("fix", ruff_cfg.fix)
.value("line-length", ruff_cfg.line_length)
.nested(c.Infra.LINT_SECTION, values=lint_nested_values)
.nested(c.Infra.LINT_SECTION, c.Infra.ISORT, values=tuple(isort_values))
.build()
)
Sources: src/flext_infra/deps/phases/ensure_ruff.py:71-98
Operational Parameters
The FlextInfraPyprojectModernizer class accepts several flags to control its behavior during execution.
| Parameter | Type | Default | Description |
|---|---|---|---|
audit | bool | False | Performs a dry-run and reports violations without modifying files. |
skip-check | bool | False | Skips the post-write build backend validation. |
rewrite-constraints | bool | False | Updates dependencies in pyproject.toml to match uv.lock. |
constraint-policy | Enum | FLOOR | The strategy for updating version requirements. |
Sources: src/flext_infra/deps/modernizer.py:37-70, pyproject.toml:130-134
Summary
The Infrastructure Modernizer is a critical component for maintaining workspace consistency in FLEXT projects. By automating the alignment of pyproject.toml files with a central configuration and the workspace lock file, it reduces manual maintenance overhead and prevents configuration drift. Its modular phase-based approach allows for precise control over tool-specific settings while providing safety through audit modes and build-check validation.
Sources: src/flext_infra/deps/modernizer.py:28-35, src/flext_infra/deps/_modernizer_run.py:145-155