diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 2182c72b..234cf407 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -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) ----------------- diff --git a/docs/usage.rst b/docs/usage.rst index 447dd96f..4e011e33 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -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``. @@ -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). @@ -269,22 +273,30 @@ 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``). @@ -292,6 +304,10 @@ 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: Return whether any chain of imports exists between ``importer`` and ``imported``, even indirectly; in other words, does ``importer`` depend on ``imported``? :rtype: bool diff --git a/rust/src/graph/direct_import_queries.rs b/rust/src/graph/direct_import_queries.rs index 6a617604..e179a8af 100644 --- a/rust/src/graph/direct_import_queries.rs +++ b/rust/src/graph/direct_import_queries.rs @@ -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, @@ -16,16 +16,14 @@ impl Graph { importer: ModuleToken, imported: ModuleToken, as_packages: bool, + exclude_shared_descendants: bool, ) -> GrimpResult { - 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() @@ -43,15 +41,8 @@ impl Graph { ) -> GrimpResult> { 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) { diff --git a/rust/src/graph/hierarchy_queries.rs b/rust/src/graph/hierarchy_queries.rs index 443e2997..9e6bf329 100644 --- a/rust/src/graph/hierarchy_queries.rs +++ b/rust/src/graph/hierarchy_queries.rs @@ -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; @@ -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, FxHashSet)> { + 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. diff --git a/rust/src/graph/higher_order_queries.rs b/rust/src/graph/higher_order_queries.rs index da9bc4f4..6c5873a1 100644 --- a/rust/src/graph/higher_order_queries.rs +++ b/rust/src/graph/higher_order_queries.rs @@ -134,7 +134,7 @@ impl Graph { ) -> GrimpResult> { // 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); } @@ -173,7 +173,7 @@ 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() @@ -181,7 +181,7 @@ impl Graph { 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() diff --git a/rust/src/graph/import_chain_queries.rs b/rust/src/graph/import_chain_queries.rs index da5295d0..4fcb60c0 100644 --- a/rust/src/graph/import_chain_queries.rs +++ b/rust/src/graph/import_chain_queries.rs @@ -37,22 +37,20 @@ impl Graph { importer: ModuleToken, imported: ModuleToken, as_packages: bool, + exclude_shared_descendants: bool, ) -> GrimpResult>> { - if as_packages { - self.find_shortest_chain_with_excluded_modules_and_imports( - &importer.conv::>().with_descendants(self), - &imported.conv::>().with_descendants(self), - &FxHashSet::default(), - &FxHashMap::default(), - ) - } else { - self.find_shortest_chain_with_excluded_modules_and_imports( - &importer.conv::>(), - &imported.conv::>(), - &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( @@ -76,9 +74,10 @@ impl Graph { importer: ModuleToken, imported: ModuleToken, as_packages: bool, + exclude_shared_descendants: bool, ) -> GrimpResult { Ok(self - .find_shortest_chain(importer, imported, as_packages)? + .find_shortest_chain(importer, imported, as_packages, exclude_shared_descendants)? .is_some()) } @@ -87,19 +86,20 @@ impl Graph { importer: ModuleToken, imported: ModuleToken, as_packages: bool, + exclude_shared_descendants: bool, ) -> GrimpResult>> { // 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( diff --git a/rust/src/graph/mod.rs b/rust/src/graph/mod.rs index 40ff48cb..f6277b68 100644 --- a/rust/src/graph/mod.rs +++ b/rust/src/graph/mod.rs @@ -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 { 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))] @@ -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>> { 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() @@ -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 { 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> { 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( diff --git a/src/grimp/application/graph.py b/src/grimp/application/graph.py index 3c679621..816c152d 100644 --- a/src/grimp/application/graph.py +++ b/src/grimp/application/graph.py @@ -208,7 +208,12 @@ def find_descendants(self, module: str) -> set[str]: # -------------- def direct_import_exists( - self, *, importer: str, imported: str, as_packages: bool = False + self, + *, + importer: str, + imported: str, + as_packages: bool = False, + exclude_shared_descendants: bool = False, ) -> bool: """ Whether or not the importer module directly imports the imported module. @@ -218,9 +223,18 @@ def direct_import_exists( imported: Name of the imported module. as_packages: Whether or not to treat the supplied modules as individual modules, or as entire packages (including any descendants). + exclude_shared_descendants: + Only applies if as_packages is True. By default, modules with shared + descendants (i.e. one is a package that contains the other) raise a + ValueError. 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. """ return self._rustgraph.direct_import_exists( - importer=importer, imported=imported, as_packages=as_packages + importer=importer, + imported=imported, + as_packages=as_packages, + exclude_shared_descendants=exclude_shared_descendants, ) def find_modules_directly_imported_by(self, module: str, as_package: bool = False) -> set[str]: @@ -370,7 +384,11 @@ def find_upstream_modules(self, module: str, as_package: bool = False) -> set[st return self._rustgraph.find_upstream_modules(module, as_package) def find_shortest_chain( - self, importer: str, imported: str, as_packages: bool = False + self, + importer: str, + imported: str, + as_packages: bool = False, + exclude_shared_descendants: bool = False, ) -> tuple[str, ...] | None: """ Attempt to find the shortest chain of imports between two modules, in the direction @@ -381,6 +399,12 @@ def find_shortest_chain( or as packages (including any descendants, if there are any). If treating them as subpackages, all descendants of the supplied modules will be checked too. + exclude_shared_descendants: + Only applies if as_packages is True. By default, modules with shared + descendants (i.e. one is a package that contains the other) raise a + ValueError. 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. Returns: Tuple of module names, from importer to imported, or None if no chain exists. @@ -390,11 +414,17 @@ def find_shortest_chain( msg = f"Module {module} is not present in the graph." raise ValueError(msg) - chain = self._rustgraph.find_shortest_chain(importer, imported, as_packages) + chain = self._rustgraph.find_shortest_chain( + importer, imported, as_packages, exclude_shared_descendants + ) return tuple(chain) if chain else None def find_shortest_chains( - self, importer: str, imported: str, as_packages: bool = True + self, + importer: str, + imported: str, + as_packages: bool = True, + exclude_shared_descendants: bool = False, ) -> set[tuple[str, ...]]: """ Find the shortest import chains that exist between the importer and imported, and @@ -405,12 +435,24 @@ def find_shortest_chains( The default behavior is to treat the import and imported as packages, however, if as_packages is False, both the importer and imported will be treated as modules instead. + If exclude_shared_descendants is True (only applicable if as_packages is True), and one of + the modules is a package containing the other, the contained package is excluded from the + outer package, rather than a ValueError being raised. + Returns: A set of tuples of strings. Each tuple is ordered from importer to imported modules. """ - return self._rustgraph.find_shortest_chains(importer, imported, as_packages) + return self._rustgraph.find_shortest_chains( + importer, imported, as_packages, exclude_shared_descendants + ) - def chain_exists(self, importer: str, imported: str, as_packages: bool = False) -> bool: + def chain_exists( + self, + importer: str, + imported: str, + as_packages: bool = False, + exclude_shared_descendants: bool = False, + ) -> bool: """ Return whether any chain of imports exists between the two modules, in the direction of importer to imported. In other words, does the importer depend on the imported? @@ -420,8 +462,16 @@ def chain_exists(self, importer: str, imported: str, as_packages: bool = False) or as packages (including any descendants, if there are any). If treating them as subpackages, all descendants of the supplied modules will be checked too. - """ - return self._rustgraph.chain_exists(importer, imported, as_packages) + exclude_shared_descendants: + Only applies if as_packages is True. By default, modules with shared + descendants (i.e. one is a package that contains the other) raise a + ValueError. 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. + """ + return self._rustgraph.chain_exists( + importer, imported, as_packages, exclude_shared_descendants + ) # High level analysis # ------------------- diff --git a/tests/unit/application/graph/test_chains.py b/tests/unit/application/graph/test_chains.py index 63047a51..e1ba1756 100644 --- a/tests/unit/application/graph/test_chains.py +++ b/tests/unit/application/graph/test_chains.py @@ -227,6 +227,74 @@ def test_modules_with_shared_descendants_allowed_when_as_packages_false( assert result == {(importer, middle, imported)} + def test_exclude_shared_descendants_when_imported_is_inside_importer(self): + graph = ImportGraph() + for module in ("pkg", "pkg.inner", "pkg.inner.leaf", "pkg.other", "pkg.other.leaf"): + graph.add_module(module) + graph.add_import(importer="pkg.other.leaf", imported="pkg.inner.leaf") + graph.add_import(importer="pkg.inner.leaf", imported="pkg.inner") # Within the overlap. + + result = graph.find_shortest_chains( + importer="pkg", + imported="pkg.inner", + as_packages=True, + exclude_shared_descendants=True, + ) + + assert result == {("pkg.other.leaf", "pkg.inner.leaf")} + + def test_exclude_shared_descendants_when_importer_is_inside_imported(self): + graph = ImportGraph() + for module in ("pkg", "pkg.inner", "pkg.inner.leaf", "pkg.other"): + graph.add_module(module) + graph.add_import(importer="pkg.inner.leaf", imported="pkg.other") + graph.add_import(importer="pkg.other", imported="pkg.inner") # Wrong direction. + + result = graph.find_shortest_chains( + importer="pkg.inner", + imported="pkg", + as_packages=True, + exclude_shared_descendants=True, + ) + + assert result == {("pkg.inner.leaf", "pkg.other")} + + def test_exclude_shared_descendants_with_identical_modules_finds_nothing(self): + graph = ImportGraph() + graph.add_module("pkg") + graph.add_import(importer="pkg.a", imported="pkg.b") + + result = graph.find_shortest_chains( + importer="pkg", imported="pkg", as_packages=True, exclude_shared_descendants=True + ) + + assert result == set() + + def test_exclude_shared_descendants_has_no_effect_without_overlap(self): + graph = ImportGraph() + graph.add_module("green") + graph.add_module("blue") + graph.add_import(importer="green.one", imported="blue.two") + + result = graph.find_shortest_chains( + importer="green", imported="blue", exclude_shared_descendants=True + ) + + assert result == {("green.one", "blue.two")} + + def test_exclude_shared_descendants_has_no_effect_if_not_as_packages(self): + graph = ImportGraph() + graph.add_import(importer="pkg", imported="pkg.inner") + + result = graph.find_shortest_chains( + importer="pkg", + imported="pkg.inner", + as_packages=False, + exclude_shared_descendants=True, + ) + + assert result == {("pkg", "pkg.inner")} + @pytest.mark.parametrize("as_packages", (False, True)) def test_top_level_import(self, as_packages: bool): graph = ImportGraph() diff --git a/tests/unit/application/graph/test_direct_imports.py b/tests/unit/application/graph/test_direct_imports.py index ac65fabd..d0e2838f 100644 --- a/tests/unit/application/graph/test_direct_imports.py +++ b/tests/unit/application/graph/test_direct_imports.py @@ -203,6 +203,55 @@ def test_direct_import_exists(importer, imported, as_packages, expected_result): ) +class TestDirectImportExistsExcludeSharedDescendants: + @staticmethod + def _build_graph() -> ImportGraph: + graph = ImportGraph() + for module in ("pkg", "pkg.inner", "pkg.inner.leaf", "pkg.other"): + graph.add_module(module) + graph.add_import(importer="pkg.other", imported="pkg.inner.leaf") + graph.add_import(importer="pkg.inner", imported="pkg.inner.leaf") # Within the overlap. + return graph + + @pytest.mark.parametrize( + "importer, imported, expected_result", + ( + # Outer package importing the inner package: pkg.other -> pkg.inner.leaf. + ("pkg", "pkg.inner", True), + # Inner package importing the outer package: the only imports are in the other + # direction, or within the overlap. + ("pkg.inner", "pkg", False), + ), + ) + def test_overlapping_packages(self, importer: str, imported: str, expected_result: bool): + graph = self._build_graph() + + result = graph.direct_import_exists( + importer=importer, + imported=imported, + as_packages=True, + exclude_shared_descendants=True, + ) + + assert result is expected_result + + def test_raises_by_default(self): + graph = self._build_graph() + + with pytest.raises(ValueError, match=re.escape("Modules have shared descendants.")): + graph.direct_import_exists(importer="pkg", imported="pkg.inner", as_packages=True) + + def test_no_effect_if_not_as_packages(self): + graph = self._build_graph() + + assert graph.direct_import_exists( + importer="pkg.inner", + imported="pkg.inner.leaf", + as_packages=False, + exclude_shared_descendants=True, + ) + + class TestCountImports: @pytest.mark.parametrize( "imports, expected_count",