planar 0.5.0__py3-none-any.whl

planar/test_utils.py

@@ -0,0 +1,105 @@
+import asyncio
+import time
+from datetime import UTC, datetime
+
+import pytest
+
+from planar.utils import asyncify, utc_now
+
+
+async def test_asyncify_converts_sync_to_async():
+    """Test that asyncify correctly converts a synchronous function to an asynchronous one."""
+
+    def sync_function(x, y):
+        return x + y
+
+    async_function = asyncify(sync_function)
+
+    # Check that the function is now a coroutine function
+    assert asyncio.iscoroutinefunction(async_function)
+    assert not asyncio.iscoroutinefunction(sync_function)
+
+    # Check that it can be awaited
+    result = await async_function(5, 3)
+    assert result == 8
+
+
+async def test_asyncify_with_args_and_kwargs():
+    """Test that asyncify correctly passes positional and keyword arguments."""
+
+    def complex_function(a, b, c=0, d=0):
+        return a + b + c + d
+
+    async_function = asyncify(complex_function)
+
+    # Test with positional args only
+    result1 = await async_function(1, 2)
+    assert result1 == 3
+
+    # Test with positional and keyword args
+    result2 = await async_function(1, 2, c=3, d=4)
+    assert result2 == 10
+
+
+async def test_asyncify_preserves_exceptions():
+    """Test that asyncify preserves exceptions raised by the wrapped function."""
+
+    def failing_function():
+        raise ValueError("Expected error")
+
+    async_function = asyncify(failing_function)
+
+    with pytest.raises(ValueError, match="Expected error"):
+        await async_function()
+
+
+async def test_asyncify_non_blocking():
+    """Test that asyncify runs the function in a way that doesn't block the event loop."""
+    # This counter will be incremented by a task running concurrently with our slow function
+    counter = 0
+
+    @asyncify
+    def slow_function():
+        time.sleep(0.5)  # This would block the event loop if not run in executor
+        return counter
+
+    # This task will increment the counter while the slow function is running
+    async def increment_counter():
+        nonlocal counter
+        await asyncio.sleep(0.1)  # Short sleep to allow the slow function to start
+        for _ in range(10):
+            counter += 1
+            await asyncio.sleep(0.01)  # Short sleep to yield control
+
+    # Create increment task
+    task = asyncio.create_task(increment_counter())
+
+    # Run the async function
+    assert counter == 0
+    result = await slow_function()
+    # If the event loop was blocked, the counter would be 0
+    assert counter == 10
+    assert result == 10
+
+    await task
+
+
+def test_raises_when_applied_to_async_function():
+    """Test that asyncify raises an error when applied to an async function."""
+
+    async def async_function():
+        pass
+
+    with pytest.raises(ValueError, match="Function is already async"):
+        asyncify(async_function)
+
+
+def test_utc_now_returns_naive_utc():
+    """utc_now should return a naive datetime captured within two timestamps."""
+
+    before = datetime.now(UTC).replace(tzinfo=None)
+    result = utc_now()
+    after = datetime.now(UTC).replace(tzinfo=None)
+
+    assert result.tzinfo is None
+    assert before <= result <= after

planar/testing/memory_storage.py

@@ -0,0 +1,78 @@
+import io
+import uuid
+from typing import AsyncGenerator, Dict, Tuple
+
+from planar.files.storage.base import Storage
+from planar.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class MemoryStorage(Storage):
+    """Stores files and mime types entirely in memory."""
+
+    def __init__(self):
+        """Initializes MemoryStorage."""
+        self._blobs: Dict[str, bytes] = {}
+        self._mime_types: Dict[str, str] = {}
+
+    async def put(
+        self, stream: AsyncGenerator[bytes, None], mime_type: str | None = None
+    ) -> str:
+        """
+        Stores a stream and its mime type in memory dictionaries.
+
+        The storage reference returned is a unique UUID string.
+        """
+        ref = str(uuid.uuid4())
+        buffer = io.BytesIO()
+        try:
+            async for chunk in stream:
+                buffer.write(chunk)
+            self._blobs[ref] = buffer.getvalue()
+            if mime_type:
+                self._mime_types[ref] = mime_type
+            logger.debug("stored ref in memory", ref=ref)
+            return ref
+        except Exception as e:
+            logger.exception("error during memory put operation", ref=ref)
+            # Clean up if storage failed mid-way (though less likely in memory)
+            self._blobs.pop(ref, None)
+            self._mime_types.pop(ref, None)
+            raise IOError(
+                f"Failed to store file or mime type in memory for ref {ref}"
+            ) from e
+
+    async def get(self, ref: str) -> Tuple[AsyncGenerator[bytes, None], str | None]:
+        """
+        Retrieves a stream and its mime type from memory.
+        """
+        if ref not in self._blobs:
+            raise FileNotFoundError(f"Storage reference not found in memory: {ref}")
+
+        blob_data = self._blobs[ref]
+        mime_type = self._mime_types.get(ref)
+
+        async def _stream():
+            # Yield the entire blob data as a single chunk for simplicity
+            # Could be chunked if needed, but for memory storage, this is fine.
+            yield blob_data
+
+        logger.debug("retrieved ref from memory", ref=ref)
+        return _stream(), mime_type
+
+    async def delete(self, ref: str) -> None:
+        """
+        Deletes the blob data and mime type from memory. Idempotent.
+        """
+        blob_deleted = self._blobs.pop(ref, None) is not None
+        mime_deleted = self._mime_types.pop(ref, None) is not None
+        if blob_deleted or mime_deleted:
+            logger.debug("deleted ref from memory", ref=ref)
+        else:
+            logger.debug("attempted to delete non-existent ref from memory", ref=ref)
+        # No FileNotFoundError raised if ref doesn't exist, deletion is idempotent.
+
+    async def external_url(self, ref: str) -> str | None:
+        """Memory storage does not provide external URLs."""
+        return None

planar/testing/planar_test_client.py

@@ -0,0 +1,54 @@
+import asyncio
+from contextlib import asynccontextmanager
+
+from httpx import ASGITransport, AsyncClient
+
+from planar import PlanarApp
+from planar.db import DatabaseManager
+from planar.session import session_var
+from planar.testing.workflow_observer import WorkflowObserver
+
+
+class PlanarTestClient(AsyncClient):
+    def __init__(self, app: PlanarApp):
+        self.app = app
+        super().__init__(
+            base_url="http://testserver", transport=ASGITransport(app=app.fastapi)
+        )
+
+
+@asynccontextmanager
+async def planar_test_client(
+    app: PlanarApp, connection_string: str, observer: WorkflowObserver
+):
+    # Override the db manager with a new one that uses test database
+    app.db_manager = DatabaseManager(connection_string)
+    app.db_manager.connect()
+    app.on_workflow_notification = observer.on_workflow_notification
+
+    async with PlanarTestClient(app) as client:
+        # run the app lifespan
+        async with app._lifespan(app.fastapi):
+            # Create a session and set it in the contextvar
+            async with app.db_manager.get_session() as session:
+                token = session_var.set(session)
+                try:
+                    yield client
+                finally:
+                    session_var.reset(token)
+    await wait_all_event_loop_tasks()
+
+
+async def wait_all_event_loop_tasks():
+    # Workaround prevent the event loop from exiting before aiosqlite
+    # has a chance to cleanup its background threads:
+    # Keep yielding back to the event loop until the only task left is this one
+    current_task = asyncio.current_task()
+    while True:
+        other_tasks = [task for task in asyncio.all_tasks() if task is not current_task]
+        if not other_tasks:
+            break
+        try:
+            await asyncio.gather(*other_tasks)
+        except asyncio.CancelledError:
+            pass

planar/testing/synchronizable_tracer.py

@@ -0,0 +1,153 @@
+import asyncio
+from dataclasses import dataclass
+from typing import Any
+
+from planar.workflows.tracing import LoggingTracer, Tracer
+
+
+@dataclass(kw_only=True, frozen=True)
+class TraceSpec:
+    module_name: str | None = None
+    function_name: str | None = None
+    message: str | None = None
+    kwargs: dict[str, Any] | None = None
+
+
+def matches(
+    spec: TraceSpec,
+    module_name: str,
+    function_name: str,
+    message: str,
+    kwargs: dict[str, Any],
+) -> bool:
+    if spec.module_name is not None and module_name != spec.module_name:
+        return False
+    if spec.function_name is not None and function_name != spec.function_name:
+        return False
+    if spec.message is not None and message != spec.message:
+        return False
+    if spec.kwargs is not None:
+        for key, value in spec.kwargs.items():
+            if key in kwargs and kwargs[key] != value:
+                return False
+    return True
+
+
+class JoinTask:
+    def __init__(self, task: asyncio.Task, signal: asyncio.Future):
+        self.__task = task
+        self.__signal = signal
+
+    def start(self):
+        if not self.__signal.done():
+            self.__signal.set_result(None)
+        return self.__task
+
+
+class TraceController:
+    def __init__(self, watcher: asyncio.Future, spec: TraceSpec):
+        self.spec = spec
+        self.watcher = watcher
+        self.join_task: JoinTask | None = None
+        self.__resume_trace = None
+        self.__resumed = False
+        self.__auto_resume = False
+
+    async def wait(
+        self, auto_resume: bool = True, timeout: float = 10, raise_timeout: bool = True
+    ):
+        try:
+            self.__resume_trace = await asyncio.wait_for(self.watcher, timeout=timeout)
+            if auto_resume or self.__auto_resume:
+                self.resume()
+        except asyncio.TimeoutError:
+            formatted_trace = Tracer.format(
+                module_name=self.spec.module_name or "(any)",
+                function_name=self.spec.function_name or "(any)",
+                task_name="(any)",
+                pid=0,
+                message=self.spec.message or "(any)",
+                kwargs=self.spec.kwargs or {},
+            )
+            if raise_timeout:
+                raise TimeoutError(f"timeout waiting for trace: {formatted_trace}")
+
+    def resume(self):
+        if self.__resumed:
+            raise ValueError("resume called multiple times")
+        if self.__resume_trace is None:
+            self.__auto_resume = True
+        else:
+            self.__resume_trace.set_result(None)
+            self.__resumed = True
+
+
+class SynchronizableTracer(LoggingTracer):
+    def __init__(self):
+        self.timeout = 5
+        self.races_detected = 0
+        self.__controllers: list[TraceController] = []
+
+    def instrument(self, spec: TraceSpec):
+        future = asyncio.Future()
+        controller = TraceController(future, spec)
+        self.__controllers.append(controller)
+        return controller
+
+    def join(self, *trace_specs: TraceSpec):
+        async def join(signal: asyncio.Future, controllers: list[TraceController]):
+            await signal
+            tasks = [
+                asyncio.create_task(
+                    controller.wait(
+                        auto_resume=False, timeout=self.timeout * 2, raise_timeout=False
+                    )
+                )
+                for controller in controllers
+            ]
+            done, _ = await asyncio.wait(tasks, timeout=self.timeout)
+            for controller in controllers:
+                controller.resume()
+            if len(done) == len(controllers):
+                self.races_detected += 1
+
+        controllers = [self.instrument(spec) for spec in trace_specs]
+        signal = asyncio.Future()
+        task = JoinTask(asyncio.create_task(join(signal, controllers)), signal)
+        for controller in controllers:
+            controller.join_task = task
+
+    async def trace(
+        self,
+        module_name: str,
+        function_name: str,
+        message: str,
+        task_name: str,
+        pid: int,
+        kwargs: dict[str, Any],
+    ):
+        i = 0
+        futures = []
+        while i < len(self.__controllers):
+            controller = self.__controllers[i]
+            if not matches(
+                controller.spec, module_name, function_name, message, kwargs
+            ):
+                i += 1
+                continue
+            self.__controllers.pop(i)
+            future = asyncio.Future()
+            try:
+                controller.watcher.set_result(future)
+            except asyncio.InvalidStateError:
+                pass
+            if controller.join_task:
+                future = controller.join_task.start()
+            futures.append(future)
+
+        if futures:
+            await asyncio.wait(futures, return_when=asyncio.ALL_COMPLETED)
+
+        return await super().trace(
+            module_name, function_name, message, task_name, pid, kwargs
+        )

planar/testing/test_memory_storage.py

@@ -0,0 +1,143 @@
+import asyncio
+import uuid
+
+import pytest
+
+from planar.testing.memory_storage import MemoryStorage
+
+
+@pytest.fixture
+async def storage() -> MemoryStorage:
+    """Provides an instance of MemoryStorage."""
+    return MemoryStorage()
+
+
+async def test_put_get_bytes(storage: MemoryStorage):
+    """Test storing and retrieving raw bytes."""
+    test_data = b"some binary data \x00\xff for memory"
+    mime_type = "application/octet-stream"
+
+    ref = await storage.put_bytes(test_data, mime_type=mime_type)
+    assert isinstance(ref, str)
+    try:
+        uuid.UUID(ref)  # Check if ref is a valid UUID string
+    except ValueError:
+        pytest.fail(f"Returned ref '{ref}' is not a valid UUID string")
+
+    retrieved_data, retrieved_mime = await storage.get_bytes(ref)
+
+    assert retrieved_data == test_data
+    assert retrieved_mime == mime_type
+
+    # Check internal state (optional)
+    assert ref in storage._blobs
+    assert ref in storage._mime_types
+    assert storage._blobs[ref] == test_data
+    assert storage._mime_types[ref] == mime_type
+
+
+async def test_put_get_string(storage: MemoryStorage):
+    """Test storing and retrieving a string."""
+    test_string = "Hello, memory! This is a test string with Unicode: éàçü."
+    mime_type = "text/plain"
+    encoding = "utf-16"
+
+    # Store with explicit encoding and mime type
+    ref = await storage.put_string(test_string, encoding=encoding, mime_type=mime_type)
+    expected_mime_type = f"{mime_type}; charset={encoding}"
+
+    retrieved_string, retrieved_mime = await storage.get_string(ref, encoding=encoding)
+
+    assert retrieved_string == test_string
+    assert retrieved_mime == expected_mime_type
+
+    # Test default encoding (utf-8)
+    ref_utf8 = await storage.put_string(test_string, mime_type="text/html")
+    expected_mime_utf8 = "text/html; charset=utf-8"
+    retrieved_string_utf8, retrieved_mime_utf8 = await storage.get_string(ref_utf8)
+    assert retrieved_string_utf8 == test_string
+    assert retrieved_mime_utf8 == expected_mime_utf8
+
+
+async def test_put_get_stream(storage: MemoryStorage):
+    """Test storing data from an async generator stream."""
+    test_chunks = [b"mem_chunk1 ", b"mem_chunk2 ", b"mem_chunk3"]
+    full_data = b"".join(test_chunks)
+    mime_type = "image/gif"
+
+    async def _test_stream():
+        for chunk in test_chunks:
+            yield chunk
+            await asyncio.sleep(0.01)  # Simulate async work
+
+    ref = await storage.put(_test_stream(), mime_type=mime_type)
+
+    stream, retrieved_mime = await storage.get(ref)
+    retrieved_data = b""
+    async for chunk in stream:
+        retrieved_data += chunk
+
+    assert retrieved_data == full_data
+    assert retrieved_mime == mime_type
+
+
+async def test_put_no_mime_type(storage: MemoryStorage):
+    """Test storing data without providing a mime type."""
+    test_data = b"memory data without mime"
+
+    ref = await storage.put_bytes(test_data)
+    retrieved_data, retrieved_mime = await storage.get_bytes(ref)
+
+    assert retrieved_data == test_data
+    assert retrieved_mime is None
+
+    # Check internal state
+    assert ref in storage._blobs
+    assert ref not in storage._mime_types
+
+
+async def test_delete(storage: MemoryStorage):
+    """Test deleting stored data."""
+    ref = await storage.put_bytes(b"to be deleted from memory", mime_type="text/plain")
+
+    # Verify data exists before delete (optional)
+    assert ref in storage._blobs
+    assert ref in storage._mime_types
+
+    await storage.delete(ref)
+
+    # Verify data is gone after delete
+    assert ref not in storage._blobs
+    assert ref not in storage._mime_types
+
+    # Try getting deleted ref
+    with pytest.raises(FileNotFoundError):
+        await storage.get(ref)
+
+
+async def test_get_non_existent(storage: MemoryStorage):
+    """Test getting a reference that does not exist."""
+    non_existent_ref = str(uuid.uuid4())
+    with pytest.raises(FileNotFoundError):
+        await storage.get(non_existent_ref)
+
+
+async def test_delete_non_existent(storage: MemoryStorage):
+    """Test deleting a reference that does not exist (should not raise error)."""
+    non_existent_ref = str(uuid.uuid4())
+    initial_blob_count = len(storage._blobs)
+    initial_mime_count = len(storage._mime_types)
+    try:
+        await storage.delete(non_existent_ref)
+        # Ensure no data was actually deleted
+        assert len(storage._blobs) == initial_blob_count
+        assert len(storage._mime_types) == initial_mime_count
+    except Exception as e:
+        pytest.fail(f"Deleting non-existent ref raised an exception: {e}")
+
+
+async def test_external_url(storage: MemoryStorage):
+    """Test that external_url returns None for memory storage."""
+    ref = await storage.put_bytes(b"some data for url test")
+    url = await storage.external_url(ref)
+    assert url is None

planar/testing/workflow_observer.py

@@ -0,0 +1,73 @@
+from asyncio import Future, wait_for
+from collections import defaultdict
+from uuid import UUID
+
+from planar.workflows import Workflow, WorkflowNotification
+from planar.workflows.models import WorkflowStep
+
+
+class WorkflowObserver:
+    def __init__(self):
+        # Scope notification queues and waiters by workflow_id
+
+        self.notification_queues: defaultdict[UUID, list[WorkflowNotification]] = (
+            defaultdict(list)
+        )
+        self.waiters: dict[UUID, Future[None]] = {}
+        self.timeout = 10
+
+    def _get_workflow_id_from_notification(
+        self, notification: WorkflowNotification
+    ) -> UUID:
+        """Extract workflow_id from notification data"""
+        if isinstance(notification.data, Workflow):
+            return notification.data.id
+        else:
+            return notification.data.workflow_id
+
+    def on_workflow_notification(self, notification: WorkflowNotification):
+        workflow_id = UUID(str(self._get_workflow_id_from_notification(notification)))
+
+        # Add to the appropriate workflow's queue
+        self.notification_queues[workflow_id].append(notification)
+
+        # Wake up any waiter for this workflow
+        waiter = self.waiters.get(workflow_id)
+        if waiter is not None:
+            waiter.set_result(None)
+            del self.waiters[workflow_id]
+
+    async def wait(
+        self, kind: str, workflow_id: UUID, step_id: int | None = None
+    ) -> WorkflowNotification:
+        workflow_id = UUID(str(workflow_id))  # ensure workflow_id is an UUID instance
+
+        while True:
+            matched = None
+            queue = self.notification_queues[workflow_id]
+            for i, notification in enumerate(queue):
+                if notification.kind == kind:
+                    # Only check step_id filter for non-Workflow notifications
+                    if isinstance(notification.data, WorkflowStep):
+                        if step_id is not None and notification.data.step_id != step_id:
+                            continue
+                    matched = i
+                    break
+            if matched is not None:
+                notification = queue[matched]
+                # Prune all previous notifications from this workflow's queue
+                self.notification_queues[workflow_id] = queue[matched + 1 :]
+                return notification
+            # notification hasn't arrived yet, lets create a future and sleep until
+            # on_workflow_notification is called
+            assert workflow_id not in self.waiters, (
+                f"waiter for workflow {workflow_id} should not be present"
+            )
+            waiter = Future()
+            self.waiters[workflow_id] = waiter
+            try:
+                await wait_for(waiter, timeout=self.timeout)
+            except TimeoutError:
+                assert False, (
+                    f"Timeout waiting for notification {kind} with workflow_id={workflow_id} and step_id={step_id}"
+                )

planar/utils.py

@@ -0,0 +1,70 @@
+import asyncio
+import functools
+import inspect
+import random
+from datetime import UTC, datetime
+from typing import Any, Callable, Coroutine, ParamSpec, TypeVar
+
+from inflection import pluralize, underscore
+
+
+def snake_case_to_camel_case(snake_case: str) -> str:
+    return "".join(word.capitalize() for word in snake_case.split("_"))
+
+
+def create_path_prefix(model_name: str) -> str:
+    """
+    Create a URL path prefix from a model name.
+
+    Example: 'Supplier' -> 'suppliers'
+    """
+    return f"{pluralize(underscore(model_name))}"
+
+
+P = ParamSpec("P")
+T = TypeVar("T")
+U = TypeVar("U")
+R = TypeVar("R")
+
+
+def asyncify(
+    func: Callable[P, R],
+) -> Callable[P, Coroutine[Any, Any, R]]:
+    if inspect.iscoroutinefunction(func):
+        raise ValueError("Function is already async")
+
+    @functools.wraps(func)
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        return await asyncio.to_thread(func, *args, **kwargs)
+
+    return wrapper
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC).replace(tzinfo=None)
+
+
+def exponential_backoff_with_jitter(
+    attempt: int, base_delay: int = 1, max_delay: int = 60, jitter_factor=0.1
+):
+    """
+    Calculate exponential backoff delay with random jitter.
+
+    Args:
+        attempt: Current attempt number (starts at 0)
+        base_delay: Initial delay in seconds (default: 1)
+        max_delay: Maximum delay in seconds (default: 60)
+        jitter_factor: Fraction of delay to use for jitter (default: 0.1)
+
+    Returns:
+        Delay in seconds with jitter applied. Minimum possible delay is 1
+        second.
+    """
+    # Calculate exponential backoff: base_delay * 2^attempt
+    delay = min(base_delay * (2**attempt), max_delay)
+
+    # Add random jitter: ±jitter_factor * delay
+    jitter = delay * jitter_factor
+    actual_delay = delay + random.uniform(-jitter, jitter)
+
+    return max(1, actual_delay)  # Ensure at least 1 second