aioipfs

info:: Asynchronous IPFS client library

aioipfs is a python3 library providing an asynchronous API for IPFS. Supported python versions: 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12.

This library supports the RPC API specifications for kubo version 0.28.0. Unit tests are run against most major go-ipfs releases and all kubo releases, see the CI section below.

See the documentation here.

https://gitlab.com/cipres/aioipfs/badges/master/coverage.svg

Installation

pip install aioipfs

To install the requirements for bohort, a REPL tool for making RPC calls on kubo nodes:

pip install 'aioipfs[bohort]'

Support for CAR (Content-Addressable Archives) decoding (with the ipfs-car-decoder package) can be enabled with the car extra:

pip install 'aioipfs[car]'

By default the json module from the standard Python library is used to decode JSON messages, but orjson will be used if it is installed:

pip install 'aioipfs[orjson]'

Usage

Client instantiation

The recommended way to specify the kubo node’s RPC API address is to pass a multiaddr.

client = aioipfs.AsyncIPFS(maddr='/ip4/127.0.0.1/tcp/5001')

client = aioipfs.AsyncIPFS(maddr='/dns4/localhost/tcp/5001')

You can also pass a multiaddr.Multiaddr instance.

from multiaddr import Multiaddr

client = aioipfs.AsyncIPFS(maddr=Multiaddr('/ip4/127.0.0.1/tcp/5001'))

Otherwise just pass host and port separately:

client = aioipfs.AsyncIPFS(host='localhost', port=5001)

client = aioipfs.AsyncIPFS(host='::1', port=5201)

If the kubo server requires authentication, you can pass the RPC authentication credentials via the constructor’s auth keyword argument:

client = aioipfs.AsyncIPFS(auth=aioipfs.BasicAuth('john', 'password123'))

client = aioipfs.AsyncIPFS(auth=aioipfs.BearerAuth('my-secret-token'))

Get an IPFS resource

import sys
import asyncio

import aioipfs

async def get(cid: str):
    client = aioipfs.AsyncIPFS()

    await client.get(cid, dstdir='.')
    await client.close()

loop = asyncio.get_event_loop()
loop.run_until_complete(get(sys.argv[1]))

Add some files

This example will import all files and directories specified on the command line. Note that the add API function is an asynchronous generator and therefore should be used with the async for syntax.

import sys
import asyncio

import aioipfs

async def add_files(files: list):
    client = aioipfs.AsyncIPFS()

    async for added_file in client.add(*files, recursive=True):
        print('Imported file {0}, CID: {1}'.format(
            added_file['Name'], added_file['Hash']))

    await client.close()

loop = asyncio.get_event_loop()
loop.run_until_complete(add_files(sys.argv[1:]))

You can also use the async list generator syntax:

cids = [entry['Hash'] async for entry in client.add(dir_path)]

Pubsub service

async def pubsub_serve(topic: str):
    async with aioipfs.AsyncIPFS() as cli:
        async for message in cli.pubsub.sub(topic):
            print('Received message from', message['from'])

            await cli.pubsub.pub(topic, message['data'])

Dialing a P2P service

async with aioipfs.AsyncIPFS() as client:
    async with client.p2p.dial_service(peer_id, '/x/echo') as dial:
        print(f'Dial host: {dial.maddr_host}, port: {dial.maddr_port}')

        # Connect to the service now
        ....

CI

The Gitlab CI workflow runs unit tests against the following go-ipfs/kubo releases (go here for the CI jobs overview).

go-ipfs >=0.11.0,<=0.13.0
kubo >=0.14.0,<=0.28.0

https://github.com/pinnaculum/aioipfs/workflows/aioipfs-build/badge.svg

https://gitlab.com/cipres/aioipfs/badges/master/pipeline.svg

Features

Async file writing on get operations

The aiofiles library is used to asynchronously write data retrieved from the IPFS daemon when using the /api/v0/get API call, to avoid blocking the event loop. TAR extraction is done in asyncio’s threadpool.

Requirements

Python >= 3.6, <= 3.12
aiohttp
aiofiles
py-multibase
yarl

License

aioipfs is offered under the GNU Lesser GPL3 (LGPL3) license.

Release files for aioipfs 0.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aioipfs 0.7.1
File	Size	Uploaded
aioipfs-0.7.1.tar.gz	49.7 kB	Apr 19, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for aioipfs 0.7.1
File	Interpreter	ABI	Platform	Reset
aioipfs-0.7.1-py3-none-any.whl 45.8 kB Apr 19, 2024	Python 3	none	any	Details

Total release size: 95.5 kB

Release files / aioipfs-0.7.1.tar.gz

Download URL	aioipfs-0.7.1.tar.gz
Size	49.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`3f9e883344f764c357836d8d25f466bbe1212c51798b03522f31e1d143155fa0`
BLAKE2b-256 checksum How to use checksums	`e5c825cea79e0ec17ee11f664dbdca36a82197ad5e9c64a7242846c49a6a2e45`
Upload date	Apr 19, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.9.2`

Release files / aioipfs-0.7.1-py3-none-any.whl

Download URL	aioipfs-0.7.1-py3-none-any.whl
Size	45.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`be0834ef413b2f853c02c202f037950ebead57fb48ed6a73842ae97d3f36e69b`
BLAKE2b-256 checksum How to use checksums	`1f9c58177dae5dc22ec8e01a48fbd5057a7be2b2a5a8c5206eb29c762644cec3`
Upload date	Apr 19, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.9.2`