Internal HTTP Client Reference

encoding

Classes for encoding and decoding datastreams into object values

class ipfshttpclient.encoding.Dummy

Bases: ipfshttpclient.encoding.Encoding

Dummy parser/encoder that does nothing

encode(obj)

Returns the bytes representation of the data passed into this function

Parameters

obj (bytes) – Any Python object

Return type

bytes

parse_partial(raw)

Yields the data passed into this method

Parameters

raw (bytes) – Any kind of data

Return type

Generator[bytes, Any, Any]

class ipfshttpclient.encoding.Encoding

Bases: typing.Generic

Abstract base for a data parser/encoder interface

abstract encode(obj)

Serializes the given Python object to a bytes string

Raises

EncodingError –

Parameters

obj (~T) – Object to be encoded

Return type

bytes

parse_finalize()

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

Raises

DecodingError –

Return type

Generator[~T, Any, Any]

abstract 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

Return type

Generator[~T, Any, Any]

class ipfshttpclient.encoding.Json

Bases: ipfshttpclient.encoding.Encoding

JSON parser/encoder that handles concatenated JSON

encode(obj)

Returns obj serialized as JSON formatted bytes

Raises

EncodingError –

Parameters

obj (Union[bool, float, int, str, ForwardRef, ForwardRef]) – JSON serializable Python object

Return type

bytes

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 –

Return type

Generator[Union[bool, float, int, str, ForwardRef, ForwardRef], Any, Any]

parse_partial(data)

Incrementally decodes JSON data sets into Python objects.

Raises

DecodingError –

ipfshttpclient.encoding.empty_gen()

A generator that yields nothing

Return type

Generator[~T, None, None]

ipfshttpclient.encoding.get_encoding(name: Literal[none]) → ipfshttpclient.encoding.Dummy

ipfshttpclient.encoding.get_encoding(name: Literal[json]) → ipfshttpclient.encoding.Json

Returns an Encoder object for the given encoding name

Raises

EncoderMissingError –

Parameters

name (str) –

Encoding name. Supported options:

• "none"

• "json"

Return type

Encoding[Any]

http

Default HTTP client selection proxy

class ipfshttpclient.http.ClientSync(addr, base, *, offline=False, workarounds=None, auth=None, cookies=None, headers=None, timeout=None)

Bases: ipfshttpclient.http_common.ClientSyncBase

class ipfshttpclient.http.StreamDecodeIteratorSync(closables, response, parser)

Bases: typing.Generic

Wrapper around a bytes generator that decodes and yields data as it is received, automatically closing all attached resources when the input stream ceases

Parameters

• closables (List[Closable]) – List of objects to .close() once this iterator has been exhausted or is manually closed

• response (Generator[bytes, Any, Any]) –

  Generator returning the bytes to decode and yield

  Will be closed in addition to all objects in closables when the time comes.

• parser (Encoding[+T_co]) – Decoder (see Encoding) that takes the bytes yielded by response and emits decoded Python objects.

multipart

HTTP multipart/*-encoded file streaming.

class ipfshttpclient.multipart.BytesFileStream(data, name='bytes', *, chunk_size=8192)

Bases: ipfshttpclient.multipart.FilesStream

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

Parameters

• data (Union[bytes, Generator[bytes, Any, Any]]) – The binary data to stream to the daemon

• name (str) – The filename to report to the daemon for this upload

• chunk_size (int) – The maximum size of a single data chunk

body()

Yields the encoded body.

Return type

Generator[bytes, Any, Any]

class ipfshttpclient.multipart.DirectoryStream(directory, *, chunk_size=8192, follow_symlinks=False, patterns=None, period_special=True, recursive=False)

Bases: ipfshttpclient.multipart.StreamBase, ipfshttpclient.multipart.StreamFileMixin, typing.Generic

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 StreamBase.

Parameters

• directory (Union[AnyStr, PathLike[AnyStr], int]) –

  The filepath or file descriptor of the directory to encode

  File descriptors are only supported on Unix.

• dirpath –

  The path to the directory being uploaded, if this is absolute it will be included in a header for each emitted file and enables use of the no-copy filestore facilities

  If the wrap_with_directory attribute is True during upload the string dirpath.name if dirpath else '_' will be visible as the name of the uploaded directory within its wrapper.

• chunk_size (int) – The maximum size that any single file chunk may have in bytes

• patterns (Union[Iterable[Union[AnyStr, Pattern, Matcher[AnyStr]]], AnyStr, Pattern, Matcher[AnyStr], None]) –

  One or several glob patterns or compiled regular expression objects used to determine which files to upload

  Only files or directories matched by any of these patterns will be uploaded. If a directory is not matched directly but contains at least one file or directory below it that is, it will be included in the upload as well but will not include other items. If a directory matches any of the given patterns and recursive is then it, as well as all other files and directories below it, will be included as well.

• period_special (bool) – Whether a leading period in file/directory names should be matchable by *, ? and […] – traditionally they are not, but many modern shells allow one to disable this behaviour

class ipfshttpclient.multipart.FilesStream(files, name='files', chunk_size=8192)

Bases: ipfshttpclient.multipart.StreamBase, ipfshttpclient.multipart.StreamFileMixin

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 StreamBase.

Parameters

• files (Union[str, PathLike, bytes, IO[bytes], int, Iterable[Union[str, PathLike, bytes, IO[bytes], int]]]) – The name, file object or file descriptor of the file to encode; may also be a list of several items to allow for more efficient batch processing

• chunk_size (int) – The maximum size that any single file chunk may have in bytes

class ipfshttpclient.multipart.StreamBase(name, chunk_size=8192)

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

body()

Yields the body of this stream.

Return type

Generator[bytes, Any, Any]

ipfshttpclient.multipart.content_disposition_headers(filename, disptype='form-data; name="file"')

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

>>> content_disposition_headers('example.txt')
{'Content-Disposition': 'form-data; filename="example.txt"'}

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

Parameters

• filename (str) – Filename to retrieve the MIME content-disposition for

• disptype (str) – Rhe disposition type to use for the file

Return type

Dict[str, str]

ipfshttpclient.multipart.content_type_headers(filename, content_type=None)

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_headers('example.txt')
{'Content-Type': 'text/plain'}

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

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

Parameters

• filename (str) – Filename to guess the content-type for

• content_type (Optional[str]) – The Content-Type to use; if not set a content type will be guessed

Return type

Dict[str, str]

ipfshttpclient.multipart.multipart_content_type_headers(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_headers('8K5rNKlLQVyreRNncxOTeg')
{'Content-Type': 'multipart/mixed; boundary="8K5rNKlLQVyreRNncxOTeg"'}

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

Parameters

• boundary (str) – The content delimiter to put into the header

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

Return type

Dict[str, str]

ipfshttpclient.multipart.stream_bytes(data, *, chunk_size=8192)

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 (Union[bytes, Generator[bytes, Any, Any]]) – The data bytes to stream

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

Return type

Tuple[Generator[bytes, Any, Any], Dict[str, str]]

ipfshttpclient.multipart.stream_directory(directory, *, chunk_size=8192, follow_symlinks=False, patterns=None, period_special=True, recursive=False)

Returns buffered generator yielding the contents of a directory

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

For the meaning of these parameters see the description of DirectoryStream.

Return type

Tuple[Generator[bytes, Any, Any], Dict[str, str]]

ipfshttpclient.multipart.stream_files(files, *, chunk_size=8192)

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 (Union[str, PathLike, bytes, IO[bytes], int, Iterable[Union[str, PathLike, bytes, IO[bytes], int]]]) – The file(s) to stream

• chunk_size (int) – Maximum size of each stream chunk

Return type

Tuple[Generator[bytes, Any, Any], Dict[str, str]]

ipfshttpclient.multipart.stream_filesystem_node(filepaths, *, chunk_size=8192, follow_symlinks=False, patterns=None, period_special=True, recursive=False)

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

• filepaths (Union[AnyStr, PathLike[AnyStr], int, Iterable[Union[AnyStr, PathLike[AnyStr]]]]) – The filepath of a single directory or one or more files to stream

• chunk_size (int) – Maximum size of each stream chunk

• follow_symlinks (bool) – Follow symbolic links when recursively scanning directories? (directories only)

• period_special (bool) –

  Treat files and directories with a leading period character (“dot-files”) specially in glob patterns? (directories only)

  If this is set these files will only be matched by path labels whose initial character is a period as well.

• patterns (Union[Iterable[Union[AnyStr, Pattern, Matcher[AnyStr]]], AnyStr, Pattern, Matcher[AnyStr], None]) – Single glob pattern or list of glob patterns and compiled regular expressions to match the paths of files and directories to be added to IPFS (directories only)

• recursive (bool) – Scan directories recursively for additional files? (directories only)

Return type

Tuple[Generator[bytes, Any, Any], Dict[str, str], bool]

ipfshttpclient.multipart.stream_text(text, *, chunk_size=8192)

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 (Union[str, Iterable[str]]) – The data bytes to stream

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

Return type

Tuple[Generator[bytes, Any, Any], Dict[str, str]]

utils

A module to handle generic operations.

class ipfshttpclient.utils.PathLike(*args, **kwargs)

Bases: typing.Protocol

class ipfshttpclient.utils.json_dict_t

Bases: dict, typing.Generic

class ipfshttpclient.utils.json_list_t(iterable=(), /)

Bases: list, typing.Generic

class ipfshttpclient.utils.return_field(field)

Bases: typing.Generic

Decorator that returns the given field of a json response.

Parameters

field (str) – The response field to be returned for all invocations

__call__(cmd)

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

Parameters

cmd (~F) – A command that is intended to be wrapped

Return type

Callable[…, ~T]

ipfshttpclient.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 (Union[str, PathLike, bytes, IO[bytes], int]) – A filepath or file-like object that may or may not need to be opened

Return type

Tuple[IO[bytes], bool]

ipfshttpclient.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 (Union[str, PathLike, bytes, IO[bytes], int, Iterable[Union[str, PathLike, bytes, IO[bytes], int]]]) – Collection or single instance of a filepath and file-like object

Return type

Generator[Tuple[IO[bytes], bool], Any, Any]

ipfshttpclient.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

Return type

str

ipfshttpclient.utils.maybe_fsencode(val, ref)

Encodes the string val using the system filesystem encoding if ref is of type :type:`bytes`

Return type

AnyStr