dash-pydantic-form 0.1.1__tar.gz

dash_pydantic_form-0.1.1/.gitignore

@@ -0,0 +1,166 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Terraform - .terraform* matches the local .lock.hcl files and modules that we do not want to export to git
+.terraform*
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+*.ipynb
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+.vscode/settings.json

dash_pydantic_form-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.1
+    hooks:
+      - id: ruff
+        args: [ --fix ]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer

dash_pydantic_form-0.1.1/.vscode/launch.json

@@ -0,0 +1,28 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Flask",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "flask",
+            "env": {
+                "FLASK_APP": "usage.py:server",
+                "FLASK_DEBUG": "1",
+                "REACT_VERSION": "18.2.0",
+                "DEBUG": "1",
+            },
+            "args": [
+                "run",
+                "--no-debugger",
+                "--no-reload"
+            ],
+            "jinja": true,
+            "autoStartBrowser": false,
+            "justMyCode": false
+        }
+    ]
+}

dash_pydantic_form-0.1.1/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [0.1.0] - 2022-10-27
+### Added
+- Working initial version

dash_pydantic_form-0.1.1/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.1
+Name: dash-pydantic-form
+Version: 0.1.1
+Summary: Create Dash forms from pydantic objects
+Author-email: Renaud Lainé <renaud.laine@enea-consulting.com>
+License: Copyright ENEA Australia Pty Ltd - All Rights Reserved. Proprietary and confidential
+Project-URL: Source, https://github.com/RenaudLN/dash-pydantic-form
+Requires-Python: <3.11,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: dash
+Requires-Dist: dash_mantine_components>=0.14
+Requires-Dist: dash_iconify
+Requires-Dist: dash_ag_grid
+Requires-Dist: pandas
+Requires-Dist: pydantic==2.*
+Requires-Dist: flatdict
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# Dash pydantic form
+
+This package allows users to quickly create forms with Plotly Dash based on pydantic models.
+
+## Getting started
+
+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) for form inputs.
+
+```py
+from dash_pydantic_form import ModelForm
+
+# somewhere in your layout:
+form = ModelForm(
+    Employee,
+    aio_id="employees",
+    form_id="new_employee",
+)
+```
+
+![Simple form](images/simple-form.png)
+
+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": {"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
+
+```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.
+
+![Nested model](images/nested-model.png)
+
+### 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",
+    ),
+)
+```
+
+![Form sections](images/form-sections.png)
+
+## 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).
+
+```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.ModelList(
+            fields_repr={
+                "species": {"options_labels": {"cat": "Cat", "dog": "Dog"}}
+            },
+            # 3 render_type options: accordion, list or modal
+            render_type="accordion",
+        )
+    },
+)
+```
+
+![ModelList](images/model-list.png)
+
+### 2. EditableTable
+
+You can also represent the list of sub-models as an ag-grid table with `fields.EditableTable`.
+
+```py
+form = ModelForm(
+    Employee,
+    aio_id="employees",
+    form_id="new_employee",
+    fields_repr={
+        "pets": fields.EditableTable(
+            fields_repr={
+                "species": {"options_labels": {"cat": "Cat", "dog": "Dog"}}
+            },
+        )
+    },
+)
+```
+
+![EditableTable](images/editable-table.png)
+
+
+## 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"),
+        )
+    },
+)
+```
+
+![Conditionnally visible field](images/conditionnally-visible-field.gif)
+
+`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")`
+
+## Creating custom fields
+
+*To be written*