caspian-utils 0.2.8

A utility package for Caspian projects

Caspian Utils (casp)

HTML-first utilities for Caspian applications.

caspian-utils is the shared Python runtime package behind Caspian templates, components, layouts, RPC handlers, and supporting utilities. This repository is not a full application starter, so this README documents the package surface that exists here.

• PyPI package: caspian-utils
• Python package: casp
• Python requirement: >=3.14

Installation

pip install caspian-utils

Core Model

Caspian is HTML-first.

• write UI in .html
• define reusable components in Python
• import those components with @import comments inside HTML
• render them with <x-component-name /> tags
• render pages and layouts from Python with helpers in casp.layout

This matches the current compiler behavior in this package.

HTML-First Components

Define a component in Python

from casp.component_decorator import component


@component
def AlertBox(title: str, children: str = "", class_name: str = "") -> str:
    return f"""
    <section class="alert {class_name}">
        <h2>{title}</h2>
        <div>{children}</div>
    </section>
    """

Import and use it in HTML

<!-- @import { AlertBox } from "../components/ui" -->

<main class="space-y-4">
  <x-alert-box title="Saved">
    <p>Your settings were updated.</p>
  </x-alert-box>
</main>

Alias imports when needed

<!-- @import { AlertBox as Notice } from "../components/ui" -->

<div>
  <x-notice title="Heads up" />
</div>

Import and tag rules:

• AlertBox becomes <x-alert-box>
• aliases also convert to kebab-case, so Notice becomes <x-notice>
• grouped imports use <!-- @import { A, B as C } from "..." -->
• single imports use <!-- @import ComponentName from "..." -->
• paths are resolved relative to the current template or component directory

Example: <!-- @import { AlertBox } from "../components/ui" --> resolves AlertBox from ../components/ui/AlertBox.py.

Rendering Pages and Layouts

Use casp.layout to render HTML templates relative to a Python file.

from casp.layout import render_page


def get_dashboard() -> str:
    return render_page(__file__, {
        "pageTitle": "Dashboard",
        "stats": ["Projects", "Tasks", "Alerts"],
    })

<!-- app/dashboard/index.html -->
<!-- @import { AlertBox } from "../components/ui" -->

<main class="space-y-6">
  <h1>[[ pageTitle ]]</h1>

  <x-alert-box title="Welcome back" class="rounded border p-4">
    <p>Rendered through an imported Python component.</p>
  </x-alert-box>

  <ul>
    <template casp-for="label in stats">
      <li>[[ label ]]</li>
    </template>
  </ul>
</main>

casp.layout also exposes render_layout(), render(), load_template(), and layout discovery helpers for nested layout flows.

Template Syntax Supported Here

This package supports the Caspian syntax that is transpiled into Jinja-compatible templates:

• [[ value ]] interpolation
• <template casp-for="..."></template> loops
• <template casp-if="..."></template> conditionals
• imported component rendering through <x-...> tags
• dynamic template compilation and nested layout rendering

Template Constraints

Some compiler rules are important when writing templates:

• every page, layout, and component must render exactly one top-level native HTML element
• the root element cannot be an <x-...> component tag
• unknown <x-...> tags raise an error unless the component has been imported
• async components are supported by the component pipeline

These constraints exist because Caspian injects pp-component metadata into the rendered root element.

RPC Helpers

The package also includes the server-side RPC decorator and related request/serialization utilities.

from casp.rpc import rpc


@rpc(require_auth=True, limits="30/minute")
async def save_profile(name: str):
    return {"ok": True, "name": name}

casp.rpc includes:

• RPC registration
• auth-aware decorators
• rate limiting
• serialization for common Python objects
• FastAPI-oriented request and response helpers

Main Modules

Module	Purpose
casp.layout	Load, compile, and render pages and nested layouts
casp.component_decorator	@component, component loading, and HTML rendering helpers
casp.components_compiler	Parse @import directives and transform <x-...> component tags
casp.syntax_compiler	Transpile Caspian HTML syntax into Jinja-compatible templates
casp.rpc	RPC decorator, registration, serialization, and request handling helpers
casp.streaming	Server-Sent Events helpers including SSE
casp.validate	Validation and sanitization helpers for strings, IDs, files, dates, and numbers
casp.caspian_config	Config loading and file index helpers

Included Dependencies

This release currently installs utilities commonly used by Caspian apps, including:

• fastapi
• uvicorn
• jinja2
• python-dotenv
• slowapi
• starsessions
• python-multipart
• httpx
• tailwind-merge
• werkzeug
• cuid2
• nanoid
• python-ulid

See setup.py for the pinned versions in this release.

Repository

TheSteelNinjaCode/caspian_utils

License

MIT

Author

Jefferson Abraham