Add asyncio support

.markdownlint.yaml

@@ -0,0 +1,4 @@
+MD013:
+  line_length: 80
+  tables: false
+MD028: false

.pre-commit-config.yaml

@@ -27,6 +27,7 @@ repos:
         # we need to force python 3.10 or it chokes on pytest v9+
         args: ["--strict", "--python-version", "3.10"]
         additional_dependencies:
+          - aiosqlite
           - pydantic
           - sqladmin
           - types-redis

README.md

@@ -13,7 +13,7 @@ is Pydantic itself.
 
 It does not aim to be a full-fledged ORM like SQLAlchemy, but rather a simple
 and easy-to-use library for basic database operations, especially for small
-projects. It is NOT asynchronous (at this time, though that is planned).
+projects. It supports both synchronous and asynchronous APIs.
 
 The ideal use case is more for Python CLI tools that need to store data in a
 database-like format without needing to learn SQL or use a full ORM.
@@ -51,6 +51,7 @@ Full documentation is available on the [Website](https://sqliter.grantramsay.dev
 - Foreign key relationships with referential integrity and CASCADE actions
 - ORM mode with lazy loading, reverse relationships, many-to-many support, and
   eager loading
+- Optional async support for database, query, and ORM usage
 - Chained Query building with filtering, ordering, and pagination
 - Projection and aggregation queries with grouping, aggregate helpers, and
   dictionary-based results
@@ -94,9 +95,10 @@ Currently by default, the only external dependency is Pydantic. However, there
 are some optional dependencies that can be installed to enable additional
 features:
 
+- `async`: Installs `aiosqlite` for `sqliter.asyncio` support
 - `demo`: Installs the Textual TUI framework for the interactive demo
 - `extras`: Installs Inflect for better pluralization of table names
-- `full`: Installs all optional dependencies (Textual and Inflect)
+- `full`: Installs all optional dependencies
 
 See [Installing Optional
 Dependencies](https://sqliter.grantramsay.dev/installation#optional-dependencies)
@@ -145,6 +147,10 @@ See the [Guide](https://sqliter.grantramsay.dev/guide/guide/) section of the
 documentation for more detailed information on how to use SQLiter, and advanced
 features.
 
+Async usage is available through `sqliter.asyncio` and `sqliter.asyncio.orm`.
+See the [async guide](https://sqliter.grantramsay.dev/guide/asyncio/) for the
+async API and async ORM relationship patterns.
+
 You can also run the interactive TUI demo to explore SQLiter features hands-on:
 
 ```bash

TODO.md

@@ -59,6 +59,8 @@ Items marked with :fire: are high priority.
 
 - Tidy up the test suite - remove any duplicates, sort them into logical files
   (many already are), try to reduce and centralize fixtures.
+- Add suitable icons to all TUI demo categories (currently all use `icon=""`)
+  for a more visually scannable tree view.
 
 ## Documentation
 

docs/api-reference/async-orm.md

@@ -0,0 +1,229 @@
+# Async ORM
+
+Async ORM support lives under `sqliter.asyncio.orm`.
+
+```python
+from sqliter.asyncio.orm import (
+    AsyncBaseDBModel,
+    AsyncForeignKey,
+    AsyncManyToMany,
+)
+```
+
+**Sources:** `sqliter/asyncio/orm/model.py`, `sqliter/asyncio/orm/fields.py`,
+`sqliter/asyncio/orm/query.py`, `sqliter/asyncio/orm/m2m.py`
+
+See also: [Guide -- Asyncio Support](../guide/asyncio.md)
+
+> [!NOTE]
+> Async ORM intentionally differs from sync ORM for lazy FK access:
+> sync uses `book.author.name`, while async lazy loading uses
+> `author = await book.author.fetch()`.
+
+---
+
+## `AsyncBaseDBModel`
+
+Base model for async ORM usage.
+
+```python
+from sqliter.asyncio.orm import AsyncBaseDBModel
+```
+
+Use this instead of `sqliter.orm.BaseDBModel` when the model is meant to be
+used with `AsyncSqliterDB`.
+
+### Behavior
+
+- forward FK fields return async-aware values
+- reverse FK accessors return async reverse query wrappers
+- many-to-many accessors return async managers
+- eager-loaded relations are returned directly from caches
+
+---
+
+## `AsyncForeignKey[T]`
+
+Async FK descriptor.
+
+```python
+class AsyncForeignKey(Generic[T]):
+    def __init__(
+        self,
+        to_model: type[T],
+        *,
+        on_delete: FKAction = "RESTRICT",
+        on_update: FKAction = "RESTRICT",
+        null: bool = False,
+        unique: bool = False,
+        related_name: str | None = None,
+        db_column: str | None = None,
+    ) -> None:
+```
+
+### Lazy access
+
+Accessing a forward FK on an instance returns either:
+
+- `None` for null FK values
+- the eager-loaded related object if already cached
+- an `AsyncLazyLoader[T]` otherwise
+
+Example:
+
+```python
+book = await db.get(Book, 1)
+loader = book.author
+author = await loader.fetch()
+```
+
+---
+
+## `AsyncLazyLoader[T]`
+
+Explicit async FK loader.
+
+### `fetch()`
+
+```python
+async def fetch(self) -> T | None:
+```
+
+Loads the related object and caches it on the loader.
+
+### `db_context`
+
+Read-only property exposing the current DB context.
+
+### `__getattr__()`
+
+Raises `AttributeError` with guidance to call `await relation.fetch()` first.
+
+---
+
+## `AsyncReverseQuery`
+
+Returned by reverse FK accessors such as `author.books`.
+
+### Query-building methods
+
+- `filter(**kwargs)`
+- `limit(count)`
+- `offset(count)`
+
+### Async terminal methods
+
+- `await fetch_all()`
+- `await fetch_one()`
+- `await count()`
+- `await exists()`
+
+Example:
+
+```python
+author = await db.get(Author, 1)
+books = await author.books.filter(title="Guide").fetch_all()
+```
+
+---
+
+## `AsyncPrefetchedResult`
+
+Returned when a reverse FK relation was loaded through `prefetch_related()`.
+
+Read methods:
+
+- `await fetch_all()`
+- `await fetch_one()`
+- `await count()`
+- `await exists()`
+
+`filter(**kwargs)` falls back to a real `AsyncReverseQuery`.
+
+---
+
+## `AsyncManyToMany[T]`
+
+Async many-to-many descriptor.
+
+```python
+class AsyncManyToMany(Generic[T]):
+    def __init__(
+        self,
+        to_model: type[T] | str,
+        *,
+        through: str | None = None,
+        related_name: str | None = None,
+        symmetrical: bool = False,
+    ) -> None:
+```
+
+Accessing the descriptor from an instance returns an async manager or a
+prefetched wrapper.
+
+---
+
+## `AsyncManyToManyManager[T]`
+
+Returned by many-to-many accessors such as `article.tags`.
+
+### Read/query methods
+
+- `await fetch_all()`
+- `await fetch_one()`
+- `await count()`
+- `await exists()`
+- `await filter(**kwargs)`
+
+### Write methods
+
+- `await add(*instances)`
+- `await remove(*instances)`
+- `await clear()`
+- `await set(*instances)`
+
+### Property
+
+- `sql_metadata`
+
+Example:
+
+```python
+await article.tags.add(tag)
+tags = await article.tags.fetch_all()
+```
+
+---
+
+## `AsyncPrefetchedM2MResult[T]`
+
+Returned when an M2M relation was loaded through `prefetch_related()`.
+
+Read methods are served from cache:
+
+- `await fetch_all()`
+- `await fetch_one()`
+- `await count()`
+- `await exists()`
+
+Write methods delegate to the real manager:
+
+- `await add(*instances)`
+- `await remove(*instances)`
+- `await clear()`
+- `await set(*instances)`
+
+`await filter(**kwargs)` falls back to a real async query.
+
+---
+
+## `AsyncReverseManyToMany`
+
+Reverse-side async many-to-many descriptor installed on the related model when
+`related_name` is defined.
+
+Example:
+
+```python
+articles = await tag.articles.fetch_all()
+```