import-guard

Enforce that some modules can't be imported from other modules. In runtime!

If you need a static analysis tools, take a look at flake8-import-graph.

Features:

• works in runtime
• checks dynamic imports
• customizable rules

This library has some performance overhead. In some cases it may lead to 1.5-2x slower import time (and startup time respectively). It's recommended to enable import_guard only during the development.

Installation

pip install import-guard

Usage

from import_guard import guard, mod


guard.set_deny_rules({
    # deny `csv` import from `test_proj` and submodules
    "test_proj": "csv",  # the same as mod("csv")
    # deny `selenium` and top_level `test_proj.tasks` imports from test_proj.api
    # but allow `test_proj.tasks` import inside the function (lazy import)
    # the same as mod("selenium") | (mod("test_proj.tasks") & Flags.TopLevel)
    "test_proj.api": ["selenium", mod.top_level("test_proj.tasks")],
    # deny `test_proj.api` and `test_proj.business_logic` imports from `test_proj.core`
    "test_proj.core": mod.matches(r"test_proj\.(api|business_logic)"),
    # deny all imports except `logging` and `yaml`
    "test_proj.logging": ~mod.explicit(["logging", "yaml"]),
})

# raise ForbiddenImportError
guard.enable(strict=True)

Rules

the code below is copy-pastable into the Python interpreter and assumes the following imports:

from importlib import reload
from import_guard import guard, mod
# enable guard in advance
guard.enable()

Exact match

guard.set_deny_rules({"<stdin>": "decimal"})
# shortcut for mod("decimal")

from decimal import Decimal  # shows warning

from enum import Enum  # ok

Explicit match

Consider the following code:

guard.set_deny_rules({"<stdin>": "re"})

import csv  # shows warning!

What happened?

csv imports some modules under the hood, e.g. re or io. We implicitly initiated loading of the re module through the csv module (rule matches at depth = 1). This is the default behavior. You can check only explicit imports using mod.explicit("re") function.

guard.set_deny_rules({"<stdin>": mod.explicit("re")})
reload(csv)  # allowed
import re  # shows warning

Match multiple modules

guard.set_deny_rules({"<stdin>": ["logging", "json"]})
# the same as mod.any(["logging", "json'])
# the same as mod("logging") | mod("json")


import json  # shows warning
from logging import getLogger  # shows warning

Match by regular expression

guard.set_deny_rules({"<stdin>": mod.matches("log.*")})

# shows multiple warnings
from logging.config import dictConfig

Inversion

guard.set_deny_rules({"<stdin>": ~mod.matches("log.*")})

import io # shows warning

Match only module-level imports

It's common practice doing a local import instead of a global one to break a cycle import or to postpone importing until you run code that actually needs the module you're importing.

# deny module-level imports
guard.set_deny_rules({"<stdin>": mod.top_level("array")})

def some_function():
    import array  # allowed (lazy import)

some_function()
import array  # shows warning

Match star import

guard.set_deny_rules({"<stdin>": mod.star("csv")})

from csv import *  # shows warning

Complex rules

Rules are very flexible. You can combine them together in a different ways and build very complex conditions.

mod.explicit(
    ~mod.top_level(["math", "json"])
    | mod.matches("log.*")
)

Nice examples:

• deny non-lazy imports in some module:

guard.set_deny_rules({
    "test_proj.business_logic": mod.top_level(mod.matches(".*")),
})

• deny start imports in project:

guard.set_deny_rules({
    "test_proj": mod.star(mod.explicit(mod.matches(".*"))),
})

Non-strict mode

# not enabled for `prod`
if env == "staging":
    # warn on forbidden import
    guard.enable(strict=False)
elif env == "local":
    # raise ForbiddenImportError
    guard.enable(strict=True)

Rules hierarchy

The set of deny rule for a module also affects its submodules.

guard.set_deny_rules({
    "test_proj": "json",
    "test_proj.api": ["selenum", "pandas"],
    "test_proj.core": "celery"
})

test_proj.core disallows json and celery imports. test_proj.api.views disallows json, selenium, pandas imports.

Lazy module

Consider the following project structure:

# main.py
import api

# api.py
def view():
    import tasks

# tasks.py
import pandas

Here main.py imports api, which imports tasks lazily, which imports pandas at module level. import_guard handles this case as lazy module import and will think that pandas being imported lazily. Thus, in this case, the following rules do not raise a warning:

guard.set_deny_rules({"tasks": mod.top_level("pandas")})

Custom module matcher

def is_relative_import(import_info, caller_info):
    return import_info.level > 1

# deny relative import
guard.set_deny_rules({"proj": mod.hook(is_relative_import)})

from .api import view  # shows warning
from proj.api import view  # ok

Testing

Rules

Testing rules directly:

rule = mod.top_level(mod.matches(".*"))
# True; mod1 imported at the module level in mod2
rule.test("mod1", caller="mod2")
# False; mod1 doesn't match the top_level constraint
rule.test("mod1", caller="<stdin>", top_level=False)

Testing deny rules through the guard:

guard.is_import_allowed("csv", caller="test_proj.api")  # False
guard.is_import_allowed("logging", caller="test_proj.api")  # True
guard.is_import_allowed("selenium", caller="test_proj.api")  # False
guard.is_import_allowed(
    "test_proj.tasks", caller="test_proj.api"
)  # False
guard.is_import_allowed(
    "test_proj.tasks", caller="test_proj.api", top_level=False
)  # True

Unit tests

Testing with current Python interpreter:

$ python -m unittest discover tests -v

Testing with different Python versions and interpreters:

$ tox