0
# Factory Operations
1

2
Core factory methods that provide the essential functionality for building instances, generating batches, and managing the data generation lifecycle. These methods are available on all factory classes and form the foundation of polyfactory's API.
3

4
## Capabilities
5

6
### Instance Building
7

8
Build single instances of the target model with optional field overrides and configuration.
9

10
```python { .api }
11
@classmethod
12
def build(**kwargs) -> T:
13
    """
14
    Build a single instance of the factory's model.
15

16
    Parameters:
17
    - **kwargs: Field values to override in the generated instance
18

19
    Returns:
20
    Instance of the model type with generated or overridden values
21
    """
22
```
23

24
**Usage Example:**
25
```python
26
from dataclasses import dataclass
27
from polyfactory.factories import DataclassFactory
28

29
@dataclass
30
class User:
31
    name: str
32
    age: int
33
    email: str
34

35
class UserFactory(DataclassFactory[User]):
36
    __model__ = User
37

38
# Build with all generated values
39
user = UserFactory.build()
40

41
# Build with specific overrides
42
user = UserFactory.build(name="Alice", age=30)
43
```
44

45
### Batch Generation
46

47
Generate multiple instances efficiently with optional size specification and field overrides applied to all instances.
48

49
```python { .api }
50
@classmethod
51
def batch(size: int, **kwargs) -> list[T]:
52
    """
53
    Build multiple instances of the factory's model.
54

55
    Parameters:
56
    - size: Number of instances to generate
57
    - **kwargs: Field values to override in all generated instances
58

59
    Returns:
60
    List of model instances
61
    """
62
```
63

64
**Usage Example:**
65
```python
66
# Generate 10 users
67
users = UserFactory.batch(10)
68

69
# Generate 5 users all with age=25
70
users = UserFactory.batch(5, age=25)
71
```
72

73
### Coverage Testing
74

75
Generate instances that ensure full type coverage, creating variations that exercise all possible code paths and type combinations.
76

77
```python { .api }
78
@classmethod
79
def coverage(cls, **kwargs) -> Iterator[T]:
80
    """
81
    Build instances that provide full coverage of the model's type variations.
82

83
    Parameters:
84
    - **kwargs: Field values to override in generated instances
85

86
    Returns:
87
    Iterator of model instances covering all type variations
88
    """
89
```
90

91
### Synchronous Persistence
92

93
Build and persist instances using synchronous persistence handlers, integrating directly with databases and storage systems.
94

95
```python { .api }
96
@classmethod
97
def create_sync(**kwargs) -> T:
98
    """
99
    Build and persist a single instance synchronously.
100

101
    Parameters:
102
    - **kwargs: Field values to override in the generated instance
103

104
    Returns:
105
    Persisted instance of the model type
106

107
    Raises:
108
    ConfigurationException: If no sync persistence handler is configured
109
    """
110

111
@classmethod
112
def create_batch_sync(size: int, **kwargs) -> list[T]:
113
    """
114
    Build and persist multiple instances synchronously.
115

116
    Parameters:
117
    - size: Number of instances to generate and persist
118
    - **kwargs: Field values to override in all generated instances
119

120
    Returns:
121
    List of persisted model instances
122
    """
123
```
124

125
### Asynchronous Persistence
126

127
Build and persist instances using asynchronous persistence handlers for non-blocking database operations.
128

129
```python { .api }
130
@classmethod
131
async def create_async(**kwargs) -> T:
132
    """
133
    Build and persist a single instance asynchronously.
134

135
    Parameters:
136
    - **kwargs: Field values to override in the generated instance
137

138
    Returns:
139
    Persisted instance of the model type
140

141
    Raises:
142
    ConfigurationException: If no async persistence handler is configured
143
    """
144

145
@classmethod
146
async def create_batch_async(size: int, **kwargs) -> list[T]:
147
    """
148
    Build and persist multiple instances asynchronously.
149

150
    Parameters:
151
    - size: Number of instances to generate and persist
152
    - **kwargs: Field values to override in all generated instances
153

154
    Returns:
155
    List of persisted model instances
156
    """
157
```
158

159
### Factory Generation
160

161
Dynamically create factory classes for types without explicitly defining factory subclasses.
162

163
```python { .api }
164
@classmethod
165
def create_factory(model: type, **kwargs) -> type[BaseFactory]:
166
    """
167
    Generate a factory class for a given model type.
168

169
    Parameters:
170
    - model: The model type to create a factory for
171
    - **kwargs: Configuration attributes for the factory class
172

173
    Returns:
174
    Factory class for the specified model type
175
    """
176
```
177

178
**Usage Example:**
179
```python
180
from typing import TypedDict
181

182
class PersonDict(TypedDict):
183
    name: str
184
    age: int
185

186
# Create factory dynamically
187
PersonFactory = BaseFactory.create_factory(PersonDict)
188
person = PersonFactory.build()
189
```
190

191
### Type Support Checking
192

193
Verify whether a given type is supported by polyfactory's generation system.
194

195
```python { .api }
196
@classmethod
197
def is_supported_type(value: Any) -> bool:
198
    """
199
    Check if a type is supported for automatic generation.
200

201
    Parameters:
202
    - value: Type or value to check for support
203

204
    Returns:
205
    True if the type can be automatically generated
206
    """
207
```