Add the URL subtraction feature

[babieiev]

What do these changes do?

Rework of the URL subtraction feature (added in #1340; removed in #1391)

Are there changes in behavior for the user?

Being able to calculate the relative path between two URLs:

from yarl import URL

target_url = URL("http://example.com/path/index.html")
base_url = URL("http://example.com/path/")

relative_url = target_url.relative_to(base_url)

print(relative_url)  # output: "index.html"

As suggested in #1392 (review), the idea is (temporarily?) implemented as a regular method, not a subtraction operator.

Related issue number

Resolves #1183

Checklist

• I think the code is well written
• Unit tests for the changes exist
• Documentation reflects the changes

Known issues

• Time complexity is roughly O(base_path_segments * target_path_segments)
• Empty segments are not handled correctly Reduce time complexity of URL subtraction #1388
• Potentially handling special cases with leading/trailing slashes Reduce time complexity of URL subtraction #1388

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.58%. Comparing base (376ea74) to head (df318fa).

❌ Your project check has failed because the head coverage (97.98%) is below the target coverage (100.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1538   +/-   ##
=======================================
  Coverage   99.57%   99.58%           
=======================================
  Files          29       29           
  Lines        5881     5978   +97     
  Branches      266      271    +5     
=======================================
+ Hits         5856     5953   +97     
  Misses         21       21           
  Partials        4        4           

Flag	Coverage Δ
CI-GHA	99.58% <100.00%> (+<0.01%)	⬆️
MyPy	97.98% <100.00%> (+0.03%)	⬆️
OS-Linux	99.80% <100.00%> (+<0.01%)	⬆️
OS-Windows	99.48% <100.00%> (+<0.01%)	⬆️
OS-macOS	99.68% <100.00%> (+<0.01%)	⬆️
Py-3.10.11	99.46% <100.00%> (+<0.01%)	⬆️
Py-3.10.19	99.70% <100.00%> (+<0.01%)	⬆️
Py-3.11.14	99.70% <100.00%> (+<0.01%)	⬆️
Py-3.11.9	99.46% <100.00%> (+<0.01%)	⬆️
Py-3.12.10	99.46% <100.00%> (+<0.01%)	⬆️
Py-3.12.12	99.70% <100.00%> (+<0.01%)	⬆️
Py-3.13.9	99.75% <100.00%> (+<0.01%)	⬆️
Py-3.13.9t	99.75% <100.00%> (+<0.01%)	⬆️
Py-3.14.0	99.75% <100.00%> (+<0.01%)	⬆️
Py-3.14.0t	99.75% <100.00%> (+<0.01%)	⬆️
Py-3.9.13	99.41% <100.00%> (+<0.01%)	⬆️
Py-3.9.25	99.65% <100.00%> (+<0.01%)	⬆️
Py-pypy3.10.16-7.3.19	99.36% <100.00%> (+<0.01%)	⬆️
Py-pypy3.9.19-7.3.16	99.34% <100.00%> (+<0.01%)	⬆️
VM-macos-latest	99.68% <100.00%> (+<0.01%)	⬆️
VM-ubuntu-latest	99.80% <100.00%> (+<0.01%)	⬆️
VM-windows-latest	99.48% <100.00%> (+<0.01%)	⬆️
pytest	99.80% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[codspeed-hq]

CodSpeed Performance Report

Merging #1538 will not alter performance

_{Comparing babieiev:url-subtraction (df318fa) with master (376ea74)}

Summary

✅ 99 untouched
🆕 2 new

Benchmarks breakdown

	Benchmark	BASE	HEAD	Change
🆕	test_relative_to	N/A	840.9 µs	N/A
🆕	test_relative_to_long_urls	N/A	4.6 ms	N/A

[commonism]

+1 for making it look trivial

[babieiev]

@webknjaz @bdraco
Hi everyone! Just a friendly reminder about this PR, which has been pending for a while (about half a year 😅). I've just brought it up to date with the main branch. If anyone has a moment to review it, I’d really appreciate it.

P.S. The failing checks are unrelated to my changes.

[bdraco]

I added this one to my review queue. Sadly its a ~400 PRs deep right now. I'm hoping to dig myself out of the hole during the holiday at the end of the month

[babieiev]

Oof, 400 PRs… Anyway, thanks for the update! Hope you get some breathing room soon 🥲