Contributing¶

Thank you for your interest in contributing! We welcome all contributions no matter their size. Please read along to learn how to get started. If you get stuck, feel free to ask for help in Libp2p Discover Server.

Setting the stage¶

To get started, fork the repository to your own GitHub account, then clone it to your development machine:

git clone git@github.com:your-github-username/py-ipld-dag.git

Next, install the development dependencies and set up the project. We recommend using a virtual environment, such as virtualenv or Python’s built-in venv module. Instructions vary by platform:

Linux Setup¶

Prerequisites¶

On Debian Linux, install make if needed (e.g. for make test, make docs-ci):

sudo apt install make

Setup Steps¶

Install the development dependencies using a virtual environment:

Option 1: Using uv (recommended, same as CI):

First, install uv if you haven’t already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or using pip:

pip install uv

Then set up the development environment:

cd py-ipld-dag
uv venv venv
source venv/bin/activate
uv pip install --upgrade pip
uv pip install --group dev -e .
pre-commit install

Option 2: Manual setup with pip:

cd py-ipld-dag
python3 -m venv ./venv
. venv/bin/activate
pip install --upgrade pip  # Ensure pip >= 25.1 for PEP 735 support
pip install --group dev -e .
pre-commit install

Note: This project uses PEP 735 [dependency-groups] which requires pip >= 25.1. If you have an older pip version, upgrade it first.

An alternative using virtualenv:

cd py-ipld-dag
virtualenv -p python venv
. venv/bin/activate
pip install --upgrade pip  # Ensure pip >= 25.1 for PEP 735 support
pip install --group dev -e .
pre-commit install

macOS Setup¶

Prerequisites¶

On macOS, make is usually already available (e.g. via Xcode Command Line Tools: xcode-select --install). No other system packages are required.

Setup Steps¶

Install the development dependencies using a virtual environment:

Option 1: Using uv (recommended, same as CI):

First, install uv if you haven’t already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or using Homebrew:

brew install uv

Or using pip:

pip install uv

Then set up the development environment:

cd py-ipld-dag
uv venv venv
source venv/bin/activate
uv pip install --upgrade pip
uv pip install --group dev -e .
pre-commit install

Option 2: Manual setup with pip:

cd py-ipld-dag
python3 -m venv ./venv
. venv/bin/activate
pip install --upgrade pip  # Ensure pip >= 25.1 for PEP 735 support
pip install --group dev -e .
pre-commit install

Note: This project uses PEP 735 [dependency-groups] which requires pip >= 25.1. If you have an older pip version, upgrade it first.

An alternative using virtualenv:

cd py-ipld-dag
virtualenv -p python venv
. venv/bin/activate
pip install --upgrade pip  # Ensure pip >= 25.1 for PEP 735 support
pip install --group dev -e .
pre-commit install

Windows Development Setup¶

Prerequisites¶

Python 3.10+ - Download and install Python from python.org or the Microsoft Store. - Verify installation:
```
python --version
```
Git - Install Git using Windows Package Manager (winget) or download from git-scm.com. - Verify:
```
winget install --id Git.Git -e
git --version
```
Make
- Option 1: Use Git Bash (included with Git) as a shell.
- Option 2: Install make via Chocolatey (install Chocolatey first if needed: choco.io).
- Verify installation:
```
choco install make
make --version
```

Setup Steps¶

Clone the Repository - Open PowerShell or Git Bash and run:

git clone git@github.com:your-github-username/py-ipld-dag.git
cd py-ipld-dag

Create a Virtual Environment - In PowerShell:

python -m venv venv
.\venv\Scripts\activate

Install Dependencies

Option A: Using uv (recommended, same as CI):

First, install uv if you haven’t already:

# Using pip
pip install uv

# Or using winget
winget install --id=astral-sh.uv

Then set up the development environment:

uv venv venv
.\venv\Scripts\activate
uv pip install --upgrade pip
uv pip install --group dev -e .
pre-commit install

Option B: Using pip:

pip install --upgrade pip  # Ensure pip >= 25.1 for PEP 735 support
pip install --group dev -e .
pre-commit install

Note: This project uses PEP 735 [dependency-groups] which requires pip >= 25.1. If you have an older pip version, upgrade it first.

Verify Setup - Run the tests to ensure everything works:
```
pytest -v
```
- If using make test with Git Bash:
```
make test
```

Notes¶

Use PowerShell, Command Prompt, or Git Bash as your shell.
Ensure all tools (Python, Git, CMake) are in your system PATH.

Requirements¶

The protobuf description in this repository was generated by protoc at version 30.1.

Running the tests¶

A great way to explore the code base is to run the tests.

We can run all tests with:

make test

Code Style¶

We use pre-commit to enforce a consistent code style across the library. This tool runs automatically with every commit, but you can also run it manually with:

make lint

If you need to make a commit that skips the pre-commit checks, you can do so with git commit --no-verify.

This library uses type hints, which are enforced by the mypy tool (part of the pre-commit checks). All new code is required to land with type hints, with the exception of code within the tests directory.

Adding Examples¶

Organize examples in a package-style layout (one package directory per example) and follow the workflow below.

To add a new example (actual py-ipld-dag example: cid_interface):

Create a package directory in examples/cid_interface.
Create examples/cid_interface/cid_interface.py with the example code.
Add examples/cid_interface/__init__.py so it is importable as a package.
Add/update an examples index page in docs (for example docs/examples.rst), and include it from docs/index.rst.
Add example tests (for example tests/examples/test_cid_interface.py).
Add dedicated docs page for the example (for example docs/examples.cid_interface.rst).
Add or update the examples list in examples/README.md and README.md.
Add a newsfragment under newsfragments/ using <ISSUE_OR_PR_NUMBER>.<TYPE>.rst when the change is user-facing.
Optionally expose it as a CLI script via pyproject.toml [project.scripts] (py-ipld-dag uses pyproject.toml, not setup.py).
Run project checks:
```
make pr
make docs-ci
```

Actual py-ipld-dag example (package-style layout)¶

Example file: examples/cid_interface/cid_interface.py

"""Equivalent of js-multiformats/examples/cid-interface.js."""

import argparse
import json

from dag.utils import bytes_to_cid, cid_to_bytes, create_cid, string_to_cid

JS_EXPECTED = {
    "base32_cid": "bagaaierasords4njcts6vs7qvdjfcvgnume4hqohf65zsfguprqphs3icwea",
    "base64_cid": "mAYAEEiCTojlxqRTl6svwqNJRVM2jCcPBxy+7mRTUfGDzy2gViA",
}


def build_report() -> dict[str, object]:
    value = {"hello": "world"}
    encoded_json = json.dumps(value, separators=(",", ":"), sort_keys=True).encode("utf-8")

    # Use the plain "json" multicodec to mirror js-multiformats cid-interface.js.
    cid = create_cid(encoded_json, codec="json", hasher="sha2-256", version=1)
    base32_cid = cid.encode("base32").decode("ascii")
    base64_cid = cid.encode("base64").decode("ascii")

    parsed_from_base32 = string_to_cid(base32_cid)
    parsed_from_base64 = string_to_cid(base64_cid)
    restored_from_bytes = bytes_to_cid(cid_to_bytes(cid))

    matches = {
        "base32_cid": base32_cid == JS_EXPECTED["base32_cid"],
        "base64_cid": base64_cid == JS_EXPECTED["base64_cid"],
        "parsed_from_base32_equals_original": parsed_from_base32.buffer == cid.buffer,
        "parsed_from_base64_equals_original": parsed_from_base64.buffer == cid.buffer,
        "bytes_round_trip_equals_original": restored_from_bytes.buffer == cid.buffer,
    }

    return {
        "input": value,
        "codec": "json",
        "codec_code_hex": "0x200",
        "cid_version": cid.version,
        "default_cid_string": str(cid),
        "base32_cid": base32_cid,
        "base64_cid": base64_cid,
        "js_expected": JS_EXPECTED,
        "matches_js_comments": matches,
    }


def main() -> None:
    parser = argparse.ArgumentParser(description="CID interface example")
    parser.add_argument("--json", action="store_true", help="Print structured JSON report")
    args = parser.parse_args()

    report = build_report()
    if args.json:
        print(json.dumps(report, indent=2, sort_keys=True))
        return

    print(f"Example CID (default string form): {report['default_cid_string']}")
    print(f"Codec code: {report['codec_code_hex']}")
    print(f"CID version: {report['cid_version']}")
    print(f"base64 encoded CID: {report['base64_cid']}")
    print(f"Parsed from base64 equals original: {report['matches_js_comments']['parsed_from_base64_equals_original']}")
    print(f"base32 encoded CID: {report['base32_cid']}")
    print(f"Parsed from base32 equals original: {report['matches_js_comments']['parsed_from_base32_equals_original']}")
    print(f"CID bytes round-trip equal: {report['matches_js_comments']['bytes_round_trip_equals_original']}")
    print(
        "Matches js comments (base32/base64): "
        f"{report['matches_js_comments']['base32_cid']}/"
        f"{report['matches_js_comments']['base64_cid']}"
    )


if __name__ == "__main__":
    main()

Run it:

source venv/bin/activate
python -m examples.cid_interface.cid_interface
python -m examples.cid_interface.cid_interface --json

Pull Requests¶

It’s a good idea to make pull requests early on. A pull request represents the start of a discussion, and doesn’t necessarily need to be the final, finished submission.

GitHub’s documentation for working on pull requests is available here.

Once you’ve made a pull request, take a look at the GitHub Actions build status in the GitHub interface and make sure all tests are passing. In general pull requests that do not pass the CI build yet won’t get reviewed unless explicitly requested.

If the pull request introduces changes that should be reflected in the release notes, please add a newsfragment file as explained here.

If possible, the change to the release notes file should be included in the commit that introduces the feature or bugfix.

Releasing¶

Releases are typically done from the master branch. This project defines make notes and make release in the repository Makefile.

Final test before each release¶

Before releasing a new version, build and test the package:

git checkout master && git pull
python -m build && pip install dist/*.whl  # or install from dist/ and test

This will build the package and install it in a temporary virtual environment. Follow the instructions to activate the venv and test whatever you think is important.

You can also preview the release notes:

towncrier --draft

Build the release notes¶

Before bumping the version number, build the release notes (consumes newsfragments and updates docs/release_notes.rst):

make notes bump=PART

Use PART as patch, minor, or major. This generates the release notes for the upcoming version and commits the result.

Bump version and tag¶

Bump the version, build the package, push the release commit and tag, and upload to PyPI:

make release bump=PART

where PART is patch, minor, or major. This creates a version bump commit and tag (e.g. v0.1.1), builds the package, pushes the commit and tag, and uploads the distribution.

Which version part to bump¶

PART must be one of: major, minor, or patch (this project uses {major}.{minor}.{patch} only).

To issue an unstable version when the current version is stable, specify the new version explicitly, e.g. bump-my-version bump --new-version 0.2.0-alpha.1.

To preview the next version without changing any files, use bump-my-version show -i PART new_version where PART is patch, minor, or major. Example: bump-my-version show -i patch new_version prints 0.1.1.

Contributing¶

Setting the stage¶

Linux Setup¶

Prerequisites¶

Setup Steps¶

macOS Setup¶

Prerequisites¶

Setup Steps¶

Windows Development Setup¶

Prerequisites¶

Setup Steps¶

Notes¶

Requirements¶

Running the tests¶

Code Style¶

Adding Examples¶

Actual py-ipld-dag example (package-style layout)¶

Pull Requests¶

Releasing¶

Final test before each release¶

Build the release notes¶

Bump version and tag¶

Which version part to bump¶

py-ipld-dag

Navigation

Related Topics