AST Transformers & Fixers

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_infra/transformers/pydantic_modernizer.py
• src/flext_infra/transformers/result_di_modernizer.py
• src/flext_infra/_utilities/docs_fix.py
• src/flext_infra/_utilities/docs_generate.py
• src/flext_infra/constants.py
• src/flext_infra/rules/class-nesting-mappings.yml

AST Transformers and Fixers within flext-infra provide automated code refactoring and documentation correction capabilities. These tools leverage Abstract Syntax Tree (AST) analysis to migrate legacy patterns to modern standards, such as updating Pydantic v1 code to v2 or canonicalizing dependency injection imports.

The system is designed to be conservative, only applying rewrites when the outcome is unambiguous to ensure code safety. It supports both source code modernizations and documentation-specific fixes like broken link resolution and TOC synchronization.
Sources: src/flext_infra/transformers/pydantic_modernizer.py:1-20, src/flext_infra/transformers/result_di_modernizer.py:1-15

Pydantic Modernizer

The FlextInfraRefactorPydanticModernizer is an AST-driven transformer dedicated to migrating Pydantic v1/legacy patterns to Pydantic v2 canonical forms. It identifies specific Pydantic structures like BaseModel, BaseSettings, and RootModel to apply targeted rewrites.

Modernization Logic

The transformer uses a visitor pattern (_PydanticVisitor) to scan for and correct several anti-patterns:

• Config Classes: Converts class Config: blocks inside models into model_config = ConfigDict(...) assignments.
• Method Renaming: Migrates deprecated methods like .dict() to .model_dump() and .parse_obj() to .model_validate().
• Validators: Rewrites @validator to @field_validator and @root_validator to @model_validator, automatically handling pre=True parameters by converting them to mode="before".
• Dunder Attributes: Replaces __fields__ and __field_defaults__ with model_fields and model_config.

Sources: src/flext_infra/transformers/pydantic_modernizer.py:23-45, src/flext_infra/transformers/pydantic_modernizer.py:141-160

Transformation Flow

The following diagram illustrates how the Pydantic Modernizer processes a source file.

Result & DI Modernizer

The FlextInfraRefactorResultDiModernizer handles the migration of result-flow patterns and Dependency Injection (DI) imports to the flext_core canonical forms.

Key Capabilities

• DI Canonicalization: Redirects imports from the third-party dependency_injector package to the internal flext_core.di facade.
• Exception to Result Flow: Converts raise ValueError("msg") into return r[str].fail("msg") specifically in functions that already import the r result alias from flext_core.

Sources: src/flext_infra/transformers/result_di_modernizer.py:20-35, src/flext_infra/transformers/result_di_modernizer.py:126-146

Import Rewriting Table

Legacy Import	Modern flext-infra Import
dependency_injector	flext_core.di
dependency_injector.containers	flext_core.di.containers
dependency_injector.providers	flext_core.di.providers

Sources: src/flext_infra/transformers/result_di_modernizer.py:7-12

Documentation Fixers

Beyond source code, the infrastructure includes specialized fixers for Markdown documentation governed by FlextInfraUtilitiesDocsFix.

Automated Fix Operations

• Broken Link Resolution: The docs_maybe_fix_link helper identifies internal .md links that are missing the extension or have incorrect relative paths and corrects them if a candidate exists.
• TOC Synchronization: The system automatically generates and replaces Table of Contents blocks defined by <!-- TOC START --> and <!-- TOC END --> markers based on H2 and H3 headings.
• Python Codeblock Linting: Uses ruff check --fix to automatically resolve linting errors within Markdown-fenced Python blocks using a specific set of ignored rules (e.g., D100, ANN001).

Sources: src/flext_infra/_utilities/docs_fix.py:20-50, src/flext_infra/_utilities/docs_fix.py:100-115

Document Sanitization

The FlextInfraUtilitiesDocsGenerate utility provides sanitization for documentation fences, specifically removing unsupported notest qualifiers from code fence info lines to ensure compatibility with documentation rendering tools.
Sources: src/flext_infra/_utilities/docs_generate.py:168-185

Refactor Rules & Mapping

The project maintains a rule-based system for class nesting and MRO (Method Resolution Order) corrections, often defined in YAML configurations.

Class Nesting Mappings

A configuration file class-nesting-mappings.yml provides instructions for relocating classes to appropriate namespaces.

• High Confidence Rules: Applied to top-level classes found in private directories (e.g., CircuitBreakerManager moving to FlextDispatcher).
• Low/Medium Confidence Rules: Target classes without proper namespace prefixes or those requiring manual verification of parent MRO chains.

Sources: src/flext_infra/rules/class-nesting-mappings.yml:1-50

Summary of Transformer Architecture

The transformation architecture relies on a shared base and specialized rewriters to ensure consistency.

Component	Responsibility
FlextInfraRopeTransformer	Base class providing integration with Rope and change tracking.
FlextInfraSourceRewriter	Provides low-level text replacement logic using AST node spans.
FlextInfraRefactorPydanticModernizer	Handles Pydantic v1 to v2 migration.
FlextInfraRefactorResultDiModernizer	Canonicalizes DI and Result flow patterns.

Sources: src/flext_infra/transformers/pydantic_modernizer.py:23-35, src/flext_infra/transformers/result_di_modernizer.py:20-30