Extra Paths & Configurations Sync
Relevant source files
The following files were used as context for generating this wiki page:
The Extra Paths & Configurations Sync system is a core infrastructure component designed to maintain consistency across a FLEXT workspace. Its primary purpose is to synchronize project metadata, environment configurations, and static analysis paths (specifically for Pyright and Mypy) based on internal dependency relationships.
This system ensures that when projects within a workspace depend on one another, their development environment settings (like extraPaths in pyproject.toml) are automatically updated to reflect these local paths. This enables seamless cross-project IDE support and type checking without manual configuration.
Core Architecture and Synchronization Logic
The synchronization logic is distributed across specialized mixins and utility classes that handle different types of configuration artifacts.
Path Dependency Resolution
The system recursively resolves transitive workspace dependencies to build a comprehensive list of paths required for static analysis.
The recursive resolution identifies every internal project name and ensures that if Project A depends on Project B, which in turn depends on Project C, Project A's configuration will include paths for both B and C.
Sources: src/flext_infra/deps/_extra_paths_sync.py:30-58, src/flext_infra/_utilities/deps_path_sync.py:276-299
Configuration Targets
The system synchronizes several key files and sections:
| Target | Description | File(s) |
|---|---|---|
| Pyright/Mypy Paths | Syncs extraPaths and mypy_path based on local dependencies. | pyproject.toml |
| PEP 621 Metadata | Rewrites dependency entries to use local file references or workspace markers. | pyproject.toml |
| uv Sources/Workspace | Manages [tool.uv.sources] and [tool.uv.workspace.members]. | pyproject.toml |
| Gitignore | Idempotently syncs a managed block of ignore patterns. | .gitignore |
| VS Code Settings | Synchronizes canonical workspace settings for Python. | .vscode/settings.json |
Sources: src/flext_infra/_utilities/deps_path_sync.py:32-132, src/flext_infra/workspace/_sync_artifacts.py:65-115
Dependency Path Rewriting (Path Sync)
The FlextInfraUtilitiesDependencyPathSync class is responsible for rewriting internal FLEXT dependency paths to toggle between "Workspace" mode (using uv workspace markers) and "Standalone" mode (using local file paths).
PEP 621 and uv Synchronization
The utility scans the [project.dependencies] and [tool.uv.sources] sections. In workspace mode, it ensures that internal dependencies are marked with workspace = True. In standalone mode, it rewrites these to point to the .flext-deps directory.
Implementation Details: Path Rewriting
# From src/flext_infra/_utilities/deps_path_sync.py:175-217
def rewrite_dep_paths(
self,
pyproject_path: Path,
*,
command: FlextInfraModelsDeps.PathSyncCommand,
internal_names: t.Infra.StrSet,
workspace_members: t.StrSequence,
) -> p.Result[t.StrSequence]:
# ... reading state ...
pep_changes, internal_deps = self._rewrite_pep621(
payload,
internal_names=internal_names,
)
# ... sync uv sources and workspace members ...
if changes and (not command.dry_run):
write_result = self._write_document_state(pyproject_path, state.payload)
return r[t.StrSequence].ok(changes)
Workspace Artifact Synchronization
Beyond dependency paths, the system manages standard workspace artifacts via the FlextInfraWorkspaceSyncArtifactsMixin. This ensures that every project in the workspace adheres to the same base infrastructure rules.
Managed Gitignore Blocks
The system maintains a "managed" section in .gitignore defined by c.Infra.GITIGNORE_MANAGED_HEADER. It identifies required entries and idempotently inserts or updates them without disturbing user-defined rules.
Sources: src/flext_infra/workspace/_sync_artifacts.py:65-103
VS Code and Environment
- VS Code: Canonical settings for Python workspaces (like type checking modes) are synced to
.vscode/settings.json. - Environment: Tools like
direnvandmiseconfiguration files are synchronized to ensure consistent development environments across the team. - Pre-commit: The workspace
.pre-commit-config.yamlis synced from a canonical Single Source of Truth (SSOT).
Sources: src/flext_infra/workspace/_sync_artifacts.py:105-125
CLI Integration and Routes
The synchronization features are exposed through specific CLI groups defined in the infra routes.
| CLI Group | Verb | Model / Service | Purpose |
|---|---|---|---|
deps | extra-paths | FlextInfraExtraPathsManager | Syncs Pyright/Mypy path settings. |
deps | path-sync | PathSyncCommand | Rewrites dependency paths (Workspace vs Standalone). |
workspace | sync | FlextInfraSyncService | Orchestrates artifact sync (Makefile, Gitignore, VS Code). |
Sources: src/flext_infra/_constants/cli_routes.py:165-177, src/flext_infra/_constants/cli_routes.py:315-320
Summary
The Extra Paths & Configurations Sync module provides automated governance for workspace metadata. By combining recursive dependency resolution with targeted file updates (TOML, JSON, and text-based configs), it eliminates manual maintenance of development environment paths and ensures that internal FLEXT projects remain integrated regardless of whether they are consumed as part of a mono-repo workspace or as standalone packages.