0
# Mimesis
1

2
Mimesis is a robust fake data generator for Python that produces realistic fake data across 35 different locales. It serves as a comprehensive testing and development library offering high-performance data generation with multilingual support, extensive customization through custom providers and field handlers, and schema-based generators for complex data structures.
3

4
## Package Information
5

6
- **Package Name**: mimesis
7
- **Language**: Python
8
- **Installation**: `pip install mimesis`
9
- **Version**: 18.0.0
10

11
## Core Imports
12

13
```python
14
import mimesis
15
```
16

17
Common provider imports:
18

19
```python
20
from mimesis import Person, Address, Internet, Datetime, Finance
21
```
22

23
Using the unified Generic provider:
24

25
```python
26
from mimesis import Generic
27
from mimesis.locales import Locale
28
```
29

30
Schema-based generation:
31

32
```python
33
from mimesis import Field, Schema
34
```
35

36
## Basic Usage
37

38
```python
39
from mimesis import Person, Address, Internet
40
from mimesis.locales import Locale
41

42
# Create providers with specific locale
43
person = Person(Locale.EN)
44
address = Address(Locale.EN)
45
internet = Internet()
46

47
# Generate individual data
48
name = person.full_name()  # "John Smith"
49
email = person.email()     # "example@domain.com"
50
city = address.city()      # "New York"
51

52
# Using Generic provider for unified access
53
from mimesis import Generic
54

55
generic = Generic(Locale.EN)
56
print(generic.person.full_name())    # "Jane Doe"
57
print(generic.address.country())     # "United States"
58
print(generic.datetime.date())       # datetime.date(2023, 5, 15)
59
```
60

61
Schema-based bulk generation:
62

63
```python
64
from mimesis import Field, Schema
65
from mimesis.locales import Locale
66

67
# Define schema
68
field = Field(Locale.EN)
69
schema = Schema(schema=lambda: {
70
    'id': field('increment'),
71
    'name': field('person.full_name'),
72
    'email': field('person.email'),
73
    'birthdate': field('person.birthdate', min_year=1980, max_year=2005),
74
    'address': field('address.address'),
75
})
76

77
# Generate multiple records
78
data = schema.create(iterations=100)
79
```
80

81
## Architecture
82

83
Mimesis is built around several key components:
84

85
- **Providers**: Specialized classes for generating different types of data (Person, Address, Internet, etc.)
86
- **BaseProvider/BaseDataProvider**: Foundation classes that handle localization and random number generation
87
- **Generic Provider**: Unified interface that provides access to all individual providers
88
- **Schema System**: High-level tools for generating structured data with export capabilities
89
- **Enumerations**: Type-safe constants for configuring data generation
90
- **Locales**: Support for 35+ locales with appropriate regional data
91

92
This architecture enables developers to use mimesis flexibly, from simple single-value generation to complex multi-field data structures, while maintaining consistent APIs across all data types.
93

94
## Capabilities
95

96
### Core Provider System
97

98
Foundation classes and the unified Generic provider that enable consistent data generation patterns across all data types.
99

100
```python { .api }
101
class BaseProvider:
102
    def reseed(self, seed: int = None) -> None: ...
103
    def validate_enum(self, item, enum) -> Any: ...
104

105
class BaseDataProvider(BaseProvider):
106
    def get_current_locale(self) -> str: ...
107
    def override_locale(self, locale): ...
108

109
class Generic:
110
    def __init__(self, locale: Locale = Locale.DEFAULT): ...
111
    def reseed(self, seed: int = None) -> None: ...
112
    def add_provider(self, cls, **kwargs) -> None: ...
113
```
114

115
[Core Providers](./core-providers.md)
116

117
### Personal Data Generation
118

119
Generate realistic personal information including names, demographics, contact details, and identification data with proper localization support.
120

121
```python { .api }
122
class Person(BaseDataProvider):
123
    def full_name(self, gender: Gender = None) -> str: ...
124
    def first_name(self, gender: Gender = None) -> str: ...
125
    def surname(self, gender: Gender = None) -> str: ...
126
    def email(self) -> str: ...
127
    def phone_number(self, mask: str = "", placeholder: str = "#") -> str: ...
128
    def birthdate(self, min_year: int = 1980, max_year: int = 2023) -> datetime.date: ...
129
```
130

131
[Personal Data](./personal-data.md)
132

133
### Location and Address Data
134

135
Generate geographical and address information including streets, cities, countries, coordinates, and postal codes with locale-appropriate formatting.
136

137
```python { .api }
138
class Address(BaseDataProvider):
139
    def address(self) -> str: ...
140
    def street_name(self) -> str: ...
141
    def city(self) -> str: ...
142
    def state(self, abbr: bool = False) -> str: ...
143
    def country(self) -> str: ...
144
    def postal_code(self) -> str: ...
145
    def coordinates(self, dms: bool = False) -> dict: ...
146
```
147

148
[Location Data](./location-data.md)
149

150
### Internet and Network Data
151

152
Generate internet-related data including IP addresses, domains, URLs, user agents, and network protocols with proper formatting and validation.
153

154
```python { .api }
155
class Internet(BaseProvider):
156
    def url(self) -> str: ...
157
    def ip_v4(self) -> str: ...
158
    def ip_v6(self) -> str: ...
159
    def mac_address(self) -> str: ...
160
    def user_agent(self) -> str: ...
161
```
162

163
[Internet Data](./internet-data.md)
164

165
### Date and Time Generation
166

167
Generate dates, times, timestamps, and time-related data with flexible date ranges, formatting options, and timezone support.
168

169
```python { .api }
170
class Datetime(BaseDataProvider):
171
    def date(self, start: int = 2000, end: int = 2023) -> datetime.date: ...
172
    def time(self) -> datetime.time: ...
173
    def datetime(self, start: int = 2000, end: int = 2023) -> datetime.datetime: ...
174
    def formatted_date(self, fmt: str = "", **kwargs) -> str: ...
175
    def timezone(self, region: TimezoneRegion = None) -> str: ...
176
```
177

178
[Date and Time](./datetime.md)
179

180
### Financial and Business Data
181

182
Generate financial data including currencies, prices, company information, stock data, and banking details with proper formatting.
183

184
```python { .api }
185
class Finance(BaseDataProvider):
186
    def company(self) -> str: ...
187
    def currency_iso_code(self, allow_random: bool = False) -> str: ...
188
    def price(self, minimum: float = 500, maximum: float = 1500) -> float: ...
189
    def bank(self) -> str: ...
190
    def stock_ticker(self) -> str: ...
191
```
192

193
[Financial Data](./financial-data.md)
194

195
### Text and Content Generation
196

197
Generate textual content including words, sentences, paragraphs, colors, and various text-based data with locale-appropriate content.
198

199
```python { .api }
200
class Text(BaseDataProvider):
201
    def word(self) -> str: ...
202
    def words(self, quantity: int = 5) -> list[str]: ...
203
    def sentence(self) -> str: ...
204
    def text(self, quantity: int = 5) -> str: ...
205
    def title(self) -> str: ...
206
    def color(self) -> str: ...
207
    def hex_color(self, safe: bool = False) -> str: ...
208
```
209

210
[Text Content](./text-content.md)
211

212
### Specialized Data Providers
213

214
Additional providers for specific domains including development data, scientific data, file information, hardware specs, transportation data, cryptographic utilities, and payment information.
215

216
```python { .api }
217
class Development(BaseProvider):
218
    def programming_language(self) -> str: ...
219
    def software_license(self) -> str: ...
220
    def version(self) -> str: ...
221

222
class Science(BaseProvider):
223
    def dna_sequence(self, length: int = 10) -> str: ...
224
    def rna_sequence(self, length: int = 10) -> str: ...
225

226
class Hardware(BaseProvider):
227
    def cpu(self) -> str: ...
228
    def resolution(self) -> str: ...
229
    def manufacturer(self) -> str: ...
230

231
class Cryptographic(BaseProvider):
232
    def uuid(self) -> str: ...
233
    def hash(self, algorithm: Algorithm = Algorithm.MD5) -> str: ...
234

235
class Payment(BaseDataProvider):
236
    def credit_card_number(self, card_type: CardType = None) -> str: ...
237
    def paypal(self) -> str: ...
238

239
class Transport(BaseDataProvider):
240
    def car(self) -> str: ...
241
    def airplane(self) -> str: ...
242

243
class Food(BaseDataProvider):
244
    def vegetable(self) -> str: ...
245
    def fruit(self) -> str: ...
246

247
class File(BaseProvider):
248
    def extension(self) -> str: ...
249
    def file_name(self) -> str: ...
250

251
class Numeric(BaseProvider):
252
    def integer_number(self, start: int = -1000, end: int = 1000) -> int: ...
253
    def decimal_number(self, start: float = -1000.0, end: float = 1000.0) -> Decimal: ...
254

255
class Choice(BaseProvider):
256
    def choice(self, *args, **kwargs) -> Any: ...
257
```
258

259
[Specialized Providers](./specialized-providers.md)
260

261
### Schema-Based Data Generation
262

263
High-level tools for generating structured data with export capabilities, enabling bulk data creation for testing and development.
264

265
```python { .api }
266
class Field:
267
    def __init__(self, locale: Locale = Locale.DEFAULT): ...
268
    def __call__(self, *args, **kwargs) -> Any: ...
269
    def register_handler(self, field_name: str, field_handler) -> None: ...
270

271
class Schema:
272
    def __init__(self, schema: callable, iterations: int = 1): ...
273
    def create(self) -> list[dict]: ...
274
    def to_csv(self, file_path: str, **kwargs) -> None: ...
275
    def to_json(self, file_path: str, **kwargs) -> None: ...
276
```
277

278
[Schema System](./schema.md)
279

280
### Configuration and Utilities
281

282
Enumerations, locale management, utility functions, and plugin integrations that support and configure the data generation system.
283

284
```python { .api }
285
class Locale(Enum):
286
    EN = "en"
287
    EN_US = "en-us"
288
    DE = "de"
289
    FR = "fr"
290
    # ... 35+ locales
291

292
def luhn_checksum(num: str) -> str: ...
293
def romanize(locale: Locale) -> callable: ...
294
```
295

296
[Configuration](./configuration.md)
297

298
## Types
299

300
```python { .api }
301
from enum import Enum
302
from typing import Union, Optional, Dict, List, Any, Callable
303
from datetime import date, time, datetime
304
from decimal import Decimal
305

306
# Core types
307
Seed = Optional[int]
308
JSON = Dict[str, Any]
309
Matrix = List[List[Any]]
310

311
# Configuration enums
312
class Gender(Enum):
313
    MALE = "male"
314
    FEMALE = "female"
315

316
class TitleType(Enum):
317
    TYPICAL = "typical"
318
    ACADEMIC = "academic"
319

320
class CountryCode(Enum):
321
    A2 = "a2"  # ISO 3166-1 alpha-2
322
    A3 = "a3"  # ISO 3166-1 alpha-3
323
    NUMERIC = "numeric"
324

325
class TimezoneRegion(Enum):
326
    AFRICA = "africa"
327
    AMERICA = "america"
328
    ANTARCTICA = "antarctica"
329
    ARCTIC = "arctic"
330
    ASIA = "asia"
331
    ATLANTIC = "atlantic"
332
    AUSTRALIA = "australia"
333
    EUROPE = "europe"
334
    INDIAN = "indian"
335
    PACIFIC = "pacific"
336

337
class Algorithm(Enum):
338
    MD5 = "md5"
339
    SHA1 = "sha1"
340
    SHA224 = "sha224"
341
    SHA256 = "sha256"
342
    SHA384 = "sha384"
343
    SHA512 = "sha512"
344

345
class CardType(Enum):
346
    VISA = "visa"
347
    MASTERCARD = "mastercard"
348
    AMERICAN_EXPRESS = "american_express"
349
    DISCOVER = "discover"
350
```