squidcloud-backend 1.0.0__tar.gz

squidcloud_backend-1.0.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: squidcloud-backend
+Version: 1.0.0
+Summary: Squid Cloud Python backend SDK — decorators, services, and project entry point
+Author-email: Squid Cloud <support@squid.cloud>
+License-Expression: MIT
+Project-URL: Homepage, https://squid.cloud
+Project-URL: Documentation, https://docs.squid.cloud
+Project-URL: Repository, https://github.com/squid-cloud/squid-cloud
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: squidcloud-client>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.11.0; extra == "dev"

squidcloud_backend-1.0.0/README.md

@@ -0,0 +1,138 @@
+# Squid Cloud Python Backend SDK
+
+Python equivalent of `@squidcloud/backend` (the TypeScript backend SDK).
+Provides decorators, `SquidService`, `SquidProject`, and types for building
+Squid backend services in Python.
+
+## Package: `squidcloud-backend`
+
+Published to PyPI. Install with:
+```bash
+pip install squidcloud-backend
+```
+
+Depends on `squidcloud-client` (the Python client SDK) for `self.squid` access.
+
+## File Structure
+
+```
+squidcloud_backend/
+├── __init__.py          # Public API exports
+├── types.py             # All TypedDict types, enums, type aliases
+├── context.py           # Request-scoped context (contextvars — Python's AsyncLocalStorage)
+├── metadata.py          # Meta singleton — collects decorator registrations
+├── decorators.py        # All 27 decorators (@executable, @trigger, etc.)
+├── service.py           # SquidService base class
+├── project.py           # SquidProject entry point
+└── llm_service.py       # SquidLlmService abstract base
+```
+
+## How It Works
+
+### Decorator Registration
+
+Python decorators execute before the class body is complete, so we use a
+deferred registration pattern:
+
+1. Each decorator stores a `(name, register_fn)` tuple on the function via
+   the `__squid_decorators__` attribute
+2. When the class is defined, `SquidService.__init_subclass__()` iterates all
+   methods and calls each `register_fn(cls, method_name)`
+3. `register_fn` calls the corresponding method on the `Meta` singleton
+4. Class-level decorators (`@llm_service`, `@mcp_server`) store options as
+   class attributes, processed in `__init_subclass__()`
+
+### Request Context (contextvars)
+
+The Python equivalent of Node.js `AsyncLocalStorage` is `contextvars.ContextVar`.
+Per-request state (auth, RunContext) is stored in a context var and accessed
+via `SquidService.context`, `SquidService.get_user_auth()`, etc.
+
+```python
+# The worker sets the context before calling a service method:
+with RequestScope(ServiceRequestConfig(auth=auth, context=run_context)):
+    result = service.my_method(*params)
+
+# Inside the method, the service accesses it:
+class MyService(SquidService):
+    @executable()
+    async def my_method(self) -> str:
+        user = self.get_user_auth()  # reads from context var
+        return f"Hello, {user['userId']}!"
+```
+
+### Environment Variables
+
+The following environment variables are used:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SQUID_REGION` | Deployment region (e.g., `us-east-1.aws`) | `local` |
+| `SQUID_APP_ID` | Application ID | — |
+
+Secrets and API keys are NOT set via env vars — they are passed per-request
+in the `ExecuteFunctionPayload` from the tenant/local-backend.
+
+### Global State
+
+The worker subprocess sets these class-level globals on `SquidService` before
+each request:
+
+- `_global_secrets` — Custom secrets from the Squid console
+- `_global_api_keys` — API keys from the Squid console
+- `_global_backend_api_key` — Internal backend API key
+- `_global_app_id` — Application ID
+- `_global_assets_directory` — Path to the `public/` assets directory
+
+### self.squid — Accessing the Client SDK
+
+`SquidService.squid` returns a `squidcloud.Squid` instance (from the
+`squidcloud-client` package). It is initialized lazily using the backend API
+key and region. Backend services can call any Squid API:
+
+```python
+class MyService(SquidService):
+    @executable()
+    async def summarize(self, url: str) -> str:
+        content = await self.squid.web().get_url_content(url)
+        return await self.squid.ai().agent("summarizer").ask(content)
+```
+
+## Types
+
+All types use `TypedDict` for JSON compatibility and IDE autocompletion.
+Key types:
+
+- **Request/Response**: `WebhookRequest`, `WebhookResponse`, `TriggerRequest`,
+  `OpenApiResponse`, `SquidFile`
+- **Auth**: `AuthWithBearer`, `AuthWithApiKey`, `RunContext`, `ServiceRequestConfig`
+- **Decorator options**: `TriggerOptions`, `SchedulerOptions`, `AiFunctionParam`,
+  `LimiterConfig`, `McpServerOptions`, `LlmServiceOptions`
+- **Enums**: `CronExpression` (50+ common cron schedules)
+- **Action types**: `DatabaseActionType`, `StorageActionType`, `TopicActionType`,
+  `MetricActionType`, `MutationType`
+
+## Metadata Output
+
+`SquidProject.metadata()` returns a dict matching the `ApplicationBundleData`
+JSON schema. This is consumed by the platform to discover and route:
+executables, webhooks, triggers, schedulers, security rules, AI functions,
+LLM services, MCP servers, and rate/quota limits.
+
+## Compatibility with TypeScript SDK
+
+This SDK mirrors the TypeScript `@squidcloud/backend` package:
+
+| TypeScript | Python |
+|------------|--------|
+| `class MyService extends SquidService` | `class MyService(SquidService)` |
+| `@executable()` | `@executable()` |
+| `@trigger('id', 'collection')` | `@trigger('id', 'collection')` |
+| `@scheduler('id', CronExpression.EVERY_HOUR)` | `@scheduler('id', CronExpression.EVERY_HOUR)` |
+| `@webhook('id')` | `@webhook('id')` |
+| `@aiFunction('desc', params)` | `@ai_function('desc', params)` |
+| `this.squid` | `self.squid` |
+| `this.context` | `self.context` |
+| `this.secrets` | `self.secrets` |
+| `this.createWebhookResponse(...)` | `self.create_webhook_response(...)` |
+| `new SquidProject()` | `SquidProject()` |

squidcloud_backend-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "squidcloud-backend"
+version = "1.0.0"
+description = "Squid Cloud Python backend SDK — decorators, services, and project entry point"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{name = "Squid Cloud", email = "support@squid.cloud"}]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "squidcloud-client>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://squid.cloud"
+Documentation = "https://docs.squid.cloud"
+Repository = "https://github.com/squid-cloud/squid-cloud"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "ruff>=0.11.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["squidcloud_backend*"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "SIM", "TCH", "RUF"]
+ignore = ["E501", "UP007"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["squidcloud_backend"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true

squidcloud_backend-1.0.0/setup.cfg

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

squidcloud_backend-1.0.0/squidcloud_backend/__init__.py

@@ -0,0 +1,155 @@
+"""Squid Cloud Python backend SDK.
+
+Provides decorators, base classes, and types for building Squid backend
+services in Python.
+
+Usage::
+
+    from squidcloud_backend import SquidService, SquidProject, executable, webhook
+
+    class MyService(SquidService):
+        @webhook("hello")
+        async def hello_webhook(self, request: WebhookRequest) -> WebhookResponse:
+            return self.create_webhook_response(body={"message": "Hello!"})
+
+        @executable()
+        async def greet(self, name: str) -> str:
+            return f"Hello, {name}!"
+
+    project = SquidProject()
+"""
+
+from squidcloud_backend.decorators import (
+    ai_function,
+    ai_functions_configurator,
+    client_connection_state_handler,
+    executable,
+    limits,
+    llm_ask,
+    llm_service,
+    mcp_authorizer,
+    mcp_server,
+    mcp_tool,
+    scheduler,
+    secure_ai_agent,
+    secure_ai_query,
+    secure_api,
+    secure_collection,
+    secure_database,
+    secure_distributed_lock,
+    secure_graphql,
+    secure_metric,
+    secure_native_query,
+    secure_storage,
+    secure_topic,
+    transform_collection,
+    transform_database,
+    trigger,
+    webhook,
+)
+from squidcloud_backend.llm_service import SquidLlmService
+from squidcloud_backend.project import SquidProject
+from squidcloud_backend.service import (
+    OpenApiResponseException,
+    SquidService,
+    WebhookResponseException,
+)
+from squidcloud_backend.types import (
+    AiFunctionAttributes,
+    AiFunctionMetadataOptions,
+    AiFunctionParam,
+    AiFunctionsConfiguratorMetadataOptions,
+    Auth,
+    AuthWithApiKey,
+    AuthWithBearer,
+    ClientConnectionState,
+    CronExpression,
+    LimiterConfig,
+    LlmServiceOptions,
+    McpAuthorizationRequest,
+    McpServerOptions,
+    McpToolMetadataOptions,
+    OnIntegrationLifecycleInput,
+    OpenApiResponse,
+    QuotaLimitOptions,
+    RateLimitOptions,
+    RunContext,
+    SchedulerOptions,
+    SecureMetricOptions,
+    ServiceRequestConfig,
+    SquidFile,
+    TriggerOptions,
+    TriggerRequest,
+    UserAiAskResponse,
+    UserAiChatOptions,
+    WebhookRequest,
+    WebhookResponse,
+)
+
+__all__ = [
+    # Core classes
+    "SquidService",
+    "SquidProject",
+    "SquidLlmService",
+    # Exceptions
+    "WebhookResponseException",
+    "OpenApiResponseException",
+    # Decorators
+    "ai_function",
+    "ai_functions_configurator",
+    "client_connection_state_handler",
+    "executable",
+    "limits",
+    "llm_ask",
+    "llm_service",
+    "mcp_authorizer",
+    "mcp_server",
+    "mcp_tool",
+    "scheduler",
+    "secure_ai_agent",
+    "secure_ai_query",
+    "secure_api",
+    "secure_collection",
+    "secure_database",
+    "secure_distributed_lock",
+    "secure_graphql",
+    "secure_metric",
+    "secure_native_query",
+    "secure_storage",
+    "secure_topic",
+    "transform_collection",
+    "transform_database",
+    "trigger",
+    "webhook",
+    # Auth & Context
+    "Auth",
+    "AuthWithApiKey",
+    "AuthWithBearer",
+    "ClientConnectionState",
+    "RunContext",
+    "ServiceRequestConfig",
+    # Types
+    "AiFunctionAttributes",
+    "AiFunctionMetadataOptions",
+    "AiFunctionParam",
+    "AiFunctionsConfiguratorMetadataOptions",
+    "CronExpression",
+    "LimiterConfig",
+    "LlmServiceOptions",
+    "McpAuthorizationRequest",
+    "McpServerOptions",
+    "McpToolMetadataOptions",
+    "OnIntegrationLifecycleInput",
+    "OpenApiResponse",
+    "QuotaLimitOptions",
+    "RateLimitOptions",
+    "SchedulerOptions",
+    "SecureMetricOptions",
+    "SquidFile",
+    "TriggerOptions",
+    "TriggerRequest",
+    "UserAiAskResponse",
+    "UserAiChatOptions",
+    "WebhookRequest",
+    "WebhookResponse",
+]

squidcloud_backend-1.0.0/squidcloud_backend/context.py

@@ -0,0 +1,64 @@
+"""Request-scoped context management using Python contextvars.
+
+Python equivalent of Node.js AsyncLocalStorage used in the TS SDK for
+per-request state (auth, RunContext, etc.).
+"""
+
+from __future__ import annotations
+
+import contextvars
+from typing import Any
+
+from squidcloud_backend.types import ServiceRequestConfig
+
+_current_request: contextvars.ContextVar[ServiceRequestConfig | None] = contextvars.ContextVar(
+    "_current_request", default=None
+)
+
+
+def get_request_config() -> ServiceRequestConfig:
+    """Get the current request's ServiceRequestConfig.
+
+    Raises:
+        RuntimeError: If called outside of a request scope.
+    """
+    config = _current_request.get()
+    if config is None:
+        raise RuntimeError(
+            "Failed to access request data outside of the request's scope. "
+            "This method can only be called during request execution."
+        )
+    return config
+
+
+def set_request_config(config: ServiceRequestConfig) -> contextvars.Token:
+    """Set the request config for the current context. Returns a token for reset."""
+    return _current_request.set(config)
+
+
+def reset_request_config(token: contextvars.Token) -> None:
+    """Reset the request config to its previous value."""
+    _current_request.reset(token)
+
+
+class RequestScope:
+    """Context manager for running code within a request scope.
+
+    Usage::
+
+        with RequestScope(config):
+            result = service.my_method(*args)
+    """
+
+    def __init__(self, config: ServiceRequestConfig) -> None:
+        self._config = config
+        self._token: contextvars.Token | None = None
+
+    def __enter__(self) -> ServiceRequestConfig:
+        self._token = set_request_config(self._config)
+        return self._config
+
+    def __exit__(self, *args: Any) -> None:
+        if self._token is not None:
+            reset_request_config(self._token)
+            self._token = None