dataclass_builder package¶
Submodules¶
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
message – Human readable error message
dataclass –
dataclasses.dataclass()
theDataclassBuilder
was made for.field – The
dataclasses.Field
representing the missing field that needs to be assigned.
-
dataclass
¶ dataclasses.dataclass()
theDataclassBuilder
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
message – Human readable error message
dataclass –
dataclasses.dataclass()
theDataclassBuilder
was made for.field – Name of the invalid field that the calling code tried to assign to.
-
dataclass
¶ dataclasses.dataclass()
theDataclassBuilder
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 thedataclass_builder.utility.build()
anddataclass_builder.utility.fields()
functions respectively.- Raises
TypeError – If dataclass is not a
dataclasses.dataclass()
. This is decided viadataclasses.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 ofDataclassBuilder
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 ofDataclassBuilder
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 underlyingdataclasses.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
TypeError – If dataclass is not a dataclass. This is decided via
dataclasses.is_dataclass()
.dataclass_builder.exceptions.UndefinedFieldError – If you try to assign to a field that is not part of the dataclass’s __init__.
dataclass_builder.exceptions.MissingFieldError – If
build()
is called on this builder before all non default fields of the dataclass are assigned.
-
__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.