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.