Skip to content

Commit d9c50c0

Browse files
asabyaacul71seetadev
authored
docs: update development setup commands and scripts for uv (#1249)
* docs: update development setup commands and scripts for uv * docs: clarify Linux venv auto-creation in setup * scripts: mention make docs in setup complete message * docs: standardize source activation syntax and simplify uv workflow - Replace 'source' with '.' for activating virtual environments across all docs and scripts for consistency - Remove unnecessary virtual environment check in uv branch of setup_dev.sh since 'uv sync' automatically handles venv creation - Update install.rst to use idiomatic 'uv sync' instead of 'uv venv' + 'uv pip install', matching the contributing guide * docs: finalize setup docs consistency for uv workflow Resolve PR #1249 merge blockers by adding the required issue newsfragment, aligning `.venv` guidance across docs/scripts, and documenting Python <= 3.13 compatibility in install and contributing docs. Made-with: Cursor --------- Co-authored-by: acul71 <34693171+acul71@users.noreply.github.com> Co-authored-by: Manu Sheel Gupta <manusheel.edu@gmail.com>
1 parent dddeb8c commit d9c50c0

5 files changed

Lines changed: 80 additions & 92 deletions

File tree

‎docs/contributing.rst‎

Lines changed: 24 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,10 @@ Next, install the development dependencies and set up the project. We recommend
1919
virtual environment, such as `virtualenv <https://virtualenv.pypa.io/en/stable/>`_ or
2020
Python's built-in ``venv`` module. Instructions vary by platform:
2121

22+
.. note::
23+
24+
py-libp2p contributor setup is currently supported on Python versions ``<= 3.13``.
25+
2226
Linux Setup
2327
^^^^^^^^^^^
2428

@@ -47,10 +51,13 @@ Install the development dependencies using a virtual environment:
4751
.. code:: sh
4852
4953
cd py-libp2p
50-
python3 -m venv ./venv
51-
. venv/bin/activate
5254
./scripts/setup_dev.sh
5355
56+
.. note::
57+
58+
On Linux, if you are not already in a virtual environment, the script will create one
59+
automatically and instruct you to activate it.
60+
5461
**Option 2: Using uv (recommended, same as CI):**
5562

5663
First, install ``uv`` if you haven't already:
@@ -70,19 +77,16 @@ Then set up the development environment:
7077
.. code:: sh
7178
7279
cd py-libp2p
73-
uv venv venv
74-
source venv/bin/activate
75-
uv pip install --upgrade pip
76-
uv pip install --group dev -e .
77-
pre-commit install
80+
uv sync --group dev
81+
uv run pre-commit install
7882
7983
**Option 3: Manual setup with pip:**
8084

8185
.. code:: sh
8286
8387
cd py-libp2p
84-
python3 -m venv ./venv
85-
. venv/bin/activate
88+
python3 -m venv .venv
89+
. .venv/bin/activate
8690
pip install --upgrade pip # Ensure pip >= 25.1 for PEP 735 support
8791
pip install --group dev -e .
8892
pre-commit install
@@ -95,8 +99,8 @@ An alternative using ``virtualenv``:
9599
.. code:: sh
96100
97101
cd py-libp2p
98-
virtualenv -p python venv
99-
. venv/bin/activate
102+
virtualenv -p python .venv
103+
. .venv/bin/activate
100104
pip install --upgrade pip # Ensure pip >= 25.1 for PEP 735 support
101105
pip install --group dev -e .
102106
pre-commit install
@@ -129,8 +133,6 @@ Install the development dependencies using a virtual environment:
129133
.. code:: sh
130134
131135
cd py-libp2p
132-
python3 -m venv ./venv
133-
. venv/bin/activate
134136
./scripts/setup_dev.sh
135137
136138
**Option 2: Using uv (recommended, same as CI):**
@@ -158,36 +160,20 @@ Then set up the development environment:
158160
.. code:: sh
159161
160162
cd py-libp2p
161-
uv venv venv
162-
source venv/bin/activate
163-
uv pip install --upgrade pip
164-
uv pip install --group dev -e .
165-
pre-commit install
166-
167-
On macOS, help the build command find and link against the ``gmp`` library:
168-
169-
.. code:: sh
170-
171-
CFLAGS="`pkg-config --cflags gmp`" LDFLAGS="`pkg-config --libs gmp`" uv pip install --group dev -e .
163+
CFLAGS="$(pkg-config --cflags gmp)" LDFLAGS="$(pkg-config --libs gmp)" uv sync --group dev
164+
uv run pre-commit install
172165
173166
**Option 3: Manual setup with pip:**
174167

175168
.. code:: sh
176169
177170
cd py-libp2p
178-
python3 -m venv ./venv
179-
. venv/bin/activate
171+
python3 -m venv .venv
172+
. .venv/bin/activate
180173
pip install --upgrade pip # Ensure pip >= 25.1 for PEP 735 support
181-
pip install --group dev -e .
174+
CFLAGS="$(pkg-config --cflags gmp)" LDFLAGS="$(pkg-config --libs gmp)" pip install --group dev -e .
182175
pre-commit install
183176
184-
On macOS, help the build command find and link against the ``gmp`` library:
185-
186-
.. code:: sh
187-
188-
pip install --upgrade pip # Ensure pip >= 25.1 for PEP 735 support
189-
CFLAGS="`pkg-config --cflags gmp`" LDFLAGS="`pkg-config --libs gmp`" pip install --group dev -e .
190-
191177
**Note:** This project uses PEP 735 ``[dependency-groups]`` which requires pip >= 25.1.
192178
If you have an older pip version, upgrade it first.
193179

@@ -196,8 +182,8 @@ An alternative using ``virtualenv``:
196182
.. code:: sh
197183
198184
cd py-libp2p
199-
virtualenv -p python venv
200-
. venv/bin/activate
185+
virtualenv -p python .venv
186+
. .venv/bin/activate
201187
pip install --upgrade pip # Ensure pip >= 25.1 for PEP 735 support
202188
pip install --group dev -e .
203189
pre-commit install
@@ -282,11 +268,8 @@ Setup Steps
282268

283269
.. code:: powershell
284270
285-
uv venv venv
286-
.\venv\Scripts\activate
287-
uv pip install --upgrade pip
288-
uv pip install --group dev -e .
289-
pre-commit install
271+
uv sync --group dev
272+
uv run pre-commit install
290273
291274
**Option B: Using pip:**
292275

‎docs/install.rst‎

Lines changed: 15 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@ Install
33

44
Follow the steps below to install `py-libp2p` on your platform.
55

6+
.. note::
7+
8+
py-libp2p installation is currently supported on Python versions ``<= 3.13``.
9+
610
Using uv (recommended)
711
~~~~~~~~~~~~~~~~~~~~~~
812

@@ -21,30 +25,27 @@ It is used in py-libp2p's CI/CD pipeline and is the recommended way to install.
2125
2226
pip install uv
2327
24-
2. Create and activate a virtual environment:
28+
2. Create a virtual environment and install `py-libp2p`:
2529

2630
.. code:: sh
2731
28-
uv venv .venv
32+
uv sync
33+
34+
This automatically creates a ``.venv`` in the project directory and installs
35+
the package. Activate the environment to use it:
2936

3037
- **Linux / macOS**
3138

3239
.. code:: sh
3340
34-
source .venv/bin/activate
41+
. .venv/bin/activate
3542
3643
- **Windows (PowerShell)**
3744

3845
.. code:: powershell
3946
4047
.venv\Scripts\Activate.ps1
4148
42-
3. Install `py-libp2p`:
43-
44-
.. code:: sh
45-
46-
uv pip install libp2p
47-
4849
Using pip
4950
~~~~~~~~~
5051

@@ -62,7 +63,7 @@ If you prefer pip, you can install `py-libp2p` the traditional way:
6263

6364
.. code:: sh
6465
65-
source .venv/bin/activate
66+
. .venv/bin/activate
6667
6768
- **Windows (cmd)**
6869

@@ -85,21 +86,14 @@ If you prefer pip, you can install `py-libp2p` the traditional way:
8586
Development Installation
8687
~~~~~~~~~~~~~~~~~~~~~~~~
8788

88-
To install for development with all dev dependencies:
89+
To install for development with all dev dependencies, use the ``dev`` dependency group:
8990

9091
.. code:: sh
9192
92-
# Using uv (recommended)
93-
uv pip install --group dev -e .
94-
95-
# Or using pip
96-
pip install --group dev -e .
93+
uv sync --group dev
9794
98-
py-libp2p uses `dependency groups <https://peps.python.org/pep-0735/>`_ (PEP 735)
99-
for dev dependencies, so the `--group dev` flag is required.
100-
If you use pip for development installation, ensure pip >= 25.1 so `--group`
101-
is available.
102-
For full contributor environment setup, see :doc:`contributing`.
95+
For the full contributor environment setup (including pre-commit hooks), see
96+
:doc:`contributing`.
10397

10498
Usage
10599
-----

‎newsfragments/1248.docs.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Updated contributor setup documentation to use ``uv sync`` with the default ``.venv`` workflow, including clearer setup-script guidance for Linux and macOS.

‎scripts/setup_dev.sh‎

Lines changed: 39 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -12,39 +12,49 @@ NC='\033[0m' # No Color
1212

1313
echo -e "${GREEN}Setting up py-libp2p development environment...${NC}"
1414

15-
# Check if we're in a virtual environment
16-
if [[ -z "$VIRTUAL_ENV" ]]; then
17-
echo -e "${YELLOW}Warning: Not in a virtual environment. Creating one...${NC}"
18-
python3 -m venv venv
19-
echo -e "${GREEN}Virtual environment created. Activate it with:${NC}"
20-
echo -e " source venv/bin/activate"
21-
echo -e "${YELLOW}Then run this script again.${NC}"
22-
exit 1
23-
fi
24-
25-
# Check pip version
26-
PIP_VERSION=$(pip --version | grep -oE '[0-9]+\.[0-9]+' | head -1)
27-
PIP_MAJOR=$(echo $PIP_VERSION | cut -d. -f1)
28-
PIP_MINOR=$(echo $PIP_VERSION | cut -d. -f2)
29-
30-
# PEP 735 dependency-groups support requires pip >= 25.1
31-
if [ "$PIP_MAJOR" -lt 25 ] || ([ "$PIP_MAJOR" -eq 25 ] && [ "$PIP_MINOR" -lt 1 ]); then
32-
echo -e "${YELLOW}Upgrading pip to support PEP 735 dependency-groups...${NC}"
33-
pip install --upgrade pip
34-
fi
35-
36-
# Check if uv is available (preferred method used in CI)
15+
# Check if uv is available
3716
if command -v uv &> /dev/null; then
3817
echo -e "${GREEN}Using uv for installation (recommended)...${NC}"
39-
uv pip install --upgrade pip
40-
uv pip install --group dev -e .
18+
# if on macOS, add gmp flags to the sync command
19+
if [[ "$(uname -s)" == "Darwin" ]]; then
20+
CFLAGS="$(pkg-config --cflags gmp)" LDFLAGS="$(pkg-config --libs gmp)" uv sync --group dev
21+
else
22+
uv sync --group dev
23+
fi
24+
25+
# Install pre-commit hooks
26+
echo -e "${GREEN}Installing pre-commit hooks...${NC}"
27+
uv run pre-commit install
28+
29+
echo -e "${GREEN}Setup complete! You can now run 'make pr' to check your changes, or 'make docs' to build the docs.${NC}"
4130
else
31+
# Check if virtual environment flag is set
32+
if [[ -z "$VIRTUAL_ENV" ]]; then
33+
echo -e "${YELLOW}Warning: Not in a virtual environment. Creating one...${NC}"
34+
python3 -m venv .venv
35+
echo -e "${GREEN}Virtual environment created. Activate it with:${NC}"
36+
echo -e " . .venv/bin/activate"
37+
echo -e "${YELLOW}Then run this script again.${NC}"
38+
exit 1
39+
fi
40+
41+
# Check pip version
42+
PIP_VERSION=$(pip --version | grep -oE '[0-9]+\.[0-9]+' | head -1)
43+
PIP_MAJOR=$(echo $PIP_VERSION | cut -d. -f1)
44+
PIP_MINOR=$(echo $PIP_VERSION | cut -d. -f2)
45+
46+
# PEP 735 dependency-groups support requires pip >= 25.1
47+
if [ "$PIP_MAJOR" -lt 25 ] || ([ "$PIP_MAJOR" -eq 25 ] && [ "$PIP_MINOR" -lt 1 ]); then
48+
echo -e "${YELLOW}Upgrading pip to support PEP 735 dependency-groups...${NC}"
49+
pip install --upgrade pip
50+
fi
51+
4252
echo -e "${GREEN}Using pip for installation...${NC}"
4353
pip install --group dev -e .
44-
fi
4554

46-
# Install pre-commit hooks
47-
echo -e "${GREEN}Installing pre-commit hooks...${NC}"
48-
pre-commit install
55+
# Install pre-commit hooks
56+
echo -e "${GREEN}Installing pre-commit hooks...${NC}"
57+
pre-commit install
4958

50-
echo -e "${GREEN}Setup complete! You can now run 'make pr' to check your changes.${NC}"
59+
echo -e "${GREEN}Setup complete! You can now run 'make pr' to check your changes, or 'make docs' to build the docs.${NC}"
60+
fi

‎scripts/smoke_test_examples.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
1616
Run from repo root with the project venv active::
1717
18-
source venv/bin/activate && python scripts/smoke_test_examples.py
18+
. .venv/bin/activate && python scripts/smoke_test_examples.py
1919
"""
2020

2121
from __future__ import annotations

0 commit comments

Comments
 (0)