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()
.
.. >