aiocouchdb 0.9.0-dev documentation

Common Base Objects

«  CouchDB 1.x API   ::   Contents

Common Base Objects

Client

class aiocouchdb.client.HttpRequest(method, url, *, params=None, headers=None, data=None, cookies=None, files=None, auth=None, encoding='utf-8', version=HttpVersion(major=1, minor=1), compress=None, chunked=None, expect100=False, loop=None, response_class=None)[source]

aiohttp.client.ClientRequest class with CouchDB specifics.

DEFAULT_HEADERS = {'ACCEPT': 'application/json', 'CONTENT-TYPE': 'application/json', 'ACCEPT-ENCODING': 'gzip, deflate'}

Default HTTP request headers.

update_body_from_data(data)[source]

Encodes data as JSON if Content-Type is application/json.

class aiocouchdb.client.HttpResponse(method, url, host='', *, writer=None, continue100=None)[source]

Deviation from aiohttp.client.ClientResponse class for CouchDB specifics. Prefers FlowControlChunksQueue flow control which fits the best to handle chunked responses.

flow_control_class

alias of FlowControlChunksQueue

maybe_raise_error()[source]

Raises an HttpErrorException if response status code is greater or equal 400.

read()[source]

Read response payload.

class aiocouchdb.client.HttpStreamResponse(method, url, host='', *, writer=None, continue100=None)[source]

Like HttpResponse, but uses FlowControlStreamReader to handle nicely large non-chunked data streams.

class aiocouchdb.client.Resource(url, *, request_class=None, response_class=None)[source]

HTTP resource representation. Accepts full url as argument.

>>> res = Resource('http://localhost:5984')
>>> res  
<aiocouchdb.client.Resource(http://localhost:5984) object at ...>

Able to construct new Resource instance by assemble base URL and path sections on call:

>>> new_res = res('foo', 'bar/baz')
>>> assert new_res is not res
>>> new_res.url
'http://localhost:5984/foo/bar%2Fbaz'
apply_auth(auth_provider, url, headers)[source]

Applies authentication routines on further request.

Parameters:
  • auth_provideraiocouchdb.authn.AuthProvider instance
  • url (str) – Request URL
  • headers (dict) – Request headers
copy(path=None, **options)[source]

Makes COPY request to the resource. See Resource.request() for arguments definition.

delete(path=None, **options)[source]

Makes DELETE request to the resource. See Resource.request() for arguments definition.

get(path=None, **options)[source]

Makes GET request to the resource. See Resource.request() for arguments definition.

head(path=None, **options)[source]

Makes HEAD request to the resource. See Resource.request() for arguments definition.

options(path=None, **options)[source]

Makes OPTIONS request to the resource. See Resource.request() for arguments definition.

post(path=None, **options)[source]

Makes POST request to the resource. See Resource.request() for arguments definition.

put(path=None, **options)[source]

Makes PUT request to the resource. See Resource.request() for arguments definition.

request(method, path=None, data=None, headers=None, params=None, auth=None, **options)[source]

Makes a HTTP request to the resource.

Parameters:
  • method (str) – HTTP method
  • path (str) – Resource relative path
  • data (bytes) – POST/PUT request payload data
  • headers (dict) – Custom HTTP request headers
  • params (dict) – Custom HTTP request query parameters
  • authaiocouchdb.authn.AuthProvider instance
  • options – Additional options for aiohttp.client.request() function
Returns:

aiocouchdb.client.HttpResponse instance

request_class

alias of HttpRequest

response_class

alias of HttpResponse

update_auth(auth_provider, response)[source]

Updates authentication provider state from the HTTP response data.

Parameters:
aiocouchdb.client.extract_credentials(url)[source]

Extract authentication (user name and password) credentials from the given URL.

>>> extract_credentials('http://localhost:5984/_config/')
('http://localhost:5984/_config/', None)
>>> extract_credentials('http://joe:secret@localhost:5984/_config/')
('http://localhost:5984/_config/', ('joe', 'secret'))
>>> extract_credentials('http://joe%40example.com:secret@localhost:5984/_config/')
('http://localhost:5984/_config/', ('joe@example.com', 'secret'))
aiocouchdb.client.urljoin(base, *path)[source]

Assemble a URI based on a base, any number of path segments, and query string parameters.

>>> urljoin('http://example.org', '_all_dbs')
'http://example.org/_all_dbs'

A trailing slash on the uri base is handled gracefully:

>>> urljoin('http://example.org/', '_all_dbs')
'http://example.org/_all_dbs'

And multiple positional arguments become path parts:

>>> urljoin('http://example.org/', 'foo', 'bar')
'http://example.org/foo/bar'

All slashes within a path part are escaped:

>>> urljoin('http://example.org/', 'foo/bar')
'http://example.org/foo%2Fbar'
>>> urljoin('http://example.org/', 'foo', '/bar/')
'http://example.org/foo/%2Fbar%2F'
>>> urljoin('http://example.org/', None) 
Traceback (most recent call last):
    ...
TypeError: argument 2 to map() must support iteration

Authentication Providers

class aiocouchdb.authn.BasicAuthProvider(name=None, password=None)[source]

Provides authentication via BasicAuth method.

credentials()[source]

Returns authentication credentials.

Return type:aiocouchdb.authn.BasicAuthCredentials
reset()[source]

Resets provider instance to default state.

set_credentials(name, password)[source]

Sets authentication credentials.

Parameters:
  • name (str) – Username
  • password (str) – User’s password
sign(url, headers)[source]

Adds BasicAuth header to headers.

Parameters:
  • url (str) – Request URL
  • headers (dict) – Request headers
class aiocouchdb.authn.BasicAuthCredentials

BasicAuth credentials

password

Alias for field number 1

username

Alias for field number 0

class aiocouchdb.authn.CookieAuthProvider[source]

Provides authentication by cookies.

reset()[source]

Resets provider instance to default state.

sign(url, headers)[source]

Adds cookies to provided headers. If headers already contains any cookies, they would be merged with instance ones.

Parameters:
  • url (str) – Request URL
  • headers (dict) – Request headers
update(response)[source]

Updates cookies from the response.

Parameters:responseaiocouchdb.client.HttpResponse instance
class aiocouchdb.authn.OAuthProvider(*, consumer_key=None, consumer_secret=None, resource_key=None, resource_secret=None)[source]

Provides authentication via OAuth1. Requires oauthlib package.

credentials()[source]

Returns OAuth credentials.

Return type:aiocouchdb.authn.OAuthCredentials
reset()[source]

Resets provider instance to default state.

set_credentials(*, consumer_key=None, consumer_secret=None, resource_key=None, resource_secret=None)[source]

Sets OAuth credentials. Currently, all keyword arguments are required for successful auth.

Parameters:
  • consumer_key (str) – Consumer key (consumer token)
  • consumer_secret (str) – Consumer secret
  • resource_key (str) – Resource key (oauth token)
  • resource_secret (str) – Resource secret (oauth token secret)
sign(url, headers)[source]

Adds OAuth1 signature to headers.

Parameters:
  • url (str) – Request URL
  • headers (dict) – Request headers
class aiocouchdb.authn.OAuthCredentials

OAuth credentials

consumer_key

Alias for field number 0

consumer_secret

Alias for field number 1

resource_key

Alias for field number 2

resource_secret

Alias for field number 3

class aiocouchdb.authn.ProxyAuthProvider(username=None, roles=None, secret=None, *, x_auth_username=None, x_auth_roles=None, x_auth_token=None)[source]

Provides CouchDB proxy authentication methods.

credentials()[source]

Returns three-element tuple of defined username, roles and secret.

reset()[source]

Resets provider instance to default state.

set_credentials(username, roles=None, secret=None)[source]

Sets ProxyAuth credentials.

Parameters:
  • username (str) – CouchDB username
  • roles (list) – List of username roles
  • secret (str) – ProxyAuth secret. Should match the one which defined on target CouchDB server.
sign(url, headers)[source]

Adds ProxyAuth credentials to headers.

Parameters:
  • url (str) – Request URL
  • headers (dict) – Request headers
x_auth_roles = 'X-AUTH-COUCHDB-ROLES'

Controls the name of header used to specify list of CouchDB user roles

x_auth_token = 'X-AUTH-COUCHDB-TOKEN'

Controls the name of header used to provide authentication token

x_auth_username = 'X-AUTH-COUCHDB-USERNAME'

Controls the name of header used to specify CouchDB username

class aiocouchdb.authn.ProxyAuthCredentials

ProxyAuth credentials

roles

Alias for field number 1

secret

Alias for field number 2

username

Alias for field number 0

Feeds

class aiocouchdb.feeds.Feed(resp, *, loop=None, buffer_size=0)[source]

Wrapper over HttpResponse content to stream continuous response by emitted chunks.

buffer_size = 0

Limits amount of items feed would fetch and keep for further iteration.

close(force=False)[source]

Closes feed and the related request connection. Closing feed doesnt means that all

Parameters:force (bool) – In case of True, close connection instead of release. See aiohttp.client.ClientResponse.close() for the details
is_active()[source]

Checks if the feed is still able to emit any data.

Return type:bool
next()[source]

Emits the next response chunk or None is feed is empty.

Return type:bytearray
class aiocouchdb.feeds.JsonFeed(resp, *, loop=None, buffer_size=0)[source]

As Feed, but for chunked JSON response. Assumes that each received chunk is valid JSON object and decodes them before emit.

next()[source]

Decodes feed chunk with JSON before emit it.

Return type:dict
class aiocouchdb.feeds.ViewFeed(resp, *, loop=None, buffer_size=0)[source]

Like JsonFeed, but uses CouchDB view response specifics.

next()[source]

Emits view result row.

Return type:dict
offset[source]

Returns view results offset.

total_rows[source]

Returns total rows in view.

update_seq[source]

Returns update sequence for a view.

class aiocouchdb.feeds.ChangesFeed(resp, *, loop=None, buffer_size=0)[source]

Processes database changes feed.

last_seq[source]

Returns last emitted sequence number.

Return type:int
next()[source]

Emits the next event from changes feed.

Return type:dict
class aiocouchdb.feeds.LongPollChangesFeed(resp, *, loop=None, buffer_size=0)[source]

Processes long polling database changes feed.

class aiocouchdb.feeds.ContinuousChangesFeed(resp, *, loop=None, buffer_size=0)[source]

Processes continuous database changes feed.

next()[source]

Emits the next event from changes feed.

Return type:dict
class aiocouchdb.feeds.EventSourceFeed(resp, *, loop=None, buffer_size=0)[source]

Handles EventSource response following the W3.org spec with single exception: it expects field data to contain valid JSON value.

next()[source]

Emits decoded EventSource event.

Return type:dict
class aiocouchdb.feeds.EventSourceChangesFeed(resp, *, loop=None, buffer_size=0)[source]

Process event source database changes feed. Similar to EventSourceFeed, but includes specifics for changes feed and emits events in the same format as others ChangesFeed does.

next()[source]

Emits the next event from changes feed.

Return type:dict

Views

class aiocouchdb.views.View(resource)[source]

Views requesting helper.

request(*, auth=None, feed_buffer_size=None, data=None, params=None)[source]

Requests a view associated with the owned resource.

Parameters:
  • authaiocouchdb.authn.AuthProvider instance
  • feed_buffer_size (int) – Internal buffer size for fetched feed items
  • data (dict) – View request payload
  • params (dict) – View request query parameters
Return type:

aiocouchdb.feeds.ViewFeed

Errors

Exception hierarchy

BaseException
+-- Exception
    +-- aiohttp.errors.HttpProcessingError
        +-- aiocouchdb.errors.HttpErrorException
            +-- aiocouchdb.errors.BadRequest
            +-- aiocouchdb.errors.Unauthorized
            +-- aiocouchdb.errors.Forbidden
            +-- aiocouchdb.errors.ResourceNotFound
            +-- aiocouchdb.errors.MethodNotAllowed
            +-- aiocouchdb.errors.ResourceConflict
            +-- aiocouchdb.errors.PreconditionFailed
            +-- aiocouchdb.errors.RequestedRangeNotSatisfiable
            +-- aiocouchdb.errors.ServerError
exception aiocouchdb.errors.HttpErrorException(error, reason, headers=None)[source]

Extension of aiohttp.errors.HttpErrorException for CouchDB related errors.

exception aiocouchdb.errors.BadRequest(error, reason, headers=None)[source]

The request could not be understood by the server due to malformed syntax.

exception aiocouchdb.errors.Unauthorized(error, reason, headers=None)[source]

The request requires user authentication.

exception aiocouchdb.errors.Forbidden(error, reason, headers=None)[source]

The server understood the request, but is refusing to fulfill it.

exception aiocouchdb.errors.ResourceNotFound(error, reason, headers=None)[source]

The server has not found anything matching the Request-URI.

exception aiocouchdb.errors.MethodNotAllowed(error, reason, headers=None)[source]

The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.

exception aiocouchdb.errors.ResourceConflict(error, reason, headers=None)[source]

The request could not be completed due to a conflict with the current state of the resource.

exception aiocouchdb.errors.PreconditionFailed(error, reason, headers=None)[source]

The precondition given in one or more of the Request-Header fields evaluated to false when it was tested on the server.

exception aiocouchdb.errors.RequestedRangeNotSatisfiable(error, reason, headers=None)[source]

The client has asked for a portion of the file, but the server cannot supply that portion.

exception aiocouchdb.errors.ServerError(error, reason, headers=None)[source]

The server encountered an unexpected condition which prevented it from fulfilling the request.

aiocouchdb.errors.maybe_raise_error(resp)[source]

Raises aiohttp.errors.HttpErrorException exception in case of >=400 response status code.

Headers

aiocouchdb.hdrs.ACCEPT_RANGES = 'ACCEPT-RANGES'

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.5.html

aiocouchdb.hdrs.CONTENT_DISPOSITION = 'CONTENT-DISPOSITION'

http://tools.ietf.org/html/rfc2183

aiocouchdb.hdrs.X_AUTH_COUCHDB_ROLES = 'X-AUTH-COUCHDB-ROLES'

Defines CouchDB Proxy Auth list of roles separated by a comma

aiocouchdb.hdrs.X_AUTH_COUCHDB_TOKEN = 'X-AUTH-COUCHDB-TOKEN'

Defines CouchDB Proxy Auth token

aiocouchdb.hdrs.X_AUTH_COUCHDB_USERNAME = 'X-AUTH-COUCHDB-USERNAME'

Defines CouchDB Proxy Auth username

«  CouchDB 1.x API   ::   Contents