Adapters

Its role

An adapter connects a core contract to an interface or technology. A driving adapter starts the workflow; a driven adapter provides a capability the core asks for.

The CLI, filesystem, Python AST, and NetworkX components remain independent. Helpers inside one component may work together. main.ApplicationFactory, outside these packages, connects the concrete parts.

Follow a CLI run

Run pyarchgraph demo from the parent of this example directory.

# demo/orders.py
import inventory

# demo/inventory.py
import orders

1. Turn CLI choices into a request

   CliApplication reads roots, exclusions, gate, detail level, optional package depth, and an optional config path. TomlOptionsReader translates an explicitly selected TOML file and CLI choices into AnalysisOptions. The CLI calls the ProjectAnalyzer port.

2. Discover the files

   When the application requests it, FileSystemProjectAccess locates roots and supplies packaging clues. FileSystemSourceDiscovery inventories sources, exclusions, bindings, and target declarations. It recognises ordinary package/module precedence within a root.

3. Read imports without running the project

   AstImportFactSource coordinates SourceReader, PythonAstParser, and ModuleImportExtractor. The two statements become two ImportFactDraft values, with locations and context. The application later assigns final fact identities.

4. Supply the graph operations

   During view analysis, NetworkXGraphAlgorithms prepares graphs and returns NetworkXGraphHandle objects. These find groups whose nodes can all reach one another and a witness cycle when asked. Domain code decides what that cycle means and which evidence supports it.

5. Present the result

   JsonReportRenderer turns the returned report into JSON for standard output. CliExitCodePolicy sees complete coverage and a gate error finding, so this example exits with 1.

How parts connect

Package analysis uses the same filesystem, parser and graph adapters. Select a package gate with --gate package-structural, --gate package-non-typing or --gate package-module-body. --package-max-depth N takes a positive integer and caps dotted package names; omitting it keeps immediate packages. The option is carried through AnalysisOptions; TOML remains focused on ownership and target boundaries.

JsonReportRenderer presents schema 0.8 using the same generic serialization. Each view gains dependencies: null when not requested, or an array of all requested relationships with readable source evidence. The three default package views always provide the array, which can be empty. These relationships are independent of --details component-edges, which controls evidence inside cycle findings.

The AST component also defines small local contracts—SourceTextReader, AstParser, and ImportExtractor—for its own collaborators. Syntax-tree details stay inside that component.

The composition root, ApplicationFactory, chooses defaults or accepts supplied collaborators, then builds an analyser or CLI. The small __main__.main entry point starts the CLI.

Configuration is read only when selected with --config. Packaging metadata is inspected as data, and analysed source is parsed without execution. The tool does not discover runtime dependencies by importing the project.

Module map

Choose a module to jump to its classes below. Package initialisers are intentionally empty; callers import from the defining modules.

Every class

All 18 classes in this package, including services, contracts, an exception, and internal helpers. Names link to the source file; descriptions match the role summaries in the code.