Client module¶

class Server¶

class couchdbcurl.client.Server(uri='http://localhost:5984/', cache=None, timeout=None)¶

Representation of a CouchDB server.

>>> server = Server('http://localhost:5984/')

This class behaves like a dictionary of databases. For example, to get a list of database names on the server, you can simply iterate over the server object.

New databases can be created using the create method:

>>> db = server.create('python-tests')
>>> db
<Database 'python-tests'>

You can access existing databases using item access, specifying the database name as the key:

>>> db = server['python-tests']
>>> db.name
'python-tests'

Databases can be deleted using a del statement:

>>> del server['python-tests']

config¶

The configuration of the CouchDB server.

The configuration is represented as a nested dictionary of sections and options from the configuration files of the server, or the default values for options that are not explicitly configured.

Type :	dict

create(name)¶

Create a new database with the given name.

Raises PreconditionFailed:
Parameters:	name – the name of the database
Returns:	a Database object representing the created database
Return type:	Database
	if a database with that name already exists

delete(name)¶

Delete the database with the specified name.

Raises ResourceNotFound:
Parameters:	name – the name of the database
	if a database with that name does not exist
Since :	0.6

replicate(source, target, **options)¶

Replicate changes from the source database to the target database.

Parameters:	source – URL of the source database target – URL of the target database options – optional replication args, e.g. continuous=True

stats()¶: Database statistics.

tasks()¶: A list of tasks currently active on the server.

version¶

The version string of the CouchDB server.

Note that this results in a request being made, and can also be used to check for the availability of the server.

Type :	unicode

class Database¶

class couchdbcurl.client.Database(uri, name=None)¶

Representation of a database on a CouchDB server.

>>> server = Server('http://localhost:5984/')
>>> db = server.create('python-tests')

New documents can be added to the database using the create() method:

>>> doc_id = db.create({'type': 'Person', 'name': 'John Doe'})

This class provides a dictionary-like interface to databases: documents are retrieved by their ID using item access

>>> doc = db[doc_id]
>>> doc                 
<Document '...'@... {...}>

Documents are represented as instances of the Row class, which is basically just a normal dictionary with the additional attributes id and rev:

>>> doc.id, doc.rev     
('...', ...)
>>> doc['type']
'Person'
>>> doc['name']
'John Doe'

To update an existing document, you use item access, too:

>>> doc['name'] = 'Mary Jane'
>>> db[doc.id] = doc

The create() method creates a document with a random ID generated by CouchDB (which is not recommended). If you want to explicitly specify the ID, you’d use item access just as with updating:

>>> db['JohnDoe'] = {'type': 'person', 'name': 'John Doe'}

>>> 'JohnDoe' in db
True
>>> len(db)
2

>>> del server['python-tests']

compact()¶

Compact the database.

This will try to prune all revisions from the database.

Returns:	a boolean to indicate whether the compaction was initiated successfully
Return type:	bool

compact_view(name)¶

Compact view. Name must be provided without leading `_design/’ :return: a boolean to indicate whether the compaction was initiated

successfully

Return type:	bool

copy(src, dest)¶

Copy the given document to create a new document.

Parameters:	src – the ID of the document to copy, or a dictionary or Document object representing the source document. dest – either the destination document ID as string, or a dictionary or Document instance of the document that should be overwritten.
Returns:	the new revision of the destination document
Return type:	str
Since :	0.6

create(data)¶

Create a new document in the database with a random ID that is generated by the server.

Note that it is generally better to avoid the create() method and instead generate document IDs on the client side. This is due to the fact that the underlying HTTP POST method is not idempotent, and an automatic retry due to a problem somewhere on the networking stack may cause multiple documents being created in the database.

To avoid such problems you can generate a UUID on the client side. Python (since version 2.5) comes with a uuid module that can be used for this:

from uuid import uuid4
doc_id = uuid4().hex
db[doc_id] = {'type': 'person', 'name': 'John Doe'}

Parameters:	data – the data to store in the document
Returns:	the ID of the created document
Return type:	unicode

delete(doc)¶

Delete the given document from the database.

Use this method in preference over __del__ to ensure you’re deleting the revision that you had previously retrieved. In the case the document has been updated since it was retrieved, this method will raise a ResourceConflict exception.

>>> server = Server('http://localhost:5984/')
>>> db = server.create('python-tests')

>>> doc = dict(type='Person', name='John Doe')
>>> db['johndoe'] = doc
>>> doc2 = db['johndoe']
>>> doc2['age'] = 42
>>> db['johndoe'] = doc2
>>> db.delete(doc)
Traceback (most recent call last):
  ...
ResourceConflict: ('conflict', 'Document update conflict.')

>>> del server['python-tests']

Raises ResourceConflict:
Parameters:	doc – a dictionary or Document object holding the document data
	if the document was updated in the database
Since :	0.4.1

delete_attachment(doc, filename)¶

Delete the specified attachment.

Note that the provided doc is required to have a _rev field. Thus, if the doc is based on a view row, the view row would need to include the _rev field.

Parameters:	doc – the dictionary or Document object representing the document that the attachment belongs to filename – the name of the attachment file
Since :	0.4.1

get(id, default=None, **options)¶

Return the document with the specified ID.

Parameters:	id – the document ID default – the default value to return when the document is not found
Returns:	a Row object representing the requested document, or None if no document with the ID was found
Return type:	Document

get_attachment(id_or_doc, filename, default=None)¶

Return an attachment from the specified doc id and filename.

Parameters:	id_or_doc – either a document ID or a dictionary or Document object representing the document that the attachment belongs to filename – the name of the attachment file default – default value to return when the document or attachment is not found
Returns:	the content of the attachment as a string, or the value of the default argument if the attachment is not found
Since :	0.4.1

info()¶

Return information about the database as a dictionary.

The returned dictionary exactly corresponds to the JSON response to a GET request on the database URI.

Returns:	a dictionary of database properties
Return type:	`dict`
Since :	0.4

name¶

The name of the database.

Note that this may require a request to the server unless the name has already been cached by the info() method.

Type :	basestring

put_attachment(doc, content, filename=None, content_type=None)¶

Create or replace an attachment.

Note that the provided doc is required to have a _rev field. Thus, if the doc is based on a view row, the view row would need to include the _rev field.

Parameters:

doc – the dictionary or Document object representing the document that the attachment should be added to
content – the content to upload, either a file-like object or a string
filename – the name of the attachment file; if omitted, this function tries to get the filename from the file-like object passed as the content argument value
content_type – content type of the attachment; if omitted, the MIME type is guessed based on the file name extension

Since :

0.4.1

query(map_fun, reduce_fun=None, language='javascript', wrapper=None, **options)¶

Execute an ad-hoc query (a “temp view”) against the database.

>>> server = Server('http://localhost:5984/')
>>> db = server.create('python-tests')
>>> db['johndoe'] = dict(type='Person', name='John Doe')
>>> db['maryjane'] = dict(type='Person', name='Mary Jane')
>>> db['gotham'] = dict(type='City', name='Gotham City')
>>> map_fun = '''function(doc) {
...     if (doc.type == 'Person')
...         emit(doc.name, null);
... }'''
>>> for row in db.query(map_fun):
...     print row.key
John Doe
Mary Jane

>>> for row in db.query(map_fun, descending=True):
...     print row.key
Mary Jane
John Doe

>>> for row in db.query(map_fun, key='John Doe'):
...     print row.key
John Doe

>>> del server['python-tests']

Parameters:	map_fun – the code of the map function reduce_fun – the code of the reduce function (optional) language – the language of the functions, to determine which view server to use wrapper – an optional callable that should be used to wrap the result rows options – optional query string parameters
Returns:	the view reults
Return type:	ViewResults

revisions(id, **options)¶

Return all available revisions of the given document.

Parameters:	id – the document ID
Returns:	an iterator over Document objects, each a different revision, in reverse chronological order, if any were found

update(documents, **options)¶

Perform a bulk update or insertion of the given documents using a single HTTP request.

>>> server = Server('http://localhost:5984/')
>>> db = server.create('python-tests')
>>> for doc in db.update([
...     Document(type='Person', name='John Doe'),
...     Document(type='Person', name='Mary Jane'),
...     Document(type='City', name='Gotham City')
... ]):
...     print repr(doc) 
(True, '...', '...')
(True, '...', '...')
(True, '...', '...')

>>> del server['python-tests']

The return value of this method is a list containing a tuple for every element in the documents sequence. Each tuple is of the form (success, docid, rev_or_exc), where success is a boolean indicating whether the update succeeded, docid is the ID of the document, and rev_or_exc is either the new document revision, or an exception instance (e.g. ResourceConflict) if the update failed.

If an object in the documents list is not a dictionary, this method looks for an items() method that can be used to convert the object to a dictionary. Effectively this means you can also use this method with schema.Document objects.

Parameters:	documents – a sequence of dictionaries or Document objects, or objects providing a `items()` method that can be used to convert them to a dictionary
Returns:	an iterable over the resulting documents
Return type:	`list`
Since :	version 0.2

view(name, wrapper=None, **options)¶

Execute a predefined view.

>>> server = Server('http://localhost:5984/')
>>> db = server.create('python-tests')
>>> db['gotham'] = dict(type='City', name='Gotham City')

>>> for row in db.view('_all_docs'):
...     print row.id
gotham

>>> del server['python-tests']

Parameters:	name – the name of the view; for custom views, use the format `design_docid/viewname`, that is, the document ID of the design document and the name of the view, separated by a slash wrapper – an optional callable that should be used to wrap the result rows options – optional query string parameters
Returns:	the view results
Return type:	ViewResults

view_cleanup()¶: Cleanup database views (emits POST /db/_view_cleanup request)

class Document¶

class couchdbcurl.client.Document(*args, **kwargs)¶

Representation of a document in the database.

This is basically just a dictionary with some helper functions and properties (see below). You may work with this object in dict-style or attribute-style

>>> from couchdbcurl.client import Document
>>> doc = Document()
>>> doc['some_field'] = 'this is value'
>>> doc.other_field = 'another value'
>>> dict(doc)
{'other_field': 'another value', 'some_field': 'this is value'}
>>> doc.some_field
'this is value'
>>> doc['other_field']
'another value'

You may check wether Document is new or existing simply by testing it id property. So, you may use constructions like:

if doc.id:
    doc.save()
else:
    doc.create('some_id_prefix')

create(id, suffix_length=12, max_retry=100, db=None, force_random_suffix=False)¶

Conflict-safe document creator. Document id will be ‘<id>’ or ‘<id><random suffix>’ if ‘<id>’ already exists.

id - id prefix. suffix_length - suffix length max_retry - upper retry limit db - database to create document in

delete(db=None)¶: Delete document

delete_attachment(name)¶: Shortcut to Database.delete_attachment()

get_attachment(name)¶: Shortcut to Database.get_attachment()

id¶

The document ID.

Type :	basestring or None for new documents

put_attachment(file_object, name, content_type=None)¶: Shortcut to Database.put_attachment()

reload(db=None)¶: Checks documents revision and reloads if necessary

rev¶

The document revision.

Type :	basestring

save(db=None)¶: Save document. Document will be saved to database db or document._db

class ViewResults¶

class couchdbcurl.client.ViewResults(view, options)¶

Representation of a parameterized view (either permanent or temporary) and the results it produces.

This class allows the specification of key, startkey, and endkey options using Python slice notation.

>>> server = Server('http://localhost:5984/')
>>> db = server.create('python-tests')
>>> db['johndoe'] = dict(type='Person', name='John Doe')
>>> db['maryjane'] = dict(type='Person', name='Mary Jane')
>>> db['gotham'] = dict(type='City', name='Gotham City')
>>> map_fun = '''function(doc) {
...     emit([doc.type, doc.name], doc.name);
... }'''
>>> results = db.query(map_fun)

At this point, the view has not actually been accessed yet. It is accessed as soon as it is iterated over, its length is requested, or one of its rows, total_rows, or offset properties are accessed:

>>> len(results)
3

You can use slices to apply startkey and/or endkey options to the view:

>>> people = results[['Person']:['Person','ZZZZ']]
>>> for person in people:
...     print person.value
John Doe
Mary Jane
>>> people.total_rows, people.offset
(3, 1)

Use plain indexed notation (without a slice) to apply the key option. Note that as CouchDB makes no claim that keys are unique in a view, this can still return multiple rows:

>>> list(results[['City', 'Gotham City']])
[<Row id='gotham', key=['City', 'Gotham City'], value='Gotham City'>]

>>> del server['python-tests']

offset¶

The offset of the results from the first row in the view.

This value is 0 for reduce views.

Type :	int

rows¶

The list of rows returned by the view.

Type :	list

total_rows¶

The total number of rows in this view.

This value is None for reduce views.

Type :	int or `NoneType` for reduce views

update_seq¶: Curren update sequence of corresponding view. To get this value, you must query view with update_seq=True parameter. Otherwise, it will always be None

Client module¶

class Server¶

class Database¶

class Document¶

class ViewResults¶

Table Of Contents

Previous topic

Next topic

This Page

Navigation

Client module¶

class Server¶

class Database¶

class Document¶

class ViewResults¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation