intessa.api — Manipulate and interact with HTTP URLs

class intessa.api.API

Represents a remote HTTP-accessible resource (and operations thereon).

Example usage:

>>> api = API(u'https://graph.facebook.com/')
>>> api
<intessa.API(u'https://graph.facebook.com/')>

Build paths using attribute access or subscription syntax:

>>> api[u'19292868552']
<intessa.API(u'https://graph.facebook.com/19292868552')>
>>> api.cocacola
<intessa.API(u'https://graph.facebook.com/cocacola')>
>>> api[u'btaylor'][u'picture']
<intessa.API(u'https://graph.facebook.com/btaylor/picture')>

Perform requests and receive responses by calling the object:

>>> api[u'19292868552']()  
<intessa.Response[200, text/javascript]>

__add__(*args, **kwargs)

Simple string concatenation is reflexive.

>>> API(u'http://example.com/') + u'foo'
<intessa.API(u'http://example.com/foo')>

__and__(*args, **kwargs)

Add parameters to this URL.

Accepts pairs or dictionaries:

>>> API(u'http://example.com/') & ('a', 'b')
<intessa.API(u'http://example.com/?a=b')>
>>> API(u'http://example.com/') & {'a': 'b'}
<intessa.API(u'http://example.com/?a=b')>

Multiple additions of the same parameter will keep all of them, in the order they were specified:

>>> API(u'http://example.com/') & ('a', 'b') & ('a', 'c')
<intessa.API(u'http://example.com/?a=b&a=c')>

__call__(*args, **kwargs)

Perform an HTTP request and return a Response.

Parameters:

• method – The HTTP method to use (defaults to GET).
• data –

  A Python object representing the body of the request.

  There are several valid values this parameter can take:

  • A bytestring, with a Content-Type header (given in headers).
  • A StreamingBody (or any file-like object which supports __len__()).
  • A file-like object, with Content-Type and Content-Length headers.
  • Any other Python object, with the type parameter provided.

  In the first two instances, it will be sent as-is. In the second, it will first be encoded to a bytestring, using the codec for the specified type.

• type – The Internet media type with which the data argument should be encoded. This will be used as a lookup type against the codec_register.
• codec_register – A CodecRegister to use for encoding the request body and decoding the response. Defaults to DEFAULT_REGISTER.
• accept –

  A specification of acceptable response types, which will be turned into an HTTP Accept header.

  This argument can be a string representing a media type (see: ContentType), a list of such strings, or a list of (media_type, quality) pairs, where quality is a floating-point number. See the documentation for make_accept_header() for examples of how this argument is turned into an Accept header.

• headers – A dictionary of raw HTTP headers to send.

Note that if a non-successful response is returned, an instance of intessa.Error will be raised.

__getattr__(*args, **kwargs)

Dynamic attribute access adds path components to the current URL.

>>> API(u'http://example.com/').users
<intessa.API(u'http://example.com/users')>

__getitem__(*args, **kwargs)

Subscription syntax is overridden to extend or modify the current URL.

Example usage:

>>> api = API(u'http://example.com/')

In the simplest case, add a path component:

>>> api['foo']
<intessa.API(u'http://example.com/foo')>
>>> api['foo']['bar']
<intessa.API(u'http://example.com/foo/bar')>

Replace the whole path by prefixing with a ‘/’:

>>> api['foo']['bar']['/baz']
<intessa.API(u'http://example.com/baz')>

Add or modify a fragment identifier:

>>> api['#foo']
<intessa.API(u'http://example.com/#foo')>
>>> api['#foo']['#bar']
<intessa.API(u'http://example.com/#bar')>

Add or modify a file extension:

>>> api['foo']['.json']
<intessa.API(u'http://example.com/foo.json')>
>>> api['foo']['.json']['.xml']
<intessa.API(u'http://example.com/foo.xml')>

Adding a file extension to a non-leaf node will add an ‘index’ component:

>>> api['.json']
<intessa.API(u'http://example.com/index.json')>

Any necessary escaping will be taken care of:

>>> api['foo bar baz']
<intessa.API(u'http://example.com/foo%20bar%20baz')>
>>> api['#foo bar#baz']
<intessa.API(u'http://example.com/#foo%20bar%23baz')>
>>> api['foo']['.js o%n']
<intessa.API(u'http://example.com/foo.js%20o%25n')>

__or__(*args, **kwargs)

Add parameters to this URL, replacing existing parameters.

Accepts pairs or dictionaries:

>>> API(u'http://example.com/') | ('a', 'b')
<intessa.API(u'http://example.com/?a=b')>
>>> API(u'http://example.com/') | {'a': 'b'}
<intessa.API(u'http://example.com/?a=b')>

Multiple additions of the same parameter will replace old values:

>>> API(u'http://example.com/') | ('a', 'b') | ('a', 'c')
<intessa.API(u'http://example.com/?a=c')>

_delete(*args, **kwargs)

Shim for issuing DELETE requests.

_post(*args, **kwargs)

Shim for issuing POST requests.

_put(*args, **kwargs)

Shim for issuing PUT requests.

_with_file_ext(*args, **kwargs)

Add/replace a file extension on this URL.

Example:

>>> API(u'http://example.com/foo')._with_file_ext('.json')
<intessa.API(u'http://example.com/foo.json')>

The leading period is optional:

>>> API(u'http://example.com/foo')._with_file_ext('json')
<intessa.API(u'http://example.com/foo.json')>

Existing file extensions will be replaced:

>>> API(u'http://example.com/foo.json')._with_file_ext('xml')
<intessa.API(u'http://example.com/foo.xml')>

This method only works on leaf nodes:

>>> API(u'http://example.com/foo/')._with_file_ext('json')
Traceback (most recent call last):
    ...
ValueError: Cannot add a file extension to directories.

_with_url(url)

Replace the URL on this API with another.