tapestry-orm 0.0.1__tar.gz → 0.0.2__tar.gz

{tapestry_orm-0.0.1 → tapestry_orm-0.0.2}/PKG-INFO

@@ -1,16 +1,26 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: tapestry-orm
-Version: 0.0.1
+Version: 0.0.2
 Summary: A prototype ORM for SurrealDB
 Author-email: timothee@obrecht.xyz
-License: MIT
+License-Expression: MIT
 Requires-Dist: more-itertools>=10.7.0
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: surrealdb>=1.0.6
+Requires-Dist: sphinx>=7.2.0 ; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2.0.0 ; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=2.0.0 ; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5.2 ; extra == 'docs'
+Requires-Dist: myst-parser>=2.0.0 ; extra == 'docs'
+Requires-Dist: sphinx-autobuild>=2021.3.14 ; extra == 'docs'
+Requires-Dist: sphinx-autoapi>=3.0.0 ; extra == 'docs'
 Requires-Python: >=3.12
+Project-URL: Documentation, https://readthedocs.org
+Project-URL: Repository, https://gitlab.com/timete_OS/tapestry-orm
+Provides-Extra: docs
 Description-Content-Type: text/markdown
 
-# 🚀 Tapestry
+# Tapestry
 
 **A modern, type-safe Python ORM for SurrealDB**
 
@@ -341,7 +351,7 @@ To test the GitLab CI pipeline locally before pushing, use [`gitlab-ci-local`](h
 
 ```bash
 # Run the test job locally (configuration is already set up)
-gitlab-ci-local test
+gitlab-ci-local
 ```
 
 The project includes two configuration files that make this work:

{tapestry_orm-0.0.1 → tapestry_orm-0.0.2}/README.md

@@ -1,4 +1,4 @@
-# 🚀 Tapestry
+# Tapestry
 
 **A modern, type-safe Python ORM for SurrealDB**
 
@@ -329,7 +329,7 @@ To test the GitLab CI pipeline locally before pushing, use [`gitlab-ci-local`](h
 
 ```bash
 # Run the test job locally (configuration is already set up)
-gitlab-ci-local test
+gitlab-ci-local
 ```
 
 The project includes two configuration files that make this work:

{tapestry_orm-0.0.1 → tapestry_orm-0.0.2}/pyproject.toml

@@ -1,21 +1,38 @@
 [project]
 name = "tapestry-orm"
-version = "0.0.1"
+version = "0.0.2"
 description = "A prototype ORM for SurrealDB"
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["licence.txt"]
 authors = [
     { email = "timothee@obrecht.xyz" }
 ]
+project_page = "https://gitlab.com/timete_OS/tapestry-orm"
 requires-python = ">=3.12"
 dependencies = [
     "more-itertools>=10.7.0",
     "pydantic>=2.11.7",
     "surrealdb>=1.0.6",
 ]
+[project.urls]
+Repository = "https://gitlab.com/timete_OS/tapestry-orm"
+Documentation = "https://readthedocs.org"
+
+[project.optional-dependencies]
+docs = [
+    "sphinx>=7.2.0",
+    "sphinx-rtd-theme>=2.0.0",
+    "sphinx-autodoc-typehints>=2.0.0",
+    "sphinx-copybutton>=0.5.2",
+    "myst-parser>=2.0.0",
+    "sphinx-autobuild>=2021.3.14",
+    "sphinx-autoapi>=3.0.0",
+]
 
 [dependency-groups]
 dev = [
+    "basedpyright>=1.32.1",
     "pytest>=8.4.1",
     "pytest-asyncio>=1.1.0",
     "testcontainers>=4.12.0",
@@ -25,13 +42,7 @@ dev = [
 misc = [
     "pandas>=2.3.1",
     "ipykernel>=6.30.1",
-    "sphinx>=7.2.0",
-    "sphinx-rtd-theme>=2.0.0",
-    "sphinx-autodoc-typehints>=2.0.0",
-    "sphinx-copybutton>=0.5.2",
-    "myst-parser>=2.0.0",
     "mypy>=1.18.2",
-    "pyright>=1.1.406",
 ]
 
 [build-system]
@@ -41,16 +52,7 @@ build-backend = "uv_build"
 [tool.uv.build-backend]
 module-name = "tapestry"
 
-[tool.uv.sources]
-# territories = { path = "../territories", editable = true }
-
 [tool.pytest.ini_options]
 filterwarnings = [
     "ignore::DeprecationWarning:testcontainers.*",
 ]
-
-[[tool.uv.index]]
-name = "datapolitics"
-url = "http://pypi.hedwige.fr:8080"
-publish-url = "http://pypi.hedwige.fr:8080"
-allow-insecure-host = ["http://pypi.hedwige.fr:8080"]

tapestry_orm-0.0.2/src/tapestry/__init__.py

@@ -0,0 +1,11 @@
+__all__ = [
+    "Base", "Text", "create_engine", "create_engine_context", "Engine", "Reference", "Node", "Edge", "Q"
+]
+
+from .query import Q
+from .base import Base
+from .node import Node
+from .edge import Edge
+from .tokenizer import Text
+from .table import Reference
+from .engine import create_engine, create_engine_context, Engine

{tapestry_orm-0.0.1 → tapestry_orm-0.0.2}/src/tapestry/base.py

@@ -1,19 +1,21 @@
 from __future__ import annotations
 
+from collections.abc import Mapping
 import inspect
+import types
 
 from enum import Enum
 from copy import deepcopy
 from itertools import chain
 from queue import LifoQueue
+from surrealdb import RecordID
+from typing import  Any, ClassVar, Unpack, get_origin, get_args
 from pydantic_core.core_schema import ValidationInfo
 from pydantic.fields import FieldInfo, ComputedFieldInfo
-from surrealdb import AsyncWsSurrealConnection, AsyncHttpSurrealConnection, RecordID
-from typing import  Any, ClassVar, Optional, Self, Any, Unpack, Union, Type, get_args
-from pydantic import BaseModel, field_validator, model_serializer, field_serializer, Field, ConfigDict, model_validator
+from pydantic import BaseModel, field_validator, model_serializer, Field, ConfigDict
 
-from .table import Table, Reference
-from .utils import convert_types, replace_type, flatten_type
+from .table import Table
+from .utils import convert_types, replace_type
 from .field import Field as CustomField, NestedFieldDescriptor, ComputedFieldDescriptor
 
 
@@ -57,20 +59,21 @@ class Base(BaseModel):
     """
     id: RecordID | None = Field(exclude=False, default = None)
 
-    model_config = {
-        "arbitrary_types_allowed": True,
-        "use_enum_values": False, # would be great to have a 'use_enum_names'
-        "validate_assignment": True
-    }
+    model_config: ClassVar[ConfigDict] = ConfigDict(
+        arbitrary_types_allowed=True,
+        use_enum_values=False, # would be great to have a 'use_enum_names'
+        validate_assignment=True
+    )
     _registry: ClassVar[tuple[Table, ...]] = ()
     _tokenizers: ClassVar[set[str]] = set()
     _to_create: ClassVar[LifoQueue[Base]]
-    child_classes: ClassVar[dict[str, Type[Base]]] = {}
+    _discarded: ClassVar[bool] = False
+    child_classes: ClassVar[dict[str, type[Base]]] = {}
 
 
     @classmethod
     @field_validator('id')
-    def validate_record_id(cls, v: Any) -> Optional[RecordID]:
+    def validate_record_id(cls, v: Any) -> RecordID | None:
         """
         Validate and convert record ID values.
 
@@ -168,7 +171,7 @@ class Base(BaseModel):
         # Create unique queue for each subclass
         # this queue will be used to chain several object creations
         cls._to_create = LifoQueue()
-        cls._discarded = discarded
+        cls._discarded = bool(discarded)
         return super().__init_subclass__(**kwargs)
 
 
@@ -180,8 +183,9 @@ class Base(BaseModel):
         if cls._discarded:
             return
 
-        model_fields: dict[str, FieldInfo | ComputedFieldInfo] = deepcopy(cls.model_fields)
-        model_fields.update(cls.model_computed_fields)
+        model_fields_copy: dict[str, FieldInfo | ComputedFieldInfo] = dict(deepcopy(cls.model_fields))
+        model_fields_copy.update(cls.model_computed_fields)  # type: ignore[arg-type]
+        model_fields: Mapping[str, FieldInfo | ComputedFieldInfo] = model_fields_copy
         fields: list[CustomField[Any]] = []
         for field_name, field_info in model_fields.items():
             field_type = field_info.annotation if isinstance(field_info, FieldInfo) else field_info.return_type
@@ -198,9 +202,9 @@ class Base(BaseModel):
                 if field_type and hasattr(field_type, '__mro__') and Base in field_type.__mro__:
                     nested_class = field_type
                 # Check if it's Optional[Base subclass] (Union with None)
-                elif hasattr(field_type, '__origin__') and field_type.__origin__ is Union:
+                elif get_origin(field_type) is types.UnionType or (get_origin(field_type) is not None and hasattr(get_origin(field_type), '__name__') and get_origin(field_type).__name__ == 'UnionType'):
                     # Get the args of the Union
-                    args = getattr(field_type, '__args__', ())
+                    args = get_args(field_type)
                     # Filter out None and check if any remaining type is a Base subclass
                     for arg in args:
                         if arg is not type(None) and hasattr(arg, '__mro__') and Base in arg.__mro__:
@@ -219,7 +223,7 @@ class Base(BaseModel):
 
             # replace Base instance with Union[annotation, RecordID]
             if field_name in cls.model_fields:
-                cls.model_fields[field_name].annotation = replace_type(cls.model_fields[field_name].annotation, Base, Union[Base, RecordID])
+                cls.model_fields[field_name].annotation = replace_type(cls.model_fields[field_name].annotation, Base, Base | RecordID)
 
 
         table = Table(name=cls.__name__.lower(), base_class=Base, model_class=cls, fields=tuple(fields), relation=relation)
@@ -249,7 +253,7 @@ class Base(BaseModel):
 
 
     @classmethod
-    def add_table(cls, table: Table, child_class: Type[Base]):
+    def add_table(cls, table: Table, child_class: type[Base]):
         """
         Register a new table in the system registry.
 

{tapestry_orm-0.0.1 → tapestry_orm-0.0.2}/src/tapestry/edge.py

@@ -1,6 +1,6 @@
 from abc import ABC
 from copy import deepcopy
-from typing import Self, Iterable, get_type_hints, Any, ClassVar, Union, TYPE_CHECKING
+from typing import Self, Iterable, get_type_hints, Any, ClassVar, TYPE_CHECKING
 from pydantic.fields import FieldInfo, ComputedFieldInfo
 from surrealdb import AsyncWsSurrealConnection, AsyncHttpSurrealConnection, RecordID
 
@@ -113,8 +113,8 @@ class Edge(Base, ABC, discarded=True):
         super().__pydantic_init_subclass__(relation=relation, **kwargs)
         # need to add those back for validation at instanciation
         # otherwise, the field is skipped
-        in_.annotation = replace_type(in_.annotation, Base, Union[Base, RecordID])
-        out_.annotation = replace_type(out_.annotation, Base, Union[Base, RecordID])
+        in_.annotation = replace_type(in_.annotation, Base, Base | RecordID)
+        out_.annotation = replace_type(out_.annotation, Base, Base | RecordID)
         cls.model_fields["in_"] = in_
         cls.model_fields["out_"] = out_
         cls.model_rebuild(force=True)

tapestry_orm-0.0.2/src/tapestry/engine.py

@@ -0,0 +1,398 @@
+import asyncio
+import logging
+import contextlib
+from typing import Optional
+
+from collections.abc import AsyncIterator
+from surrealdb import AsyncSurreal, AsyncWsSurrealConnection, AsyncHttpSurrealConnection
+
+
+logger = logging.getLogger(__name__)
+
+
+class Engine:
+    """
+    SurrealDB connection pool engine, similar to SQLAlchemy's engine.
+
+    This class manages a pool of authenticated SurrealDB connections that can be
+    reused across async operations. It provides a clean API for connection management
+    with context managers.
+
+    The Engine should be created with `create_engine()` and manages its own lifecycle.
+
+    Attributes:
+        url: SurrealDB connection URL
+        auth_payload: Authentication credentials dictionary
+        pool_size: Number of connections to maintain in the pool
+        connect_timeout: Timeout for connection attempts in seconds
+
+    Example:
+        >>> # Create and start engine
+        >>> engine = create_engine(
+        ...     url="ws://localhost:8000/rpc",
+        ...     auth_payload={"username": "root", "password": "root"},
+        ...     pool_size=5
+        ... )
+        >>> await engine.start()
+        >>>
+        >>> # Use connections via context manager
+        >>> async with engine.connect() as db:
+        ...     await db.use("mydb", "myns")
+        ...     results = await db.select("person")
+        >>>
+        >>> # Close when done
+        >>> await engine.close()
+
+        Or use with lifecycle context manager:
+        >>> async with create_engine_context(url, auth_payload) as engine:
+        ...     async with engine.connect() as db:
+        ...         # use db
+        ...         pass
+    """
+
+    def __init__(
+        self,
+        url: str,
+        auth_payload: dict,
+        pool_size: int = 4,
+        connect_timeout: float = 5.0,
+    ):
+        """
+        Initialize the engine.
+
+        Note: The engine is not started automatically. Call await engine.start()
+        or use create_engine_context() for automatic lifecycle management.
+
+        Args:
+            url: SurrealDB connection URL (ws:// or http://)
+            auth_payload: Dictionary with authentication credentials
+            pool_size: Number of connections to maintain (default: 4)
+            connect_timeout: Connection timeout in seconds (default: 5.0)
+        """
+        self.url = url
+        self.auth_payload = auth_payload
+        self.pool_size = pool_size
+        self.connect_timeout = connect_timeout
+        self._queue: Optional[asyncio.Queue] = None
+        self._clients: list = []
+        self._closed = False
+        self._started = False
+
+    async def _make_client(self) -> AsyncSurreal:
+        """
+        Create and authenticate a single SurrealDB client.
+
+        Returns:
+            An authenticated AsyncSurreal client ready for use
+
+        Raises:
+            Exception: If connection or authentication fails
+        """
+        client = AsyncSurreal(self.url)
+        await client.signin(self.auth_payload)
+        return client
+
+    async def start(self) -> "Engine":
+        """
+        Initialize the connection pool with authenticated clients.
+
+        Creates the specified number of clients, authenticates them,
+        and adds them to the pool queue for reuse.
+
+        Returns:
+            self: Returns the engine instance for chaining
+
+        Raises:
+            RuntimeError: If the engine is already started or closed
+            Exception: If unable to create the required number of clients
+        """
+        if self._started:
+            raise RuntimeError("Engine already started")
+        if self._closed:
+            raise RuntimeError("Engine is closed")
+
+        self._queue = asyncio.Queue()
+
+        for i in range(self.pool_size):
+            try:
+                client = await self._make_client()
+            except Exception as e:
+                logger.exception("Failed to create surreal client #%d: %s", i, e)
+                # Retry once with backoff before giving up
+                await asyncio.sleep(0.5)
+                client = await self._make_client()
+
+            self._clients.append(client)
+            self._queue.put_nowait(client)
+
+        self._started = True
+        logger.info("SurrealDB engine started with %d connections", len(self._clients))
+        return self
+
+    async def close(self) -> None:
+        """
+        Close all connections and shut down the engine.
+
+        Drains the queue and closes all client connections gracefully.
+        This should be called when the application shuts down.
+        """
+        if self._closed:
+            return
+
+        self._closed = True
+
+        # Drain queue
+        if self._queue is not None:
+            while not self._queue.empty():
+                try:
+                    _ = self._queue.get_nowait()
+                    self._queue.task_done()
+                except asyncio.QueueEmpty:
+                    break
+
+        # Close all clients
+        for client in self._clients:
+            try:
+                await client.close()
+            except Exception:
+                logger.exception("Error closing surreal client")
+
+        self._clients.clear()
+        self._started = False
+        logger.info("SurrealDB engine closed")
+
+    @contextlib.asynccontextmanager
+    async def connect(self) -> AsyncIterator[AsyncWsSurrealConnection | AsyncHttpSurrealConnection]:
+        """
+        Acquire a connection from the pool as a context manager.
+
+        This is the primary way to get a database connection from the engine.
+        The connection is automatically returned to the pool when the context exits.
+
+        Yields:
+            AsyncWsSurrealConnection | AsyncHttpSurrealConnection: An authenticated client
+
+        Example:
+            >>> async with engine.connect() as db:
+            ...     await db.use("mydb", "myns")
+            ...     results = await db.select("person")
+
+        Raises:
+            RuntimeError: If the engine is not started or is closed
+            Exception: If the acquired client encounters a fatal error
+        """
+        if self._closed:
+            raise RuntimeError("Engine is closed")
+        if not self._started:
+            raise RuntimeError("Engine not started. Call await engine.start() first")
+
+        client = await self._queue.get()
+        try:
+            yield client
+        except Exception as exc:
+            # If the client had a fatal error, replace it
+            if self._is_fatal_client_error(exc):
+                logger.warning("Client had fatal error, replacing: %s", exc)
+                await self._replace_client(client)
+            raise
+        finally:
+            # Return to pool if not closed
+            if not self._closed and self._queue is not None:
+                self._queue.put_nowait(client)
+
+    # Alias for SQLAlchemy-like API
+    acquire = connect
+
+    async def execute(self, query: str, *args, retries: int = 1, backoff: float = 0.2, **kwargs):
+        """
+        Execute a query using a pooled connection with automatic retry.
+
+        Acquires a client from the pool, executes the query, and handles
+        retries for transient failures.
+
+        Args:
+            query: The query string to execute
+            *args: Arguments to pass to the query method
+            retries: Number of retry attempts for transient errors (default: 1)
+            backoff: Base backoff time in seconds between retries (default: 0.2)
+            **kwargs: Keyword arguments to pass to the query method
+
+        Returns:
+            Query results from SurrealDB
+
+        Raises:
+            RuntimeError: If the engine is not started
+            Exception: If the query fails after all retry attempts
+        """
+        if self._closed:
+            raise RuntimeError("Engine is closed")
+        if not self._started:
+            raise RuntimeError("Engine not started. Call await engine.start() first")
+
+        for attempt in range(retries + 1):
+            async with self.connect() as client:
+                try:
+                    return await client.query(query, *args, **kwargs)
+                except Exception as exc:
+                    logger.exception("Query failed on attempt %d: %s", attempt, exc)
+                    if attempt < retries and self._is_retryable_error(exc):
+                        await asyncio.sleep(backoff * (2 ** attempt))
+                        continue
+                    raise
+
+    async def _replace_client(self, dead_client: AsyncSurreal) -> None:
+        """
+        Replace a failed client with a new authenticated connection.
+
+        Closes the dead client, creates a new one, and adds it back to the pool
+        to maintain the pool size.
+
+        Args:
+            dead_client: The client connection that failed
+        """
+        try:
+            await dead_client.close()
+        except Exception:
+            pass
+
+        try:
+            new_client = await self._make_client()
+        except Exception as e:
+            logger.exception("Failed to create replacement client: %s", e)
+            # If we can't create a replacement, put back the old one to avoid pool starvation
+            if self._queue is not None and not self._closed:
+                self._queue.put_nowait(dead_client)
+            return
+
+        # Replace in internal list
+        try:
+            idx = self._clients.index(dead_client)
+            self._clients[idx] = new_client
+        except ValueError:
+            self._clients.append(new_client)
+
+        if self._queue is not None and not self._closed:
+            self._queue.put_nowait(new_client)
+
+    def _is_retryable_error(self, exc: Exception) -> bool:
+        """
+        Determine if an exception is retryable.
+
+        Args:
+            exc: The exception to check
+
+        Returns:
+            bool: True if the error is transient and worth retrying
+        """
+        return isinstance(exc, (asyncio.TimeoutError, ConnectionError))
+
+    def _is_fatal_client_error(self, exc: Exception) -> bool:
+        """
+        Determine if an exception indicates a broken client connection.
+
+        Args:
+            exc: The exception to check
+
+        Returns:
+            bool: True if the client connection is likely broken and needs replacement
+        """
+        return isinstance(exc, (ConnectionError, RuntimeError))
+
+
+def create_engine(
+    url: str,
+    auth_payload: dict,
+    pool_size: int = 4,
+    connect_timeout: float = 5.0,
+) -> Engine:
+    """
+    Create a connection pool engine for SurrealDB.
+
+    This function creates an Engine instance that manages a pool of authenticated
+    SurrealDB connections. The engine must be started with await engine.start()
+    before use.
+
+    Args:
+        url: SurrealDB connection URL (e.g., "ws://localhost:8000/rpc")
+        auth_payload: Dictionary with authentication credentials
+            Example: {"username": "root", "password": "root"}
+        pool_size: Number of connections to maintain in the pool (default: 4)
+        connect_timeout: Timeout for connection attempts in seconds (default: 5.0)
+
+    Returns:
+        Engine: An engine instance (not yet started)
+
+    Example:
+        >>> # Create and manually manage lifecycle
+        >>> engine = create_engine(
+        ...     "ws://localhost:8000/rpc",
+        ...     {"username": "root", "password": "root"},
+        ...     pool_size=5
+        ... )
+        >>> await engine.start()
+        >>>
+        >>> async with engine.connect() as db:
+        ...     await db.use("mydatabase", "mynamespace")
+        ...     people = await Person.insert(db, [
+        ...         Person(name="Alice"),
+        ...         Person(name="Bob")
+        ...     ])
+        >>>
+        >>> await engine.close()
+
+    See Also:
+        - create_engine_context(): For automatic lifecycle management
+        - Engine.connect(): Get a connection from the pool
+        - Engine.execute(): Execute a query with automatic retry
+    """
+    return Engine(url, auth_payload, pool_size, connect_timeout)
+
+
+@contextlib.asynccontextmanager
+async def create_engine_context(
+    url: str,
+    auth_payload: dict,
+    pool_size: int = 4,
+    connect_timeout: float = 5.0,
+) -> AsyncIterator[Engine]:
+    """
+    Create a connection pool engine with automatic lifecycle management.
+
+    This context manager creates an engine, starts it, yields it for use,
+    and automatically closes it when the context exits. This is the recommended
+    way to use the engine as it ensures proper cleanup.
+
+    Args:
+        url: SurrealDB connection URL (e.g., "ws://localhost:8000/rpc")
+        auth_payload: Dictionary with authentication credentials
+            Example: {"username": "root", "password": "root"}
+        pool_size: Number of connections to maintain in the pool (default: 4)
+        connect_timeout: Timeout for connection attempts in seconds (default: 5.0)
+
+    Yields:
+        Engine: A started engine instance
+
+    Example:
+        >>> async with create_engine_context(
+        ...     "ws://localhost:8000/rpc",
+        ...     {"username": "root", "password": "root"},
+        ...     pool_size=5
+        ... ) as engine:
+        ...     async with engine.connect() as db:
+        ...         await db.use("mydatabase", "mynamespace")
+        ...         people = await Person.insert(db, [
+        ...             Person(name="Alice"),
+        ...             Person(name="Bob")
+        ...         ])
+        ...     # Engine is automatically closed here
+
+    See Also:
+        - create_engine(): For manual lifecycle management
+        - Engine.connect(): Get a connection from the pool
+    """
+    engine = Engine(url, auth_payload, pool_size, connect_timeout)
+    await engine.start()
+    try:
+        yield engine
+    finally:
+        await engine.close()