Skip to content

gavicore.ui API Reference

gavicore.ui - Field API

gavicore.ui.Field

Bases: ABC, Generic[VT]

A binding unit between data, represented by property view_model, and a concrete piece of typically data-bound UI, represented by the view property of type T, such as a widget, panel, control.

meta property 

meta: FieldMeta

The field metadata.

view_model abstractmethod property 

view_model: ViewModel

The view model used by this field.

view abstractmethod property 

view: VT

The view used by this field.

gavicore.ui.FieldBase 

FieldBase(view_model: ViewModel, view: VT)

Bases: Field[VT], ABC, Generic[VT]

Abstract base class for UI fields.

meta property 

meta: FieldMeta

The field metadata.

gavicore.ui.FieldContext 

FieldContext(
    *,
    generator: FieldGenerator[FT, VT],
    meta: FieldMeta,
    initial_value: Any | Undefined = Undefined.value,
    label_hidden: bool = False,
    hidden_prop_name: str | None = None,
    parent_ctx: FieldContext[FT, VT] | None = None
)

Bases: Generic[FT, VT]

The context object passed to a UI field factory.

meta property 

meta: FieldMeta

The field metadata.

name property 

name: str

The name from field metadata.

label_hidden property 

label_hidden: bool

A flag indicating that the label for the field should not be shown.

label property 

label: str

A label for the field. It is an empty string if the label_hidden flag is set.

schema property 

schema: Schema

The OpenAPI Schema from field metadata.

vm property 

vm: ViewModelFactory

The view model factory.

initial_value property 

initial_value: Any

An initial value.

path property 

path: list[str]

The path of this field context as list of field names.

layout 

layout(layout_function: LayoutFunction, views: dict[str, VT]) -> VT

Lay out the given views using the field metadata's layout property.

create_property_fields 

create_property_fields() -> dict[str, FT]

Create property fields given that this context's field is of type "object".

create_item_field 

create_item_field(label_hidden: bool = False) -> FT

Create a new item field given that this context's field is of type "array".

create_child_field 

create_child_field(
    child_meta: FieldMeta,
    label_hidden: bool = False,
    hidden_prop_name: str | None = None,
) -> FT

Create a new field for the given child field metadata.

gavicore.ui.FieldFactory

Bases: ABC, Generic[FT]

Field factories are used to create UI fields from field metadata and other context data. The applicability of a factory for given field metadata is determined by an integer score value.

get_score abstractmethod 

get_score(meta: FieldMeta) -> int

Get the score of this factory for the given field metadata. The score is proportional to the factory's ability to create a field for the field metadata. A negative or zero score indicates complete inability.

create_field abstractmethod 

create_field(ctx: FieldContext) -> FT

Create the UI field for the given field context.

gavicore.ui.FieldFactoryBase

Bases: FieldFactory[FT], ABC, Generic[FT]

A convenient base class for UI field factories that create UI fields based on the schema data type.

You need to override one or more of the get_{type}_score() methods and return a value greater than zero. By default, all get_{type}_score() return zero.

Make sure to also implement any create_{type}_field() method for which get_{type}_score() returns a value greater than zero. By default, all create_{type}_field() raise a NotImplementedError.

Nullable fields (ctx.schema.nullable) are handled separately.

get_score 

get_score(meta: FieldMeta) -> int

Get the score for a field based on its data type.

The default implementation delegates to various get_xxx_score() methods that all return 0 when not being overridden.

Note that we do not consider the case not ctx.schema.required, for optional object properties. This must be dealt with in subclasses.

get_nullable_score 

get_nullable_score(meta: FieldMeta) -> int

Get the score for a nullable field.

get_boolean_score 

get_boolean_score(meta: FieldMeta) -> int

Get the score for a field of type "boolean".

get_integer_score 

get_integer_score(meta: FieldMeta) -> int

Get the score for a field of type "integer".

get_number_score 

get_number_score(meta: FieldMeta) -> int

Get the score for a field of type "number".

get_string_score 

get_string_score(meta: FieldMeta) -> int

Get the score for a field of type "string".

get_array_score 

get_array_score(meta: FieldMeta) -> int

Get the score for a field of type "array".

get_object_score 

get_object_score(meta: FieldMeta) -> int

Get the score for a field of type "object".

get_one_of_score 

get_one_of_score(meta: FieldMeta) -> int

Get the score for a schema that defines 'oneOf'.

get_any_of_score 

get_any_of_score(meta: FieldMeta) -> int

Get the score for a schema that defines 'anyOf'.

get_all_of_score 

get_all_of_score(meta: FieldMeta) -> int

Get the score for a schema that defines 'allOf'.

get_untyped_score 

get_untyped_score(meta: FieldMeta) -> int

Get the score for a field that has no explicit type.

create_field 

create_field(ctx: FieldContext) -> FT

Create a UI field based on its data type.

The default implementation delegates to various create_xxx_field() methods that all raise NotImplementedError when not being overridden.

Note that we do not consider the case not ctx.schema.required, for optional object properties. This must be dealt with in subclasses.

create_nullable_field 

create_nullable_field(ctx: FieldContext) -> FT

Create a UI field for a value that is nullable.

create_boolean_field 

create_boolean_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "boolean".

create_integer_field 

create_integer_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "integer".

create_number_field 

create_number_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "number".

create_string_field 

create_string_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "string".

create_array_field 

create_array_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "array".

create_object_field 

create_object_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "object".

create_one_of_field 

create_one_of_field(ctx: FieldContext) -> FT

Create a UI field for a schema that uses the "oneOf" operator.

create_any_of_field 

create_any_of_field(ctx: FieldContext) -> FT

Create a UI field for a schema that uses the "anyOf" operator.

create_all_of_field 

create_all_of_field(ctx: FieldContext) -> FT

Create a UI field for a schema that uses the "allOf" operator.

create_untyped_field 

create_untyped_field(ctx: FieldContext) -> FT

Create a UI field for a value with no explicit type specified.

gavicore.ui.FieldFactoryRegistry 

FieldFactoryRegistry(*factories: FieldFactory[FT])

Bases: Generic[FT]

A registry of field factories.

factories property 

factories: set[FieldFactory[FT]]

The factories registered in this registry.

register 

register(factory: FieldFactory[FT]) -> Callable[[], None]

Register the given field factory.

Parameters:

Name Type Description Default
factory FieldFactory[FT]

A field factory.

 required

Returns: An callable that can be used to register the added factory.

unregister 

unregister(factory: FieldFactory[FT]) -> None

Unregister a given factory.

lookup 

lookup(meta: FieldMeta) -> FieldFactory[FT] | None

Find a factory for the given field metadata.

gavicore.ui.FieldGenerator 

FieldGenerator(field_factory_registry: FieldFactoryRegistry[FT] | None = None)

Bases: Generic[FT, VT]

Entry point for generating fields and field forms from field metadata.

register_field_factory 

register_field_factory(field_factory: FieldFactory[FT]) -> Callable[[], None]

Register a new field factory.

Parameters:

Name Type Description Default
field_factory FieldFactory[FT]

A field factory.

 required

Returns: A callable that can be used to register the added field factory.

generate_field 

generate_field(
    meta: FieldMeta, initial_value: Any | Undefined = Undefined.value
) -> FT

Generate a field or form from the given field metadata.

Parameters:

Name Type Description Default
meta FieldMeta

The field metadata.

 required
initial_value Any | Undefined

The optional, initial value for the field.

 Undefined.value

Returns: The generated field or form.

gavicore.ui.FieldGroup

Bases: pydantic.BaseModel

Definition of a group of complex UI fields.

Example:

FieldGroup(
    type="row",
    items=[
        FieldGroup(type="column", items=["field_a", "field_b"]),
        FieldGroup(type="column", items=["field_c", "field_d"]),
    ]
)

Items can be other Group objects or the names of the fields that should be part of the layout. Another possibility for a field to join a layout is to set its group_name property to the target group's name. Children of a complex field whose names do not occur in any group of a layout tree and do not have the group property set will be appended to the root group of a layout tree. Their order will be determined by the value of the order property, if any, or the original property order.

gavicore.ui.FieldMeta

Bases: pydantic.BaseModel

Metadata used to generate a GUI field like a widget or panel.

The properties of instances of this class have been collected from a process input/output description, the respective JSON schema, and from dedicated UI-related extension property values.

For example, if a UI should use a dedicated enum value, it could be specified using the property named "x-ui:enum" or as a property "enum" in an object that is the value of the "x-ui" property.

{
    "schema": {"type": "number", "minimum": 0.1},
    "x-ui:enum": [0.1, 0.25, 0.5, 1.0]
}

or

{
    "schema": {"type": "number", "minimum": 0.1},
    "x-ui": {"enum": [0.1, 0.25, 0.5, 1.0]}
}

This class should not be instantiated from its constructor; instead, use one of the factory methods

name instance-attribute 

name: str

The name of the field. This is the name of the corresponding process input/output or property name of object fields.

schema_ class-attribute instance-attribute 

schema_: Schema = pydantic.Field(..., alias='schema')

The original schema from which this metadata was extracted.

properties class-attribute instance-attribute 

properties: dict[str, FieldMeta] | None = None

The metadata of object properties. Set if schema type is "object".

items class-attribute instance-attribute 

items: FieldMeta | None = None

The metadata of array items. Set if schema type is "array".

one_of class-attribute instance-attribute 

one_of: list[FieldMeta] | None = None

The metadata for a schema's "oneOf" element, if given.

any_of class-attribute instance-attribute 

any_of: list[FieldMeta] | None = None

The metadata for a schema's "anyOf" element, if given.

all_of class-attribute instance-attribute 

all_of: list[FieldMeta] | None = None

The metadata for a schema's "allOf" element, if given.

layout class-attribute instance-attribute 

layout: FieldLayout | None = None

Hint to lay out the children of this field.

widget class-attribute instance-attribute 

widget: FieldWidgetType | str | None = None

Hint for the type of widget to be used for this field.

title class-attribute instance-attribute 

title: str | None = None

The title of this field. See also label.

description class-attribute instance-attribute 

description: str | None = None

The description text for this field.

tooltip class-attribute instance-attribute 

tooltip: str | None = None

A tooltip text for this field.

placeholder class-attribute instance-attribute 

placeholder: str | None = None

A placeholder text for this field.

nullable_parent class-attribute instance-attribute 

nullable_parent: bool | None = None

If True, the parent of this field is a nullable field.

group_name class-attribute instance-attribute 

group_name: str | None = None

The name of the group in which this field will occur. See also FieldGroup.

order class-attribute instance-attribute 

order: int | None = None

The order of this field in the group. The order's value is used to compare it against other order values when sorting multiple fields in ascending order. See also FieldGroup.

required class-attribute instance-attribute 

required: bool | None = None

Whether this field originates from a required process input or object property.

password class-attribute instance-attribute 

password: bool | None = None

Whether this field is a password input field.

separator class-attribute instance-attribute 

separator: (
    Annotated[str, pydantic.StringConstraints(min_length=1, max_length=1)]
    | None
) = None

The separator character used for separating array items when for arrays edited as text.

advanced class-attribute instance-attribute 

advanced: bool | None = None

Whether this field is considered an advanced field.

level class-attribute instance-attribute 

level: Literal['common', 'advanced'] | str | None = None

User level of a field. A UI may decide to hide advanced fields.

minimum class-attribute instance-attribute 

minimum: int | float | None = None

Minimum numeric value as used for slider widgets.

maximum class-attribute instance-attribute 

maximum: int | float | None = None

Maximum numeric value as used for slider widgets.

step class-attribute instance-attribute 

step: int | float | None = None

Step size as used for slider widgets.

enum class-attribute instance-attribute 

enum: list[Any] | None = None

Enumeration used for the options of select widgets.

ref class-attribute instance-attribute 

ref: str | None = None

Set from schema reference property '$ref'. Since we resolve schemas, the original $ref value is kept so we can still use it to evaluate a schema's discriminator mappings.

nullable property 

nullable: bool

Whether this field is nullable.

default property 

default: Any

This field's default value.

label cached property 

label: str

The label is the title if the title is provided, even if it is empty. Otherwise, a label is created from the name.

from_input_description classmethod 

from_input_description(
    input_name: str, input_description: InputDescription
) -> FieldMeta

Extract field metadata from the given input name and input description.

from_input_descriptions classmethod 

from_input_descriptions(
    input_descriptions: dict[str, InputDescription],
    name: str = "inputs",
    title: str | None = None,
    description: str | None = None,
) -> FieldMeta

Extract a field metadata instance of type "object" from given input descriptions.

from_schema classmethod 

from_schema(
    name: str, schema: Schema, required: bool | None = None
) -> FieldMeta

Create field metadata from an OpenAPI Schema.

to_non_nullable 

to_non_nullable() -> FieldMeta

Create a non-nullable version of this field metadata.

get_initial_value 

get_initial_value() -> Any

Compute an initial value for this UI field metadata.

gavicore.ui.vm - View Model API

gavicore.ui.vm.ViewModel 

ViewModel(meta: FieldMeta)

Bases: Generic[T], ABC

Abstract base class for all view models.

Base class constructor.

meta property 

meta: FieldMeta

The field's metadata.

schema property 

schema: Schema

The field's OpenAPI schema.

value property writable 

value: T

Get the current value.

from_field_meta classmethod 

from_field_meta(
    meta: FieldMeta, *, value: Any | Undefined = UNDEFINED
) -> ViewModel

Create a new view model instance from the given field metadata and an optional initial value.

watch 

watch(*observers: ViewModelObserver) -> Callable[[], None]

Watch this view model by adding one or more observers to it.

Parameters:

Name Type Description Default
observers ViewModelObserver

The observer(s) to add.

 ()

Returns: A function unwatch() that, when called, removes the added observer(s).

dispose 

dispose()

Dispose this view model. The default implementation removes all registered observers.

intercept_changes 

intercept_changes() -> Generator[list[ViewModelChangeEvent]]

A context manager that is used to temporarily disable change events fired by this view model and return all collected events, if any, in the order they have been collected.

gavicore.ui.vm.PrimitiveViewModel 

PrimitiveViewModel(
    meta: FieldMeta, *, value: Any | Undefined = Undefined.value
)

Bases: Generic[T], ViewModel[T]

A view model that represents a non-nullable, primitive value.

meta property 

meta: FieldMeta

The field's metadata.

schema property 

schema: Schema

The field's OpenAPI schema.

value property writable 

value: T

Get the current value.

from_field_meta classmethod 

from_field_meta(
    meta: FieldMeta, *, value: Any | Undefined = UNDEFINED
) -> ViewModel

Create a new view model instance from the given field metadata and an optional initial value.

watch 

watch(*observers: ViewModelObserver) -> Callable[[], None]

Watch this view model by adding one or more observers to it.

Parameters:

Name Type Description Default
observers ViewModelObserver

The observer(s) to add.

 ()

Returns: A function unwatch() that, when called, removes the added observer(s).

dispose 

dispose()

Dispose this view model. The default implementation removes all registered observers.

intercept_changes 

intercept_changes() -> Generator[list[ViewModelChangeEvent]]

A context manager that is used to temporarily disable change events fired by this view model and return all collected events, if any, in the order they have been collected.

gavicore.ui.vm.ArrayViewModel 

ArrayViewModel(meta: FieldMeta, *, value: Any | Undefined = UNDEFINED)

Bases: CompositeViewModel[int, list[Any]]

A view model for a non-nullable, growable, sparse array value.

meta property 

meta: FieldMeta

The field's metadata.

schema property 

schema: Schema

The field's OpenAPI schema.

value property writable 

value: T

Get the current value.

from_field_meta classmethod 

from_field_meta(
    meta: FieldMeta, *, value: Any | Undefined = UNDEFINED
) -> ViewModel

Create a new view model instance from the given field metadata and an optional initial value.

watch 

watch(*observers: ViewModelObserver) -> Callable[[], None]

Watch this view model by adding one or more observers to it.

Parameters:

Name Type Description Default
observers ViewModelObserver

The observer(s) to add.

 ()

Returns: A function unwatch() that, when called, removes the added observer(s).

dispose 

dispose()

Dispose this view model. The default implementation removes all registered observers.

intercept_changes 

intercept_changes() -> Generator[list[ViewModelChangeEvent]]

A context manager that is used to temporarily disable change events fired by this view model and return all collected events, if any, in the order they have been collected.

gavicore.ui.vm.ObjectViewModel 

ObjectViewModel(
    meta: FieldMeta,
    *,
    value: Any | Undefined = Undefined.value,
    properties: dict[str, ViewModel] | None = None
)

Bases: CompositeViewModel[str, dict[str, Any]]

A view model for a non-nullable, static object comprising view models for each of its properties.

meta property 

meta: FieldMeta

The field's metadata.

schema property 

schema: Schema

The field's OpenAPI schema.

value property writable 

value: T

Get the current value.

from_field_meta classmethod 

from_field_meta(
    meta: FieldMeta, *, value: Any | Undefined = UNDEFINED
) -> ViewModel

Create a new view model instance from the given field metadata and an optional initial value.

watch 

watch(*observers: ViewModelObserver) -> Callable[[], None]

Watch this view model by adding one or more observers to it.

Parameters:

Name Type Description Default
observers ViewModelObserver

The observer(s) to add.

 ()

Returns: A function unwatch() that, when called, removes the added observer(s).

dispose 

dispose()

Dispose this view model. The default implementation removes all registered observers.

intercept_changes 

intercept_changes() -> Generator[list[ViewModelChangeEvent]]

A context manager that is used to temporarily disable change events fired by this view model and return all collected events, if any, in the order they have been collected.

gavicore.ui.panel - Panel API

gavicore.ui.panel.PanelField 

PanelField(
    view_model: ViewModel,
    view: pn.widgets.WidgetBase,
    *,
    json_codec: JsonCodec | None = None
)

Bases: FieldBase[pn.widgets.WidgetBase]

A panel widget-like field.

meta property 

meta: FieldMeta

The field metadata.

UNAVAILABLE_VIEW class-attribute instance-attribute 

UNAVAILABLE_VIEW: Final = pn.widgets.ButtonIcon(
    icon="mood-annoyed-2", name="Missing Field", disabled=True
)

The panel widget used to indicate that a view is missing.

view property 

view: pn.widgets.WidgetBase

The Panel widget-like viewable.

gavicore.ui.panel.PanelFieldFactory

Bases: FieldFactory[PanelField], ABC

Interface implemented by Panel field factories.

get_score abstractmethod 

get_score(meta: FieldMeta) -> int

Get the score of this factory for the given field metadata. The score is proportional to the factory's ability to create a field for the field metadata. A negative or zero score indicates complete inability.

create_field abstractmethod 

create_field(ctx: FieldContext) -> FT

Create the UI field for the given field context.

gavicore.ui.panel.PanelFieldFactoryBase

Bases: FieldFactoryBase[PanelField], PanelFieldFactory, ABC

Convenient base class for custom Panel field factories.

get_score 

get_score(meta: FieldMeta) -> int

Get the score for a field based on its data type.

The default implementation delegates to various get_xxx_score() methods that all return 0 when not being overridden.

Note that we do not consider the case not ctx.schema.required, for optional object properties. This must be dealt with in subclasses.

create_field 

create_field(ctx: FieldContext) -> FT

Create a UI field based on its data type.

The default implementation delegates to various create_xxx_field() methods that all raise NotImplementedError when not being overridden.

Note that we do not consider the case not ctx.schema.required, for optional object properties. This must be dealt with in subclasses.

get_nullable_score 

get_nullable_score(meta: FieldMeta) -> int

Get the score for a nullable field.

get_boolean_score 

get_boolean_score(meta: FieldMeta) -> int

Get the score for a field of type "boolean".

get_integer_score 

get_integer_score(meta: FieldMeta) -> int

Get the score for a field of type "integer".

get_number_score 

get_number_score(meta: FieldMeta) -> int

Get the score for a field of type "number".

get_string_score 

get_string_score(meta: FieldMeta) -> int

Get the score for a field of type "string".

get_array_score 

get_array_score(meta: FieldMeta) -> int

Get the score for a field of type "array".

get_object_score 

get_object_score(meta: FieldMeta) -> int

Get the score for a field of type "object".

get_one_of_score 

get_one_of_score(meta: FieldMeta) -> int

Get the score for a schema that defines 'oneOf'.

get_any_of_score 

get_any_of_score(meta: FieldMeta) -> int

Get the score for a schema that defines 'anyOf'.

get_all_of_score 

get_all_of_score(meta: FieldMeta) -> int

Get the score for a schema that defines 'allOf'.

get_untyped_score 

get_untyped_score(meta: FieldMeta) -> int

Get the score for a field that has no explicit type.

create_nullable_field 

create_nullable_field(ctx: FieldContext) -> FT

Create a UI field for a value that is nullable.

create_boolean_field 

create_boolean_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "boolean".

create_integer_field 

create_integer_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "integer".

create_number_field 

create_number_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "number".

create_string_field 

create_string_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "string".

create_array_field 

create_array_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "array".

create_object_field 

create_object_field(ctx: FieldContext) -> FT

Create a UI field for a value of type "object".

create_one_of_field 

create_one_of_field(ctx: FieldContext) -> FT

Create a UI field for a schema that uses the "oneOf" operator.

create_any_of_field 

create_any_of_field(ctx: FieldContext) -> FT

Create a UI field for a schema that uses the "anyOf" operator.

create_all_of_field 

create_all_of_field(ctx: FieldContext) -> FT

Create a UI field for a schema that uses the "allOf" operator.

create_untyped_field 

create_untyped_field(ctx: FieldContext) -> FT

Create a UI field for a value with no explicit type specified.