API

define_factory

define_factory(model, aliases=None, /, *, storage=Absent())

RETURNS	DESCRIPTION
FactoryDSL	The definition of factory

PARAMETER	DESCRIPTION
model	TYPE: type[T]
aliases	Alias attached to this factory. For example if you open you definition like this: with define_factory(User, "account") as factory: ... build(User, "account") it will match the previous definition. If alias is missing, it will target the main factory. You can also define multiple factories at once, using this syntaxe: with define_factory(User, {"alias1", "alias2", "alias3"}) as factory: ... build(User, "alias1") build(User, "alias2") build(User, "alias3") TYPE: Iterable[str | None] | str | None DEFAULT: None
storage	Let define how instances will be persisted when using create and create_many TYPE: Persist[Any] | None | AbsentSentinel DEFAULT: Absent()

build

build(
    model,
    *specializations,
    overrides=None,
    refine=lambda: None
)

Build one model instance.

user = build(User)
assert isinstance(user, User)

PARAMETER	DESCRIPTION
model	TYPE: type[T]
*specializations	Where the first value is the factory alias, and the others are traits TYPE: str DEFAULT: ()
overrides	TYPE: MaybeOverrides DEFAULT: None
refine	TYPE: Refine[T] DEFAULT: lambda : None

build_many

build_many(
    count,
    /,
    model,
    *specializations,
    overrides=None,
    refine=lambda: None,
)

Build many model instances.

user1, user2 = build_many(2, User)
assert isinstance(user1, User)
assert isinstance(user2, User)

PARAMETER	DESCRIPTION
count	TYPE: int
model	TYPE: type[T]
*specializations	Where the first value is the factory alias, and the others are traits TYPE: str DEFAULT: ()
overrides	TYPE: MaybeOverrides DEFAULT: None
refine	TYPE: Refine[T] DEFAULT: lambda : None

create

create(
    model,
    *specializations,
    overrides=None,
    refine=lambda: None,
    storage=None
)

Create one model instance.

user = create(User)
assert isinstance(user, User)

PARAMETER	DESCRIPTION
model	TYPE: type[T]
*specializations	Where the first value is the factory alias, and the others are traits TYPE: str DEFAULT: ()
overrides	TYPE: MaybeOverrides DEFAULT: None
refine	TYPE: Refine[T] DEFAULT: lambda : None
storage	Tell how the instance is persisted. When not set, fallback to the one defined by define_factory TYPE: Persist[T] | None DEFAULT: None

create_many

create_many(
    count,
    /,
    model,
    *specializations,
    overrides=None,
    refine=lambda: None,
    storage=None,
)

Create many model instances.

user1, user2 = create_many(2, User)
assert isinstance(user1, User)
assert isinstance(user2, User)

PARAMETER	DESCRIPTION
count	TYPE: int
model	TYPE: type[T]
*specializations	Where the first value is the factory alias, and the others are traits TYPE: str DEFAULT: ()
overrides	TYPE: MaybeOverrides DEFAULT: None
refine	TYPE: Refine[T] DEFAULT: lambda : None
storage	Tell how instances are persisted. When not set, fallback to the one defined by define_factory TYPE: Persist[T] | None DEFAULT: None

attributes_for

attributes_for(model, *specializations, overrides=None)

Get attributes for one model instance

PARAMETER	DESCRIPTION
model	TYPE: type[T]
*specializations	Where the first value is the factory alias, and the others are traits TYPE: str DEFAULT: ()
overrides	TYPE: MaybeOverrides DEFAULT: None

Attributes module-attribute

Attributes = Mapping[str, Any]

Collected attributes of model object.

For example for this object:

@dataclass
class User:
    given_name: str
    family_name: str
    age: int

This container should looks like:

{"given_name": "John", "family_name": "Smith", "age": 45}

Computed dataclass

Bases: ValueProvider[T]

random class-attribute instance-attribute

random = field(kw_only=True, default=random)

dependencies class-attribute instance-attribute

dependencies = field(kw_only=True, default_factory=list)

wrapped instance-attribute

wrapped

__call__

__call__(context=None)

PARAMETER	DESCRIPTION
context	TYPE: Context | None DEFAULT: None

Cycle dataclass

Bases: ValueProvider[T]

random class-attribute instance-attribute

random = field(kw_only=True, default=random)

dependencies class-attribute instance-attribute

dependencies = field(kw_only=True, default_factory=list)

values instance-attribute

values

__call__

__call__(context=None)

PARAMETER	DESCRIPTION
context	TYPE: Context | None DEFAULT: None

__next__

__next__()

Sequence dataclass

Bases: ValueProvider[T]

random class-attribute instance-attribute

random = field(kw_only=True, default=random)

dependencies class-attribute instance-attribute

dependencies = field(kw_only=True, default_factory=list)

wrapped class-attribute instance-attribute

wrapped = field(default=lambda : x)

Any callable where first argument is the index of the sequence counter, and other arguments are members of Context.

For example, a simple counter:

seq = Sequence(lambda i: f"rank#{i}")
assert seq() == "rank#0"
assert seq() == "rank#1"
assert seq() == "rank#2"

Generate email based on instance.name and counter index:

seq = Sequence(lambda i, name: f"{name}.{i}@example.com".lower)
assert seq({"name": "John"}) == "john.0@example.com"
assert seq({"name": "John"}) == "john.1@example.com"
assert seq({"name": "Dave"}) == "dave.2@example.com"

i class-attribute instance-attribute

i = 0

__call__

__call__(context=None)

PARAMETER	DESCRIPTION
context	TYPE: Context | None DEFAULT: None

Name module-attribute

Name = tuple[type[T], str | None]

Identifier of factory.

Can be only the model class, or a tuple of model class, profile.

For example:

User
(User, "admin")

Those two identifier are equivalents:

User
(User, None)

Persist

Bases: Protocol[T_contrat]

__call__

__call__(instance, context)

PARAMETER	DESCRIPTION
instance	TYPE: T_contrat
context	TYPE: Context

MaybeOverrides module-attribute

MaybeOverrides = Mapping[str, Any] | None

Refine module-attribute

Refine = Callable[[T], Any]

UserHook module-attribute

UserHook = Callable[[Any, Any], Any]

Any callable that has 2 parameters: instance and context.

PARAMETER	DESCRIPTION
instance	the instance being build TYPE: T
context	the context TYPE: Context

Example:

@factory.add_hook("after_create", lambda instance, context: instance.tags.append("new-tag"))

Context module-attribute

Context = Mapping[str, Any]

Set of attributes currently being collected and transient data.

FactoryDSL dataclass

set

set(attr, /, value)

Set a value for attr.

Value may be anything.

Using Computed, it can be based on other attributes or transient data.

PARAMETER	DESCRIPTION
attr	TYPE: str
value	TYPE: Any | Computed[Any] | Cycle[Any] | Sequence[Any] | RandomValue[Any]

associate

associate(
    attr, model, *traits, overrides=None, strategy=None
)

PARAMETER	DESCRIPTION
attr	TYPE: str
model	TYPE: type[Any]
*traits	TYPE: str DEFAULT: ()
overrides	TYPE: MaybeOverrides DEFAULT: None
strategy	TYPE: Strategy | None DEFAULT: None

transient

transient()

RETURNS	DESCRIPTION
TransientDSL	The definition of factory

trait

trait(name)

RETURNS	DESCRIPTION
TraitDSL	The definition of factory

PARAMETER	DESCRIPTION
name	TYPE: str

add_hook

add_hook(name, callback)

Register a hook Example:

factory.add_hook("after_build", lambda instance, context: ...)

PARAMETER	DESCRIPTION
name	TYPE: str
callback	TYPE: UserHook

hook

hook(name)

Decorator used to register hook

PARAMETER	DESCRIPTION
name	TYPE: str

RETURNS	DESCRIPTION
Callable[[UserHook], None]	decorator

Example:

@factory.hook("after_build")
def _(instance, context):
    pass

derived_factory

derived_factory(aliases, /, storage=Absent())

Define a sub factory that inherits from current.

PARAMETER	DESCRIPTION
aliases	TYPE: Iterable[str] | str
storage	TYPE: Persist[T] | None | AbsentSentinel DEFAULT: Absent()

RETURNS	DESCRIPTION
FactoryDSL	The definition of factory

TransientDSL dataclass

set

set(attr, /, value)

PARAMETER	DESCRIPTION
attr	TYPE: str
value	TYPE: Any | Computed[Any] | Cycle[Any] | Sequence[Any]

TraitDSL dataclass

set

set(attr, /, value)

PARAMETER	DESCRIPTION
attr	TYPE: str
value	TYPE: Any | Computed[Any] | Cycle[Any] | Sequence[Any]

add_hook

add_hook(name, callback)

PARAMETER	DESCRIPTION
name	TYPE: str
callback	TYPE: UserHook

hook

hook(name)

PARAMETER	DESCRIPTION
name	TYPE: str

transient

transient()

RETURNS	DESCRIPTION
TransientDSL	The definition of factory

associate

associate(
    attr, model, *traits, overrides=None, strategy=None
)

PARAMETER	DESCRIPTION
attr	TYPE: str
model	TYPE: type[T]
*traits	TYPE: str DEFAULT: ()
overrides	TYPE: MaybeOverrides DEFAULT: None
strategy	TYPE: Strategy | None DEFAULT: None