Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@
Changelog
=========

latest
------

* Add ``exclude_shared_descendants`` parameter to ``find_shortest_chain``, ``find_shortest_chains``,
``chain_exists`` and ``direct_import_exists``, to allow searching between packages where one
contains the other.

3.20 (2026-11-13)
-----------------

Expand Down
24 changes: 20 additions & 4 deletions docs/usage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -136,12 +136,16 @@ Methods for analysing the module tree
Methods for analysing direct imports
------------------------------------

.. py:function:: ImportGraph.direct_import_exists(importer, imported, as_packages=False)
.. py:function:: ImportGraph.direct_import_exists(importer, imported, as_packages=False, exclude_shared_descendants=False)

:param str importer: A module name.
:param str imported: A module name.
:param bool as_packages: Whether or not to treat the supplied modules as individual modules, or as entire
packages (including any descendants).
:param bool exclude_shared_descendants: Only applies if ``as_packages`` is True. By default, a ``ValueError`` is raised
if the modules have shared descendants (i.e. one is a package that contains the other). If True, the shared
descendants are instead excluded from the outer package, so imports are checked between the inner package and
the rest of the outer package. Defaults to False.
:return: Whether or not the importer directly imports the imported module.
:rtype: ``True`` or ``False``.

Expand Down Expand Up @@ -260,7 +264,7 @@ Methods for analysing import chains
:return: All the modules that are imported (even indirectly) by the supplied module.
:rtype: A set of strings.

.. py:function:: ImportGraph.find_shortest_chain(importer, imported, as_packages=False)
.. py:function:: ImportGraph.find_shortest_chain(importer, imported, as_packages=False, exclude_shared_descendants=False)

:param str importer: The module at the start of a potential chain of imports between ``importer`` and ``imported``
(i.e. the module that potentially imports ``imported``, even indirectly).
Expand All @@ -269,29 +273,41 @@ Methods for analysing import chains
or as packages (including any descendants, if there are any). If
treating them as packages, all descendants of ``importer`` and
``imported`` will be checked too.
:param bool exclude_shared_descendants: Only applies if ``as_packages`` is True. By default, a ``ValueError`` is raised
if the modules have shared descendants (i.e. one is a package that contains the other). If True, the shared
descendants are instead excluded from the outer package, so chains are searched between the inner package and
the rest of the outer package. Defaults to False.
:return: The shortest chain of imports between the supplied modules, or None if no chain exists.
:rtype: A tuple of strings, ordered from importer to imported modules, or None.

.. py:function:: ImportGraph.find_shortest_chains(importer, imported, as_packages=True)
.. py:function:: ImportGraph.find_shortest_chains(importer, imported, as_packages=True, exclude_shared_descendants=False)

:param str importer: A module or subpackage within the graph.
:param str imported: Another module or subpackage within the graph.
:param bool as_packages: Whether or not to treat the imported and importer as an individual module,
or as a package (including any descendants, if there are any). If treating them as packages, all descendants
of ``importer`` and ``imported`` will be checked too. Defaults to True.
:param bool exclude_shared_descendants: Only applies if ``as_packages`` is True. By default, a ``ValueError`` is raised
if the modules have shared descendants (i.e. one is a package that contains the other). If True, the shared
descendants are instead excluded from the outer package, so chains are searched between the inner package and
the rest of the outer package. Defaults to False.
:return: The shortest import chains that exist between the ``importer`` and ``imported``, and between any modules
contained within them. Only one chain per upstream/downstream pair will be included. Any chains that are
contained within other chains in the result set will be excluded.
:rtype: A set of tuples of strings. Each tuple is ordered from importer to imported modules.

.. py:function:: ImportGraph.chain_exists(importer, imported, as_packages=False)
.. py:function:: ImportGraph.chain_exists(importer, imported, as_packages=False, exclude_shared_descendants=False)

:param str importer: The module at the start of the potential chain of imports (as in ``find_shortest_chain``).
:param str imported: The module at the end of the potential chain of imports (as in ``find_shortest_chain``).
:param bool as_packages: Whether to treat the supplied modules as individual modules,
or as packages (including any descendants, if there are any). If
treating them as packages, all descendants of ``importer`` and
``imported`` will be checked too.
:param bool exclude_shared_descendants: Only applies if ``as_packages`` is True. By default, a ``ValueError`` is raised
if the modules have shared descendants (i.e. one is a package that contains the other). If True, the shared
descendants are instead excluded from the outer package, so chains are searched between the inner package and
the rest of the outer package. Defaults to False.
:return: Return whether any chain of imports exists between ``importer`` and ``imported``,
even indirectly; in other words, does ``importer`` depend on ``imported``?
:rtype: bool
Expand Down
29 changes: 10 additions & 19 deletions rust/src/graph/direct_import_queries.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
use crate::errors::{GrimpError, GrimpResult};
use crate::errors::GrimpResult;
use crate::graph::{
EMPTY_IMPORT_DETAILS, EMPTY_MODULE_TOKENS, ExtendWithDescendants, Graph, ModuleIterator,
ModuleToken, PyImportDetails,
Expand All @@ -16,16 +16,14 @@ impl Graph {
importer: ModuleToken,
imported: ModuleToken,
as_packages: bool,
exclude_shared_descendants: bool,
) -> GrimpResult<bool> {
let mut importers: FxHashSet<_> = importer.into();
let mut importeds: FxHashSet<_> = imported.into();
if as_packages {
importers.extend_with_descendants(self);
importeds.extend_with_descendants(self);
if !(&importers & &importeds).is_empty() {
return Err(GrimpError::SharedDescendants);
}
}
let (importers, importeds) = self.get_importer_and_imported_modules(
importer,
imported,
as_packages,
exclude_shared_descendants,
)?;

let direct_imports = importers
.iter()
Expand All @@ -43,15 +41,8 @@ impl Graph {
) -> GrimpResult<FxHashSet<(ModuleToken, ModuleToken)>> {
let mut all_imports: FxHashSet<(ModuleToken, ModuleToken)> = FxHashSet::default();

let mut importers: FxHashSet<_> = importer.into();
let mut importeds: FxHashSet<_> = imported.into();
if as_packages {
importers.extend_with_descendants(self);
importeds.extend_with_descendants(self);
if !(&importers & &importeds).is_empty() {
return Err(GrimpError::SharedDescendants);
}
}
let (importers, importeds) =
self.get_importer_and_imported_modules(importer, imported, as_packages, false)?;

for importer_module in importers.iter() {
if let Some(all_imports_imported_by_this_one) = self.imports.get(*importer_module) {
Expand Down
41 changes: 40 additions & 1 deletion rust/src/graph/hierarchy_queries.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
use crate::graph::{Graph, MODULE_NAMES, Module, ModuleIterator, ModuleToken};
use crate::errors::{GrimpError, GrimpResult};
use crate::graph::{
ExtendWithDescendants, Graph, MODULE_NAMES, Module, ModuleIterator, ModuleToken,
};
use crate::module_expressions::ModuleExpression;
use rustc_hash::FxHashSet;

Expand Down Expand Up @@ -39,6 +42,42 @@ impl Graph {
children.into_iter()
}

/// Return the sets of modules to search between, for an importer and an imported module.
///
/// If `as_packages` is true, each set includes the descendants of the module. In that case, if
/// the sets have modules in common (i.e. one module is a descendant of the other, or they are
/// the same module), it is an error, unless `exclude_shared_descendants` is true. If it is,
/// the shared modules - which are the whole of the inner package - are removed from the outer
/// package. If the modules are the same, nothing is left in the importer set.
pub fn get_importer_and_imported_modules(
&self,
importer: ModuleToken,
imported: ModuleToken,
as_packages: bool,
exclude_shared_descendants: bool,
) -> GrimpResult<(FxHashSet<ModuleToken>, FxHashSet<ModuleToken>)> {
let mut importers = FxHashSet::from_iter([importer]);
let mut importeds = FxHashSet::from_iter([imported]);
if as_packages {
importers.extend_with_descendants(self);
importeds.extend_with_descendants(self);

let shared: FxHashSet<_> = importers.intersection(&importeds).cloned().collect();
if !shared.is_empty() {
if !exclude_shared_descendants {
return Err(GrimpError::SharedDescendants);
}
let outer = if importers.len() >= importeds.len() {
&mut importers
} else {
&mut importeds
};
outer.retain(|module| !shared.contains(module));
}
}
Ok((importers, importeds))
}

/// Returns an iterator over the passed modules descendants.
///
/// Parent modules will be yielded before their child modules.
Expand Down
6 changes: 3 additions & 3 deletions rust/src/graph/higher_order_queries.rs
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ impl Graph {
) -> GrimpResult<Option<PackageDependency>> {
// Shortcut the detailed implementation in the case of no chains.
// This will be much faster!
if !self.chain_exists(from_layer, to_layer, true)? {
if !self.chain_exists(from_layer, to_layer, true, false)? {
return Ok(None);
}

Expand Down Expand Up @@ -173,15 +173,15 @@ impl Graph {
let heads = from_layer_with_descendants
.iter()
.filter(|importer| {
self.direct_import_exists(**importer, *middle.first().unwrap(), false)
self.direct_import_exists(**importer, *middle.first().unwrap(), false, false)
.unwrap()
})
.cloned()
.collect::<FxHashSet<_>>();
let tails = to_layer_with_descendants
.iter()
.filter(|imported| {
self.direct_import_exists(*middle.last().unwrap(), **imported, false)
self.direct_import_exists(*middle.last().unwrap(), **imported, false, false)
.unwrap()
})
.cloned()
Expand Down
46 changes: 23 additions & 23 deletions rust/src/graph/import_chain_queries.rs
Original file line number Diff line number Diff line change
Expand Up @@ -37,22 +37,20 @@ impl Graph {
importer: ModuleToken,
imported: ModuleToken,
as_packages: bool,
exclude_shared_descendants: bool,
) -> GrimpResult<Option<Vec<ModuleToken>>> {
if as_packages {
self.find_shortest_chain_with_excluded_modules_and_imports(
&importer.conv::<FxHashSet<_>>().with_descendants(self),
&imported.conv::<FxHashSet<_>>().with_descendants(self),
&FxHashSet::default(),
&FxHashMap::default(),
)
} else {
self.find_shortest_chain_with_excluded_modules_and_imports(
&importer.conv::<FxHashSet<_>>(),
&imported.conv::<FxHashSet<_>>(),
&FxHashSet::default(),
&FxHashMap::default(),
)
}
let (from_modules, to_modules) = self.get_importer_and_imported_modules(
importer,
imported,
as_packages,
exclude_shared_descendants,
)?;
self.find_shortest_chain_with_excluded_modules_and_imports(
&from_modules,
&to_modules,
&FxHashSet::default(),
&FxHashMap::default(),
)
}

pub(crate) fn find_shortest_chain_with_excluded_modules_and_imports(
Expand All @@ -76,9 +74,10 @@ impl Graph {
importer: ModuleToken,
imported: ModuleToken,
as_packages: bool,
exclude_shared_descendants: bool,
) -> GrimpResult<bool> {
Ok(self
.find_shortest_chain(importer, imported, as_packages)?
.find_shortest_chain(importer, imported, as_packages, exclude_shared_descendants)?
.is_some())
}

Expand All @@ -87,19 +86,20 @@ impl Graph {
importer: ModuleToken,
imported: ModuleToken,
as_packages: bool,
exclude_shared_descendants: bool,
) -> GrimpResult<FxHashSet<Vec<ModuleToken>>> {
// Shortcut the detailed implementation in the case of no chains.
// This will be much faster!
if !self.chain_exists(importer, imported, as_packages)? {
if !self.chain_exists(importer, imported, as_packages, exclude_shared_descendants)? {
return Ok(FxHashSet::default());
}

let mut downstream_modules = FxHashSet::from_iter([importer]);
let mut upstream_modules = FxHashSet::from_iter([imported]);
if as_packages {
downstream_modules.extend_with_descendants(self);
upstream_modules.extend_with_descendants(self);
}
let (downstream_modules, upstream_modules) = self.get_importer_and_imported_modules(
importer,
imported,
as_packages,
exclude_shared_descendants,
)?;

let chains = self
._find_shortest_chains(
Expand Down
29 changes: 19 additions & 10 deletions rust/src/graph/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -380,18 +380,22 @@ impl GraphWrapper {
.collect())
}

#[pyo3(signature = (*, importer, imported, as_packages = false))]
#[pyo3(signature = (*, importer, imported, as_packages = false, exclude_shared_descendants = false))]
pub fn direct_import_exists(
&self,
importer: &str,
imported: &str,
as_packages: bool,
exclude_shared_descendants: bool,
) -> PyResult<bool> {
let importer = self.get_visible_module_by_name(importer)?.token();
let imported = self.get_visible_module_by_name(imported)?.token();
Ok(self
._graph
.direct_import_exists(importer, imported, as_packages)?)
Ok(self._graph.direct_import_exists(
importer,
imported,
as_packages,
exclude_shared_descendants,
)?)
}

#[pyo3(signature = (module, as_package=false))]
Expand Down Expand Up @@ -550,18 +554,19 @@ impl GraphWrapper {
.collect())
}

#[pyo3(signature = (importer, imported, as_packages=false))]
#[pyo3(signature = (importer, imported, as_packages=false, exclude_shared_descendants=false))]
pub fn find_shortest_chain(
&self,
importer: &str,
imported: &str,
as_packages: bool,
exclude_shared_descendants: bool,
) -> PyResult<Option<Vec<String>>> {
let importer = self.get_visible_module_by_name(importer)?.token();
let imported = self.get_visible_module_by_name(imported)?.token();
Ok(self
._graph
.find_shortest_chain(importer, imported, as_packages)?
.find_shortest_chain(importer, imported, as_packages, exclude_shared_descendants)?
.map(|chain| {
chain
.iter()
Expand All @@ -571,31 +576,35 @@ impl GraphWrapper {
}))
}

#[pyo3(signature = (importer, imported, as_packages=false))]
#[pyo3(signature = (importer, imported, as_packages=false, exclude_shared_descendants=false))]
pub fn chain_exists(
&self,
importer: &str,
imported: &str,
as_packages: bool,
exclude_shared_descendants: bool,
) -> PyResult<bool> {
let importer = self.get_visible_module_by_name(importer)?.token();
let imported = self.get_visible_module_by_name(imported)?.token();
Ok(self._graph.chain_exists(importer, imported, as_packages)?)
Ok(self
._graph
.chain_exists(importer, imported, as_packages, exclude_shared_descendants)?)
}

#[pyo3(signature = (importer, imported, as_packages=true))]
#[pyo3(signature = (importer, imported, as_packages=true, exclude_shared_descendants=false))]
pub fn find_shortest_chains<'py>(
&self,
py: Python<'py>,
importer: &str,
imported: &str,
as_packages: bool,
exclude_shared_descendants: bool,
) -> PyResult<Bound<'py, PySet>> {
let importer = self.get_visible_module_by_name(importer)?.token();
let imported = self.get_visible_module_by_name(imported)?.token();
let chains = self
._graph
.find_shortest_chains(importer, imported, as_packages)?
.find_shortest_chains(importer, imported, as_packages, exclude_shared_descendants)?
.into_iter()
.map(|chain| {
PyTuple::new(
Expand Down
Loading
Loading