stupidhuman-func 0.2.0__tar.gz

stupidhuman_func-0.2.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: stupidhuman-func
+Version: 0.2.0
+Summary: Decorator library for turning plain Python functions into Azure HTTP-triggered Functions
+Requires-Python: >=3.8
+Requires-Dist: azure-functions>=1.24.0
+Requires-Dist: azurefunctions-extensions-http-fastapi
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: requires-python

stupidhuman_func-0.2.0/README.md

@@ -0,0 +1,584 @@
+# azure-func-decorator
+
+A decorator library that turns plain Python functions into Azure HTTP-triggered
+Functions or MCP tool triggers automatically. It handles parameter extraction
+(query string, route params, and JSON body), type coercion, OAuth2/JWT scope
+validation, and error responses.
+
+## Installation
+
+**From GitHub via HTTPS:**
+
+```bash
+pip install git+https://github.com/stupidhumanAI/python-func.git
+```
+
+**From GitHub via SSH** (requires an SSH key configured for your GitHub account):
+
+```bash
+pip install git+ssh://git@github.com/stupidhumanAI/python-func.git
+```
+
+Pin to a specific tag or commit when you need reproducible installs:
+
+```bash
+# HTTPS
+pip install git+https://github.com/stupidhumanAI/python-func.git@v0.1.0
+pip install git+https://github.com/stupidhumanAI/python-func.git@<commit-sha>
+
+# SSH
+pip install git+ssh://git@github.com/stupidhumanAI/python-func.git@v0.1.0
+pip install git+ssh://git@github.com/stupidhumanAI/python-func.git@<commit-sha>
+```
+
+Inside a `requirements.txt` or `pyproject.toml`:
+
+```
+# requirements.txt (HTTPS)
+git+https://github.com/stupidhumanAI/python-func.git@v0.1.0
+
+# requirements.txt (SSH)
+git+ssh://git@github.com/stupidhumanAI/python-func.git@v0.1.0
+```
+
+```toml
+# pyproject.toml (HTTPS)
+[project]
+dependencies = [
+    "azure-func-decorator @ git+https://github.com/stupidhumanAI/python-func.git@v0.1.0",
+]
+
+# pyproject.toml (SSH)
+[project]
+dependencies = [
+    "azure-func-decorator @ git+ssh://git@github.com/stupidhumanAI/python-func.git@v0.1.0",
+]
+```
+
+## Public API
+
+Two top-level classes are exported from `azure_func`:
+
+```python
+from azure_func import AzureFunctionApp   # simple HTTP routes
+from azure_func import ServiceHandler     # HTTP routes + OAuth2 scope guards
+```
+
+---
+
+### `AzureFunctionApp`
+
+A thin wrapper around `azure.functions.FunctionApp`. Use it when you do not
+need scope-based access control.
+
+```python
+app = AzureFunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS, **kwargs)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `http_auth_level` | `func.AuthLevel` | `ANONYMOUS` | Passed straight to the underlying `FunctionApp` |
+| `**kwargs` | — | — | Forwarded to `FunctionApp.__init__` |
+
+**`app.route(route=None, methods=None)`** — decorator
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `route` | `str \| None` | function name | URL path for the HTTP trigger |
+| `methods` | `list[str] \| None` | `["GET", "POST"]` | Accepted HTTP methods |
+
+Returns the **original function unchanged**, so it can be called directly in
+tests and other code without going through the HTTP layer.
+
+**`app.func_app`** — the underlying `azure.functions.FunctionApp` instance.
+
+#### Example
+
+```python
+import azure.functions as func
+from azure_func import AzureFunctionApp
+
+app = AzureFunctionApp()
+
+@app.route()
+def full_name(fname, lname):
+    return fname + " " + lname
+
+# GET /full_name?fname=John&lname=Doe  →  {"result": "John Doe"}
+
+@app.route(route="api/greet", methods=["GET"])
+def greet(name, greeting="Hello"):
+    return f"{greeting}, {name}!"
+
+# GET /api/greet?name=World  →  {"result": "Hello, World!"}
+
+# The original function is still directly callable:
+assert full_name("John", "Doe") == "John Doe"
+```
+
+---
+
+### `ServiceHandler`
+
+Like `AzureFunctionApp` but adds OAuth2/JWT scope validation via
+`@sh.scope()`. Use it when endpoints must be protected by bearer tokens.
+
+```python
+sh = ServiceHandler(http_auth_level=func.AuthLevel.ANONYMOUS, **kwargs)
+```
+
+Constructor parameters are identical to `AzureFunctionApp`.
+
+**`sh.service(route=None, methods=None)`** — decorator
+
+Same parameters as `app.route()`. Reads any scope metadata placed on the
+function by `@sh.scope()` and enforces it on every request.
+
+**`sh.anonymous(route=None, methods=None)`** — decorator
+
+Same parameters as `sh.service()`. Registers the function as a public HTTP
+trigger with no authentication or scope requirements. Use this instead of
+`@sh.service()` to make the intent explicit that the endpoint is publicly
+accessible, even when other endpoints on the same handler use `@sh.scope()`.
+
+**`sh.scope(*scopes)`** — decorator
+
+Attaches required OAuth2 scope strings to a function. The check is an **AND**:
+all listed scopes must be present in the token.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `*scopes` | `str` | One or more scope strings to require |
+
+`@sh.scope()` is **cumulative**: stacking multiple calls or listing multiple
+scopes in one call both accumulate onto the same set of required scopes.
+Scope metadata is stored on the function object under the attribute
+`_required_scopes` and is read by `@sh.service()` at decoration time.
+
+`@sh.scope()` must be applied **below** `@sh.service()` in the source (i.e.
+closer to the function definition).
+
+#### Example
+
+```python
+from azure_func import ServiceHandler
+
+sh = ServiceHandler()
+
+@sh.anonymous()
+def health():
+    return "ok"
+
+# GET /health  →  {"result": "ok"}  (no token required)
+
+@sh.service()
+@sh.scope("read:items")
+def get_item(item_id: int):
+    return {"id": item_id}
+
+@sh.service(methods=["POST"])
+@sh.scope("read:items")
+@sh.scope("write:items")   # cumulative — both scopes required
+def create_item(name, price: float):
+    return {"name": name, "price": price}
+
+# Equivalent single call:
+# @sh.scope("read:items", "write:items")
+```
+
+---
+
+## Parameter handling
+
+Parameters are resolved from the HTTP request using this priority order:
+
+1. **Query string** — `?key=value`
+2. **Route params** — path segments defined in the route template (e.g. `route="items/{item_id}"`)
+3. **JSON body** — `Content-Type: application/json` with `{"key": "value"}`
+
+Query string always wins when the same key appears in multiple sources.
+
+All incoming values arrive as strings. If a function parameter has a type
+annotation the value is cast before the function is called.
+
+### Type coercion
+
+| Annotation | Behaviour |
+|---|---|
+| `int` | `int(value)` |
+| `float` | `float(value)` |
+| `bool` | `False` for `"false"`, `"0"`, `"no"`, `""`; `True` for everything else (case-insensitive) |
+| `str` | no-op |
+| any other callable | called with the string value |
+
+Failed coercion returns **HTTP 400** before the function is invoked.
+
+### Default values
+
+Parameters with Python default values are optional in the request. Parameters
+without defaults are required; omitting them returns **HTTP 400**.
+
+```python
+@sh.service()
+def calc(n: int, op: str = "double"):
+    return n * 2 if op == "double" else n
+
+# GET /calc?n=5         →  {"result": 10}
+# GET /calc?n=5&op=id   →  {"result": 5}
+# GET /calc             →  400 {"error": "Missing required parameter(s): n"}
+```
+
+Route parameters are declared in the `route` template using `{param}` syntax and
+resolved automatically like any other parameter:
+
+```python
+@sh.service(route="items/{item_id}", methods=["GET"])
+def get_item(item_id: int):
+    return {"id": item_id}
+
+# GET /items/42  →  {"result": {"id": 42}}
+```
+
+---
+
+## Response format
+
+Every response body is JSON.
+
+### Success
+
+```json
+{"result": <return value of the function>}
+```
+
+HTTP status: **200**
+
+### Error responses
+
+| Situation | Status | Body |
+|---|---|---|
+| Missing required parameter(s) | 400 | `{"error": "Missing required parameter(s): x, y"}` |
+| Type coercion failure | 400 | `{"error": "Invalid value for 'n': expected int, got 'abc'", "detail": "<exception message>"}` |
+| Missing or insufficient scope | 403 | `{"error": "Insufficient scope", "required": ["scope1", ...]}` |
+| Unhandled exception in function | 500 | `{"error": "Internal server error", "detail": "<exception message>"}` |
+
+---
+
+## OAuth2 / JWT scope validation
+
+When `@sh.scope()` is used, every request must include an `Authorization`
+header with a Bearer JWT:
+
+```
+Authorization: Bearer <jwt>
+```
+
+Scopes are read from the JWT payload (no signature verification is performed —
+the Azure Functions host or an API gateway is expected to validate the token):
+
+- `scp` claim — Azure AD format, space-separated string
+- `scope` claim — standard OAuth2, space-separated string or list
+
+If the header is absent, malformed, or the token does not contain all required
+scopes, the handler returns **HTTP 403** and the function is never called.
+
+---
+
+## Project layout for Azure Functions
+
+A minimal Azure Functions v2 (Python) project using this library:
+
+```
+my_project/
+├── function_app.py      ← entry point; register all routes here
+├── host.json
+├── local.settings.json
+└── requirements.txt
+```
+
+**`function_app.py`**:
+
+```python
+import azure.functions as func
+from azure_func import AzureFunctionApp
+
+app = AzureFunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
+
+@app.route()
+def hello(name: str):
+    return f"Hello, {name}!"
+```
+
+The `app` (or `sh.func_app` when using `ServiceHandler`) must be named `app`
+in `function_app.py` — that is what the Azure Functions runtime discovers.
+
+When using `ServiceHandler`, expose `sh.func_app` as `app`:
+
+```python
+from azure_func import ServiceHandler
+import azure.functions as func
+
+sh = ServiceHandler(http_auth_level=func.AuthLevel.ANONYMOUS)
+app = sh.func_app   # runtime entry point
+
+@sh.service()
+@sh.scope("api:access")
+def protected(value: str):
+    return value.upper()
+```
+
+---
+
+## Queue triggers
+
+`@sh.queue(queue_name)` registers a function as an Azure Storage Queue trigger.
+The function is called automatically whenever a message arrives on the specified
+queue, receiving a `func.QueueMessage` object.
+
+### `sh.queue(queue_name, connection="AzureWebJobsStorage")` — decorator
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `queue_name` | `str` | — | Name of the storage queue to listen on |
+| `connection` | `str` | `"AzureWebJobsStorage"` | App setting name for the storage connection string |
+
+```python
+import azure.functions as func
+from azure_func import ServiceHandler
+
+sh = ServiceHandler()
+app = sh.func_app
+
+@sh.queue("my-queue")
+def process_message(msg: func.QueueMessage):
+    data = msg.get_json()          # parse JSON body
+    raw = msg.get_body().decode()  # raw string body
+    print(f"Received: {data}")
+
+@sh.queue("orders", connection="OrdersStorageConnection")
+def process_order(msg: func.QueueMessage):
+    order = msg.get_json()
+    ...
+```
+
+Unhandled exceptions are logged and re-raised, which causes the Azure Functions
+runtime to retry the message according to the queue's poison-message policy.
+
+---
+
+## Streaming responses
+
+`@sh.stream()` registers an async generator function as an HTTP trigger that
+streams its output using the
+[`azurefunctions-extensions-http-fastapi`](https://pypi.org/project/azurefunctions-extensions-http-fastapi/)
+extension. This is the correct approach for SSE, LLM token streaming, and any
+response too large to buffer.
+
+All handlers (`@sh.service()`, `@sh.anonymous()`, `@sh.stream()`) now use
+the FastAPI-compatible `Request` type from this extension, so the request model
+is consistent across the whole app.
+
+### `sh.stream(route=None, methods=None, media_type="text/event-stream")` — decorator
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `route` | `str \| None` | function name | URL path for the HTTP trigger |
+| `methods` | `list[str] \| None` | `["GET", "POST"]` | Accepted HTTP methods |
+| `media_type` | `str` | `"text/event-stream"` | `Content-Type` of the streamed response |
+
+The decorated function must be an **async generator** (`async def` with `yield`).
+Parameters are extracted and type-coerced exactly like `@sh.service()`.
+`@sh.scope()` is supported and enforced before streaming begins.
+
+```python
+from azure_func import ServiceHandler
+
+sh = ServiceHandler()
+app = sh.func_app
+
+@sh.stream()
+async def count(n: int):
+    """Stream n numbers as Server-Sent Events."""
+    for i in range(n):
+        yield f"data: {i}\n\n"
+
+# GET /count?n=3  →  streams:
+#   data: 0
+#
+#   data: 1
+#
+#   data: 2
+#
+
+@sh.stream(media_type="application/x-ndjson")
+@sh.scope("read:data")
+async def search_results(query: str):
+    """Stream search results as newline-delimited JSON."""
+    import json
+    for result in run_search(query):
+        yield json.dumps(result) + "\n"
+```
+
+### Required environment variables
+
+Add these to `local.settings.json` for local development and to Azure App
+Settings for deployed apps:
+
+```json
+{
+  "IsEncrypted": false,
+  "Values": {
+    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
+    "FUNCTIONS_WORKER_RUNTIME": "python",
+    "PYTHON_ENABLE_INIT_INDEXING": "1",
+    "PYTHON_ISOLATE_WORKER_DEPENDENCIES": "1"
+  }
+}
+```
+
+`PYTHON_ENABLE_INIT_INDEXING=1` is required for all deployments.
+`PYTHON_ISOLATE_WORKER_DEPENDENCIES=1` is required on the Linux Consumption
+plan and recommended elsewhere to avoid protobuf/grpcio conflicts.
+
+### Limitations
+
+- Does not work on **Premium** or **Dedicated** hosting plans (known Azure issue)
+- Works on **Consumption** and **Flex Consumption** plans
+
+---
+
+## Static files
+
+`@sh.static(folder)` registers a catch-all GET route that serves files from a
+local folder at the root URL path.
+
+```python
+@sh.static('public')
+def serve_static():
+    pass
+
+# GET /style.css        →  ./public/style.css
+# GET /js/app.js        →  ./public/js/app.js
+# GET /images/logo.png  →  ./public/images/logo.png
+```
+
+| Situation | Status |
+|---|---|
+| File found | 200 with correct `Content-Type` |
+| File not found | 404 |
+| Path traversal attempt | 404 |
+
+The `folder` argument is relative to the function app's working directory.
+MIME types are detected automatically from the file extension.
+
+Because the catch-all route `{*filepath}` has lower specificity than named
+routes, all your `@sh.service()` and `@sh.tool()` endpoints continue to take
+precedence.
+
+---
+
+## MCP tools
+
+`ServiceHandler` supports registering functions as [Azure Functions MCP tool
+triggers](https://learn.microsoft.com/en-us/azure/azure-functions/functions-bindings-mcp-tool-trigger)
+via `@sh.tool()`. This turns your function app into a remote MCP server that
+any MCP client (e.g. VS Code Agent Mode, Claude Desktop) can connect to.
+
+Requires `azure-functions >= 1.25.0b2` (still in pre-release — install explicitly
+with `pip install "azure-functions>=1.25.0b2"`) and the **preview extension bundle** in
+`host.json` (included in this repo).
+
+### `sh.tool()` — decorator
+
+Registers the function as an MCP tool trigger. The **function name** becomes
+the tool name and the **docstring** becomes the tool description. Each
+parameter is automatically registered as an MCP tool property.
+
+```python
+from azure_func import ServiceHandler
+
+sh = ServiceHandler()
+app = sh.func_app   # runtime entry point
+
+@sh.tool()
+def hello() -> str:
+    """Say hello."""
+    return "Hello from MCP!"
+
+@sh.tool()
+@sh.tool_property("item_id", "The ID of the item to retrieve.")
+def get_item(item_id: int) -> str:
+    """Get an item by ID."""
+    return str(item_id)
+
+@sh.tool()
+@sh.tool_property("name", "The name of the item.")
+@sh.tool_property("price", "The price of the item in USD.")
+def create_item(name: str, price: float) -> str:
+    """Create a new item with a name and price."""
+    return f"Created {name} at ${price}"
+```
+
+Property descriptions are optional — parameters without a `@sh.tool_property()`
+are still registered as MCP tool properties, just without a description.
+
+### Authentication
+
+MCP tools are **not** protected by `@sh.scope()`. Instead, authentication is
+handled at the Azure host level via the `mcp_extension` system key. When
+deployed, clients must include this key either as a `?code=` query parameter
+or as the `x-functions-key` header.
+
+Retrieve the key from the portal (**Functions → App keys → System keys →
+`mcp_extension`**) or via the CLI:
+
+```bash
+az functionapp keys list --name <app> --resource-group <rg> --query systemKeys
+```
+
+### Connecting an MCP client
+
+**VS Code (Agent Mode)** — add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "my-func-mcp": {
+      "type": "http",
+      "url": "https://<funcappname>.azurewebsites.net/runtime/webhooks/mcp",
+      "headers": {
+        "x-functions-key": "<mcp_extension key>"
+      }
+    }
+  }
+}
+```
+
+**MCP Inspector** — use the URL with `?code=<mcp_extension key>` appended.
+
+### host.json
+
+The `mcpToolTrigger` binding is a preview feature and requires the preview
+extension bundle. The `host.json` in this repo is already configured:
+
+```json
+{
+  "version": "2.0",
+  "extensionBundle": {
+    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
+    "version": "[4.*, 5.0.0)"
+  }
+}
+```
+
+---
+
+## Running tests
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+Tests mock the Azure SDK (`azure.functions`) entirely, so no Azure account or
+Functions runtime is needed.

stupidhuman_func-0.2.0/azure_func/__init__.py

@@ -0,0 +1,5 @@
+from .app import AzureFunctionApp
+from .service_handler import ServiceHandler
+from .openai import stream_chat
+
+__all__ = ["AzureFunctionApp", "ServiceHandler", "stream_chat"]

stupidhuman_func-0.2.0/azure_func/app.py

@@ -0,0 +1,48 @@
+import azure.functions as func
+
+from .decorator import make_http_handler
+
+
+class AzureFunctionApp:
+    """
+    Thin wrapper around ``azure.functions.FunctionApp`` that adds a
+    ``@app.route()`` decorator for turning plain Python functions into
+    Azure HTTP-triggered functions.
+
+    Usage::
+
+        app = AzureFunctionApp()
+
+        @app.route()
+        def full_name(fname, lname):
+            return fname + " " + lname
+
+        # The underlying FunctionApp is available as app.func_app
+    """
+
+    def __init__(self, http_auth_level=func.AuthLevel.ANONYMOUS, **kwargs):
+        self.func_app = func.FunctionApp(http_auth_level=http_auth_level, **kwargs)
+
+    # Proxy attribute access so callers can do ``app.func_app`` things directly
+    def __getattr__(self, name):
+        return getattr(self.func_app, name)
+
+    def route(self, route: str = None, methods: list = None):
+        """
+        Decorator that registers the wrapped function as an Azure HTTP trigger.
+
+        Args:
+            route:   URL path segment. Defaults to the function's own name.
+            methods: HTTP methods to accept. Defaults to ``["GET", "POST"]``.
+
+        The decorated function is returned unchanged so it can still be
+        called directly in tests or other Python code.
+        """
+        if methods is None:
+            methods = ["GET", "POST"]
+
+        def decorator(fn):
+            route_name = route or fn.__name__
+            return make_http_handler(fn, self.func_app, route_name, methods)
+
+        return decorator