.. Tapestry documentation master file

Tapestry
========

**Tapestry** is a modern Python ORM for `SurrealDB <https://surrealdb.com>`_, built on top of `Pydantic <https://docs.pydantic.dev/>`_ for robust data validation and type safety.

Tapestry makes it intuitive to work with SurrealDB's powerful graph database features using familiar Python classes and type hints. Define your schema as Pydantic models, and Tapestry handles the rest - from generating SurrealQL schemas to managing relationships and complex queries.

.. toctree::
   :maxdepth: 2
   :caption: Contents

   installation
   quickstart
   api/index

Key Features
------------

✨ **Type Safe**
   Full type hints and Pydantic validation for better IDE support and fewer runtime errors

🔗 **Graph Relationships**
   First-class support for nodes and edges with intuitive relationship modeling

🚀 **Simple & Pythonic**
   Clean API that feels natural to Python developers

🔍 **Query Builder**
   Expressive query construction with support for graph traversals

📝 **Schema Generation**
   Automatic SurrealQL schema generation from your Python models

Quick Example
-------------

.. code-block:: python

   from tapestry import Node, Edge
   from datetime import date

   # Define your models
   class Person(Node):
       name: str
       email: str
       date_of_birth: date

   class FriendOf(Edge):
       in_: Person
       out_: Person
       since: date

   # Use them with SurrealDB
   async with db_session as db:
       # Create records
       alice = await Person(
           name="Alice",
           email="alice@example.com",
           date_of_birth=date(1990, 1, 1)
       ).create(db)

       bob = await Person(
           name="Bob",
           email="bob@example.com",
           date_of_birth=date(1992, 5, 15)
       ).create(db)

       # Create relationships
       friendship = await FriendOf(
           in_=alice,
           out_=bob,
           since=date.today()
       ).relate(db)

Installation
------------

Install Tapestry using pip:

.. code-block:: bash

   pip install tapestry-orm

Or using uv:

.. code-block:: bash

   uv add tapestry-orm

Requirements
------------

- Python 3.12+
- SurrealDB 1.0+
- Pydantic 2.0+

Why Tapestry?
-------------

SurrealDB is a powerful multi-model database that combines SQL, NoSQL, and Graph databases. However, working with it directly requires writing SurrealQL queries as strings, which can be error-prone and lacks the benefits of Python's type system.

Tapestry bridges this gap by providing:

**Type-Safe Schema Definition**
   Define your database schema using Python classes with full type hints

**Automatic Validation**
   Leverage Pydantic's validation to catch errors before they reach the database

**Intuitive API**
   Work with database records as Python objects with familiar methods

**Graph Operations**
   Express complex graph traversals using Python operators (``>>`` and ``<<``)

**IDE Support**
   Get autocompletion, type checking, and inline documentation in your IDE

License
-------

Tapestry is open source software, licensed under the MIT License.

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`