0
# Dependency Tracking
1

2
Import Tracker provides sophisticated dependency tracking capabilities that analyze Python modules to determine which external packages they require. This functionality is essential for debugging dependency issues in large projects and understanding the dependency footprint of individual modules.
3

4
## Capabilities
5

6
### Module Dependency Analysis
7

8
Analyzes a specific module to determine all external packages it imports, both directly and transitively. The analysis runs in an isolated subprocess to avoid affecting the current Python environment.
9

10
```python { .api }
11
def track_module(
12
    module_name: str,
13
    package_name: Optional[str] = None,
14
    log_level: Optional[int] = None,
15
    recursive: bool = False,
16
    num_jobs: int = 0,
17
    side_effect_modules: Optional[List[str]] = None,
18
    submodules: Optional[List[str]] = None,
19
    track_import_stack: bool = False,
20
    detect_transitive: bool = False,
21
) -> Dict[str, List[str]]:
22
    """
23
    Track the dependencies of a module by launching subprocess analysis.
24

25
    Parameters:
26
    - module_name: str - Name of the module to track (may be relative if package_name provided)
27
    - package_name: Optional[str] - Parent package name if module name is relative
28
    - log_level: Optional[int] - Log level for subprocess (accepts logging constants or string names)
29
    - recursive: bool - Whether to recursively track sub-modules (default: False)
30
    - num_jobs: int - Number of concurrent jobs for recursive analysis (0 = serial, default: 0)
31
    - side_effect_modules: Optional[List[str]] - Modules with import-time side effects to always allow
32
    - submodules: Optional[List[str]] - Specific sub-modules to recurse into (only used with recursive=True)
33
    - track_import_stack: bool - Store stack trace of imports for debugging (very slow, default: False)
34
    - detect_transitive: bool - Distinguish between direct and transitive dependencies (default: False)
35

36
    Returns:
37
    Dict[str, List[str]] - Mapping from fully-qualified module name to list of required imports
38
    """
39
```
40

41
**Usage Example:**
42

43
```python
44
import import_tracker
45

46
# Basic dependency tracking
47
deps = import_tracker.track_module("requests")
48
print(deps)
49
# {'requests': ['urllib3', 'certifi', 'charset_normalizer', 'idna']}
50

51
# Recursive analysis with concurrency
52
deps = import_tracker.track_module(
53
    "myproject", 
54
    recursive=True, 
55
    num_jobs=4,
56
    detect_transitive=True
57
)
58
print(deps)
59
# {
60
#   'myproject': ['numpy', 'pandas'],
61
#   'myproject.utils': ['numpy'],
62
#   'myproject.data': ['pandas', 'sqlalchemy']
63
# }
64

65
# Analysis with custom logging
66
deps = import_tracker.track_module(
67
    "mymodule",
68
    log_level="DEBUG",
69
    side_effect_modules=["matplotlib.pyplot"]  # Allow matplotlib side effects
70
)
71
```
72

73
## Command Line Interface
74

75
Import Tracker can be run as a command-line tool for static dependency analysis:
76

77
```bash
78
# Basic module tracking
79
python -m import_tracker --name my_module
80

81
# Recursive analysis with pretty-printed JSON
82
python -m import_tracker --name my_module --recursive --indent
83

84
# Concurrent recursive analysis
85
python -m import_tracker --name my_module --recursive --num_jobs 4
86

87
# Relative import with package context
88
python -m import_tracker --name .submodule --package my_package
89

90
# Advanced options
91
python -m import_tracker \
92
    --name my_module \
93
    --recursive \
94
    --log_level debug \
95
    --side_effect_modules matplotlib.pyplot seaborn \
96
    --submodules utils data processing \
97
    --track_import_stack \
98
    --detect_transitive
99
```
100

101
**CLI Arguments:**
102

103
- `--name`: Module name to track (required)
104
- `--package`: Parent package for relative imports
105
- `--recursive`: Enable recursive sub-module tracking
106
- `--num_jobs`: Number of concurrent workers (0 = serial)
107
- `--indent`: Pretty-print JSON output
108
- `--log_level`: Set logging level (error, warning, info, debug, debug1-debug4)
109
- `--submodules`: Specific sub-modules to analyze (space-separated)
110
- `--side_effect_modules`: Modules with known import side effects (space-separated)
111
- `--track_import_stack`: Store import stack traces (very slow)
112
- `--detect_transitive`: Distinguish direct vs transitive dependencies
113

114
## Advanced Features
115

116
### Transitive Dependency Detection
117

118
When `detect_transitive=True`, the analysis distinguishes between direct dependencies (imported directly by the module) and transitive dependencies (imported by dependencies):
119

120
```python
121
deps = import_tracker.track_module("requests", detect_transitive=True)
122
# Returns detailed dependency information with 'type' classification
123
```
124

125
### Side Effect Module Handling
126

127
Some libraries require specific modules to be imported for side effects (e.g., global registries). These can be explicitly allowed:
128

129
```python
130
deps = import_tracker.track_module(
131
    "my_viz_lib",
132
    side_effect_modules=["matplotlib.pyplot", "seaborn"]
133
)
134
```
135

136
### Import Stack Tracing
137

138
For debugging complex import issues, enable stack trace collection (warning: very slow):
139

140
```python
141
deps = import_tracker.track_module("complex_module", track_import_stack=True)
142
# Includes stack trace information for each import
143
```