Skip to content

Commit 32e427f

Browse files
seetadevseetadev
authored
Merge branch 'libp2p:main' into main
2 parents 7513f82 + 6054fd7 commit 32e427f

21 files changed

+1233
-57
lines changed

‎docs/contributing.rst

Lines changed: 199 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -5,39 +5,52 @@ Thank you for your interest in contributing! We welcome all contributions no mat
55
their size. Please read along to learn how to get started. If you get stuck, feel free
66
to ask for help in `Ethereum Python Discord server <https://discord.gg/GHryRvPB84>`_.
77

8-
Dependencies
9-
^^^^^^^^^^^^
8+
Setting the stage
9+
~~~~~~~~~~~~~~~~~
1010

11-
The following dependencies are needed to build py-libp2p:
11+
To get started, fork the repository to your own GitHub account, then clone it
12+
to your development machine:
1213

13-
* `GNU Multiprecision Arithmetic Library <https://gmplib.org/>`_
14-
* `CMake <https://cmake.org>`
15-
* `freedesktop.org pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config>`
14+
.. code:: sh
1615
17-
On Debian Linux you can install them using the following command:
16+
git clone [email protected]:your-github-username/py-libp2p.git
1817
19-
.. code:: sh
18+
Next, install the development dependencies and set up the project. We recommend using a
19+
virtual environment, such as `virtualenv <https://virtualenv.pypa.io/en/stable/>`_ or
20+
Python's built-in ``venv`` module. Instructions vary by platform:
2021

21-
sudo apt-get install cmake pkg-config libgmp-dev
22+
Linux Setup
23+
^^^^^^^^^^^
24+
25+
Prerequisites
26+
"""""""""""""
27+
28+
On Debian Linux, you need to install the following dependencies:
29+
30+
- `GNU Multiprecision Arithmetic Library <https://gmplib.org/>`_
31+
- `CMake <https://cmake.org>`_
32+
- `freedesktop.org pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config>`_
2233

23-
On MacOS, you can install them using the following command:
34+
Install them with:
2435

2536
.. code:: sh
2637
27-
brew install cmake pkgconfig gmp
38+
sudo apt-get install cmake pkg-config libgmp-dev
2839
29-
Setting the stage
30-
~~~~~~~~~~~~~~~~~
40+
Setup Steps
41+
"""""""""""
3142

32-
To get started, fork the repository to your own github account, then clone it
33-
to your development machine:
43+
Install the development dependencies using a virtual environment:
3444

3545
.. code:: sh
3646
37-
git clone [email protected]:your-github-username/py-libp2p.git
47+
cd py-libp2p
48+
python3 -m venv ./venv
49+
. venv/bin/activate
50+
python3 -m pip install -e ".[dev]"
51+
pre-commit install
3852
39-
Next, install the development dependencies. We recommend using a virtual
40-
environment, such as `virtualenv <https://virtualenv.pypa.io/en/stable/>`_.
53+
An alternative using ``virtualenv``:
4154

4255
.. code:: sh
4356
@@ -47,22 +60,140 @@ environment, such as `virtualenv <https://virtualenv.pypa.io/en/stable/>`_.
4760
python -m pip install -e ".[dev]"
4861
pre-commit install
4962
50-
An alternative to virtualenv is to use the built-in Python3 venv module:
63+
macOS Setup
64+
^^^^^^^^^^^
65+
66+
Prerequisites
67+
"""""""""""""
68+
69+
On macOS, you need to install the following dependencies:
70+
71+
- `GNU Multiprecision Arithmetic Library <https://gmplib.org/>`_
72+
- `CMake <https://cmake.org>`_
73+
- `freedesktop.org pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config>`_
74+
75+
Install them with:
76+
77+
.. code:: sh
78+
79+
brew install cmake pkgconfig gmp
80+
81+
Setup Steps
82+
"""""""""""
83+
84+
Install the development dependencies using a virtual environment:
85+
86+
.. code:: sh
87+
88+
cd py-libp2p
89+
python3 -m venv ./venv
90+
. venv/bin/activate
91+
python3 -m pip install -e ".[dev]"
92+
pre-commit install
93+
94+
On macOS, help the build command find and link against the ``gmp`` library:
5195

5296
.. code:: sh
5397
54-
cd py-libp2p
55-
python3 -m venv ./venv
56-
. venv/bin/activate
57-
python3 -m pip install -e ".[dev]"
58-
pre-commit install
98+
CFLAGS="`pkg-config --cflags gmp`" LDFLAGS="`pkg-config --libs gmp`" python3 -m pip install -e ".[dev]"
5999
60-
Currently, on MacOS you must help the build command find and link against the
61-
gmp library. On MacOS run the following to build py-libp2p:
100+
An alternative using ``virtualenv``:
62101

63102
.. code:: sh
64103
65-
CFLAGS="`pkg-config --cflags gmp`" LDFLAGS="`pkg-config --libs gmp`" python3 -m pip install -e ".[dev]"
104+
cd py-libp2p
105+
virtualenv -p python venv
106+
. venv/bin/activate
107+
python -m pip install -e ".[dev]"
108+
pre-commit install
109+
110+
Windows Development Setup
111+
^^^^^^^^^^^^^^^^^^^^^^^^^
112+
113+
Prerequisites
114+
"""""""""""""
115+
116+
1. **Python 3.11+**
117+
- Download and install Python from `python.org <https://www.python.org/downloads/>`_ or the Microsoft Store.
118+
- Verify installation:
119+
120+
.. code:: powershell
121+
122+
python --version
123+
124+
2. **Git**
125+
- Install Git using Windows Package Manager (``winget``) or download from `git-scm.com <https://git-scm.com/download/win>`_.
126+
- Verify:
127+
128+
.. code:: powershell
129+
130+
winget install --id Git.Git -e
131+
git --version
132+
133+
3. **CMake**
134+
- Install CMake with ``winget`` or download from `cmake.org <https://cmake.org/download/>`_.
135+
- Add CMake to your PATH during installation, then verify:
136+
137+
.. code:: powershell
138+
139+
winget install --id Kitware.CMake -e
140+
cmake --version
141+
142+
4. **Make**
143+
- Option 1: Use Git Bash (included with Git) as a shell.
144+
- Option 2: Install ``make`` via Chocolatey (install Chocolatey first if needed: `choco.io <https://chocolatey.org/install>`_).
145+
- Verify installation:
146+
147+
.. code:: powershell
148+
149+
choco install make
150+
make --version
151+
152+
153+
Setup Steps
154+
"""""""""""
155+
156+
1. **Clone the Repository**
157+
- Open PowerShell or Git Bash and run:
158+
159+
.. code:: powershell
160+
161+
git clone git@github.com:your-github-username/py-libp2p.git
162+
cd py-libp2p
163+
164+
2. **Create a Virtual Environment**
165+
- In PowerShell:
166+
167+
.. code:: powershell
168+
169+
python -m venv venv
170+
.\venv\Scripts\activate
171+
172+
3. **Install Dependencies**
173+
- Install the project and dev dependencies:
174+
175+
.. code:: powershell
176+
177+
pip install -e ".[dev]"
178+
179+
4. **Verify Setup**
180+
- Run the tests to ensure everything works:
181+
182+
.. code:: powershell
183+
184+
pytest -v
185+
186+
- If using ``make test`` with Git Bash:
187+
188+
.. code:: bash
189+
190+
make test
191+
192+
Notes
193+
"""""
194+
195+
- Use PowerShell, Command Prompt, or Git Bash as your shell.
196+
- Ensure all tools (Python, Git, CMake) are in your system PATH.
66197

67198
Requirements
68199
^^^^^^^^^^^^
@@ -110,6 +241,47 @@ Good documentation will lead to quicker adoption and happier users. Please check
110241
guide on
111242
`how to create documentation for the Python Ethereum ecosystem <https://github.com/ethereum/snake-charmers-tactical-manual/blob/main/documentation.md>`_.
112243

244+
Adding Examples
245+
~~~~~~~~~~~~~~~
246+
247+
To add a new example (e.g., identify):
248+
249+
1. Create a directory in ``examples/identify``
250+
2. Create a file ``examples/identify/identify.py`` with the example code
251+
3. Add ``__init__.py`` to make it a proper Python package (automatically discovered by find_packages() in ``setup.py``)
252+
4. Add the example in the example list ``docs/examples.rst``
253+
5. Add example tests in ``tests/core/examples/test_examples.py``
254+
6. Add the example documentation in ``docs/examples.identify.rst``
255+
7. Add a news fragment for the new release in file ``newsfragments/536.feature.rst`` (fix-id.type.rst)
256+
8. Generate doc files with ``make docs`` or ``make linux-docs`` in linux (generates files ``libp2p.identity.identify.rst libp2p.identity.rst libp2p.identity.identify.pb.rst``)
257+
9. Add the example to ``setup.py``:
258+
259+
.. code:: python
260+
261+
entry_points={
262+
"console_scripts": [
263+
"chat-demo=examples.chat.chat:main",
264+
"echo-demo=examples.echo.echo:main",
265+
"ping-demo=examples.ping.ping:main",
266+
"identify-demo=examples.identify.identify:main",
267+
],
268+
}
269+
270+
10. Run ``make package-test`` to test the release:
271+
272+
.. code:: sh
273+
274+
.....
275+
Activate with `source /tmp/tmpb9ybjgtg/package-smoke-test/bin/activate`
276+
Press enter when the test has completed. The directory will be deleted.
277+
278+
Then test the example:
279+
280+
.. code:: sh
281+
282+
source /tmp/tmpb9ybjgtg/package-smoke-test/bin/activate
283+
(package-smoke-test) $ identify-demo
284+
113285
Pull Requests
114286
~~~~~~~~~~~~~
115287

‎docs/examples.pubsub.rst

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
2+
PubSub Chat Demo
3+
================
4+
5+
This example demonstrates how to create a chat application using libp2p's PubSub implementation with the GossipSub protocol.
6+
7+
.. code-block:: console
8+
9+
$ python -m pip install libp2p
10+
Collecting libp2p
11+
...
12+
Successfully installed libp2p-x.x.x
13+
$ pubsub-demo
14+
2025-04-06 23:59:17,471 - pubsub-demo - INFO - Running pubsub chat example...
15+
2025-04-06 23:59:17,471 - pubsub-demo - INFO - Your selected topic is: pubsub-chat
16+
2025-04-06 23:59:17,472 - pubsub-demo - INFO - Using random available port: 33269
17+
2025-04-06 23:59:17,490 - pubsub-demo - INFO - Node started with peer ID: QmcJnocH1d1tz3Zp4MotVDjNfNFawXHw2dpB9tMYGTXJp7
18+
2025-04-06 23:59:17,490 - pubsub-demo - INFO - Listening on: /ip4/0.0.0.0/tcp/33269
19+
2025-04-06 23:59:17,490 - pubsub-demo - INFO - Initializing PubSub and GossipSub...
20+
2025-04-06 23:59:17,491 - pubsub-demo - INFO - Pubsub and GossipSub services started.
21+
2025-04-06 23:59:17,491 - pubsub-demo - INFO - Pubsub ready.
22+
2025-04-06 23:59:17,491 - pubsub-demo - INFO - Subscribed to topic: pubsub-chat
23+
2025-04-06 23:59:17,491 - pubsub-demo - INFO - Run this script in another console with:
24+
pubsub-demo -d /ip4/127.0.0.1/tcp/33269/p2p/QmcJnocH1d1tz3Zp4MotVDjNfNFawXHw2dpB9tMYGTXJp7
25+
26+
2025-04-06 23:59:17,491 - pubsub-demo - INFO - Waiting for peers...
27+
Type messages to send (press Enter to send):
28+
29+
Copy the line that starts with ``pubsub-demo -d``, open a new terminal and paste it in:
30+
31+
.. code-block:: console
32+
33+
$ pubsub-demo -d /ip4/127.0.0.1/tcp/33269/p2p/QmcJnocH1d1tz3Zp4MotVDjNfNFawXHw2dpB9tMYGTXJp7
34+
2025-04-07 00:00:59,845 - pubsub-demo - INFO - Running pubsub chat example...
35+
2025-04-07 00:00:59,846 - pubsub-demo - INFO - Your selected topic is: pubsub-chat
36+
2025-04-07 00:00:59,846 - pubsub-demo - INFO - Using random available port: 51977
37+
2025-04-07 00:00:59,864 - pubsub-demo - INFO - Node started with peer ID: QmYQKCm95Ut1aXsjHmWVYqdaVbno1eKTYC8KbEVjqUaKaQ
38+
2025-04-07 00:00:59,864 - pubsub-demo - INFO - Listening on: /ip4/0.0.0.0/tcp/51977
39+
2025-04-07 00:00:59,864 - pubsub-demo - INFO - Initializing PubSub and GossipSub...
40+
2025-04-07 00:00:59,864 - pubsub-demo - INFO - Pubsub and GossipSub services started.
41+
2025-04-07 00:00:59,865 - pubsub-demo - INFO - Pubsub ready.
42+
2025-04-07 00:00:59,865 - pubsub-demo - INFO - Subscribed to topic: pubsub-chat
43+
2025-04-07 00:00:59,866 - pubsub-demo - INFO - Connecting to peer: QmcJnocH1d1tz3Zp4MotVDjNfNFawXHw2dpB9tMYGTXJp7 using protocols: MultiAddrKeys(<Multiaddr /ip4/127.0.0.1/tcp/33269/p2p/QmcJnocH1d1tz3Zp4MotVDjNfNFawXHw2dpB9tMYGTXJp7>)
44+
2025-04-07 00:00:59,866 - pubsub-demo - INFO - Run this script in another console with:
45+
pubsub-demo -d /ip4/127.0.0.1/tcp/51977/p2p/QmYQKCm95Ut1aXsjHmWVYqdaVbno1eKTYC8KbEVjqUaKaQ
46+
47+
2025-04-07 00:00:59,881 - pubsub-demo - INFO - Connected to peer: QmcJnocH1d1tz3Zp4MotVDjNfNFawXHw2dpB9tMYGTXJp7
48+
Type messages to send (press Enter to send):
49+
50+
You can then start typing messages in either terminal and see them relayed to the other terminal. The messages will be distributed using the GossipSub protocol to all peers subscribed to the same topic. To exit the demo, type "quit" or send a keyboard interrupt (``Ctrl+C``) in either terminal.
51+
52+
Command Line Options
53+
--------------------
54+
55+
- ``-t, --topic``: Specify the topic name to subscribe to (default: "pubsub-chat")
56+
- ``-d, --destination``: Address of peer to connect to
57+
- ``-p, --port``: Port to listen on (default: random available port)
58+
- ``-v, --verbose``: Enable debug logging
59+
60+
The full source code for this example is below:
61+
62+
.. literalinclude:: ../examples/pubsub/pubsub.py
63+
:language: python
64+
:linenos:

‎docs/examples.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ Examples
99
examples.chat
1010
examples.echo
1111
examples.ping
12+
examples.pubsub

0 commit comments

Comments
 (0)