Change find_matching_direct_imports to expect an import expression

Author: seddonym

docs/usage.rst

@@ -194,9 +194,9 @@ Methods for analysing direct imports
         So if a module is imported twice from the same module, it will only be counted once.
     :rtype: Integer.
 
-.. py:function:: ImportGraph.find_matching_direct_imports(importer_expression, imported_expression)
+.. py:function:: ImportGraph.find_matching_direct_imports(import_expression)
 
-    Find all direct imports matching the passed expressions (see :ref:`module_expressions`).
+    Find all direct imports matching the passed import expression.
 
     The imports are returned are in the following form::
 
@@ -208,12 +208,13 @@ Methods for analysing direct imports
             # (additional imports here)
         ]
 
-    :param str importer_expression: A module expression used for matching importing modules.
-    :param str imported_expression: A module expression used for matching imported modules.
+    :param str import_expression: An expression in the form "importer_expression -> imported_expression", where each
+        expression is a module expression (see :ref:`module_expressions`).
+        Example: ``"mypackage.*.blue -> mypackage.*.green"``.
     :return: An ordered list of direct imports matching the expressions (ordered alphabetically).
     :rtype: List of dictionaries with the structure shown above. If you want to use type annotations, you may use the
         ``grimp.Import`` TypedDict for each dictionary.
-    :raises: ``grimp.exceptions.InvalidModuleExpression`` if either of the module expressions is invalid.
+    :raises: ``grimp.exceptions.InvalidImportExpression`` if the expression is not well-formed.
 
 Methods for analysing import chains
 -----------------------------------

src/grimp/adaptors/graph.py

@@ -4,7 +4,7 @@
 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
+from grimp.exceptions import ModuleNotPresent, NoSuchContainer, InvalidModuleExpression, InvalidImportExpression
 from grimp.application.ports import graph
 
 
@@ -108,15 +108,18 @@ def get_import_details(self, *, importer: str, imported: str) -> List[DetailedIm
             imported=imported,
         )
 
-    def find_matching_direct_imports(
-        self, *, importer_expression: str, imported_expression: str
-    ) -> List[Import]:
+    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 InvalidModuleExpression(str(e)) from 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)

src/grimp/application/ports/graph.py

@@ -215,9 +215,7 @@ def get_import_details(self, *, importer: str, imported: str) -> List[DetailedIm
         raise NotImplementedError
 
     @abc.abstractmethod
-    def find_matching_direct_imports(
-        self, *, importer_expression: str, imported_expression: str
-    ) -> List[Import]:
+    def find_matching_direct_imports(self, *, import_expression: str) -> List[Import]:
         """
         Find all direct imports matching the passed expressions.
 
@@ -232,14 +230,15 @@ def find_matching_direct_imports(
         ]
 
         Args:
-            importer_expression: A module expression used for matching importing modules.
-            imported_expression: A module expression used for matching imported modules.
+            import_expression: An expression used for matching importing modules, in the form
+                "importer_expression -> imported_expression", where both expressions are
+                module expressions.
         Returns:
             A list of direct imports matching the expressions, ordered alphabetically by importer,
             then imported.
             (We return a list rather than a set purely because dictionaries aren't hashable.)
         Raises:
-            InvalidModuleExpression if either of the passed expressions are invalid.
+            InvalidImportExpression if either of the passed expressions are invalid.
 
         See `ImportGraph.find_matching_modules` for a description of module expressions.
         """

src/grimp/exceptions.py

@@ -65,3 +65,7 @@ def __eq__(self, other):
 
 class InvalidModuleExpression(GrimpException):
     pass
+
+
+class InvalidImportExpression(GrimpException):
+    pass

tests/unit/adaptors/graph/test_direct_imports.py

@@ -1,7 +1,8 @@
 import pytest  # type: ignore
 
 from grimp.adaptors.graph import ImportGraph
-from grimp.exceptions import InvalidModuleExpression
+import re
+from grimp.exceptions import InvalidImportExpression
 
 
 def test_find_modules_directly_imported_by():
@@ -318,9 +319,7 @@ def test_finds_matching_direct_imports(self, import_line_number, import_line_con
             line_contents=import_line_contents,
         )
 
-        assert graph.find_matching_direct_imports(
-            importer_expression="pkg.animals.*", imported_expression="pkg.food.*"
-        ) == [
+        assert graph.find_matching_direct_imports("pkg.animals.* -> pkg.food.*") == [
             {"importer": "pkg.animals.cat", "imported": "pkg.food.fish"},
             {"importer": "pkg.animals.dog", "imported": "pkg.food.chicken"},
         ]
@@ -340,26 +339,22 @@ def test_deduplicates_imports(self):
             line_contents="...2",
         )
 
-        assert graph.find_matching_direct_imports(
-            importer_expression="pkg.animals.*", imported_expression="pkg.colors.*"
-        ) == [
+        assert graph.find_matching_direct_imports("pkg.animals.* -> pkg.colors.*") == [
             {"importer": "pkg.animals.dog", "imported": "pkg.colors.golden"},
         ]
 
-    def test_raises_error_if_importer_expression_is_invalid(self):
-        graph = ImportGraph()
-        with pytest.raises(
-            InvalidModuleExpression, match="foo.. is not a valid module expression."
-        ):
-            graph.find_matching_direct_imports(
-                importer_expression="foo..", imported_expression="bar"
-            )
-
-    def test_raises_error_if_imported_expression_is_invalid(self):
+    @pytest.mark.parametrize(
+        "expression",
+        [
+            "foo.. -> bar",
+            "foo -> bar..",
+            "foo > bar",
+        ],
+    )
+    def test_raises_error_if_expression_is_invalid(self, expression):
         graph = ImportGraph()
         with pytest.raises(
-            InvalidModuleExpression, match="bar.. is not a valid module expression."
+            InvalidImportExpression,
+            match=re.escape(f"{expression} is not a valid import expression."),
         ):
-            graph.find_matching_direct_imports(
-                importer_expression="foo", imported_expression="bar.."
-            )
+            graph.find_matching_direct_imports(expression)