plato.formclasses module

Implementation of Plato’s core formclasses API.

Plato’s core API consists out of

• the formclass decorator to annotate classes defining the hierarchical structure of desired test data,

• and the sample function to generate instances of concrete test data from instances of such form classes.

@plato.formclasses.formclass

Class decorator to process a class definition as formclass.

The formclass decorator is one of the main parts of the Plato API. A class annotated with it will be processed to enable Plato’s feature. In particular, it will become a dataclass() and support for the derivedfield decorator will be added.

Similar to a dataclass(), you can define fields in a formclass using type annotations. In addition to normal default values and field() assignments, you can assign a Provider that is used to generate values when using sample.

Like dataclasses, a formclass supports the InitVar type. A field with such a type will not be available on the instance, but will be passed as argument to the __post_init__ method (in order of declaration) and derivedfield methods (as keyword argument by name).

Example

fake = plato.providers.faker.FromFaker()

@formclass
class MyFormclass:
    field: str = "value"
    generated_field: str = fake.first_name()

data = sample(MyFormclass())
print(data.field)
print(data.generated_field)

value
Alicia

Parameters

cls (type) –

Return type

type

@plato.formclasses.derivedfield

Method decorator to derive a formclass field from other fields.

When instantiating a formclass, the decorated method will be run after initializing all normal fields. The returned value will be used to add a field with the method’s name to the formclass instance. You get access to your fields (including InitVar fields) by declaring additional arguments for the derivedfield using the same name as the field.

Parameters

fn (DerivedFieldT) –

plato.formclasses.fn

Decorated method.

plato.formclasses.sample(form, context=None)

Generates a dataclass with concrete values from a formclass instance.

Recursively processes a formclass instance and returns an analogous dataclass() where all Provider have been replaced with values generated from these providers. The returned dataclass will also have fields added for derivedfield annotated methods.

This function uses a context to provide deterministic random number seeds based on the field names and allow information to be shared between Provider instances. Usually it will not be necessary to provide this context as it will be automatically initialized for each top-level invocation.

Parameters

• form (T) – Usually a formclass instance to be processed. But can also be a Provider instance which will forward the call to the provider’s Provider.sample method. Any other type of object will be returned unchanged.

• context (Optional[plato.context.Context]) – Context of the sample operation, for example, the random number seed to use. Usually this argument has not to be set manually and will be initialized automatically.

Returns

For a formclass a dataclass instance is returned with Provider instances replaced by sampled values and derviedfield methods added as fields. For a Provider the sampled value will be returned and for all other objects, the object itself is returned.

Return type

T

Examples

With formclass:

fake = plato.providers.faker.FromFaker()

@formclass
class MyFormclass:
    field: str = "value"
    generated_field: str = fake.first_name()

data = sample(MyFormclass())
print(data.field)
print(data.generated_field)

value
Alicia

With Provider:

fake = plato.providers.faker.FromFaker()
print(sample(fake.first_name()))

Thomas

Any other object:

print(sample("foo"))

foo