# Inputs

> How type hints become form fields: text, numbers, dropdowns, dates, lists, models and file uploads.

Source: https://callables.app/docs/inputs

A function's parameters become its form. The type hint picks the field, the default prefills it, and the parameter name becomes the label.

```python
from datetime import date
from typing import Literal

from callables import deploy


@deploy(title="Closed deals")
def closed_deals(
    region: Literal["NA", "EMEA", "APAC"] = "NA",
    since: date | None = None,
    min_value: int = 0,
    include_refunds: bool = False,
) -> list[dict]: ...
```

This form has a dropdown, an optional date picker, a number field and a checkbox.

## Type hints and fields

| Type hint | Form field |
|---|---|
| `str` | Text box |
| `int`, `float` | Number |
| `bool` | Checkbox |
| `date`, `datetime` | Date or date-time picker |
| `Literal["a", "b"]` or an `Enum` | Dropdown |
| `list[str]`, `list[int]` and so on | List editor |
| `X \| None = None` | Optional field |
| A Pydantic model | Grouped sub-form |
| `File`, or `Annotated[File, accept(".csv")]` | File upload |

## Required and optional

- A parameter without a default is required.
- A default makes the field optional and prefills it.
- `X | None = None` is an optional field that starts empty.

## Labels

Parameter names become labels: `min_value` shows as "Min value". Choose names that read well to the people running the function.

## Validation

Inputs are validated and converted before your function runs, the same way in the web app, from the CLI and in `call local`. A `date` arrives as a `datetime.date`, an `Enum` as its member and a model as an instance. Invalid input is shown next to its field, and the function isn't called.

## Models

Group related fields with a Pydantic model:

```python
from pydantic import BaseModel

from callables import deploy


class Address(BaseModel):
    street: str
    city: str
    postcode: str


@deploy(title="Update shipping address")
def update_address(order_id: str, address: Address) -> str: ...
```

## Good practice

- Prefer `Literal[...]` over free text whenever the valid values are known.
- Avoid `dict` inputs: they show as a raw JSON box. Use a Pydantic model instead.
- Never take an API key or password as an input. Declare it as a [secret](https://callables.app/docs/secrets).

## Not supported

`*args`, `**kwargs`, `Callable` and arbitrary classes. `call check` names any parameter it can't turn into a field.

For file uploads, see [files](https://callables.app/docs/files).