ipfs.api package¶

Submodules¶

ipfs.api.block module¶

This module handles the utilities for the node’s blocks.

class ipfs.api.block.BlockApi(root)¶

Bases: object

Manipulate raw IPFS blocks.

get(key)¶

Get a raw IPFS block.

Parameters:	key – The base58 multihash of an existing block
Returns:	A byte stream with the raw contents of that block

Example:

>>> key = "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V"
>>> IpfsApi().block.get(key).read()[27:62].decode()
'IPFS -- Inter-Planetary File system'

put(f)¶

Store data as an IPFS block.

Parameters:	f – A byte stream that is used as contents of that block
Returns:	A dict with: `Key`: The key of the new block `Size`: The size of the new block

Example:

>>> from io import BytesIO
>>> IpfsApi().block.put(BytesIO(b"foobar"))
{'Key': 'QmbWTwYGcmdyK9CYfNBcfs9nhZs17a6FQ4Y8oea278xx41', 'Size': 6}

stat(key)¶

Print information of a raw IPFS block.

Parameters:	key – The base58 multihash of an existing block
Returns:	A dict with: `Key`: The key of that block `Size`: The size of that block in bytes

ipfs.api.config module¶

This module handles the utilities to read and write to the IPFS node’s config.

class ipfs.api.config.ConfigApi(root)¶

Bases: object

Get and set IPFS config values

show()¶

Return the current configuration

Returns:	The current configuration as dict.

ipfs.api.dht module¶

This module handles the Distributed Hash Table

class ipfs.api.dht.DhtApi(root)¶

Bases: object

Issue commands directly through the DHT.

find_peer(peer_id)¶

Run a ‘FindPeer’ query through the DHT.

Parameters:	peer_id – The peer to search for
Returns:	TODO

find_providers(key)¶

Run a ‘FindProviders’ query through the DHT.

Parameters:	key – The key to find providers for
Returns:	TODO

get(key)¶

Run a ‘GetValue’ query through the DHT.

Parameters:	key – The key to find a value for
Returns:	TODO

put(key, value)¶

Run a ‘PutValue’ query through the DHT.

Parameters:	key – The key to store the value at value – The value to store
Returns:	TODO

query(peer_id)¶

Run a ‘FindClosestPeers’ query through the DHT.

Parameters:	peer_id – The peer ID to run the query against
Returns:	TODO

ipfs.api.file module¶

This module exposes the IPFS file API.

class ipfs.api.file.FileApi(root)¶

Bases: object

Interact with IPFS objects that represent Unix files.

add(f)¶

Add a file to IPFS.

Parameters:	f – A file-like object that will be added to IPFS
Returns:	A dict containing the `Hash` of the file.

cat(path)¶

Read a file from IPFS.

Parameters:	path – The path to the IPFS object to read
Returns:	A file-like object with the contents of the file.

ls(path)¶

List directory contents for unixfs objects.

Parameters:	path – The path to the IPFS object to list links from
Returns:	Retrieves the object named by the path and lists its contents.

ipfs.api.name module¶

This modules handles name publishing and resolution

class ipfs.api.name.NameApi(root)¶

Bases: object

Publish an resolve IPNS names.

publish(path, resolve=True, lifetime=None, ttl=None)¶

Publish an object to IPNS.

Parameters:	path – IPFS path of the object to be published resolve – resolve given path before publishing (default=True) lifetime – time duration that the record will be valid for (default: 24 hours) ttl – time duration this record should be cached for (caution: experimental)
Returns:	A dict with: `Name`: The IPNS name of the published object `Value`: The IPFS path of the published object

resolve(name=None, recursive=None, nocache=None)¶

Gets the value currently published at an IPNS name

Parameters:	name – The IPNS name to resolve. Defaults to your node’s peer ID. recursive – Resolve until the result is not an IPNS name (default: True) nocache – Do not used cached entries (default: TODO)
Returns:	A dict with: `Path`: The path pubilshed under that name
Raise:	ProxyError if the name can’t be resolved

ipfs.api.object module¶

class ipfs.api.object.ObjectPatchApi(rpc, key)¶

Bases: object

Patch an object.

add_link(name, hash)¶

Add a link to the object.

Parameters:	name – Link name hash – Hash of object to be linked
Returns:	The new object

append_data(f)¶

Set data for the object. NOT IMPLEMENTED YET!

Parameters:	f – File-like object which is appended to the data of the object
Returns:	The new object

rm_link(name)¶

Remove a link from the object.

Parameters:	name – Link name
Returns:	The new object

set_data(f)¶

Set data for the object. NOT IMPLEMENTED YET!

Parameters:	f – File-like object which is used as data for the object
Returns:	The new object

class ipfs.api.object.ObjectApi(root)¶

Bases: object

Interact with IPFS objects.

For a more high-level API for interacting with IPFS objects, see ipfs.merkledag

data(key)¶

Return the raw bytes in an IPFS object. Wrapped into a File-like object.

Methods that work on raw data use file-like objects (HTTPResponse acts as a file-like object) for input and output.

Return HTTPResponse:
Parameters:	key – Key of the object to retrieve
	The raw bytes of that object

get(key)¶

Return the object, i.e. its data and links.

Example Ouput:

>>> ex = {'Links': [{'Hash': 'QmdoDatULjkor1eA1YhBAjmKkkDr7AGEiTrANh7uK17Hfn', 'Size': 4118930,            'Name': 'bundle.js'}, {'Hash': 'QmP5BvrMtqWGirZYyHgz77zhEzLiJbonZVdHPMJRM1xe8G', 'Size': 2506050,            'Name': 'static'}, {'Hash': 'QmecBJMFtTsn4RawUcqFGudevEWcDUym4b6FtemLtKhZy7', 'Size': 181436,             'Name': 'style.css'}], 'Data': b''}
>>> print(ex)

Parameters:	key – Key of the object to retrieve
Returns:	A dict that may contain: `Data`: The raw data stored in this object, if any `Links`: See `links()`, if any. An object without links can cause the Links item to not exist, the Links item being None or the Links item being the empty list.

links(key)¶

Return the links pointed to by the specified object.

Example output:

>>> {'Links': [], 'Hash': 'QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn'}
>>> print(ex)

Parameters:	key – Key of the object to retrieve
Return dict:	A list of links that are dicts that may contain: `Name`: The name of that link `Hash`: The hash of the linked object `Size`: The size of the linked object

new(template=None)¶

Create a new object from an IPFS template.

Parameters:	template – The template name (optional). If no template is specified, an empty node is created.
Returns:	Same as `put()`

patch(key)¶

Return the patch API for the specified key.

Parameters:	key – The key to be patched
Returns:	A `ObjectPatchApi` object, which can be used to patch an object.

put(node)¶

Store an object.

Example output:

>>> ex = {'Hash': 'QmXy2pAWQ3Ef1PqZqi4Z9TJnpDh1trdkCqAvzBgKNNRrSR', 'Links': []}
>>> print(ex)

Parameters:	node – The node (a.k.a. object) to be stored
Returns:	A dict with: `Hash`: The hash of the object `Links`: The links of the object. See `get()`.

stat(key)¶

Return node’s statistics.

Example output::

>>> ex = {'DataSize': 2, 'NumLinks': 0,            'Hash': 'QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn',           'CumulativeSize': 4, 'LinksSize': 2, 'BlockSize': 4}
>>> print(ex))

Parameters:	key – Key of the object to retrieve
Returns:	Dict with stats. See example output.

ipfs.api.pin module¶

Module containing the PinApi

class ipfs.api.pin.PinApi(root)¶

Bases: object

Pin and unpin objects to local storage.

add(path)¶

Pin object to local storage.

Parameters:	path – Path of object to pin
Returns:	A dict with: `Pinned`: List of hashes that have been pinned.

ls()¶

List all pinned objects.

Returns:	See example

TODO: Example

rm(path)¶

Unpin object from local storage.

Parameters:	path – Path of object to unpin
Returns:	A dict with: `Pinned`: List of hashes that have been unpinned.

ipfs.api.proxy module¶

This modules handles HTTP RPC requests, by exposing them via proxies.

exception ipfs.api.proxy.ProxyError¶

Bases: Exception

Raised when the HTTP server returns an error code.

class ipfs.api.proxy.Proxy(rootProxy, path)¶

Bases: object

A proxy is a wrapper around an HTTP call to an specific path.

When you have a proxy for an path e.g. /api/v0/ you can get the proxy for /api/v0/block either by accessing an attribute proxy.block or by accessing an item proxy["block"].

with_inputenc(inputenc)¶

Return a proxy with the same path, but with the input wrapped with the specified encoding.

Parameters:	inputenc – The input encoding that will be applied to any input before sending the HTTP request.
Returns:	A new proxy with the same path but, but with the specified input encoding.

with_outputenc(outputenc)¶

Return a proxy with the same path, but with the output wrapped with the specified encoding.

Parameters:	outputenc – The output encoding that will be applied to any output before sending the HTTP request.
Returns:	A new proxy with the same path but, but with the specified output encoding.

class ipfs.api.proxy.InputEncodingProxy(parent, inputenc)¶

Bases: ipfs.api.proxy.Proxy

A proxy that handles input encoding.

class ipfs.api.proxy.OutputEncodingProxy(parent, outputenc)¶

Bases: ipfs.api.proxy.Proxy

A proxy that handles input encoding.

class ipfs.api.proxy.HttpProxy(host, port)¶

Bases: object

The root proxy which offers the root attribute from which all proxies are derived. This class also actually does the work of doing an HTTP request.

DEBUG = False¶: Whether to output debugging information for HTTP requests.

ENDPOINT = '/api/v0'¶: The api endpoint we’re using. Currently API v0.

Module contents¶

This modules exposes the IPFS HTTP API to Python.

To get started create an instance of IpfsApi:

>>> from ipfs.api import IpfsApi
>>> ipfs = IpfsApi()

class ipfs.api.IpfsApi(host='localhost', port=5001)¶

Bases: object

An wrapper for the IPFS HTTP API. It exposes sub-commands and top-level commands and wraps them with the appropiate encodings.

Example:

>>> key = "QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB"
>>> print(IpfsApi().file.cat(key).read().decode())

IpfsApi exposes top-level command as its methods (e.g. id()) and sub-commands can be accessed via the name of the plumbing command (e.g. file).

The following plumbing commands are available at the moment:

block: Operations on raw blocks.

dht: Operations on the DHT

object: Operations on objects a.k.a merkledag nodes

config: Operations on the configuration

name: Name resolution and publishing

pin: Pinning of blocks

file: File operations

id(peer_id=None)¶

Return information about the specified IPFS peer. If no peer is specified, own peer information will be returned.

Parameters:	peer_id – Peer ID of node to look up (optional)
Returns:	A dict with: `ID`: The peer’s ID `PublicKey`: The peer’s public key encoded as base64 `Addresses`: A list of the peer’s addresses `AgentVersion`: The peer’s agent version `ProtocolVersion`: The peer’s protocol version

repo_gc()¶: Perform a garbage collection sweep on the repo.

resolve(name, recursive=None)¶

Resolve a name.

Parameters:	name – The name to resolve recursive – Resolve until the name is an IPFS name (default: true)
Returns:	The resolved IPFS name

Example:

>>> name = "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/readme"
>>> IpfsApi().resolve(name)
{'Path': '/ipfs/QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB'}

version()¶

Return IPFS version information.

Returns:	A dict with: `Version`: Version number `Commit`: Commit hash `Repo`: Repo version

Example:

>>> ipfs.version()
{'Commit': '', 'Repo': '2', 'Version': '0.3.11-dev'}