modularizer-plat-browser 0.17.1__py3-none-any.whl

modularizer_plat_browser-0.17.1.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: modularizer-plat-browser
+Version: 0.17.1
+Summary: Browser-hosted Python runtime for plat
+License-Expression: Unlicense
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# plat_browser
+
+Browser-hosted Python runtime for plat.
+
+This package is intended for client-side Python execution environments while keeping the main `plat` package focused on normal server/client/CLI usage.
+
+## Example
+
+```python
+from plat_browser import Controller, POST, serve_server
+
+
+@Controller()
+class MathApi:
+    @POST()
+    def add(self, a: int, b: int, ctx):
+        return a + b
+
+
+serve_server("browser-python-math", [MathApi])
+```
+
+It also supports hidden browser package installation syntax:
+
+```python
+!pip install pandas
+```
+
+The browser host/runtime is responsible for package loading and transport bridging. User code should stay normal Python.
+
+Payload fields are passed into handlers as keyword arguments by default, so browser Python code can use normal Python signatures like `def add(self, a, b, ctx)`.
+
+Browser Python can also act as a client:
+
+```python
+from plat_browser import connect_server
+
+client = await connect_server("css://browser-python-math")
+await client.add(a=20, b=22)
+```
+
+Browser Python clients can also pass optional trust inputs:
+
+```python
+client = await connect_server(
+    "css://browser-python-math",
+    {
+        "identity": {
+            "known_hosts": {},
+            "authority_servers": [
+                {
+                    "base_url": "https://authority.example.com",
+                    "public_key_jwk": {...},
+                }
+            ],
+        }
+    },
+)
+```
+
+That same client helper can also connect to normal HTTP servers that expose OpenAPI:
+
+```python
+from plat_browser import connect_server
+
+client = await connect_server("https://api.example.com")
+await client.createOrder(itemId="sku_123", qty=2)
+```
+
+## css:// host identity
+
+The `css://` transport can keep a stable host identity too.
+
+- Browser-hosted servers can reuse a persisted public/private keypair
+- Clients can trust on first use and remember a host key for later
+- Clients can also verify a signed authority record for well-known server names
+
+Those identity helpers live in the TypeScript/browser host layer so browser Python user code can stay normal Python and never mention lower-level runtime details.
+
+## TypeScript host utilities
+
+Use the browser host utilities from the TypeScript package:
+
+```ts
+import { startClientSidePythonServerFromSource } from '@modularizer/plat/python-browser'
+```
+
+That host layer is responsible for:
+- loading the hidden browser Python runtime
+- handling `!pip install ...` and import-based package installation
+- serving the Python-defined methods over the same client-side-server transport utilities

modularizer_plat_browser-0.17.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+plat_browser/__init__.py,sha256=TkMVt7XSNyP8E-L2Dw2BIUEtlheyaNXV4ZfavBgAfOs,1002
+plat_browser/client.py,sha256=Mg2lXlKF79vceKM2R2SX4aGq4TZdI0Z2X6OvMxhM98U,4200
+plat_browser/decorators.py,sha256=GWrvPXKnseWLmIL-wA1yZMIsHjOFzr-hM6mPVHMSDgE,2826
+plat_browser/errors.py,sha256=WNeJBHYdIGI1QRmasiuxNoE5h77fZA6CefPDuC29BRA,787
+plat_browser/metadata.py,sha256=ahrkAY-IhUQpNyNN3iT_cWELA5bjazEfaokiZZRYxbU,472
+plat_browser/plugins.py,sha256=y09hxAsZd98B1vAXS2EuukBP0n9vAqNeXPDvNef0Gjo,16621
+plat_browser/server.py,sha256=ywUfaMELUMax5pxsJIWthCsf5IWuppugS8hOMt0F-G0,36708
+plat_browser/types.py,sha256=1CW1x0x_xtcggkW_StZisWV6d7nrXLuJigjBOh64sh8,1209
+modularizer_plat_browser-0.17.1.dist-info/METADATA,sha256=9-GkxQwe-_92WavsvTqDhpIMePeBvdhRi0MlVrpANX8,2786
+modularizer_plat_browser-0.17.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+modularizer_plat_browser-0.17.1.dist-info/RECORD,,

modularizer_plat_browser-0.17.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

plat_browser/__init__.py

@@ -0,0 +1,40 @@
+from .client import BrowserPLATClient, connect_client_side_server, connect_server, run_python_client_source
+from .decorators import Controller, DELETE, GET, PATCH, POST, PUT
+from .errors import HttpError, HttpResponse
+from .plugins import BucketConfig
+from .server import (
+    BrowserPackagePlan,
+    BrowserPLATServer,
+    BrowserServerDefinition,
+    create_browser_server,
+    create_server,
+    prepare_python_source,
+    serve_server,
+    serve_client_side_server,
+)
+from .types import RouteContext
+
+__all__ = [
+    "Controller",
+    "DELETE",
+    "GET",
+    "PATCH",
+    "POST",
+    "PUT",
+    "BrowserPLATClient",
+    "BrowserPackagePlan",
+    "BrowserPLATServer",
+    "BrowserServerDefinition",
+    "BucketConfig",
+    "HttpError",
+    "HttpResponse",
+    "RouteContext",
+    "connect_client_side_server",
+    "connect_server",
+    "create_browser_server",
+    "create_server",
+    "prepare_python_source",
+    "run_python_client_source",
+    "serve_server",
+    "serve_client_side_server",
+]

plat_browser/client.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import ast
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+
+BrowserClientConnectBridge = Callable[[str, Any], Awaitable[Any]]
+BrowserClientCallBridge = Callable[[int, str, Any], Awaitable[Any]]
+
+_CONNECT_BRIDGE: BrowserClientConnectBridge | None = None
+_CALL_BRIDGE: BrowserClientCallBridge | None = None
+
+
+class BrowserPLATClient:
+    def __init__(self, client_id: int, base_url: str, openapi: Any = None) -> None:
+        self.client_id = client_id
+        self.base_url = base_url
+        self.openapi = openapi
+
+    async def call(self, method_name: str, input: Any = None, /, **kwargs: Any) -> Any:
+        call_bridge = _require_call_bridge()
+        payload = _merge_input(input, kwargs)
+        result = await call_bridge(self.client_id, method_name, payload)
+        return _to_python_value(result)
+
+    def __getattr__(self, method_name: str):
+        async def invoke(input: Any = None, /, **kwargs: Any) -> Any:
+            return await self.call(method_name, input, **kwargs)
+
+        return invoke
+
+
+def _set_browser_client_bridge(
+    connect_bridge: BrowserClientConnectBridge,
+    call_bridge: BrowserClientCallBridge,
+) -> None:
+    global _CONNECT_BRIDGE, _CALL_BRIDGE
+    _CONNECT_BRIDGE = connect_bridge
+    _CALL_BRIDGE = call_bridge
+
+
+async def connect_client_side_server(base_url: str, options: Any = None) -> BrowserPLATClient:
+    connect_bridge = _require_connect_bridge()
+    connection = _to_python_value(await connect_bridge(base_url, options))
+    if not isinstance(connection, dict):
+        raise RuntimeError("Browser client bridge returned an invalid connection payload.")
+    return BrowserPLATClient(
+        client_id=int(connection["client_id"]),
+        base_url=str(connection.get("base_url") or base_url),
+        openapi=connection.get("openapi"),
+    )
+
+
+# Server-style parity alias.
+connect_server = connect_client_side_server
+
+
+async def run_python_client_source(source: str) -> Any:
+    namespace = {
+        "__name__": "__plat_browser_client__",
+        "connect_client_side_server": connect_client_side_server,
+    }
+    compiled = _compile_python_client_snippet(source)
+    exec(compiled, namespace)
+    result = await namespace["__plat_browser_client_main__"]()
+    return _to_python_value(result)
+
+
+def _compile_python_client_snippet(source: str):
+    module = ast.parse(source, mode="exec")
+    body = list(module.body)
+    if body and isinstance(body[-1], ast.Expr):
+        body[-1] = ast.Return(body[-1].value)
+    else:
+        body.append(ast.Return(value=ast.Constant(value=None)))
+    function = ast.AsyncFunctionDef(
+        name="__plat_browser_client_main__",
+        args=ast.arguments(
+            posonlyargs=[],
+            args=[],
+            kwonlyargs=[],
+            kw_defaults=[],
+            defaults=[],
+            vararg=None,
+            kwarg=None,
+        ),
+        body=body,
+        decorator_list=[],
+        returns=None,
+        type_comment=None,
+    )
+    wrapper = ast.Module(body=[function], type_ignores=[])
+    ast.fix_missing_locations(wrapper)
+    return compile(wrapper, "<plat_browser_client>", "exec")
+
+
+def _merge_input(input_data: Any, kwargs: dict[str, Any]) -> Any:
+    if input_data is None:
+        return kwargs or {}
+    if kwargs:
+        if isinstance(input_data, dict):
+            merged = dict(input_data)
+            merged.update(kwargs)
+            return merged
+        raise TypeError("Cannot pass both a non-dict positional input and keyword arguments.")
+    return input_data
+
+
+def _to_python_value(value: Any) -> Any:
+    to_py = getattr(value, "to_py", None)
+    if callable(to_py):
+        try:
+            return to_py()
+        except TypeError:
+            return to_py(depth=-1)
+    return value
+
+
+def _require_connect_bridge() -> BrowserClientConnectBridge:
+    if _CONNECT_BRIDGE is None:
+        raise RuntimeError("Browser Python client bridge is not installed in this runtime.")
+    return _CONNECT_BRIDGE
+
+
+def _require_call_bridge() -> BrowserClientCallBridge:
+    if _CALL_BRIDGE is None:
+        raise RuntimeError("Browser Python client bridge is not installed in this runtime.")
+    return _CALL_BRIDGE

plat_browser/decorators.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any, TypeVar, cast
+
+from .metadata import ensure_controller_meta
+from .types import ControllerMeta, HttpMethod, RouteMeta
+
+F = TypeVar("F", bound=Callable[..., Any])
+ROUTE_METADATA_KEY = "__plat_browser_route_meta__"
+
+
+def Controller(
+    controller_name: str | None = None,
+    opts: Mapping[str, Any] | None = None,
+):
+    options = dict(opts or {})
+
+    def decorator(cls: type) -> type:
+        meta = ensure_controller_meta(cls)
+        _apply_controller_options(meta, cls, controller_name, options)
+        return cls
+
+    return decorator
+
+
+def _apply_controller_options(
+    meta: ControllerMeta,
+    cls: type,
+    controller_name: str | None,
+    options: dict[str, Any],
+) -> None:
+    meta.base_path = controller_name or cls.__name__
+    meta.tag = cast(str | None, options.get("tag")) or controller_name or cls.__name__
+    meta.auth = cast(str | None, options.get("auth"))
+    meta.rate_limit = options.get("rateLimit", options.get("rate_limit"))
+    meta.token_limit = options.get("tokenLimit", options.get("token_limit"))
+    meta.cache = options.get("cache")
+
+
+def _route_decorator(method: HttpMethod):
+    def factory(
+        arg: str | Mapping[str, Any] | F | None = None,
+        opts: Mapping[str, Any] | None = None,
+    ):
+        if callable(arg):
+            return _decorate_route(cast(F, arg), method, None, {})
+
+        decorator_path: str | None = None
+        options: dict[str, Any] = dict(opts or {})
+        if isinstance(arg, str):
+            decorator_path = arg
+        elif isinstance(arg, Mapping):
+            options = dict(arg)
+        elif arg is not None:
+            raise TypeError(f"Unsupported decorator argument for {method}: {arg!r}")
+
+        def decorator(fn: F) -> F:
+            return _decorate_route(fn, method, decorator_path, options)
+
+        return decorator
+
+    return factory
+
+
+def _decorate_route(
+    fn: F,
+    method: HttpMethod,
+    decorator_path: str | None,
+    options: dict[str, Any],
+) -> F:
+    meta = RouteMeta(
+        name=fn.__name__,
+        method=method,
+        path=f"/{fn.__name__}",
+        decorator_path=decorator_path,
+        auth=cast(str | None, options.get("auth")),
+        summary=cast(str | None, options.get("summary")),
+        description=cast(str | None, options.get("description")),
+        rate_limit=options.get("rateLimit", options.get("rate_limit")),
+        token_limit=options.get("tokenLimit", options.get("token_limit")),
+        cache=options.get("cache"),
+        opts=options or None,
+    )
+    fn.__dict__[ROUTE_METADATA_KEY] = meta
+    return fn
+
+
+GET = _route_decorator("GET")
+POST = _route_decorator("POST")
+PUT = _route_decorator("PUT")
+PATCH = _route_decorator("PATCH")
+DELETE = _route_decorator("DELETE")

plat_browser/errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class HttpResponse(Exception):
+    status_code: int
+    body: Any = None
+    headers: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        super().__init__(f"HTTP {self.status_code}")
+
+
+class HttpError(HttpResponse):
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        data: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        body: dict[str, Any] = {"error": message}
+        if data is not None:
+            body["data"] = data
+        super().__init__(status_code=status_code, body=body, headers=headers or {})
+        self.message = message
+        self.data = data

plat_browser/metadata.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from .types import ControllerMeta
+
+
+CONTROLLER_METADATA_KEY = "__plat_browser_controller_meta__"
+
+
+def get_controller_meta(ctor: type) -> ControllerMeta | None:
+    return getattr(ctor, CONTROLLER_METADATA_KEY, None)
+
+
+def ensure_controller_meta(ctor: type) -> ControllerMeta:
+    meta = get_controller_meta(ctor)
+    if meta is None:
+        meta = ControllerMeta()
+        setattr(ctor, CONTROLLER_METADATA_KEY, meta)
+    return meta