aiocouchdb 0.9.0-dev documentation

Common Base Objects

«  CouchDB 1.x API   ::   Contents

Common Base Objects


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.


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.


alias of FlowControlChunksQueue


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


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
apply_auth(auth_provider, url, headers)[source]

Applies authentication routines on further request.

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

  • 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

aiocouchdb.client.HttpResponse instance


alias of HttpRequest


alias of HttpResponse

update_auth(auth_provider, response)[source]

Updates authentication provider state from the HTTP response data.


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://localhost:5984/_config/', ('', 'secret'))
aiocouchdb.client.urljoin(base, *path)[source]

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

>>> urljoin('', '_all_dbs')

A trailing slash on the uri base is handled gracefully:

>>> urljoin('', '_all_dbs')

And multiple positional arguments become path parts:

>>> urljoin('', 'foo', 'bar')

All slashes within a path part are escaped:

>>> urljoin('', 'foo/bar')
>>> urljoin('', 'foo', '/bar/')
>>> urljoin('', 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.


Returns authentication credentials.

Return type:aiocouchdb.authn.BasicAuthCredentials

Resets provider instance to default state.

set_credentials(name, password)[source]

Sets authentication credentials.

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

Adds BasicAuth header to headers.

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

BasicAuth credentials


Alias for field number 1


Alias for field number 0

class aiocouchdb.authn.CookieAuthProvider[source]

Provides authentication by cookies.


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.

  • url (str) – Request URL
  • headers (dict) – Request headers

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.


Returns OAuth credentials.

Return type:aiocouchdb.authn.OAuthCredentials

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.

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

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

OAuth credentials


Alias for field number 0


Alias for field number 1


Alias for field number 2


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.


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


Resets provider instance to default state.

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

Sets ProxyAuth credentials.

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

  • 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


Alias for field number 1


Alias for field number 2


Alias for field number 0


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.


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

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

Return type:bool

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.


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.


Emits view result row.

Return type:dict

Returns view results offset.


Returns total rows in view.


Returns update sequence for a view.

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

Processes database changes feed.


Returns last emitted sequence number.

Return type:int

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.


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 spec with single exception: it expects field data to contain valid JSON value.


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.


Emits the next event from changes feed.

Return type:dict


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.

  • 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:



Exception hierarchy

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


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





Defines CouchDB Proxy Auth list of roles separated by a comma


Defines CouchDB Proxy Auth token


Defines CouchDB Proxy Auth username

«  CouchDB 1.x API   ::   Contents