Import Tracker is a Python package offering a number of capabilities related to tracking and managing optional dependencies in Python projects. Specifically, this project enables developers to:
-
Track the dependencies of a python project to map each module within the project to the set of dependencies it relies on. This can be useful for debugging of dependencies in large projects.
-
Enable lazy import errors in a python projects to prevent code from crashing when uninstalled imports are imported, but not utilized. This can be helpful in large projects, especially those which incorporate lots of hierarchical wild imports, as importing the top level package of such projects can often bring a lot of heavy dependencies into
sys.modules. -
Programmatically determine the
install_requiresandextras_requirearguments tosetuptools.setupwhere the extras sets are determined by a set of modules that should be optional.
Running Import Tracker
To run import_tracker against a project, simply invoke the module’s main:
--package: Allows--nameto be a relative import (seeimportlib.import_module)--recursive: Recurse into sub-modules within the given module to produce the full mapping for the given module--num_jobs: When--recurseis given, run the recursive jobs concurrently with the given number of workers (0 implies serial execution)--indent: Indent the output json for pretty printing--log_level: Set the level of logging (up todebug4) to debug unexpected behavior--submodules: List of sub-modules to recurse on (only used when –recursive set)--side_effect_modules: Modules with known import-time side effect which should always be allowed to import--track_import_stack: Store the stack trace of imports belonging to the tracked module- NOTE: This is very slow and should be used only when performing specific debugging tasks!
Integrating import_tracker into a projects
When using import_tracker to implement optional dependencies in a project, there are two steps to take:
- Enable
lazy_import_errorsfor the set of modules that should be managed as optional - Use
setup_tools.parse_requirementsinsetup.pyto determine theinstall_requiresandextras_requirearguments
In the following examples, we’ll use a fictitious project with the following structure:
my_module/
├── __init__.py
├── utils.py
└── widgets
├── __init__.py
├── widget1.py
└── widget2.py
Enabling lazy_import_errors
The import_tracker.lazy_import_errors function can be invoked directly to enable lazy import errors globally, or used as a context manager to enable them only for a selcted set of modules.
To globally enable lazy import errors, my_module/__init__.py would look like the following:
# Globally enable lazy import errors from import_tracker
