gs.form Documentation

This package provides a useful way of pushing data to a server by making a POST to a form. While originally written for GroupServer, there is nothing specific to GroupServer in this product. Mostly it is a light facade around the requests library, which you should use <http://requests.readthedocs.org>.

Contents:

gs.form API Reference

The package exports the following API symbols.

gs.form.post_multipart(netloc, selector, fields, files=None, usessl=False)[source]

Post fields and files to an http host as multipart/form-data.

Parameters:
  • netloc (str) – The netloc (host or host:port).
  • selector (str) – The path to the form that will be posted to.
  • fields (list) – A sequence of (name, value) 2-tuple elements for regular form fields.
  • files (list) – A sequence of (name, filename, value) 3-tuple elements for data to be uploaded as files
  • usessl (bool) – True if TLS should be used to communicate with the server.
Returns:

The reponse-status
Return type:

gs.form.Response
Example:

Post three normal form fields (parrot, piranah, and ethyl) and one file (the text file rule.txt, sent as the unwritten form field) to example.com on port 2585, using normal HTTP rather than TLS (the default):

fields = [('parrot', 'dead'), ('piranha', 'brother'),
          ('ethyl', 'frog')]
files = [('unwritten', 'rule.txt', 'This is a transgression.')]
r = post_multipart('example.com:2585', '/form.html', fields, files)
status, reason, text = r
class gs.form.Response(status, reason, text)

Response from the server

status

The status code

reason

The short reason for the staus

text

The text of the document returned by the server.

Internals

gs.form.postmultipart.files_to_dict(files)[source]

Turn a list of file-info tuples into a dict for requests.post

Parameters:files (list) – A list of 3-tuples (field name, filename, data)
Returns:A dictionary of files.
Return type:dict

The field names are returned as keys, and the file-data is represented as 2-tuples: filename, file. The data is converted from a string (bytes or Unicode) to either a io.BytesIO or io.StringIO.

Changelog

3.0.0 (2015-06-12)

2.2.1 (2015-04-15)

2.2.0 (2014-05-05)

  • Added unit tests.
  • Refactored code into smaller modules and functions.
  • Added docstrings
  • Added Sphinx support
  • Added Python 3 support

1.1.1 (2014-01-23)

  • Metadata cleanup for the product.
  • PEP-8 tidy.
  • Switch to Unicode literals.

1.1.0 (2012-08-01)

  • Added SSL (TLS) support.

1.0.1 (2012-07-30)

  • Support Unicode properly.

1.0.0 (2012-07-16)

  • Added post_multipart to the module
  • Moved the user-interface code to gs.content.form
  • Renamed this module gs.form.

Indices and tables