Asynchronous IPFS client API for Python3’s asyncio.
pip install aioipfs
If you want to use orjson to decode JSON messages:
pip install 'aioipfs[orjson]'
To create an AsyncIPFS client instance it’s
recommended to specify the node’s RPC API address with a multiaddr:
import aioipfs
client = aioipfs.AsyncIPFS(maddr='/ip4/127.0.0.1/tcp/5001')
client = aioipfs.AsyncIPFS(maddr='/dns4/localhost/tcp/5001')
The default constructor assumes that the kubo node you want to connect to is localhost on port 5001 (use the host and port keyword arguments to set different values):
client = aioipfs.AsyncIPFS()
client = aioipfs.AsyncIPFS(host='10.0.12.3', port=5003)
Maximum HTTP connections and read timeout parameters:
client = aioipfs.AsyncIPFS(host='localhost', port=5008, conns_max=20)
client = aioipfs.AsyncIPFS(host='localhost', port=5008, read_timeout=30)
You can use an async context manager in your code:
async with aioipfs.AsyncIPFS() as client:
async for reply in client.ping(peer_id):
...
When finished you should always call AsyncIPFS.close() on your client:
await client.close()
The kubo (formerly called go-ipfs) RPC HTTP API provides many endpoints which allow to access the different subsystems of the IPFS daemon. You can read the RPC API specifications here.
Important: The aioipfs client API closely follows kubo’s RPC endpoints path hierarchy, as each subsystem has its own namespace/attribute inside the AsyncIPFS client object, for example:
client.core for the CoreAPI
client.pin for the PinAPI
client.pin.remote for the PinRemoteAPI
client.files for the FilesAPI
client.pubsub for the PubsubAPI
etc …
All API functions will raise an APIError
(or a more specific exception) if there’s an error raised during the request.
Add files to the IPFS repository with the api.CoreAPI.add() async
generator:
async for added in client.core.add('file1.txt', '/usr/local/src',
recursive=True):
print(added['Hash'])
async for added in client.core.add(['one', 'two', 'three'],
wrap_with_directory=True):
...
cids = [entry['Hash'] async for entry in client.add(dir_path)]
Entries yielded by the generator are as returned by the IPFS daemon, dictionaries with Name, Hash and Size keys.
Add some bytes with api.CoreAPI.add_bytes():
>>> entry = await client.core.add_bytes(b'ABCD')
{'Name': 'QmZ655k2oftYnsocBxqTWzDer3GNui2XQTtcA4ZUbhpz5N', 'Hash': 'QmZ655k2oftYnsocBxqTWzDer3GNui2XQTtcA4ZUbhpz5N', 'Size': '12'}
Add a UTF-8 string with api.CoreAPI.add_str():
entry = await client.core.add_str('ABCD')
Download IPFS objects with api.CoreAPI.get():
await client.core.get('QmRGqvWK44oWu8re5whp43P2M7j5XEDLHmPB3wncYFmCNg')
await client.core.get('QmRGqvWK44oWu8re5whp43P2M7j5XEDLHmPB3wncYFmCNg',
dstdir='/tmp')
Use api.CoreAPI.cat() to get an object’s raw data:
bytes = await client.core.cat(cid)
Use api.CoreAPI.ls() for listing:
listing = await client.core.ls(path)
Get IPFS node information:
info = await client.core.id()
Gives access to the BitswapAPI
Gives access to the BootstrapAPI
Gives access to the DagAPI
Gives access to the FilestoreAPI
Access the IPFS event log with:
import pprint
async for msg in client.log.tail():
print(pprint.pprint(msg))
Gives access to the MultibaseAPI
Pinning a CID or an IPFS path:
async for pinned in client.pin.add(cid):
print('Pin progress', pinned['Progress'])
Listing the pinned objects:
pinned = await client.pin.ls()
Unpin with:
await client.pin.rm(path)
Gives access to the PinRemoteAPI
Gives access to the PubsubAPI
Gives access to the RoutingAPI
Gives access to the SwarmPeeringAPI