Update Documentation: Correct Example for Running ping

[seetadev]

Summary

The ping example in the py-libp2p documentation (please visit https://py-libp2p.readthedocs.io/en/latest/examples.ping.html ) does not work when libp2p is installed via PyPI using python -m pip install libp2p. This is because the PyPI version does not include the ping functionality. To replicate the issue, install libp2p via PyPI and attempt to run the ping example; it will result in an error.

Steps to Replicate:

1. Install libp2p via PyPI:

   python -m pip install libp2p

2. Try running the ping example:

   python examples/ping/ping.py

3. The command will fail because the ping functionality is missing in the PyPI version.

Current workflow to run ping example successfully
Install libp2p directly from the GitHub repository to get the latest version, which includes ping:

python -m pip install git+https://github.com/libp2p/py-libp2p.git

Expected behavior

When following the instructions in the documentation, running the ping example should work without issues. Specifically:

1. After installing libp2p via the documented command:

   python -m pip install libp2p

2. Running the ping example with:

   python examples/ping/ping.py

The ping example should successfully execute, allowing nodes to ping each other and display the expected output, such as the successful exchange of ping messages between nodes.

Actual behavior

When installing libp2p via PyPI using the command:

python -m pip install libp2p

and then running the ping example with:

python examples/ping/ping.py

the command fails because the ping functionality is not included in the PyPI version of libp2p. This results in an error, such as:

ModuleNotFoundError: No module named 'libp2p.ping'

This error occurs because the version of libp2p available on PyPI does not contain the ping feature, which is only available in the latest version on GitHub.

Relevant log output

ModuleNotFoundError: No module named 'libp2p.ping'

Possible Solution

The issue arises because the version of libp2p available on PyPI is outdated and does not include the ping functionality. To resolve this, the following steps are recommended:

1. Update the Documentation:
   Change the installation instructions in the ping example documentation to recommend installing libp2p directly from the GitHub repository, which contains the latest code:

   python -m pip install git+https://github.com/libp2p/py-libp2p.git

   This ensures users get the latest version, which includes the ping functionality.

2. Publish an Updated Version to PyPI:
   Push the latest version of libp2p to PyPI so that the ping functionality is available when users install via:

   python -m pip install libp2p

3. Add a Note to the Documentation:
   Include a note explaining that the PyPI version might not always contain the latest features and suggest installing from GitHub for the most up-to-date functionality.

Environment

No response

Would you like to work on fixing this bug ?

Yes

[pacrob]

I've just released a version 0.2.1 which will have the ping example included.

The instructions on how to run a demo are kind of clunky, so I've started PR #490 to make the interface nicer and the docs more explicit.

I'd rather just have instructions using pip install libp2p if at all possible, rather than pointing to a pip install git+... line. This kind of problem (docs pointing to a non-existent demo) should be relatively rare, and wouldn't be a problem at all if I can stick to a better release schedule 😅

If you'd like to add to that PR, you're welcome.

[seetadev]

@pacrob : Congrats on the 0.2.1 release — it’s great to see the ping example included! This is a fantastic addition and will really help developers understand and test basic functionality more easily. 🎉

I appreciate the effort you’re putting into PR #490 to streamline the interface and improve the documentation. Making the demo instructions clearer and more intuitive is a big win, and simplifying it to a clean pip install libp2p approach sounds like the right direction. Moving away from pip install git+... will definitely make onboarding smoother and reduce potential confusion for newer contributors.

I totally understand the challenge of keeping a consistent release schedule — it’s a tough balancing act. Regardless, your work to improve the process and minimize these issues is greatly appreciated.

I’d be happy to take a look at PR #490 and contribute where I can. Let me know if there are any specific areas you'd like help with, whether it’s refining instructions, adding examples, or testing out the changes.

Thanks for your great work on py-libp2p — it’s exciting to see the project evolving and becoming more accessible! 🚀