A CouchDB driver for Python.
Project description
time2relax: Python CouchDB Driver
A CouchDB driver for Python.
time2relax is a Python CouchDB driver that tries to offer a minimal level of abstraction between you and CouchDB.
Basic insert usage:
>>> from time2relax import CouchDB
>>> db = CouchDB('http://localhost:5984/dbname')
>>> db.insert({'title': 'Ziggy Stardust'})
<Response [201]>
Table of Contents
- Feature Support
- Installation
- Documentation
- Create a Database
- Delete a Database
- Create/Update a Document
- Fetch a Document
- Delete a Document
- Create/Update a Batch of Documents
- Fetch a Batch of Documents
- Replicate a Database
- Save an Attachment
- Get an Attachment
- Delete an Attachment
- Get Database Information
- Compact a Database
- Run a List Function
- Run a Show Function
- Run a View Function
- How to Contribute
Feature Support
Inspired by pouchdb and couchdb-nano APIs, it features:
- Requests (HTTP for Humans) under the hood.
- Transparent URL and parameter encoding.
- HTTP exceptions modeled from CouchDB error codes.
- Support for CouchDB 1.7.x.
time2relax officially supports Python 2.7 & 3.6-3.7.
Installation
To install time2relax, simply run:
$ pip install -U time2relax
✨🛋✨
Documentation
Detailed documentation is available at https://time2relax.readthedocs.org.
To use time2relax in a project:
>>> from time2relax import CouchDB
>>> db = CouchDB('http://localhost:5984/dbname')
Most of the API is exposed as db.FUNCTION(*args, **kwargs)
, where **kwargs
are optional arguments that requests.Session.request
can take.
Create a Database
Initially the CouchDB
object will check if the database exists, and try to create it if it does not. You can use create_db=False
to skip this step:
>>> db = CouchDB('http://localhost:5984/dbname', create_db=False)
Delete a Database
Delete a database:
>>> db.destroy()
<Response [200]>
Further requests with the CouchDB
object should raise a time2relax.ResourceNotFound
:
>>> db.info()
ResourceNotFound: ({'error': 'not_found', 'reason': 'missing'}, <Response [404]>)
Create/Update a Document
Note: There are some CouchDB restrictions on valid property names of the documents.
Create a new document:
>>> db.insert({'_id': 'docid', 'title': 'Heros'})
<Response [201]>
To create a new document and let CouchDB auto-generate an _id
for it:
>>> db.insert({'title': 'Ziggy Stardust'})
<Response [201]>
If the document already exists, you must specify its revision _rev
, otherwise a conflict will occur. You can update an existing document using _rev
:
>>> result = db.get('docid').json()
>>> db.insert({'_id': result['_id'], '_rev': result['_rev'], 'title': 'Dance'})
<Response [201]>
Fetch a Document
Retrieve a document:
>>> db.get('docid')
<Response [200]>
Delete a Document
You must supply the _rev
of the existing document.
Delete a document:
>>> result = db.get('docid').json()
>>> db.remove(result['_id'], result['_rev'])
<Response [200]>
You can also delete a document by using time2relax.CouchDB.insert
with {'_deleted': True}
:
>>> result = db.get('docid').json()
>>> result['_deleted'] = True
>>> db.insert(result)
<Response [200]>
Create/Update a Batch of Documents
Create multiple documents:
>>> db.bulk_docs([
... {'_id': 'doc1', 'title': 'Lisa Says'},
... {'_id': 'doc2', 'title': 'Space Oddity'},
... ])
<Response [201]>
If you omit the _id
parameter on a given document, the database will create a new document and assign the ID for you:
>>> db.bulk_docs([
... {'title': 'Lisa Says'},
... {'title': 'Space Oddity'},
... ])
<Response [201]>
To update a document, you must include both an _id
parameter and a _rev
parameter, which should match the ID and revision of the document on which to base your updates:
>>> db.bulk_docs([
... {
... '_id': 'doc1',
... '_rev': '1-84abc2a942007bee7cf55007cba56198',
... 'title': 'Lisa Says',
... 'artist': 'Velvet Underground',
... },
... {
... '_id': 'doc2',
... '_rev': '1-7b80fc50b6af7a905f368670429a757e',
... 'title': 'Space Oddity',
... 'artist': 'David Bowie',
... },
... ])
<Response [201]>
Finally, to delete a document, include a _deleted
parameter with the value True
:
>>> db.bulk_docs([
... {
... '_id': 'doc1',
... '_rev': '1-84abc2a942007bee7cf55007cba56198',
... 'title': 'Lisa Says',
... '_deleted': True,
... },
... {
... '_id': 'doc2',
... '_rev': '1-7b80fc50b6af7a905f368670429a757e',
... 'title': 'Space Oddity',
... '_deleted': True,
... },
... ])
<Response [201]>
Fetch a Batch of Documents
Fetch multiple documents:
>>> params = {'include_docs': True, 'attachments': True}
>>> db.all_docs(params)
<Response [200]>
You can use startkey
/endkey
to find all docs in a range:
>>> params = {'startkey': 'bar', 'endkey': 'quux'}
>>> db.all_docs(params)
<Response [200]>
You can also do a prefix search – i.e. "give me all the documents whose _id
start with 'foo'
" – by using the special high Unicode character '\uffff'
:
>>> params = {'startkey': 'foo', 'endkey': 'foo\uffff'}
>>> db.all_docs(params)
<Response [200]>
Replicate a Database
Note: The target has to exist, you can use json={'create_target': True}
to create it prior to replication.
Replicate a database to a target:
>>> db.replicate_to('http://localhost:5984/otherdb')
<Response [200]>
Save an Attachment
This method will update an existing document to add an attachment, so it requires a _rev
if the document already exists. If the document doesn't already exist, then this method will create an empty document containing the attachment.
Attach a text/plain file:
>>> with open('/tmp/att.txt') as fp:
... db.insert_att('docid', None, 'att.txt', fp, 'text/plain')
...
<Response [201]>
Get an Attachment
Get attachment data:
>>> db.get_att('docid', 'att.txt')
<Response [200]>
Delete an Attachment
You must supply the _rev
of the existing document.
Delete an attachment:
>>> result = db.get('docid').json()
>>> db.remove_att(result['_id'], result['_rev'], 'att.txt')
<Response [200]>
Get Database Information
Get information about a database:
>>> db.info()
<Response [200]>
Compact a Database
This reduces a database's size by removing unused and old data, namely non-leaf revisions and attachments that are no longer referenced by those revisions.
Trigger a compaction operation:
>>> db.compact()
<Response [202]>
Run a List Function
Make sure you understand how list functions work in CouchDB. A good start is the CouchDB guide entry on lists:
>>> db.insert({
... '_id': '_design/testid',
... 'views': {
... 'viewid': {
... 'map': "function (doc) {"
... " emit(doc._id, 'value');"
... "}",
... },
... },
... 'lists': {
... 'listid': "function (head, req) {"
... " return 'Hello World!';"
... "}",
... },
... })
<Response [201]>
>>> db.ddoc_list('testid', 'listid', 'viewid')
<Response [200]>
Run a Show Function
Make sure you understand how show functions work in CouchDB. A good start is the CouchDB guide entry on shows:
>>> db.insert({
... '_id': '_design/testid',
... 'shows': {
... 'showid': "function (doc, req) {"
... " return {body: 'relax!'}"
... "}",
... },
... })
<Response [201]>
>>> db.ddoc_show('testid', 'showid')
<Response [200]>
Run a View Function
Make sure you understand how view functions work in CouchDB. A good start is the CouchDB guide entry on views:
>>> db.insert({
... '_id': '_design/testid',
... 'views': {
... 'viewid': {
... 'map': "function (doc) {"
... " emit(doc.key);"
... "}",
... },
... },
... })
<Response [201]>
>>> params = {'reduce': False, 'key': 'key2'}
>>> db.ddoc_view('testid', 'viewid', params)
<Response [200]>
How to Contribute
- Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
- Fork the repository to start making your changes to the master branch (or branch off of it).
- Write a test which shows that the bug was fixed or that the feature works as expected.
- Send a pull request and bug the maintainer until it gets merged and published. Make sure to add yourself to AUTHORS.
Version History
0.5.0 (2018-??-??)
- Move the time2relax API to
time2relax.time2relax
. - Add Python 3.7 support.
0.4.1 (2017-11-22)
- Fix Travis build errors - invalid config
0.4.0 (2017-11-21)
CouchDBError
is nowHTTPError
(Backwards Incompatible)CouchDB(skip_setup=False)
is nowCouchDB(create_db=True)
(Backwards Incompatible)- Add Python 3.6 support.
- Drop Python 2.6 support - Python 2.6 is no longer supported by the Python core team. (Backwards Incompatible)
0.3.0 (2017-03-03)
- New time2relax API. (Backwards Incompatible)
- time2relax is now a thin
requests
wrapper. - New design document functions;
list
,show
,view
.
0.2.0 (2016-12-10)
- Add Python 3.3, 3.4, 3.5 support.
0.1.0 (2016-12-10)
- First release on PyPI.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for time2relax-0.5.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0cb923e2dee78028392a2fc7dec96f5240ff4f32ea717c710d9bbeafb1973e8a |
|
MD5 | 6d6bd63328198f5f1485e799237e30ec |
|
BLAKE2b-256 | 7b295c3cfa38fbfc6395b0fc98bfec91e625de9763191fa16d3fe4a4c1a15a04 |