set demos as console scripts, update chat instructions

Author: pacrob

docs/examples.chat.rst

@@ -1,18 +1,33 @@
 Chat Demo
 =========
 
-Copy the code below into a file called ``chat.py``.
-Install dependencies, preferably in a virtual environment, with:
+This example demonstrates how to create a simple chat application using libp2p.
 
-.. code-block:: bash
+.. code-block:: console
 
-    python -m pip install libp2p
+    $ python -m pip install libp2p
+    Collecting libp2p
+    ...
+    Successfully installed libp2p-x.x.x
+    $ chat-demo
+    Run this from the same folder in another console:
 
+    chat-demo -p 8001 -d /ip4/127.0.0.1/tcp/8000/p2p/QmPouApKqyxJDy6YT21EXNS6efuNzvJ3W3kqRQxkQ77GFJ
 
-Run the demo with ``python chat.py`` and copy the output.
+    Waiting for incoming connection...
 
-Open a second terminal, navigate to the folder that contains ``chat.py``, then paste
-and run the copied line.
+Copy the line that starts with ``chat-demo -p 8001``, open a new terminal in the same
+folder and paste it in:
+
+.. code-block:: console
+
+    $ chat-demo -p 8001 -d /ip4/127.0.0.1/tcp/8000/p2p/QmPouApKqyxJDy6YT21EXNS6efuNzvJ3W3kqRQxkQ77GFJ
+    Connected to peer /ip4/127.0.0.1/tcp/8000
+
+You can then start typing messages in either terminal and see them relayed to the
+other terminal. To exit the demo, send a keyboard interrupt (``Ctrl+C``) in either terminal.
+
+The full source code for this example is below:
 
 .. literalinclude:: ../examples/chat/chat.py
     :language: python

docs/examples.echo.rst

@@ -1,17 +1,32 @@
 Echo Demo
 =========
 
-Copy the code below into a file called ``demo.py``.
-Install dependencies, preferably in a virtual environment, with:
+This example demonstrates a simple ``echo`` protocol.
 
-.. code-block:: bash
+.. code-block:: console
 
-    python -m pip install libp2p
+    $ python -m pip install libp2p
+    Collecting libp2p
+    ...
+    Successfully installed libp2p-x.x.x
+    $ echo-demo
+    Run this from the same folder in another console:
 
-Run the demo with ``python echo.py`` and copy the output.
+    echo-demo -p 8001 -d /ip4/127.0.0.1/tcp/8000/p2p/16Uiu2HAmAsbxRR1HiGJRNVPQLNMeNsBCsXT3rDjoYBQzgzNpM5mJ
 
-Open a second terminal, navigate to the folder that contains ``echo.py``, then paste
-and run the copied line.
+    Waiting for incoming connection...
+
+Copy the line that starts with ``echo-demo -p 8001``, open a new terminal in the same
+folder and paste it in:
+
+.. code-block:: console
+
+    $ echo-demo -p 8001 -d /ip4/127.0.0.1/tcp/8000/p2p/16Uiu2HAmAsbxRR1HiGJRNVPQLNMeNsBCsXT3rDjoYBQzgzNpM5mJ
+
+    I am 16Uiu2HAmE3N7KauPTmHddYPsbMcBp2C6XAmprELX3YcFEN9iXiBu
+    Sent: hi, there!
+
+    Got: hi, there!
 
 .. literalinclude:: ../examples/echo/echo.py
     :language: python

docs/examples.ping.rst

@@ -1,17 +1,31 @@
 Ping Demo
 =========
 
-Copy the code below into a file called ``ping.py``.
-Install dependencies, preferably in a virtual environment, with:
+This example demonstrates how to use the libp2p ``ping`` protocol.
 
-.. code-block:: bash
+.. code-block:: console
 
-    python -m pip install libp2p
+    $ python -m pip install libp2p
+    Collecting libp2p
+    ...
+    Successfully installed libp2p-x.x.x
+    $ ping-demo
+    Run this from the same folder in another console:
 
-Run the demo with ``python ping.py`` and copy the output.
+    ping-demo -p 8001 -d /ip4/127.0.0.1/tcp/8000/p2p/QmXfptdHU6hqG95JswxYVUH4bphcK8y18mhFcgUQFe6fCN
 
-Open a second terminal, navigate to the folder that contains ``ping.py``, then paste
-and run the copied line.
+    Waiting for incoming connection...
+
+Copy the line that starts with ``ping-demo -p 8001``, open a new terminal in the same
+folder and paste it in:
+
+.. code-block:: console
+
+    $ ping-demo -p 8001 -d /ip4/127.0.0.1/tcp/8000/p2p/QmXfptdHU6hqG95JswxYVUH4bphcK8y18mhFcgUQFe6fCN
+    sending ping to QmXfptdHU6hqG95JswxYVUH4bphcK8y18mhFcgUQFe6fCN
+    received pong from QmXfptdHU6hqG95JswxYVUH4bphcK8y18mhFcgUQFe6fCN
+
+The full source code for this example is below:
 
 .. literalinclude:: ../examples/echo/echo.py
     :language: python

docs/examples.rst

@@ -1,23 +1,10 @@
 Examples
 ========
 
-These are functional demonstrations of aspects of the library. They are
-intended to be run as scripts, and are not intended to be used as part of
-another application.
-
-Example Scripts
----------------
+These are functional demonstrations of aspects of the library.
 
 .. toctree::
 
     examples.chat
     examples.echo
     examples.ping
-
-Module contents
----------------
-
-.. automodule:: examples
-    :members:
-    :undoc-members:
-    :show-inheritance:

examples/chat/chat.py

@@ -54,7 +54,7 @@ async def stream_handler(stream: INetStream) -> None:
 
             print(
                 "Run this from the same folder in another console:\n\n"
-                f"python chat.py -p {int(port) + 1} "
+                f"chat-demo -p {int(port) + 1} "
                 f"-d /ip4/{localhost_ip}/tcp/{port}/p2p/{host.get_id().pretty()}\n"
             )
             print("Waiting for incoming connection...")

examples/echo/echo.py

@@ -53,7 +53,7 @@ async def run(port: int, destination: str, seed: int = None) -> None:
 
             print(
                 "Run this from the same folder in another console:\n\n"
-                f"python echo.py -p {int(port) + 1} "
+                f"echo-demo -p {int(port) + 1} "
                 f"-d /ip4/{localhost_ip}/tcp/{port}/p2p/{host.get_id().pretty()}\n"
             )
             print("Waiting for incoming connections...")

examples/ping/ping.py

@@ -65,7 +65,7 @@ async def run(port: int, destination: str) -> None:
 
             print(
                 "Run this from the same folder in another console:\n\n"
-                f"python ping.py -p {int(port) + 1} "
+                f"ping-demo -p {int(port) + 1} "
                 f"-d /ip4/{localhost_ip}/tcp/{port}/p2p/{host.get_id().pretty()}\n"
             )
             print("Waiting for incoming connection...")

newsfragments/490.feature.rst

@@ -0,0 +1 @@
+Create entry points for demos to be run directly from installed package

setup.py

@@ -111,4 +111,11 @@
         "Programming Language :: Python :: 3.12",
     ],
     platforms=["unix", "linux", "osx"],
+    entry_points={
+        "console_scripts": [
+            "chat-demo=examples.chat.chat:main",
+            "echo-demo=examples.echo.echo:main",
+            "ping-demo=examples.ping.ping:main",
+        ],
+    },
 )