usage.rst

Usage

Grimp provides an API in the form of an ImportGraph that represents all the imports within one or more top-level Python packages. This object has various methods that make it easy to find out information about the packages' structures and interdependencies.

Terminology

The terminology around Python packages and modules can be a little confusing. Here are the definitions we use, taken in part from the official Python docs:

• Module: A file containing Python definitions and statements. This includes ordinary .py files and __init__.py files.
• Package: A Python module which can contain submodules or recursively, subpackages.
• Top Level Package: A package that is not a subpackage of another package.
• Graph: A graph in the mathematical sense of a collection of items with relationships between them. Grimp's ImportGraph is a directed graph of imports between modules.
• Direct Import: An import from one module to another.
• Import Chain: A chain of direct imports between two modules, possibly via other modules. For example, if mypackage.foo imports mypackage.bar, which in turn imports mypackage.baz, then there is an import chain between mypackage.foo and mypackage.baz.
• Squashed Module: A module in the graph that represents both itself and all its descendants. Squashed modules allow parts of the graph to be simplified. For example, if you include external packages when building the graph, each external package will exist in the graph as a single squashed module.

Building the graph

import grimp

# Single package
graph = grimp.build_graph('mypackage')

# Multiple packages
graph = grimp.build_graph('mypackage', 'anotherpackage', 'onemore')

# Include imports of external packages
graph = grimp.build_graph('mypackage', include_external_packages=True)

# Exclude imports within a TYPE_CHECKING guard
graph = grimp.build_graph('mypackage', exclude_type_checking_imports=True)

# Use a different cache directory, or disable caching altogether
graph = grimp.build_graph('mypackage', cache_dir="/path/to/cache")
graph = grimp.build_graph('mypackage', cache_dir=None)

Methods for analysing the module tree

Methods for analysing direct imports

Methods for analysing import chains

Higher level analysis

A layer within a layered architecture.

module_tails

set[str]: A set, each element of which is the final component of a module name. This 'tail' is combined with any container names to provide the full module name. For example, if a container is "mypackage" then to refer to "mypackage.foo" you would supply "foo" as the module tail.

independent

bool: Whether the sibling modules within this layer are required to be independent.

A collection of import dependencies from one Python package to another.

importer

str: The full name of the package within which all the routes start; the downstream package. E.g. "mypackage.foo".

imported

str: The full name of the package within which all the routes end; the upstream package. E.g. "mypackage.bar".

routes

frozenset[grimp.Route]: A set of .Route objects from importer to imported.

A set of import chains that share the same middle.

The route fans in at the head and out at the tail, but the middle of the chain just links individual modules.

Example: the following Route represents a chain of imports from mypackage.orange -> mypackage.utils -> mypackage.helpers -> mypackage.green, plus an import from mypackage.red to mypackage.utils, and an import from mypackage.helpers to mypackage.blue:

Route(
    heads=frozenset(
        {
            "mypackage.orange",
            "mypackage.red",
        }
    ),
    middle=(
        "mypackage.utils",
        "mypackage.helpers",
    ),
    tails=frozenset(
        {
            "mypackage.green",
            "mypackage.blue",
        }
    ),
)

heads

frozenset[str]: The importer modules at the start of the chain.

middle

tuple[str]: A sequence of imports that link the head modules to the tail modules.

tails

frozenset[str]: Imported modules at the end of the chain.

Methods for manipulating the graph