Skip to main content

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

Project description


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.


  • 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.


pip install import-guard


from import_guard import guard, mod

    # 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


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

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


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)

import array  # shows warning

Match star import


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.top_level(["math", "json"])
    | mod.matches("log.*")

Nice examples:

  • deny non-lazy imports in some module:
    "test_proj.business_logic": mod.top_level(mod.matches(".*")),
  • deny start imports in project:

Non-strict mode

# not enabled for `prod`
if env == "staging":
    # warn on forbidden import
elif env == "local":
    # raise ForbiddenImportError

Rules hierarchy

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

    "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:

import api

def view():
    import tasks

import pandas

Here 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 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
    "test_proj.tasks", caller="test_proj.api"
)  # False
    "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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

import-guard-0.1.2.tar.gz (11.8 kB view hashes)

Uploaded source

Built Distribution

import_guard-0.1.2-py2.py3-none-any.whl (9.8 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page