0
# Configuration and Utilities
1

2
Enumerations, locale management, utility functions, and plugin integrations that support and configure the mimesis data generation system.
3

4
## Capabilities
5

6
### Locale Configuration
7

8
```python { .api }
9
class Locale(Enum):
10
    """Supported locales for data generation."""
11
    
12
    DEFAULT = "en"
13
    EN = "en"
14
    EN_US = "en-us"
15
    EN_GB = "en-gb"
16
    DE = "de"
17
    DE_DE = "de-de"
18
    FR = "fr"
19
    ES = "es"
20
    IT = "it"
21
    JA = "ja"
22
    ZH = "zh"
23
    RU = "ru"
24
    # ... 35+ total locales
25

26
def validate_locale(locale: Union[str, Locale]) -> Locale:
27
    """Validate and convert locale to Locale enum."""
28
```
29

30
### Key Utility Functions
31

32
```python { .api }
33
def luhn_checksum(num: str) -> str:
34
    """
35
    Calculate Luhn checksum for validation algorithms.
36
    
37
    Parameters:
38
    - num (str): Number string to calculate checksum for
39
    
40
    Returns:
41
    str: Number with checksum digit appended
42
    """
43

44
def romanize(locale: Locale) -> callable:
45
    """
46
    Create romanization function for specific locale.
47
    
48
    Parameters:
49
    - locale (Locale): Source locale for romanization
50
    
51
    Returns:
52
    callable: Function that romanizes text from locale
53
    """
54

55
def maybe(value: Any, probability: float = 0.5) -> callable:
56
    """
57
    Create probabilistic value function.
58
    
59
    Parameters:
60
    - value: Value to return probabilistically
61
    - probability (float): Probability of returning value (0.0-1.0)
62
    
63
    Returns:
64
    callable: Function that returns value or None based on probability
65
    """
66
```
67

68
### Configuration Enumerations
69

70
```python { .api }
71
class Gender(Enum):
72
    MALE = "male"
73
    FEMALE = "female"
74

75
class CountryCode(Enum):
76
    A2 = "a2"        # ISO 3166-1 alpha-2
77
    A3 = "a3"        # ISO 3166-1 alpha-3
78
    NUMERIC = "numeric"
79

80
class TimezoneRegion(Enum):
81
    AFRICA = "africa"
82
    AMERICA = "america"
83
    ANTARCTICA = "antarctica"
84
    ARCTIC = "arctic"
85
    ASIA = "asia"
86
    ATLANTIC = "atlantic"
87
    AUSTRALIA = "australia"
88
    EUROPE = "europe"
89
    INDIAN = "indian"
90
    PACIFIC = "pacific"
91

92
class CardType(Enum):
93
    VISA = "visa"
94
    MASTERCARD = "mastercard"
95
    AMERICAN_EXPRESS = "american_express"
96
    DISCOVER = "discover"
97

98
class Algorithm(Enum):
99
    MD5 = "md5"
100
    SHA1 = "sha1"
101
    SHA224 = "sha224"
102
    SHA256 = "sha256"
103
    SHA384 = "sha384"
104
    SHA512 = "sha512"
105

106
class FileType(Enum):
107
    SOURCE = "source"
108
    TEXT = "text"
109
    DATA = "data"
110
    AUDIO = "audio"
111
    VIDEO = "video"
112
    IMAGE = "image"
113
    EXECUTABLE = "executable"
114
    COMPRESSED = "compressed"
115

116
class MimeType(Enum):
117
    APPLICATION = "application"
118
    AUDIO = "audio"
119
    EXAMPLE = "example"
120
    FONT = "font"
121
    IMAGE = "image"
122
    MESSAGE = "message"
123
    MODEL = "model"
124
    MULTIPART = "multipart"
125
    TEXT = "text"
126
    VIDEO = "video"
127

128
class PortRange(Enum):
129
    ALL = "all"
130
    WELL_KNOWN = "well_known"        # 1-1023
131
    EPHEMERAL = "ephemeral"          # 32768-65535
132

133
class URLScheme(Enum):
134
    HTTP = "http"
135
    HTTPS = "https"
136
    FTP = "ftp"
137
    SFTP = "sftp"
138
    WS = "ws"
139
    WSS = "wss"
140
```
141

142
### Exception Classes
143

144
```python { .api }
145
class LocaleError(Exception):
146
    """Raised when locale is not supported or invalid."""
147

148
class SchemaError(Exception):
149
    """Raised when schema definition is invalid."""
150

151
class NonEnumerableError(Exception):
152
    """Raised when value is not a valid enum member."""
153

154
class FieldError(Exception):
155
    """Raised when field operation fails."""
156

157
class FieldsetError(Exception):
158
    """Raised when fieldset operation fails."""
159

160
class FieldArityError(Exception):
161
    """Raised when field handler has wrong number of arguments."""
162

163
class FieldNameError(Exception):
164
    """Raised when field name is invalid."""
165
```
166

167
### Plugin Integrations
168

169
```python { .api }
170
# Factory Boy Integration
171
class FactoryField:
172
    """Integration with Factory Boy for factory definitions."""
173
    
174
    def __init__(self, provider_method: str, **kwargs):
175
        """Initialize with provider method and arguments."""
176

177
MimesisField = FactoryField  # Alias
178

179
# Pytest Integration
180
def mimesis_locale() -> Locale:
181
    """Pytest fixture providing default locale."""
182

183
def mimesis() -> Field:
184
    """Pytest fixture providing Field instance."""
185
```
186

187
## Usage Examples
188

189
### Locale Management
190

191
```python
192
from mimesis.locales import Locale, validate_locale
193

194
# Using different locales
195
person_en = Person(Locale.EN)
196
person_de = Person(Locale.DE)
197
person_ja = Person(Locale.JA)
198

199
# Locale validation
200
valid_locale = validate_locale("en-us")  # Returns Locale.EN_US
201
```
202

203
### Utility Functions
204

205
```python
206
from mimesis.keys import romanize, maybe
207
from mimesis.shortcuts import luhn_checksum
208

209
# Romanization
210
romanize_ja = romanize(Locale.JA)
211
romanized_text = romanize_ja("こんにちは")  # "konnichiwa"
212

213
# Probabilistic values
214
maybe_value = maybe("special", probability=0.3)
215
result = maybe_value()  # Returns "special" 30% of the time, None 70%
216

217
# Luhn checksum
218
card_number = "424242424242424"
219
valid_card = luhn_checksum(card_number)  # Adds checksum digit
220
```
221

222
### Enum Configuration
223

224
```python
225
from mimesis import Internet, Finance, Address
226
from mimesis.enums import PortRange, CardType, CountryCode
227

228
internet = Internet()
229
finance = Finance()
230
address = Address()
231

232
# Configure with enums
233
port = internet.port(PortRange.WELL_KNOWN)     # Port 1-1023
234
card = finance.credit_card_number(CardType.VISA)
235
country = address.country_code(CountryCode.A3)  # 3-letter code
236
```
237

238
### Factory Boy Integration
239

240
```python
241
import factory
242
from mimesis.plugins.factory import MimesisField
243

244
class UserFactory(factory.Factory):
245
    class Meta:
246
        model = User
247
    
248
    name = MimesisField('person.full_name')
249
    email = MimesisField('internet.email')
250
    age = MimesisField('person.age', minimum=18, maximum=65)
251

252
# Create users
253
user = UserFactory()
254
```
255

256
### Pytest Integration
257

258
```python
259
import pytest
260
from mimesis.plugins.pytest import mimesis, mimesis_locale
261

262
def test_user_creation(mimesis):
263
    """Test using mimesis pytest fixture."""
264
    name = mimesis('person.full_name')
265
    email = mimesis('internet.email')
266
    
267
    assert isinstance(name, str)
268
    assert '@' in email
269

270
def test_with_locale(mimesis_locale):
271
    """Test using locale fixture."""
272
    person = Person(mimesis_locale)
273
    name = person.full_name()
274
    assert isinstance(name, str)
275
```
276

277
### Exception Handling
278

279
```python
280
from mimesis import Person
281
from mimesis.exceptions import LocaleError, NonEnumerableError
282
from mimesis.enums import Gender
283

284
try:
285
    person = Person("invalid-locale")
286
except LocaleError as e:
287
    print(f"Invalid locale: {e}")
288

289
try:
290
    person = Person()
291
    name = person.first_name(gender="invalid")
292
except NonEnumerableError as e:
293
    print(f"Invalid enum value: {e}")
294
```
295

296
### Package Metadata
297

298
```python
299
import mimesis
300

301
# Package information
302
print(mimesis.__version__)      # "18.0.0"
303
print(mimesis.__title__)        # "mimesis"
304
print(mimesis.__description__)  # "Mimesis: Fake Data Generator."
305
print(mimesis.__author__)       # "Isaak Uchakaev (Likid Geimfari)"
306
print(mimesis.__license__)      # "MIT License"
307
```