grimp 3.12__tar.gz → 3.13__tar.gz

{grimp-3.12 → grimp-3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grimp
-Version: 3.12
+Version: 3.13
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: BSD License
@@ -26,7 +26,7 @@ License: BSD 2-Clause License
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst; charset=UTF-8
 Project-URL: Documentation, https://grimp.readthedocs.io/
-Project-URL: Source-code, https://github.com/seddonym/grimp/
+Project-URL: Source-code, https://github.com/python-grimp/grimp/
 
 =====
 Grimp
@@ -39,13 +39,19 @@ Grimp
     :alt: Python versions
     :target: https://pypi.org/project/grimp/
 
-.. image:: https://github.com/seddonym/grimp/workflows/CI/badge.svg?branch=main
-     :target: https://github.com/seddonym/grimp/actions?workflow=CI
+.. image:: https://github.com/python-grimp/grimp/actions/workflows/main.yml/badge.svg
+     :target: https://github.com/python-grimp/grimp/actions?workflow=CI
      :alt: CI Status
 
-Builds a queryable graph of the imports within one or more Python packages.
+.. image:: https://img.shields.io/endpoint?url=https://codspeed.io/badge.json
+     :target: https://codspeed.io/python-grimp/grimp?utm_source=badge
+     :alt: Codspeed
+
+.. image:: https://img.shields.io/badge/License-BSD_2--Clause-orange.svg
+     :target: https://opensource.org/licenses/BSD-2-Clause
+     :alt: BSD license
 
-* Free software: BSD license
+Builds a queryable graph of the imports within one or more Python packages.
 
 Quick start
 -----------

{grimp-3.12 → grimp-3.13}/README.rst

@@ -9,13 +9,19 @@ Grimp
     :alt: Python versions
     :target: https://pypi.org/project/grimp/
 
-.. image:: https://github.com/seddonym/grimp/workflows/CI/badge.svg?branch=main
-     :target: https://github.com/seddonym/grimp/actions?workflow=CI
+.. image:: https://github.com/python-grimp/grimp/actions/workflows/main.yml/badge.svg
+     :target: https://github.com/python-grimp/grimp/actions?workflow=CI
      :alt: CI Status
 
-Builds a queryable graph of the imports within one or more Python packages.
+.. image:: https://img.shields.io/endpoint?url=https://codspeed.io/badge.json
+     :target: https://codspeed.io/python-grimp/grimp?utm_source=badge
+     :alt: Codspeed
+
+.. image:: https://img.shields.io/badge/License-BSD_2--Clause-orange.svg
+     :target: https://opensource.org/licenses/BSD-2-Clause
+     :alt: BSD license
 
-* Free software: BSD license
+Builds a queryable graph of the imports within one or more Python packages.
 
 Quick start
 -----------

{grimp-3.12 → grimp-3.13}/pyproject.toml

@@ -8,7 +8,7 @@ module-name = "grimp._rustgrimp"
 
 [project]
 name = "grimp"
-version = "3.12"
+version = "3.13"
 license = {text = "BSD 2-Clause License"}
 description = "Builds a queryable graph of the imports within one or more Python packages."
 authors = [
@@ -40,7 +40,7 @@ readme = "README.rst"
 
 [project.urls]
 Documentation = "https://grimp.readthedocs.io/"
-Source-code = "https://github.com/seddonym/grimp/"
+Source-code = "https://github.com/python-grimp/grimp/"
 
 [dependency-groups]
 dev = [
@@ -67,7 +67,7 @@ docs = [
     "sphinx-rtd-theme>=3.0.2",
 ]
 benchmark_ci = [
-    "pytest-codspeed>=3.2.0",
+    "pytest-codspeed>=4.2.0",
 ]
 
 [tool.setuptools]

grimp-3.13/rust/src/graph/cycle_breakers.rs

@@ -0,0 +1,249 @@
+use crate::errors::GrimpResult;
+
+use crate::graph::{Graph, ModuleToken};
+use rustc_hash::{FxHashMap, FxHashSet};
+use slotmap::SecondaryMap;
+use std::cmp::Ordering;
+
+impl Graph {
+    pub fn nominate_cycle_breakers(
+        &self,
+        package: 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 {
+            return Ok(FxHashSet::default());
+        }
+        let (orig_imports, orig_reverse_imports, edge_weights) =
+            self.build_graph_maps_of_children(children);
+
+        // Make a copy of the graph. We'll iteratively remove nodes from this.
+        let mut working_imports = orig_imports.clone();
+        let mut working_reverse_imports = orig_reverse_imports.clone();
+
+        // Iteratively extract sources into a vec.
+        let mut sources: Vec<ModuleToken> = vec![];
+
+        loop {
+            let current_sources: Vec<ModuleToken> = working_reverse_imports
+                .iter()
+                .filter(|(_imported, importers)| importers.is_empty())
+                .map(|(source, _)| source)
+                .collect();
+
+            if current_sources.is_empty() {
+                break;
+            }
+
+            sources.extend(current_sources);
+            // Remove sources from graph, then try again for another round.
+            for source in sources.iter() {
+                remove_module_from_graph(
+                    source,
+                    &mut working_imports,
+                    &mut working_reverse_imports,
+                );
+            }
+        }
+
+        // Iteratively extract sinks into a vec.
+        let mut sinks: Vec<ModuleToken> = vec![];
+        loop {
+            let new_sinks: Vec<ModuleToken> = working_imports
+                .iter()
+                .filter(|(_importer, importeds)| importeds.is_empty())
+                .map(|(sink, _)| sink)
+                .collect();
+
+            if new_sinks.is_empty() {
+                break;
+            }
+
+            // Remove sinks from graph, then try again for another round.
+            for sink in new_sinks.iter() {
+                remove_module_from_graph(sink, &mut working_imports, &mut working_reverse_imports);
+            }
+            // Add the new sinks to the beginning of sinks - these need to appear earlier in
+            // the overall order, as they depend on the sinks previously found.
+            sinks.splice(0..0, new_sinks);
+            //sinks.extend(new_sinks);
+        }
+
+        // Iteratively extract remaining nodes, based on out-degree - in-degree.
+        let mut middle: Vec<ModuleToken> = vec![];
+        loop {
+            if working_imports.is_empty() {
+                // We've finished ordering the nodes.
+                break;
+            }
+
+            // Initialize with the first node.
+            let mut node_with_highest_difference: Option<ModuleToken> = None;
+            let mut highest_difference_so_far: Option<isize> = None;
+
+            for (candidate, _) in working_imports.iter() {
+                let difference = calculate_degree_difference(
+                    &candidate,
+                    &working_imports,
+                    &working_reverse_imports,
+                    &edge_weights,
+                );
+
+                match node_with_highest_difference {
+                    Some(incumbent) => {
+                        match difference.cmp(&highest_difference_so_far.unwrap()) {
+                            Ordering::Greater => {
+                                highest_difference_so_far = Some(difference);
+                                node_with_highest_difference = Some(candidate);
+                            }
+                            Ordering::Equal => {
+                                // Tie breaker - choose the earlier one alphabetically.
+                                let incumbent_name = self.get_module(incumbent).unwrap().name();
+                                let candidate_name = self.get_module(candidate).unwrap().name();
+
+                                if candidate_name < incumbent_name {
+                                    highest_difference_so_far = Some(difference);
+                                    node_with_highest_difference = Some(candidate);
+                                }
+                            }
+                            Ordering::Less => {}
+                        }
+                    }
+                    None => {
+                        node_with_highest_difference = Some(candidate);
+                        highest_difference_so_far = Some(difference);
+                    }
+                }
+            }
+
+            // Extract node with highest difference to one of the two middle vecs.
+            let node_with_highest_difference = node_with_highest_difference.unwrap();
+
+            // Prioritize high out-degree.
+            middle.push(node_with_highest_difference);
+            remove_module_from_graph(
+                &node_with_highest_difference,
+                &mut working_imports,
+                &mut working_reverse_imports,
+            );
+        }
+        if !working_reverse_imports.is_empty() {
+            panic!("Expected reverse imports also to be empty.");
+        }
+
+        // Combine sources + ordered + sinks.
+        let full_ordering: Vec<_> = sources.into_iter().chain(middle).chain(sinks).collect();
+        // Iterate through all edges in original graph.
+        // If the edge points leftwards in the full ordering, it is a circuit breaker.
+        let mut package_cycle_breakers: Vec<(ModuleToken, ModuleToken)> = vec![];
+        for (importer, importeds) in orig_imports.iter() {
+            for imported in importeds.iter() {
+                let importer_position = get_module_position(&full_ordering, &importer).unwrap();
+                let imported_position = get_module_position(&full_ordering, imported).unwrap();
+                if imported_position < importer_position {
+                    package_cycle_breakers.push((importer, *imported));
+                }
+            }
+        }
+
+        // Expand the package cycle breakers to the specific imports from the unsquashed graph.
+        let mut cycle_breakers = FxHashSet::default();
+        for (importer, imported) in package_cycle_breakers {
+            cycle_breakers.extend(
+                self.find_direct_imports_between(importer, imported, true)
+                    .unwrap(),
+            );
+        }
+
+        Ok(cycle_breakers)
+    }
+
+    // These maps represent the local graph. Each module appears as a key in the maps,
+    // 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(
+        &self,
+        children: &FxHashSet<ModuleToken>,
+    ) -> (
+        SecondaryMap<ModuleToken, FxHashSet<ModuleToken>>, // Imports
+        SecondaryMap<ModuleToken, FxHashSet<ModuleToken>>, // Reverse imports
+        FxHashMap<(ModuleToken, ModuleToken), usize>,      // Weights
+    ) {
+        let mut orig_imports: SecondaryMap<ModuleToken, FxHashSet<ModuleToken>> =
+            SecondaryMap::default();
+        let mut orig_reverse_imports: SecondaryMap<ModuleToken, FxHashSet<ModuleToken>> =
+            SecondaryMap::default();
+        let mut weights = FxHashMap::default();
+
+        for child in children {
+            orig_imports.insert(*child, FxHashSet::default());
+            orig_reverse_imports.insert(*child, FxHashSet::default());
+        }
+        // Get number of imports between each child.
+        // 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).
+                let num_imports_from_a_to_b = self
+                    .find_direct_imports_between(*child_a, *child_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, orig_reverse_imports, weights)
+    }
+}
+
+/// Removes the module from the graph, along with any imports to or from it.
+fn remove_module_from_graph(
+    module: &ModuleToken,
+    imports: &mut SecondaryMap<ModuleToken, FxHashSet<ModuleToken>>,
+    reverse_imports: &mut SecondaryMap<ModuleToken, FxHashSet<ModuleToken>>,
+) {
+    imports.remove(*module);
+    for (_, importeds) in imports.iter_mut() {
+        importeds.remove(module);
+    }
+    reverse_imports.remove(*module);
+    for (_, importers) in reverse_imports.iter_mut() {
+        importers.remove(module);
+    }
+}
+
+/// Removes the module from the graph, along with any imports to or from it.
+fn calculate_degree_difference(
+    module: &ModuleToken,
+    imports: &SecondaryMap<ModuleToken, FxHashSet<ModuleToken>>,
+    reverse_imports: &SecondaryMap<ModuleToken, FxHashSet<ModuleToken>>,
+    edge_weights: &FxHashMap<(ModuleToken, ModuleToken), usize>,
+) -> isize {
+    let importer_modules = &reverse_imports[*module];
+    let imported_modules = &imports[*module];
+
+    let indegree: isize = importer_modules
+        .iter()
+        .map(|importer| edge_weights[&(*importer, *module)] as isize)
+        .sum();
+    let outdegree: isize = imported_modules
+        .iter()
+        .map(|imported| edge_weights[&(*module, *imported)] as isize)
+        .sum();
+
+    outdegree - indegree
+}
+
+fn get_module_position(vec: &[ModuleToken], module: &ModuleToken) -> Option<usize> {
+    vec.iter().position(|&i| i == *module)
+}

{grimp-3.12 → grimp-3.13}/rust/src/graph/direct_import_queries.rs

@@ -17,22 +17,54 @@ impl Graph {
         imported: ModuleToken,
         as_packages: bool,
     ) -> GrimpResult<bool> {
-        let mut importer: FxHashSet<_> = importer.into();
-        let mut imported: FxHashSet<_> = imported.into();
+        let mut importers: FxHashSet<_> = importer.into();
+        let mut importeds: FxHashSet<_> = imported.into();
         if as_packages {
-            importer.extend_with_descendants(self);
-            imported.extend_with_descendants(self);
-            if !(&importer & &imported).is_empty() {
+            importers.extend_with_descendants(self);
+            importeds.extend_with_descendants(self);
+            if !(&importers & &importeds).is_empty() {
                 return Err(GrimpError::SharedDescendants);
             }
         }
 
-        let direct_imports = importer
+        let direct_imports = importers
             .iter()
-            .flat_map(|module| self.imports.get(*module).unwrap().iter().cloned())
+            .flat_map(|importer_module| self.imports.get(*importer_module).unwrap().iter().cloned())
             .collect::<FxHashSet<ModuleToken>>();
 
-        Ok(!(&direct_imports & &imported).is_empty())
+        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> {

{grimp-3.12 → grimp-3.13}/rust/src/graph/mod.rs

@@ -25,6 +25,7 @@ pub mod hierarchy_queries;
 pub mod higher_order_queries;
 pub mod import_chain_queries;
 
+pub mod cycle_breakers;
 pub(crate) mod pathfinding;
 
 static MODULE_NAMES: LazyLock<RwLock<StringInterner<StringBackend>>> =
@@ -619,6 +620,35 @@ impl GraphWrapper {
         self.convert_package_dependencies_to_python(py, illegal_dependencies)
     }
 
+    pub fn nominate_cycle_breakers<'py>(
+        &self,
+        py: Python<'py>,
+        package: &str,
+    ) -> 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()
+                }),
+        )
+    }
+
     #[pyo3(name = "clone")]
     pub fn clone_py(&self) -> GraphWrapper {
         self.clone()

{grimp-3.12 → grimp-3.13}/src/grimp/__init__.py

@@ -1,6 +1,6 @@
-__version__ = "3.12"
+__version__ = "3.13"
 
-from .application.ports.graph import DetailedImport, ImportGraph, Import
+from .application.graph import DetailedImport, ImportGraph, Import
 from .domain.analysis import PackageDependency, Route
 from .domain.valueobjects import DirectImport, Module, Layer
 from .main import build_graph

{grimp-3.12/src/grimp/application/ports → grimp-3.13/src/grimp/application}/graph.py

@@ -1,12 +1,14 @@
 from __future__ import annotations
-
-import abc
-from typing import Iterator, List, Optional, Sequence, Set, Tuple
-
-from typing_extensions import TypedDict
-
-from grimp.domain.analysis import PackageDependency
+from typing import List, Optional, Sequence, Set, Tuple, TypedDict
+from grimp.domain.analysis import PackageDependency, Route
 from grimp.domain.valueobjects import Layer
+from grimp import _rustgrimp as rust  # type: ignore[attr-defined]
+from grimp.exceptions import (
+    ModuleNotPresent,
+    NoSuchContainer,
+    InvalidModuleExpression,
+    InvalidImportExpression,
+)
 
 
 class Import(TypedDict):
@@ -14,28 +16,38 @@ class Import(TypedDict):
     imported: str
 
 
+# Corresponds to importer, imported.
+# Prefer this form to Import, as it's both more lightweight, and hashable.
+ImportTuple = Tuple[str, str]
+
+
 class DetailedImport(Import):
     line_number: int
     line_contents: str
 
 
-class ImportGraph(abc.ABC):
+class ImportGraph:
     """
     A Directed Graph of imports between Python modules.
     """
 
+    def __init__(self) -> None:
+        super().__init__()
+        self._cached_modules: Set[str] | None = None
+        self._rustgraph = rust.Graph()
+
     # Mechanics
     # ---------
 
     @property
-    @abc.abstractmethod
     def modules(self) -> Set[str]:
         """
         The names of all the modules in the graph.
         """
-        raise NotImplementedError
+        if self._cached_modules is None:
+            self._cached_modules = self._rustgraph.get_modules()
+        return self._cached_modules
 
-    @abc.abstractmethod
     def find_matching_modules(self, expression: str) -> Set[str]:
         """
         Find all modules matching the passed expression.
@@ -67,9 +79,11 @@ class ImportGraph(abc.ABC):
         - ``mypackage.foo*``: is not a valid expression. (The wildcard must replace a whole module
           name.)
         """
-        raise NotImplementedError
+        try:
+            return self._rustgraph.find_matching_modules(expression)
+        except rust.InvalidModuleExpression as e:
+            raise InvalidModuleExpression(str(e)) from e
 
-    @abc.abstractmethod
     def add_module(self, module: str, is_squashed: bool = False) -> None:
         """
         Add a module to the graph.
@@ -80,18 +94,18 @@ class ImportGraph(abc.ABC):
         want to include an external package in the graph but don't care about all the dependencies
         within that package.
         """
-        raise NotImplementedError
+        self._cached_modules = None
+        self._rustgraph.add_module(module, is_squashed)
 
-    @abc.abstractmethod
     def remove_module(self, module: str) -> None:
         """
         Remove a module from the graph, if it exists.
 
         If the module is not present in the graph, no exception will be raised.
         """
-        raise NotImplementedError
+        self._cached_modules = None
+        self._rustgraph.remove_module(module)
 
-    @abc.abstractmethod
     def squash_module(self, module: str) -> None:
         """
         'Squash' a module in the graph.
@@ -101,18 +115,21 @@ class ImportGraph(abc.ABC):
         A squashed module represents both itself and all its descendants. This allow parts of the
         graph to be simplified.
         """
-        raise NotImplementedError
+        self._cached_modules = None
+        if not self._rustgraph.contains_module(module):
+            raise ModuleNotPresent(f'"{module}" not present in the graph.')
+        self._rustgraph.squash_module(module)
 
-    @abc.abstractmethod
     def is_module_squashed(self, module: str) -> bool:
         """
         Return whether a module is squashed.
 
         If the module is not present in the graph, grimp.exceptions.ModuleNotPresent will be raised.
         """
-        raise NotImplementedError
+        if not self._rustgraph.contains_module(module):
+            raise ModuleNotPresent(f'"{module}" not present in the graph.')
+        return self._rustgraph.is_module_squashed(module)
 
-    @abc.abstractmethod
     def add_import(
         self,
         *,
@@ -125,26 +142,30 @@ class ImportGraph(abc.ABC):
         Add a direct import between two modules to the graph. If the modules are not already
         present, they will be added to the graph.
         """
-        raise NotImplementedError
+        self._cached_modules = None
+        self._rustgraph.add_import(
+            importer=importer,
+            imported=imported,
+            line_number=line_number,
+            line_contents=line_contents,
+        )
 
-    @abc.abstractmethod
     def remove_import(self, *, importer: str, imported: str) -> None:
         """
         Remove a direct import between two modules. Does not remove the modules themselves.
         """
-        raise NotImplementedError
+        self._cached_modules = None
+        return self._rustgraph.remove_import(importer=importer, imported=imported)
 
-    @abc.abstractmethod
     def count_imports(self) -> int:
         """
         Return the number of imports in the graph.
         """
-        raise NotImplementedError
+        return self._rustgraph.count_imports()
 
     # Descendants
     # -----------
 
-    @abc.abstractmethod
     def find_children(self, module: str) -> Set[str]:
         """
         Find all modules one level below the module. For example, the children of
@@ -153,9 +174,12 @@ class ImportGraph(abc.ABC):
         Raises:
             ValueError if attempted on a squashed module.
         """
-        raise NotImplementedError
+        # It doesn't make sense to find the children of a squashed module, as we don't store
+        # the children in the graph.
+        if self.is_module_squashed(module):
+            raise ValueError("Cannot find children of a squashed module.")
+        return self._rustgraph.find_children(module)
 
-    @abc.abstractmethod
     def find_descendants(self, module: str) -> Set[str]:
         """
         Find all modules below the module. For example, the descendants of
@@ -164,12 +188,15 @@ class ImportGraph(abc.ABC):
         Raises:
             ValueError if attempted on a squashed module.
         """
-        raise NotImplementedError
+        # It doesn't make sense to find the descendants of a squashed module, as we don't store
+        # the descendants in the graph.
+        if self.is_module_squashed(module):
+            raise ValueError("Cannot find descendants of a squashed module.")
+        return self._rustgraph.find_descendants(module)
 
     # Direct imports
     # --------------
 
-    @abc.abstractmethod
     def direct_import_exists(
         self, *, importer: str, imported: str, as_packages: bool = False
     ) -> bool:
@@ -182,17 +209,19 @@ class ImportGraph(abc.ABC):
             as_packages:  Whether or not to treat the supplied modules as individual modules,
                           or as entire packages (including any descendants).
         """
-        raise NotImplementedError
+        return self._rustgraph.direct_import_exists(
+            importer=importer, imported=imported, as_packages=as_packages
+        )
 
-    @abc.abstractmethod
     def find_modules_directly_imported_by(self, module: str) -> Set[str]:
-        raise NotImplementedError
+        return self._rustgraph.find_modules_directly_imported_by(module)
 
-    @abc.abstractmethod
     def find_modules_that_directly_import(self, module: str) -> Set[str]:
-        raise NotImplementedError
+        if self._rustgraph.contains_module(module):
+            # TODO panics if module isn't in modules.
+            return self._rustgraph.find_modules_that_directly_import(module)
+        return set()
 
-    @abc.abstractmethod
     def get_import_details(self, *, importer: str, imported: str) -> List[DetailedImport]:
         """
         Return available metadata relating to the direct imports between two modules, in the form:
@@ -212,10 +241,12 @@ class ImportGraph(abc.ABC):
         For example, if an import has been added by the `add_import` method without line_number and
         line_contents specified.
         """
-        raise NotImplementedError
+        return self._rustgraph.get_import_details(
+            importer=importer,
+            imported=imported,
+        )
 
-    @abc.abstractmethod
-    def find_matching_direct_imports(self, *, import_expression: str) -> List[Import]:
+    def find_matching_direct_imports(self, import_expression: str) -> List[Import]:
         """
         Find all direct imports matching the passed expressions.
 
@@ -242,12 +273,23 @@ class ImportGraph(abc.ABC):
 
         See `ImportGraph.find_matching_modules` for a description of module expressions.
         """
-        raise NotImplementedError
+        try:
+            importer_expression, imported_expression = import_expression.split(" -> ")
+        except ValueError:
+            raise InvalidImportExpression(f"{import_expression} is not a valid import expression.")
+
+        try:
+            return self._rustgraph.find_matching_direct_imports(
+                importer_expression=importer_expression, imported_expression=imported_expression
+            )
+        except rust.InvalidModuleExpression as e:
+            raise InvalidImportExpression(
+                f"{import_expression} is not a valid import expression."
+            ) from e
 
     # Indirect imports
     # ----------------
 
-    @abc.abstractmethod
     def find_downstream_modules(self, module: str, as_package: bool = False) -> Set[str]:
         """
         Return a set of the names of all the modules that import (even indirectly) the
@@ -268,9 +310,8 @@ class ImportGraph(abc.ABC):
             # mypackage.foo.two.
             import_graph.find_downstream_modules('mypackage.foo', as_package=True)
         """
-        raise NotImplementedError
+        return self._rustgraph.find_downstream_modules(module, as_package)
 
-    @abc.abstractmethod
     def find_upstream_modules(self, module: str, as_package: bool = False) -> Set[str]:
         """
         Return a set of the names of all the modules that are imported (even indirectly) by the
@@ -284,9 +325,8 @@ class ImportGraph(abc.ABC):
                            modules *external* to the subpackage, and won't include modules within
                            the subpackage.
         """
-        raise NotImplementedError
+        return self._rustgraph.find_upstream_modules(module, as_package)
 
-    @abc.abstractmethod
     def find_shortest_chain(
         self, importer: str, imported: str, as_packages: bool = False
     ) -> tuple[str, ...] | None:
@@ -303,9 +343,13 @@ class ImportGraph(abc.ABC):
         Returns:
             Tuple of module names, from importer to imported, or None if no chain exists.
         """
-        raise NotImplementedError
+        for module in (importer, imported):
+            if not self._rustgraph.contains_module(module):
+                raise ValueError(f"Module {module} is not present in the graph.")
+
+        chain = self._rustgraph.find_shortest_chain(importer, imported, as_packages)
+        return tuple(chain) if chain else None
 
-    @abc.abstractmethod
     def find_shortest_chains(
         self, importer: str, imported: str, as_packages: bool = True
     ) -> Set[Tuple[str, ...]]:
@@ -318,24 +362,11 @@ class ImportGraph(abc.ABC):
         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.
 
-
-
         Returns:
             A set of tuples of strings. Each tuple is ordered from importer to imported modules.
         """
-        raise NotImplementedError
-
-    def find_all_simple_chains(self, importer: str, imported: str) -> Iterator[Tuple[str, ...]]:
-        """
-        Generate all simple chains between the importer and the imported modules.
-
-        Note: this method is no longer documented and will be removed.
-        """
-        raise AttributeError(
-            "This method has been removed. Consider using find_shortest_chains instead?"
-        )
+        return self._rustgraph.find_shortest_chains(importer, imported, as_packages)
 
-    @abc.abstractmethod
     def chain_exists(self, importer: str, imported: str, as_packages: bool = False) -> bool:
         """
         Return whether any chain of imports exists between the two modules, in the direction
@@ -347,7 +378,7 @@ class ImportGraph(abc.ABC):
                          treating them as subpackages, all descendants of the supplied modules
                          will be checked too.
         """
-        raise NotImplementedError
+        return self._rustgraph.chain_exists(importer, imported, as_packages)
 
     # High level analysis
     # -------------------
@@ -395,7 +426,34 @@ class ImportGraph(abc.ABC):
 
         Raises NoSuchContainer if the container is not a module in the graph.
         """
-        raise NotImplementedError
+        layers = _parse_layers(layers)
+        try:
+            result = self._rustgraph.find_illegal_dependencies_for_layers(
+                layers=tuple(
+                    {
+                        "layers": layer.module_tails,
+                        "independent": layer.independent,
+                        "closed": layer.closed,
+                    }
+                    for layer in layers
+                ),
+                containers=set(containers) if containers else set(),
+            )
+        except rust.NoSuchContainer as e:
+            raise NoSuchContainer(str(e))
+
+        return _dependencies_from_tuple(result)
+
+    def nominate_cycle_breakers(self, package: str) -> set[ImportTuple]:
+        """
+        Identify a set of imports that, if removed, would make the package locally acyclic.
+        """
+        if not self._rustgraph.contains_module(package):
+            raise ModuleNotPresent(f'"{package}" not present in the graph.')
+        return self._rustgraph.nominate_cycle_breakers(package)
+
+    # Dunder methods
+    # --------------
 
     def __repr__(self) -> str:
         """
@@ -415,3 +473,57 @@ class ImportGraph(abc.ABC):
         else:
             stringified_modules = "empty"
         return f"<{self.__class__.__name__}: {stringified_modules}>"
+
+    def __deepcopy__(self, memodict: dict) -> "ImportGraph":
+        new_graph = ImportGraph()
+        new_graph._rustgraph = self._rustgraph.clone()
+        return new_graph
+
+
+class _RustRoute(TypedDict):
+    heads: frozenset[str]
+    middle: tuple[str, ...]
+    tails: frozenset[str]
+
+
+class _RustPackageDependency(TypedDict):
+    importer: str
+    imported: str
+    routes: tuple[_RustRoute, ...]
+
+
+def _parse_layers(layers: Sequence[Layer | str | set[str]]) -> tuple[Layer, ...]:
+    """
+    Convert the passed raw `layers` into `Layer`s.
+    """
+    out_layers = []
+    for layer in layers:
+        if isinstance(layer, Layer):
+            out_layers.append(layer)
+        elif isinstance(layer, str):
+            out_layers.append(Layer(layer))
+        else:
+            out_layers.append(Layer(*tuple(layer)))
+    return tuple(out_layers)
+
+
+def _dependencies_from_tuple(
+    rust_package_dependency_tuple: tuple[_RustPackageDependency, ...],
+) -> set[PackageDependency]:
+    return {
+        PackageDependency(
+            imported=dep_dict["imported"],
+            importer=dep_dict["importer"],
+            routes=frozenset(
+                {
+                    Route(
+                        heads=route_dict["heads"],
+                        middle=route_dict["middle"],
+                        tails=route_dict["tails"],
+                    )
+                    for route_dict in dep_dict["routes"]
+                }
+            ),
+        )
+        for dep_dict in rust_package_dependency_tuple
+    }

{grimp-3.12 → grimp-3.13}/src/grimp/application/usecases.py

@@ -7,7 +7,7 @@ from typing import Dict, Sequence, Set, Type, Union, cast, Iterable
 from .scanning import scan_imports
 from ..application.ports import caching
 from ..application.ports.filesystem import AbstractFileSystem
-from ..application.ports.graph import ImportGraph
+from ..application.graph import ImportGraph
 from ..application.ports.modulefinder import AbstractModuleFinder, FoundPackage, ModuleFile
 from ..application.ports.packagefinder import AbstractPackageFinder
 from ..domain.valueobjects import DirectImport, Module

{grimp-3.12 → grimp-3.13}/src/grimp/main.py

@@ -2,7 +2,7 @@ __all__ = ["build_graph"]
 
 from .adaptors.caching import Cache
 from .adaptors.filesystem import FileSystem
-from .adaptors.graph import ImportGraph
+from .application.graph import ImportGraph
 from .adaptors.modulefinder import ModuleFinder
 from .adaptors.packagefinder import ImportLibPackageFinder
 from .adaptors.timing import SystemClockTimer

grimp-3.12/src/grimp/adaptors/graph.py

@@ -1,233 +0,0 @@
-from __future__ import annotations
-from typing import List, Optional, Sequence, Set, Tuple, TypedDict
-from grimp.application.ports.graph import DetailedImport, Import
-from grimp.domain.analysis import PackageDependency, Route
-from grimp.domain.valueobjects import Layer
-from grimp import _rustgrimp as rust  # type: ignore[attr-defined]
-from grimp.exceptions import (
-    ModuleNotPresent,
-    NoSuchContainer,
-    InvalidModuleExpression,
-    InvalidImportExpression,
-)
-from grimp.application.ports import graph
-
-
-class ImportGraph(graph.ImportGraph):
-    """
-    Rust-backed implementation of the ImportGraph.
-    """
-
-    def __init__(self) -> None:
-        super().__init__()
-        self._cached_modules: Set[str] | None = None
-        self._rustgraph = rust.Graph()
-
-    @property
-    def modules(self) -> Set[str]:
-        if self._cached_modules is None:
-            self._cached_modules = self._rustgraph.get_modules()
-        return self._cached_modules
-
-    def find_matching_modules(self, expression: str) -> Set[str]:
-        try:
-            return self._rustgraph.find_matching_modules(expression)
-        except rust.InvalidModuleExpression as e:
-            raise InvalidModuleExpression(str(e)) from e
-
-    def add_module(self, module: str, is_squashed: bool = False) -> None:
-        self._cached_modules = None
-        self._rustgraph.add_module(module, is_squashed)
-
-    def remove_module(self, module: str) -> None:
-        self._cached_modules = None
-        self._rustgraph.remove_module(module)
-
-    def squash_module(self, module: str) -> None:
-        self._cached_modules = None
-        if not self._rustgraph.contains_module(module):
-            raise ModuleNotPresent(f'"{module}" not present in the graph.')
-        self._rustgraph.squash_module(module)
-
-    def is_module_squashed(self, module: str) -> bool:
-        if not self._rustgraph.contains_module(module):
-            raise ModuleNotPresent(f'"{module}" not present in the graph.')
-        return self._rustgraph.is_module_squashed(module)
-
-    def add_import(
-        self,
-        *,
-        importer: str,
-        imported: str,
-        line_number: Optional[int] = None,
-        line_contents: Optional[str] = None,
-    ) -> None:
-        self._cached_modules = None
-        self._rustgraph.add_import(
-            importer=importer,
-            imported=imported,
-            line_number=line_number,
-            line_contents=line_contents,
-        )
-
-    def remove_import(self, *, importer: str, imported: str) -> None:
-        self._cached_modules = None
-        return self._rustgraph.remove_import(importer=importer, imported=imported)
-
-    def count_imports(self) -> int:
-        return self._rustgraph.count_imports()
-
-    def find_children(self, module: str) -> Set[str]:
-        # It doesn't make sense to find the children of a squashed module, as we don't store
-        # the children in the graph.
-        if self.is_module_squashed(module):
-            raise ValueError("Cannot find children of a squashed module.")
-        return self._rustgraph.find_children(module)
-
-    def find_descendants(self, module: str) -> Set[str]:
-        # It doesn't make sense to find the descendants of a squashed module, as we don't store
-        # the descendants in the graph.
-        if self.is_module_squashed(module):
-            raise ValueError("Cannot find descendants of a squashed module.")
-        return self._rustgraph.find_descendants(module)
-
-    def direct_import_exists(
-        self, *, importer: str, imported: str, as_packages: bool = False
-    ) -> bool:
-        return self._rustgraph.direct_import_exists(
-            importer=importer, imported=imported, as_packages=as_packages
-        )
-
-    def find_modules_directly_imported_by(self, module: str) -> Set[str]:
-        return self._rustgraph.find_modules_directly_imported_by(module)
-
-    def find_modules_that_directly_import(self, module: str) -> Set[str]:
-        if self._rustgraph.contains_module(module):
-            # TODO panics if module isn't in modules.
-            return self._rustgraph.find_modules_that_directly_import(module)
-        return set()
-
-    def get_import_details(self, *, importer: str, imported: str) -> List[DetailedImport]:
-        return self._rustgraph.get_import_details(
-            importer=importer,
-            imported=imported,
-        )
-
-    def find_matching_direct_imports(self, import_expression: str) -> List[Import]:
-        try:
-            importer_expression, imported_expression = import_expression.split(" -> ")
-        except ValueError:
-            raise InvalidImportExpression(f"{import_expression} is not a valid import expression.")
-
-        try:
-            return self._rustgraph.find_matching_direct_imports(
-                importer_expression=importer_expression, imported_expression=imported_expression
-            )
-        except rust.InvalidModuleExpression as e:
-            raise InvalidImportExpression(
-                f"{import_expression} is not a valid import expression."
-            ) from e
-
-    def find_downstream_modules(self, module: str, as_package: bool = False) -> Set[str]:
-        return self._rustgraph.find_downstream_modules(module, as_package)
-
-    def find_upstream_modules(self, module: str, as_package: bool = False) -> Set[str]:
-        return self._rustgraph.find_upstream_modules(module, as_package)
-
-    def find_shortest_chain(
-        self, importer: str, imported: str, as_packages: bool = False
-    ) -> tuple[str, ...] | None:
-        for module in (importer, imported):
-            if not self._rustgraph.contains_module(module):
-                raise ValueError(f"Module {module} is not present in the graph.")
-
-        chain = self._rustgraph.find_shortest_chain(importer, imported, as_packages)
-        return tuple(chain) if chain else None
-
-    def find_shortest_chains(
-        self, importer: str, imported: str, as_packages: bool = True
-    ) -> Set[Tuple[str, ...]]:
-        return self._rustgraph.find_shortest_chains(importer, imported, as_packages)
-
-    def chain_exists(self, importer: str, imported: str, as_packages: bool = False) -> bool:
-        return self._rustgraph.chain_exists(importer, imported, as_packages)
-
-    def find_illegal_dependencies_for_layers(
-        self,
-        layers: Sequence[Layer | str | set[str]],
-        containers: set[str] | None = None,
-    ) -> set[PackageDependency]:
-        layers = _parse_layers(layers)
-        try:
-            result = self._rustgraph.find_illegal_dependencies_for_layers(
-                layers=tuple(
-                    {
-                        "layers": layer.module_tails,
-                        "independent": layer.independent,
-                        "closed": layer.closed,
-                    }
-                    for layer in layers
-                ),
-                containers=set(containers) if containers else set(),
-            )
-        except rust.NoSuchContainer as e:
-            raise NoSuchContainer(str(e))
-
-        return _dependencies_from_tuple(result)
-
-    # Dunder methods
-    # --------------
-
-    def __deepcopy__(self, memodict: dict) -> "ImportGraph":
-        new_graph = ImportGraph()
-        new_graph._rustgraph = self._rustgraph.clone()
-        return new_graph
-
-
-class _RustRoute(TypedDict):
-    heads: frozenset[str]
-    middle: tuple[str, ...]
-    tails: frozenset[str]
-
-
-class _RustPackageDependency(TypedDict):
-    importer: str
-    imported: str
-    routes: tuple[_RustRoute, ...]
-
-
-def _parse_layers(layers: Sequence[Layer | str | set[str]]) -> tuple[Layer, ...]:
-    """
-    Convert the passed raw `layers` into `Layer`s.
-    """
-    out_layers = []
-    for layer in layers:
-        if isinstance(layer, Layer):
-            out_layers.append(layer)
-        elif isinstance(layer, str):
-            out_layers.append(Layer(layer))
-        else:
-            out_layers.append(Layer(*tuple(layer)))
-    return tuple(out_layers)
-
-
-def _dependencies_from_tuple(
-    rust_package_dependency_tuple: tuple[_RustPackageDependency, ...],
-) -> set[PackageDependency]:
-    return {
-        PackageDependency(
-            imported=dep_dict["imported"],
-            importer=dep_dict["importer"],
-            routes=frozenset(
-                {
-                    Route(
-                        heads=route_dict["heads"],
-                        middle=route_dict["middle"],
-                        tails=route_dict["tails"],
-                    )
-                    for route_dict in dep_dict["routes"]
-                }
-            ),
-        )
-        for dep_dict in rust_package_dependency_tuple
-    }