Dependencies Detection System
Relevant source files
The following files were used as context for generating this wiki page:
The Dependencies Detection System is a core infrastructure component designed to analyze, validate, and report on Python package dependencies across a FLEXT workspace. Its primary purpose is to ensure that all internal and external dependencies are correctly declared in pyproject.toml files, identifying missing, unused, or transitive dependencies that might compromise project stability or build reproducibility.
The system operates by scanning workspace projects, parsing requirement specifiers (PEP 621 and Poetry formats), and integrating with external tools like deptry to generate comprehensive reports. It supports both workspace-wide analysis and per-project deep dives, including the detection of required typing stubs and validation of pip environment consistency.
Sources: src/flext_infra/deps/detection.py, src/flext_infra/deps/detector.py, src/flext_infra/_models/deps.py:12-15
Core Architecture and Data Flow
The system is structured around service-oriented components that handle discovery, execution of external linters, and report aggregation.
Component Overview
| Component | Responsibility |
|---|---|
FlextInfraDependencyDetectionService | Orchestrates the high-level detection workflow, filtering projects and aggregating results. |
FlextInfraRuntimeDevDependencyDetector | Handles the execution of deptry and internal linter logic to identify dependency mismatches. |
FlextInfraUtilitiesDependencies | Provides static helpers for parsing requirement strings, extracting package names, and resolving versions from uv.lock. |
FlextInfraProjectClassifierDepsMixin | Normalizes dependency lists across various TOML formats (PEP 621 vs Poetry). |
Sources: src/flext_infra/deps/detection.py, src/flext_infra/deps/detector.py, src/flext_infra/_utilities/dependencies.py, src/flext_infra/refactor/_project_classifier_deps.py
Detection Workflow
The following diagram illustrates the flow from a CLI request to the final generated report:
The workflow begins with a DetectCommand which triggers the discovery of projects within the workspace. For each project, the system executes dependency analysis and typing stub verification before aggregating the results into a unified workspace report.
Sources: src/flext_infra/deps/detection.py, src/flext_infra/deps/detector.py
Dependency Parsing and Normalization
A critical aspect of the system is the ability to extract clean package names from complex requirement specifiers.
Parsing Logic
The FlextInfraUtilitiesDependencies.dep_name method normalizes requirement strings by:
- Stripping whitespace.
- Removing environment markers (after
;). - Removing direct URL references (after
@). - Stripping version specifiers (e.g.,
[,==,>=,~=). - Extracting the terminal package name from path-based dependencies.
Sources: src/flext_infra/_utilities/dependencies.py:21-39.%0A5.%20Extracting%20the%20terminal%20package%20name%20from%20path-based%20dependencies.%0A%0ASources%3A%20%5Bsrc/flext_infra/_utilities/dependencies.py%3A21-39)
Supported TOML Tables
The system scans multiple locations in pyproject.toml to build a complete list of declared dependencies:
[project.dependencies][project.optional-dependencies](all groups)[dependency-groups](PEP 735)[tool.poetry.dependencies][tool.poetry.group.<name>.dependencies]
Sources: src/flext_infra/_utilities/dependencies.py:141-213
Analysis and Reporting
The system produces several levels of reporting, from raw issue counts to detailed typing package deltas.
Report Models
The data structures used for reporting are defined in the FlextInfraModelsDeps namespace.
This class diagram shows the hierarchical relationship between workspace-level reports and project-specific analysis results.
Sources: src/flext_infra/_models/deps.py:165-240
Typing Stub Detection
The system specifically tracks required typing packages. It analyzes imported modules and compares them against current project dependencies and an optional "dependency limits" TOML file. This allows the system to suggest missing stubs (e.g., types-requests) or identify unnecessary ones.
Sources: src/flext_infra/deps/detector.py, src/flext_infra/_models/deps.py:186-212
Configuration and Constraints
The system behavior is influenced by project configuration and workspace-level locks.
| Option | Type | Description |
|---|---|---|
dry_run | bool | Preview changes without modifying TOML files. |
typings | bool | Enable detection of required typing packages. |
apply_typings | bool | Automatically install missing typing packages. |
no_pip_check | bool | Skip the global pip check environment validation. |
constraint_policy | Enum | Determines if rewritten constraints use "floor" (>=) or "compatible" (~=) specifiers. |
Sources: src/flext_infra/_models/deps.py:21-65, src/flext_infra/_constants/base.py:270-275
Locked Version Integration
The system can read uv.lock files to synchronize declared dependencies with currently locked versions. The locked_dependency_versions helper extracts normalized registry package versions, which can then be used to rewrite pyproject.toml constraints to match the lock file precisely.
Sources: src/flext_infra/_utilities/dependencies.py:53-93
Conclusion
The Dependencies Detection System provides a robust mechanism for maintaining dependency health in a multi-project workspace. By combining standardized parsing, external tool execution, and detailed reporting, it ensures that project declarations remain accurate and synchronized with actual usage and environment locks.