pumpkin-api-py 0.1.0__py3-none-any.whl

componentize_py_async_support/futures.py

@@ -0,0 +1,149 @@
+import componentize_py_runtime
+import componentize_py_async_support
+import weakref
+
+from typing import TypeVar, Generic, cast, Self, Any, Callable
+from types import TracebackType
+from componentize_py_async_support import _ReturnCode
+
+T = TypeVar('T')
+
+class FutureReader(Generic[T]):
+    """Represents the readable end of a Component Model `future`.
+
+    Each object of this type should be closed promptly using either context
+    management (e.g. a `with` statement) or by calling `read` in order to notify
+    the owner of the writable end of the `future` that the readable end has been
+    closed.  If the object becomes unreachable without being closed, it will be
+    closed via finalization.
+
+    """
+    def __init__(self, type_: int, handle: int):
+        """Constructor for internal use by generated code.
+
+        Application code should not call this directly.  Instead,
+        `componentize-py` will generate a constructor function for each unique
+        `future` type used by the target world.  Each such function will return
+        a (`FutureReader`, `FutureWriter`) pair and use this constructor behind
+        the scenes.
+
+        """
+        self.type_ = type_
+        self.handle: int | None = handle
+        self.finalizer = weakref.finalize(self, componentize_py_runtime.future_drop_readable, type_, handle)
+
+    async def read(self) -> T:
+        """Asynchronously read the value sent to this `future`.
+
+        The awaitable returned by this function will resolve when a value has
+        been delivered to the `future`.
+
+        Calling this function consumes the target object; any attempt to call
+        `read` more than once will raise an `AssertionError`.
+
+        """
+        
+        self.finalizer.detach()
+        handle = self.handle
+        self.handle = None
+        if handle is not None:
+            result = await componentize_py_async_support.await_result(
+                componentize_py_runtime.future_read(self.type_, handle)
+            )
+            componentize_py_runtime.future_drop_readable(self.type_, handle)
+            return cast(T, result)
+        else:
+            raise AssertionError
+
+    def __enter__(self) -> Self:
+        return self
+        
+    def __exit__(self,
+                 exc_type: type[BaseException] | None,
+                 exc_value: BaseException | None,
+                 traceback: TracebackType | None) -> bool | None:
+        if self.handle is not None:
+            self.finalizer.detach()
+            handle = self.handle
+            self.handle = None
+            componentize_py_runtime.future_drop_readable(self.type_, handle)
+
+        return None
+
+async def _write(type_: int, handle: int, value: Any) -> None:
+    await componentize_py_async_support.await_result(
+        componentize_py_runtime.future_write(type_, handle, value)
+    )
+    componentize_py_runtime.future_drop_writable(type_, handle)    
+
+def _write_default(type_: int, handle: int, default: Callable[[], Any]) -> None:
+    componentize_py_async_support.spawn(_write(type_, handle, default()))
+            
+class FutureWriter(Generic[T]):
+    """Represents the writable end of a Component Model `future`.
+
+    Each object of this type should be closed promptly using either context
+    management (e.g. a `with` statement) or by calling `write` in order to send
+    a value to the readable end of the `future.  If the object becomes
+    unreachable without being closed, it will be closed via finalization after
+    sending the default value which was specified during construction.
+
+    """
+    def __init__(self, type_: int, handle: int, default: Callable[[], T]):
+        """Constructor for internal use by generated code.
+
+        Application code should not call this directly.  Instead,
+        `componentize-py` will generate a constructor function for each unique
+        `future` type used by the target world.  Each such function will return
+        a (`FutureReader`, `FutureWriter`) pair and use this constructor behind
+        the scenes.
+
+        """
+        self.type_ = type_
+        self.handle: int | None = handle
+        self.default = default
+        self.finalizer = weakref.finalize(self, _write_default, type_, handle, default)
+
+    async def write(self, value: T) -> bool:
+        """Asynchronously write a value to the `future`.
+
+        The awaitable returned by this function will resolve once either the
+        value has been delivered to the readable end of the `future` or the
+        readable end has been closed.
+
+        Calling this function consumes the target object; any attempt to call
+        `write` more than once will raise an `AssertionError`.
+
+        """
+        self.finalizer.detach()
+        handle = self.handle
+        self.handle = None
+        if handle is not None:
+            code, _ = await componentize_py_async_support.await_result(
+                componentize_py_runtime.future_write(self.type_, handle, value)
+            )
+            componentize_py_runtime.future_drop_writable(self.type_, handle)
+            match code:
+                case _ReturnCode.COMPLETED:
+                    return True
+                case _ReturnCode.DROPPED:
+                    return False
+                case _ReturnCode.CANCELLED:
+                    # todo
+                    raise NotImplementedError
+                case _:
+                    raise AssertionError
+        else:
+            raise AssertionError
+
+    def __enter__(self) -> Self:
+        return self
+        
+    def __exit__(self,
+                 exc_type: type[BaseException] | None,
+                 exc_value: BaseException | None,
+                 traceback: TracebackType | None) -> bool | None:
+        if self.handle is not None:
+            componentize_py_async_support.spawn(self.write(self.default()))
+
+        return None

componentize_py_async_support/streams.py

@@ -0,0 +1,345 @@
+import componentize_py_runtime
+import componentize_py_async_support
+import weakref
+
+from typing import TypeVar, Generic, Self, cast
+from types import TracebackType
+from componentize_py_async_support import _ReturnCode
+
+class ByteStreamReader:
+    """Represents the readable end of a Component Model `stream<u8>`.
+
+    Each object of this type should be closed promptly using context management
+    (e.g. a `with` statement) in order to notify the owner of the writable end
+    of the `stream` that the readable end has been closed.  If the object
+    becomes unreachable without being closed, it will be closed via
+    finalization.
+
+    """
+    def __init__(self, type_: int, handle: int):
+        """Constructor for internal use by generated code.
+
+        Application code should not call this directly.  Instead,
+        `componentize-py` will generate `byte_stream` function if the target
+        world uses the `stream<u8>` type.  That function will return a
+        (`ByteStreamReader`, `ByteStreamWriter`) pair and use this constructor
+        behind the scenes.
+
+        """
+        self.writer_dropped = False
+        self.type_ = type_
+        self.handle: int | None = handle
+        self.finalizer = weakref.finalize(self, componentize_py_runtime.stream_drop_readable, type_, handle)
+
+    async def read(self, max_count: int) -> bytes:
+        """Asynchronously read up to `max_count` bytes sent to this `stream`.
+
+        The awaitable returned by this function will resolve when either at
+        least one byte has been delivered to the `stream` or the writable end
+        has been closed (in which case the `writer_dropped` field will be set to
+        `True`).
+
+        Only one `read` operation is allowed at a time for a given object.  Any
+        attempt to start a second read while the first is still in progress will
+        raise an `AssertionError`.
+
+        """
+        if self.writer_dropped:
+            return bytes()
+        
+        handle = self.handle
+        self.handle = None
+        code, values = await self._read(max_count, handle)
+        self.handle = handle
+
+        if code == _ReturnCode.DROPPED:
+            self.writer_dropped = True
+        
+        return values
+        
+    async def _read(self, max_count: int, handle: int | None) -> tuple[int, bytes]:
+        if handle is not None:
+            return cast(tuple[int, bytes], await componentize_py_async_support.await_result(
+                componentize_py_runtime.stream_read(self.type_, handle, max_count)
+            ))
+        else:
+            raise AssertionError
+
+    def __enter__(self) -> Self:
+        return self
+        
+    def __exit__(self,
+                 exc_type: type[BaseException] | None,
+                 exc_value: BaseException | None,
+                 traceback: TracebackType | None) -> bool | None:
+        self.finalizer.detach()
+        handle = self.handle
+        self.handle = None
+        if handle is not None:
+            componentize_py_runtime.stream_drop_readable(self.type_, handle)
+        return None
+
+class ByteStreamWriter:
+    """Represents the writable end of a Component Model `stream<u8>`.
+
+    Each object of this type should be closed promptly using context management
+    (e.g. a `with` statement) in order to notify the owner of the readable end
+    of the `stream` that the writable end has been closed.  If the object
+    becomes unreachable without being closed, it will be closed via
+    finalization.
+
+    """
+    def __init__(self, type_: int, handle: int):
+        """Constructor for internal use by generated code.
+
+        Application code should not call this directly.  Instead,
+        `componentize-py` will generate `byte_stream` function if the target
+        world uses the `stream<u8>` type.  That function will return a
+        (`ByteStreamReader`, `ByteStreamWriter`) pair and use this constructor
+        behind the scenes.
+
+        """
+        self.reader_dropped = False
+        self.type_ = type_
+        self.handle: int | None = handle
+        self.finalizer = weakref.finalize(self, componentize_py_runtime.stream_drop_writable, type_, handle)
+
+    async def write(self, source: bytes) -> int:
+        """Asynchronously write (some of) the specified bytes to the `stream`.
+
+        The awaitable returned by this function will resolve when either at
+        least one byte has been delivered to the `stream` or the readable end
+        has been closed (in which case the `reader_dropped` field will be set to
+        `True`).
+
+        The return value is the total number of bytes delivered (which may be
+        less than `len(source)`).  See also `write_all`, which attempts to write
+        the entire buffer before returning.
+
+        Only one `write` operation is allowed at a time for a given object.  Any
+        attempt to start a second write while the first is still in progress
+        will raise an `AssertionError`.
+
+        """
+        if self.reader_dropped:
+            return 0
+        
+        handle = self.handle
+        self.handle = None
+        code, count = await self._write(source, handle)
+        self.handle = handle
+
+        if code == _ReturnCode.DROPPED:
+            self.reader_dropped = True
+        
+        return count
+
+    async def _write(self, source: bytes, handle: int | None) -> tuple[int, int]:
+        if handle is not None:
+            return await componentize_py_async_support.await_result(
+                componentize_py_runtime.stream_write(self.type_, handle, source)
+            )
+        else:
+            raise AssertionError
+
+    async def write_all(self, source: bytes) -> int:
+        """Asynchronously write the specified bytes to the `stream`.
+
+        This calls `write` in a loop until either the entire buffer has been
+        delivered or the readable end of the `stream` has been closed.  The
+        return value is the total number of bytes delivered (which may be less
+        than `len(source)`).
+
+        """
+        total = 0
+        
+        while len(source) > 0 and not self.reader_dropped:
+            count = await self.write(source)
+            source = source[count:]
+            total += count
+            
+        return total
+
+    def __enter__(self) -> Self:
+        return self
+        
+    def __exit__(self,
+                 exc_type: type[BaseException] | None,
+                 exc_value: BaseException | None,
+                 traceback: TracebackType | None) -> bool | None:
+        self.finalizer.detach()
+        handle = self.handle
+        self.handle = None
+        if handle is not None:
+            componentize_py_runtime.stream_drop_writable(self.type_, handle)
+        return None
+
+T = TypeVar('T')
+
+class StreamReader(Generic[T]):
+    """Represents the readable end of a Component Model `stream`.
+
+    Each object of this type should be closed promptly using context management
+    (e.g. a `with` statement) in order to notify the owner of the writable end
+    of the `stream` that the readable end has been closed.  If the object
+    becomes unreachable without being closed, it will be closed via
+    finalization.
+
+    """
+    def __init__(self, type_: int, handle: int):
+        """Constructor for internal use by generated code.
+
+        Application code should not call this directly.  Instead,
+        `componentize-py` will generate a constructor function for each unique
+        `stream` type used by the target world.  Each such function will return
+        a (`StreamReader`, `StreamWriter`) pair and use this constructor behind
+        the scenes.
+
+        """
+        self.writer_dropped = False
+        self.type_ = type_
+        self.handle: int | None = handle
+        self.finalizer = weakref.finalize(self, componentize_py_runtime.stream_drop_readable, type_, handle)
+
+    async def read(self, max_count: int) -> list[T]:
+        """Asynchronously read up to `max_count` items sent to this `stream`.
+
+        The awaitable returned by this function will resolve when either at
+        least one item has been delivered to the `stream` or the writable end
+        has been closed (in which case the `writer_dropped` field will be set to
+        `True`).
+
+        Only one `read` operation is allowed at a time for a given object.  Any
+        attempt to start a second read while the first is still in progress will
+        raise an `AssertionError`.
+
+        """
+        if self.writer_dropped:
+            return []
+        
+        handle = self.handle
+        self.handle = None
+        code, values = await self._read(max_count, handle)
+        self.handle = handle
+
+        if code == _ReturnCode.DROPPED:
+            self.writer_dropped = True
+        
+        return values
+        
+    async def _read(self, max_count: int, handle: int | None) -> tuple[int, list[T]]:
+        if handle is not None:
+            return cast(tuple[int, list[T]], await componentize_py_async_support.await_result(
+                componentize_py_runtime.stream_read(self.type_, handle, max_count)
+            ))
+        else:
+            raise AssertionError        
+
+    def __enter__(self) -> Self:
+        return self
+        
+    def __exit__(self,
+                 exc_type: type[BaseException] | None,
+                 exc_value: BaseException | None,
+                 traceback: TracebackType | None) -> bool | None:
+        self.finalizer.detach()
+        handle = self.handle
+        self.handle = None
+        if handle is not None:
+            componentize_py_runtime.stream_drop_readable(self.type_, handle)
+        return None
+
+class StreamWriter(Generic[T]):
+    """Represents the writable end of a Component Model `stream`.
+
+    Each object of this type should be closed promptly using context management
+    (e.g. a `with` statement) in order to notify the owner of the readable end
+    of the `stream` that the writable end has been closed.  If the object
+    becomes unreachable without being closed, it will be closed via
+    finalization.
+
+    """
+    def __init__(self, type_: int, handle: int):
+        """Constructor for internal use by generated code.
+
+        Application code should not call this directly.  Instead,
+        `componentize-py` will generate a constructor function for each unique
+        `stream` type used by the target world.  Each such function will return
+        a (`StreamReader`, `StreamWriter`) pair and use this constructor behind
+        the scenes.
+
+        """
+        self.reader_dropped = False
+        self.type_ = type_
+        self.handle: int | None = handle
+        self.finalizer = weakref.finalize(self, componentize_py_runtime.stream_drop_writable, type_, handle)
+
+    async def write(self, source: list[T]) -> int:
+        """Asynchronously write (some of) the specified itmes to the `stream`.
+
+        The awaitable returned by this function will resolve when either at
+        least one item has been delivered to the `stream` or the readable end
+        has been closed (in which case the `reader_dropped` field will be set to
+        `True`).
+
+        The return value is the total number of items delivered (which may be
+        less than `len(source)`).  See also `write_all`, which attempts to write
+        the entire buffer before returning.
+
+        Only one `write` operation is allowed at a time for a given object.  Any
+        attempt to start a second write while the first is still in progress will
+        raise an `AssertionError`.
+
+        """
+        if self.reader_dropped:
+            return 0
+        
+        handle = self.handle
+        self.handle = None
+        code, count = await self._write(source, handle)
+        self.handle = handle
+
+        if code == _ReturnCode.DROPPED:
+            self.reader_dropped = True
+        
+        return count
+
+    async def _write(self, source: list[T], handle: int | None) -> tuple[int, int]:
+        if handle is not None:
+            return await componentize_py_async_support.await_result(
+                componentize_py_runtime.stream_write(self.type_, handle, source)
+            )
+        else:
+            raise AssertionError        
+
+    async def write_all(self, source: list[T]) -> int:
+        """Asynchronously write the specified items to the `stream`.
+
+        This calls `write` in a loop until either the entire buffer has been
+        delivered or the readable end of the `stream` has been closed.  The
+        return value is the total number of items delivered (which may be less
+        than `len(source)`).
+
+        """
+        total = 0
+        
+        while len(source) > 0 and not self.reader_dropped:
+            count = await self.write(source)
+            source = source[count:]
+            total += count
+            
+        return total
+
+    def __enter__(self) -> Self:
+        return self
+        
+    def __exit__(self,
+                 exc_type: type[BaseException] | None,
+                 exc_value: BaseException | None,
+                 traceback: TracebackType | None) -> bool | None:
+        self.finalizer.detach()
+        handle = self.handle
+        self.handle = None
+        if handle is not None:
+            componentize_py_runtime.stream_drop_writable(self.type_, handle)
+        return None

componentize_py_runtime.pyi

@@ -0,0 +1,40 @@
+"""Internal functions used by generated code to interact with the
+`componentize-py` runtime.
+
+These are not meant to be called directly by application code.
+
+"""
+from typing import Any
+from componentize_py_types import Result
+
+def call_task_return(index: int, borrows: int, result: Any) -> None: ...
+
+def waitable_set_drop(set: int) -> None: ...
+
+def context_set(value: Any) -> None: ...
+
+def context_get() -> Any: ...
+
+def waitable_join(waitable: int, set: int) -> None: ...
+
+def subtask_drop(task: int) -> None: ...
+
+def waitable_set_new() -> int: ...
+
+def promise_get_result(event: int, promise: int) -> Any: ...
+
+def future_read(ty: int, future: int) -> Result[Any, tuple[int, int]]: ...
+
+def future_write(ty: int, future: int, value: Any) -> Result[tuple[int, int], tuple[int, int]]: ...
+
+def future_drop_readable(ty: int, future: int) -> None: ...
+
+def future_drop_writable(ty: int, future: int) -> None: ...
+
+def stream_read(ty: int, stream: int, max_count: int) -> Result[tuple[int, bytes | list[Any]], tuple[int, int]]: ...
+
+def stream_write(ty: int, stream: int, values: bytes | list[Any]) -> Result[tuple[int, int], tuple[int, int]]: ...
+
+def stream_drop_readable(ty: int, stream: int) -> None: ...
+
+def stream_drop_writable(ty: int, stream: int) -> None: ...

componentize_py_types.py

@@ -0,0 +1,32 @@
+from typing import TypeVar, Generic, Union
+from dataclasses import dataclass
+
+S = TypeVar('S')
+@dataclass
+class Some(Generic[S]):
+    """Represents the "present" (i.e. non-absent) case of an optional value.
+
+    This is used to disambiguate values of a nested ComponentModel `option` type
+    (e.g. `option<option<T>>` or similar).  Non-nested `option` values are
+    represented using `typing.Optional`, i.e. nullable types.
+
+    """
+    value: S
+
+T = TypeVar('T')
+@dataclass
+class Ok(Generic[T]):
+    """Represents the success case of a Component Model `result` value."""
+    value: T
+
+E = TypeVar('E')
+@dataclass(frozen=True)
+class Err(Generic[E], Exception):
+    """Represents the failure case of a Component Model `result` value."""
+    value: E
+
+Result = Union[Ok[T], Err[E]]
+"""Represents a Component Model `result` value, i.e. a variant type representing
+either success payload or failure payload.
+
+"""