Skip to main content

Create instances of dataclasses with the builder pattern.

Project description

Build status Documentation status Test coverage Code style is black PyPI Package latest release Supported versions Status MIT

Create instances of Python dataclasses with the builder pattern.

Requirements

  • Python 3.6 or greater

  • dataclasses if using Python 3.6

Installation

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

$ pip install dataclass-builder

Usage

There are two ways to use dataclass-builder. Via a builder instance or by creating a dedicated builder. The latter is recommended when repeated building of a given dataclass is desired or when docstrings and type checking are important.

Dedicated Builder (builder factory)

Using specialized builders allows for better documentation than the DataclassBuilder wrapper.

from dataclasses import dataclass
from dataclass_builder import (dataclass_builder, build, fields, update
                               REQUIRED, OPTIONAL)

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

PointBuilder = dataclass_builder(Point)

Now we can build a point.

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

As long as the dataclass the builder was constructed for does not have a build field then a build method will be generated as well.

>>> builder.build()
Point(x=5.8, y=8.1, w=2.0)

Field values can also be provided in the constructor.

>>> builder = PointBuilder(x=5.8, w=100)
>>> builder.y = 8.1
>>> builder.build()
Point(x=5.8, y=8.1, w=100)

Positional arguments are not allowed.

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

>>> builder = PointBuilder()
>>> builder.x = 5.8
>>> builder.y = 8.1
>>> builder.build()
Point(x=5.8, y=8.1, w=1.0)

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

>>> builder = PointBuilder()
>>> builder.y = 8.1
>>> builder.build()
Traceback (most recent call last):
...
MissingFieldError: field 'x' of dataclass 'Point' is not optional

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

>>> builder.z = 3.0
Traceback (most recent call last):
...
UndefinedFieldError: dataclass 'Point' does not define field 'z'

No exception will be raised for fields beginning with an underscore as they are reserved for use by subclasses.

Accessing a field of the builder before it is set gives either the REQUIRED or OPTIONAL constant

>>> builder = PointBuilder()
>>> builder.x
REQUIRED
>>> builder.w
OPTIONAL

The fields method can be used to retrieve a dictionary of settable fields for the builder. This is a mapping of field names to dataclasses.Field objects from which extra data can be retrieved such as the type of the data stored in the field.

>>> list(builder.fields().keys())
['x', 'y', 'w']
>>> [f.type.__name__ for f in builder.fields().values()]
['float', 'float', 'float']

A subset of the fields can be also be retrieved, for instance, to only get required fields:

>>> list(builder.fields(optional=False).keys())
['x', 'y']

or only the optional fields.

>>> list(builder.fields(required=False).keys())
['w']

If the underlying dataclass has a field named fields this method will not be generated and instead the fields function should be used instead.

An already built dataclass can be updated with a partially completed builder using the update function.

>>> point = Point(x=5.8, y=8.1, w=100)
>>> update(point, PointBuilder(y=1.1))
>>> point
Point(x=5.8, y=1.1, w=100)

Dataclass builders can also be updated, but frozen dataclasses cannot.

Builder Instance (generic wrapper)

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

from dataclasses import dataclass
from dataclass_builder import (DataclassBuilder, build, fields,
                               REQUIRED, OPTIONAL)

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

Now we can build a point.

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

Field values can also be provided in the constructor.

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

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

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

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

>>> builder = DataclassBuilder(Point)
>>> builder.y = 8.1
>>> build(builder)
Traceback (most recent call last):
...
MissingFieldError: field 'x' of dataclass 'Point' is not optional

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

>>> builder.z = 3.0
Traceback (most recent call last):
...
UndefinedFieldError: dataclass 'Point' does not define field 'z'

Accessing a field of the builder before it is set gives either the REQUIRED or OPTIONAL constant

>>> builder = DataclassBuilder(Point)
>>> builder.x
REQUIRED
>>> builder.w
OPTIONAL

The fields function can be used to retrieve a dictionary of settable fields for the builder. This is a mapping of field names to dataclasses.Field objects from which extra data can be retrieved such as the type of the data stored in the field.

>>> list(fields(builder).keys())
['x', 'y', 'w']
>>> [f.type.__name__ for f in fields(builder).values()]
['float', 'float', 'float']

A subset of the fields can be also be retrieved, for instance, to only get required fields:

>>> list(fields(builder, optional=False).keys())
['x', 'y']

or only the optional fields.

>>> list(fields(builder, required=False).keys())
['w']

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dataclass-builder-1.2.0.tar.gz (18.0 kB view hashes)

Uploaded Source

Built Distribution

dataclass_builder-1.2.0-py3-none-any.whl (21.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page