pieui 0.1.0__py3-none-any.whl

pie/__init__.py

@@ -0,0 +1,27 @@
+__version__ = "0.1.0"
+
+__author__ = "George K."
+
+
+from .fastweb import Web
+from .async_page import AsyncPage
+from .card import Card, InputCard
+from .components.hidden import HiddenCard
+from .components.union import UnionCard
+from .components.ajax_group import AjaxGroupCard
+from .components.html_embed import HTMLEmbedCard
+from .components.one_of import OneOfCard
+from .components.io_log import IOLogCard
+
+
+__all__ = ["__version__",
+           "Web",
+           "AsyncPage",
+           "InputCard",
+           "Card",
+           "HiddenCard",
+           "UnionCard",
+           "AjaxGroupCard",
+           "HTMLEmbedCard",
+           "OneOfCard",
+           "IOLogCard"]

pie/__main__.py

@@ -0,0 +1,99 @@
+"""PieDemo CLI
+
+Command-line interface for the PieDemo framework.
+"""
+
+import argparse
+import sys
+from typing import Optional
+
+from .code import handle_card_add, handle_build, handle_create, handle_web, handle_web_verify
+
+
+CARD_TYPES = {"simple", "complex", "container", "complex-container"}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pie",
+        description="Pie - Framework for building interactive web applications",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands", required=True)
+
+    # piedemo web module:app [verify|build]
+    web_parser = subparsers.add_parser("web", help="Run or lint a web application")
+    web_parser.add_argument("web", help="Web in format module:attribute, e.g. some:app")
+    web_subparsers = web_parser.add_subparsers(dest="web_command")
+    web_subparsers.add_parser("verify", help="Verify the web application")
+    web_subparsers.add_parser("build", help="Build static JSON from a Web application")
+
+    card_parser = subparsers.add_parser("card", help="Manage card templates")
+    card_subparsers = card_parser.add_subparsers(dest="card_command", required=True)
+    card_add_parser = card_subparsers.add_parser("add", help="Create a card file from a template")
+    card_add_parser.add_argument("card_type", choices=sorted(CARD_TYPES))
+    card_add_parser.add_argument("card_name", metavar="NAME")
+    card_add_parser.add_argument("--io", action="store_true", dest="use_io")
+    card_add_parser.add_argument("--ajax", action="store_true", dest="use_ajax")
+
+    create_parser = subparsers.add_parser("create", help="Create a new Pie project")
+    create_parser.add_argument("project_name", metavar="NAME")
+
+    return parser
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    return build_parser().parse_args(argv)
+
+
+def main(
+    command: str,
+    web: Optional[str] = None,
+    web_command: Optional[str] = None,
+    card_command: Optional[str] = None,
+    card_type: Optional[str] = None,
+    card_name: Optional[str] = None,
+    project_name: Optional[str] = None,
+    use_io: bool = False,
+    use_ajax: bool = False,
+) -> int:
+    try:
+        if command == "web":
+            if web is None:
+                raise ValueError("Web path is required")
+            if web_command == "verify":
+                handle_web_verify(web)
+            elif web_command == "build":
+                handle_build(web)
+            else:
+                handle_web(web)
+            return 0
+
+        if command == "page":
+            return 0
+        if command == "card":
+            if card_command == "add":
+                handle_card_add(
+                    card_name=card_name,
+                    card_type=card_type,
+                    use_io=use_io,
+                    use_ajax=use_ajax,
+                )
+            return 0
+        if command == "create":
+            if project_name is None:
+                raise ValueError("Project name is required")
+            handle_create(project_name)
+            return 0
+        if command == "init":
+            return 0
+        if command == "login":
+            return 0
+        return 0
+    except ValueError as error:
+        print(error, file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(**vars(parse_args())))

pie/async_page.py

@@ -0,0 +1,381 @@
+import asyncio
+import inspect
+import json
+import sys
+import traceback
+from typing import Any, AsyncGenerator, Callable, Dict, List, Literal, Optional, Union, TypeAlias
+from fastapi.responses import StreamingResponse
+from pie.card import Card
+from pie.types import SocketIOEvent
+
+try:
+    from fastapi_socketio import SocketManager
+    SocketManagerType: TypeAlias = SocketManager
+except ImportError:
+    print(
+        "FastAPI socketio not installed. Emitting events is not available",
+        file=sys.stderr,
+    )
+    SocketManagerType: TypeAlias = Any
+
+try:
+    from faststream.redis.fastapi import RedisBroker
+    from redis.asyncio import StrictRedis
+
+    RedisBrokerType: TypeAlias = RedisBroker
+    StrictRedisType: TypeAlias = StrictRedis
+except ImportError:
+    print(
+        "FastStream & redis not installed. Cache and Background processing are not available",
+        file=sys.stderr,
+    )
+    RedisBrokerType: TypeAlias = Any
+    StrictRedisType: TypeAlias = Any
+
+
+class AsyncPage(object):
+    """
+    Base class for asynchronous pages.
+
+    Provides methods for:
+        - filling and parsing data
+        - generating events
+        - SocketIO or Centrifuge integration
+        - caching via Redis
+        - AJAX registration
+    """
+
+    def __init__(self, is_typed: bool = False) -> None:
+        super(AsyncPage, self).__init__()
+        """
+        Initialize AsyncPage with default attributes.
+        """
+        self.is_typed: bool = is_typed
+        self.global_data: Dict[str, Any] = {}
+        self.ajax_post: Dict[str, Callable[..., Any]] = {}
+        self.ajax_get: Dict[str, Callable[..., Any]] = {}
+        self.io: Optional[SocketManagerType] = None
+        self.broker: Optional[RedisBrokerType] = None
+        self.cache: Optional[StrictRedisType] = None
+
+    def get_possible_fields(self) -> Dict[str, Card]:
+        return {
+            name: value
+            for name, value in inspect.getmembers(self)
+            if not name.startswith("__") and isinstance(value, Card)
+        }
+
+    def get_io_cards(self) -> List[Card]:
+        """
+        Return all cards that support IO events (SocketIO or Centrifuge).
+
+        Raises:
+            NotImplementedError: If the page has no fields.
+
+        Returns:
+            List: IO-enabled cards.
+        """
+        if hasattr(self, "fields"):
+            return self._get_io_cards(self.fields)
+        raise NotImplementedError("In " + self.__class__.__name__)
+
+    @staticmethod
+    def _get_io_cards(fields: Card) -> List[Card]:
+        """
+        Helper to extract IO-enabled cards from a Card object.
+
+        Args:
+            fields: Card object.
+
+        Returns:
+            List: Cards supporting IO events.
+        """
+        return [
+            card
+            for card in fields.children()
+            if hasattr(card, "name")
+            and (
+                (hasattr(card, "use_socketio_support") and card.use_socketio_support)
+                or (
+                    hasattr(card, "use_centrifuge_support")
+                    and card.use_centrifuge_support
+                )
+            )
+        ]
+
+    async def get_content(self, **kwargs: Any):
+        """
+        Return filled content of the page.
+
+        Raises:
+            NotImplementedError: If the page has no fields.
+
+        Returns:
+            dict: Page content.
+        """
+        if hasattr(self, "fields"):
+            return self.fill(self.fields, {})
+        raise NotImplementedError()
+
+    async def process(self, **data: Any):
+        """
+        Process form submission.
+
+        Raises:
+            NotImplementedError
+        """
+        raise NotImplementedError()
+
+    @staticmethod
+    def fill(
+        fields: Card,
+        data: Dict[str, Any],
+        inplace: bool = False,
+        generate: bool = True,
+    ):
+        """
+        Fill a card or V1 fields with data.
+
+        Args:
+            fields: Card or legacy fields.
+            data: Dictionary with input values.
+            inplace: Modify fields in place.
+            generate: Generate content after filling.
+            hook: Optional function to run after filling fields.
+
+        Returns:
+            Generated content or modified fields.
+        """
+        return fields.fill(data, inplace=inplace, generate=generate)
+
+    @staticmethod
+    def parse(fields: Card,
+              data: Dict[str, Any],
+              strict: bool = True) -> Dict[str, Any]:
+        """
+        Parse input data into Card or legacy field structure.
+
+        Args:
+            fields: Card or legacy fields.
+            data: Input dictionary.
+            strict: Raise exceptions on invalid values.
+
+        Returns:
+            Parsed data dictionary.
+        """
+        return fields.parse_all(data)
+
+    @staticmethod
+    def redirect_url(to: Optional[str], **kwargs: Any) -> Optional[str]:
+        """
+        Build a redirect URL with optional query parameters.
+
+        Args:
+            to: Base URL.
+            kwargs: Query parameters.
+
+        Returns:
+            str: Full redirect URL.
+        """
+        if to is None:
+            return None
+        if len(kwargs) == 0 or all([v is None for v in kwargs.values()]):
+            return to
+        params = "&".join([f"{k}={v}" for k, v in kwargs.items() if v is not None])
+
+        if "?" in to:
+            if to.endswith("&"):
+                return f"{to}{params}"
+            else:
+                return f"{to}&{params}"
+        else:
+            return f"{to}?{params}"
+
+    async def emit(
+        self,
+        event: Union[List[SocketIOEvent], SocketIOEvent],
+        to: Optional[str] = None,
+    ) -> None:
+        """
+        Emit SocketIO event(s) to connected clients.
+
+        Args:
+            event: Single or list of events.
+            to: Target recipient or broadcast.
+        """
+        if self.io is None:
+            raise RuntimeError("SocketIO and Centrifuge not supported!")
+
+        if not isinstance(event, list):
+            events = [event]
+        else:
+            events = event
+
+        await asyncio.gather(*[self.io.emit(ev.name, ev.data, to=to)
+                               for ev in events])
+
+    async def reload(self, to: Optional[str] = None) -> None:
+        """
+        Trigger a page reload via SocketIO.
+
+        Args:
+            to: Target recipient or broadcast.
+        """
+        if self.io is None:
+            raise RuntimeError("SocketIO not supported!")
+        print("Reload: ")
+        await self.io.emit("piereload", {}, to=to)
+
+    def register_ajax(
+        self,
+        pathname: str,
+        ajax_fn: Callable[..., Any],
+        method: Literal["GET", "POST"] = "POST",
+    ) -> str:
+        """
+        Register an AJAX endpoint.
+
+        Args:
+            pathname: URL path.
+            ajax_fn: Handler function.
+            method: HTTP method ("POST" or "GET").
+
+        Returns:
+            str: Pathname.
+        """
+        if method == "POST":
+            self.ajax_post[pathname[1:]] = ajax_fn
+        elif method == "GET":
+            self.ajax_get[pathname[1:]] = ajax_fn
+        return pathname
+
+    @staticmethod
+    def create_ajax_event_streaming(
+        event_generator: AsyncGenerator[SocketIOEvent, None],
+    ) -> StreamingResponse:
+        """
+        Wrap async generator as a streaming response.
+
+        Args:
+            event_generator: Async generator of SocketIO events.
+
+        Returns:
+            StreamingResponse: Streaming events to the client.
+        """
+
+        async def wrapped_generator() -> AsyncGenerator[str, None]:
+            try:
+                async for event in event_generator:
+                    yield event.to_json() + "\n"
+            except asyncio.CancelledError:
+                print("Streaming cancelled by client", file=sys.stderr)
+                raise
+            except Exception:
+                traceback.print_exc(file=sys.stderr)
+
+        return StreamingResponse(wrapped_generator(), media_type="text/plain",
+                                 headers={
+                                     "Cache-Control": "no-cache",
+                                     "X-Accel-Buffering": "no",
+                                 })
+
+    def lock(self, name: str, timeout: int = 120) -> Any:
+        """
+        Create a Redis lock.
+
+        Args:
+            name: Lock name.
+            timeout: Lock timeout in seconds.
+
+        Returns:
+            Redis lock object.
+        """
+        if self.cache is None:
+            raise RuntimeError("Lock not supported!")
+        return self.cache.lock(f"lock:{name}", timeout=timeout)
+
+    async def page_lock(self, name: str, timeout: int = 120) -> Any:
+        """
+        Create a page-scoped Redis lock.
+
+        Args:
+            name: Lock name.
+            timeout: Lock timeout.
+
+        Returns:
+            Redis lock object.
+        """
+        return self.lock(f"{self.__class__.__name__}:{name}", timeout=timeout)
+
+    async def save_value(
+        self,
+        scope: str,
+        key: str,
+        value: Any,
+        encode: bool = False,
+    ) -> Any:
+        """
+        Save a string value to Redis.
+
+        Args:
+            scope: Key prefix.
+            key: Key name.
+            value: Value to save (must be str).
+            encode: JSON encode value.
+
+        Returns:
+            bool: Result of Redis set.
+        """
+        if not isinstance(value, str):
+            raise TypeError("Value must be a string")
+        if scope in ["lock"]:
+            raise RuntimeError("scope must not be `lock`")
+        if ":" in scope:
+            raise RuntimeError("scope must not contain ':')")
+        if encode:
+            value = json.dumps(value)
+        return await self.cache.set(f"{scope}:{key}", value)
+
+    async def load_value(
+        self,
+        scope: str,
+        key: str,
+        decode: bool = False,
+    ) -> Any:
+        """
+        Load a value from Redis.
+
+        Args:
+            scope: Key prefix.
+            key: Key name.
+            decode: JSON decode value.
+
+        Returns:
+            str or decoded object.
+        """
+        if scope in ["lock"]:
+            raise RuntimeError("scope must not be `lock`")
+        if ":" in scope:
+            raise RuntimeError("scope must not contain ':')")
+        value = await self.cache.get(f"{scope}:{key}")
+        if decode:
+            value = json.loads(value)
+        return value
+
+    def debug(self) -> None:
+        """
+        Run a development server for debugging the page.
+        """
+        from pie.fastweb import Web
+
+        web = Web(
+            {
+                "": self,
+            },
+            use_socketio_support=True,
+            enable_cors=True,
+            disable_serving=True,
+            serving_url="http://localhost:3000",
+            cors_origins=["http://localhost:8008", "http://localhost:3000"],
+        )
+        web.run(host="localhost", port=8008, debug=False)