Create Dash forms from pydantic objects
Project description
Dash pydantic form
This package allows users to quickly create forms with Plotly Dash based on pydantic models.
See the full docs at dash-pydantic-form docs.
Check out a full self-standing example app in usage.py.
Getting started
Install with pip
pip install dash-pydantic-form
Create a pydantic model you would like to display a form for.
Note: This package uses pydantic 2.
from datetime import date
from typing import Literal
from pydantic import BaseModel, Field
class Employee(BaseModel):
first_name: str = Field(title="First name")
last_name: str = Field(title="Last name")
office: Literal["au", "uk", "us", "fr"] = Field(title="Office")
joined: date = Field(title="Employment date")
Then you can get an auto-generated form with ModelForm
, leveraging dash-mantine-components (version 0.14) for form inputs.
from dash_pydantic_form import ModelForm
# somewhere in your layout:
form = ModelForm(
Employee,
aio_id="employees",
form_id="new_employee",
)
You can also render a pre-filled form by passing an instance of the data model rather than the class
# NOTE: This could come from a database
bob = Employee(first_name="Bob", last_name="K", office="au", joined="2020-05-20")
form = ModelForm(
bob,
aio_id="employees",
form_id="bob",
)
You can then retrieve the contents of the whole form at once in a callback as follows
from dash import Input, Output, callback
@callback(
Output("some-output-id", "some-output-attribute"),
Input(ModelForm.ids.main("employees", "new_employee"), "data"),
)
def use_form_data(form_data: dict):
try:
print(Employee(**form_data))
except ValidationError as exc:
print("Could not validate form data:")
print(exc.errors())
return # ...
Customising inputs
The ModelForm
will automaticlly pick which input type to use based on the type annotation for the model field. However, you can customise how each field input is rendered, and or pass additional props to the DMC component.
from dash_pydantic_form import ModelfForm, fields
form = ModelForm(
Employee,
aio_id="employees",
form_id="new_employee",
fields_repr={
# Change the default from a Select to Radio items
# NOTE: `description` can be set on pydantic fields as well
"office": fields.RadioItems(description="Wich country office?"),
# Pass additional props to the default input field
"joined": {"input_kwargs": {"maxDate": "2024-01-01"}},
},
)
List of current field inputs:
Based on DMC:
- Checkbox
- Checklist
- Color
- Date
- Json
- MultiSelect
- Number
- Password
- RadioItems
- Range
- SegmentedControl
- Select
- Slider
- Switch
- Textarea
- Text
- Time
Custom:
- EditableTable
- Model
- ModelList
Creating sections
There are 2 main avenues to create form sections:
1. Create a submodel in one of the model fields
class HRData(BaseModel):
office: Literal["au", "uk", "us", "fr"] = Field(title="Office")
joined: date = Field(title="Employment date")
class EmployeeNested(BaseModel):
first_name: str = Field(title="First name")
last_name: str = Field(title="Last name")
hr_data: HRData = Field(title="HR data")
ModelForm will then recognise HRData as a pydantic model and use the fields.Model
to render it, de facto creating a section.
2. Pass sections information to ModelForm
from dash_pydantic_form import FormSection, ModelForm, Sections
form = ModelForm(
Employee,
aio_id="employees",
form_id="new_employee",
sections=Sections(
sections=[
FormSection(name="General", fields=["first_name", "last_name"], default_open=True),
FormSection(name="HR data", fields=["office", "joined"], default_open=False),
],
# 3 render values are available: accordion, tabs and steps
render="tabs",
),
)
List of nested models
Dash pydantic form also handles lists of nested models with the possibility to add/remove items from the list and edit each one.
Let's say we now want to record the employee's pets
1. ModelList
This creates a list of sub-forms each of which can take similar arguments as a ModelForm (fields_repr, sections).
class Pet(BaseModel):
name: str = Field(title="Name")
species: Literal["cat", "dog"] = Field(title="Species")
age: int = Field(title="Age")
class Employee(BaseModel):
first_name: str = Field(title="First name")
last_name: str = Field(title="Last name")
pets: list[Pet] = Field(title="Pets", default_factory=list)
form = ModelForm(
Employee,
aio_id="employees",
form_id="new_employee",
fields_repr={
"pets": fields.ModelList(
fields_repr={
"species": {"options_labels": {"cat": "Cat", "dog": "Dog"}}
},
# 3 render_type options: accordion, list or modal
render_type="accordion",
)
},
)
2. EditableTable
You can also represent the list of sub-models as an ag-grid table with fields.EditableTable
.
form = ModelForm(
Employee,
aio_id="employees",
form_id="new_employee",
fields_repr={
"pets": fields.EditableTable(
fields_repr={
"species": {"options_labels": {"cat": "Cat", "dog": "Dog"}}
},
)
},
)
Make fields conditionnally visible
You can make field visibility depend on the value of other fields in the form. To do so, simply pass a visible
argument to the field.
class Employee(BaseModel):
first_name: str
last_name: str
only_bob: str | None = Field(
title="Only for Bobs",
description="What's your favourite thing about being a Bob?",
default=None,
)
form = ModelForm(
Employee,
aio_id="employees",
form_id="new_employee",
fields_repr={
"only_bob": fields.Textarea(
visible=("first_name", "==", "Bob"),
)
},
)
visible
accepts a boolean, a 3-tuple or list of 3-tuples with format: (field, operator, value). The available operators are:
- "=="
- "!="
- "in"
- "not in"
- "array_contains"
- "array_contains_any"
NOTE: The field in the 3-tuples is a ":" separated path relative to the current field's level of nesting. If you need to reference a field from a parent or the root use the special values _parent_
or _root_
.
E.g., visible=("_root_:first_name", "==", "Bob")
Discriminated unions
Dash pydantic form supports Pydantic discriminated unions with str discriminator
class HomeOffice(BaseModel):
"""Home office model."""
type: Literal["home_office"]
has_workstation: bool = Field(title="Has workstation", description="Does the employee have a suitable workstation")
class WorkOffice(BaseModel):
"""Work office model."""
type: Literal["work_office"]
commute_time: int = Field(title="Commute time", description="Commute time in minutes", ge=0)
class Employee(BaseModel):
name: str = Field(title="Name")
work_location: HomeOffice | WorkOffice | None = Field("Work location", default=None, discriminator="type")
form = ModelForm(
Employee,
aio_id="employees",
form_id="new_employee",
fields_repr={
"work_location": {
"fields_repr": {
"type": fields.RadioItems(
options_labels={"home_office": "Home", "work_office": "Work"}
)
},
},
}
)
Creating custom fields
To be written
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for dash_pydantic_form-0.1.14-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f77a18a31b816754749d87ef3169eda391821278895961af60f3bd059eb7b1f4 |
|
MD5 | 6d31200d39627bd0c4b897135792033e |
|
BLAKE2b-256 | 3aaac58bb543a3919aeb2893ab2d6d551a59b76b312a887c31037958ac8510b7 |