dataclass-builder 0.0.2

Create instances of dataclasses with the builder pattern.

Create instances of Python dataclasses with the builder pattern.

Usage

There are two ways to use dataclass-builder. Via a builder instance or by creating a dedicated builder.

Builder Instance

Using a builder instance is the fastest way to get started with dataclass-builder.

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

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

Now we can build a point.

>>> p1_builder = DataclassBuilder(Point)
>>> p1_builder.x = 5.8
>>> p1_builder.y = 8.1
>>> p1_builder.w = 2.0
>>> p1 = build(p1_builder)
Point(x=5.8, y=8.1, w=2.0)

Field values can also be provided in the constructor.

>>> p3_builder = DataclassBuilder(Point, w=100)
>>> p3_builder.x = 5.8
>>> p3_builder.y = 8.1
>>> p3 = build(p3_builder)
Point(x=5.8, y=8.1, w=100)

Fields with default values in the dataclass are optional in the builder.

>>> p4_builder = DataclassBuilder(Point)
>>> p4_builder.x = 5.8
>>> p4_builder.y = 8.1
>>> p4 = build(p4_builder)
Point(x=5.8, y=8.1, w=1.0)

Fields that don’t have default values in the dataclass are not optional.

>>> p5_builder = DataclassBuilder(Point)
>>> p5_builder.y = 8.1
>>> p5 = build(p5_builder)
MissingFieldError: field 'x' of dataclass 'Point' is not optional

Fields not defined in the dataclass cannot be set in the builder.

>>> p6_builder = DataclassBuilder(Point)
>>> p6_builder.z = 3.0
UndefinedFieldError: dataclass 'Point' does not define field 'z'

No exception will be raised for fields beginning with an underscore.

Accessing a field of the builder before it is set results in an AttributeError.

>>> p8_builder = DataclassBuilder(Point)
>>> p8.x
AttributeError: 'DataclassBuilder' object has no attribute 'x'

Dedicated Builder (coming soon)

A dedicated builder can make more sense if used often or when needing to document the builder.

from dataclasses
from dataclass_builder import dataclass_builder, build

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

@dataclass_builder
class PointBuilder:
    pass

Now we can build a point.

>>> p_builder = PointBuilder()
>>> p_builder.x = 5.8
>>> p_builder.y = 8.1
>>> p_builder.w = 2.0
>>> p = build(p_builder)
Point(x=5.8, y=8.1, w=2.0)

In addition to providing field values during initialization as with the Builder Instance they can also be provided in the decorator.

@dataclass_builder(w=100)
class PointBuilder:
    pass

The following two statements are mostly equivalent, with the exception of documentation and type.

PointBuilder()
DataclassBuilder(Point)

Therefore, see the section on Builder Instance for further documentation.

Requirements

• Python 3.6 or greater

• dataclasses if using Python 3.6

Installation

dataclass-builder is on PyPI so the best way to install it is:

$ pip install dataclass-builder