gpframe 0.0.1__tar.gz

gpframe-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 minoru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gpframe-0.0.1/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: gpframe
+Version: 0.0.1
+Summary: A general-purpose framework for routine execution with concurrency and event handling.
+Author: minoru_jp
+License: MIT License
+        
+        Copyright (c) 2025 minoru
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/minoru-jp/gpframe
+Project-URL: Source, https://github.com/minoru-jp/gpframe
+Project-URL: Issues, https://github.com/minoru-jp/gpframe/issues
+Keywords: general-purpose,framework,concurrency,async,subprocess,event,lifecycle,context,outcome,exception-handling,wrapper,skeleton,task,workflow,execution,state-management
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# gpframe
+
+A general-purpose framework for managing routine execution with concurrency, event handling, and lifecycle control.
+
+Note: This project is in an early stage. It currently provides implementation only, with no tests yet.
+
+[![PyPI version](https://img.shields.io/pypi/v/gpframe.svg)](https://pypi.org/project/gpframe/)
+

gpframe-0.0.1/README.md

@@ -0,0 +1,8 @@
+# gpframe
+
+A general-purpose framework for managing routine execution with concurrency, event handling, and lifecycle control.
+
+Note: This project is in an early stage. It currently provides implementation only, with no tests yet.
+
+[![PyPI version](https://img.shields.io/pypi/v/gpframe.svg)](https://pypi.org/project/gpframe/)
+

gpframe-0.0.1/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=70", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gpframe"
+version = "0.0.1"
+description = "A general-purpose framework for routine execution with concurrency and event handling."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+    { name = "minoru_jp" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+keywords = [
+    "general-purpose",
+    "framework",
+    "concurrency",
+    "async",
+    "subprocess",
+    "event",
+    "lifecycle",
+    "context",
+    "outcome",
+    "exception-handling",
+    "wrapper",
+    "skeleton",
+    "task",
+    "workflow",
+    "execution",
+    "state-management"
+]
+
+[project.urls]
+Homepage = "https://github.com/minoru-jp/gpframe"
+Source = "https://github.com/minoru-jp/gpframe"
+Issues = "https://github.com/minoru-jp/gpframe/issues"
+
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["gpframe*"]

gpframe-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gpframe-0.0.1/src/gpframe/__init__.py

@@ -0,0 +1,57 @@
+"""
+Unified routine execution framework with frames, events, and contexts.
+
+gpframe wraps user-defined routines with a *frame* that provides lifecycle
+management, event handling, re-execution, and shared state. The routine itself
+can remain a simple function or async function, while the frame coordinates
+control flow and consistency.
+
+Key features:
+    - Works generically, from simple processes to event-driven extensions
+      and parallel execution control
+    - Supports both synchronous and asynchronous routines
+    - Synchronous routines can optionally be executed in subprocesses
+      (asynchronous ones are excluded)
+
+Execution flow:
+    - on_start → routine execution → on_end → redo check (continue or finish)
+    - on_cancel is called when canceled
+    - on_close is always called upon termination, followed by the terminated callback
+
+Data and error handling:
+    - Results, errors, and message exchange are consolidated into an ``Outcome``
+    - Exceptions from routines, frames, and event handlers are distinguished,
+      and which to re-raise is controlled by ``Raises``
+    - Shared data (environment, requests, event messages) is managed with
+      synchronized maps to ensure consistency across contexts
+    - Contexts (``ControllerContext``, ``EventContext``, ``RoutineContext``)
+      provide safe and structured access during execution
+
+Main components:
+    - **Frame** — entry point that wraps and manages routines
+    - **ControllerContext / EventContext / RoutineContext** — execution contexts
+    - **Outcome** — holds results, errors, requests, and messages
+    - **Raises** — selects which exception types to re-raise
+    - **Error types** — ``FrameError``, ``TerminatedError``, ``NotTerminatedError``, etc.
+
+gpframe provides unified control features without burdening the routine itself.
+"""
+from .api.gpframe import Frame
+
+from .api.gpframe import FrameError, FrameType, TerminatedError, NotTerminatedError
+from .api.error import Raises
+
+from .api.contexts import Controller
+from .api.contexts import EventContext
+from .api.contexts import RoutineContext
+
+from .api.outcome import Outcome
+
+from .api.result import NO_VALUE
+
+
+__all__ = ("Frame", "FrameType",
+           "FrameError", "TerminatedError", "NotTerminatedError", "Raises",
+           "Controller", "EventContext", "RoutineContext", "Outcome",
+           "NO_VALUE")
+

gpframe-0.0.1/src/gpframe/api/contexts.py

@@ -0,0 +1,220 @@
+"""
+contexts.py
+
+Defines abstract context interfaces for controllers, event handlers,
+and routines. These contexts provide structured access to logging,
+shared state, and communication channels, making it clear which
+elements are read-only and which are writable.
+
+Design notes:
+    - All contexts separate read-only and writable elements.
+    - Logging is always available.
+    - Shared state and message access are structured to prevent
+      unintended interference.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from logging import Logger
+
+    from ..impl.result import RoutineResult
+    from ..impl.syncm import SynchronizedMapReader, SynchronizedMapUpdater
+
+
+class Controller(ABC):
+    """Controller for running routine.
+
+    Provides:
+        - Read-only access to environment and inbound messages
+        - Writable request channel
+        - Routine result access
+        - Lifecycle control (stop / is_running)
+
+    Notes:
+        - `environment`, `event_msg`, `routine_msg`, `routine_result` are read-only
+        - `request` is the only writable channel
+        - `stop()` is idempotent
+    """
+    __slots__ = ()
+    @property
+    @abstractmethod
+    def frame_name(self) -> str:
+        ...
+    @property
+    @abstractmethod
+    def logger(self) -> Logger:
+        ...
+    @property
+    @abstractmethod
+    def routine_in_subprocess(self) -> bool:
+        ...
+    @property
+    @abstractmethod
+    def environment(self) -> SynchronizedMapReader:
+        ...
+    @property
+    @abstractmethod
+    def request(self) -> SynchronizedMapUpdater:
+        """Writable channel to send requests to the routine.
+
+        This is a best-effort communication mechanism:
+            - The routine may use these requests as hints or instructions.
+            - There is no guarantee that any given request will be executed
+            or even recognized.
+            - Actual behavior depends on the routine's implementation.
+
+        Use this as a way to suggest actions, not as a strict control channel.
+        """
+    @property
+    @abstractmethod
+    def event_msg(self) -> SynchronizedMapReader:
+        ...
+    @property
+    @abstractmethod
+    def routine_msg(self) -> SynchronizedMapReader:
+        ...
+    @property
+    @abstractmethod
+    def routine_result(self) -> RoutineResult:
+        """Result container for the routine.
+
+        Notes:
+            - The `RoutineResult.value` field is initialized to `NO_VALUE`.
+            - This remains `NO_VALUE` if the routine has not yet executed,
+            or if it finished without producing a result.
+            - Compare against `NO_VALUE` to detect these cases.
+        """
+    @abstractmethod
+    def stop(self, *, kill: bool = False) -> None:
+        """Request the routine to stop.
+
+        Behavior depends on how the routine is executed:
+            - Async routine: calls `cancel()`. If `kill=True`, the flag is ignored.
+            - Subprocess routine: calls `terminate()`. If `kill=True`, calls `kill()` instead.
+            - Synchronous in-process routine: not supported → raises TypeError.
+
+        Args:
+            kill: If True and the routine is a subprocess, use a hard kill instead
+                of graceful termination. Ignored for async routines.
+
+        Raises:
+            TypeError: If the routine is a synchronous in-process function.
+        """
+    @property
+    @abstractmethod
+    def routine_is_running(self) -> bool:
+        """Whether the routine appears to be running.
+
+        Notes:
+            - This value is an approximate indicator only.
+            - It may not reflect the exact, real-time execution state.
+            - Use it as a guideline rather than a strict guarantee.
+        """
+
+
+
+class EventContext(ABC):
+    """Context used inside event handlers.
+
+    Provides:
+        - Read-only access to environment, request, routine messages, and results
+        - Writable event message channel
+
+    Notes:
+        - `request` is read-only here (no sending)
+        - `event_msg` is the only writable channel
+    """
+    __slots__ = ()
+    @property
+    @abstractmethod
+    def frame_name(self) -> str:
+        ...
+    @property
+    @abstractmethod
+    def logger(self) -> Logger:
+        ...
+    @property
+    @abstractmethod
+    def routine_in_subprocess(self) -> bool:
+        ...
+    @property
+    @abstractmethod
+    def environment(self) -> SynchronizedMapReader:
+        ...
+    @property
+    @abstractmethod
+    def request(self) -> SynchronizedMapReader:
+        ...
+    @property
+    @abstractmethod
+    def event_msg(self) -> SynchronizedMapUpdater:
+        ...
+    @property
+    @abstractmethod
+    def routine_msg(self) -> SynchronizedMapReader:
+        ...
+    @property
+    @abstractmethod
+    def routine_result(self) -> RoutineResult:
+        """Result container for the routine.
+
+        Notes:
+            - The `RoutineResult.value` field is initialized to `NO_VALUE`.
+            - This remains `NO_VALUE` if the routine has not yet executed,
+            or if it finished without producing a result.
+            - Compare against `NO_VALUE` to detect these cases.
+        """
+
+
+class RoutineContext(ABC):
+    """Context for routines executed by the system.
+
+    Provides:
+        - Read-only access to environment, request, and event messages
+        - Writable routine message channel
+        - Logger name and subprocess execution flag
+
+    Notes:
+        - When `executes_as_subprocess` is True, data must be serializable
+        - `routine_msg` is the only writable channel
+    """
+    __slots__ = ()
+    @property
+    @abstractmethod
+    def frame_name(self) -> str:
+        ...
+    @property
+    @abstractmethod
+    def logger_name(self) -> str:
+        """Name of the logger channel associated with this routine.
+
+        Unlike other contexts, a `Logger` instance is not provided directly.
+        Instead, use this name to obtain a logger when needed.
+
+        Reason:
+            - Supports routines that may run in a separate subprocess,
+            where direct logger objects cannot be shared safely.
+        """
+    @property
+    @abstractmethod
+    def routine_in_subprocess(self) -> bool:
+        ...
+    @property
+    @abstractmethod
+    def environment(self) -> SynchronizedMapReader:
+        ...
+    @property
+    @abstractmethod
+    def request(self) -> SynchronizedMapUpdater:
+        ...
+    @property
+    @abstractmethod
+    def event_msg(self) -> SynchronizedMapReader:
+        ...
+    @property
+    @abstractmethod
+    def routine_msg(self) -> SynchronizedMapReader:
+        ...

gpframe-0.0.1/src/gpframe/api/error.py

@@ -0,0 +1,52 @@
+"""
+Exception handling policy for gpframe.
+
+Defines the ``Raises`` enumeration, an ``IntFlag`` used to
+specify which categories of exceptions should be re-raised.
+
+Notes:
+    - Members can be combined with bitwise operations.
+    - ``Raises.ALL`` is equivalent to combining all flags.
+"""
+
+from enum import IntFlag, auto
+
+class Raises(IntFlag):
+    """
+    Enumeration of flags that control which exceptions are re-raised.
+
+    Members:
+        SUPPRESS
+            Suppress all exceptions.
+        ROUTINE
+            Re-raise exceptions raised in routines.
+        FRAME
+            Re-raise exceptions raised during frame control.
+        HANDLER
+            Re-raise exceptions raised in handlers.
+        ALL
+            Equivalent to combining ROUTINE, FRAME, and HANDLER.
+    """
+    SUPPRESS = 0
+    ROUTINE = auto()
+    FRAME = auto()
+    HANDLER = auto()
+    ALL = ROUTINE | FRAME | HANDLER
+
+    def matches(self, r: Exception | None, f: Exception | None, h: Exception | None) -> bool:
+        """
+        Check whether any of the given exceptions should be re-raised.
+
+        Args:
+            r: Exception from a routine, or None if none occurred.
+            f: Exception from frame control, or None if none occurred.
+            h: Exception from a handler, or None if none occurred.
+
+        Returns:
+            True if at least one exception matches this Raises setting,
+            otherwise False.
+        """
+        result = r is not None and self & Raises.ROUTINE
+        result |= f is not None and self & Raises.FRAME
+        result |= h is not None and self & Raises.HANDLER
+        return bool(result)