# djarea (Python)

Django server functions framework. See the [monorepo root](../README.md) for full documentation.

## Install

```bash
uv add "djarea[channels,allauth] @ git+https://git.impactsoundworks.com/isw/djarea.git#subdirectory=django"
```

## Setup

```python
# settings.py
INSTALLED_APPS = ["djarea", ...]

# urls.py
path("api/djarea/", include("djarea.urls"))

# asgi.py (optional, for WebSocket)
from djarea import wrap_asgi
application = wrap_asgi(get_asgi_application())
```

## Define Functions

```python
from djarea.client import client
from djarea.setup.registry import register
from pydantic import BaseModel

class Output(BaseModel):
    message: str

@client
def echo(request, text: str) -> Output:
    return Output(message=text)

register(echo, "echo")
```

Register in `apps.py`:

```python
def ready(self):
    import myapp.djarea_clients
```

## Auth

```python
@client(auth=True)          # requires authentication
@client(auth='staff')       # requires is_staff
@client(auth='superuser')   # requires is_superuser
@client(auth=my_callable)   # custom check
```

## Contexts

```python
@client(context='global')   # fetched once, SSR-hydrated, becomes useCurrentUser()
@client(context='local')    # fetched with params, becomes <GreetProvider>
```

## Forms

```python
from djarea.forms import DjareaFormMixin, DjareaFormMeta

class ContactForm(DjareaFormMixin, forms.Form):
    djarea = DjareaFormMeta(name="contact", title="Contact Us")
    name = forms.CharField()
    email = forms.EmailField()

    def on_submit_success(self, request):
        return {"sent": True}
```

Auto-registers `contact.schema`, `contact.validate`, `contact.submit`. Generates `useContactForm()` with Zod validation.

## Channels

```python
from djarea.channels import ReactChannel

class ChatChannel(ReactChannel):
    class Params(BaseModel):
        room: str
    class DjangoMessage(BaseModel):
        text: str

    def authorize(self, params):
        return self.user.is_authenticated
    def group(self, params):
        return f"chat_{params.room}"
```

Generates `useChatChannel({ room })`.

## Running Tests

```bash
uv sync --extra dev --extra channels
uv run pytest
```