Internal API Reference¶
encoding
¶
Defines encoding related classes.
Note
The XML and ProtoBuf encoders are currently not functional.
-
class
ipfsapi.encoding.
Encoding
[source]¶ Bases:
object
Abstract base for a data parser/encoder interface.
-
parse_partial
(raw)[source]¶ 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
()[source]¶ Finalizes parsing based on remaining buffered data and yields the remaining data sets.
Raises: DecodingError
Returns: generator
-
parse
(raw)[source]¶ Returns a Python object decoded from the bytes of this encoding.
Raises: DecodingError
Parameters: raw (bytes) – Data to be parsed Returns: object
-
encode
(obj)[source]¶ Serialize a raw object into corresponding encoding.
Raises: EncodingError
Parameters: obj (object) – Object to be encoded
-
-
class
ipfsapi.encoding.
Dummy
[source]¶ Bases:
ipfsapi.encoding.Encoding
Dummy parser/encoder that does nothing.
-
class
ipfsapi.encoding.
Json
[source]¶ Bases:
ipfsapi.encoding.Encoding
JSON parser/encoder that handles concatenated JSON.
-
parse_partial
(data)[source]¶ Incrementally decodes JSON data sets into Python objects.
Raises: DecodingError
Returns: generator
-
parse_finalize
()[source]¶ 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)[source]¶ 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
[source]¶ Bases:
ipfsapi.encoding.Encoding
Python object parser/encoder using pickle.
-
parse_partial
(raw)[source]¶ 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
()[source]¶ Parses the buffered data and yields the result.
Raises: DecodingError
Returns: generator
-
parse
(raw)[source]¶ 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)[source]¶ Returns
obj
serialized as a pickle binary string.Raises: EncodingError
Parameters: obj (object) – Serializable Python object Returns: bytes
-
-
class
ipfsapi.encoding.
Protobuf
[source]¶ Bases:
ipfsapi.encoding.Encoding
Protobuf parser/encoder that handles protobuf.
-
class
ipfsapi.encoding.
Xml
[source]¶ Bases:
ipfsapi.encoding.Encoding
XML parser/encoder that handles XML.
-
ipfsapi.encoding.
get_encoding
(name)[source]¶ 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)[source]¶ 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)[source]¶ Bases:
object
An HTTP client for interacting with the IPFS daemon.
Parameters: -
request
(*args, **kwargs)[source]¶ Makes an HTTP request to the IPFS daemon.
This function returns the contents of the HTTP response from the IPFS daemon.
Raises: 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)[source]¶ 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: 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
-
multipart
¶
HTTP multipart/*-encoded file streaming.
-
ipfsapi.multipart.
content_disposition
(fn, disptype='file')[source]¶ 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:
-
ipfsapi.multipart.
content_type
(fn)[source]¶ 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')[source]¶ 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:
-
class
ipfsapi.multipart.
BodyGenerator
(name, disptype='file', subtype='mixed', boundary=None)[source]¶ Bases:
object
Generators for creating the body of a multipart/* HTTP request.
Parameters:
-
class
ipfsapi.multipart.
BufferedGenerator
(name, chunk_size=4096)[source]¶ Bases:
object
Generator that encodes multipart/form-data.
An abstract buffered generator class which encodes multipart/form-data.
Parameters: -
file_chunks
(fp)[source]¶ 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)[source]¶ 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
-
-
class
ipfsapi.multipart.
FileStream
(files, chunk_size=4096)[source]¶ 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:
-
ipfsapi.multipart.
glob_compile
(pat)[source]¶ 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)[source]¶ 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:
-
class
ipfsapi.multipart.
BytesStream
(data, chunk_size=4096)[source]¶ Bases:
ipfsapi.multipart.BufferedGenerator
A buffered generator that encodes bytes as multipart/form-data.
Parameters:
-
ipfsapi.multipart.
stream_files
(files, chunk_size=4096)[source]¶ 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:
-
ipfsapi.multipart.
stream_directory
(directory, recursive=False, patterns='**', chunk_size=4096)[source]¶ 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)[source]¶ 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)[source]¶ 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: Returns: (generator, dict)
utils
¶
A module to handle generic operations.
-
ipfsapi.utils.
guess_mimetype
(filename)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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