linkahead.connection.encode module

multipart/form-data encoding module.

This module provides functions that faciliate encoding name/value pairs as multipart/form-data suitable for a HTTP POST or PUT request.

multipart/form-data is the standard way to upload files over HTTP

class linkahead.connection.encode.MultipartParam(name: str, value=None, filename=None, filetype=None, filesize=None, fileobj=None, callback=None)

Bases: object

Represents a single parameter in a multipart/form-data request.

name is the name of this parameter.

If value is set, it must be a string or unicode object to use as the data for this parameter.

If filename is set, it is what to say that this parameter’s filename is. Note that this does not have to be the actual filename any local file.

If filetype is set, it is used as the Content-Type for this parameter. If unset it defaults to “text/plain; charset=utf8”

If filesize is set, it specifies the length of the file fileobj

If fileobj is set, it must be a file-like object that supports .read().

Both value and fileobj must not be set, doing so will raise a ValueError assertion.

If fileobj is set, and filesize is not specified, then the file’s size will be determined first by stat’ing fileobj’s file descriptor, and if that fails, by seeking to the end of the file, recording the current position as the size, and then by seeking back to the beginning of the file.

callback is a callable which will be called from iter_encode with (self, current_transferred, total), representing the current parameter, current amount transferred, and the total size.

encode(boundary): Returns the string encoding of this parameter.

encode_hdr(boundary): Returns the header of the encoding of this parameter.

classmethod from_file(paramname, filename)

Returns a new MultipartParam object constructed from the local file at filename.

filesize is determined by os.path.getsize(filename)

filetype is determined by mimetypes.guess_type(filename)[0]

filename is set to os.path.basename(filename)

classmethod from_params(params)

Returns a list of MultipartParam objects from a sequence of name, value pairs, MultipartParam instances, or from a mapping of names to values.

The values may be strings or file objects, or MultipartParam objects. MultipartParam object names must match the given names in the name,value pairs or mapping, if applicable.

get_size(boundary): Returns the size in bytes that this param will be when encoded with the given boundary.

iter_encode(boundary, blocksize=4096): Yields the encoding of this parameter If self.fileobj is set, then blocks of blocksize bytes are read and yielded.

reset(): Reset the file object’s read pointer.

class linkahead.connection.encode.ReadableMultiparts(multipart_yielder)

Bases: object

Wraps instances of the MultipartYielder class as a readable and withable object.

close()

read(size=-1)

linkahead.connection.encode.encode_and_quote(data: str | None) → str | None: If data is unicode, return urllib.quote_plus(data.encode(“utf-8”)) otherwise return urllib.quote_plus(data)

linkahead.connection.encode.encode_file_header(boundary, paramname, filesize, filename=None, filetype=None)

Returns the leading data for a multipart/form-data field that contains file data.

boundary is the boundary string used throughout a single request to separate variables.

paramname is the name of the variable in this request.

filesize is the size of the file data.

filename if specified is the filename to give to this field. This field is only useful to the server for determining the original filename.

filetype if specified is the MIME type of this file.

The actual file data should be sent after this header has been sent.

linkahead.connection.encode.encode_string(boundary, name, value)

Returns name and value encoded as a multipart/form-data variable.

boundary is the boundary string used throughout a single request to separate variables.

linkahead.connection.encode.gen_boundary(): Returns a random string to use as the boundary for a message.

linkahead.connection.encode.get_body_size(params, boundary): Returns the number of bytes that the multipart/form-data encoding of params will be.

linkahead.connection.encode.get_headers(params, boundary): Returns a dictionary with Content-Type and Content-Length headers for the multipart/form-data encoding of params.

linkahead.connection.encode.multipart_encode(params, boundary=None, callback=None)

Encode params as multipart/form-data.

params should be a sequence of (name, value) pairs or MultipartParam objects, or a mapping of names to values. Values are either strings parameter values, or file-like objects to use as the parameter value. The file-like objects must support .read() and either .fileno() or both .seek() and .tell().

If boundary is set, then it as used as the MIME boundary. Otherwise a randomly generated boundary will be used. In either case, if the boundary string appears in the parameter values a ValueError will be raised.

If callback is set, it should be a callback which will get called as blocks of data are encoded. It will be called with (param, current_transferred, total), indicating the current parameter being encoded, the current amount encoded, and the total amount to encode.

Returns a tuple of datagen, headers, where datagen is a generator that will yield blocks of data that make up the encoded parameters, and headers is a dictionary with the assoicated Content-Type and Content-Length headers.

Examples:

>>> datagen, headers = multipart_encode( [("key", "value1"), ("key", "value2")] )
>>> s = "".join(datagen)
>>> assert "value2" in s and "value1" in s

>>> p = MultipartParam("key", "value2")
>>> datagen, headers = multipart_encode( [("key", "value1"), p] )
>>> s = "".join(datagen)
>>> assert "value2" in s and "value1" in s

>>> datagen, headers = multipart_encode( {"key": "value1"} )
>>> s = "".join(datagen)
>>> assert "value2" not in s and "value1" in s