mycorrhizal 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

mycorrhizal/spores/models.py

@@ -174,6 +174,28 @@ class EventAttr:
     name: Optional[str] = None
 
 
+@dataclass(frozen=True)
+class SporesAttr:
+    """
+    Metadata annotation for object attributes in OCEL object logging.
+
+    Used with typing.Annotated to mark fields that should be logged when an object is logged:
+
+        class Order(BaseModel):
+            id: str
+            status: Annotated[str, SporesAttr]  # Logged
+            total: Annotated[float, SporesAttr]  # Logged
+            items: list[dict]  # Not marked - not logged
+
+    When using @spore.log_event(relationships={...}), fields marked with SporesAttr
+    are automatically logged. If attributes list is provided, it overrides SporesAttr.
+
+    Attributes:
+        name: Optional custom name for the attribute (defaults to field name)
+    """
+    name: Optional[str] = None
+
+
 # ============================================================================
 # Attribute Value Conversion
 # ============================================================================

mycorrhizal/spores/transport/__init__.py

@@ -5,6 +5,13 @@ Spores Transports
 Transports for sending OCEL LogRecords to various destinations.
 """
 
-from .base import Transport
+from .base import SyncTransport, AsyncTransport, Transport
+from .file import SyncFileTransport, AsyncFileTransport
 
-__all__ = ['Transport']
+__all__ = [
+    'SyncTransport',
+    'AsyncTransport',
+    'Transport',  # Backward compatibility alias for AsyncTransport
+    'SyncFileTransport',
+    'AsyncFileTransport',
+]

mycorrhizal/spores/transport/base.py

@@ -2,26 +2,28 @@
 """
 Spores Transport Interface
 
-Abstract base class for transporting encoded LogRecords.
+Protocols for transporting encoded LogRecords.
+Separate sync and async protocols for clarity.
 """
 
 from __future__ import annotations
 
-from abc import ABC, abstractmethod
-from typing import Protocol, Callable, Optional
+from typing import Protocol
 
 
-class Transport(Protocol):
+class SyncTransport(Protocol):
     """
-    Protocol for transports that send encoded LogRecords.
+    Protocol for synchronous transports (blocking I/O).
 
-    Transports handle the actual delivery of log records to consumers
-    (e.g., HTTP POST, files, message queues, etc.).
+    Sync transports use blocking send() - they write data immediately
+    and block until complete. Use these with get_spore_sync().
+
+    Examples: file writes, blocking HTTP requests, etc.
     """
 
-    async def send(self, data: bytes, content_type: str) -> None:
+    def send(self, data: bytes, content_type: str) -> None:
         """
-        Send encoded data to the transport destination.
+        Send encoded data to the transport destination (blocking).
 
         Args:
             data: The encoded log record data
@@ -29,18 +31,35 @@ class Transport(Protocol):
         """
         ...
 
-    def is_async(self) -> bool:
-        """
-        Return True if this transport is async (non-blocking).
+    def close(self) -> None:
+        """Close the transport and release resources."""
+        ...
+
+
+class AsyncTransport(Protocol):
+    """
+    Protocol for asynchronous transports (async I/O).
+
+    Async transports use non-blocking async send() - they await completion.
+    Use these with get_spore_async().
 
-        Async transports don't block the caller when sending data.
-        They typically use background threads, queues, or async I/O.
+    Examples: async file writes, async HTTP requests, message queues, etc.
+    """
 
-        Returns:
-            True if transport is async, False if synchronous
+    async def send(self, data: bytes, content_type: str) -> None:
+        """
+        Send encoded data to the transport destination (async).
+
+        Args:
+            data: The encoded log record data
+            content_type: MIME content type (e.g., "application/json")
         """
         ...
 
-    def close(self) -> None:
+    async def close(self) -> None:
         """Close the transport and release resources."""
         ...
+
+
+# Backward compatibility alias
+Transport = AsyncTransport

mycorrhizal/spores/transport/file.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+Spores File Transports
+
+File-based transports for OCEL log records.
+Includes both synchronous (blocking I/O) and asynchronous (async I/O) implementations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from pathlib import Path
+from typing import Optional
+
+
+class SyncFileTransport:
+    """
+    Synchronous file transport using blocking I/O.
+
+    Writes log records to a file in JSONL format (one JSON object per line).
+    Thread-safe with a lock for concurrent writes.
+    """
+
+    def __init__(self, filepath: str | Path):
+        """
+        Initialize the file transport.
+
+        Args:
+            filepath: Path to the log file. Will be created if it doesn't exist.
+        """
+        self.filepath = Path(filepath)
+        self.filepath.parent.mkdir(parents=True, exist_ok=True)
+        self._file = open(self.filepath, 'a', encoding='utf-8')
+        self._lock = threading.Lock()
+
+    def send(self, data: bytes, content_type: str) -> None:
+        """
+        Write data to file (blocking call).
+
+        Args:
+            data: Encoded log record data
+            content_type: MIME content type (e.g., "application/json")
+        """
+        with self._lock:
+            self._file.write(data.decode('utf-8') + '\n')
+            self._file.flush()
+
+    def close(self) -> None:
+        """Close the file handle."""
+        with self._lock:
+            if self._file and not self._file.closed:
+                self._file.close()
+                self._file = None
+
+    def __enter__(self):
+        """Context manager support."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager support."""
+        self.close()
+
+
+class AsyncFileTransport:
+    """
+    Asynchronous file transport using async I/O.
+
+    Writes log records to a file in JSONL format (one JSON object per line).
+    Uses asyncio.to_thread() for non-blocking async file I/O.
+
+    This is the async version of SyncFileTransport - use it with get_spore_async().
+    """
+
+    def __init__(self, filepath: str | Path):
+        """
+        Initialize the async file transport.
+
+        Args:
+            filepath: Path to the log file. Will be created if it doesn't exist.
+        """
+        self.filepath = Path(filepath)
+        self.filepath.parent.mkdir(parents=True, exist_ok=True)
+        # Open file in append mode, will be managed by asyncio.to_thread
+        self._file = open(self.filepath, 'a', encoding='utf-8')
+        self._lock = asyncio.Lock()
+
+    async def send(self, data: bytes, content_type: str) -> None:
+        """
+        Write data to file asynchronously.
+
+        Uses asyncio.to_thread() to run blocking I/O in a thread pool,
+        avoiding the need for external dependencies like aiofiles.
+
+        Args:
+            data: Encoded log record data
+            content_type: MIME content type (e.g., "application/json")
+        """
+        async with self._lock:
+            # Run blocking file I/O in thread pool
+            await asyncio.to_thread(self._write_sync, data)
+
+    def _write_sync(self, data: bytes) -> None:
+        """
+        Synchronous write helper - runs in thread pool.
+
+        Args:
+            data: Encoded log record data
+        """
+        self._file.write(data.decode('utf-8') + '\n')
+        self._file.flush()
+
+    async def close(self) -> None:
+        """Close the file handle asynchronously."""
+        async with self._lock:
+            if self._file and not self._file.closed:
+                await asyncio.to_thread(self._file.close)
+                self._file = None
+
+    async def __aenter__(self):
+        """Async context manager support."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager support."""
+        await self.close()

{mycorrhizal-0.1.0.dist-info → mycorrhizal-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mycorrhizal
-Version: 0.1.0
+Version: 0.1.2
 Summary: Utilities and DSLs for modelling and implementing safe, performant, structured systems
 Author-email: Jeff Ciesielski <jeffciesielski@gmail.com>
 Requires-Python: >=3.10

{mycorrhizal-0.1.0.dist-info → mycorrhizal-0.1.2.dist-info}/RECORD

@@ -1,4 +1,5 @@
 mycorrhizal/__init__.py,sha256=ajz1GSNU9xYVrFEDSz6Xwg7amWQ_yvW75tQa1ZvRIWc,3
+mycorrhizal/_version.py,sha256=08TK2sYzQF2Wqm6gpxZEgWYYF9ZjbInObIzS2R2yxiE,18
 mycorrhizal/common/__init__.py,sha256=vAL2NZFFVcoGoPlIREKRG0mrgx1prVTGTlWBopJ76Sw,1450
 mycorrhizal/common/interface_builder.py,sha256=rBJzduqZ6EjD9MNGO669BcjkM9mYvsnMG0F1kd1wWaQ,6895
 mycorrhizal/common/interfaces.py,sha256=fWw6bm2ejFmKUnl2pSTiSEwTP0Id8Kowg827_Mqir-s,12261
@@ -11,18 +12,18 @@ mycorrhizal/enoki/util.py,sha256=oJ9vmHrbUdX99Rkh7bBeUHFzM5sS3yrtXOTQDA1524I,843
 mycorrhizal/hypha/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mycorrhizal/hypha/util.py,sha256=tpvjWXTdGhtVUycQElcQg4usOy-tSEqwE9KEni8R30s,906
 mycorrhizal/hypha/core/__init__.py,sha256=o6BE3fhRKjVfyIWwtNTO64kPt0udlZGyXr-ZuN_ZzF8,2518
-mycorrhizal/hypha/core/builder.py,sha256=3oXG235bllLql8v2IiIa9K7ska_e4cHc8tvGGWwWZzA,15210
+mycorrhizal/hypha/core/builder.py,sha256=GyjDWG3ZTO_0OIhJNrty4-SaJ9RGsNIzHyOQBCNKDfc,16912
 mycorrhizal/hypha/core/runtime.py,sha256=K7EDxPTYu9lyHoolBGrrOTws7f1xmbnU2SBVVLnoD3g,34848
-mycorrhizal/hypha/core/specs.py,sha256=-MH4-ast3uxIWns3VpYV9vC_vqfjLCbvj61nbAOImn8,7882
+mycorrhizal/hypha/core/specs.py,sha256=uWvW9x7-bSoSENIUJkYMIkJ3KxsgE9mB9PyRLPrOEjk,8429
 mycorrhizal/rhizomorph/README.md,sha256=g-G8d00VgMOPriggsNveH7HqLhnJ9HlvoIzrwmUEy_M,8134
 mycorrhizal/rhizomorph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mycorrhizal/rhizomorph/core.py,sha256=BmgTbnzF2fzYhjQK4iAuO85LHCsN9-dKGok6U8bDv-g,58668
+mycorrhizal/rhizomorph/core.py,sha256=FrV7S6coulaeqhYfHmNE9x6tmlGFBYcqO04zOdpwNNs,60816
 mycorrhizal/rhizomorph/util.py,sha256=dUgKAWX5RNtzFK01mGkz10tJyeTMCqyyfnZ8Mi97LkY,1280
-mycorrhizal/spores/__init__.py,sha256=y-KPzgUMVXJKjClgQXmsykdWNe2g_U42pWRvdmmCqbg,2836
+mycorrhizal/spores/__init__.py,sha256=VI0y_723Fo1la-nJGJweBWc8PKvpd_VmmT9EBtVrEog,4763
 mycorrhizal/spores/cache.py,sha256=0FuWHKudgyC7vlrlcJ_kmRKr7OAJuC2gxRURReMlqF4,6119
-mycorrhizal/spores/core.py,sha256=mfo1dQtDeyyYedIiaQ16YPhcBpIe-4wgzWXiMCjIj1I,12310
+mycorrhizal/spores/core.py,sha256=KGv3X6w6pz5RiUD__7MMrYUXvDwGUfWFU_eCvDcQSUg,38624
 mycorrhizal/spores/extraction.py,sha256=YnUGABcVgZVSDCXyOQewWG62NAkdievJrXPIA_eJkxg,14918
-mycorrhizal/spores/models.py,sha256=P5hlBaKmK6pCyLxBwGgPB4U9ef29_9fEoNEbYXJLV6g,7964
+mycorrhizal/spores/models.py,sha256=Gm_7jwPNgWhYCK5XDIUiN0DfDp4kJEkSbqxpwPdlsJE,8712
 mycorrhizal/spores/dsl/__init__.py,sha256=bkxHTkaPrDWUlU1pjYlGJOM-772M5_k7R4aZ8HaxMNM,1153
 mycorrhizal/spores/dsl/enoki.py,sha256=eVYNBp3ESZ7lK91vE8H5JWkXX14pOtf6cdAWSLiqAsE,15506
 mycorrhizal/spores/dsl/hypha.py,sha256=vcJimWbZT2MmGhj8Lbn3izF1PO9HVJe1YQi5P3EiZ6o,11959
@@ -30,8 +31,9 @@ mycorrhizal/spores/dsl/rhizomorph.py,sha256=ChG2fRQD9DR90dLKLYSQR72asC-7eLccvBwZ
 mycorrhizal/spores/encoder/__init__.py,sha256=hpp1W4xwQUG1N1zdrea0coBPtMf-WYSE77Q780TinP8,204
 mycorrhizal/spores/encoder/base.py,sha256=xFKk-f5_W_HNrOgNXyquUwhcrcz28LmeT5Y5enDVrwU,870
 mycorrhizal/spores/encoder/json.py,sha256=dyQSTXfG0VQPSNt9ed8VEgMwxFUPnLtV6u_bSRuEnNY,4747
-mycorrhizal/spores/transport/__init__.py,sha256=-QYmAwqaTbhrgEXr16qSYWx2f6J22d0SklPlm_Y8RWo,168
-mycorrhizal/spores/transport/base.py,sha256=lJ2sLlXd-ZDeMn3ujSoYTneUB3Zwlz0mpWh5yxKK6Lw,1201
-mycorrhizal-0.1.0.dist-info/METADATA,sha256=fKifHtnUMVeIKv13_kukZ6rtotKusA3m20VSXRr9qK0,4895
-mycorrhizal-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mycorrhizal-0.1.0.dist-info/RECORD,,
+mycorrhizal/spores/transport/__init__.py,sha256=Tw6glCXsPK2pzsLPbb9vKOCvvT9vh-ql-xUaulKBAw0,407
+mycorrhizal/spores/transport/base.py,sha256=OsyWx1J8Ig7Y7idUoI9oS-LkONwQAxAP47jL_5OVRjA,1668
+mycorrhizal/spores/transport/file.py,sha256=xcMPxAGiv5q-GfcNKsF_3a-2-yxlDkhHusZli1Fsqa0,3833
+mycorrhizal-0.1.2.dist-info/METADATA,sha256=c_xR3AeCwrC8jhbnimBcfu_7jmFItM8UdgAR2Wi8RYQ,4895
+mycorrhizal-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mycorrhizal-0.1.2.dist-info/RECORD,,