0
# Import Tracker
1

2
A Python library offering comprehensive dependency management capabilities for modular Python projects. Import Tracker enables developers to track dependencies across individual modules, implement lazy import error handling to prevent crashes from missing optional dependencies, and programmatically determine setuptools requirements.
3

4
## Package Information
5

6
- **Package Name**: import-tracker
7
- **Language**: Python
8
- **Installation**: `pip install import-tracker`
9

10
## Core Imports
11

12
```python
13
import import_tracker
14
```
15

16
Main functions:
17

18
```python
19
from import_tracker import track_module, lazy_import_errors, LazyModule
20
```
21

22
Setup tools for dependency management:
23

24
```python
25
from import_tracker.setup_tools import parse_requirements
26
```
27

28
## Basic Usage
29

30
```python
31
import import_tracker
32

33
# Track dependencies of a module
34
dependencies = import_tracker.track_module("my_module", recursive=True)
35
print(dependencies)
36

37
# Enable lazy import errors to defer ImportError until usage
38
with import_tracker.lazy_import_errors():
39
    import some_optional_module  # Won't crash if missing
40
    
41
# Use lazy module for deferred imports
42
lazy_mod = import_tracker.LazyModule("expensive_module")
43
```
44

45
## Architecture
46

47
Import Tracker operates on three key principles:
48

49
- **Dependency Tracking**: Uses subprocess isolation to safely import modules and track their dependencies without affecting the current Python environment
50
- **Lazy Error Handling**: Implements custom meta path finders and loaders to intercept import failures and defer errors until actual usage
51
- **Setuptools Integration**: Analyzes dependency patterns to automatically generate install_requires and extras_require configurations
52

53
The library provides both programmatic APIs for runtime dependency management and CLI tools for static analysis of Python projects.
54

55
## Capabilities
56

57
### Dependency Tracking
58

59
Tracks which external packages are required by specific modules or entire projects. This enables fine-grained dependency analysis and helps identify unused dependencies in large codebases.
60

61
```python { .api }
62
def track_module(
63
    module_name: str,
64
    package_name: Optional[str] = None,
65
    log_level: Optional[int] = None,
66
    recursive: bool = False,
67
    num_jobs: int = 0,
68
    side_effect_modules: Optional[List[str]] = None,
69
    submodules: Optional[List[str]] = None,
70
    track_import_stack: bool = False,
71
    detect_transitive: bool = False,
72
) -> Dict[str, List[str]]: ...
73
```
74

75
[Dependency Tracking](./dependency-tracking.md)
76

77
### Lazy Import Error Handling
78

79
Enables lazy import errors that defer ModuleNotFoundError until the module is actually used, allowing graceful handling of optional dependencies in projects with complex import hierarchies.
80

81
```python { .api }
82
def lazy_import_errors(
83
    *,
84
    get_extras_modules: Optional[Callable[[], Set[str]]] = None,
85
    make_error_message: Optional[Callable[[str], str]] = None,
86
): ...
87

88
class LazyModule(ModuleType):
89
    def __init__(self, name: str, package: Optional[str] = None): ...
90
    def __getattr__(self, name: str) -> any: ...
91
```
92

93
[Lazy Import Handling](./lazy-imports.md)
94

95
### Setuptools Integration
96

97
Automatically generates install_requires and extras_require configurations for setuptools by analyzing project dependencies and categorizing them into core and optional dependency sets.
98

99
```python { .api }
100
def parse_requirements(
101
    requirements: Union[List[str], str],
102
    library_name: str,
103
    extras_modules: Optional[List[str]] = None,
104
    **kwargs,
105
) -> Tuple[List[str], Dict[str, List[str]]]: ...
106
```
107

108
[Setuptools Integration](./setuptools-integration.md)
109

110
## Types
111

112
```python { .api }
113
from typing import Dict, List, Optional, Set, Union, Callable, Tuple
114

115
# Dependency mapping type
116
DependencyMapping = Dict[str, List[str]]
117

118
# Requirements specification
119
RequirementsList = Union[List[str], str]
120

121
# Extras require mapping  
122
ExtrasRequireDict = Dict[str, List[str]]
123
```