poster package¶

Submodules¶

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

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)¶

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.

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

poster.streaminghttp module¶

Streaming HTTP uploads module.

This module extends the standard httplib and urllib2 objects so that iterable objects can be used in the body of HTTP requests.

In most cases all one should have to do is call register_openers() to register the new streaming http handlers which will take priority over the default handlers, and then you can use iterable objects in the body of HTTP requests.

N.B. You must specify a Content-Length header if using an iterable object since there is no way to determine in advance the total size that will be yielded, and there is no way to reset an interator.

Example usage:

>>> from StringIO import StringIO
>>> import urllib2, poster.streaminghttp

>>> opener = poster.streaminghttp.register_openers()

>>> s = "Test file data"
>>> f = StringIO(s)

>>> req = urllib2.Request("http://localhost:5000", f,
...                       {'Content-Length': str(len(s))})

class poster.streaminghttp.StreamingHTTPConnection(host, port=None, strict=None, timeout=<object object>, source_address=None)¶

Bases: poster.streaminghttp._StreamingHTTPMixin, httplib.HTTPConnection

Subclass of httplib.HTTPConnection that overrides the send() method to support iterable body objects

class poster.streaminghttp.StreamingHTTPRedirectHandler¶

Bases: urllib2.HTTPRedirectHandler

Subclass of urllib2.HTTPRedirectHandler that overrides the redirect_request method to properly handle redirected POST requests

This class is required because python 2.5’s HTTPRedirectHandler does not remove the Content-Type or Content-Length headers when requesting the new resource, but the body of the original request is not preserved.

handler_order = 499¶

redirect_request(req, fp, code, msg, headers, newurl)¶

Return a Request or None in response to a redirect.

This is called by the http_error_30x methods when a redirection response is received. If a redirection should take place, return a new Request to allow http_error_30x to perform the redirect. Otherwise, raise HTTPError if no-one else should try to handle this url. Return None if you can’t but another Handler might.

class poster.streaminghttp.StreamingHTTPHandler(debuglevel=0)¶

Bases: urllib2.HTTPHandler

Subclass of urllib2.HTTPHandler that uses StreamingHTTPConnection as its http connection class.

handler_order = 499¶

http_open(req)¶: Open a StreamingHTTPConnection for the given request

http_request(req)¶: Handle a HTTP request. Make sure that Content-Length is specified if we’re using an interable value

poster.streaminghttp.register_openers()¶

Register the streaming http handlers in the global urllib2 default opener object.

Returns the created OpenerDirector object.

class poster.streaminghttp.StreamingHTTPSHandler(debuglevel=0)¶

Bases: urllib2.HTTPSHandler

Subclass of urllib2.HTTPSHandler that uses StreamingHTTPSConnection as its http connection class.

handler_order = 499¶

https_open(req)¶

https_request(req)¶

class poster.streaminghttp.StreamingHTTPSConnection(host, port=None, key_file=None, cert_file=None, strict=None, timeout=<object object>, source_address=None)¶

Bases: poster.streaminghttp._StreamingHTTPMixin, httplib.HTTPSConnection

Subclass of httplib.HTTSConnection that overrides the send() method to support iterable body objects

Module contents¶

poster module

Support for streaming HTTP uploads, and multipart/form-data encoding

`poster.version` is a 3-tuple of integers representing the version number. New releases of poster will always have a version number that compares greater than an older version of poster. New in version 0.6.