| Name | dash-pydantic-form JSON |
| Version |
0.7.1
JSON |
| download |
| home_page | None |
| Summary | Create Dash forms from pydantic objects |
| upload_time | 2024-10-22 00:36:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.13,>=3.10 |
| license | The MIT License (MIT) Copyright (c) 2023 Plotly, Inc Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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](https://pydf-docs.onrender.com).
Check out a full self-standing example app in [usage.py](usage.py).
## Getting started
Install with pip
```sh
pip install dash-pydantic-form
```
Create a pydantic model you would like to display a form for.
*Note: This package uses pydantic 2.*
```py
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](https://dash-mantine-components.com) (version 0.14) for form inputs.
```py
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
```py
# 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
```py
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.
```py
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": {"maxDate": "2024-01-01"},
},
)
```
You can also customise inputs by adding arguments to the fields' json_schema_extra if you don't mind mixing data and presentation layers.
```py
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",
description="Wich country office?",
# Use repr_type to change the default field used
json_schema_extra={"repr_type": "RadioItems"},
)
joined: date = Field(
title="Employment date",
# Use repr_kwargs to pass default keyword arguments to the field
json_schema_extra={"repr_kwargs": {"maxDate": "2024-01-01"}},
)
form = ModelForm(Employee, aio_id="employees", form_id="new_employee")
```
Note: You can currently skip the `json_schema_extra=...` and just pass `repr_type=..., repr_kwargs=...` in the field. However, the `**extras` keyword arguments are deprecated on pydantic's `Field` so using `json_schema_extra` is more future-proof.
### List of current field inputs:
Based on DMC:
* Checkbox
* Checklist
* Color
* Date
* Json
* Month
* MultiSelect
* Number
* Password
* RadioItems
* Range
* Rating
* SegmentedControl
* Select
* Slider
* Switch
* Tags
* Textarea
* Text
* Time
* Year
Custom:
* Dict
* Table
* List
* Markdown
* Model
* Quantity
* TransferList
## Creating sections
There are 2 main avenues to create form sections:
### 1. Create a submodel in one of the model fields
```py
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
```py
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. List
This creates a list of sub-forms each of which can take similar arguments as a ModelForm (fields_repr, sections).
```py
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.List(
fields_repr={
"species": {"options_labels": {"cat": "Cat", "dog": "Dog"}}
},
# 3 render_type options: accordion, list or modal
render_type="accordion",
)
},
)
```
### 2. Table
You can also represent the list of sub-models as an ag-grid table with `fields.Table`.
```py
form = ModelForm(
Employee,
aio_id="employees",
form_id="new_employee",
fields_repr={
"pets": fields.Table(
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.
```py
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](https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions-with-str-discriminators)
```py
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*
Raw data
{
"_id": null,
"home_page": null,
"name": "dash-pydantic-form",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Renaud Lain\u00e9 <renaudlaine31@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/34/c4/d5c13d0bc9e4d9890601b8a059de397b122c744e711921f04ea4c61304dc/dash_pydantic_form-0.7.1.tar.gz",
"platform": null,
"description": "# Dash pydantic form\n\nThis package allows users to quickly create forms with Plotly Dash based on pydantic models.\n\nSee the full docs at [dash-pydantic-form docs](https://pydf-docs.onrender.com).\n\nCheck out a full self-standing example app in [usage.py](usage.py).\n\n## Getting started\n\nInstall with pip\n\n```sh\npip install dash-pydantic-form\n```\n\nCreate a pydantic model you would like to display a form for.\n\n*Note: This package uses pydantic 2.*\n\n```py\nfrom datetime import date\nfrom typing import Literal\nfrom pydantic import BaseModel, Field\n\nclass Employee(BaseModel):\n first_name: str = Field(title=\"First name\")\n last_name: str = Field(title=\"Last name\")\n office: Literal[\"au\", \"uk\", \"us\", \"fr\"] = Field(title=\"Office\")\n joined: date = Field(title=\"Employment date\")\n```\n\nThen you can get an auto-generated form with `ModelForm`, leveraging [dash-mantine-components](https://dash-mantine-components.com) (version 0.14) for form inputs.\n\n```py\nfrom dash_pydantic_form import ModelForm\n\n# somewhere in your layout:\nform = ModelForm(\n Employee,\n aio_id=\"employees\",\n form_id=\"new_employee\",\n)\n```\n\n\n\nYou can also render a pre-filled form by passing an instance of the data model rather than the class\n\n```py\n# NOTE: This could come from a database\nbob = Employee(first_name=\"Bob\", last_name=\"K\", office=\"au\", joined=\"2020-05-20\")\n\nform = ModelForm(\n bob,\n aio_id=\"employees\",\n form_id=\"bob\",\n)\n```\n\nYou can then retrieve the contents of the whole form at once in a callback as follows\n\n```py\nfrom dash import Input, Output, callback\n\n@callback(\n Output(\"some-output-id\", \"some-output-attribute\"),\n Input(ModelForm.ids.main(\"employees\", \"new_employee\"), \"data\"),\n)\ndef use_form_data(form_data: dict):\n try:\n print(Employee(**form_data))\n except ValidationError as exc:\n print(\"Could not validate form data:\")\n print(exc.errors())\n return # ...\n```\n\n## Customising inputs\n\nThe `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.\n\n```py\nfrom dash_pydantic_form import ModelfForm, fields\n\nform = ModelForm(\n Employee,\n aio_id=\"employees\",\n form_id=\"new_employee\",\n fields_repr={\n # Change the default from a Select to Radio items\n # NOTE: `description` can be set on pydantic fields as well\n \"office\": fields.RadioItems(description=\"Wich country office?\"),\n # Pass additional props to the default input field\n \"joined\": {\"maxDate\": \"2024-01-01\"},\n },\n)\n```\n\nYou can also customise inputs by adding arguments to the fields' json_schema_extra if you don't mind mixing data and presentation layers.\n\n```py\nclass Employee(BaseModel):\n first_name: str = Field(title=\"First name\")\n last_name: str = Field(title=\"Last name\")\n office: Literal[\"au\", \"uk\", \"us\", \"fr\"] = Field(\n title=\"Office\",\n description=\"Wich country office?\",\n # Use repr_type to change the default field used\n json_schema_extra={\"repr_type\": \"RadioItems\"},\n )\n joined: date = Field(\n title=\"Employment date\",\n # Use repr_kwargs to pass default keyword arguments to the field\n json_schema_extra={\"repr_kwargs\": {\"maxDate\": \"2024-01-01\"}},\n )\n\nform = ModelForm(Employee, aio_id=\"employees\", form_id=\"new_employee\")\n```\n\nNote: You can currently skip the `json_schema_extra=...` and just pass `repr_type=..., repr_kwargs=...` in the field. However, the `**extras` keyword arguments are deprecated on pydantic's `Field` so using `json_schema_extra` is more future-proof.\n\n### List of current field inputs:\n\nBased on DMC:\n* Checkbox\n* Checklist\n* Color\n* Date\n* Json\n* Month\n* MultiSelect\n* Number\n* Password\n* RadioItems\n* Range\n* Rating\n* SegmentedControl\n* Select\n* Slider\n* Switch\n* Tags\n* Textarea\n* Text\n* Time\n* Year\n\nCustom:\n* Dict\n* Table\n* List\n* Markdown\n* Model\n* Quantity\n* TransferList\n\n## Creating sections\n\nThere are 2 main avenues to create form sections:\n\n### 1. Create a submodel in one of the model fields\n\n```py\nclass HRData(BaseModel):\n office: Literal[\"au\", \"uk\", \"us\", \"fr\"] = Field(title=\"Office\")\n joined: date = Field(title=\"Employment date\")\n\nclass EmployeeNested(BaseModel):\n first_name: str = Field(title=\"First name\")\n last_name: str = Field(title=\"Last name\")\n hr_data: HRData = Field(title=\"HR data\")\n```\nModelForm will then recognise HRData as a pydantic model and use the `fields.Model` to render it, de facto creating a section.\n\n\n\n### 2. Pass sections information to ModelForm\n\n```py\nfrom dash_pydantic_form import FormSection, ModelForm, Sections\n\nform = ModelForm(\n Employee,\n aio_id=\"employees\",\n form_id=\"new_employee\",\n sections=Sections(\n sections=[\n FormSection(name=\"General\", fields=[\"first_name\", \"last_name\"], default_open=True),\n FormSection(name=\"HR data\", fields=[\"office\", \"joined\"], default_open=False),\n ],\n # 3 render values are available: accordion, tabs and steps\n render=\"tabs\",\n ),\n)\n```\n\n\n\n## List of nested models\n\nDash pydantic form also handles lists of nested models with the possibility to add/remove items from the list and edit each one.\n\nLet's say we now want to record the employee's pets\n\n### 1. List\n\nThis creates a list of sub-forms each of which can take similar arguments as a ModelForm (fields_repr, sections).\n\n```py\nclass Pet(BaseModel):\n name: str = Field(title=\"Name\")\n species: Literal[\"cat\", \"dog\"] = Field(title=\"Species\")\n age: int = Field(title=\"Age\")\n\nclass Employee(BaseModel):\n first_name: str = Field(title=\"First name\")\n last_name: str = Field(title=\"Last name\")\n pets: list[Pet] = Field(title=\"Pets\", default_factory=list)\n\nform = ModelForm(\n Employee,\n aio_id=\"employees\",\n form_id=\"new_employee\",\n fields_repr={\n \"pets\": fields.List(\n fields_repr={\n \"species\": {\"options_labels\": {\"cat\": \"Cat\", \"dog\": \"Dog\"}}\n },\n # 3 render_type options: accordion, list or modal\n render_type=\"accordion\",\n )\n },\n)\n```\n\n\n\n### 2. Table\n\nYou can also represent the list of sub-models as an ag-grid table with `fields.Table`.\n\n```py\nform = ModelForm(\n Employee,\n aio_id=\"employees\",\n form_id=\"new_employee\",\n fields_repr={\n \"pets\": fields.Table(\n fields_repr={\n \"species\": {\"options_labels\": {\"cat\": \"Cat\", \"dog\": \"Dog\"}}\n },\n )\n },\n)\n```\n\n\n\n\n## Make fields conditionnally visible\n\nYou 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.\n\n```py\nclass Employee(BaseModel):\n first_name: str\n last_name: str\n only_bob: str | None = Field(\n title=\"Only for Bobs\",\n description=\"What's your favourite thing about being a Bob?\",\n default=None,\n )\n\nform = ModelForm(\n Employee,\n aio_id=\"employees\",\n form_id=\"new_employee\",\n fields_repr={\n \"only_bob\": fields.Textarea(\n visible=(\"first_name\", \"==\", \"Bob\"),\n )\n },\n)\n```\n\n\n\n`visible` accepts a boolean, a 3-tuple or list of 3-tuples with format: (field, operator, value). The available operators are:\n* \"==\"\n* \"!=\"\n* \"in\"\n* \"not in\"\n* \"array_contains\"\n* \"array_contains_any\"\n\nNOTE: 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_`.\n\nE.g., `visible=(\"_root_:first_name\", \"==\", \"Bob\")`\n\n## Discriminated unions\n\nDash pydantic form supports Pydantic [discriminated unions with str discriminator](https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions-with-str-discriminators)\n\n```py\nclass HomeOffice(BaseModel):\n \"\"\"Home office model.\"\"\"\n\n type: Literal[\"home_office\"]\n has_workstation: bool = Field(title=\"Has workstation\", description=\"Does the employee have a suitable workstation\")\n\n\nclass WorkOffice(BaseModel):\n \"\"\"Work office model.\"\"\"\n\n type: Literal[\"work_office\"]\n commute_time: int = Field(title=\"Commute time\", description=\"Commute time in minutes\", ge=0)\n\nclass Employee(BaseModel):\n name: str = Field(title=\"Name\")\n work_location: HomeOffice | WorkOffice | None = Field(\"Work location\", default=None, discriminator=\"type\")\n\nform = ModelForm(\n Employee,\n aio_id=\"employees\",\n form_id=\"new_employee\",\n fields_repr={\n \"work_location\": {\n \"fields_repr\": {\n \"type\": fields.RadioItems(\n options_labels={\"home_office\": \"Home\", \"work_office\": \"Work\"}\n )\n },\n },\n }\n)\n```\n\n\n\n## Creating custom fields\n\n*To be written*\n",
"bugtrack_url": null,
"license": "The MIT License (MIT) Copyright (c) 2023 Plotly, Inc Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Create Dash forms from pydantic objects",
"version": "0.7.1",
"project_urls": {
"Homepage": "https://pydf-docs.onrender.com",
"Source": "https://github.com/RenaudLN/dash-pydantic-form"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cbdefa393aa71a1812f5403d27a11825a6f15bbe4046ab5eab7199e40bdb0815",
"md5": "9a3c4c13d26b242ba34570dd17e3f7f2",
"sha256": "e36ef21fc24ab0c9d88041502e543dfd7d50d03c6230c87314c509fad29e5aa1"
},
"downloads": -1,
"filename": "dash_pydantic_form-0.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a3c4c13d26b242ba34570dd17e3f7f2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 165314,
"upload_time": "2024-10-22T00:36:51",
"upload_time_iso_8601": "2024-10-22T00:36:51.310538Z",
"url": "https://files.pythonhosted.org/packages/cb/de/fa393aa71a1812f5403d27a11825a6f15bbe4046ab5eab7199e40bdb0815/dash_pydantic_form-0.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "34c4d5c13d0bc9e4d9890601b8a059de397b122c744e711921f04ea4c61304dc",
"md5": "ca8d5d75c03213ee78597b30f31eb85e",
"sha256": "c73d7e376ac0ba412849d618228af34fd89ed35a8f226b29343ef18090c049ee"
},
"downloads": -1,
"filename": "dash_pydantic_form-0.7.1.tar.gz",
"has_sig": false,
"md5_digest": "ca8d5d75c03213ee78597b30f31eb85e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 161430,
"upload_time": "2024-10-22T00:36:53",
"upload_time_iso_8601": "2024-10-22T00:36:53.280747Z",
"url": "https://files.pythonhosted.org/packages/34/c4/d5c13d0bc9e4d9890601b8a059de397b122c744e711921f04ea4c61304dc/dash_pydantic_form-0.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 00:36:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RenaudLN",
"github_project": "dash-pydantic-form",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dash-pydantic-form"
}
