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.64%. Comparing base (c050999) to head (fd5e4ee).
⚠️ Report is 7 commits behind head on master.

❌ Your project check has failed because the head coverage (98.11%) 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.63%   99.64%           
=======================================
  Files          29       29           
  Lines        5806     5903   +97     
  Branches      265      270    +5     
=======================================
+ Hits         5785     5882   +97     
  Misses         18       18           
  Partials        3        3           

Flag	Coverage Δ
CI-GHA	99.64% <100.00%> (+<0.01%)	⬆️
MyPy	98.11% <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.18	99.70% <100.00%> (+<0.01%)	⬆️
Py-3.11.13	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.11	99.70% <100.00%> (+<0.01%)	⬆️
Py-3.13.5	99.75% <100.00%> (+<0.01%)	⬆️
Py-3.13.5t	99.75% <100.00%> (+<0.01%)	⬆️
Py-3.9.13	99.41% <100.00%> (+<0.01%)	⬆️
Py-3.9.23	99.65% <100.00%> (+<0.01%)	⬆️
Py-pypy7.3.16	99.34% <100.00%> (+<0.01%)	⬆️
Py-pypy7.3.19	99.36% <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 (fd5e4ee) with master (c050999)}

Summary

✅ 101 untouched benchmarks
🆕 2 new benchmarks

Benchmarks breakdown

	Benchmark	BASE	HEAD	Change
🆕	test_relative_to	N/A	837.9 µs	N/A
🆕	test_relative_to_long_urls	N/A	4.5 ms	N/A

[commonism]

+1 for making it look trivial