Metadata-Version: 2.4
Name: caspian-utils
Version: 0.2.5
Summary: A utility package for Caspian projects
Home-page: https://github.com/TheSteelNinjaCode/caspian_utils
Author: Jefferson Abraham
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: fastapi==0.136.1
Requires-Dist: uvicorn==0.46.0
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: jinja2==3.1.6
Requires-Dist: tailwind-merge==0.3.3
Requires-Dist: slowapi==0.1.9
Requires-Dist: python-multipart==0.0.27
Requires-Dist: starsessions==2.2.1
Requires-Dist: httpx==0.28.1
Requires-Dist: werkzeug==3.1.8
Requires-Dist: cuid2==2.0.1
Requires-Dist: nanoid==2.0.0
Requires-Dist: python-ulid==3.1.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```bash
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

```py
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

```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

```html
<!-- @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.

```py
from casp.layout import render_page


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

```html
<!-- 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.

```py
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](https://github.com/TheSteelNinjaCode/caspian_utils)

## License

MIT

## Author

Jefferson Abraham
