Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 122 lines (91 sloc) 4.752 kB
a9466d2 @ownport adopt README.rst after migration from Markdown
authored
1 ======
2 kvlite
3 ======
cd8d344 @ownport update README
authored
4
3d9806c @ownport updated README
authored
5 kvlite is small library for storing documents in SQL databases. At the moment supported MySQL and SQLite. A document can be string, list/tuple or dictionary. Default serialization is based on cPickleSerializer methods but of course it is possible to define own serialization to store data in kvlite database.
2c3e46e @ownport Initial commit
authored
6
d796b16 @ownport README updated
authored
7 A collection is a group of documents stored in kvlite, and it can be thought of as roughly the equivalent of a table in a relational database.
6096378 @ownport readme update
authored
8
a9466d2 @ownport adopt README.rst after migration from Markdown
authored
9 Installation
10 ============
fb638ca @ownport update README
authored
11
3413ff4 @ownport added new way of kvlite installation
authored
12 To install kvlite you just need to copy two files: kvlite.py and kvlite-cli.py. Second one is optional and it will be needed only if you need to have access to kvlite collections via console. Also kvlite-cli.py can be used as example how to use kvlite library.
13
14 If `pip <http://www.pip-installer.org/>` installed in your system, you can install kvlite via
15
16 pip install kvlite
fb638ca @ownport update README
authored
17
a9466d2 @ownport adopt README.rst after migration from Markdown
authored
18 Examples of use
19 ===============
20
21 >>> import kvlite
22 >>> collection = open('sqlite://memory:test_collection')
23 >>> collection
24 <kvlite.SqliteCollection object at 0x14cb350>
25 >>> collection.count
26 0
27 >>> collection.put('1', 'first document')
28 >>> collection.put('2', ('second', 'document'))
29 >>> collection.put('3', {'third': 'document'})
30 >>> collection.count
31 3
32 >>> collection.get('1')
33 ('1', 'first document')
34 >>> collection.get('2')
35 ('2', ('second', 'document'))
36 >>> collection.get('3')
37 ('3', {'third': 'document'})
38 >>>
39 >>> [k for k in collection.keys() ]
40 ['1', '2', '3']
41 >>> collection.delete('1')
42 >>> collection.delete('2')
43 >>> collection.delete('3')
44 >>> collection.count
45 0
46 >>> collection.close()
47 >>>
48
49 Collection Utils
50 ================
7434aa2 @ownport added new topics in README
authored
51
dbaa5ab @ownport README updated accroding to current kvlite version
authored
52 - open(uri) - open collection
53 - remove(uri) - remove collection
54 - get_uuid(amount) - get list of uuid
55
56 To get started just open() function is needed.
57
58 URI format is:
59
60 - for mysql: `mysql://username:password@hostname:port/database.collection_name`
61 - for sqlite: `sqlite://path-to-sqlite-file:collection_name` or `sqlite://memory:collection_name`
62
63 In case when sqlite is in use two variants of collection is possible: in file and in memory.
64
65 The function open(uri) returns MysqlCollection or SqliteCollection object
7434aa2 @ownport added new topics in README
authored
66
a9466d2 @ownport adopt README.rst after migration from Markdown
authored
67 Collection
68 ==========
7434aa2 @ownport added new topics in README
authored
69
dbaa5ab @ownport README updated accroding to current kvlite version
authored
70 MysqlCollection and SqliteCollection have the same methods:
71
72 - get_uuid() - in case of mysql use, this function will be working faster than for sqlite
73 - get(k) - if k(key) is not defined, the function get() returns the list of all documents in collection. Otherwise key/value pair is returned for defined k(key)
74 - put(k,v) - put key/value to storage. The key has limitation - only 40 bytes length. The value can be string, list or tuple, dictionary
75 - delete(k) - delete key/value pair
76 - keys() - returns the list of all keys in collection
77 - count() - returns the amount of documents in collection
78 - commit() - as kvlite based on transactional databases, commit() is used for commitment changes in collection
79 - close() - close connection to database
80
a9466d2 @ownport adopt README.rst after migration from Markdown
authored
81 CollectionManager
82 =================
7434aa2 @ownport added new topics in README
authored
83
dbaa5ab @ownport README updated accroding to current kvlite version
authored
84 Sometimes it will needed to manage collections: create, check if exists, remove. For these operations you can use CollectionManager. This class has the next methods:
7434aa2 @ownport added new topics in README
authored
85
dbaa5ab @ownport README updated accroding to current kvlite version
authored
86 - parse_uri(uri) - depends on type of database, the function parse_uri() can returns deferent result based on which backend is used
87 - create(name) - create collection
88 - connection - returns refernce to database collection
89 - collection_class - returns class MysqlCollection or SqliteCollection depend on backend parameter in URI
90 - collections() - returns the list of collections in database
91 - remove(name) - remove collection
92 - close() - close connection to database
6096378 @ownport readme update
authored
93
3d9806c @ownport updated README
authored
94 Serializers
95 ===========
96
97 - cPickleSerializer (by default)
98 - CompressedJsonSerializer
99
100 Serializer can be defined via open function
101
102 def open(uri, serializer=cPickleSerializer):
103 '''
104 open collection by URI,
105 if collection does not exist kvlite will try to create it
106
107 in case of successful opening or creation new collection
108 return Collection object
109
110 serializer: the class or module to serialize msgs with, must have
111 methods or functions named ``dumps`` and ``loads``,
112 `pickle <http://docs.python.org/library/pickle.html>`_ is the default,
113 use ``None`` to store messages in plain text (suitable for strings,
114 integers, etc)
115
a9466d2 @ownport adopt README.rst after migration from Markdown
authored
116 Another topics
117 ==============
de4ee2e @ownport redesign of README document
authored
118
7b1e4c4 @ownport fix typos
authored
119 - kvlite structure <https://github.com/ownport/kvlite/blob/master/docs/kvlite.png>
120 - Link collection to similar projects or where the ideas were taken <https://github.com/ownport/kvlite/blob/master/docs/links.md>
fb638ca @ownport update README
authored
121
Something went wrong with that request. Please try again.