Skip to content

Contract types

Import Linter provides several contract types:

Forbidden

Prevent one set of modules being imported by another.

Read more

Protected

Prevent modules from being directly imported, except by modules in an allow-list.

Read more

Layers

Enforce a 'layered architecture'.

Read more

Independence

Prevent a set of modules depending on each other.

Read more

Acyclic siblings

Forbid dependency cycles between siblings.

Read more

Custom contract types

If none of the built in contract types meets your needs, you can define a custom contract type: see Custom Contract Types.

Options used by multiple contracts

  • ignore_imports: Optional list of imports, each in the form mypackage.foo.importer -> mypackage.bar.imported. These imports will be ignored: if the import would cause a contract to be broken, adding it to the list will cause the contract be kept instead. Supports wildcards.

  • unmatched_ignore_imports_alerting: The alerting level for handling expressions supplied in ignore_imports that do not match any imports in the graph. Choices are:

    • error: Error if there are any unmatched expressions (default).
    • warn: Print a warning for each unmatched expression.
    • none: Do not alert.

  • broken_contract_guidance: A message for Import Linter to display when the contract is broken, below the built-in message. (Optional.) 

[importlinter:contract:no-legacy-colors]
name = Colors should not use the legacy numbers API
type = forbidden
source_modules =
    mypackage.colors
forbidden_modules =
    mypackage.legacy.numbers
broken_contract_guidance =
    Use mypackage.numbers instead - it's the supported top-level interface.
    Migration guide: https://docs.example.com/numbers-migration

[[tool.importlinter.contracts]]
name = "Colors should not use the legacy numbers API"
type = "forbidden"
source_modules = ["mypackage.colors"]
forbidden_modules = ["mypackage.legacy.numbers"]
broken_contract_guidance = """
Use mypackage.numbers instead - it's the supported top-level interface.
Migration guide: https://docs.example.com/numbers-migration
"""

Wildcards

Many contract fields refer to sets of modules - some (but not all) of these support wildcards.

* stands in for a module name, without including subpackages. ** includes subpackages too.

Examples:

  • mypackage.*: matches mypackage.foo but not mypackage.foo.bar.
  • mypackage.*.baz: matches mypackage.foo.baz but not mypackage.foo.bar.baz.
  • mypackage.*.*: matches mypackage.foo.bar and mypackage.foobar.baz.
  • mypackage.**: matches mypackage.foo.bar and mypackage.foo.bar.baz.
  • mypackage.**.qux: matches mypackage.foo.bar.qux and mypackage.foo.bar.baz.qux.
  • mypackage.foo*: not a valid expression. (The wildcard must replace a whole module name.)