or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cursors.mddatabase-management.mdindex.mdjson-collections.mdjx9-scripting.mdkey-value.mdtransactions.mdutilities.md
tile.json

tessl/pypi-unqlite

Fast Python bindings for the UnQLite embedded NoSQL database.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/unqlite@0.9.x

To install, run

npx @tessl/cli install tessl/pypi-unqlite@0.9.0

index.mddocs/

UnQLite

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.

Package Information

  • Package Name: unqlite
  • Language: Python
  • Installation: pip install unqlite
  • License: MIT

Core Imports

import unqlite

Main database class:

from unqlite import UnQLite

Additional classes and exceptions:

from unqlite import UnQLiteError, Transaction, Cursor, VM, Collection

Basic Usage

import unqlite

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

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

# Check if key exists
if 'key' in db:
    print("Key exists")

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

# Close database
db.close()

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

Architecture

UnQLite provides multiple interfaces for different use cases:

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

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.

Capabilities

Key-Value Storage

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

class UnQLite:
    def store(self, key, value): ...
    def fetch(self, key): ...
    def delete(self, key): ...
    def exists(self, key): ...
    def append(self, key, value): ...
    def update(self, dict values): ...
    def __setitem__(self, key, value): ...
    def __getitem__(self, key): ...
    def __delitem__(self, key): ...
    def __contains__(self, key): ...
    def keys(self): ...
    def values(self): ...
    def items(self): ...
    def range(self, start_key, end_key, include_end_key=True): ...
    def __len__(self): ...
    def __iter__(self): ...

Key-Value Storage

Database Management

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

class UnQLite:
    def __init__(self, filename=':mem:', flags=UNQLITE_OPEN_CREATE, open_database=True, thread_safe=True): ...
    def open(self): ...
    def close(self): ...
    def flush(self): ...
    def __enter__(self): ...
    def __exit__(self, exc_type, exc_val, exc_tb): ...

Database Management

Transactions

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

class UnQLite:
    def begin(self): ...
    def commit(self): ...
    def rollback(self): ...
    def transaction(self): ...
    def commit_on_success(self, fn): ...
    def disable_autocommit(self): ...

class Transaction:
    def __enter__(self): ...
    def __exit__(self, exc_type, exc_val, exc_tb): ...

Transactions

Cursor Operations

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

class Cursor:
    def reset(self): ...
    def seek(self, key, flags=...): ...
    def first(self): ...
    def last(self): ...
    def next_entry(self): ...
    def previous_entry(self): ...
    def key(self): ...
    def value(self): ...
    def delete(self): ...
    def is_valid(self): ...
    def fetch_until(self, stop_key, include_stop_key=True): ...

Cursor Operations

Jx9 Scripting

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

class VM:
    def compile(self): ...
    def execute(self): ...
    def reset(self): ...
    def close(self): ...
    def set_value(self, name, value): ...
    def get_value(self, name): ...
    def set_values(self, dict data): ...
    def __setitem__(self, name, value): ...
    def __getitem__(self, name): ...

Jx9 Scripting

JSON Collections

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

class Collection:
    def create(self): ...
    def drop(self): ...
    def exists(self): ...
    def store(self, record, return_id=True): ...
    def fetch(self, record_id): ...
    def update(self, record_id, record): ...
    def delete(self, record_id): ...
    def all(self): ...
    def filter(self, filter_fn): ...
    def set_schema(self, _schema=None, **kwargs): ...
    def get_schema(self): ...

JSON Collections

Utility Functions

Random data generation and library information utilities.

class UnQLite:
    def random_string(self, int nbytes): ...
    def random_int(self): ...
    def lib_version(self): ...

Utility Functions

Constants

Database open flags and configuration constants.

# Database open flags
UNQLITE_OPEN_READONLY: int
UNQLITE_OPEN_READWRITE: int  
UNQLITE_OPEN_CREATE: int
UNQLITE_OPEN_EXCLUSIVE: int
UNQLITE_OPEN_TEMP_DB: int
UNQLITE_OPEN_NOMUTEX: int
UNQLITE_OPEN_OMIT_JOURNALING: int
UNQLITE_OPEN_IN_MEMORY: int
UNQLITE_OPEN_MMAP: int

# Cursor positioning flags
UNQLITE_CURSOR_MATCH_EXACT: int
UNQLITE_CURSOR_MATCH_LE: int
UNQLITE_CURSOR_MATCH_GE: int

Exception Handling

Error handling and exception types for database operations.

class UnQLiteError(Exception):
    def __init__(self, msg, errno): ...
    
    @property
    def errno(self): ...
    
    @property  
    def error_message(self): ...
    
    def __repr__(self): ...

Standard Python exceptions are also used:

  • KeyError: Raised when accessing non-existent keys
  • MemoryError: Raised when out of memory
  • NotImplementedError: Raised for unsupported operations