ipfs package

Submodules

ipfs.merkledag module

This module is a high-level abstraction to the ipfs.object API.

It provides a pythonic way of interacting with merkledag nodes (a.k.a. objects).

To run the following examples start with:

>>> from ipfs.api import IpfsApi
>>> from ipfs.merkledag import Merkledag
>>> dag = Merkledag(IpfsApi())

Bases: object

A link in the merkledag that links another node.

name

The link name

hash

The linked node’s hash

size

Size of the node (optional, might be 0)

follow()

Return the referenced node.

Example:

>>> node = dag["QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec"]
>>> link = node.get_link("readme")
>>> readme = link.follow()
>>> readme
Node(QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB)
>>> readme.data[5:22].decode()
'Hello and Welcome'

Normally you don’t have to interact with links. You can directly follow links by referencing attributes of a Node.

class ipfs.merkledag.Node(dag, hash)

Bases: object

A merkledag node (a.k.a object).

A merkledag node is a node like in any other graph. It stores some data and can have multiple links (or edges) to other nodes.

To get a merkledag node call dag.get(ref) or access it via dag[ref], where ref can be a ipfs or ipns name or a plain base58 hash of your node:

>>> dag["QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec"]
Node(QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec)

The data of a node can be accessed via its data attribute:

>>> n = dag["QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB"]
>>> n.data[5:22].decode()
'Hello and Welcome'

Links can be followed by directly accessing attributes:

>>> node = dag["QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec"]
>>> node.readme
Node(QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB)

You can also interate over a node’s links by:

>>> node = dag["QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec"]
>>> for link in node:
        print(link.name, "->", link.hash)
 
about -> QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V
contact -> QmYCvbfNbCwFR45HiNP45rwJgvatpiW38D961L5qAhUM5Y
help -> QmY5heUM5qgRubMDD1og9fhCPA6QdkMp3QCwd4s7gJsyE7
quick-start -> QmXifYTiYxz8Nxt3LmjaxtQNLYkjdh324L4r81nZSadoST
readme -> QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB
security-notes -> QmTumTjvcYCAvRRwQ8sDRxh8ezmrcr88YFU7iYNroGGTBZ
hash

The node’s hash

data

The data contained in this node.

DEPRECATED: Use value instead.

flush()

Flush the cached value and links.

Return a link by its name.

Parameters:name – The link name
Returns:The link with that name
get_node(name)

Return a linked node given the link’s name.

Parameters:name – The link name
Returns:The node linked by this name

This is a shortcut for node.get_link(name).follow()

Return whether this node has a link with the given name.

Parameters:name – The link name
Returns:True if a link with that name exists, False otherwise.

A list of the links contained in this node.

ref

The reference URL, e.g. "/ipfs/QmPXME1oRtoT627YKaDPDQ3PwA8tdP9rWuAAweLzqSwAWT".

value

The value contained in this node.

class ipfs.merkledag.NodeBuilder(dag)

Bases: object

The NodeBuilder is used to create new nodes.

Currently it’s the only mechanism available to create a node. Soon there will be methods to patch a node in order to create new nodes.

Example:

>>> c1 = dag.builder().data("Child 1").build()
>>> c2 = dag.builder().data("Child 2").link("sibling", c1).build()
>>> r = dag.builder().data("Root")               .link("child_1", c1).link("child_2", c2).build()
>>> r
Node(Qme2Fuk2YRNWwbhQ9G4d3GBAEQ5kL1r8P1b5RVx1HgZsco)

Try exploring that in your DAG browser: http://localhost:5001/ipfs/QmR9MzChjp1MdFWik7NjEjqKQMzVmBkdK3dz14A6B5Cupm/#/objects/object/Qme2Fuk2YRNWwbhQ9G4d3GBAEQ5kL1r8P1b5RVx1HgZsco

build()

Return the node built by this builder.

Returns:The node with the specified data and links
data(data)

Set the data that will be contained in the new node.

Parameters:data – A bytes object or string that will be the node’s content.
Returns:The builder itself to allow chaining.

DEPRECATED: Use value() instead.

Set a link that will be added to the node.

Parameters:
  • name – The link name
  • target – The merkledag node or hash to which the link points
  • size – The cumulative size of the linked node (optional)
Returns:

The builder itself to allow chaining.
value(value)

Set the value that will be included in the new node.

Parameters:value – A value that can be encoded by the coded specified in Merkledag.
Returns:The builder itself to allow chaining.
class ipfs.merkledag.Merkledag(ipfs, codec=None)

Bases: object

The root for all merkledag operations.

To get a node try:

>>> dag = Merkledag(IpfsApi())
>>> dag["QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB"]
Node(QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB)

or:

>>> dag["/ipfs/QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/readme"]
Node(QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB)

or:

>>> dag["/ipns/<your peer ID>"]
builder()
get(ref)

Return a merkledag node by it’s reference.

Parameters:ref – Either a IPNS or IPFS name or a plain base58 hash to a node
Returns:The references node

ipfs.codec module

This modules handles various encodings formats used by the IPFS HTTP API.

class ipfs.codec.Codec

Bases: object

An abstract encoding/decoding mechanism.

It exposes the same methods as json, pickle, etc. Namely dump, dumps, load and loads.

Implement dump and load and this class will handle dumps and loads for you.

dump(obj, f)

Dump a object to a file stream. The file stream is expected to be binary.

Parameters:
  • obj – The object to dump
  • f – The stream to dump to

Override this method to implement a codec.

dumps(obj)

Dump an object as bytes object.

Param:The object to dump
Returns:The bytes that represent the object in binary form
load(f)

Load a object from a file stream. The file stream is binary.

Parameters:f – The stream to load from
Returns:The object loaded from the stream

Override this method to implement a codec.

loads(data)

Load an object from an bytes object.

Parameters:data – The binary data representing an object
Returns:The object represented by the data
name = None

The name of that encoding. This will be sent to the HTTP API to select the input or output encoding.

class ipfs.codec.Json

Bases: ipfs.codec.Codec

Encoding and decoding of JSON.

dump(obj, f)
load(f)
name = 'json'
class ipfs.codec.JsonVector

Bases: ipfs.codec.Codec

Encoding and decoding of a stream of lines that contain JSON.

dump(obj, f)
load(f)
name = 'json'
class ipfs.codec.Protobuf2(protocol, message)

Bases: ipfs.codec.Codec

Encoding and decoding of protobuf2 encoded messages.

dump(obj, f)
load(f)
name = 'protobuf'
ipfs.codec.JSON = <ipfs.codec.Json object>

The singleton instance of the JSON encoding.

ipfs.codec.JSONV = <ipfs.codec.JsonVector object>

The singleton instance of the JSON vector encoding.

ipfs.codec.PB2(protocol, message)

Return a Protobuf2 instance depending on the protocol and message type.

ipfs.unixfs module

The unixfs module implements pythonic file-abstractions for unixfs files.

Currently only reading files is implemented.

You need an instance of UnixFs to access the unixfs.

Example::
>>> from ipfs.api import IpfsApi
>>> from ipfs.unixfs import UnixFs
>>> fs = UnixFs(IpfsApi())
>>> with fs.open("QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB") as f:
        print(f.read())
Hello and Welcome to IPFS!
...
class ipfs.unixfs.ModeParser(mode)

Bases: object

Parser for mode strings (e.g “r+b”).

This is only used internally.

invalid()
parse()
parse_enc(c)
parse_primary(c)
class ipfs.unixfs.Inode(node, parent, link_index)

Bases: object

An Inode can be a directory, file or file block. It implements the mechanism to update the underlying node and notify its parents when a child changes.

observe(observer)

Add an observer. The observer gets notified when the node changed.

Parameters:observer – A function that takes an :py:class`Inode` as argument.
class ipfs.unixfs.FileBlock(node, parent, link_index, offset, size)

Bases: ipfs.unixfs.Inode

Files are split into blocks by unixfs. This class represents such a block.

class ipfs.unixfs.FileStream(file, mode)

Bases: io.RawIOBase

This class implements the RawIOBase interface. Thus you can use it as any other file opened by open().

close()
flush()
read(n=-1)
readable()
readall()
readinto(buf)
seek(offset, whence)
seekable()
tell()
truncate(size=None)
writable()
write()
class ipfs.unixfs.File(node, parent, link_index)

Bases: ipfs.unixfs.Inode

A unixfs file.

Call open() to open it.

open(mode='r')

Open the file.

Parameters:mode – The mode to open the file in. See io.open() for documentation.
class ipfs.unixfs.Directory(node, parent, link_index)

Bases: ipfs.unixfs.Inode

create_dir(name)
dir(path, as_child=True)
file(path, as_child=True)
listdir()
open(path, mode='r')
class ipfs.unixfs.IpnsRoot(ipns_name=None)

Bases: object

An IPNS root. It automatically updates the published IPNS record when the underlying unixfs tree changes.

NOTE: Currently not functional!

class ipfs.unixfs.UnixFs(ipfs)

Bases: object

The pivot class of the unixfs module.

dir(path)
file(path)
open(path, mode='r')

Open a unixfs file.

Parameters:
  • path – Name of the file. Either a plain base58 hash, an IPFS or IPNS name.
  • mode – The mode to open the file in. See io.open() for documentation. Defaults to “r”, which opens the file for reading in text mode.

Module contents

python3-ipfs-api

This module is a Python API for the IPFS HTTP API.

The module consists of a lowlevel API ipfs.api and some high level APIs:

  • merkledag abstracts the merkledag.
  • unixfs abstracts unixfs with pythonic file-like objects.