Add the URL subtraction feature

Author: babieiev

CHANGES/1538.feature.rst

@@ -0,0 +1,15 @@
+Added a new method :py:meth:`~yarl.URL.relative_to`
+to get the relative path between URLs.
+
+Note that both URLs must have the same scheme, user, password, host and port:
+
+.. code-block:: pycon
+
+    >>> target = URL("http://example.com/path/to")
+    >>> base = URL("http://example.com/")
+    >>> target.relative_to(base)
+    URL('path/to')
+    >>> base.relative_to(target)
+    URL('../..')
+
+-- by :user:`babieiev`.

docs/api.rst

@@ -1015,6 +1015,22 @@ The path is encoded if needed.
          >>> base.join(URL('//python.org/page.html'))
          URL('http://python.org/page.html')
 
+.. method:: URL.relative_to(url)
+
+   Return a new URL with a relative *path* between two other URL objects.
+   *scheme*, *user*, *password*, *host*, *port*, *query* and *fragment* are removed.
+
+   .. doctest::
+
+      >>> target = URL('http://example.com/path/to')
+      >>> base = URL('http://example.com/')
+      >>> target.relative_to(base)
+      URL('path/to')
+      >>> base.relative_to(target)
+      URL('../..')
+
+   .. versionadded:: 1.21
+
 Human readable representation
 -----------------------------
 

tests/test_url.py

@@ -4,6 +4,7 @@
 import pytest
 
 from yarl import URL
+from yarl._path import normalize_path
 
 _WHATWG_C0_CONTROL_OR_SPACE = (
     "\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f\x10"
@@ -994,6 +995,91 @@ def test_div_with_dots() -> None:
     assert url.raw_path == "/path/to"
 
 
+# relative_to
+
+
+@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/this/is/a/test", "http://example.com/this/", "is/a/test"),
+        (
+            "http://example.com/this/./is/a/test",
+            "http://example.com/this/",
+            "is/a/test",
+        ),
+        (
+            "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/this/is/../a//test",
+            "http://example.com/this/",
+            "a//test",
+        ),
+        ("http://example.com/", "http://example.com/", "."),
+        ("http://example.com", "http://example.com", "."),
+        ("http://example.com/", "http://example.com", "."),
+        ("http://example.com", "http://example.com/", "."),
+        ("//example.com", "//example.com", "."),
+        ("/path/to", "/spam/", "../path/to"),
+        ("path/to", "spam/", "../path/to"),
+        (
+            "http://example.com/path/to//",
+            "http://example.com/path/to",
+            ".//",
+        ),
+        (
+            "http://example.com/path/to//",
+            "http://example.com/path/to/",
+            ".//",
+        ),
+        ("path/../to", "path/", "../to"),
+        ("path/..", ".", "../path/.."),
+        ("path/../replace/me", "path/../replace", "me"),
+        ("path/../replace/me", "path/../replace/", "me"),
+        ("path/to", "spam", "../path/to"),
+        ("..", ".", "../.."),
+        (".", "..", "../."),
+    ],
+)
+def test_relative_to(target: str, base: str, expected: str) -> None:
+    # test the input data
+    target_url = URL(target)
+    base_url = URL(base)
+    assert normalize_path(target_url.path) == normalize_path((base_url / expected).path)
+    # test the function itself
+    expected_url = URL(expected)
+    relative_url = target_url.relative_to(base_url)
+    assert relative_url == expected_url
+
+
+def test_relative_to_a_non_url() -> None:
+    expected_error_msg = r"^other should be URL$"
+    with pytest.raises(TypeError, match=expected_error_msg):
+        URL("https://example.com/path/to").relative_to("http://example.com/")
+
+
+def test_relative_to_with_different_schemes() -> None:
+    expected_error_msg = r"^Both URLs should have the same scheme$"
+    with pytest.raises(ValueError, match=expected_error_msg):
+        URL("http://example.com/").relative_to(URL("https://example.com/"))
+
+
+def test_relative_to_with_different_netlocs() -> None:
+    expected_error_msg = r"^Both URLs should have the same netloc$"
+    with pytest.raises(ValueError, match=expected_error_msg):
+        URL("https://spam.com/").relative_to(URL("https://ham.com/"))
+
+
 # joinpath
 
 

tests/test_url_benchmarks.py

@@ -34,6 +34,9 @@
 QUERY_URL = URL(QUERY_URL_STR)
 URL_WITH_PATH_STR = "http://www.domain.tld/req"
 URL_WITH_PATH = URL(URL_WITH_PATH_STR)
+URL_WITH_LONGER_PATH = URL("http://www.domain.tld/req/req/req")
+URL_WITH_LONG_PATH = URL("http://www.domain.tld/" + "req/" * 30)
+URL_WITH_VERY_LONG_PATH = URL("http://www.domain.tld/" + "req/" * 100)
 REL_URL = URL("/req")
 QUERY_SEQ = {str(i): tuple(str(j) for j in range(10)) for i in range(10)}
 SIMPLE_QUERY = {str(i): str(i) for i in range(10)}
@@ -574,6 +577,20 @@ def _run() -> None:
             URL_WITH_PATH.parent
 
 
+def test_relative_to(benchmark: BenchmarkFixture) -> None:
+    @benchmark
+    def _run() -> None:
+        for _ in range(100):
+            URL_WITH_LONGER_PATH.relative_to(URL_WITH_PATH)
+
+
+def test_relative_to_long_urls(benchmark: BenchmarkFixture) -> None:
+    @benchmark
+    def _run() -> None:
+        for _ in range(100):
+            URL_WITH_VERY_LONG_PATH.relative_to(URL_WITH_LONG_PATH)
+
+
 def test_url_join(benchmark: "BenchmarkFixture") -> None:
     @benchmark
     def _run() -> None:

yarl/_path.py

@@ -39,3 +39,27 @@ def normalize_path(path: str) -> str:
 
     segments = path.split("/")
     return prefix + "/".join(normalize_path_segments(segments))
+
+
+def calculate_relative_path(target: str, base: str) -> str:
+    """Calculate the relative path between two other paths"""
+
+    base_segments = base.rstrip("/").split("/")
+    target_segments = target.rstrip("/").split("/")
+
+    offset = 0
+    for base_seg, target_seg in zip(base_segments, target_segments):
+        if base_seg != target_seg:
+            break
+        offset += 1
+
+    remaining_base_segments = base_segments[offset:]
+    remaining_target_segments = target_segments[offset:]
+
+    relative_segments = [".."] * len(remaining_base_segments)
+    relative_segments.extend(remaining_target_segments)
+
+    relative = "/".join(relative_segments) or "."
+    trailing_slashes = target[len(target.rstrip("/")) :]
+
+    return relative + trailing_slashes if len(trailing_slashes) > 1 else relative

yarl/_url.py

@@ -21,7 +21,7 @@
     split_url,
     unsplit_result,
 )
-from ._path import normalize_path, normalize_path_segments
+from ._path import calculate_relative_path, normalize_path, normalize_path_segments
 from ._query import (
     Query,
     QueryVariable,
@@ -1387,6 +1387,34 @@ def with_suffix(
         fragment = self._fragment if keep_fragment else ""
         return from_parts(self._scheme, netloc, "/".join(parts), query, fragment)
 
+    def relative_to(self, other: object) -> "URL":
+        """Return a new URL with a relative path between two other URL objects.
+
+        Note that both URLs must have the same scheme and netloc.
+
+        Example:
+        >>> target = URL("http://example.com/path/to")
+        >>> base = URL("http://example.com/")
+        >>> target.relative_to(base)
+        URL('path/to')
+        >>> base.relative_to(target)
+        URL('../..')
+        """
+
+        if type(other) is not URL:
+            raise TypeError("other should be URL")
+
+        target_scheme, target_netloc, target_path, _, _ = self._val
+        base_scheme, base_netloc, base_path, _, _ = 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 = calculate_relative_path(target_path, base_path)
+        return from_parts("", "", path, "", "")
+
     def join(self, url: "URL") -> "URL":
         """Join URLs