From a72dbaa58da092683579f0a5e31637aed26793fa Mon Sep 17 00:00:00 2001 From: pacrob <5199899+pacrob@users.noreply.github.com> Date: Fri, 20 Dec 2024 13:23:04 -0700 Subject: [PATCH] set demos as console scripts, update chat instructions --- docs/examples.chat.rst | 29 ++++++++++++++++++++++------- docs/examples.echo.rst | 29 ++++++++++++++++++++++------- docs/examples.ping.rst | 28 +++++++++++++++++++++------- docs/examples.rst | 15 +-------------- examples/chat/chat.py | 2 +- examples/echo/echo.py | 2 +- examples/ping/ping.py | 2 +- newsfragments/490.feature.rst | 1 + setup.py | 7 +++++++ 9 files changed, 77 insertions(+), 38 deletions(-) create mode 100644 newsfragments/490.feature.rst diff --git a/docs/examples.chat.rst b/docs/examples.chat.rst index 728858b7..96e27d89 100644 --- a/docs/examples.chat.rst +++ b/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 diff --git a/docs/examples.echo.rst b/docs/examples.echo.rst index 12bd1eae..13b12fe8 100644 --- a/docs/examples.echo.rst +++ b/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 diff --git a/docs/examples.ping.rst b/docs/examples.ping.rst index a5af648f..625015c9 100644 --- a/docs/examples.ping.rst +++ b/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 diff --git a/docs/examples.rst b/docs/examples.rst index 91909d05..1574d968 100644 --- a/docs/examples.rst +++ b/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: diff --git a/examples/chat/chat.py b/examples/chat/chat.py index 6496f1dd..2b390a54 100755 --- a/examples/chat/chat.py +++ b/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...") diff --git a/examples/echo/echo.py b/examples/echo/echo.py index 75259843..24be3b16 100644 --- a/examples/echo/echo.py +++ b/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...") diff --git a/examples/ping/ping.py b/examples/ping/ping.py index 3ac65701..778deba0 100644 --- a/examples/ping/ping.py +++ b/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...") diff --git a/newsfragments/490.feature.rst b/newsfragments/490.feature.rst new file mode 100644 index 00000000..4b2270d8 --- /dev/null +++ b/newsfragments/490.feature.rst @@ -0,0 +1 @@ +Create entry points for demos to be run directly from installed package diff --git a/setup.py b/setup.py index fe301c42..59edb2af 100644 --- a/setup.py +++ b/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", + ], + }, )