0
# UnQLite
1

2
Fast Python bindings for UnQLite, a lightweight, embedded NoSQL database and JSON document store. UnQLite provides both key/value storage capabilities and a JSON document store with Jx9 scripting language support, offering ACID transactions, cursors for record traversal, and support for terabyte-sized databases.
3

4
## Package Information
5

6
- **Package Name**: unqlite
7
- **Language**: Python  
8
- **Installation**: `pip install unqlite`
9
- **License**: MIT
10

11
## Core Imports
12

13
```python
14
import unqlite
15
```
16

17
Main database class:
18

19
```python
20
from unqlite import UnQLite
21
```
22

23
Additional classes and exceptions:
24

25
```python
26
from unqlite import UnQLiteError, Transaction, Cursor, VM, Collection
27
```
28

29
## Basic Usage
30

31
```python
32
import unqlite
33

34
# Create an in-memory database
35
db = unqlite.UnQLite(':mem:')
36

37
# Store and retrieve key-value pairs
38
db['key'] = 'value'
39
print(db['key'])  # 'value'
40

41
# Check if key exists
42
if 'key' in db:
43
    print("Key exists")
44

45
# Iterate over all items
46
for key, value in db.items():
47
    print(f"{key}: {value}")
48

49
# Close database
50
db.close()
51

52
# Use as context manager for automatic cleanup
53
with unqlite.UnQLite('mydatabase.db') as db:
54
    db['user:1'] = {'name': 'Alice', 'age': 30}
55
    user = db['user:1']
56
```
57

58
## Architecture
59

60
UnQLite provides multiple interfaces for different use cases:
61

62
- **UnQLite Database**: Main database connection with key/value operations and transaction support
63
- **Cursor Interface**: Efficient traversal and iteration over large datasets  
64
- **Jx9 Virtual Machine**: Embedded scripting engine for complex operations and JSON document manipulation
65
- **JSON Collections**: High-level document store interface built on Jx9 scripting
66
- **Transaction Management**: ACID transaction support for file-based databases
67

68
The library is built as a Cython extension providing high-performance access to the underlying UnQLite C library, with automatic encoding/decoding between Python objects and database storage formats.
69

70
## Capabilities
71

72
### Key-Value Storage
73

74
Core database operations for storing, retrieving, and managing key-value pairs. Includes dictionary-style interface, bulk operations, and existence checks.
75

76
```python { .api }
77
class UnQLite:
78
    def store(self, key, value): ...
79
    def fetch(self, key): ...
80
    def delete(self, key): ...
81
    def exists(self, key): ...
82
    def append(self, key, value): ...
83
    def update(self, dict values): ...
84
    def __setitem__(self, key, value): ...
85
    def __getitem__(self, key): ...
86
    def __delitem__(self, key): ...
87
    def __contains__(self, key): ...
88
    def keys(self): ...
89
    def values(self): ...
90
    def items(self): ...
91
    def range(self, start_key, end_key, include_end_key=True): ...
92
    def __len__(self): ...
93
    def __iter__(self): ...
94
```
95

96
[Key-Value Storage](./key-value.md)
97

98
### Database Management
99

100
Database lifecycle management including connection handling, configuration, and bulk operations.
101

102
```python { .api }
103
class UnQLite:
104
    def __init__(self, filename=':mem:', flags=UNQLITE_OPEN_CREATE, open_database=True, thread_safe=True): ...
105
    def open(self): ...
106
    def close(self): ...
107
    def flush(self): ...
108
    def __enter__(self): ...
109
    def __exit__(self, exc_type, exc_val, exc_tb): ...
110
```
111

112
[Database Management](./database-management.md)
113

114
### Transactions
115

116
ACID transaction support for file-based databases with manual and context manager interfaces.
117

118
```python { .api }
119
class UnQLite:
120
    def begin(self): ...
121
    def commit(self): ...
122
    def rollback(self): ...
123
    def transaction(self): ...
124
    def commit_on_success(self, fn): ...
125
    def disable_autocommit(self): ...
126

127
class Transaction:
128
    def __enter__(self): ...
129
    def __exit__(self, exc_type, exc_val, exc_tb): ...
130
```
131

132
[Transactions](./transactions.md)
133

134
### Cursor Operations
135

136
Efficient database traversal and iteration capabilities for large datasets with positioning and filtering support.
137

138
```python { .api }
139
class Cursor:
140
    def reset(self): ...
141
    def seek(self, key, flags=...): ...
142
    def first(self): ...
143
    def last(self): ...
144
    def next_entry(self): ...
145
    def previous_entry(self): ...
146
    def key(self): ...
147
    def value(self): ...
148
    def delete(self): ...
149
    def is_valid(self): ...
150
    def fetch_until(self, stop_key, include_stop_key=True): ...
151
```
152

153
[Cursor Operations](./cursors.md)
154

155
### Jx9 Scripting
156

157
Embedded Jx9 scripting engine for complex database operations and JSON manipulation with variable management.
158

159
```python { .api }
160
class VM:
161
    def compile(self): ...
162
    def execute(self): ...
163
    def reset(self): ...
164
    def close(self): ...
165
    def set_value(self, name, value): ...
166
    def get_value(self, name): ...
167
    def set_values(self, dict data): ...
168
    def __setitem__(self, name, value): ...
169
    def __getitem__(self, name): ...
170
```
171

172
[Jx9 Scripting](./jx9-scripting.md)
173

174
### JSON Collections
175

176
High-level document store interface for managing JSON documents with querying, filtering, and schema support.
177

178
```python { .api }
179
class Collection:
180
    def create(self): ...
181
    def drop(self): ...
182
    def exists(self): ...
183
    def store(self, record, return_id=True): ...
184
    def fetch(self, record_id): ...
185
    def update(self, record_id, record): ...
186
    def delete(self, record_id): ...
187
    def all(self): ...
188
    def filter(self, filter_fn): ...
189
    def set_schema(self, _schema=None, **kwargs): ...
190
    def get_schema(self): ...
191
```
192

193
[JSON Collections](./json-collections.md)
194

195
### Utility Functions
196

197
Random data generation and library information utilities.
198

199
```python { .api }
200
class UnQLite:
201
    def random_string(self, int nbytes): ...
202
    def random_int(self): ...
203
    def lib_version(self): ...
204
```
205

206
[Utility Functions](./utilities.md)
207

208
### Constants
209

210
Database open flags and configuration constants.
211

212
```python { .api }
213
# Database open flags
214
UNQLITE_OPEN_READONLY: int
215
UNQLITE_OPEN_READWRITE: int  
216
UNQLITE_OPEN_CREATE: int
217
UNQLITE_OPEN_EXCLUSIVE: int
218
UNQLITE_OPEN_TEMP_DB: int
219
UNQLITE_OPEN_NOMUTEX: int
220
UNQLITE_OPEN_OMIT_JOURNALING: int
221
UNQLITE_OPEN_IN_MEMORY: int
222
UNQLITE_OPEN_MMAP: int
223

224
# Cursor positioning flags
225
UNQLITE_CURSOR_MATCH_EXACT: int
226
UNQLITE_CURSOR_MATCH_LE: int
227
UNQLITE_CURSOR_MATCH_GE: int
228
```
229

230
### Exception Handling
231

232
Error handling and exception types for database operations.
233

234
```python { .api }
235
class UnQLiteError(Exception):
236
    def __init__(self, msg, errno): ...
237
    
238
    @property
239
    def errno(self): ...
240
    
241
    @property  
242
    def error_message(self): ...
243
    
244
    def __repr__(self): ...
245
```
246

247
Standard Python exceptions are also used:
248
- `KeyError`: Raised when accessing non-existent keys
249
- `MemoryError`: Raised when out of memory  
250
- `NotImplementedError`: Raised for unsupported operations