eg/870-add-circuit-relay-dcutr-autonat-demonstration (libp2p#975)

* added layout of full nat traversal example

* refactored circuit relay module to accept reservation

* fixed DCUtRs false positive connection

* Fix linting, type checking, test failures, and documentation issues

- Fix AutoNATService type mismatch by casting IHost to BasicHost
- Add type: ignore comments for raw_conn attribute access (implementation-specific)
- Fix stream handler type mismatch in listener.py with proper casting
- Fix all line length violations (E501) by breaking long lines
- Remove unused variable listener_peer_info
- Fix docstring format (D301) by using raw string for backslashes
- Fix DCUtR test failures by restoring cache trust in _have_direct_connection
- Add examples.nat to documentation toctree to fix build warning

All linting, type checking, tests, and documentation builds now pass.

* added newsfragement

---------

Co-authored-by: Manu Sheel Gupta <[email protected]>
Co-authored-by: acul71 <[email protected]>

Author: 3 people

docs/examples.nat.rst

@@ -0,0 +1,37 @@
+examples.nat package
+====================
+
+Submodules
+----------
+
+examples.nat.dialer module
+--------------------------
+
+.. automodule:: examples.nat.dialer
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+examples.nat.listener module
+----------------------------
+
+.. automodule:: examples.nat.listener
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+examples.nat.relay module
+-------------------------
+
+.. automodule:: examples.nat.relay
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: examples.nat
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/examples.rst

@@ -17,6 +17,7 @@ Examples
    examples.circuit_relay
    examples.kademlia
    examples.mDNS
+   examples.nat
    examples.rendezvous
    examples.random_walk
    examples.multiple_connections

examples/nat/__init__.py

@@ -0,0 +1,13 @@
+"""
+NAT Traversal Examples for py-libp2p
+
+This package contains examples demonstrating NAT traversal using:
+- Circuit Relay v2: Relay connections through publicly reachable nodes
+- DCUtR: Direct Connection Upgrade through Relay (hole punching)
+- AutoNAT: Automatic NAT detection and reachability assessment
+
+Examples:
+- relay.py: Publicly reachable relay node
+- listener.py: NAT'd node that advertises via relay
+- dialer.py: NAT'd node that connects via relay and attempts hole punching
+"""