Grimp provides an API in the form of an ImportGraph that represents all the imports within a top-level Python package. This object has various methods that make it easy to find out information about that package's structure and interdependencies.
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
.pyfiles and__init__.pyfiles. - Package: A special kind of module that namespaces other modules using dotted module names. For example, the module name
A.Bdesignates a submodule namedBin a package namedA. Packages take the form of__init__.pyfiles in a container directory. Packages may contain other packages. A package is also a module. - Top Level Package: A package in the root namespace - in other words, one that is not a subpackage. For example,
Ais a top level package, butA.Bis not. - Graph: A graph in the mathematical sense of a collection of items with relationships between them. Grimp's
ImportGraphis a directed graph of imports contained in a particular top level package. - 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.fooimportsmypackage.bar, which in turn importsmypackage.baz, then there is an import chain betweenmypackage.fooandmypackage.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.
import grimp
graph = grimp.build_graph('mypackage')