Support using the subtraction operator to get the relative path between URLs

CHANGES/1340.feature.rst

@@ -0,0 +1,2 @@
+Added support for using the :meth:`subtraction operator <yarl.URL.__sub__>`
+to get the relative path between URLs -- by :user:`oleksbabieiev`.

docs/api.rst

@@ -974,6 +974,21 @@ The path is encoded if needed.
          >>> base.join(URL('//python.org/page.html'))
          URL('http://python.org/page.html')
 
+The subtraction (``-``) operator creates a new URL with
+a relative *path* to the target URL from the given base URL.
+*scheme*, *user*, *password*, *host* and *port* are removed.
+
+.. method:: URL.__sub__(url)
+
+   Returns a new URL with a relative *path* between two other URL objects.
+
+   .. doctest::
+
+      >>> target = URL('http://example.com/path/index.html')
+      >>> base = URL('http://example.com/')
+      >>> target - base
+      URL('path/index.html')
+
 Human readable representation
 -----------------------------
 

tests/test_url.py

@@ -61,6 +61,33 @@ def test_str():
     assert str(url) == "http://example.com:8888/path/to?a=1&b=2"
 
 
+@pytest.mark.parametrize(
+    "target,base,expected",
+    [
+        ("http://example.com/path/to", "http://example.com/", "path/to"),
+        ("http://example.com/path/to", "http://example.com/spam", "path/to"),
+        ("http://example.com/path/to", "http://example.com/spam/", "../path/to"),
+        ("http://example.com/path", "http://example.com/path/to/", ".."),
+        ("http://example.com/", "http://example.com/", "."),
+        ("http://example.com", "http://example.com", "."),
+    ],
+)
+def test_sub(target: str, base: str, expected: str):
+    assert URL(target) - URL(base) == URL(expected)
+
+
+def test_sub_with_different_schemes():
+    with pytest.raises(ValueError) as ctx:
+        URL("http://example.com/") - URL("https://example.com/")
+    assert "Both URLs should have the same scheme" == str(ctx.value)
+
+
+def test_sub_with_different_netlocs():
+    with pytest.raises(ValueError) as ctx:
+        URL("https://spam.com/") - URL("https://ham.com/")
+    assert "Both URLs should have the same netloc" == str(ctx.value)
+
+
 def test_repr():
     url = URL("http://example.com")
     assert "URL('http://example.com')" == repr(url)

yarl/_path.py

@@ -2,6 +2,7 @@
 
 from collections.abc import Sequence
 from contextlib import suppress
+from os.path import dirname, relpath
 
 
 def normalize_path_segments(segments: Sequence[str]) -> list[str]:
@@ -39,3 +40,16 @@ def normalize_path(path: str) -> str:
 
     segments = path.split("/")
     return prefix + "/".join(normalize_path_segments(segments))
+
+
+def relative_path(path: str, start: str) -> str:
+    """A wrapper over os.path.relpath()"""
+
+    if not path:
+        path = "/"
+    if not start:
+        start = "/"
+    if not start.endswith("/"):
+        start = dirname(start)
+
+    return relpath(path, start)

yarl/_url.py

@@ -12,7 +12,7 @@
 from propcache.api import under_cached_property as cached_property
 
 from ._parse import USES_AUTHORITY, make_netloc, split_netloc, split_url, unsplit_result
-from ._path import normalize_path, normalize_path_segments
+from ._path import normalize_path, normalize_path_segments, relative_path
 from ._query import (
     Query,
     QueryVariable,
@@ -475,6 +475,21 @@ def __truediv__(self, name: str) -> "URL":
             return NotImplemented
         return self._make_child((str(name),))
 
+    def __sub__(self, other: object) -> "URL":
+        if type(other) is not URL:
+            return NotImplemented
+
+        target = self._val
+        base = other._val
+
+        if target.scheme != base.scheme:
+            raise ValueError("Both URLs should have the same scheme")
+        if target.netloc != base.netloc:
+            raise ValueError("Both URLs should have the same netloc")
+
+        path = relative_path(target.path, base.path)
+        return self._from_tup(("", "", path, "", ""))
+
     def __mod__(self, query: Query) -> "URL":
         return self.update_query(query)