grimp 3.18__tar.gz → 3.20__tar.gz

grimp-3.20/AUTHORS.rst

@@ -0,0 +1,16 @@
+
+Authors
+=======
+
+* David Seddon - https://seddonym.me
+* Kevin Amado - https://github.com/kamadorueda
+* Matthew Gamble - https://github.com/mwgamble
+* NetworkX developers - The shortest path algorithm was adapted from the NetworkX library https://networkx.org/.
+* Peter Byfield - https://github.com/Peter554
+* Shane Smiskol - https://github.com/sshane
+* Andreas Rammhold - https://github.com/andir
+* Nicholas Bunn - https://github.com/NicholasBunn
+* Nathan McDougall - https://github.com/nathanjmcdougall
+* Oleksandr Zaiats - https://github.com/z4y4ts
+* Nikhil Dabas - https://github.com/ndabas
+* Pierre-Yves Le Borgne - https://github.com/pylaterreur

grimp-3.20/LICENSE

@@ -0,0 +1,21 @@
+BSD 2-Clause License
+
+Copyright (c) 2018, David Seddon
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
+conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+  disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+  disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

{grimp-3.18 → grimp-3.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grimp
-Version: 3.18
+Version: 3.20
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: BSD License
@@ -8,7 +8,6 @@ Classifier: Operating System :: Unix
 Classifier: Operating System :: POSIX
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -22,7 +21,7 @@ License-File: AUTHORS.rst
 Summary: Builds a queryable graph of the imports within one or more Python packages.
 Author-email: David Seddon <david@seddonym.me>
 License: BSD 2-Clause License
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/x-rst; charset=UTF-8
 Project-URL: Documentation, https://grimp.readthedocs.io/
 Project-URL: Source-code, https://github.com/python-grimp/grimp/

{grimp-3.18 → grimp-3.20}/pyproject.toml

@@ -8,13 +8,13 @@ module-name = "grimp._rustgrimp"
 
 [project]
 name = "grimp"
-version = "3.18"
+version = "3.20"
 license = {text = "BSD 2-Clause License"}
 description = "Builds a queryable graph of the imports within one or more Python packages."
 authors = [
     {name = "David Seddon", email = "david@seddonym.me"},
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = []
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -24,7 +24,6 @@ classifiers = [
     "Operating System :: POSIX",
     "Operating System :: Microsoft :: Windows",
     "Programming Language :: Python",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -60,6 +59,7 @@ dev = [
     "requests==2.32.3",
     "sqlalchemy==2.0.35",
     "google-cloud-audit-log==0.3.0",
+    "pyupgrade>=3.21.2",
 ]
 docs = [
     "sphinx>=7.4.7",

{grimp-3.18 → grimp-3.20}/rust/src/graph/cycle_breakers.rs

@@ -1,6 +1,6 @@
-use crate::errors::GrimpResult;
+use crate::errors::{GrimpError, GrimpResult};
 
-use crate::graph::{Graph, ModuleToken};
+use crate::graph::{Graph, ModuleIterator, ModuleToken};
 use rustc_hash::{FxHashMap, FxHashSet};
 use slotmap::SecondaryMap;
 use std::cmp::Ordering;
@@ -9,17 +9,45 @@ impl Graph {
     pub fn nominate_cycle_breakers(
         &self,
         package: ModuleToken,
+        additional_packages: &[ModuleToken],
     ) -> GrimpResult<FxHashSet<(ModuleToken, ModuleToken)>> {
-        // Get children of this package.
-        let children = match self.module_children.get(package) {
-            Some(children) => children,
-            None => return Ok(FxHashSet::default()),
-        };
-        if children.len() < 2 {
+        if additional_packages.is_empty() {
+            // A single package was passed: the nodes of the graph are its children.
+            // Children of a single package can never overlap, so no need to check.
+            let children = match self.module_children.get(package) {
+                Some(children) => children.clone(),
+                None => return Ok(FxHashSet::default()),
+            };
+            self.nominate_cycle_breakers_for_nodes(&children)
+        } else {
+            // Multiple packages were passed: the packages themselves are the nodes.
+            let mut nodes: FxHashSet<ModuleToken> = FxHashSet::default();
+            nodes.insert(package);
+            nodes.extend(additional_packages.iter().copied());
+
+            // The packages must not overlap: if one is a descendant of another, the edges
+            // between them (as packages) would be ill-defined.
+            for node in &nodes {
+                for descendant in self.get_module_descendants(*node).tokens() {
+                    if nodes.contains(&descendant) {
+                        return Err(GrimpError::SharedDescendants);
+                    }
+                }
+            }
+
+            self.nominate_cycle_breakers_for_nodes(&nodes)
+        }
+    }
+
+    fn nominate_cycle_breakers_for_nodes(
+        &self,
+        nodes: &FxHashSet<ModuleToken>,
+    ) -> GrimpResult<FxHashSet<(ModuleToken, ModuleToken)>> {
+        if nodes.len() < 2 {
             return Ok(FxHashSet::default());
         }
         let (orig_imports, orig_reverse_imports, edge_weights) =
-            self.build_graph_maps_of_children(children);
+            self.build_graph_maps_of_nodes(nodes);
 
         // Make a copy of the graph. We'll iteratively remove nodes from this.
         let mut working_imports = orig_imports.clone();
@@ -166,9 +194,9 @@ impl Graph {
     // with empty sets if they have no imports to / from.
     // They are denormalized into two maps for fast lookups.
     #[allow(clippy::type_complexity)]
-    fn build_graph_maps_of_children(
+    fn build_graph_maps_of_nodes(
         &self,
-        children: &FxHashSet<ModuleToken>,
+        nodes: &FxHashSet<ModuleToken>,
     ) -> (
         SecondaryMap<ModuleToken, FxHashSet<ModuleToken>>, // Imports
         SecondaryMap<ModuleToken, FxHashSet<ModuleToken>>, // Reverse imports
@@ -180,25 +208,25 @@ impl Graph {
             SecondaryMap::default();
         let mut weights = FxHashMap::default();
 
-        for child in children {
-            orig_imports.insert(*child, FxHashSet::default());
-            orig_reverse_imports.insert(*child, FxHashSet::default());
+        for node in nodes {
+            orig_imports.insert(*node, FxHashSet::default());
+            orig_reverse_imports.insert(*node, FxHashSet::default());
         }
-        // Get number of imports between each child.
+        // Get number of imports between each node.
         // Add as edges.
-        for child_a in children {
-            for child_b in children.iter().filter(|child| *child != child_a) {
-                // Get number of imports from child_a to child_b (as package).
+        for node_a in nodes {
+            for node_b in nodes.iter().filter(|node| *node != node_a) {
+                // Get number of imports from node_a to node_b (as package).
                 let num_imports_from_a_to_b = self
-                    .find_direct_imports_between(*child_a, *child_b, true)
+                    .find_direct_imports_between(*node_a, *node_b, true)
                     .unwrap()
                     .len();
 
                 if num_imports_from_a_to_b > 0 {
                     // a depends on b - add it as an edge in our temporary graph.
-                    orig_imports[*child_a].insert(*child_b);
-                    orig_reverse_imports[*child_b].insert(*child_a);
-                    weights.insert((*child_a, *child_b), num_imports_from_a_to_b);
+                    orig_imports[*node_a].insert(*node_b);
+                    orig_reverse_imports[*node_b].insert(*node_a);
+                    weights.insert((*node_a, *node_b), num_imports_from_a_to_b);
                 }
             }
         }

grimp-3.20/rust/src/graph/direct_import_queries.rs

@@ -0,0 +1,328 @@
+use crate::errors::{GrimpError, GrimpResult};
+use crate::graph::{
+    EMPTY_IMPORT_DETAILS, EMPTY_MODULE_TOKENS, ExtendWithDescendants, Graph, ModuleIterator,
+    ModuleToken, PyImportDetails,
+};
+use crate::module_expressions::ModuleExpression;
+use rustc_hash::FxHashSet;
+
+impl Graph {
+    pub fn count_imports(&self) -> usize {
+        self.imports.values().map(|imports| imports.len()).sum()
+    }
+
+    pub fn direct_import_exists(
+        &self,
+        importer: ModuleToken,
+        imported: ModuleToken,
+        as_packages: 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 direct_imports = importers
+            .iter()
+            .flat_map(|importer_module| self.imports.get(*importer_module).unwrap().iter().cloned())
+            .collect::<FxHashSet<ModuleToken>>();
+
+        Ok(!(&direct_imports & &importeds).is_empty())
+    }
+
+    pub fn find_direct_imports_between(
+        &self,
+        importer: ModuleToken,
+        imported: ModuleToken,
+        as_packages: bool,
+    ) -> 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);
+            }
+        }
+
+        for importer_module in importers.iter() {
+            if let Some(all_imports_imported_by_this_one) = self.imports.get(*importer_module) {
+                let imports_of_supplied_package: FxHashSet<_> = all_imports_imported_by_this_one
+                    .iter()
+                    .filter(|candidate| importeds.contains(*candidate))
+                    .map(|imported_module| (*importer_module, *imported_module))
+                    .collect();
+                all_imports.extend(imports_of_supplied_package);
+            }
+        }
+
+        Ok(all_imports)
+    }
+
+    /// Find the modules directly imported by the module.
+    ///
+    /// If `as_package` is true, the module is treated as a package: the result is the modules
+    /// directly imported by it or any of its descendants, excluding modules within the package.
+    pub fn modules_directly_imported_by(
+        &self,
+        importer: ModuleToken,
+        as_package: bool,
+    ) -> FxHashSet<ModuleToken> {
+        let mut importers: FxHashSet<_> = importer.into();
+        if as_package {
+            importers.extend_with_descendants(self);
+        }
+
+        let mut imported_modules: FxHashSet<_> = importers
+            .iter()
+            .flat_map(|importer| self.imports.get(*importer).unwrap_or(&EMPTY_MODULE_TOKENS))
+            .cloned()
+            .collect();
+        if as_package {
+            imported_modules.retain(|imported| !importers.contains(imported));
+        }
+        imported_modules
+    }
+
+    /// Find the modules that directly import the module.
+    ///
+    /// If `as_package` is true, the module is treated as a package: the result is the modules
+    /// that directly import it or any of its descendants, excluding modules within the package.
+    pub fn modules_that_directly_import(
+        &self,
+        imported: ModuleToken,
+        as_package: bool,
+    ) -> FxHashSet<ModuleToken> {
+        let mut importeds: FxHashSet<_> = imported.into();
+        if as_package {
+            importeds.extend_with_descendants(self);
+        }
+
+        let mut importers: FxHashSet<_> = importeds
+            .iter()
+            .flat_map(|imported| {
+                self.reverse_imports
+                    .get(*imported)
+                    .unwrap_or(&EMPTY_MODULE_TOKENS)
+            })
+            .cloned()
+            .collect();
+        if as_package {
+            importers.retain(|importer| !importeds.contains(importer));
+        }
+        importers
+    }
+
+    pub fn get_import_details(
+        &self,
+        importer: ModuleToken,
+        imported: ModuleToken,
+    ) -> &FxHashSet<PyImportDetails> {
+        match self.import_details.get(&(importer, imported)) {
+            Some(import_details) => import_details,
+            None => &EMPTY_IMPORT_DETAILS,
+        }
+    }
+
+    pub fn find_matching_direct_imports(
+        &self,
+        importer_expression: &ModuleExpression,
+        imported_expression: &ModuleExpression,
+    ) -> FxHashSet<(ModuleToken, ModuleToken)> {
+        let importers: FxHashSet<ModuleToken> = self
+            .find_matching_modules(importer_expression)
+            .tokens()
+            .collect();
+        let importeds: FxHashSet<ModuleToken> = self
+            .find_matching_modules(imported_expression)
+            .tokens()
+            .collect();
+
+        importers
+            .iter()
+            .flat_map(|importer| {
+                self.modules_directly_imported_by(*importer, false)
+                    .into_iter()
+                    .filter(|imported| importeds.contains(imported))
+                    .map(move |imported| (*importer, imported))
+            })
+            .collect()
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn test_modules_directly_imported_by() {
+        let mut graph = Graph::default();
+
+        let animals = graph.get_or_add_module("pkg.animals").token;
+        let dog = graph.get_or_add_module("pkg.animals.dog").token;
+        let cat = graph.get_or_add_module("pkg.animals.cat").token;
+        let food = graph.get_or_add_module("pkg.food").token;
+        let chicken = graph.get_or_add_module("pkg.food.chicken").token;
+        let tesco = graph.get_or_add_module("pkg.shops.tesco").token;
+
+        graph.add_import(dog, chicken);
+        graph.add_import(cat, food);
+        // An import within the package.
+        graph.add_import(dog, cat);
+        // An import of the package, not by it.
+        graph.add_import(tesco, animals);
+
+        // Without as_package, only the module itself is looked at.
+        assert_eq!(
+            graph.modules_directly_imported_by(animals, false),
+            FxHashSet::default()
+        );
+        assert_eq!(
+            graph.modules_directly_imported_by(dog, false),
+            FxHashSet::from_iter([chicken, cat])
+        );
+        // With as_package, descendants are looked at too, but modules within the package
+        // are excluded.
+        assert_eq!(
+            graph.modules_directly_imported_by(animals, true),
+            FxHashSet::from_iter([chicken, food])
+        );
+    }
+
+    #[test]
+    fn test_modules_that_directly_import() {
+        let mut graph = Graph::default();
+
+        let animals = graph.get_or_add_module("pkg.animals").token;
+        let dog = graph.get_or_add_module("pkg.animals.dog").token;
+        let cat = graph.get_or_add_module("pkg.animals.cat").token;
+        let chicken = graph.get_or_add_module("pkg.food.chicken").token;
+        let shops = graph.get_or_add_module("pkg.shops").token;
+        let tesco = graph.get_or_add_module("pkg.shops.tesco").token;
+
+        graph.add_import(tesco, animals);
+        graph.add_import(shops, cat);
+        // An import within the package.
+        graph.add_import(dog, cat);
+        // An import by the package, not of it.
+        graph.add_import(dog, chicken);
+
+        // Without as_package, only the module itself is looked at.
+        assert_eq!(
+            graph.modules_that_directly_import(animals, false),
+            FxHashSet::from_iter([tesco])
+        );
+        assert_eq!(
+            graph.modules_that_directly_import(cat, false),
+            FxHashSet::from_iter([shops, dog])
+        );
+        // With as_package, descendants are looked at too, but modules within the package
+        // are excluded.
+        assert_eq!(
+            graph.modules_that_directly_import(animals, true),
+            FxHashSet::from_iter([tesco, shops])
+        );
+    }
+
+    #[test]
+    fn test_find_matching_direct_imports() {
+        let mut graph = Graph::default();
+
+        let _ = graph.get_or_add_module("pkg.animals").token;
+        let dog = graph.get_or_add_module("pkg.animals.dog").token;
+        let cat = graph.get_or_add_module("pkg.animals.cat").token;
+        let _ = graph.get_or_add_module("pkg.food").token;
+        let chicken = graph.get_or_add_module("pkg.food.chicken").token;
+        let fish = graph.get_or_add_module("pkg.food.fish").token;
+        let _ = graph.get_or_add_module("pkg.colors").token;
+        let golden = graph.get_or_add_module("pkg.colors.golden").token;
+        let ginger = graph.get_or_add_module("pkg.colors.ginger").token;
+        let _ = graph.get_or_add_module("pkg.shops").token;
+        let tesco = graph.get_or_add_module("pkg.shops.tesco").token;
+        let coop = graph.get_or_add_module("pkg.shops.coop").token;
+
+        // Should match
+        graph.add_import(dog, chicken);
+        graph.add_import(cat, fish);
+        // Should not match: Imported does not match
+        graph.add_import(dog, golden);
+        graph.add_import(cat, ginger);
+        // Should not match: Importer does not match
+        graph.add_import(tesco, chicken);
+        graph.add_import(coop, fish);
+
+        let importer_expression = "pkg.animals.*".parse().unwrap();
+        let imported_expression = "pkg.food.*".parse().unwrap();
+        let matching_imports =
+            graph.find_matching_direct_imports(&importer_expression, &imported_expression);
+
+        assert_eq!(
+            matching_imports,
+            FxHashSet::from_iter([(dog, chicken), (cat, fish)])
+        );
+    }
+
+    #[test]
+    fn test_find_matching_direct_imports_with_and_without_wildcards() {
+        let mut graph = Graph::default();
+
+        let dog = graph.get_or_add_module("pkg.animals.dog").token;
+        let cat = graph.get_or_add_module("pkg.animals.cat").token;
+        let chicken = graph.get_or_add_module("pkg.food.chicken").token;
+        let fish = graph.get_or_add_module("pkg.food.fish").token;
+        let golden = graph.get_or_add_module("pkg.colors.golden").token;
+        let tesco = graph.get_or_add_module("pkg.shops.tesco").token;
+        graph.get_or_add_module("pkg.shops.coop");
+
+        graph.add_import(dog, chicken);
+        graph.add_import(dog, golden);
+        graph.add_import(cat, fish);
+        graph.add_import(tesco, chicken);
+
+        let find = |importer_expression: &str, imported_expression: &str| {
+            graph.find_matching_direct_imports(
+                &importer_expression.parse().unwrap(),
+                &imported_expression.parse().unwrap(),
+            )
+        };
+
+        // Neither side has wildcards.
+        assert_eq!(
+            find("pkg.animals.dog", "pkg.food.chicken"),
+            FxHashSet::from_iter([(dog, chicken)])
+        );
+        // Only the importer is a single module.
+        assert_eq!(
+            find("pkg.animals.dog", "pkg.*.*"),
+            FxHashSet::from_iter([(dog, chicken), (dog, golden)])
+        );
+        // Only the imported is a single module.
+        assert_eq!(
+            find("pkg.*.*", "pkg.food.chicken"),
+            FxHashSet::from_iter([(dog, chicken), (tesco, chicken)])
+        );
+        // Both sides have wildcards.
+        assert_eq!(
+            find("pkg.shops.*", "pkg.food.*"),
+            FxHashSet::from_iter([(tesco, chicken)])
+        );
+        // A module with no imports.
+        assert!(find("pkg.shops.coop", "pkg.*.*").is_empty());
+        // A module that has no importers.
+        assert!(find("pkg.*.*", "pkg.shops.coop").is_empty());
+        // Modules that aren't in the graph.
+        assert!(find("pkg.animals.missing", "pkg.*.*").is_empty());
+        assert!(find("pkg.*.*", "pkg.food.missing").is_empty());
+        assert!(find("pkg.animals.missing", "pkg.food.missing").is_empty());
+        // Wildcards that match nothing.
+        assert!(find("pkg.nothing.*", "pkg.*.*").is_empty());
+    }
+}

{grimp-3.18 → grimp-3.20}/rust/src/graph/graph_manipulation.rs

@@ -91,10 +91,10 @@ impl Graph {
         self.module_children.remove(module);
 
         // Update imports.
-        for imported in self.modules_directly_imported_by(module).clone() {
+        for imported in self.modules_directly_imported_by(module, false) {
             self.remove_import(module, imported);
         }
-        for importer in self.modules_that_directly_import(module).clone() {
+        for importer in self.modules_that_directly_import(module, false) {
             self.remove_import(importer, module);
         }
         self.imports.remove(module);
@@ -164,19 +164,11 @@ impl Graph {
 
         let modules_imported_by_descendants: FxHashSet<_> = descendants
             .iter()
-            .flat_map(|descendant| {
-                self.modules_directly_imported_by(*descendant)
-                    .iter()
-                    .cloned()
-            })
+            .flat_map(|descendant| self.modules_directly_imported_by(*descendant, false))
             .collect();
         let modules_that_import_descendants: FxHashSet<_> = descendants
             .iter()
-            .flat_map(|descendant| {
-                self.modules_that_directly_import(*descendant)
-                    .iter()
-                    .cloned()
-            })
+            .flat_map(|descendant| self.modules_that_directly_import(*descendant, false))
             .collect();
 
         // Add descendants and imports to parent module.

{grimp-3.18 → grimp-3.20}/rust/src/graph/hierarchy_queries.rs

@@ -54,12 +54,19 @@ impl Graph {
         &self,
         expression: &ModuleExpression,
     ) -> impl ModuleIterator<'_> + use<'_> {
-        let interner = MODULE_NAMES.read().unwrap();
-        let modules: FxHashSet<_> = self
-            .modules
-            .values()
-            .filter(|m| expression.is_match(interner.resolve(m.interned_name).unwrap()))
-            .collect();
+        let modules: FxHashSet<_> = if expression.as_ref().contains('*') {
+            let interner = MODULE_NAMES.read().unwrap();
+            self.modules
+                .values()
+                .filter(|m| expression.is_match(interner.resolve(m.interned_name).unwrap()))
+                .collect()
+        } else {
+            // Without wildcards the expression can only match the module with that name,
+            // so there's no need to check every module.
+            self.get_module_by_name(expression.as_ref())
+                .into_iter()
+                .collect()
+        };
         modules.into_iter()
     }
 }
@@ -80,6 +87,8 @@ mod tests {
 
     #[parameterized(case = {
         FindMatchingModulesTestCase::new("foo", ["foo"]),
+        FindMatchingModulesTestCase::new("foo.bar.baz", ["foo.bar.baz"]),
+        FindMatchingModulesTestCase::new("foo.missing", Vec::<&str>::new()),
         FindMatchingModulesTestCase::new("foo.*", ["foo.bar"]),
         FindMatchingModulesTestCase::new("foo.**", ["foo.bar", "foo.bar.baz"]),
     })]

{grimp-3.18 → grimp-3.20}/rust/src/graph/mod.rs

@@ -198,6 +198,33 @@ impl GraphWrapper {
 
         PyTuple::new(py, python_dependencies)
     }
+
+    fn convert_cycle_breakers_to_python<'py>(
+        &self,
+        py: Python<'py>,
+        cycle_breakers: FxHashSet<(ModuleToken, ModuleToken)>,
+    ) -> PyResult<Bound<'py, PySet>> {
+        PySet::new(
+            py,
+            cycle_breakers
+                .into_iter()
+                .map(|(importer, imported)| {
+                    let importer = self._graph.get_module(importer).unwrap();
+                    let imported = self._graph.get_module(imported).unwrap();
+                    Import::new(importer.name(), imported.name())
+                })
+                .map(|import| {
+                    PyTuple::new(
+                        py,
+                        [
+                            import.importer.into_py_any(py).unwrap(),
+                            import.imported.into_py_any(py).unwrap(),
+                        ],
+                    )
+                    .unwrap()
+                }),
+        )
+    }
 }
 
 /// Wrapper around the Graph struct that integrates with Python.
@@ -367,11 +394,16 @@ impl GraphWrapper {
             .direct_import_exists(importer, imported, as_packages)?)
     }
 
-    pub fn find_modules_directly_imported_by(&self, module: &str) -> PyResult<HashSet<String>> {
+    #[pyo3(signature = (module, as_package=false))]
+    pub fn find_modules_directly_imported_by(
+        &self,
+        module: &str,
+        as_package: bool,
+    ) -> PyResult<HashSet<String>> {
         let module = self.get_visible_module_by_name(module)?.token();
         Ok(self
             ._graph
-            .modules_directly_imported_by(module)
+            .modules_directly_imported_by(module, as_package)
             .iter()
             .into_module_iterator(&self._graph)
             .visible()
@@ -379,11 +411,16 @@ impl GraphWrapper {
             .collect())
     }
 
-    pub fn find_modules_that_directly_import(&self, module: &str) -> PyResult<HashSet<String>> {
+    #[pyo3(signature = (module, as_package=false))]
+    pub fn find_modules_that_directly_import(
+        &self,
+        module: &str,
+        as_package: bool,
+    ) -> PyResult<HashSet<String>> {
         let module = self.get_visible_module_by_name(module)?.token();
         Ok(self
             ._graph
-            .modules_that_directly_import(module)
+            .modules_that_directly_import(module, as_package)
             .iter()
             .into_module_iterator(&self._graph)
             .visible()
@@ -642,29 +679,17 @@ impl GraphWrapper {
         &self,
         py: Python<'py>,
         package: &str,
+        additional_packages: Vec<String>,
     ) -> PyResult<Bound<'py, PySet>> {
         let package = self.get_visible_module_by_name(package)?.token();
-        let cycle_breakers = self._graph.nominate_cycle_breakers(package)?;
-        PySet::new(
-            py,
-            cycle_breakers
-                .into_iter()
-                .map(|(importer, imported)| {
-                    let importer = self._graph.get_module(importer).unwrap();
-                    let imported = self._graph.get_module(imported).unwrap();
-                    Import::new(importer.name(), imported.name())
-                })
-                .map(|import| {
-                    PyTuple::new(
-                        py,
-                        [
-                            import.importer.into_py_any(py).unwrap(),
-                            import.imported.into_py_any(py).unwrap(),
-                        ],
-                    )
-                    .unwrap()
-                }),
-        )
+        let additional_packages = additional_packages
+            .iter()
+            .map(|package| Ok(self.get_visible_module_by_name(package)?.token()))
+            .collect::<PyResult<Vec<_>>>()?;
+        let cycle_breakers = self
+            ._graph
+            .nominate_cycle_breakers(package, &additional_packages)?;
+        self.convert_cycle_breakers_to_python(py, cycle_breakers)
     }
 
     #[pyo3(name = "clone")]

{grimp-3.18 → grimp-3.20}/src/grimp/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "3.18"
+__version__ = "3.20"
 
 from .application.graph import DetailedImport, Import, ImportGraph
 from .domain.analysis import PackageDependency, Route

{grimp-3.18 → grimp-3.20}/src/grimp/application/graph.py

@@ -223,27 +223,41 @@ class ImportGraph:
             importer=importer, imported=imported, as_packages=as_packages
         )
 
-    def find_modules_directly_imported_by(self, module: str) -> set[str]:
+    def find_modules_directly_imported_by(self, module: str, as_package: bool = False) -> set[str]:
         """
         Find all modules that are directly imported by the supplied module.
 
+        Args:
+            module:     The name of the importing module.
+            as_package: Whether or not to treat the supplied module as an individual module,
+                        or as a package (i.e. including any descendants, if there are any). If
+                        treating it as a package, the result will include modules *external* to
+                        the package, and won't include modules within it.
+
         If the module is not present in the graph, grimp.exceptions.ModuleNotPresent will be raised.
         """
         if not self._rustgraph.contains_module(module):
             msg = f'"{module}" not present in the graph.'
             raise ModuleNotPresent(msg)
-        return self._rustgraph.find_modules_directly_imported_by(module)
+        return self._rustgraph.find_modules_directly_imported_by(module, as_package)
 
-    def find_modules_that_directly_import(self, module: str) -> set[str]:
+    def find_modules_that_directly_import(self, module: str, as_package: bool = False) -> set[str]:
         """
         Find all modules that directly import the supplied module.
 
+        Args:
+            module:     The name of the imported module.
+            as_package: Whether or not to treat the supplied module as an individual module,
+                        or as a package (i.e. including any descendants, if there are any). If
+                        treating it as a package, the result will include modules *external* to
+                        the package, and won't include modules within it.
+
         If the module is not present in the graph, grimp.exceptions.ModuleNotPresent will be raised.
         """
         if not self._rustgraph.contains_module(module):
             msg = f'"{module}" not present in the graph.'
             raise ModuleNotPresent(msg)
-        return self._rustgraph.find_modules_that_directly_import(module)
+        return self._rustgraph.find_modules_that_directly_import(module, as_package)
 
     def get_import_details(self, *, importer: str, imported: str) -> list[DetailedImport]:
         """
@@ -476,14 +490,18 @@ class ImportGraph:
 
         return _dependencies_from_tuple(result)
 
-    def nominate_cycle_breakers(self, package: str) -> set[ImportTuple]:
+    def nominate_cycle_breakers(self, package: str, *additional_packages: str) -> set[ImportTuple]:
         """
-        Identify a set of imports that, if removed, would make the package locally acyclic.
+        Identify a set of imports that, if removed, would make the supplied packages acyclic.
+
+        For more information see the docs in usage.rst.
         """
-        if not self._rustgraph.contains_module(package):
-            msg = f'"{package}" not present in the graph.'
-            raise ModuleNotPresent(msg)
-        return self._rustgraph.nominate_cycle_breakers(package)
+        for package_ in (package, *additional_packages):
+            if not self._rustgraph.contains_module(package_):
+                msg = f'"{package_}" not present in the graph.'
+                raise ModuleNotPresent(msg)
+
+        return self._rustgraph.nominate_cycle_breakers(package, additional_packages)
 
     # Dunder methods
     # --------------

{grimp-3.18 → grimp-3.20}/src/grimp/application/ports/timing.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import abc
 from types import TracebackType
+from typing import Self
 
 
 class Timer(abc.ABC):
@@ -22,7 +23,7 @@ class Timer(abc.ABC):
         # We use a stack so context managers can be nested.
         self._start_stack: list[float] = []
 
-    def __enter__(self) -> Timer:
+    def __enter__(self) -> Self:
         self._start_stack.append(self.get_current_time())
         return self
 

grimp-3.18/rust/src/graph/direct_import_queries.rs

@@ -1,158 +0,0 @@
-use crate::errors::{GrimpError, GrimpResult};
-use crate::graph::{
-    EMPTY_IMPORT_DETAILS, EMPTY_MODULE_TOKENS, ExtendWithDescendants, Graph, MODULE_NAMES,
-    ModuleToken, PyImportDetails,
-};
-use crate::module_expressions::ModuleExpression;
-use rustc_hash::FxHashSet;
-
-impl Graph {
-    pub fn count_imports(&self) -> usize {
-        self.imports.values().map(|imports| imports.len()).sum()
-    }
-
-    pub fn direct_import_exists(
-        &self,
-        importer: ModuleToken,
-        imported: ModuleToken,
-        as_packages: 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 direct_imports = importers
-            .iter()
-            .flat_map(|importer_module| self.imports.get(*importer_module).unwrap().iter().cloned())
-            .collect::<FxHashSet<ModuleToken>>();
-
-        Ok(!(&direct_imports & &importeds).is_empty())
-    }
-
-    pub fn find_direct_imports_between(
-        &self,
-        importer: ModuleToken,
-        imported: ModuleToken,
-        as_packages: bool,
-    ) -> 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);
-            }
-        }
-
-        for importer_module in importers.iter() {
-            if let Some(all_imports_imported_by_this_one) = self.imports.get(*importer_module) {
-                let imports_of_supplied_package: FxHashSet<_> = all_imports_imported_by_this_one
-                    .iter()
-                    .filter(|candidate| importeds.contains(*candidate))
-                    .map(|imported_module| (*importer_module, *imported_module))
-                    .collect();
-                all_imports.extend(imports_of_supplied_package);
-            }
-        }
-
-        Ok(all_imports)
-    }
-
-    pub fn modules_directly_imported_by(&self, importer: ModuleToken) -> &FxHashSet<ModuleToken> {
-        self.imports.get(importer).unwrap_or(&EMPTY_MODULE_TOKENS)
-    }
-
-    pub fn modules_that_directly_import(&self, imported: ModuleToken) -> &FxHashSet<ModuleToken> {
-        self.reverse_imports
-            .get(imported)
-            .unwrap_or(&EMPTY_MODULE_TOKENS)
-    }
-
-    pub fn get_import_details(
-        &self,
-        importer: ModuleToken,
-        imported: ModuleToken,
-    ) -> &FxHashSet<PyImportDetails> {
-        match self.import_details.get(&(importer, imported)) {
-            Some(import_details) => import_details,
-            None => &EMPTY_IMPORT_DETAILS,
-        }
-    }
-
-    pub fn find_matching_direct_imports(
-        &self,
-        importer_expression: &ModuleExpression,
-        imported_expression: &ModuleExpression,
-    ) -> FxHashSet<(ModuleToken, ModuleToken)> {
-        let interner = MODULE_NAMES.read().unwrap();
-        self.imports
-            .iter()
-            .flat_map(|(importer, imports)| {
-                imports
-                    .iter()
-                    .cloned()
-                    .map(move |imported| (importer, imported))
-            })
-            .filter(|(importer, imported)| {
-                let importer = self.get_module(*importer).unwrap();
-                let importer_name = interner.resolve(importer.interned_name).unwrap();
-                let imported = self.get_module(*imported).unwrap();
-                let imported_name = interner.resolve(imported.interned_name).unwrap();
-                importer_expression.is_match(importer_name)
-                    && imported_expression.is_match(imported_name)
-            })
-            .collect()
-    }
-}
-
-#[cfg(test)]
-mod test {
-    use super::*;
-
-    #[test]
-    fn test_find_matching_direct_imports() {
-        let mut graph = Graph::default();
-
-        let _ = graph.get_or_add_module("pkg.animals").token;
-        let dog = graph.get_or_add_module("pkg.animals.dog").token;
-        let cat = graph.get_or_add_module("pkg.animals.cat").token;
-        let _ = graph.get_or_add_module("pkg.food").token;
-        let chicken = graph.get_or_add_module("pkg.food.chicken").token;
-        let fish = graph.get_or_add_module("pkg.food.fish").token;
-        let _ = graph.get_or_add_module("pkg.colors").token;
-        let golden = graph.get_or_add_module("pkg.colors.golden").token;
-        let ginger = graph.get_or_add_module("pkg.colors.ginger").token;
-        let _ = graph.get_or_add_module("pkg.shops").token;
-        let tesco = graph.get_or_add_module("pkg.shops.tesco").token;
-        let coop = graph.get_or_add_module("pkg.shops.coop").token;
-
-        // Should match
-        graph.add_import(dog, chicken);
-        graph.add_import(cat, fish);
-        // Should not match: Imported does not match
-        graph.add_import(dog, golden);
-        graph.add_import(cat, ginger);
-        // Should not match: Importer does not match
-        graph.add_import(tesco, chicken);
-        graph.add_import(coop, fish);
-
-        let importer_expression = "pkg.animals.*".parse().unwrap();
-        let imported_expression = "pkg.food.*".parse().unwrap();
-        let matching_imports =
-            graph.find_matching_direct_imports(&importer_expression, &imported_expression);
-
-        assert_eq!(
-            matching_imports,
-            FxHashSet::from_iter([(dog, chicken), (cat, fish)])
-        );
-    }
-}