libp2p · acul71 · Mar 27, 2026 · Feb 20, 2026 · Mar 13, 2026 · Mar 13, 2026
diff --git a/docs/examples.path_handling.rst b/docs/examples.path_handling.rst
@@ -4,6 +4,8 @@ Path Handling Demo
 This example demonstrates how to use the cross-platform path utilities
 provided by :mod:`libp2p.utils.paths`.
 
+After installing py-libp2p (``pip install -e .`` from a checkout, or ``pip install libp2p``), you can run the demo as a console script or as a module:
+
 .. code-block:: console
 
     $ python -m pip install libp2p
@@ -12,8 +14,44 @@ provided by :mod:`libp2p.utils.paths`.
     Successfully installed libp2p-x.x.x
     $ path-handling
 
-The full source code for this example is below:
+From a source checkout you can also run:
+
+.. code-block:: console
+
+    $ python -m examples.path_handling.path_handling_demo
 
-.. literalinclude:: ../examples/path_handling.py
+The full source code for the implementation is below:
+
+.. literalinclude:: ../examples/path_handling/path_handling.py
     :language: python
     :linenos:
+
+API reference (Sphinx)
+----------------------
+
+Submodules
+~~~~~~~~~~
+
+examples.path\_handling.path\_handling module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: examples.path_handling.path_handling
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+examples.path\_handling.path\_handling\_demo module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: examples.path_handling.path_handling_demo
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Package contents
+~~~~~~~~~~~~~~~~
+
+.. automodule:: examples.path_handling
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -26,6 +26,8 @@ Examples
    gossipsub-1.2
    examples.websocket
    examples.tls
+   examples.tcp
+   examples.transport
    examples.autotls
    examples.perf
    examples.path_handling
diff --git a/docs/examples.tcp.rst b/docs/examples.tcp.rst
@@ -0,0 +1,21 @@
+examples.tcp package
+====================
+
+Submodules
+----------
+
+examples.tcp.test\_tcp\_data\_transfer module
+---------------------------------------------
+
+.. automodule:: examples.tcp.test_tcp_data_transfer
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: examples.tcp
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/docs/examples.transport.rst b/docs/examples.transport.rst
@@ -0,0 +1,21 @@
+examples.transport package
+==========================
+
+Submodules
+----------
+
+examples.transport.transport\_integration\_demo module
+------------------------------------------------------
+
+.. automodule:: examples.transport.transport_integration_demo
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: examples.transport
+   :members:
+   :show-inheritance:
+   :undoc-members:
diff --git a/examples/path_handling/__init__.py b/examples/path_handling/__init__.py
diff --git a/examples/path_handling.py → examples/path_handling/path_handling.py b/examples/path_handling.py → examples/path_handling/path_handling.py
@@ -70,9 +70,9 @@ def main() -> None:
     except Exception as e:
         logging.error(f"Failed to create or use temp file: {e}")
 
-    # Resolve a relative path from the script directory
+    # Resolve a relative path from the script directory (repo root README)
     try:
-        rel_path: Path = resolve_relative_path(script_dir, "../README.md")
+        rel_path: Path = resolve_relative_path(script_dir, "../../README.md")
         if rel_path.exists():
             logging.info(f"Resolved README.md path: {rel_path}")
         else:

diff --git a/examples/path_handling/path_handling_demo.py b/examples/path_handling/path_handling_demo.py
@@ -0,0 +1,12 @@
+"""
+Entry point for the path handling demo.
+
+This allows running the example as a CLI tool via
+`python -m examples.path_handling.path_handling_demo` or as a console script
+(path-handling) if registered in pyproject.toml.
+"""
+
+from examples.path_handling.path_handling import main
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/path_handling_demo.py b/examples/path_handling_demo.py
diff --git a/examples/tcp/__init__.py b/examples/tcp/__init__.py
diff --git a/examples/test_tcp_data_transfer.py → examples/tcp/test_tcp_data_transfer.py b/examples/test_tcp_data_transfer.py → examples/tcp/test_tcp_data_transfer.py
@@ -4,6 +4,10 @@
 
 This test proves that TCP peer-to-peer data transfer works correctly in libp2p.
 This serves as a baseline to compare with WebSocket tests.
+
+Usage:
+    python examples/tcp/test_tcp_data_transfer.py
+    pytest examples/tcp/test_tcp_data_transfer.py -v
 """
 
 import pytest

diff --git a/examples/tls_listener_dialer_demo.py → examples/tls/tls_listener_dialer_demo.py b/examples/tls_listener_dialer_demo.py → examples/tls/tls_listener_dialer_demo.py
@@ -3,9 +3,9 @@
 TLS Listener and Dialer Demo with "ping-pong" test.
 
 Usage:
-    python examples/tls_listener_dialer_demo.py listener [port]
-    python examples/tls_listener_dialer_demo.py dialer <listener_address>
-    python examples/tls_listener_dialer_demo.py
+    python examples/tls/tls_listener_dialer_demo.py listener [port]
+    python examples/tls/tls_listener_dialer_demo.py dialer <listener_address>
+    python examples/tls/tls_listener_dialer_demo.py
 """
 
 import sys

diff --git a/examples/transport/__init__.py b/examples/transport/__init__.py
diff --git a/examples/transport_integration_demo.py → ...s/transport/transport_integration_demo.py b/examples/transport_integration_demo.py → ...s/transport/transport_integration_demo.py
@@ -7,18 +7,15 @@
 2. How to create transports dynamically based on multiaddrs
 3. How to register custom transports
 4. How the new system automatically selects the right transport
+
+Usage:
+    python examples/transport/transport_integration_demo.py
 """
 
 import logging
-from pathlib import Path
-import sys
-
-import trio
-
-# Add the libp2p directory to the path so we can import it
-sys.path.insert(0, str(Path(__file__).parent.parent))
 
 import multiaddr
+import trio
 
 from libp2p.transport import (
     create_transport,

diff --git a/examples/websocket/__init__.py b/examples/websocket/__init__.py
diff --git a/examples/browser_wss_demo.py → examples/websocket/browser_wss_demo.py b/examples/browser_wss_demo.py → examples/websocket/browser_wss_demo.py
@@ -5,6 +5,10 @@
 This example demonstrates browser-to-Python WebSocket connectivity using WSS.
 It creates a simple web server that serves an HTML page with JavaScript
 that connects to a libp2p WSS server.
+
+Usage:
+    python examples/websocket/browser_wss_demo.py
+    python examples/websocket/browser_wss_demo.py -p 8443 -w 8080
 """
 
 import argparse

diff --git a/examples/proxy_websocket_demo.py → examples/websocket/proxy_websocket_demo.py b/examples/proxy_websocket_demo.py → examples/websocket/proxy_websocket_demo.py
@@ -7,6 +7,11 @@
 - Proxy authentication
 - Connection through corporate firewalls
 - Production-ready proxy support
+
+Usage:
+    python examples/websocket/proxy_websocket_demo.py
+    python examples/websocket/proxy_websocket_demo.py -c <server_multiaddr>
+    python examples/websocket/proxy_websocket_demo.py -c <server_multiaddr> --proxy socks5://127.0.0.1:1080
 """
 
 import argparse
@@ -123,9 +128,11 @@ async def run_server(port: int):
         logger.info("🔒 Proxy: None (Direct connection)")
         logger.info("")
         logger.info("📋 To test with proxy, run:")
-        logger.info(
-            f"   python proxy_websocket_demo.py -c {client_addr} --proxy socks5://127.0.0.1:1080"
+        proxy_cmd = (
+            f"   python examples/websocket/proxy_websocket_demo.py -c {client_addr} "
+            "--proxy socks5://127.0.0.1:1080"
         )
+        logger.info(proxy_cmd)
         logger.info("")
         logger.info("⏳ Waiting for connections...")
         logger.info("─" * 50)

diff --git a/examples/websocket_comprehensive_demo.py → ...websocket/websocket_comprehensive_demo.py b/examples/websocket_comprehensive_demo.py → ...websocket/websocket_comprehensive_demo.py
@@ -8,6 +8,13 @@
 - Browser integration
 - Production-ready configuration
 - Real-world use cases
+
+Usage:
+    python examples/websocket/websocket_comprehensive_demo.py
+    python examples/websocket/websocket_comprehensive_demo.py -c <addr>
+    python examples/websocket/websocket_comprehensive_demo.py -c <addr> --wss
+    python examples/websocket/websocket_comprehensive_demo.py -c <addr>
+        --proxy <proxy_url>
 """
 
 import argparse
@@ -292,16 +299,18 @@ async def run_server(port: int, use_wss: bool = False, proxy_url: str | None = N
             logger.info("📋 To test the connection, run:")
             if use_wss:
                 logger.info(
-                    f"   python websocket_comprehensive_demo.py -c {client_addr} --wss"
+                    "   python examples/websocket/websocket_comprehensive_demo.py "
+                    f"-c {client_addr} --wss"
                 )
             else:
                 logger.info(
-                    f"   python websocket_comprehensive_demo.py -c {client_addr}"
+                    "   python examples/websocket/websocket_comprehensive_demo.py "
+                    f"-c {client_addr}"
                 )
             if proxy_url:
                 logger.info(
-                    f"   python websocket_comprehensive_demo.py -c {client_addr} "
-                    f"--proxy {proxy_url}"
+                    "   python examples/websocket/websocket_comprehensive_demo.py "
+                    f"-c {client_addr} --proxy {proxy_url}"
                 )
             logger.info("")
             logger.info("⏳ Waiting for connections...")

diff --git a/examples/wss_demo.py → examples/websocket/wss_demo.py b/examples/wss_demo.py → examples/websocket/wss_demo.py
@@ -7,6 +7,11 @@
 - Secure WebSocket connections (WSS)
 - Real-world certificate management
 - Browser-compatible WSS connections
+
+Usage:
+    python examples/websocket/wss_demo.py
+    python examples/websocket/wss_demo.py -p <port>
+    python examples/websocket/wss_demo.py -d <listener_multiaddr>
 """
 
 import argparse
@@ -204,7 +209,10 @@ async def run_server(port: int):
             print("🔐 Security: TLS with self-signed certificate", flush=True)
             print("", flush=True)
             print("📋 To test, run in another terminal:", flush=True)
-            print(f"   python wss_demo.py -d {client_addr}", flush=True)
+            print(
+                f"   python examples/websocket/wss_demo.py -d {client_addr}",
+                flush=True,
+            )
             print("", flush=True)
             print("⏳ Waiting for incoming WSS connections...", flush=True)
             print("─" * 50, flush=True)
@@ -330,10 +338,8 @@ def main():
     args = parser.parse_args()
 
     if args.destination:
-        # Client mode
         trio.run(run_client, args.destination)
     else:
-        # Server mode
         trio.run(run_server, args.port)
 
 

diff --git a/newsfragments/1219.misc.rst b/newsfragments/1219.misc.rst
@@ -0,0 +1 @@
+Reorganized example scripts from the root examples/ directory into subdirectories (e.g. examples/websocket/, examples/tls/, examples/tcp/, examples/transport/, examples/path_handling/). Updated in-file usage and run instructions; the path-handling demo is now ``python -m examples.path_handling.path_handling_demo`` (console script unchanged).
diff --git a/pyproject.toml b/pyproject.toml
@@ -76,7 +76,7 @@ mdns-demo = "examples.mDNS.mDNS:main"
 circuit-relay-demo = "examples.circuit_relay.relay_example:main"
 tls-demo = "examples.tls.example_tls_server:main"
 tls-client-demo = "examples.tls.example_tls_client:main"
-path-handling = "examples.path_handling_demo:main"
+path-handling = "examples.path_handling.path_handling_demo:main"
 oso-health-report = "libp2p.observability.oso.cli:main"
 
 [dependency-groups]
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Reorganized example scripts from the root examples/ directory into subdirectories (e.g. examples/websocket/, examples/tls/, examples/tcp/, examples/transport/, examples/path_handling/). Updated in-file usage and run instructions; the path-handling demo is now ``python -m examples.path_handling.path_handling_demo`` (console script unchanged).