ContentGrid Extension Helpers

Reusable helpers for building ContentGrid extensions in Python with FastAPI.

Features

• Authentication: OIDC/OAuth token verification and a ContentGridUserDependency for FastAPI routes.
• ContentGrid clients: factories for clients authenticated via the extension flow (on behalf of the user) or a service account.
• Database: SQLModel session factories for PostgreSQL and SQLite, plus a base repository.
• Responses: HAL / HAL-Forms response models and RFC 7807 problem responses.
• Middleware & logging: exception middleware and JSON logging (setup_json_logging).

Installation

pip install contentgrid-extension-helpers

Configuration

Settings are read from environment variables (case-insensitive). .env and .env.secret files in the working directory are also loaded. Values passed directly to a constructor take precedence over the environment.

Authentication (ContentGridUserDependency)

Extension flow client (ContentGridExtensionFlowClientFactory)

Service account client (ContentGridServiceAccountFactory)

Database

Server (extension_config)

Examples

Authentication

from fastapi import FastAPI, Depends
from contentgrid_extension_helpers.dependencies.authentication.user import ContentGridUserDependency
from contentgrid_extension_helpers.authentication.user import ContentGridUser

app = FastAPI()
current_user = ContentGridUserDependency()  # reads EXTENSION_NAME, OAUTH_ISSUER, ...

@app.get("/me")
def me(user: ContentGridUser = Depends(current_user)):
    return user

HAL responses

Subclass FastAPIHALResponse for your resources and reference other endpoints by function name with HALLinkFor / HALTemplateFor. They are resolved to URLs from the app's routes during serialization. HAL-Forms templates get their properties from the endpoint's request body model.

import uuid
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from contentgrid_extension_helpers.responses.hal import (
    FastAPIHALResponse, FastAPIHALCollection, HALLinkFor, HALTemplateFor,
)

app = FastAPI()
FastAPIHALResponse.init_app(app)                            # required: resolve links from this app's routes
FastAPIHALResponse.add_server_url("http://localhost:8000")  # optional: make links absolute

class BookCreate(BaseModel):
    title: str

class Book(FastAPIHALResponse):
    id: uuid.UUID = Field(default_factory=uuid.uuid4)
    title: str

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        # path_params as a callable receives the instance at serialization time
        self.links = {
            "self": HALLinkFor(endpoint_function_name="get_book", path_params=lambda book: {"book_id": str(book.id)}),
            "collection": HALLinkFor(endpoint_function_name="list_books"),
        }

books: list[Book] = [Book(title="Dune")]

@app.get("/books", response_model=FastAPIHALCollection, response_model_exclude_none=True)
def list_books():
    return FastAPIHALCollection[Book](
        _links={"self": HALLinkFor(endpoint_function_name="list_books")},
        _embedded={"books": books},
        _templates={"create": HALTemplateFor(endpoint_function_name="create_book")},
    )

@app.get("/books/{book_id}", response_model=Book, response_model_exclude_none=True)
def get_book(book_id: uuid.UUID):
    for book in books:
        if book.id == book_id:
            return book
    raise HTTPException(status_code=404, detail="Book not found")

@app.post("/books", response_model=Book, response_model_exclude_none=True)
def create_book(book: BookCreate):
    new_book = Book(**book.model_dump())
    books.append(new_book)
    return new_book

GET /books returns:

{
  "_links": { "self": { "href": "http://localhost:8000/books", "templated": false } },
  "_templates": {
    "create": {
      "method": "POST",
      "contentType": "application/json",
      "properties": [{ "name": "title", "type": "text", "prompt": "title", "required": true }],
      "target": "http://localhost:8000/books"
    }
  },
  "_embedded": {
    "books": [{
      "_links": {
        "self": { "href": "http://localhost:8000/books/3f2b8c1e-5d4a-4b7e-9c6f-1a2b3c4d5e6f", "templated": false },
        "collection": { "href": "http://localhost:8000/books", "templated": false }
      },
      "id": "3f2b8c1e-5d4a-4b7e-9c6f-1a2b3c4d5e6f",
      "title": "Dune"
    }]
  }
}

path_params and params take either a dict of strings or a callable that receives the resource, as in Book above. Links can also be passed per response with _links=..., as done for the collection. condition (a bool or a callable) leaves a link or template out when it is false. When routers are included more than once, pass tags to choose the right route.

Development

# from the repository root
pip install -r requirements.txt -r requirements-dev.txt
cd contentgrid_extension_helpers && pytest