[Peter554]

Motivation

Closes #25.

find_upstream_modules and find_downstream_modules can treat the supplied module as a package with as_package=True, and direct_import_exists has as_packages. find_modules_directly_imported_by and find_modules_that_directly_import didn't, which made it awkward to ask "what does this package directly import?" or "what directly imports this package?".

To do that today, you have to find the package's descendants, call the method for each one, combine the results, and remove the modules within the package.

As discussed here import-linter/import-linter#406 (comment)

Changes

Add as_package=False to both methods. With as_package=True:

• the module's descendants are included, as for find_upstream_modules;
• the result excludes modules within the package.

The default behaviour is unchanged. Includes tests, docs and a changelog entry.

[codspeed]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 23 skipped benchmarks¹

---

_{Comparing Peter554:direct-import-methods-as-package (f2e4cfc) with main (3c4c7c9)}

Footnotes

1. 23 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[Copilot]

🟢 Approval recommended

No active review issues block the package-aware direct import query changes.

No open issues 🎉

What changed in this PR

Adds package-aware direct import queries to Grimp, addressing #25. Callers can include a module’s descendants without manually combining and filtering results.

Changes:

• Add optional as_package=False to both direct import query methods, preserving default behavior.
• Implement package-level queries in Rust, excluding imports within the queried package.
• Add Python and Rust tests, API documentation, and a changelog entry.

File	Description
tests/​unit/​application/​graph/​test_direct_imports.py	Test package queries and missing-module errors in both modes.
src/​grimp/​application/​graph.py	Expose and document as_package in the Python API.
rust/​src/​graph/​mod.rs	Pass the new option through the Python–Rust bindings.
rust/​src/​graph/​graph_manipulation.rs	Adapt internal callers while preserving individual-module behavior.
rust/​src/​graph/​direct_import_queries.rs	Implement package-aware queries and add Rust tests.
docs/​usage.rst	Document the parameter and package filtering behavior.
CHANGELOG.rst	Announce the new option and link to #25.

_{Review effort: Balanced}