qsave

QuickSave

QuickSave is a fast, memory-efficient, and lightweight key-value database designed for use in small applications. It operates as a pure Python solution, offering a dictionary-like interface for easy integration. QuickSave works efficiently without dependencies, but if you want to boost its performance even further, you can install msgspec, which significantly enhances its speed.

---

Documentation

📖 Table of Contents

• Why QuickSave?
• Installation
• Getting Started
• Examples
• License

---

Why QuickSave?

QuickSave stands out for its speed, memory efficiency, and simplicity. Here are some of the key reasons you should consider using it:

• 🚀 High Performance: QuickSave is designed to be fast, with minimal overhead.
• 💡 Low Memory Usage: The library is optimized for memory efficiency, making it a great choice for projects with limited resources.
• 🧵 Thread-Safe: It supports thread-safe operations, ensuring that it works reliably in concurrent environments.
• 🔀 Both sync and async support: You can use either sync or async version of QuickSave.
• 🏎️ Boosted Performance with msgspec: By installing the optional msgspec library, you can further enhance QuickSave's performance, especially when handling complex data types.
• 🔧 No Dependencies: QuickSave is a pure Python library, which means it has no external dependencies, making it easy to install and use in any Python project.

---

Installation

Install QuickSave using pip:

pip install --upgrade qsave

Optionally, install msgspec to boost performance:

pip install msgspec==0.19.0

If you want use async version of QuickSave:

pip install qsave[async]

Getting Started

To start using QuickSave, import it and initialize your database:

from qsave import QuickSave

db = QuickSave(path="path/to/your/file.json", pretty=True)

The pretty argument beautifies the saved data for better readability (optional).

---

Examples

Basic Usage

By default, changes are automatically saved when the with block ends:

with db.session() as session:
    session["key"] = "value"
    print(session.get("key"))  # Output: None, not yet saved

# Exiting the block automatically commits changes
with db.session() as session:
    print(session.get("key"))  # Output: value

Manual Commit (commit_on_expire=False)

For full control over when changes are saved, use commit_on_expire=False:

with db.session(commit_on_expire=False) as session:
    session["key"] = "manual_value"
    print(session.get("key"))  # Output: None, not yet saved
    session.commit()  # Now changes are saved
    print(session.get("key"))  # Output: manual_value

with db.session() as session:
    print(session.get("key"))  # Output: manual_value

Commit and Rollback

You can manually save or discard changes during a session:

with db.session() as session:
    session["key"] = "temp_value"
    session.rollback()  # Discard changes
    print(session.get("key"))  # Output: None

Nested Data

with db.session() as session:
    session["nested"] = {"key": [1, 2, 3]}
    session.commit()

with db.session() as session:
    print(session["nested"])  # Output: {"key": [1, 2, 3]}

Async version:

from qsave.asyncio import AsyncQuickSave

db = AsyncQuickSave("path/to/your/file.json")

async def main():
    async with db.session(False) as session:
        print(len(session))
        await session.commit()
        await session.rollback()  # NOTE: after commit, rollback does nothing :(
        # only commit and rollback need to be awaited
        # other functionalities remain the same as sync version

---

License

This repository is licensed under MIT License.