Reference¶
Every public module, listed in full. See Usage and How it works for the explanations behind them.
Forms¶
Bases: pydantic.BaseModel
class-attribute
instance-attribute
model_config = pydantic.ConfigDict(arbitrary_types_allowed=True, title='unknown', extra='forbid', validate_default=True)
class-attribute
meta__: pydantic_forms.types.JSON = None
Data about the page itself, passed to the frontend alongside its JSON schema.
Set it on a subclass to tell the frontend something the schema cannot express, such as whether
another page follows. It travels out as the meta key of the FormNotCompleteError response.
Being a ClassVar it is not a form field, so it stays out of the schema and the validated result.
list_forms() -> list[str]
register_form(key: str, form: typing.Callable) -> None
generate_form(form_generator: typing.Union[pydantic_forms.types.StateInputFormGenerator, None], state: pydantic_forms.types.State, user_inputs: list[pydantic_forms.types.State], lang: str = 'en_US', extra_translations: typing.Union[dict[str, str], None] = None) -> Union[State, None]
Generate form using form generator as defined by a form definition.
post_form(form_generator: typing.Union[pydantic_forms.types.StateInputFormGenerator, None], state: pydantic_forms.types.State, user_inputs: list[pydantic_forms.types.State], locale: str = 'en_US', extra_translations: typing.Union[dict[str, str], None] = None) -> State
Post user_input based ond serve a new form if the form wizard logic dictates it.
start_form(form_key: str, user_inputs: typing.Union[list[pydantic_forms.types.State], None] = None, user: str = 'Just a user', locale: str = 'en_US', extra_translations: typing.Union[dict[str, str], None] = None, **extra_state: dict[str, typing.Any]) -> State
Handle the logic for the endpoint that the frontend uses to render a form with or without prefilled input.
Args:
form_key: name of form in the FORM dict
user_inputs: List of form inputs from frontend
user: User who starts this form
locale: Language of the form
extra_translations: Extra translations to apply to the form
extra_state: Optional initial state variables
Returns:
The data that the user entered into the form
Async variants¶
async
generate_form(form_generator: typing.Union[pydantic_forms.types.StateInputFormGeneratorAsync, None], state: pydantic_forms.types.State, user_inputs: list[pydantic_forms.types.State], locale: str = 'en_US', extra_translations: typing.Union[dict[str, str], None] = None) -> Union[State, None]
Generate form using form generator as defined by a form definition.
async
post_form(form_generator: typing.Union[pydantic_forms.types.StateInputFormGeneratorAsync, None], state: pydantic_forms.types.State, user_inputs: list[pydantic_forms.types.State], locale: str = 'en_US', extra_translations: typing.Union[dict[str, str], None] = None) -> State
Post user_input based ond serve a new form if the form wizard logic dictates it.
async
start_form(form_key: str, user_inputs: typing.Union[list[pydantic_forms.types.State], None] = None, user: str = 'Just a user', locale: str = 'en_US', extra_translations: typing.Union[dict[str, str], None] = None, **extra_state: typing.Any) -> State
Handle the logic for the endpoint that the frontend uses to render a form with or without prefilled input.
Args:
form_key: name of form in the FORM dict
user_inputs: List of form inputs from frontend
user: User who starts this form
locale: Language of the form
extra_translations: Extra translations to apply to the form
extra_state: Optional initial state variables
Returns:
The data that the user entered into the form
Field types¶
module-attribute
Callout = pydantic_forms.validators.components.callout._Callout
A callout box. Use callout() to set its content and styling.
module-attribute
ContactPersonName = str
A string tagged so the frontend renders it as a contact person name.
module-attribute
DisplaySubscription = uuid.UUID
Displays a subscription, identified by UUID. Display-only: it collects no input.
Deprecated: use orchestrator.forms.validators.DisplaySubscription instead.
module-attribute
Divider = typing.Optional[str]
A horizontal separator line. Display-only: it collects no input.
module-attribute
Hidden = typing.Optional[str]
A field that is not shown to the user. Display-only: it collects no input.
module-attribute
Label = typing.Optional[str]
A plain string formatted as a label. Display-only: it collects no input.
module-attribute
ListOfOne = list[pydantic_forms.validators.components.unique_constrained_list.T]
A list constrained to exactly one item.
module-attribute
ListOfTwo = list[pydantic_forms.validators.components.unique_constrained_list.T]
A list constrained to exactly two items, which must differ from each other.
module-attribute
LongText = str
A multi-line text input.
module-attribute
Markdown = pydantic_forms.validators.components.markdown._Markdown
A block of rendered Markdown. Use markdown() to set its content.
module-attribute
MigrationSummary = pydantic_forms.validators.components.migration_summary._MigrationSummary
A static summary table. Use migration_summary() to supply its data.
module-attribute
OrganisationId = str
A string tagged for organisation-ID rendering.
Deprecated: use orchestrator.forms.validators.CustomerId instead.
module-attribute
Timestamp = pydantic_forms.validators.components.timestamp.timestamp()
A date/time picker with default settings. Use timestamp() to configure it.
Bases: str
A checklist the user works through before the form can be submitted.
Validation fails while the value is still "INCOMPLETE". Subclass it and set data to
describe the items to display.
class-attribute
data: typing.Optional[pydantic_forms.types.AcceptData] = None
classmethod
enum_validator(v: typing.Any) -> str
classmethod
must_be_complete(v: str) -> bool
Bases: pydantic_forms.types.strEnum
class-attribute
instance-attribute
ACCEPTED = 'ACCEPTED'
class-attribute
instance-attribute
INCOMPLETE = 'INCOMPLETE'
Bases: pydantic_forms.types.strEnum
Let the user choose from an enum, showing a label that may differ from the stored value.
Each member is a (value, label) pair: the value is what the form submits, the label is what
the frontend displays. A member declared without a label uses its value for both.
As of March 2023 mypy does not yet support functional API on Enum subclasses https://github.com/python/mypy/issues/6037
This means that: MyChoice1 = Choice(“MyChoice1”, {“option1”: “value1”, “option2”: “value2”})
Will result in the (invalid) mypy error error: Argument 2 to “Choice” has incompatible type “Dict[str, str]”; expected “Optional[str]” [arg-type]
Because it maps to Choice.new instead of Enum.call
Workaround is to be explicit: MyChoice1 = Choice.call(“MyChoice1”, {“option1”: “value1”, “option2”: “value2”})
class-attribute
label: str
Bases: pydantic.BaseModel
instance-attribute
name: pydantic_forms.validators.components.contact_person.ContactPersonName
instance-attribute
email: pydantic.EmailStr
class-attribute
instance-attribute
phone: str = ''
callout(*, header: typing.Union[str, None] = None, message: typing.Union[str, None] = None, icon_type: typing.Union[str, None] = 'info', message_type: typing.Union[pydantic_forms.validators.components.callout.CalloutMessageType, str] = CalloutMessageType.PRIMARY) -> type[Callout]
Create a callout box.
message_type selects the styling and accepts a CalloutMessageType: primary, success,
warning, danger or accent. icon_type names the icon to show, and defaults to "info".
choice_list(item_type: type[pydantic_forms.validators.components.choice.Choice], *, min_items: typing.Optional[int] = None, max_items: typing.Optional[int] = None, unique_items: typing.Optional[bool] = None) -> type[list[Choice]]
Create a multi-select list of Choice values.
contact_person_list(organisation: typing.Optional[uuid.UUID] = None, organisation_key: typing.Optional[str] = 'organisation', min_items: typing.Optional[int] = None, max_items: typing.Optional[int] = None) -> type[list[T]]
Create a list of ContactPerson entries.
Deprecated: use orchestrator.forms.validators.customer_contact_list instead.
markdown(*, content: typing.Union[str, None] = None, color: typing.Union[pydantic_forms.validators.components.markdown.MarkdownColor, str] = MarkdownColor.PRIMARY) -> type[Markdown]
Create a block of rendered Markdown.
color accepts a MarkdownColor: primary, success, warning, danger or accent.
migration_summary(data: pydantic_forms.types.SummaryData) -> type[MigrationSummary]
Create a static table from a {headers, labels, columns} mapping.
read_only_field(default: typing.Any, merge_type: typing.Any | None = None) -> Any
Create type with json schema that sets frontend form field to active=false.
Args:
default(Any): value to display as inactive field on form
merge_type(Any | None): merge another pydantic_form type for this field
Returns:
type annotation which will submit json schema with active=false to uniforms
read_only_list(default: list[typing.Any] | None = None) -> Any
Create type with json schema of type array that is ‘read only’.
timestamp(show_time_select: typing.Optional[bool] = True, locale: typing.Optional[str] = None, validate: bool = True, min: typing.Optional[int] = None, max: typing.Optional[int] = None, date_format: typing.Optional[str] = None, time_format: typing.Optional[str] = None) -> Any
Create a date/time picker, backed by an int holding a unix timestamp.
Pass validate=False to emit the widget bounds without enforcing min/max on the value.
This can be useful to implement custom validation error messages while still having the same
UI representation.
unique_conlist(item_type: type[pydantic_forms.validators.components.unique_constrained_list.T], *, min_items: typing.Optional[int] = None, max_items: typing.Optional[int] = None) -> type[list[T]]
Create a list whose items must all be unique.
validate_unique_list(values: list[pydantic_forms.validators.components.unique_constrained_list.T]) -> list[T]
Return the list unchanged, raising PydanticCustomError if it holds duplicates.
Exceptions¶
module-attribute
Loc = tuple[typing.Union[int, str], ...]
Bases: Exception
Bases: pydantic_forms.exceptions.FormException
Raised when fewer inputs are provided than the form can process.
This exception is part of the normal forms workflow.
instance-attribute
form: pydantic_forms.types.JSON = pydantic_forms.exceptions.FormNotCompleteError(form)
instance-attribute
meta: typing.Optional[pydantic_forms.types.JSON] = pydantic_forms.exceptions.FormNotCompleteError(meta)
Bases: pydantic_forms.exceptions.FormException
Raised when more inputs are provided than the form can process.
Bases: pydantic_forms.exceptions.FormException
Raised when the requested form key is not registered.
Bases: pydantic_forms.exceptions.FormException
instance-attribute
validator_name: str = pydantic_forms.exceptions.FormValidationError(validator_name)
instance-attribute
errors: list[pydantic_core.ErrorDetails] = list(pydantic_forms.exceptions.convert_errors(pydantic_forms.exceptions.FormValidationError(error), pydantic_forms.exceptions.FormValidationError(tr), pydantic_forms.exceptions.FormValidationError(locale)))
Bases: pydantic_forms.exceptions._ErrorDictRequired
instance-attribute
ctx: dict[str, typing.Any]
convert_errors(validation_error: pydantic.ValidationError, tr: pydantic_i18n.PydanticI18n, locale: str = 'en_US') -> Iterable[ErrorDetails]
Convert Pydantic’s error messages to our needs.
https://docs.pydantic.dev/2.4/errors/errors/#customize-error-messages
display_errors(errors: list[pydantic_forms.exceptions.ErrorDict]) -> str
show_ex(ex: Exception, stacklimit: typing.Union[int, None] = None) -> str
Show an exception, including its class name, message and (limited) stacktrace.
Examples:
>>> try:
... raise Exception("Something went wrong")
... except Exception as e:
... print(show_ex(e))
Exception: Something went wrong
...
Types¶
module-attribute
union_types = [typing.Union, types.UnionType]
module-attribute
UUIDstr = str
module-attribute
State = dict[str, typing.Any]
module-attribute
JSON = typing.Any
module-attribute
InputForm = typing.Type[pydantic.main.BaseModel]
module-attribute
AcceptData = list[typing.Union[tuple[str, pydantic_forms.types.AcceptItemType], tuple[str, pydantic_forms.types.AcceptItemType, dict]]]
module-attribute
T = typing.TypeVar('T', bound=pydantic.main.BaseModel)
module-attribute
FormGenerator = typing.Generator[typing.Type[pydantic_forms.types.T], pydantic_forms.types.T, pydantic_forms.types.State]
module-attribute
SimpleInputFormGenerator = typing.Callable[..., pydantic_forms.types.InputForm]
module-attribute
InputFormGenerator = typing.Callable[..., pydantic_forms.types.FormGenerator]
module-attribute
InputStepFunc = typing.Union[pydantic_forms.types.SimpleInputFormGenerator, pydantic_forms.types.InputFormGenerator]
module-attribute
StateSimpleInputFormGenerator = typing.Callable[[pydantic_forms.types.State], pydantic_forms.types.InputForm]
module-attribute
StateInputFormGenerator = typing.Callable[[pydantic_forms.types.State], pydantic_forms.types.FormGenerator]
module-attribute
StateInputStepFunc = typing.Union[pydantic_forms.types.StateSimpleInputFormGenerator, pydantic_forms.types.StateInputFormGenerator]
module-attribute
SubscriptionMapping = dict[str, list[dict[str, str]]]
module-attribute
FormGeneratorAsync = typing.AsyncGenerator[typing.Union[typing.Type[pydantic_forms.types.T], pydantic_forms.types.State], pydantic_forms.types.T]
module-attribute
StateInputFormGeneratorAsync = typing.Callable[[pydantic_forms.types.State], pydantic_forms.types.FormGeneratorAsync]
Bases: pydantic_forms.types.strEnum
class-attribute
instance-attribute
INFO = 'info'
class-attribute
instance-attribute
LABEL = 'label'
class-attribute
instance-attribute
WARNING = 'warning'
class-attribute
instance-attribute
URL = 'url'
class-attribute
instance-attribute
CHECKBOX = 'checkbox'
class-attribute
instance-attribute
SUBCHECKBOX = '>checkbox'
class-attribute
instance-attribute
OPTIONAL_CHECKBOX = 'checkbox?'
class-attribute
instance-attribute
OPTIONAL_SUBCHECKBOX = '>checkbox?'
class-attribute
instance-attribute
SKIP = 'skip'
class-attribute
instance-attribute
VALUE = 'value'
class-attribute
instance-attribute
MARGIN = 'margin'
Bases: typing_extensions.TypedDict
instance-attribute
headers: list[str]
instance-attribute
labels: list[str]
instance-attribute
columns: list[list[typing.Union[str, int, bool, float]]]
FastAPI exception handler¶
async
form_error_handler(request: fastapi.requests.Request, exc: pydantic_forms.exceptions.FormException) -> JSONResponse
FastAPI exception handler that turns a FormException into a HTTP 4xx/5xx response with JSON body.