dataclass_builder package

Module contents

Create instances of dataclasses with the builder pattern.

exception dataclass_builder.DataclassBuilderError[source]

Bases: Exception

Base class of errors raised by DataclassBuilder.

exception dataclass_builder.MissingFieldError(message: str, dataclass: Any, field: Field[Any])[source]

Bases: dataclass_builder.exceptions.DataclassBuilderError

Thrown when fields are missing when building a dataclasses.dataclass().

Parameters
dataclass

dataclasses.dataclass() the DataclassBuilder was made for.

field

The dataclasses.Field representing the missing field that needs to be assigned.

exception dataclass_builder.UndefinedFieldError(message: str, dataclass: Any, field: str)[source]

Bases: dataclass_builder.exceptions.DataclassBuilderError

Exception thrown when attempting to assign to an invalid field.

Parameters
dataclass

dataclasses.dataclass() the DataclassBuilder was made for.

field

Name of the invalid field that the calling code tried to assign to.

dataclass_builder.dataclass_builder(dataclass: Type[Any], *, name: Optional[str] = None) → Type[Any][source]

Create a new builder class specialized to a given dataclass.

Parameters

  • dataclass – The dataclasses.dataclass() to create the builder for.

  • name – Override the name of the builder, by default it will be ‘<dataclass>Builder’ where <dataclass> is replaced by the name of the dataclass.

Return object

A new dataclass builder class that is specialized to the given dataclass. If the given dataclasses.dataclass() does not contain the fields build or fields these will be exposed as public methods with the same signature as the dataclass_builder.utility.build() and dataclass_builder.utility.fields() functions respectively.

Raises

TypeError – If dataclass is not a dataclasses.dataclass(). This is decided via dataclasses.is_dataclass().

dataclass_builder.build(builder: dataclass_builder.wrapper.DataclassBuilder) → Any[source]

Use the given DataclassBuilder to initialize a dataclass.

This will use the values assigned to the given builder to construct a dataclasses.dataclass() of the type the builder was created for.

Note

This is not a method of DataclassBuilder in order to not interfere with possible field names. This function will use special private methods of DataclassBuilder which are excepted from field assignment.

Parameters

builder – The dataclass builder to build from.

Raises

dataclass_builder.exceptions.MissingFieldError – If not all of the required fields have been assigned to this builder.

dataclass_builder.fields(builder: dataclass_builder.wrapper.DataclassBuilder, *, required: bool = True, optional: bool = True) → Mapping[str, Field[Any]][source]

Get a dictionary of the given DataclassBuilder’s fields.

Note

This is not a method of DataclassBuilder in order to not interfere with possible field names. This function will use special private methods of DataclassBuilder which are excepted from field assignment.

Parameters

  • builder – The dataclass builder to get the fields for.

  • required – Set to False to not report required fields.

  • optional – Set to False to not report optional fields.

Returns

A mapping from field names to actual dataclasses.Field’s in the same order as the builder’s underlying dataclasses.dataclass().

dataclass_builder.update(dataclass: Any, builder: dataclass_builder.wrapper.DataclassBuilder) → None[source]

Update a dataclass or dataclass builder from a partial dataclass builder.

Parameters

  • dataclass –

    :func`dataclasses.dataclass` or dataclass builder to update.

    Note

    Technically this can be any object that supports __setattr__().

  • builder – The datalcass builder to update dataclass with. All fields that are not missing in the builder will be set (overridden) on the given dataclass.

class dataclass_builder.DataclassBuilder(dataclass: Any, **kwargs: Any)[source]

Bases: object

Wrap a dataclass with an object implementing the builder pattern.

This class, via wrapping, allows dataclasses to be constructed with the builder pattern. Once an instance is constructed simply assign to it’s attributes, which are identical to the dataclass it was constructed with. When done use the dataclass_builder.utility.build() function to attempt to build the underlying dataclass.

Warning

Because this class overrides attribute assignment when extending it care must be taken to only use private or “dunder” attributes and methods.

Parameters

  • dataclass – The dataclass_that should be built by the builder instance

  • **kwargs – Optionally initialize fields during initialization of the builder. These can be changed later and will raise UndefinedFieldError if they are not part of the dataclass’s __init__ method.

Raises
__setattr__(item: str, value: Any) → None[source]

Set a field value, or an object attribute if it is private.

Note

This will pass through all attributes beginning with an underscore. If this is a valid field of the dataclass it will still be built correctly but UndefinedFieldError will not be thrown for attributes beginning with an underscore.

If you need the exception to be thrown then set the field in the constructor.

Parameters

  • item – Name of the dataclass field or private/”dunder” attribute to set.

  • value – Value to assign to the dataclass field or private/”dunder” attribute.

Raises

dataclass_builder.exceptions.UndefinedFieldError – If item is not initialisable in the underlying dataclass. If item is private (begins with an underscore) or is a “dunder” then this exception will not be raised.

__repr__() → str[source]

Print a representation of the builder.

from dataclasses import dataclass
from dataclass_builder import DataclassBuilder, build, fields

@dataclass
class Point:
    x: float
    y: float
    w: float = 1.0

>>> DataclassBuilder(Point, x=4.0, w=2.0)
DataclassBuilder(Point, x=4.0, w=2.0)
Returns

String representation that can be used to construct this builder instance.