0
# Core Providers
1
2
Foundation classes and the unified Generic provider that enable consistent data generation patterns across all data types in mimesis.
3
4
## Capabilities
5
6
### BaseProvider
7
8
Abstract base class that provides fundamental functionality for all mimesis providers including random number generation control and enum validation.
9
10
```python { .api }
11
class BaseProvider:
12
"""Base class for all mimesis providers."""
13
14
def reseed(self, seed: int = None) -> None:
15
"""
16
Reseed the internal random number generator.
17
18
Parameters:
19
- seed (int, optional): Seed value for reproducible results
20
"""
21
22
def validate_enum(self, item: Any, enum: type) -> Any:
23
"""
24
Validate that an item is a valid enum value.
25
26
Parameters:
27
- item: Value to validate
28
- enum: Enum class to validate against
29
30
Returns:
31
Valid enum value
32
33
Raises:
34
NonEnumerableError: If item is not a valid enum value
35
"""
36
```
37
38
### BaseDataProvider
39
40
Abstract base class extending BaseProvider with locale-specific functionality for providers that generate locale-dependent data.
41
42
```python { .api }
43
class BaseDataProvider(BaseProvider):
44
"""Base class for locale-dependent data providers."""
45
46
def __init__(self, locale: Locale = Locale.DEFAULT):
47
"""
48
Initialize provider with locale.
49
50
Parameters:
51
- locale (Locale): Locale for data generation
52
"""
53
54
def get_current_locale(self) -> str:
55
"""
56
Get the current locale string.
57
58
Returns:
59
str: Current locale (e.g., 'en', 'de-de')
60
"""
61
62
def override_locale(self, locale: Locale):
63
"""
64
Context manager for temporarily overriding locale.
65
66
Parameters:
67
- locale (Locale): Temporary locale to use
68
69
Usage:
70
```python
71
provider = Person(Locale.EN)
72
with provider.override_locale(Locale.DE):
73
name = provider.first_name() # German name
74
```
75
"""
76
77
def update_dataset(self, data: dict) -> None:
78
"""
79
Update the internal dataset with custom data.
80
81
Parameters:
82
- data (dict): Data to merge with existing dataset
83
"""
84
```
85
86
### Generic Provider
87
88
Unified provider that gives access to all individual providers through a single interface, enabling convenient access to the entire mimesis API.
89
90
```python { .api }
91
class Generic:
92
"""Unified provider for accessing all mimesis functionality."""
93
94
def __init__(self, locale: Locale = Locale.DEFAULT):
95
"""
96
Initialize Generic provider with locale.
97
98
Parameters:
99
- locale (Locale): Default locale for all providers
100
"""
101
102
def reseed(self, seed: int = None) -> None:
103
"""
104
Reseed all internal providers' random number generators.
105
106
Parameters:
107
- seed (int, optional): Seed value for reproducible results
108
"""
109
110
def add_provider(self, cls: type, **kwargs) -> None:
111
"""
112
Add a custom provider to the Generic instance.
113
114
Parameters:
115
- cls: Provider class to add
116
- **kwargs: Arguments to pass to provider constructor
117
118
Usage:
119
```python
120
from mimesis import Generic
121
122
class CustomProvider:
123
def custom_data(self):
124
return "custom"
125
126
generic = Generic()
127
generic.add_provider(CustomProvider)
128
print(generic.custom.custom_data()) # "custom"
129
```
130
"""
131
132
def add_providers(self, *providers: type) -> None:
133
"""
134
Add multiple custom providers to the Generic instance.
135
136
Parameters:
137
- *providers: Provider classes to add
138
"""
139
140
# Provider access attributes
141
person: Person
142
address: Address
143
internet: Internet
144
datetime: Datetime
145
finance: Finance
146
text: Text
147
numeric: Numeric
148
development: Development
149
science: Science
150
food: Food
151
hardware: Hardware
152
transport: Transport
153
cryptographic: Cryptographic
154
payment: Payment
155
choice: Choice
156
code: Code
157
binaryfile: BinaryFile
158
file: File
159
path: Path
160
```
161
162
## Usage Examples
163
164
### Basic Provider Usage
165
166
```python
167
from mimesis import Person, Address
168
from mimesis.locales import Locale
169
170
# Create providers with different locales
171
person_en = Person(Locale.EN)
172
person_de = Person(Locale.DE)
173
address = Address(Locale.FR)
174
175
# Generate localized data
176
english_name = person_en.full_name() # "John Smith"
177
german_name = person_de.full_name() # "Hans Müller"
178
french_city = address.city() # "Paris"
179
```
180
181
### Generic Provider Usage
182
183
```python
184
from mimesis import Generic
185
from mimesis.locales import Locale
186
187
# Single Generic instance for all data types
188
generic = Generic(Locale.EN)
189
190
# Access all providers through unified interface
191
user_data = {
192
'name': generic.person.full_name(),
193
'email': generic.internet.email(),
194
'address': generic.address.address(),
195
'birthday': generic.datetime.date(),
196
'salary': generic.finance.price(minimum=50000, maximum=150000)
197
}
198
```
199
200
### Reproducible Data Generation
201
202
```python
203
from mimesis import Generic
204
205
# Set seed for reproducible results
206
generic = Generic()
207
generic.reseed(12345)
208
209
# These will be the same on every run
210
name1 = generic.person.full_name()
211
name2 = generic.person.full_name()
212
213
# Reseed with same value to get same sequence again
214
generic.reseed(12345)
215
name3 = generic.person.full_name() # Same as name1
216
```
217
218
### Locale Override
219
220
```python
221
from mimesis import Person
222
from mimesis.locales import Locale
223
224
person = Person(Locale.EN)
225
226
# Default locale
227
english_name = person.full_name() # "John Smith"
228
229
# Temporarily use different locale
230
with person.override_locale(Locale.JA):
231
japanese_name = person.full_name() # "田中太郎"
232
233
# Back to default locale
234
english_name2 = person.full_name() # "Jane Doe"
235
```