Configuration & Global Settings

Relevant source files

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

• src/flext_infra/_constants/base.py
• src/flext_infra/_constants/workspace.py
• src/flext_infra/deps/tool_config.yml
• src/flext_infra/_models/docs.py
• src/flext_infra/pyproject.toml
• src/flext_infra/_utilities/docs_render.py
• src/flext_infra/_constants/docs.py

Configuration and global settings in the FLEXT infrastructure are managed through a combination of static constants, YAML-based tool configurations, and Pydantic-driven domain models. This system provides a Single Source of Truth (SSOT) for build automation, workspace management, and quality gate enforcement across governed projects.

The infrastructure utilizes pyproject.toml as the primary configuration entry point for project-level metadata, while centralized defaults for linting, formatting, and type-checking are maintained in tool_config.yml. This architecture ensures deterministic behavior across the workspace, where execution modes (dry-run vs. apply) and environment variables control the behavior of the underlying tooling.

Sources: src/flext_infra/_constants/base.py, src/flext_infra/deps/tool_config.yml, pyproject.toml:139-142

Core Infrastructure Constants

The system defines a hierarchy of constants that govern project classification, execution modes, and CLI routing. These constants are centralized to ensure consistency across different modules such as deps, docs, and workspace.

Execution and Operation Modes

The infrastructure supports various execution modes that dictate how file-modifying commands behave.

Mode	Key	Description
Dry Run	dry-run	Preview changes without writing to disk.
Check Only	check-only	Detect violations without attempting to fix them.
Apply Safe	apply-safe	Apply changes with backups; rollback on validation failure.
Apply Force	apply-force	Apply changes immediately without post-validation.

Sources: src/flext_infra/_constants/base.py:270-282

Hierarchy of Constants

This diagram illustrates the inheritance and relationship between different constant namespaces within the infrastructure.
Sources: src/flext_infra/_constants/base.py:21-25, src/flext_infra/_constants/workspace.py:12, src/flext_infra/_constants/docs.py:14

Tool Configuration (SSOT)

FLEXT enforces standardized configurations for various third-party tools via tool_config.yml. This file serves as the blueprint for generating managed sections in project pyproject.toml files.

Linting and Formatting Defaults

Standard configurations are provided for:

• Ruff: Comprehensive linting rules (select ALL) with specific per-file ignores for tests, docs, and examples.
• MyPy: Strict type checking with specific error codes disabled to accommodate FLEXT's MRO (Method Resolution Order) composition and lazy-import patterns.
• Pyrefly: Enforces strict error checking for type safety, including bad-assignment and annotation-mismatch.
• Formatting Tools: Defaults for codespell, tomlsort (sorting project and tool tables first), and yamlfix.

Sources: src/flext_infra/deps/tool_config.yml:5-514, src/flext_infra/deps/tool_config.yml:765-777

Pyproject Table Mappings

The infrastructure defines specific keys for navigating and modifying pyproject.toml documents.

constant	key	Description
TOOL	tool	Top-level section for tool-specific settings.
PROJECT	project	Standard PEP 621 project metadata.
POETRY	poetry	Legacy or specific Poetry tool subsection.
DEPENDENCY_GROUPS	dependency-groups	PEP 735 dependency groups (dev, docs, test, etc).

Sources: src/flext_infra/_constants/base.py:53-62

Workspace Environment Configuration

Workspace configuration involves managing the developer environment through .envrc and .mise.toml generation, ensuring that all contributors share the same Python version and tool versions.

Environment Activation Flow

This sequence shows how environment variables and tool shims are initialized when a developer enters a FLEXT-managed workspace.
Sources: src/flext_infra/_constants/workspace.py:72-126

Standard Ignores and Replacements

The workspace sync service manages .gitignore entries and Makefile command migrations to ensure legacy scripts are replaced by the modern flext-infra CLI.

• Managed Ignores: .direnv/, .reports/, .venv/, __pycache__/, and base.mk.
• Makefile Migrations: Replaces manual script calls (e.g., scripts/sync.py) with python -m flext_infra workspace sync --apply.

Sources: src/flext_infra/_constants/workspace.py:33-58

Documentation Models and Settings

Documentation configuration is handled via DocScope and DocsProjectMeta models, which define how API reference pages and project READMEs are generated.

Documentation Metadata Structure

Key Documentation Constants

• Default Output: .reports/docs is the standard directory for generated reports.
• Link Resolution: Generated READMEs use relative paths (prefix ..), while docs/index.md pages use absolute GitHub URLs for governance pointers to ensure resolveability in MkDocs builds.
• Excluded Rules: A sequence of Ruff rules (e.g., D100, ANN001) are ignored specifically for executable python code fences within markdown files.

Sources: src/flext_infra/_constants/docs.py:16-43, src/flext_infra/_utilities/docs_render.py:99-105

Configuration and global settings in FLEXT provide a rigid but extensible framework for multi-project management. By utilizing centralized constants and a structured YAML-to-TOML pipeline, the system maintains high standards for code quality and environment consistency across the entire infrastructure.