Schemas

BespokeFit uses Pydantic to validate input provided by users. Pydantic helps BespokeFit provide clear error messages when it is configured improperly, and also provides inspection and documentation tools that BespokeFit uses extensively.

Models and fields

Not every class in BespokeFit uses Pydantic; those that do are found mostly in the schema module and can be identified in documentation as a model, which appears in green before their path and name.

Models are characterized by their fields, which are like attributes in Python data classes. Fields can be validated at runtime, both according to their type annotations and via custom validator functions. Attempting to set a field to an invalid value will immediately raise a clear error, rather than causing a failure later on when the value is used.

A model’s fields, validation machinery, and other Pydantic configuration forms its schema. A schema describes every possible configuration of a model and is useful for investigating what can be done with a class. Schemas are included in a model’s API reference documentation, and can be accessed programmatically with the schema() method.

For example, BespokeWorkflowFactory is a model. Its schema is available on its API page, but can also be accessed on the class itself or any instance:

from openff.bespokefit.workflows.bespoke import BespokeWorkflowFactory

BespokeWorkflowFactory.schema()

factory = BespokeWorkflowFactory()
factory.schema()

Introspection

Models provide a number of methods that are useful for inspecting objects in an interactive environment, such as a Jupyter notebook. These methods are implemented on pydantic.BaseModel, documented below. Models in BespokeFit inherit these methods, though they are not explicitly documented in order to reduce clutter.

class pydantic.BaseModel

Base class for Pydantic Models.

Provides introspection methods and validation for fields.

dict(*, include: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, exclude: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, by_alias: bool = False, skip_defaults: Optional[bool] = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → DictStrAny

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

copy(*, include: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, exclude: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, update: Optional[DictStrAny] = None, deep: bool = False) → Model

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters

  • include – fields to include in new model

  • exclude – fields to exclude from new model, as with values this takes precedence over include

  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data

  • deep – set to True to make a deep copy of the model

Returns

new model instance

json(*, include: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, exclude: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, by_alias: bool = False, skip_defaults: Optional[bool] = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Optional[Callable[[Any], Any]] = None, models_as_dict: bool = True, **dumps_kwargs: Any) → unicode

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

classmethod parse_file(path: Union[str, Path], *, content_type: unicode = None, encoding: unicode = 'utf8', proto: Protocol = None, allow_pickle: bool = False) → Model

Read a json file with the given filename encoding an instance of a model.

classmethod schema(by_alias: bool = True, ref_template: unicode = '#/definitions/{model}') → DictStrAny

Display the schema satisfied by instances of the model.

This method is useful for inspecting the options available in a schema in an interactive environment.