0
# Dependency Tracking
1
2
Comprehensive module dependency analysis using bytecode inspection to discover all imports and their relationships within Python projects.
3
4
## Capabilities
5
6
### Module Dependency Analysis
7
8
Tracks dependencies of Python modules by analyzing bytecode to discover all import statements, supporting both direct analysis and recursive submodule tracking.
9
10
```python { .api }
11
def track_module(
12
module_name: str,
13
package_name: Optional[str] = None,
14
submodules: Union[List[str], bool] = False,
15
track_import_stack: bool = False,
16
full_depth: bool = False,
17
detect_transitive: bool = False,
18
show_optional: bool = False,
19
) -> Union[Dict[str, List[str]], Dict[str, Dict[str, Any]]]:
20
"""
21
Track the dependencies of a single python module
22
23
Args:
24
module_name: The name of the module to track (may be relative if package_name provided)
25
package_name: The parent package name of the module if the module name is relative
26
submodules: If True, all submodules of the given module will also be tracked.
27
If given as a list of strings, only those submodules will be tracked.
28
If False, only the named module will be tracked.
29
track_import_stack: Store the stacks of modules causing each dependency for debugging
30
full_depth: Include transitive dependencies of third party dependencies
31
detect_transitive: Detect whether each dependency is 'direct' or 'transitive'
32
show_optional: Show whether each requirement is optional (behind a try/except) or not
33
34
Returns:
35
import_mapping: The mapping from fully-qualified module name to the set of imports
36
needed by the given module. If tracking import stacks or detecting
37
direct vs transitive dependencies, returns Dict[str, Dict[str, Any]]
38
with nested dicts containing "stack" and/or "type" keys.
39
Otherwise returns Dict[str, List[str]].
40
"""
41
```
42
43
### Basic Dependency Tracking
44
45
Simple module dependency analysis returning a mapping of modules to their required dependencies:
46
47
```python
48
import import_tracker
49
50
# Track a single module
51
deps = import_tracker.track_module('requests')
52
print(deps)
53
# {'requests': ['urllib3', 'certifi', 'charset_normalizer', 'idna']}
54
55
# Track a module with package context
56
deps = import_tracker.track_module('.widgets', package_name='my_package')
57
print(deps)
58
# {'my_package.widgets': ['matplotlib', 'pillow']}
59
```
60
61
### Submodule Analysis
62
63
Track dependencies across all submodules within a package:
64
65
```python
66
# Track all submodules
67
deps = import_tracker.track_module('my_package', submodules=True)
68
print(deps)
69
# {
70
# 'my_package': ['requests'],
71
# 'my_package.utils': ['numpy', 'pandas'],
72
# 'my_package.widgets': ['matplotlib']
73
# }
74
75
# Track specific submodules only
76
deps = import_tracker.track_module(
77
'my_package',
78
submodules=['my_package.core', 'my_package.utils']
79
)
80
```
81
82
### Advanced Dependency Analysis
83
84
Detailed analysis with transitive dependency detection and import stack tracing:
85
86
```python
87
# Detect direct vs transitive dependencies
88
deps = import_tracker.track_module(
89
'my_package',
90
submodules=True,
91
detect_transitive=True,
92
show_optional=True
93
)
94
print(deps)
95
# {
96
# 'my_package': {
97
# 'requests': {'type': 'direct', 'optional': False},
98
# 'urllib3': {'type': 'transitive', 'optional': False}
99
# }
100
# }
101
102
# Track import stacks for debugging
103
deps = import_tracker.track_module(
104
'my_package',
105
track_import_stack=True,
106
full_depth=True
107
)
108
print(deps)
109
# {
110
# 'my_package': {
111
# 'requests': {'stack': [['my_package']]},
112
# 'urllib3': {'stack': [['my_package', 'requests']]}
113
# }
114
# }
115
```
116
117
### Optional Dependency Detection
118
119
Identifies dependencies that are wrapped in try/except blocks, indicating they are optional:
120
121
```python
122
# Show which dependencies are optional
123
deps = import_tracker.track_module('my_package', show_optional=True)
124
print(deps)
125
# {
126
# 'my_package': {
127
# 'requests': {'optional': False}, # Required dependency
128
# 'matplotlib': {'optional': True} # Optional dependency (in try/except)
129
# }
130
# }
131
```
132
133
## Command Line Interface
134
135
The dependency tracking functionality is available via command line:
136
137
```bash
138
# Basic tracking
139
python -m import_tracker --name my_package
140
141
# Track all submodules with pretty printing
142
python -m import_tracker --name my_package --submodules --indent 2
143
144
# Comprehensive analysis
145
python -m import_tracker \
146
--name my_package \
147
--submodules \
148
--track_import_stack \
149
--detect_transitive \
150
--show_optional \
151
--full_depth \
152
--indent 2
153
```
154
155
### Command Line Options
156
157
```python { .api }
158
# Available CLI arguments
159
--name/-n # Module name to track (required)
160
--package/-p # Package for relative imports
161
--submodules/-s # List of submodules to include (all if no value given)
162
--track_import_stack/-t # Store import stack traces
163
--detect_transitive/-d # Detect direct vs transitive dependencies
164
--show_optional/-o # Show optional vs required dependencies
165
--full_depth/-f # Include transitive third-party dependencies
166
--indent/-i # JSON output indentation
167
--log_level/-l # Set logging level
168
```
169
170
## Return Value Formats
171
172
### Simple Format
173
174
When `detect_transitive=False`, `track_import_stack=False`, and `show_optional=False`:
175
176
```python
177
{
178
'module_name': ['dep1', 'dep2', 'dep3']
179
}
180
```
181
182
### Extended Format
183
184
When any of the advanced options are enabled:
185
186
```python
187
{
188
'module_name': {
189
'dependency_name': {
190
'type': 'direct', # When detect_transitive=True
191
'stack': [['module_path']], # When track_import_stack=True
192
'optional': False # When show_optional=True
193
}
194
}
195
}
196
```
197
198
## Types
199
200
```python { .api }
201
# Core function types
202
from typing import Any, Dict, List, Optional, Union
203
204
ModuleName = str
205
DependencyName = str
206
ImportStack = List[List[str]]
207
208
# Simple return format
209
SimpleDependencyMap = Dict[ModuleName, List[DependencyName]]
210
211
# Extended return format
212
ExtendedDependencyInfo = Dict[str, Any] # Contains 'type', 'stack', 'optional' keys
213
ExtendedDependencyMap = Dict[ModuleName, Dict[DependencyName, ExtendedDependencyInfo]]
214
215
# Function return type
216
TrackModuleReturn = Union[SimpleDependencyMap, ExtendedDependencyMap]
217
```