0
# Import Tracker
1

2
A comprehensive Python library for managing dependencies in modular Python projects. Import Tracker provides tools for tracking module dependencies, implementing lazy import error handling to prevent crashes from uninstalled optional dependencies, and programmatically determining 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
Common imports for specific functionality:
17

18
```python
19
from import_tracker import track_module, lazy_import_errors
20
from import_tracker.setup_tools import parse_requirements
21
```
22

23
## Basic Usage
24

25
```python
26
import import_tracker
27

28
# Track dependencies of a module
29
deps = import_tracker.track_module('my_module')
30
print(deps)  # {'my_module': ['requests', 'numpy']}
31

32
# Enable lazy import errors globally
33
from import_tracker import lazy_import_errors
34
lazy_import_errors()
35

36
# Use as context manager for specific imports
37
with lazy_import_errors():
38
    from . import optional_module  # Won't crash if missing
39

40
# Parse requirements for setuptools
41
from import_tracker.setup_tools import parse_requirements
42
install_requires, extras_require = parse_requirements(
43
    requirements='requirements.txt',
44
    library_name='my_package',
45
    extras_modules=['my_package.widgets']
46
)
47
```
48

49
## Architecture
50

51
Import Tracker is built around three core capabilities:
52

53
- **Dependency Tracking**: Uses bytecode analysis to discover all module dependencies, including direct, transitive, and optional dependencies
54
- **Lazy Import Errors**: Implements a custom import system using meta path finders and loaders to defer ImportError exceptions until actual usage
55
- **Setup Tools Integration**: Bridges dependency analysis with setuptools configuration by automatically generating install_requires and extras_require
56

57
## Capabilities
58

59
### Dependency Tracking
60

61
Comprehensive module dependency analysis with support for submodule tracking, import stack tracing, and direct vs transitive dependency classification.
62

63
```python { .api }
64
def track_module(
65
    module_name: str,
66
    package_name: Optional[str] = None,
67
    submodules: Union[List[str], bool] = False,
68
    track_import_stack: bool = False,
69
    full_depth: bool = False,
70
    detect_transitive: bool = False,
71
    show_optional: bool = False,
72
) -> Union[Dict[str, List[str]], Dict[str, Dict[str, Any]]]:
73
    """Track the dependencies of a single python module"""
74
```
75

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

78
### Lazy Import Error Handling
79

80
Context manager and function for deferring ImportError exceptions until modules are actually used, with support for custom error messages and extras integration.
81

82
```python { .api }
83
def lazy_import_errors(
84
    *,
85
    get_extras_modules: Optional[Callable[[], Set[str]]] = None,
86
    make_error_message: Optional[Callable[[str], str]] = None,
87
):
88
    """Enable lazy import errors"""
89
```
90

91
[Lazy Import Errors](./lazy-import-errors.md)
92

93
### Setup Tools Integration
94

95
Automatic generation of setuptools configuration from dependency analysis, supporting install_requires and extras_require computation.
96

97
```python { .api }
98
def parse_requirements(
99
    requirements: Union[List[str], str],
100
    library_name: str,
101
    extras_modules: Optional[List[str]] = None,
102
    full_depth: bool = True,
103
    keep_optional: Union[bool, Dict[str, List[str]]] = False,
104
    **kwargs,
105
) -> Tuple[List[str], Dict[str, List[str]]]:
106
    """Parse requirements and generate install_requires and extras_require"""
107
```
108

109
[Setup Tools Integration](./setup-tools.md)
110

111
## Command Line Interface
112

113
Import Tracker can be run as a command-line tool for dependency analysis:
114

115
```bash
116
# Track a single module
117
python -m import_tracker --name my_library
118

119
# Track with all submodules and show optional dependencies
120
python -m import_tracker --name my_library --submodules --show_optional
121

122
# Generate detailed analysis with import stacks
123
python -m import_tracker --name my_library --track_import_stack --detect_transitive --indent 2
124
```
125

126
## Types
127

128
```python { .api }
129
# Type aliases used throughout the package
130
Union[Dict[str, List[str]], Dict[str, Dict[str, Any]]]  # track_module return type
131
Tuple[List[str], Dict[str, List[str]]]  # parse_requirements return type
132
Optional[Callable[[], Set[str]]]  # get_extras_modules function type
133
Optional[Callable[[str], str]]  # make_error_message function type
134
```
135

136
## Constants
137

138
```python { .api }
139
# Dependency type constants
140
TYPE_DIRECT = "direct"
141
TYPE_TRANSITIVE = "transitive"
142

143
# Information keys for dependency metadata
144
INFO_TYPE = "type"
145
INFO_STACK = "stack" 
146
INFO_OPTIONAL = "optional"
147
```