poster.encode

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

poster.encode.gen_boundary()

Returns a random string to use as the boundary for a message

poster.encode.encode_and_quote(data)

If data is unicode, return urllib.quote_plus(data.encode(“utf-8”)) otherwise return urllib.quote_plus(data)

class poster.encode.MultipartParam(name, value=None, filename=None, filetype=None, filesize=None, fileobj=None, cb=None)

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.

cb is a callable which will be called from iter_encode with (self, current, 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()
poster.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.

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

poster.encode.get_body_size(params, boundary)

Returns the number of bytes that the multipart/form-data encoding of params will be.

poster.encode.get_headers(params, boundary)

Returns a dictionary with Content-Type and Content-Length headers for the multipart/form-data encoding of params.

poster.encode.multipart_encode(params, boundary=None, cb=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 cb is set, it should be a callback which will get called as blocks of data are encoded. It will be called with (param, current, 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

Previous topic

poster - poster module reference

Next topic

poster.streaminghttp

This Page