Examples: Reorganize example scripts into subdirectories

[ChayanDass]

What was wrong?

Issue #1219

Several example scripts lived in the root examples/ directory instead of being grouped with related examples in subdirectories (e.g. examples/websocket/, examples/tls/). This made the layout inconsistent and harder to navigate.

How was it fixed?

• WebSocket demos → examples/websocket/: browser_wss_demo.py, proxy_websocket_demo.py, websocket_comprehensive_demo.py, wss_demo.py
• TLS demo → examples/tls/: tls_listener_dialer_demo.py
• TCP test → new examples/tcp/: test_tcp_data_transfer.py
• Transport demo → new examples/transport/: transport_integration_demo.py

Removed duplicate copies from examples/ root. Updated in-file path references and printed run instructions to the new paths.

To-Do

• Clean up commit history
• Add or update documentation related to these changes
• Add entry to the release notes

Cute Animal Picture

[acul71]

Hello @ChayanDass, thanks for this PR. The reorganization matches issue #1219 and the updated paths in docstrings look good. The following items are required before merge.

---

Required before merge

1. Newsfragment (blocker)

Per project policy, every PR that references an issue needs a newsfragment. Right now there is none for #1219.

• Add: newsfragments/1219.misc.rst (or 1219.internal.rst if you prefer).
• Content (ReST, user-facing): e.g.
  Reorganized example scripts from the root examples/ directory into subdirectories (e.g. examples/websocket/, examples/tls/, examples/tcp/, examples/transport/). Updated in-file usage and run instructions to the new paths.
• Detail: File must end with a newline. See newsfragments/README.md for the full format.

Until this is added, the PR cannot be approved.

2. Add __init__.py to the new/moved example dirs

So that these example dirs are proper packages (like examples/identify and examples/tls), please add an empty __init__.py in:

• examples/websocket/
• examples/tcp/
• examples/transport/

That allows running from repo root as e.g. python -m examples.websocket.wss_demo and keeps the layout consistent with the rest of the examples.

3. Confirm moved examples still run

After removing the sys.path hack from transport_integration_demo.py, please confirm all moved examples still work from repo root (e.g. after pip install -e .):

• websocket: browser_wss_demo.py, proxy_websocket_demo.py, websocket_comprehensive_demo.py, wss_demo.py — e.g. python examples/websocket/wss_demo.py
• tls: tls_listener_dialer_demo.py — e.g. python examples/tls/tls_listener_dialer_demo.py listener
• tcp: test_tcp_data_transfer.py — e.g. python examples/tcp/test_tcp_data_transfer.py or pytest examples/tcp/test_tcp_data_transfer.py -v
• transport: transport_integration_demo.py — e.g. python examples/transport/transport_integration_demo.py

Please add a short note in the PR (or a screenshot/log snippet) showing they run.

4. Proxy demo log on one line

In examples/websocket/proxy_websocket_demo.py (around lines 129–131): the logged proxy test command is split across two strings, so copy-paste can include an extra newline. Use a single f-string (or concatenation) so the full command appears on one line in the log.

---

Summary

Item	Status
Newsfragment for #1219	Required
__init__.py in websocket, tcp, transport	Required
Note/screenshot that moved examples run	Required
Proxy demo log on one line	Required

Docs and paths look correct; no doc changes needed for the moved scripts.

---

Why __init__.py? (quick background)

So you’re not just adding empty files blindly: in Python, a directory is only treated as a package (and thus importable) if it contains an __init__.py file. The root examples/__init__.py is what makes the whole examples tree a package.

• Entry points: In pyproject.toml we have console scripts like identify-demo = "examples.identify.identify:main". For that to work, both examples and examples.identify must be importable packages — so each of those directories needs an __init__.py.
• Sphinx docs: The docs use .. automodule:: examples.identify, .. automodule:: examples.tls, etc. Sphinx imports those modules; without the package layout, that would fail.
• Run as module: From the repo root you can run python -m examples.websocket.wss_demo only if examples and examples.websocket are packages (each with an __init__.py). Without it, Python doesn’t treat those folders as packages and the -m form fails.

So every example subdirectory that we want to use as a package (for entry points, docs, or python -m) needs an __init__.py. The file can be empty — it just marks the directory as a package. Adding empty __init__.py in websocket, tcp, and transport makes them consistent with identify, tls, and the rest of the examples.

Thanks again.

[ChayanDass]

Final PR Review Report: #1222 (Example Reorganization)

All reviewer requirements have been satisfied. This includes organizational changes, package infrastructure, specific code fixes, and verified execution of all moved examples.

✅ Reviewer Checklist Status

Requirement	Status	Verification Detail
1. Newsfragment	✅ Done	Added 1219.misc.rst
2. package layout	✅ Done	Added init.py to websocket/, tcp/, and transport/.
3. Moved examples run	✅ Verified	All 7 staged examples tested from repo root (see below).
4. Proxy log fix	✅ Fixed	proxy_websocket_demo.py log line merged.

---

🚀 Verification Proof (Execution Logs)

Below are the snippets showing that the moved examples run correctly from the root directory using the new paths.

📁 TCP: Data Transfer (pytest)

$ pytest examples/tcp/test_tcp_data_transfer.py -v
================== test session starts ==================
examples/tcp/test_tcp_data_transfer.py::test_tcp_basic_connection PASSED [ 25%]
examples/tcp/test_tcp_data_transfer.py::test_tcp_data_transfer PASSED [ 50%]
examples/tcp/test_tcp_data_transfer.py::test_tcp_large_data_transfer PASSED [ 75%]
examples/tcp/test_tcp_data_transfer.py::test_tcp_bidirectional_transfer PASSED [100%]
=================== 4 passed in 0.63s ===================

📁 TLS: Listener/Dialer Demo

$ python examples/tls/tls_listener_dialer_demo.py listener &
$ python examples/tls/tls_listener_dialer_demo.py dialer /ip4/0.0.0.0/tcp/8000/p2p/Qm...
Connected to Qm...
Sending: ping
Got reply: b'pong'
Listener running at: /ip4/0.0.0.0/tcp/8000/p2p/Qm...
Waiting for ping requests on protocol: "/tls/ping/1.0.0"

📁 Transport: Integration Demo

$ python examples/transport/transport_integration_demo.py
Supported transport protocols: ['tcp', 'ws', 'wss', 'quic', 'quic-v1']
✅ Created TCP transport: TCP
✅ Created WebSocket transport: WebsocketTransport
✅ /ip4/127.0.0.1/tcp/8080/ws -> WebsocketTransport
🚀 The transport system is now ready for production use!

📁 WebSocket: Secure/Proxy/Comprehensive

** uses logger , not gettinng log in terminal , but working propely

📁 wss Demo

 python examples/websocket/wss_demo.py 
DEBUG: Server mode selected
🌐 WSS Server Started Successfully!
==================================================
📍 Server Address: /ip4/127.0.0.1/tcp/8443/wss/p2p/16Uiu2HAm6cQqXV6WNbhCiaVx9iFC4NjHCUK3Ly8ektuTRXU46PZ4
🔧 Protocol: /echo/1.0.0
🚀 Transport: WebSocket Secure (WSS)
🔐 Security: TLS with self-signed certificate

📋 To test the connection, run this in another terminal:
   python examples/websocket/wss_demo.py -d /ip4/127.0.0.1/tcp/8443/wss/p2p/16Uiu2HAm6cQqXV6WNbhCiaVx9iFC4NjHCUK3Ly8ektuTRXU46PZ4

⏳ Waiting for incoming WSS connections...
──────────────────────────────────────────────────

---

🗂️ Modified Files Summary

• [NEW] 1219.misc.rst
• [NEW] examples/websocket/init.py
• [NEW] examples/tcp/init.py
• [NEW] examples/transport/init.py
• [MODIFY] proxy_websocket_demo.py (Fix log line)
• [MODIFY] browser_wss_demo.py (Fix URL 404s & logs)
• [MODIFY] wss_demo.py (Fix terminal log visibility)

PR #1222 is complete and verified according to the reviewer's specifications.