Internal API Reference

encoding

Defines encoding related classes.

Note

The XML and ProtoBuf encoders are currently not functional.

class ipfsapi.encoding.Encoding

Bases: object

Abstract base for a data parser/encoder interface.

parse_partial(raw)

Parses the given data and yields all complete data sets that can be built from this.

Raises:DecodingError Parameters:raw (bytes) – Data to be parsed Returns:generator

parse_finalize()

Finalizes parsing based on remaining buffered data and yields the remaining data sets.

Raises:DecodingError Returns:generator

parse(raw)

Returns a Python object decoded from the bytes of this encoding.

Raises:DecodingError Parameters:raw (bytes) – Data to be parsed Returns:object

encode(obj)

Serialize a raw object into corresponding encoding.

Raises:EncodingError Parameters:obj (object) – Object to be encoded

class ipfsapi.encoding.Dummy

Bases: ipfsapi.encoding.Encoding

Dummy parser/encoder that does nothing.

parse_partial(raw)

Yields the data passed into this method.

Parameters:raw (bytes) – Any kind of data Returns:generator

encode(obj)

Returns the bytes representation of the data passed into this function.

Parameters:obj (object) – Any Python object Returns:bytes

class ipfsapi.encoding.Json

Bases: ipfsapi.encoding.Encoding

JSON parser/encoder that handles concatenated JSON.

parse_partial(data)

Incrementally decodes JSON data sets into Python objects.

Raises:DecodingError Returns:generator

parse_finalize()

Raises errors for incomplete buffered data that could not be parsed because the end of the input data has been reached.

Raises:DecodingError Returns:tuple (Always empty)

encode(obj)

Returns obj serialized as JSON formatted bytes.

Raises:EncodingError Parameters:obj (str | list | dict | int) – JSON serializable Python object Returns:bytes

class ipfsapi.encoding.Pickle

Bases: ipfsapi.encoding.Encoding

Python object parser/encoder using pickle.

parse_partial(raw)

Buffers the given data so that the it can be passed to pickle in one go.

This does not actually process the data in smaller chunks, but merely buffers it until parse_finalize is called! This is mostly because the standard-library module expects the entire data to be available up front, which is currently always the case for our code anyways.

Parameters:raw (bytes) – Data to be buffered Returns:tuple (An empty tuple)

parse_finalize()

Parses the buffered data and yields the result.

Raises:DecodingError Returns:generator

parse(raw)

Returns a Python object decoded from a pickle byte stream.

>>> p = Pickle()
>>> p.parse(b'(lp0\nI1\naI2\naI3\naI01\naF4.5\naNaF6000.0\na.')
[1, 2, 3, True, 4.5, None, 6000.0]

Raises:DecodingError Parameters:raw (bytes) – Pickle data bytes Returns:object

encode(obj)

Returns obj serialized as a pickle binary string.

Raises:EncodingError Parameters:obj (object) – Serializable Python object Returns:bytes

class ipfsapi.encoding.Protobuf

Bases: ipfsapi.encoding.Encoding

Protobuf parser/encoder that handles protobuf.

class ipfsapi.encoding.Xml

Bases: ipfsapi.encoding.Encoding

XML parser/encoder that handles XML.

ipfsapi.encoding.get_encoding(name)

Returns an Encoder object for the named encoding

Raises:EncoderMissingError Parameters:name (str) –

Encoding name. Supported options:

• "none"
• "json"
• "pickle"
• "protobuf"
• "xml"

http

HTTP client for api requests.

This is pluggable into the IPFS Api client and will hopefully be supplemented by an asynchronous version.

ipfsapi.http.pass_defaults(func)

Decorator that returns a function named wrapper.

When invoked, wrapper invokes func with default kwargs appended.

Parameters:func (callable) – The function to append the default kwargs to

class ipfsapi.http.HTTPClient(host, port, base, **defaults)

Bases: object

An HTTP client for interacting with the IPFS daemon.

Parameters:

• host (str) – The host the IPFS daemon is running on
• port (int) – The port the IPFS daemon is running at
• base (str) – The path prefix for API calls
• defaults (dict) – The default parameters to be passed to request()

request(*args, **kwargs)

Makes an HTTP request to the IPFS daemon.

This function returns the contents of the HTTP response from the IPFS daemon.

Raises:

• ErrorResponse
• ConnectionError
• ProtocolError
• StatusError
• TimeoutError

Parameters:

• path (str) – The REST command path to send
• args (list) – Positional parameters to be sent along with the HTTP request
• files (io.RawIOBase | str | list) – The file object(s) or path(s) to stream to the daemon
• opts (dict) – Query string paramters to be sent along with the HTTP request
• decoder (str) – The encoder to use to parse the HTTP response
• kwargs (dict) – Additional arguments to pass to requests

download(*args, **kwargs)

Makes a request to the IPFS daemon to download a file.

Downloads a file or files from IPFS into the current working directory, or the directory given by filepath.

Raises:

• ErrorResponse
• ConnectionError
• ProtocolError
• StatusError
• TimeoutError

Parameters:

• path (str) – The REST command path to send
• filepath (str) –

  The local path where IPFS will store downloaded files

  Defaults to the current working directory.

• args (list) – Positional parameters to be sent along with the HTTP request
• opts (dict) – Query string paramters to be sent along with the HTTP request
• compress (bool) – Whether the downloaded file should be GZip compressed by the daemon before being sent to the client
• kwargs (dict) – Additional arguments to pass to requests

session(*args, **kwds)

A context manager for this client’s session.

This function closes the current session when this client goes out of scope.

multipart

HTTP multipart/*-encoded file streaming.

ipfsapi.multipart.content_disposition(fn, disptype='file')

Returns a dict containing the MIME content-disposition header for a file.

>>> content_disposition('example.txt')
{'Content-Disposition': 'file; filename="example.txt"'}

>>> content_disposition('example.txt', 'attachment')
{'Content-Disposition': 'attachment; filename="example.txt"'}

Parameters:

• fn (str) – Filename to retrieve the MIME content-disposition for
• disptype (str) – Rhe disposition type to use for the file

ipfsapi.multipart.content_type(fn)

Returns a dict with the content-type header for a file.

Guesses the mimetype for a filename and returns a dict containing the content-type header.

>>> content_type('example.txt')
{'Content-Type': 'text/plain'}

>>> content_type('example.jpeg')
{'Content-Type': 'image/jpeg'}

>>> content_type('example')
{'Content-Type': 'application/octet-stream'}

Parameters:fn (str) – Filename to guess the content-type for

ipfsapi.multipart.multipart_content_type(boundary, subtype='mixed')

Creates a MIME multipart header with the given configuration.

Returns a dict containing a MIME multipart header with the given boundary.

>>> multipart_content_type('8K5rNKlLQVyreRNncxOTeg')
{'Content-Type': 'multipart/mixed; boundary="8K5rNKlLQVyreRNncxOTeg"'}

>>> multipart_content_type('8K5rNKlLQVyreRNncxOTeg', 'alt')
{'Content-Type': 'multipart/alt; boundary="8K5rNKlLQVyreRNncxOTeg"'}

Parameters:

• boundry (str) – The content delimiter to put into the header
• subtype (str) – The subtype in multipart/*-domain to put into the header

class ipfsapi.multipart.BodyGenerator(name, disptype='file', subtype='mixed', boundary=None)

Bases: object

Generators for creating the body of a multipart/* HTTP request.

Parameters:

• name (str) – The filename of the file(s)/content being encoded
• disptype (str) – The Content-Disposition of the content
• subtype (str) – The multipart/*-subtype of the content
• boundary (str) – An identifier used as a delimiter for the content’s body

write_headers()

Yields the HTTP header text for the content.

open(**kwargs)

Yields the body section for the content.

file_open(fn)

Yields the opening text of a file section in multipart HTTP.

Parameters:fn (str) – Filename for the file being opened and added to the HTTP body

file_close()

Yields the end text of a file section in HTTP multipart encoding.

close()

Yields the ends of the content area in a HTTP multipart body.

class ipfsapi.multipart.BufferedGenerator(name, chunk_size=4096)

Bases: object

Generator that encodes multipart/form-data.

An abstract buffered generator class which encodes multipart/form-data.

Parameters:

• name (str) – The name of the file to encode
• chunk_size (int) – The maximum size that any single file chunk may have in bytes

file_chunks(fp)

Yields chunks of a file.

Parameters:fp (io.RawIOBase) – The file to break into chunks (must be an open file or have the readinto method)

gen_chunks(gen)

Generates byte chunks of a given size.

Takes a bytes generator and yields chunks of a maximum of chunk_size bytes.

Parameters:gen (generator) – The bytes generator that produces the bytes

body(*args, **kwargs)

Returns the body of the buffered file.

Note

This function is not actually implemented.

close()

Yields the closing text of a multipart envelope.

class ipfsapi.multipart.FileStream(files, chunk_size=4096)

Bases: ipfsapi.multipart.BufferedGenerator

Generator that encodes multiples files into HTTP multipart.

A buffered generator that encodes an array of files as multipart/form-data. This is a concrete implementation of BufferedGenerator.

Parameters:

• name (str) – The filename of the file to encode
• chunk_size (int) – The maximum size that any single file chunk may have in bytes

body()

Yields the body of the buffered file.

ipfsapi.multipart.glob_compile(pat)

Translate a shell glob PATTERN to a regular expression.

This is almost entirely based on fnmatch.translate source-code from the python 3.5 standard-library.

class ipfsapi.multipart.DirectoryStream(directory, recursive=False, patterns='**', chunk_size=4096)

Bases: ipfsapi.multipart.BufferedGenerator

Generator that encodes a directory into HTTP multipart.

A buffered generator that encodes an array of files as multipart/form-data. This is a concrete implementation of BufferedGenerator.

Parameters:

• directory (str) – The filepath of the directory to encode
• patterns (str | list) – A single glob pattern or a list of several glob patterns and compiled regular expressions used to determine which filepaths to match
• chunk_size (int) – The maximum size that any single file chunk may have in bytes

body()

Returns the HTTP headers for this directory upload request.

headers()

Returns the HTTP body for this directory upload request.

class ipfsapi.multipart.BytesStream(data, chunk_size=4096)

Bases: ipfsapi.multipart.BufferedGenerator

A buffered generator that encodes bytes as multipart/form-data.

Parameters:

• data (bytes) – The binary data to stream to the daemon
• chunk_size (int) – The maximum size of a single data chunk

body()

Yields the encoded body.

ipfsapi.multipart.stream_files(files, chunk_size=4096)

Gets a buffered generator for streaming files.

Returns a buffered generator which encodes a file or list of files as multipart/form-data with the corresponding headers.

Parameters:

• files (str) – The file(s) to stream
• chunk_size (int) – Maximum size of each stream chunk

ipfsapi.multipart.stream_directory(directory, recursive=False, patterns='**', chunk_size=4096)

Gets a buffered generator for streaming directories.

Returns a buffered generator which encodes a directory as multipart/form-data with the corresponding headers.

Parameters:

• directory (str) – The filepath of the directory to stream
• recursive (bool) – Stream all content within the directory recursively?
• patterns (str | list) – Single glob pattern or list of glob patterns and compiled regular expressions to match the names of the filepaths to keep
• chunk_size (int) – Maximum size of each stream chunk

ipfsapi.multipart.stream_filesystem_node(path, recursive=False, patterns='**', chunk_size=4096)

Gets a buffered generator for streaming either files or directories.

Returns a buffered generator which encodes the file or directory at the given path as multipart/form-data with the corresponding headers.

Parameters:

• path (str) – The filepath of the directory or file to stream
• recursive (bool) – Stream all content within the directory recursively?
• patterns (str | list) – Single glob pattern or list of glob patterns and compiled regular expressions to match the names of the filepaths to keep
• chunk_size (int) – Maximum size of each stream chunk

ipfsapi.multipart.stream_bytes(data, chunk_size=4096)

Gets a buffered generator for streaming binary data.

Returns a buffered generator which encodes binary data as multipart/form-data with the corresponding headers.

Parameters:

• data (bytes) – The data bytes to stream
• chunk_size (int) – The maximum size of each stream chunk

Returns:

(generator, dict)

ipfsapi.multipart.stream_text(text, chunk_size=4096)

Gets a buffered generator for streaming text.

Returns a buffered generator which encodes a string as multipart/form-data with the corresponding headers.

Parameters:

• text (str) – The data bytes to stream
• chunk_size (int) – The maximum size of each stream chunk

Returns:

(generator, dict)

utils

A module to handle generic operations.

ipfsapi.utils.guess_mimetype(filename)

Guesses the mimetype of a file based on the given filename.

>>> guess_mimetype('example.txt')
'text/plain'
>>> guess_mimetype('/foo/bar/example')
'application/octet-stream'

Parameters:filename (str) – The file name or path for which the mimetype is to be guessed

ipfsapi.utils.ls_dir(dirname)

Returns files and subdirectories within a given directory.

Returns a pair of lists, containing the names of directories and files in dirname.

Raises:OSError : Accessing the given directory path failed Parameters:dirname (str) – The path of the directory to be listed

ipfsapi.utils.clean_file(file)

Returns a tuple containing a file-like object and a close indicator.

This ensures the given file is opened and keeps track of files that should be closed after use (files that were not open prior to this function call).

Raises:OSError : Accessing the given file path failed Parameters:file (str | io.IOBase) – A filepath or file-like object that may or may not need to be opened

ipfsapi.utils.clean_files(files)

Generates tuples with a file-like object and a close indicator.

This is a generator of tuples, where the first element is the file object and the second element is a boolean which is True if this module opened the file (and thus should close it).

Raises:OSError : Accessing the given file path failed Parameters:files (list | io.IOBase | str) – Collection or single instance of a filepath and file-like object

ipfsapi.utils.file_size(f)

Returns the size of a file in bytes.

Raises:OSError : Accessing the given file path failed Parameters:f (io.IOBase | str) – The file path or object for which the size should be determined

class ipfsapi.utils.return_field(field)

Bases: object

Decorator that returns the given field of a json response.

Parameters:field (object) – The response field to be returned for all invocations

__call__(cmd)

Wraps a command so that only a specified field is returned.

Parameters:cmd (callable) – A command that is intended to be wrapped