importguard is a powerful tool designed to measure and enforce import-time behavior in Python projects, addressing critical issues that can arise during the import process. It stops slow imports and hidden side effects from making their way into production, ensuring a more reliable and efficient codebase.

The Problem

Python imports can inadvertently lead to performance bottlenecks and unreliable behavior:

• Slow Startup: Heavy modules such as pandas, torch, and boto3 can result in longer cold starts for your CLI or server due to unnecessary imports or expensive initializations.
• Hidden Side Effects: Modules may execute unintended operations like reading configurations, making network calls, or writing to the filesystem upon import, which complicates debugging and reliability.
• Difficult to Track: These issues can be subtle, often becoming noticeable only when users encounter problems.

importguard transforms these concerns into quantifiable metrics, allowing enforcement through Continuous Integration (CI) pipelines.

Quick Start

Measure Import Times

Check the import time of any module:

$ importguard check requests

✓ requests imported in 45ms

Top 5 slowest imports:
  1. urllib3.util.ssl_     12ms  
  2. urllib3.util          8ms  
  3. requests.adapters     7ms  
  4. charset_normalizer    6ms  
  5. requests.models       5ms

Enforce Import Budgets

$ importguard check mypkg --max-ms 200

✓ mypkg imported in 127ms (budget: 200ms)

If the budget is exceeded:

$ importguard check mypkg --max-ms 100

✗ FAIL: mypkg imported in 127ms (budget: 100ms)

Ban Specific Imports

Prevent certain modules from being imported at the top level:

$ importguard check mypkg.cli --ban pandas --ban torch

✗ FAIL: mypkg.cli imports banned module: pandas

Get Consistent Results with --repeat

To account for variability in import timing, use --repeat to run multiple iterations:

$ importguard check mypkg --max-ms 150 --repeat 5

Running 5 iterations...
✓ mypkg imported in 127ms (median of 5 runs: 118ms, 127ms, 132ms, 124ms, 129ms)

Pin Python Interpreter

Specify the Python interpreter to test across different versions:

$ importguard check mypkg --python /usr/local/bin/python3.11 --max-ms 200

✓ mypkg imported in 134ms (using Python 3.11.7)

Configuration

Create a .importguard.toml file in your project root to customize settings:

[importguard]
max_total_ms = 200

[importguard.budgets]
"mypkg" = 150
"mypkg.cli" = 100
"mypkg.api" = 80

[importguard.banned]
"mypkg.cli" = ["pandas", "numpy", "torch"]
"mypkg" = ["boto3", "tensorflow"]

Run import checks using the config:

$ importguard check mypkg --config .importguard.toml

CI Integration

Integration with CI systems helps maintain import performance:

GitHub Actions Example

name: Import Guard

on: [push, pull_request]

jobs:
  import-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install -e .
          pip install importguardpy
      - name: Check import performance
        run: |
          importguard check mypkg --config .importguard.toml --fail-on-warning --repeat 3

Pre-commit Hook Example

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: importguard
        name: importguard
        entry: importguard check mypkg --max-ms 200
        language: system
        pass_filenames: false
        always_run: true

Use Cases

• CLI Startup Time Management: Ensure quick CLI responses to user commands.
• Library Hygiene: Guarantee that importing a library does not lead to unnecessary dependencies being loaded.
• Serverless Cold Start Optimization: Particularly relevant for environments like AWS Lambda, where import times can be detrimental to performance.
• Monorepo Management: Act as a guardrail against unwanted imports across multiple modules.

Roadmap

• Implement baseline comparisons and side-effect detection in future releases.

Contributing

Contributions are encouraged; open an issue to discuss potential improvements.