EasyCouch – документация

Оглавление:

Основы работы

Рассмотрим пример работы с библиотекой

>>> couch = EasyCouch("http://localhost:5984/", {'default': 'default', 'comments': 'real_comments'})

Для начала следует создать объект EasyCouch. В дальнейшем все действия с сервером производятся через этот объект. Первым параметром передается адрес сервера, вторым – карта имен баз данных. Здесь мы можем указать синонимы для баз данных которые мы хотим использовать. Ключу соответствует синоним, а значению – реальное имя БД. Теперь можно получить объект Database, позволяющий работать с отдельной БД:

>>> db = couch.comments

Так же присутствует возможность получить доступ к любой БД по её реальному имени

>>> db = couch.get_db('real_comments')

Библиотека EasyCouch устроена таким образом, что позволяет хранить в CouchDB объекты любого типа. Например, наш класс:

class BlogPost(object):
        pass

Прежде чем сохранить первый объект в базе, необходимо создать и зарегистрировать Mapper для данного типа объектов

>>> mapper = Mapper(BlogPost)
>>> db.register_mapper("blogpost", mapper)

Mapper – это объект, знающий КАК преобразовать python-объект в структуру, пригодную для хранения в CouchDB, и обратно. Первым аргументом в __init__ передается doctype – это имя будет сохраняться вместе с объектом в БД для нужд последующего преобразования JSON структуры couchdb в python-объект. Вторым аргументом передается сам класс, для которого данный мапер актуален.

Далее объект создается самым тривиальным путём и отправляется в базу данных для сохранения:

>>> my_post = BlogPost()
>>> my_post._id = "test_post"
>>> my_post.title = "hello easycouch"
>>> db.store(my_post, force_commit = True)

В случае если у объекта отсутствует свойство _id, store сгенерирует его стандартным алгоритмом. force_commit позволяет вносить изменения мгновенно, делая commit().

>>> my_post = db.get("test_post")
>>> my_post.title
u"hello easycouch"

Дизайн-документы

Виды (view) – главный инструмент запросов к CouchDB. В простейшем случае, вид можно создать так:

>>> my_view = View("function(doc) { emit(doc.title); }")
>>> resoults = my_view(db, limit = 10, include_docs = True)

В примере выше my_view не привязан к дизайн документу, поэтому при его вызове необходимо первым аргументом передать экземпляр Database (остальные аргументы – параметры запроса). Привязать вид к дизайн-документу можно разными способами. Например:

>>> my_design = DesignDocument()
>>> my_design.add_view('some_view', my_view)

или:

>>> class MyDesign(DesignDocument):
>>>     some_view = View("function(doc) { emit(doc.title); }")
>>> my_design = MyDesign()

Вызывать виды можно по соответствующему имени

>>> type(my_design.some_view)
<class 'easycouch.view.View'>

Поскольку дизайн-документ должен являться частью базы данных, его следует там зарегистрировать:

>>> db.register_design('my_design', my_design)

и тогда наш вид можно вызывать без первого аргумента db

>>> resoults = db.my_design.some_view(limit = 10, include_docs = True)

В случае если дизайн-документ синхронизирован с базой данных, easycouch выполнит запрос к этому виду, в ином случае вид будет запущен как временный (temp view).

>>> couch.sync()
>>> db.hello_design.some_view() # HTTP /db/_design/my_design/_view/some_view

Проще всего организовывать код дизайн-документов в директорию вида

  • designs
    • my_design
      • some_view
        • map.js
        • reduce.js

Тогда код самих функций для всего дизайн-документа можно подгрузить используя sources_from_path. В таком случае определение видов в DesignDocument можно использовать только для задания параметров “по-умолчанию”:

class MyDesign(DesignDocument):
        some_view = View(limit = 10, include_docs = True)
my_design.sources_from_path('./design/my_design')

Работа с результатами

ViewResoults позволяет работать с результатами вида разными способами. Поскольку сам по себе этот объект является итератором, можно пройтись по результатам следующим образом:

for key, object_or_value in resoults:
        pass

Первым значением в этом случае всегда будет являться ключ, а второй параметр может быть объектом, если include_docs = True, либо значением (которое преобразуется в объект если задан doctype и для него есть mapper) в ином случае. Так же можно использовать .items(), .objects(), .values(). .. >

API

Indices and tables