feat: Add dynamic port binding to TCPSite

[rodrigobnogueira]

What do these changes do?

This PR continues #10697 by @twhittock-disguise, adding a port property to web.TCPSite that returns the dynamically assigned port when the site is created with port=0.

Key changes:

• Introduced _bound_port to track the actual runtime port without mutating _port (addressing @webknjaz's feedback).
• The port property returns _bound_port after start(), or the requested _port before that.
• Updated name property to use self.port so logging reflects the real bound port.
• Updated examples/fake_server.py to use port=0 + site.port instead of the race-prone unused_port() helper.
• Added documentation in docs/web_advanced.rst and docs/web_reference.rst.
• Added test_tcpsite_ephemeral_port in tests/test_web_runner.py.

Are there changes in behavior for the user?

Yes. Users can now retrieve the actual bound port via site.port after calling await site.start(). This is especially useful when port=0 is used for ephemeral port allocation. Previously, users had to resort to the internal site._server.sockets[0].getsockname()[1] hack.

Is it a substantial burden for the maintainers to support this?

No. This is a small, self-contained change to TCPSite that adds a read-only property backed by a single new slot (_bound_port). It does not change any existing public API or break backward compatibility. The maintenance cost is minimal.

Related issue number

Fixes #10665
Continues #10697

Checklist

• I think the code is well written
• Unit tests for the changes exist
• Documentation reflects the changes
• If you provide code modification, please add yourself to CONTRIBUTORS.txt
• Add a new news fragment into the CHANGES/ folder

[codspeed-hq]

Merging this PR will not alter performance

✅ 59 untouched benchmarks

---

_{Comparing rodrigobnogueira:dynamic-ports-finish (c0b0f83) with master (c1981ef)}

[webknjaz]

CHANGES.rst aren't supposed to be edited in PRs, nor manually. It's updated as a part of the release process by a tool called Towncrier.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.78%. Comparing base (c1981ef) to head (c0b0f83).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master   #12167   +/-   ##
=======================================
  Coverage   98.77%   98.78%           
=======================================
  Files         128      128           
  Lines       45321    45342   +21     
  Branches     2405     2407    +2     
=======================================
+ Hits        44768    44789   +21     
  Misses        393      393           
  Partials      160      160           

Flag	Coverage Δ
CI-GHA	98.63% <100.00%> (+<0.01%)	⬆️
OS-Linux	98.38% <100.00%> (+<0.01%)	⬆️
OS-Windows	96.75% <100.00%> (+<0.01%)	⬆️
OS-macOS	97.63% <100.00%> (+<0.01%)	⬆️
Py-3.10.11	97.19% <100.00%> (+<0.01%)	⬆️
Py-3.10.19	97.66% <100.00%> (+<0.01%)	⬆️
Py-3.11.14	97.86% <100.00%> (+<0.01%)	⬆️
Py-3.11.9	97.39% <100.00%> (+<0.01%)	⬆️
Py-3.12.10	97.48% <100.00%> (-0.01%)	⬇️
Py-3.12.12	97.95% <100.00%> (+<0.01%)	⬆️
Py-3.13.12	98.20% <100.00%> (+<0.01%)	⬆️
Py-3.14.3	98.16% <100.00%> (+<0.01%)	⬆️
Py-3.14.3t	97.26% <100.00%> (-0.01%)	⬇️
Py-pypy3.11.13-7.3.20	97.30% <100.00%> (+<0.01%)	⬆️
VM-macos	97.63% <100.00%> (+<0.01%)	⬆️
VM-ubuntu	98.38% <100.00%> (+<0.01%)	⬆️
VM-windows	96.75% <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.