sqlite-database 0.7.2__tar.gz → 0.7.4__tar.gz

{sqlite_database-0.7.2 → sqlite_database-0.7.4}/.github/workflows/python-publish.yml

@@ -11,6 +11,7 @@ name: Upload Python Package
 on:
   release:
     types: [published]
+  workflow_dispatch:
 
 permissions:
   contents: read

{sqlite_database-0.7.2 → sqlite_database-0.7.4}/.gitignore

@@ -170,4 +170,7 @@ reports.txt
 records
 testdb.sqlite3
 /test*.py
-perf-counter.txt
+perf-counter.txt
+
+/transient/*
+!/transient/README.md

{sqlite_database-0.7.2/sqlite_database.egg-info → sqlite_database-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlite_database
-Version: 0.7.2
+Version: 0.7.4
 Summary: A weird wrapper for SQLite Connection
 Home-page: https://github.com/RimuEirnarn/sqlite_database
 Author: RimuEirnarn

sqlite_database-0.7.4/docs/ModelAPI.md

@@ -0,0 +1,261 @@
+# 📘 ModelAPI – A Friendly Guide to a Lightweight SQLite ORM
+
+> **Note**: ModelAPI uses a different structure than TableAPI! So if you're coming from that, treat this as a fresh start.
+
+---
+
+## 📚 Table of Contents
+
+- [📘 ModelAPI – A Friendly Guide to a Lightweight SQLite ORM](#-modelapi--a-friendly-guide-to-a-lightweight-sqlite-orm)
+  - [📚 Table of Contents](#-table-of-contents)
+  - [🧠 Introduction](#-introduction)
+  - [🚀 Getting Started](#-getting-started)
+    - [1. Bootstrapping the Database](#1-bootstrapping-the-database)
+    - [2. Creating a Model](#2-creating-a-model)
+      - [💡 How it works](#-how-it-works)
+    - [3. Running CRUD Operations](#3-running-crud-operations)
+      - [CREATE](#create)
+      - [READ](#read)
+        - [Advanced `.where()` filtering](#advanced-where-filtering)
+      - [UPDATE](#update)
+      - [DELETE](#delete)
+  - [🎮 Example App – CRUD in Action](#-example-app--crud-in-action)
+  - [🙋 FAQ](#-faq)
+  - [💡 Tips \& Notes](#-tips--notes)
+
+---
+
+## 🧠 Introduction
+
+**ModelAPI** gives you a Laravel-style, class-based ORM interface for SQLite in Python. It's minimal, fast, and easy to use.
+
+Think of it like this:
+
+- You define your data with Python classes.
+- The ORM handles schema definition, inserts, reads, updates, and deletes.
+- It's flexible enough for small scripts and powerful enough for CLI tools.
+
+---
+
+## 🚀 Getting Started
+
+Let’s walk through setting things up step-by-step!
+
+---
+
+### 1. Bootstrapping the Database
+
+Create a file like `db.py` to initialize your SQLite database.
+
+```py
+# db.py
+from sqlite_database import Database
+
+db = Database(":memory:")  # or use "your_file.db" to persist data
+```
+
+This creates a simple in-memory SQLite database. For persistent storage, pass a filename instead of `":memory:"`.
+
+---
+
+### 2. Creating a Model
+
+Each model is a Python class with typed fields and a schema definition.
+
+```py
+# model/notes.py
+from uuid import uuid4
+from sqlite_database import model, BaseModel, Primary
+from ..db import db
+
+@model(db)
+class Notes(BaseModel):
+    __schema__ = (Primary('id'),)
+    __auto_id__ = lambda: str(uuid4())
+
+    id: str
+    title: str
+    content: str
+```
+
+#### 💡 How it works
+
+- `@model(db)` binds the class to the database.
+- `__schema__` defines your table schema. You can use `Primary()`, `Unique()`, `Foreign()`, etc.
+- `__auto_id__` is optional. It helps generate IDs automatically (e.g. UUIDs).
+
+---
+
+### 3. Running CRUD Operations
+
+#### CREATE
+
+```py
+Notes.create(title="Hello", content="World!")
+```
+
+You can gather user input too:
+
+```py
+title = input('Title: ')
+content = input('Content: ')
+Notes.create(title=title, content=content)
+```
+
+---
+
+#### READ
+
+You can fetch all rows, one row, or use filters:
+
+```py
+Notes.all()                  # Returns a list of all notes
+Notes.first(id="123")        # Returns the first match or None
+Notes.one(id="123")          # Returns exactly one result, else throws error
+```
+
+##### Advanced `.where()` filtering
+
+```py
+# Find a note by title
+note = Notes.where(title="Shopping List").fetch_one()
+
+# Limit or offset
+Notes.where().limit(5).fetch()     # Get top 5 notes
+Notes.where().offset(5).fetch()    # Skip 5 and get the rest
+
+# Count matching rows
+count = Notes.where().count()
+```
+
+---
+
+#### UPDATE
+
+Updating a row is super simple. Fetch it first, then call `.update()`:
+
+```py
+note = Notes.first(id="some-id")
+note.update(title="Updated", content="Updated content here.")
+```
+
+---
+
+#### DELETE
+
+Delete just like you'd update:
+
+```py
+note = Notes.first(id="some-id")
+note.delete()
+```
+
+---
+
+## 🎮 Example App – CRUD in Action
+
+Here’s a small CLI app to tie it all together:
+
+```py
+from enum import IntEnum
+from uuid import uuid4
+from sqlite_database import Database, model, BaseModel, Primary
+
+db = Database(":memory:")
+
+@model(db)
+class Notes(BaseModel):
+    __schema__ = (Primary('id'),)
+    __auto_id__ = lambda: str(uuid4())
+
+    id: str
+    title: str
+    content: str
+
+def display():
+    print('-'*3)
+    for note in Notes.all():
+        print(f"ID      : {note.id}")
+        print(f"Title   : {note.title}")
+        print(f"Content : {note.content}")
+        print("-"*3)
+
+def create():
+    title = input("Title: ")
+    content = input("Content: ")
+    Notes.create(title=title, content=content)
+
+def update():
+    note_id = input('ID: ')
+    note = Notes.first(id=note_id)
+    if note:
+        title = input("New title: ")
+        content = input("New content: ")
+        note.update(title=title, content=content)
+    else:
+        print("Note not found.")
+
+def delete():
+    note_id = input('ID: ')
+    note = Notes.first(id=note_id)
+    if note:
+        note.delete()
+    else:
+        print("Note not found.")
+
+class CMD(IntEnum):
+    DISPLAY = 1
+    CREATE = 2
+    UPDATE = 3
+    DELETE = 4
+    EXIT = 5
+
+def main():
+    while True:
+        print('-'*8)
+        print('1. Display all notes')
+        print('2. Create a note')
+        print('3. Update a note')
+        print('4. Delete a note')
+        print('5. Exit')
+        try:
+            cmd = int(input("Command: "))
+            if cmd == CMD.DISPLAY:
+                display()
+            elif cmd == CMD.CREATE:
+                create()
+            elif cmd == CMD.UPDATE:
+                update()
+            elif cmd == CMD.DELETE:
+                delete()
+            elif cmd == CMD.EXIT:
+                break
+        except KeyboardInterrupt:
+            break
+        except Exception as exc:
+            print(f"{type(exc).__name__}: {exc}")
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+## 🙋 FAQ
+
+**Q: Can I define relationships between models?**
+A: Yes, using `Foreign()` in `__schema__`. This doc will be updated with examples soon.
+
+**Q: Does it support migrations?**
+A: Not directly. The schema is defined per-model, so migrations require manual changes.
+
+**Q: How are models stored?**
+A: The models reflect SQLite tables. Everything is automatically synced on class definition.
+
+---
+
+## 💡 Tips & Notes
+
+- You can use any primitive Python types (e.g. `int`, `str`, `float`) in your model class.
+- Keep `__auto_id__` short and efficient — UUIDs are recommended.
+- Don’t forget to call `Database()` only once and reuse the instance.

{sqlite_database-0.7.2 → sqlite_database-0.7.4}/docs/SimpleGuide.md

@@ -1,10 +1,10 @@
-# SQLite Database (Beginner-Friendly Guide)
+# SQLite Database (Beginner-Friendly Guide to Table API)
 
 This library is a simple wrapper for Python's built-in SQLite package. It simplifies database operations, making it easier to interact with SQLite without writing complex SQL queries.
 
 ## Table of Contents
 
-- [SQLite Database (Beginner-Friendly Guide)](#sqlite-database-beginner-friendly-guide)
+- [SQLite Database (Beginner-Friendly Guide to Table API)](#sqlite-database-beginner-friendly-guide-to-table-api)
   - [Table of Contents](#table-of-contents)
   - [Introduction](#introduction)
   - [Getting Started](#getting-started)
@@ -39,6 +39,8 @@ SQLite is a small and fast database engine that stores all data in a single file
 
 This library itself is intended to help around your life from having to write SQL statements unless in specific cases. For now, implemented API is Table API which is what is this documentation will show to you.
 
+There's 2 taste what we've developed, both are named as "TableAPI" and "ModelAPI". Refer to [this for ModelAPI](./ModelAPI.md)
+
 ### Installation
 
 If the library is available on PyPI, install it using:
@@ -107,8 +109,8 @@ print(all_users)  # Output: [Row(id=1, name='Alice'), Row(id=2, name='Bob'), Row
 To fetch only names:
 
 ```python
-user_names = users.select(only=("name",))
-print(user_names)  # Output: [Row(name='Alice'), Row(name='Bob'), Row(name='Charlie')]
+user_names = users.select(what=("name",))
+print(user_names)  # Output: ['Alice', 'Bob', 'Charlie']
 ```
 
 ### Updating Data

sqlite_database-0.7.4/docs/_.md

@@ -0,0 +1,251 @@
+# 🍃 ModelAPI: Lightweight SQLite ORM
+
+A simple, model-centric ORM for SQLite that feels familiar if you've used Laravel's Eloquent. Designed for fast prototyping and projects that value readability and minimalism.
+
+> **Heads up:** `ModelAPI` is **not** the same as `TableAPI`. While both serve as ORMs, `ModelAPI` focuses on declarative, class-based models — ideal for those who prefer OOP-style code.
+
+---
+
+## 📘 Table of Contents
+
+- [🍃 ModelAPI: Lightweight SQLite ORM](#-modelapi-lightweight-sqlite-orm)
+  - [📘 Table of Contents](#-table-of-contents)
+  - [🚀 Getting Started](#-getting-started)
+    - [🧩 Installation](#-installation)
+    - [🛠 Database Setup](#-database-setup)
+  - [🧱 Defining Models](#-defining-models)
+    - [🏷 `__schema__` and Field Declarations](#-__schema__-and-field-declarations)
+    - [🔁 Auto-Generating IDs](#-auto-generating-ids)
+  - [🛠 CRUD Operations](#-crud-operations)
+    - [✅ Create](#-create)
+    - [🔍 Read](#-read)
+      - [`all()`, `first()`, and `one()`](#all-first-and-one)
+      - [Flexible Queries with `where()`](#flexible-queries-with-where)
+    - [📝 Update](#-update)
+    - [🗑 Delete](#-delete)
+  - [💻 CLI Example](#-cli-example)
+  - [🧠 Best Practices](#-best-practices)
+  - [⚠️ Common Pitfalls](#️-common-pitfalls)
+
+---
+
+## 🚀 Getting Started
+
+### 🧩 Installation
+
+You’ll need the core dependency, `sqlite-database`:
+
+```bash
+pip install sqlite-database
+```
+
+If you're developing locally and already have it, just ensure it's accessible in your Python path.
+
+---
+
+### 🛠 Database Setup
+
+Start by initializing your database:
+
+```python
+# db.py
+from sqlite_database import Database
+
+db = Database("notes.db")  # Or use ":memory:" for an in-memory DB
+```
+
+You’ll reuse `db` across all your models.
+
+---
+
+## 🧱 Defining Models
+
+Models define how your data is structured. Think of each model as a table blueprint.
+
+```python
+# model/notes.py
+from sqlite_database import model, BaseModel, Primary
+from db import db
+
+@model(db)
+class Notes(BaseModel):
+    __schema__ = (Primary('id'),)
+
+    id: str
+    title: str
+    content: str
+```
+
+### 🏷 `__schema__` and Field Declarations
+
+Define your fields using schema helpers like:
+
+- `Primary(field_name)`
+- `Unique(field_name)`
+- `Foreign(field_name, f"{ref_table}/{ref_column}")`
+
+These help ensure integrity and enforce constraints under the hood.
+
+---
+
+### 🔁 Auto-Generating IDs
+
+If your primary key is a UUID or something dynamic, define `__auto_id__`:
+
+```python
+from uuid import uuid4
+
+@model(db)
+class Notes(BaseModel):
+    __schema__ = (Primary("id"),)
+    __auto_id__ = lambda: str(uuid4())
+
+    id: str
+    title: str
+    content: str
+```
+
+Whenever you call `.create()` without an `id`, this auto-generator kicks in.
+
+---
+
+## 🛠 CRUD Operations
+
+### ✅ Create
+
+Create a new record like this:
+
+```python
+Notes.create(title="Meeting", content="Discuss roadmap")
+```
+
+Interactive input? No problem:
+
+```python
+title = input("Title: ")
+content = input("Content: ")
+Notes.create(title=title, content=content)
+```
+
+---
+
+### 🔍 Read
+
+#### `all()`, `first()`, and `one()`
+
+```python
+Notes.all()                 # Returns a list of all notes
+Notes.first(id="abc")       # First match or None
+Notes.one(id="abc")         # Exactly one match; raises error if 0 or >1
+```
+
+#### Flexible Queries with `where()`
+
+Chainable query builder:
+
+```python
+Notes.where(title="Roadmap").fetch_one()
+Notes.where().limit(5).fetch()
+Notes.where().offset(5).fetch()
+Notes.where().count()
+```
+
+---
+
+### 📝 Update
+
+First, fetch a record — then update it:
+
+```python
+note = Notes.first(id="abc")
+if note:
+    note.update(title="Updated title", content="Updated body")
+```
+
+---
+
+### 🗑 Delete
+
+```python
+note = Notes.first(id="abc")
+if note:
+    note.delete()
+```
+
+This permanently removes the record from the database.
+
+---
+
+## 💻 CLI Example
+
+Here’s a complete interactive CLI app:
+
+```python
+# cli.py
+from model.notes import Notes
+from enum import IntEnum
+
+class CMD(IntEnum):
+    DISPLAY = 1
+    CREATE = 2
+    UPDATE = 3
+    DELETE = 4
+    EXIT = 5
+
+def display():
+    print("---")
+    for note in Notes.all():
+        print(f"ID: {note.id}\nTitle: {note.title}\nContent: {note.content}\n---")
+
+def create():
+    Notes.create(title=input("Title: "), content=input("Content: "))
+
+def update():
+    note = Notes.first(id=input("ID: "))
+    if note:
+        note.update(title=input("Title: "), content=input("Content: "))
+    else:
+        print("Note not found.")
+
+def delete():
+    note = Notes.first(id=input("ID: "))
+    if note:
+        note.delete()
+    else:
+        print("Note not found.")
+
+def main():
+    while True:
+        print("1. Display\n2. Create\n3. Update\n4. Delete\n5. Exit")
+        try:
+            cmd = int(input("Select: "))
+            if cmd == CMD.DISPLAY: display()
+            elif cmd == CMD.CREATE: create()
+            elif cmd == CMD.UPDATE: update()
+            elif cmd == CMD.DELETE: delete()
+            elif cmd == CMD.EXIT: break
+        except Exception as e:
+            print(f"{type(e).__name__}: {e}")
+
+if __name__ == '__main__':
+    main()
+```
+
+---
+
+## 🧠 Best Practices
+
+✅ **Define all constraints in `__schema__`** — Primary, Foreign, and Unique.
+✅ **Use `__auto_id__`** for consistent ID generation (especially UUIDs).
+✅ **Keep models minimal** — push business logic elsewhere (CLI, service layer, etc).
+✅ Use `.where().count()` instead of loading all records just to count them.
+✅ Only use `.one()` when you’re 100% sure the result is unique.
+
+---
+
+## ⚠️ Common Pitfalls
+
+❌ Missing `@model(db)` — your model won’t be registered.
+❌ Using `.one()` on multi-match queries — it will throw an exception.
+❌ Forgetting `.fetch()` or `.fetch_one()` after `.where()` — it won’t run.
+❌ Assuming `.create()` returns an object — it returns `None`.

{sqlite_database-0.7.2 → sqlite_database-0.7.4}/docs/index.rst

@@ -14,8 +14,7 @@ SQLite Database
    :caption: SQLite Database
 
    SimpleGuide
-   usage
-   api_reference
+   ModelAPI
 
 
 Indices and tables

{sqlite_database-0.7.2 → sqlite_database-0.7.4}/pyproject.toml

@@ -25,7 +25,7 @@ Repository = "https://github.com/RimuEirnarn/sqlite_database.git"
 
 [tool.setuptools]
 zip-safe = true
-packages = ["sqlite_database", "sqlite_database.model"]
+packages = ["sqlite_database", "sqlite_database.models"]
 
 [project.optional-dependencies]
 dev = ["pytest", "pylint", "black"]

{sqlite_database-0.7.2 → sqlite_database-0.7.4}/sqlite_database/__init__.py

@@ -1,6 +1,6 @@
 """Database"""
 
-from .model import BaseModel, model, Foreign, Primary, Unique
+from .models import BaseModel, model, Foreign, Primary, Unique
 from .database import Database
 from ._utils import null, Row, Null
 from .column import Column, text, integer, blob, real
@@ -14,7 +14,7 @@ def test_installed():
     return True
 
 
-__version__ = "0.7.2"
+__version__ = "0.7.4"
 __all__ = [
     "Database",
     "Table",
@@ -29,7 +29,7 @@ __all__ = [
     "real",
     "blob",
     "BaseModel",
-    "model",
+    "models",
     "Foreign",
     "Primary",
     "Unique"

{sqlite_database-0.7.2 → sqlite_database-0.7.4}/sqlite_database/database.py

@@ -1,7 +1,8 @@
 """SQLite Database"""
 
 from atexit import register as finalize
-from sqlite3 import OperationalError, connect
+from sqlite3 import OperationalError, connect, Connection
+from threading import local
 from typing import Iterable, Literal, Optional
 
 from sqlite_database._debug import if_debug_print
@@ -43,14 +44,17 @@ class Database: # pylint: disable=too-many-instance-attributes
             del kwargs['forgive']
         if 'strict' in kwargs:
             del kwargs['strict']
-        self._database = connect(path, **kwargs)
-        self._database.row_factory = dict_factory
         self._config = None
         self._closed = False
         if not self._closed or self.__dict__.get("_initiated", False) is False:
             finalize(self._finalizer)
             self._initiated = True
         self._kwargs = kwargs
+        self._create_connection()
+
+    def _create_connection(self):
+        self._database = connect(self._path, **self._kwargs)
+        self._database.row_factory = dict_factory
 
     def _finalizer(self):
         self.close()
@@ -224,3 +228,30 @@ class Database: # pylint: disable=too-many-instance-attributes
     def sql(self):
         """SQL Connection"""
         return self._database
+
+class AsyncDatabase(Database):
+    """Async (threads, subprocess) ready"""
+
+    def __init__(self, path: str, **kwargs) -> None:
+        super().__init__(path, **kwargs)
+        self._local = local()
+
+    def _create_connection(self):
+        conn = getattr(self._local, "conn", None)
+        if conn is None:
+            timeout = self._kwargs.pop('timeout', 30)
+            conn = connect(
+                self._path,
+                timeout=timeout,
+                isolation_level=self._kwargs.pop("isolation_level", None),
+                check_same_thread=self._kwargs.pop("check_same_thread", False)
+            )
+            conn.row_factory = dict_factory
+            conn.execute("PRAGMA journal_mode=WAL;")
+            if isinstance(timeout, int):
+                conn.execute(f'PRAGMA busy_timeout={timeout * 1000};')
+            self._local.conn = conn
+
+    @property
+    def _database(self) -> Connection:
+        return self._local.conn