API

This part of the documentation covers all the public interfaces of Mimesis.

Random module

class mimesis.random.Random(x=None)

A custom random class.

It is a subclass of the random.Random class from the standard library’s random module. The class incorporates additional custom methods.

This class can be extended according to specific requirements.

choice_enum_item(enum)

Get random value of enum object.

Parameters:

enum (Any) – Enum object.

Return type:

Any

Returns:

Random value of enum.

generate_string_by_mask(mask='@###', char='@', digit='#')

Generate custom code using ascii uppercase and random integers.

Parameters:

• mask (str) – Mask of code.

• char (str) – Placeholder for characters.

• digit (str) – Placeholder for digits.

Return type:

str

Returns:

Custom code.

randbytes(n=16)

Generate n random bytes.

Return type:

bytes

randints(n=3, a=1, b=100)

Generate a list of random integers.

Parameters:

• n (int) – Number of elements.

• a (int) – Minimum value of range.

• b (int) – Maximum value of range.

Return type:

list[int]

Returns:

List of random integers.

Raises:

ValueError – if the number is less or equal to zero.

uniform(a, b, precision=15)

Get a random number in the range [a, b) or [a, b] depending on rounding.

Parameters:

• a (float) – Minimum value.

• b (float) – Maximum value.

• precision (int) – Round a number to a given precision in decimal digits, default is 15.

Return type:

float

weighted_choice(choices)

Returns a random element according to the specified weights.

Parameters:

choices (dict[Any, float]) – A dictionary where keys are choices and values are weights.

Raises:

ValueError – If choices are empty.

Return type:

Any

Returns:

Random key from dictionary.

Keys module

The module mimesis.keys provides a set of key functions.

Key functions can be applied to fields and fieldsets using the key argument. These functions are applied after the field’s value is generated and before the field is returned to the caller.

mimesis.keys.maybe(value, probability=0.5)

Return a closure (a key function).

The returned closure itself returns either value or the first argument passed to closure with a certain probability (0.5 by default).

Parameters:

• value (Any) – The value that may be returned.

• probability (float) – The probability of returning value.

Return type:

Callable[[Any, Random], Any]

Returns:

A closure that takes two arguments.

mimesis.keys.romanize(locale)

Create a closure function to romanize a given string in the specified locale.

Supported locales are:

• Locale.RU (Russian)

• Locale.UK (Ukrainian)

• Locale.KK (Kazakh)

Parameters:

locale (Locale) – Locale.

Return type:

Callable[[str], str]

Returns:

A closure that takes a string and returns a romanized string.

Builtin Data Providers

BrazilSpecProvider

class mimesis.builtins.BrazilSpecProvider(seed=<mimesis.types._MissingSeed object>)

Class that provides special data for Brazil (pt-br).

__init__(seed=<mimesis.types._MissingSeed object>)

Initialize attributes.

cnpj(with_mask=True)

Get a random CNPJ.

Parameters:

with_mask (bool) – Use cnpj mask (###.###.###-##)

Return type:

str

Returns:

Random cnpj.

Example:

77.732.230/0001-70

cpf(with_mask=True)

Get a random CPF.

Parameters:

with_mask (bool) – Use CPF mask (###.###.###-##).

Return type:

str

Returns:

Random CPF.

Example:

001.137.297-40

DenmarkSpecProvider

class mimesis.builtins.DenmarkSpecProvider(seed=<mimesis.types._MissingSeed object>)

Class that provides special data for Denmark (da).

__init__(seed=<mimesis.types._MissingSeed object>)

Initialize attributes.

cpr()

Generate a random CPR number (Central Person Registry).

Return type:

str

Returns:

CPR number.

Example:

0405420694

NetherlandsSpecProvider

class mimesis.builtins.NetherlandsSpecProvider(seed=<mimesis.types._MissingSeed object>)

Class that provides special data for the Netherlands (nl).

__init__(seed=<mimesis.types._MissingSeed object>)

Initialize attributes.

bsn()

Generate a random, but valid Burgerservicenummer.

Return type:

str

Returns:

Random BSN.

Example:

255159705

burgerservicenummer()

Generate a random, but valid Burgerservicenummer.

An alias for self.bsn()

Return type:

str

RussiaSpecProvider

class mimesis.builtins.RussiaSpecProvider(seed=<mimesis.types._MissingSeed object>)

Class that provides special data for Russia (ru).

class Meta

The name of the provider.

__init__(seed=<mimesis.types._MissingSeed object>)

Initialize attributes.

bic()

Generate random BIC (Bank ID Code).

Return type:

str

Returns:

BIC.

Example:

generate_sentence()

Generate sentence from the parts.

Return type:

str

Returns:

Sentence.

inn()

Generate random, but valid INN.

Return type:

str

Returns:

INN.

kpp()

Generate random KPP.

Return type:

str

Returns:

‘KPP’.

Example:

ogrn()

Generate random valid OGRN.

Return type:

str

Returns:

OGRN.

Example:

passport_number()

Generate random passport number.

Return type:

int

Returns:

Number.

Example:

560430

passport_series(year=None)

Generate random series of passport.

Parameters:

year (int or None) – Year of manufacture.

Return type:

str

Returns:

Series.

Example:

02 15.

patronymic(gender=None)

Generate random patronymic name.

Parameters:

gender (Optional[Gender]) – Gender of person.

Return type:

str

Returns:

Patronymic name.

Example:

Алексеевна.

series_and_number()

Generate a random passport number and series.

Return type:

str

Returns:

Series and number.

Example:

57 16 805199.

snils()

Generate snils with a special algorithm.

Return type:

str

Returns:

SNILS.

Example:

UkraineSpecProvider

class mimesis.builtins.UkraineSpecProvider(seed=<mimesis.types._MissingSeed object>)

Class that provides special data for Ukraine (uk).

__init__(seed=<mimesis.types._MissingSeed object>)

Initialize attributes.

patronymic(gender=None)

Generate random patronymic name.

Parameters:

gender (str or int) – Gender of person.

Return type:

str

Returns:

Patronymic name.

USASpecProvider

class mimesis.builtins.USASpecProvider(seed=<mimesis.types._MissingSeed object>)

Class that provides special data for the USA (en).

__init__(seed=<mimesis.types._MissingSeed object>)

Initialize attributes.

ssn()

Generate a random, but valid SSN.

Return type:

str

Returns:

SSN.

Example:

569-66-5801

tracking_number(service='usps')

Generate random tracking number.

Supported services: USPS, FedEx and UPS.

Parameters:

service (str) – Post service.

Return type:

str

Returns:

Tracking number.

PolandSpecProvider

class mimesis.builtins.PolandSpecProvider(seed=<mimesis.types._MissingSeed object>)

Class that provides special data for Poland (pl).

__init__(seed=<mimesis.types._MissingSeed object>)

Initialize attributes.

nip()

Generate random valid 10-digit NIP.

Return type:

str

Returns:

Valid 10-digit NIP

pesel(birth_date=None, gender=None)

Generate random 11-digit PESEL.

Parameters:

• birth_date (Optional[datetime]) – Initial birthdate (optional)

• gender (Optional[Gender]) – Gender of the person.

Return type:

str

Returns:

Valid 11-digit PESEL

regon()

Generate random valid 9-digit REGON.

Return type:

str

Returns:

Valid 9-digit REGON

Shortcuts

This module provides internal util functions.

mimesis.shortcuts.luhn_checksum(num)

Calculate a checksum for num using the Luhn algorithm.

Used to validate credit card numbers, IMEI numbers, and other identification numbers.

Parameters:

num (str) – The number to calculate a checksum for as a string.

Return type:

str

Returns:

Checksum for number.

Custom Exceptions

Custom exceptions which are used in Mimesis.

exception mimesis.exceptions.AliasesTypeError

Raised when the aliases attribute is set to a format other than a flat dictionary.

exception mimesis.exceptions.FieldArityError

Raised when registering field handler has incompatible arity.

exception mimesis.exceptions.FieldError(name=None)

Raised when field is not found.

exception mimesis.exceptions.FieldNameError(name=None)

Raised when a field name is invalid.

exception mimesis.exceptions.FieldsetError

Raised when a resulting fieldset is empty.

exception mimesis.exceptions.LocaleError(locale)

Raised when a locale isn’t supported.

exception mimesis.exceptions.NonEnumerableError(enum_obj)

Raised when an object is not an instance of Enum.

exception mimesis.exceptions.SchemaError

Raised when a schema is unsupported.

Base Providers

BaseProvider

class mimesis.providers.BaseProvider(*, seed=<mimesis.types._MissingSeed object>, random=None)

This is a base class for all providers.

Attr:

random: An instance of mimesis.random.Random.

Attr:

seed: Seed for random.

__init__(*, seed=<mimesis.types._MissingSeed object>, random=None)

Initialize attributes.

Keep in mind that locale-independent data providers will work only with keyword-only arguments.

Parameters:

• seed (UnionType[None, int, float, str, bytes, bytearray, _MissingSeed]) – Seed for random. When set to None the current system time is used.

• random (Optional[Random]) – Custom random. See https://github.com/lk-geimfari/mimesis/issues/1313 for details.

reseed(seed=<mimesis.types._MissingSeed object>)

Reseeds the internal random generator.

In case we use the default seed, we need to create a per instance random generator. In this case, two providers with the same seed will always return the same values.

Parameters:

seed (UnionType[None, int, float, str, bytes, bytearray, _MissingSeed]) – Seed for random. When set to None the current system time is used.

Return type:

None

validate_enum(item, enum)

Validates various enum objects that are used as arguments for methods.

Parameters:

• item (Any) – Item of an enum object.

• enum (Any) – Enum object.

Return type:

Any

Returns:

Value of item.

Raises:

NonEnumerableError – If enums has not such an item.

BaseDataProvider

class mimesis.providers.BaseDataProvider(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>, *args, **kwargs)

This is a base class for all data providers.

__init__(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>, *args, **kwargs)

Initialize attributes for data providers.

Parameters:

• locale (Locale) – Current locale.

• seed (UnionType[None, int, float, str, bytes, bytearray, _MissingSeed]) – Seed to all the random functions.

get_current_locale()

Returns current locale.

If locale is not defined, then this method will always return en, because en is default locale for all providers, excluding builtins.

Return type:

str

Returns:

Current locale.

override_locale(locale)

Context manager that allows overriding current locale.

Temporarily overrides current locale for locale-dependent providers.

Parameters:

locale (Locale) – Locale.

Return type:

Generator[BaseDataProvider, None, None]

Returns:

Provider with overridden locale.

update_dataset(data)

Updates dataset merging a given dict into default data.

This method may be useful when you need to override data for a given key in JSON file.

Return type:

None

Generic Providers

Generic

class mimesis.Generic(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>)

Class which contain all providers at one.

class Meta

Class for metadata.

__init__(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>)

Initialize attributes lazily.

add_provider(cls, **kwargs)

Adds a custom provider to a Generic() object.

Parameters:

• cls (Type[BaseProvider]) – Custom provider.

• kwargs (Any) – Keyword arguments for provider.

Raises:

TypeError – if cls is Generic, if cls is not class or is not a subclass of BaseProvider.

Return type:

None

Returns:

Absolutely none.

add_providers(*providers)

Adds multiple custom providers to a Generic() object.

This method is a convenience method for adding multiple providers at once. It is equivalent to calling add_provider() for each provider in the list of providers.

Example:

>>> from mimesis import Generic
>>> from myproviders import ProviderA, ProviderB
>>> g = Generic()
>>> g.add_providers(ProviderA, ProviderB)
>>> g.providera.never()
>>> g.providerb.gonna()

If you want to pass keyword arguments to the providers, you can do so by using add_provider() instead.

Parameters:

providers (Type[BaseProvider]) – Custom providers.

Return type:

None

Returns:

None

reseed(seed=<mimesis.types._MissingSeed object>)

Reseed the internal random generator.

Overrides method BaseProvider.reseed().

Parameters:

seed (UnionType[None, int, float, str, bytes, bytearray, _MissingSeed]) – Seed for random.

Return type:

None

Returns:

None.

Locale-Dependent Providers

Address

class mimesis.Address(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>, *args, **kwargs)

Class for generate fake address data.

This object provides all the data related to geographical location.

address()

Generates a random full address.

Return type:

str

Returns:

Full address.

calling_code()

Generates a random calling code of random country.

Return type:

str

Returns:

Calling code.

city()

Generates a random city.

Return type:

str

Returns:

City name.

continent(code=False)

Returns a random continent name or continent code.

Parameters:

code (bool) – Return code of a continent.

Return type:

str

Returns:

Continent name.

coordinates(dms=False)

Generates random geo coordinates.

Parameters:

dms (bool) – DMS format.

Return type:

dict[str, str | float]

Returns:

Dict with coordinates.

country()

Generates a random country.

Return type:

str

Returns:

The Country.

country_code(code=CountryCode.A2)

Generates a random code of country.

Default format is A2 (ISO 3166-1-alpha2), you can change it by passing parameter fmt.

Parameters:

code (Optional[CountryCode]) – Country code.

Return type:

str

Returns:

Country code in selected format.

Raises:

KeyError – if fmt is not supported.

country_emoji_flag()

Generates a randomly chosen country emoji flag.

Example:

🇹🇷

Return type:

str

Returns:

Flag emoji.

default_country()

Returns the country associated with the current locale.

Return type:

str

Returns:

The country associated with current locale.

federal_subject(*args, **kwargs)

Generates a random federal_subject (Russia).

An alias for state().

Return type:

str

isd_code()

Generates a random ISD code.

An alias for calling_code().

Return type:

str

latitude(dms=False)

Generates a random value of latitude.

Parameters:

dms (bool) – DMS format.

Return type:

str | float

Returns:

Value of longitude.

longitude(dms=False)

Generates a random value of longitude.

Parameters:

dms (bool) – DMS format.

Return type:

str | float

Returns:

Value of longitude.

postal_code()

Generates a postal code for current locale.

Return type:

str

Returns:

Postal code.

prefecture(*args, **kwargs)

Generates a random prefecture.

An alias for state().

Return type:

str

province(*args, **kwargs)

Generates a random province.

An alias for state().

Return type:

str

region(*args, **kwargs)

Generates a random region.

An alias for state().

Return type:

str

state(abbr=False)

Generates a random administrative district of the country.

Parameters:

abbr (bool) – Return ISO 3166-2 code.

Return type:

str

Returns:

Administrative district.

street_name()

Generates a random street name.

Return type:

str

Returns:

Street name.

street_number(maximum=1400)

Generates a random street number.

Parameters:

maximum (int) – Maximum value.

Return type:

str

Returns:

Street number.

street_suffix()

Generates a random street suffix.

Return type:

str

Returns:

Street suffix.

zip_code()

Generates a zip code.

An alias for postal_code().

Return type:

str

Returns:

Zip code.

Finance

class mimesis.Finance(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>, *args, **kwargs)

Class to generate finance and business related data.

bank()

Generates a random bank name.

Return type:

str

Returns:

Bank name.

company()

Generates a random company name.

Return type:

str

Returns:

Company name.

company_type(abbr=False)

Generates a random type of business entity.

Parameters:

abbr (bool) – Abbreviated company type.

Return type:

str

Returns:

Types of business entity.

cryptocurrency_iso_code()

Generates a random cryptocurrency ISO code.

Return type:

str

Returns:

Symbol of cryptocurrency.

cryptocurrency_symbol()

Get a cryptocurrency symbol.

Return type:

str

Returns:

Symbol of cryptocurrency.

currency_iso_code(allow_random=False)

Returns a currency code for current locale.

Parameters:

allow_random (bool) – Get a random ISO code.

Return type:

str

Returns:

Currency code.

currency_symbol()

Returns a currency symbol for current locale.

Return type:

str

Returns:

Currency symbol.

price(minimum=500, maximum=1500)

Generate a random price.

Parameters:

• minimum (float) – Minimum value of price.

• maximum (float) – Maximum value of price.

Return type:

float

Returns:

Price.

price_in_btc(minimum=0, maximum=2)

Generates a random price in BTC.

Parameters:

• minimum (float) – Minimum value of price.

• maximum (float) – Maximum value of price.

Return type:

float

Returns:

Price in BTC.

stock_exchange()

Generates a stock exchange name.

Return type:

str

Returns:

Returns exchange name.

stock_name()

Generates a stock name.

Return type:

str

Returns:

Stock name.

stock_ticker()

Generates a random stock ticker.

Return type:

str

Returns:

Ticker.

Datetime

class mimesis.Datetime(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>, *args, **kwargs)

Class for generating data related to the date and time.

static bulk_create_datetimes(date_start, date_end, **kwargs)

Bulk create datetime objects.

This method creates a list of datetime objects from date_start to date_end.

You can use the following keyword arguments:

• days

• hours

• minutes

• seconds

• microseconds

Warning

Empty **kwargs produces timedelta(0) which obviously cannot be used as step, so you have to pass valid **kwargs for datetime.timedelta which will be used as a step by which date_start will be incremented until it reaches date_end to avoid infinite loop which eventually leads to OverflowError.

See datetime.timedelta for more details.

Parameters:

• date_start (datetime) – Begin of the range.

• date_end (datetime) – End of the range.

• kwargs (Any) – Keyword arguments for datetime.timedelta

Return type:

list[datetime]

Returns:

List of datetime objects

Raises:

ValueError: When date_start/date_end not passed, when date_start larger than date_end or when the given keywords for datetime.timedelta represent a non-positive timedelta.

century()

Generates a random century.

Return type:

str

Returns:

Century.

date(start=2000, end=2024)

Generates a random date object.

Parameters:

• start (int) – Minimum value of year.

• end (int) – Maximum value of year.

Return type:

date

Returns:

Formatted date.

datetime(start=2024, end=2024, timezone=None)

Generates random datetime.

Parameters:

• start (int) – Minimum value of year.

• end (int) – Maximum value of year.

• timezone (Optional[str]) – Set custom timezone (pytz required).

Return type:

datetime

Returns:

Datetime

day_of_month()

Generates a random day of the month, from 1 to 31.

Return type:

int

Returns:

Random value from 1 to 31.

day_of_week(abbr=False)

Generates a random day of the week.

Parameters:

abbr (bool) – Abbreviated day name.

Return type:

str

Returns:

Day of the week.

formatted_date(fmt='', **kwargs)

Generates random date as string.

Parameters:

• fmt (str) – The format of date, if None then use standard accepted in the current locale.

• kwargs (Any) – Keyword arguments for date()

Return type:

str

Returns:

Formatted date.

formatted_datetime(fmt='', **kwargs)

Generates datetime string in human-readable format.

Parameters:

• fmt (str) – Custom format (default is format for current locale)

• kwargs (Any) – Keyword arguments for datetime()

Return type:

str

Returns:

Formatted datetime string.

formatted_time(fmt='')

Generates formatted time as string.

Parameters:

fmt (str) – The format of time, if None then use standard accepted in the current locale.

Return type:

str

Returns:

String formatted time.

gmt_offset()

Generates a random GMT offset value.

Return type:

str

Returns:

GMT Offset.

month(abbr=False)

Generates a random month of the year.

Parameters:

abbr (bool) – Abbreviated month name.

Return type:

str

Returns:

Month name.

periodicity()

Generates a random periodicity string.

Return type:

str

Returns:

Periodicity.

time()

Generates a random time object.

Return type:

time

Returns:

datetime.time object.

timestamp(fmt=TimestampFormat.POSIX, **kwargs)

Generates a random timestamp in given format.

Supported formats are:

• TimestampFormat.POSIX

• TimestampFormat.RFC_3339

• TimestampFormat.ISO_8601

Example:

>>> from mimesis import Datetime
>>> from mimesis.enums import TimestampFormat
>>> dt = Datetime()
>>> dt.timestamp(fmt=TimestampFormat.POSIX)
1697322442
>>> dt.timestamp(fmt=TimestampFormat.RFC_3339)
'2023-12-08T18:46:34'
>>> dt.timestamp(fmt=TimestampFormat.ISO_8601)
'2009-05-30T21:45:57.328600'

Parameters:

• fmt (TimestampFormat) – Format of timestamp (Default is TimestampFormat.POSIX).

• kwargs (Any) – Kwargs for datetime().

Return type:

str | int

Returns:

Timestamp.

timezone(region=None)

Generates a random timezone.

Parameters:

region (Optional[TimezoneRegion]) – Timezone region.

Return type:

str

Returns:

Timezone.

week_date(start=2017, end=2024)

Generates week number with year.

Parameters:

• start (int) – Starting year.

• end (int) – Ending year.

Return type:

str

Returns:

Week number.

year(minimum=1990, maximum=2024)

Generates a random year.

Parameters:

• minimum (int) – Minimum value.

• maximum (int) – Maximum value.

Return type:

int

Returns:

Year.

Food

class mimesis.Food(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>, *args, **kwargs)

Class for generating data related to food.

dish()

Generates a random dish name.

Return type:

str

Returns:

Dish name.

Example:

Ratatouille.

drink()

Generates a random drink name.

Return type:

str

Returns:

Drink name.

Example:

Vodka.

fruit()

Generates a random fruit or berry name.

Return type:

str

Returns:

Fruit name.

Example:

Banana.

spices()

Generates a random spices/herb name.

Return type:

str

Returns:

The name of the spices or herbs.

Example:

Anise.

vegetable()

Generates a random vegetable name.

Return type:

str

Returns:

Vegetable name.

Example:

Tomato.

Person

class mimesis.Person(*args, **kwargs)

Class for generating personal data.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:

• locale – Current locale.

• seed – Seed.

academic_degree()

Generates a random academic degree.

Return type:

str

Returns:

Degree.

Example:

Bachelor.

birthdate(min_year=1980, max_year=2023)

Generates a random birthdate as a datetime.date object.

Parameters:

• min_year (int) – Maximum birth year.

• max_year (int) – Minimum birth year.

Return type:

date

Returns:

Random date object.

blood_type()

Generates a random blood type.

Return type:

str

Returns:

Blood type (blood group).

Example:

A+

email(domains=None, unique=False)

Generates a random email.

Parameters:

• domains (Optional[Sequence[str]]) – List of custom domains for emails.

• unique (bool) – Makes email addresses unique.

Return type:

str

Returns:

Email address.

Raises:

ValueError – if «unique» is True and the provider was seeded.

Example:

foretime10@live.com

first_name(gender=None)

Generates a random first name.

..note: An alias for name().

Parameters:

gender (Optional[Gender]) – Gender’s enum object.

Return type:

str

Returns:

First name.

full_name(gender=None, reverse=False)

Generates a random full name.

Parameters:

• reverse (bool) – Return reversed full name.

• gender (Optional[Gender]) – Gender’s enum object.

Return type:

str

Returns:

Full name.

Example:

Johann Wolfgang.

gender()

Generates a random gender title.

Example:

Male

Return type:

str

gender_code()

Generate a random ISO/IEC 5218 gender code.

Generate a random title of gender code for the representation of human sexes is an international standard that defines a representation of human sexes through a language-neutral single-digit code or symbol of gender.

Codes for the representation of human sexes is an international standard (0 - not known, 1 - male, 2 - female, 9 - not applicable).

Return type:

int

Returns:

gender_symbol()

Generate a random sex symbol.

Example:

♂

Return type:

str

height(minimum=1.5, maximum=2.0)

Generates a random height in meters.

Parameters:

• minimum (float) – Minimum value.

• maximum (float) – Maximum value.

Return type:

str

Returns:

Height.

Example:

1.85.

identifier(mask='##-##/##')

Generates a random identifier by mask.

With this method, you can generate any identifiers that you need by specifying the mask.

Parameters:

mask (str) – The mask. Here @ is a placeholder for characters and # is placeholder for digits.

Return type:

str

Returns:

An identifier.

Example:

07-97/04

language()

Generates a random language name.

Return type:

str

Returns:

Random language.

Example:

Irish.

last_name(gender=None)

Generates a random last name.

..note: An alias for surname().

Parameters:

gender (Optional[Gender]) – Gender’s enum object.

Return type:

str

Returns:

Last name.

name(gender=None)

Generates a random name.

Parameters:

gender (Optional[Gender]) – Gender’s enum object.

Return type:

str

Returns:

Name.

Example:

John.

nationality(gender=None)

Generates a random nationality.

Parameters:

gender (Optional[Gender]) – Gender.

Return type:

str

Returns:

Nationality.

Example:

Russian

occupation()

Generates a random job.

Return type:

str

Returns:

The name of job.

Example:

Programmer.

password(length=8, hashed=False)

Generates a password or hash of password.

Parameters:

• length (int) – Length of password.

• hashed (bool) – SHA256 hash.

Return type:

str

Returns:

Password or hash of password.

Example:

k6dv2odff9#4h

phone_number(mask='', placeholder='#')

Generates a random phone number.

Parameters:

• mask (str) – Mask for formatting number.

• placeholder (str) – A placeholder for a mask (default is #).

Return type:

str

Returns:

Phone number.

Example:

+7-(963)-409-11-22.

political_views()

Get a random political views.

Return type:

str

Returns:

Political views.

Example:

Liberal.

sex()

An alias for method gender().

Return type:

str

Returns:

Sex.

surname(gender=None)

Generates a random surname.

Parameters:

gender (Optional[Gender]) – Gender’s enum object.

Return type:

str

Returns:

Surname.

Example:

Smith.

telephone(*args, **kwargs)

An alias for phone_number().

Return type:

str

title(gender=None, title_type=None)

Generates a random title for name.

You can generate a random prefix or suffix for name using this method.

Parameters:

• gender (Optional[Gender]) – The gender.

• title_type (Optional[TitleType]) – TitleType enum object.

Return type:

str

Returns:

The title.

Raises:

NonEnumerableError – if gender or title_type in incorrect format.

Example:

PhD.

university()

Generates a random university name.

Return type:

str

Returns:

University name.

Example:

MIT.

username(mask=None, drange=(1800, 2100))

Generates a username by mask.

Masks allow you to generate a variety of usernames.

• C stands for capitalized username.

• U stands for uppercase username.

• l stands for lowercase username.

• d stands for digits in the username.

You can also use symbols to separate the different parts of the username: . _ -

Parameters:

• mask (Optional[str]) – Mask.

• drange (tuple[int, int]) – Digits range.

Raises:

ValueError – If template is not supported.

Return type:

str

Returns:

Username as string.

Example:

>>> username(mask='C_C_d')
Cotte_Article_1923
>>> username(mask='U.l.d')
ELKINS.wolverine.2013
>>> username(mask='l_l_d', drange=(1900, 2021))
plasmic_blockader_1907

views_on()

Get a random views on.

Return type:

str

Returns:

Views on.

Example:

Negative.

weight(minimum=38, maximum=90)

Generates a random weight in Kg.

Parameters:

• minimum (int) – min value

• maximum (int) – max value

Return type:

int

Returns:

Weight.

Example:

worldview()

Generates a random worldview.

Return type:

str

Returns:

Worldview.

Example:

Pantheism.

Text

class mimesis.Text(*args, **kwargs)

Class for generating text data.

__init__(*args, **kwargs)

Initialize attributes.

alphabet(lower_case=False)

Returns an alphabet for current locale.

Parameters:

lower_case (bool) – Return alphabet in lower case.

Return type:

list[str]

Returns:

Alphabet.

answer()

Generates a random answer in the current language.

Return type:

str

Returns:

An answer.

Example:

No

color()

Generates a random color name.

Return type:

str

Returns:

Color name.

Example:

Red.

emoji(category=EmojyCategory.DEFAULT)

Generates a random emoji from the specified category.

Generates a random emoji from the specified category. If the category is not specified, a random emoji from any category will be returned.

Parameters:

category (Optional[EmojyCategory]) – EmojyCategory.

Raises:

NonEnumerableError – When category is not supported.

Return type:

str

Returns:

Emoji code.

Example:

😟

hex_color(safe=False)

Generates a random HEX color.

Parameters:

safe (bool) – Get safe Flat UI hex color.

Return type:

str

Returns:

Hex color code.

Example:

#d8346b

level()

Generates a word that indicates a level of something.

Return type:

str

Returns:

Level.

Example:

critical.

quote()

Generates a random quote.

Return type:

str

Returns:

Random quote.

Example:

“Bond… James Bond.”

rgb_color(safe=False)

Generates a random RGB color tuple.

Parameters:

safe (bool) – Get safe RGB tuple.

Return type:

tuple[int, ...]

Returns:

RGB tuple.

Example:

(252, 85, 32)

sentence()

Generates a random sentence from the text.

Return type:

str

Returns:

Sentence.

text(quantity=5)

Generates the text.

Parameters:

quantity (int) – Quantity of sentences.

Return type:

str

Returns:

Text.

title()

Generates a random title.

Return type:

str

Returns:

The title.

word()

Generates a random word.

Return type:

str

Returns:

Single word.

Example:

Science.

words(quantity=5)

Generates a list of random words.

Parameters:

quantity (int) – Quantity of words. Default is 5.

Return type:

list[str]

Returns:

Word list.

Example:

[science, network, god, octopus, love]

Locale-Independent Providers

BinaryFile

class mimesis.BinaryFile(*args, **kwargs)

Class for generating binary data

__init__(*args, **kwargs)

Initialize attributes.

Parameters:

• locale – Current locale.

• seed – Seed.

audio(*, file_type=AudioFile.MP3)

Generates an audio file of given format and returns it as bytes.

Note

This method accepts keyword-only arguments.

Parameters:

file_type (AudioFile) – File extension.

Return type:

bytes

Returns:

File as a sequence of bytes.

compressed(*, file_type=CompressedFile.ZIP)

Generates a compressed file of given format and returns it as bytes.

Note

This method accepts keyword-only arguments.

Parameters:

file_type (CompressedFile) – File extension.

Return type:

bytes

Returns:

File as a sequence of bytes.

document(*, file_type=DocumentFile.PDF)

Generates a document of given format and returns it as bytes.

Note

This method accepts keyword-only arguments.

Parameters:

file_type (DocumentFile) – File extension.

Return type:

bytes

Returns:

File as a sequence of bytes.

image(*, file_type=ImageFile.PNG)

Generates an image of given format and returns it as bytes.

Note

This method accepts keyword-only arguments.

Parameters:

file_type (ImageFile) – File extension.

Return type:

bytes

Returns:

File as a sequence of bytes.

video(*, file_type=VideoFile.MP4)

Generates video file of given format and returns it as bytes.

Note

This method accepts keyword-only arguments.

Parameters:

file_type (VideoFile) – File extension.

Return type:

bytes

Returns:

File as a sequence of bytes.

Code

class mimesis.Code(*, seed=<mimesis.types._MissingSeed object>, random=None)

A class, which provides methods for generating codes.

ean(fmt=None)

Generates EAN.

To change an EAN format, pass parameter code with needed value of the enum object EANFormat.

Parameters:

fmt (Optional[EANFormat]) – Format of EAN.

Return type:

str

Returns:

EAN.

Raises:

NonEnumerableError – if code is not enum EANFormat.

imei()

Generates a random IMEI.

Return type:

str

Returns:

IMEI.

isbn(fmt=None, locale=Locale.EN)

Generates ISBN for current locale.

To change ISBN format, pass parameter code with needed value of the enum object ISBNFormat

Parameters:

• fmt (Optional[ISBNFormat]) – ISBN format.

• locale (Locale) – Locale code.

Return type:

str

Returns:

ISBN.

Raises:

NonEnumerableError – if code is not enum ISBNFormat.

issn(mask='####-####')

Generates a random ISSN.

Parameters:

mask (str) – Mask of ISSN.

Return type:

str

Returns:

ISSN.

locale_code()

Generates a random locale code (MS-LCID).

See Windows Language Code Identifier Reference for more information.

Return type:

str

Returns:

Locale code.

pin(mask='####')

Generates a random PIN code.

Parameters:

mask (str) – Mask of pin code.

Return type:

str

Returns:

PIN code.

Choice

class mimesis.Choice(*, seed=<mimesis.types._MissingSeed object>, random=None)

Class for generating a random choice from items in a sequence.

choice(*args, **kwargs)

Choice random item form sequence.

See https://github.com/lk-geimfari/mimesis/issues/619

Parameters:

• args (Any) – Positional arguments.

• kwargs (Any) – Keyword arguments.

Return type:

Any

Returns:

Sequence or uncontained element randomly chosen from items.

Cryptographic

class mimesis.Cryptographic(*, seed=<mimesis.types._MissingSeed object>, random=None)

Class that provides cryptographic data.

hash(algorithm=None)

Generates random hash.

To change hashing algorithm, pass parameter algorithm with needed value of the enum object Algorithm

Warning

Seed is not applicable to this method, because of its cryptographic-safe nature.

Parameters:

algorithm (Optional[Algorithm]) – Enum object Algorithm.

Return type:

str

Returns:

Hash.

Raises:

NonEnumerableError – When algorithm is unsupported.

mnemonic_phrase()

Generates BIP-39 looking mnemonic phrase.

Return type:

str

Returns:

Mnemonic phrase.

static token_bytes(entropy=32)

Generates byte string containing entropy bytes.

The string has entropy random bytes, each byte converted to two hex digits.

Warning

Seed is not applicable to this method, because of its cryptographic-safe nature.

Parameters:

entropy (int) – Number of bytes (default: 32).

Return type:

bytes

Returns:

Random bytes.

static token_hex(entropy=32)

Generates a random text string, in hexadecimal.

The string has entropy random bytes, each byte converted to two hex digits. If entropy is None or not supplied, a reasonable default is used.

Warning

Seed is not applicable to this method, because of its cryptographic-safe nature.

Parameters:

entropy (int) – Number of bytes (default: 32).

Return type:

str

Returns:

Token.

static token_urlsafe(entropy=32)

Generates a random URL-safe text string, in Base64 encoding.

The string has entropy random bytes. If entropy is None or not supplied, a reasonable default is used.

Warning

Seed is not applicable to this method, because of its cryptographic-safe nature.

Parameters:

entropy (int) – Number of bytes (default: 32).

Return type:

str

Returns:

URL-safe token.

uuid()

Generates UUID4 string.

Return type:

str

Returns:

UUID4 as string.

static uuid_object()

Generates UUID4 object.

Return type:

UUID

Returns:

UUID4 object.

Development

class mimesis.Development(*args, **kwargs)

Class for getting fake data for Developers.

__init__(*args, **kwargs)

Initialize attributes.

Keep in mind that locale-independent data providers will work only with keyword-only arguments.

Parameters:

• seed – Seed for random. When set to None the current system time is used.

• random – Custom random. See https://github.com/lk-geimfari/mimesis/issues/1313 for details.

boolean()

Generates a random boolean value.

Return type:

bool

Returns:

True of False.

calver()

Generates a random calendar versioning string.

Return type:

str

Returns:

Calendar versioning string.

Example:

2016.11.08

ility()

Generates a random system quality attribute.

An alias for system_quality_attribute().

Return type:

str

os()

Generates a random operating system or distributive name.

Return type:

str

Returns:

The name of OS.

Example:

Gentoo

programming_language()

Generates a random programming language from the list.

Return type:

str

Returns:

Programming language.

Example:

Erlang.

software_license()

Generates a random software license.

Return type:

str

Returns:

License name.

Example:

The BSD 3-Clause License.

stage()

Generates a random stage of development.

Return type:

str

Returns:

Release stage.

Example:

Alpha.

system_quality_attribute()

Generates a random system quality attribute.

Within systems engineering, quality attributes are realized non-functional requirements used to evaluate the performance of a system. These are sometimes named “ilities” after the suffix many of the words share.

Return type:

str

Returns:

System quality attribute.

version()

Generates a random semantic versioning string.

Return type:

str

Returns:

Semantic versioning string.

Example:

0.2.1

File

class mimesis.File(*, seed=<mimesis.types._MissingSeed object>, random=None)

Class for generate data related to files.

extension(file_type=None)

Generates a random file extension.

Parameters:

file_type (Optional[FileType]) – Enum object FileType.

Return type:

str

Returns:

Extension of the file.

Example:

.py

file_name(file_type=None)

Generates a random file name with an extension.

Parameters:

file_type (Optional[FileType]) – Enum object FileType

Return type:

str

Returns:

File name.

Example:

legislative.txt

mime_type(type_=None)

Generates a random mime type.

Parameters:

type – Enum object MimeType.

Return type:

str

Returns:

Mime type.

size(minimum=1, maximum=100)

Generates a random file size as string.

Parameters:

• minimum (int) – Maximum value.

• maximum (int) – Minimum value.

Return type:

str

Returns:

Size of file.

Example:

56 kB

Hardware

class mimesis.Hardware(*, seed=<mimesis.types._MissingSeed object>, random=None)

Class for generate data related to hardware.

class Meta

Class for metadata.

cpu()

Generates a random CPU name.

Return type:

str

Returns:

CPU name.

Example:

Intel® Core i7.

cpu_codename()

Generates a random CPU code name.

Return type:

str

Returns:

CPU code name.

Example:

Cannonlake.

cpu_frequency()

Generates a random frequency of CPU.

Return type:

str

Returns:

Frequency of CPU.

Example:

4.0 GHz.

generation()

Generates a random generation.

Return type:

str

Returns:

Generation of something.

Example:

6th Generation.

graphics()

Generates a random graphics card name.

Return type:

str

Returns:

Graphics.

Example:

Intel® Iris™ Pro Graphics 6200.

manufacturer()

Generates a random manufacturer of hardware.

Return type:

str

Returns:

Manufacturer.

Example:

Dell.

phone_model()

Generates a random phone model.

Return type:

str

Returns:

Phone model.

Example:

Nokia Lumia 920.

ram_size()

Generates a random size of RAM.

Return type:

str

Returns:

RAM size.

Example:

16GB.

ram_type()

Generates a random RAM type.

Return type:

str

Returns:

Type of RAM.

Example:

DDR3.

resolution()

Generates a random screen resolution.

Return type:

str

Returns:

Resolution of screen.

Example:

1280x720.

screen_size()

Generates a random size of screen in inch.

Return type:

str

Returns:

Screen size.

Example:

13″.

ssd_or_hdd()

Generates a random type of disk.

Return type:

str

Returns:

HDD or SSD.

Example:

512GB SSD.

Internet

class mimesis.Internet(*args, **kwargs)

Class for generating data related to the internet.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:

• args (Any) – Arguments.

• kwargs (Any) – Keyword arguments.

content_type(mime_type=None)

Generates a random HTTP content type.

Return type:

str

Returns:

Content type.

Example:

application/json

dsn(dsn_type=None, **kwargs)

Generates a random DSN (Data Source Name).

Parameters:

• dsn_type (Optional[DSNType]) – DSN type.

• kwargs (Any) – Additional keyword-arguments for hostname method.

Return type:

str

hostname(tld_type=None, subdomains=None)

Generates a random hostname without a scheme.

Parameters:

• tld_type (Optional[TLDType]) – TLDType.

• subdomains (Optional[list[str]]) – List of subdomains (make sure they are valid).

Return type:

str

Returns:

Hostname.

http_method()

Generates a random HTTP method.

Return type:

str

Returns:

HTTP method.

Example:

POST

http_request_headers()

Generates a random HTTP request headers.

The following headers are included:

• Referer

• Authorization

• Cookie

• User-Agent

• X-CSRF-Token

• Content-Type

• Content-Length

• Connection

• Cache-Control

• Accept

• Host

• Accept-Language

Return type:

dict[str, Any]

Returns:

Request headers as dict.

http_response_headers()

Generates a random HTTP response headers.

The following headers are included:

• Allow

• Age

• Server

• Content-Type

• X-Request-ID

• Content-Language

• Content-Location

• Set-Cookie

• Upgrade-Insecure-Requests

• X-Content-Type-Options

• X-XSS-Protection

• Connection

• X-Frame-Options

• Content-Encoding

• Cross-Origin-Opener-Policy

• Cross-Origin-Resource-Policy

• Strict-Transport-Security

Return type:

dict[str, Any]

Returns:

Response headers as dict.

http_status_code()

Generates a random HTTP status code.

Return type:

int

Returns:

HTTP status.

Example:

200

http_status_message()

Generates a random HTTP status message.

Return type:

str

Returns:

HTTP status message.

Example:

200 OK

ip_v4()

Generates a random IPv4 address as string.

Example:

19.121.223.58

Return type:

str

ip_v4_object()

Generates a random ipaddress.IPv4Address object.

Return type:

IPv4Address

Returns:

ipaddress.IPv4Address object.

ip_v4_with_port(port_range=PortRange.ALL)

Generates a random IPv4 address as string.

Parameters:

port_range (PortRange) – PortRange enum object.

Return type:

str

Returns:

IPv4 address as string.

Example:

19.121.223.58:8000

ip_v6()

Generates a random IPv6 address as string.

Return type:

str

Returns:

IPv6 address string.

Example:

2001:c244:cf9d:1fb1:c56d:f52c:8a04:94f3

ip_v6_object()

Generates random ipaddress.IPv6Address object.

Return type:

IPv6Address

Returns:

ipaddress.IPv6Address object.

mac_address()

Generates a random MAC address.

Return type:

str

Returns:

Random MAC address.

Example:

00:16:3e:25:e7:f1

path(*args, **kwargs)

Generates a random path.

Parameters:

• args (Any) – Arguments to pass to slug().

• kwargs (Any) – Keyword arguments to pass to slug().

Return type:

str

Returns:

Path.

port(port_range=PortRange.ALL)

Generates a random port.

Parameters:

port_range (PortRange) – PortRange enum object.

Return type:

int

Returns:

Port number.

Raises:

NonEnumerableError – if port_range is not in PortRange.

Example:

8080

public_dns()

Generates a random public DNS.

Example:

1.1.1.1

Return type:

str

query_parameters(length=None)

Generates an arbitrary query parameters as a dict.

Parameters:

length (Optional[int]) – Length of query parameters dictionary (maximum is 32).

Return type:

dict[str, str]

Returns:

Dict of query parameters.

query_string(length=None)

Generates an arbitrary query string of given length.

Parameters:

length (Optional[int]) – Length of query string.

Return type:

str

Returns:

Query string.

slug(parts_count=None)

Generates a random slug of given parts count.

Parameters:

parts_count (Optional[int]) – Slug’s parts count.

Return type:

str

Returns:

Slug.

static stock_image_url(width=1920, height=1080, keywords=None)

Generates a random stock image URL hosted on Unsplash.

See «Random search term» on https://source.unsplash.com/ for more details.

Parameters:

• width (int | str) – Width of the image.

• height (int | str) – Height of the image.

• keywords (Union[list[str], set[str], tuple[str, ...], None]) – Sequence of search keywords.

Return type:

str

Returns:

URL of the image.

tld(*args, **kwargs)

Generates a random TLD.

An alias for top_level_domain()

Return type:

str

top_level_domain(tld_type=TLDType.CCTLD)

Generates random top level domain.

Parameters:

tld_type (TLDType) – Enum object enums.TLDType

Return type:

str

Returns:

Top level domain.

Raises:

NonEnumerableError – if tld_type not in enums.TLDType.

uri(scheme=URLScheme.HTTPS, tld_type=None, subdomains=None, query_params_count=None)

Generates a random URI.

Parameters:

• scheme (Optional[URLScheme]) – Scheme.

• tld_type (Optional[TLDType]) – TLDType.

• subdomains (Optional[list[str]]) – List of subdomains (make sure they are valid).

• query_params_count (Optional[int]) – Query params.

Return type:

str

Returns:

URI.

url(scheme=URLScheme.HTTPS, port_range=None, tld_type=None, subdomains=None)

Generates a random URL.

Parameters:

• scheme (Optional[URLScheme]) – The scheme.

• port_range (Optional[PortRange]) – PortRange enum object.

• tld_type (Optional[TLDType]) – TLDType.

• subdomains (Optional[list[str]]) – List of subdomains (make sure they are valid).

Return type:

str

Returns:

URL.

user_agent()

Get a random user agent.

Return type:

str

Returns:

User agent.

Example:

Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:15.0) Gecko/20100101 Firefox/15.0.1

Numeric

class mimesis.Numeric(*args, **kwargs)

A provider for generating numeric data.

__init__(*args, **kwargs)

Initialize attributes.

Keep in mind that locale-independent data providers will work only with keyword-only arguments.

Parameters:

• seed – Seed for random. When set to None the current system time is used.

• random – Custom random. See https://github.com/lk-geimfari/mimesis/issues/1313 for details.

complex_number(start_real=0.0, end_real=1.0, start_imag=0.0, end_imag=1.0, precision_real=15, precision_imag=15)

Generates a random complex number.

Parameters:

• start_real (float) – Start real range.

• end_real (float) – End real range.

• start_imag (float) – Start imaginary range.

• end_imag (float) – End imaginary range.

• precision_real (int) – Round a real part of number to a given precision.

• precision_imag (int) – Round the imaginary part of number to a given precision.

Return type:

complex

Returns:

Complex numbers.

complexes(start_real=0, end_real=1, start_imag=0, end_imag=1, precision_real=15, precision_imag=15, n=10)

Generates a list of random complex numbers.

Parameters:

• start_real (float) – Start real range.

• end_real (float) – End real range.

• start_imag (float) – Start imaginary range.

• end_imag (float) – End imaginary range.

• precision_real (int) – Round a real part of number to a given precision.

• precision_imag (int) – Round the imaginary part of number to a given precision.

• n (int) – Length of the list.

Return type:

list[complex]

Returns:

A list of random complex numbers.

decimal_number(start=-1000.0, end=1000.0)

Generates a random decimal number.

Parameters:

• start (float) – Start range.

• end (float) – End range.

Return type:

Decimal

Returns:

decimal.Decimal object.

decimals(start=0.0, end=1000.0, n=10)

Generates a list of decimal numbers.

Parameters:

• start (float) – Start range.

• end (float) – End range.

• n (int) – Length of the list.

Return type:

list[Decimal]

Returns:

A list of decimal.Decimal objects.

float_number(start=-1000.0, end=1000.0, precision=15)

Generates a random float number in range [start, end].

Parameters:

• start (float) – Start range.

• end (float) – End range.

• precision (int) – Round a number to a given precision in decimal digits, default is 15.

Return type:

float

Returns:

Float.

floats(start=0, end=1, n=10, precision=15)

Generates a list of random float numbers.

Parameters:

• start (float) – Start range.

• end (float) – End range.

• n (int) – Length of the list.

• precision (int) – Round a number to a given precision in decimal digits, default is 15.

Return type:

list[float]

Returns:

The list of floating-point numbers.

increment(accumulator=None)

Generates an incrementing number.

Each call of this method returns an incrementing number (with the step of +1).

If accumulator passed then increments number associated with it.

Example:

>>> self.increment()
1
>>> self.increment(accumulator="a")
1
>>> self.increment()
2
>>> self.increment(accumulator="a")
2
>>> self.increment(accumulator="b")
1
>>> self.increment(accumulator="a")
3

Parameters:

accumulator (Optional[str]) – Accumulator (used to create associative incrementation).

Return type:

int

Returns:

Integer.

integer_number(start=-1000, end=1000)

Generates a random integer from start to end.

Parameters:

• start (int) – Start range.

• end (int) – End range.

Return type:

int

Returns:

Integer.

integers(start=0, end=10, n=10)

Generates a list of random integers.

Parameters:

• start (int) – Start.

• end (int) – End.

• n (int) – Length of the list.

Return type:

list[int]

Returns:

List of integers.

Example:

[-20, -19, -18, -17]

matrix(m=10, n=10, num_type=NumType.FLOAT, **kwargs)

Generates m x n matrix with a random numbers.

This method works with a variety of types, so you can pass method-specific **kwargs.

Parameters:

• m (int) – Number of rows.

• n (int) – Number of columns.

• num_type (NumType) – NumType enum object.

• kwargs (Any) – Other method-specific arguments.

Return type:

list[list[int | float | complex | Decimal]]

Returns:

A matrix of random numbers.

Path

class mimesis.Path(platform='linux', *args, **kwargs)

Class that provides methods and property for generate paths.

__init__(platform='linux', *args, **kwargs)

Initialize attributes.

Supported platforms: ‘linux’, ‘darwin’, ‘win32’, ‘win64’.

Parameters:

platform (str) – Required platform type.

dev_dir()

Generates a random path to development directory.

Return type:

str

Returns:

Path.

Example:

/home/sherrell/Development/Python

home()

Generates a home path.

Return type:

str

Returns:

Home path.

Example:

/home

project_dir()

Generates a random path to project directory.

Return type:

str

Returns:

Path to project.

Example:

/home/sherika/Development/Falcon/mercenary

root()

Generates a root dir path.

Return type:

str

Returns:

Root dir.

Example:

/

user()

Generates a random user.

Return type:

str

Returns:

Path to user.

Example:

/home/oretha

users_folder()

Generates a random path to user’s folders.

Return type:

str

Returns:

Path.

Example:

/home/taneka/Pictures

Payment

class mimesis.Payment(*args, **kwargs)

Class that provides data related to payments.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:

• args (Any) – Arguments.

• kwargs (Any) – Keyword arguments.

bitcoin_address()

Generates a random bitcoin address.

Keep in mind that although it generates valid-looking addresses, it does not mean that they are actually valid.

Return type:

str

Returns:

Bitcoin address.

Example:

3EktnHQD7RiAE6uzMj2ZifT9YgRrkSgzQX

cid()

Generates a random CID.

Return type:

str

Returns:

CID code.

Example:

7452

credit_card_expiration_date(minimum=16, maximum=25)

Generates a random expiration date for credit card.

Parameters:

• minimum (int) – Date of issue.

• maximum (int) – Maximum of expiration_date.

Return type:

str

Returns:

Expiration date of credit card.

Example:

03/19.

credit_card_network()

Generates a random credit card network.

Return type:

str

Returns:

Credit card network

Example:

MasterCard

credit_card_number(card_type=None)

Generates a random credit card number.

Parameters:

card_type (Optional[CardType]) – Issuing Network. Default is Visa.

Return type:

str

Returns:

Credit card number.

Raises:

NotImplementedError – if card_type not supported.

Example:

4455 5299 1152 2450

credit_card_owner(gender=None)

Generates a random credit card owner.

Parameters:

gender (Gender enum.) – Gender of the card owner.

Return type:

dict[str, str]

Returns:

cvv()

Generates a random CVV.

Return type:

str

Returns:

CVV code.

Example:

069

ethereum_address()

Generates a random Ethereum address.

..note: The address will look like Ethereum address, but keep in mind that it is not the valid address.

Return type:

str

Returns:

Ethereum address.

Example:

0xe8ece9e6ff7dba52d4c07d37418036a89af9698d

paypal()

Generates a random PayPal account.

Return type:

str

Returns:

Email of PapPal user.

Example:

wolf235@gmail.com

Transport

class mimesis.Transport(*, seed=<mimesis.types._MissingSeed object>, random=None)

Class for generating data related to transports.

airplane()

Generates a random airplane model name.

Return type:

str

Returns:

Airplane model.

Example:

Boeing 727.

car()

Generates a random vehicle name.

Return type:

str

Returns:

A vehicle.

Example:

Tesla Model S.

manufacturer()

Generates a random car manufacturer.

Return type:

str

Returns:

A car manufacturer

Example:

Tesla.

vehicle_registration_code(locale=None)

Returns vehicle registration code.

Parameters:

locale (Optional[Locale]) – Registration code for locale (country).

Return type:

str

Returns:

Vehicle registration code.

Science

class mimesis.Science(*, seed=<mimesis.types._MissingSeed object>, random=None)

Class for generating pseudo-scientific data.

dna_sequence(length=10)

Generates a random DNA sequence.

Parameters:

length (int) – Length of block.

Return type:

str

Returns:

DNA sequence.

Example:

GCTTTAGACC

measure_unit(name=None, symbol=False)

Returns unit name from the International System of Units.

Parameters:

• name (Optional[MeasureUnit]) – Enum object UnitName.

• symbol (bool) – Return only symbol

Return type:

str

Returns:

Unit.

metric_prefix(sign=None, symbol=False)

Generates a random prefix for the International System of Units.

Parameters:

• sign (Optional[MetricPrefixSign]) – Sing of prefix (positive/negative).

• symbol (bool) – Return the symbol of the prefix.

Return type:

str

Returns:

Metric prefix for SI measure units.

Raises:

NonEnumerableError – if sign is not supported.

Example:

mega

rna_sequence(length=10)

Generates a random RNA sequence.

Parameters:

length (int) – Length of block.

Return type:

str

Returns:

RNA sequence.

Example:

AGUGACACAA

Schema-based Generators

BaseField

class mimesis.schema.BaseField(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>)

__init__(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>)

Base class for fields.

This class is used as a base class for Field and Fieldset.

Attr:

aliases: A dictionary of aliases for standard fields.

Parameters:

• locale (Locale) – Locale.

• seed (UnionType[None, int, float, str, bytes, bytearray, _MissingSeed]) – Seed for random.

get_random_instance()

Get a random object from Generic.

Return type:

Random

Returns:

Random object.

handle(field_name=None)

Decorator for registering a custom field handler.

You can use this decorator only for functions, not for any other callables.

New in version 12.0.0.

Parameters:

field_name (Optional[str]) – Name of the field. If not specified, the name of the function is used.

Return type:

Callable[[Callable[[Random, Any], Any]], Callable[[Random, Any], Any]]

Returns:

Decorator.

perform(name=None, key=None, **kwargs)

Performs the value of the field by its name.

It takes any string that represents the name of any method of any supported data provider and the **kwargs of this method.

Note

Some data providers have methods with the same names, and in such cases, you can explicitly define that the method belongs to data-provider field(name='provider.name') otherwise it will return the data from the first provider which has a method name.

Allowed delimiters: ., :, / and space:

• provider.name

• provider:name

• provider/name

• provider name

You can apply a key function to the result returned by the method, by passing a parameter key with a callable object which returns the final result.

The key function has the option to accept two parameters: result and random. In case you require access to a random instance within the key function, you must modify the function to accept both of them, where the first corresponds to the method result and the second corresponds to the instance of random.

Parameters:

• name (Optional[str]) – Name of the method.

• key (Optional[Callable[[Any], Any]]) – A key function (any callable object) which will be applied to result.

• kwargs (Any) – Kwargs of method.

Return type:

Any

Returns:

The result of method.

Raises:

ValueError – if provider is not supported or if field is not defined.

register_handler(field_name, field_handler)

Register a new field handler.

Parameters:

• field_name (str) – Name of the field.

• field_handler (Callable[[Random, Any], Any]) – Callable object.

Return type:

None

register_handlers(fields)

Register the new field handlers.

Parameters:

fields (Sequence[tuple[str, Callable[[Random, Any], Any]]]) – A sequence of sequences with field name and handler.

Return type:

None

Returns:

None.

reseed(seed=<mimesis.types._MissingSeed object>)

Reseed the random generator.

Parameters:

seed (UnionType[None, int, float, str, bytes, bytearray, _MissingSeed]) – Seed for random.

Return type:

None

unregister_all_handlers()

Unregister all custom field handlers.

Return type:

None

Returns:

None.

unregister_handler(field_name)

Unregister a field handler.

Parameters:

field_name (str) – Name of the field.

Return type:

None

unregister_handlers(field_names=())

Unregister a field handlers with given names.

Parameters:

field_names (Sequence[str]) – Names of the fields.

Return type:

None

Returns:

None.

Field

class mimesis.schema.Field(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>)

Greedy field (evaluates immediately).

Warning

There is no case when you need to instance field in loops.

If you are doing this:

>>> for i in range(1000):
...     field = Field()

You’re doing it wrong! It is a terrible idea that will lead to a memory leak.

Forewarned is forearmed.

Here is an example of how to use it:

>>> _ = Field()
>>> _('username')
Dogtag_1836

Fieldset

class mimesis.schema.Fieldset(*args, **kwargs)

Greedy fieldset (evaluates immediately).

Works like a field, but returns a list of values.

Here is an example:

>>> fieldset = Fieldset(i=100)
>>> fieldset('username')
['pot_1821', 'vhs_1915', ..., 'reviewed_1849']

You may also specify the number of iterations by passing the i keyword argument to the callable instance of fieldset:

>>> fieldset = Fieldset()
>>> fieldset('username', i=2)
['pot_1821', 'vhs_1915']

When i is not specified, the reasonable default is used — 10.

See “Field vs Fieldset” section of documentation for more details.

Variables:

• fieldset_default_iterations – Default iterations. Default is 10.

• fieldset_iterations_kwarg – Keyword argument for iterations. Default is i.

Schema

class mimesis.schema.Schema(schema, iterations=10)

Class which return list of filled schemas.

__init__(schema, iterations=10)

Initialize schema.

Parameters:

• iterations (int) – Number of iterations. This parameter is keyword-only. The default value is 10.

• schema (Callable[[], dict[str, Any]]) – A schema (must be a callable object).

create()

Creates a list of a fulfilled schemas.

Note

This method evaluates immediately, so be careful when creating large datasets otherwise you’re risking running out of memory.

If you need a lazy version of this method, see iterator().

Return type:

list[dict[str, Any]]

Returns:

List of fulfilled schemas.

to_csv(file_path, **kwargs)

Export a schema as a CSV file.

Parameters:

• file_path (str) – The file path.

• kwargs (Any) – The keyword arguments for csv.DictWriter class.

Return type:

None

to_json(file_path, **kwargs)

Export a schema as a JSON file.

Parameters:

• file_path (str) – File a path.

• kwargs (Any) – Extra keyword arguments for json.dump() class.

Return type:

None

to_pickle(file_path, **kwargs)

Export a schema as the pickled representation of the object to the file.

Parameters:

• file_path (str) – The file path.

• kwargs (Any) – Extra keyword arguments for pickle.dump() class.

Return type:

None

Enums

Implements enums for a lot of methods.

Enums from this module are used in a lot of methods. You should always import enums from this module if you want behavior for the methods that differ from the default behavior.

You should never use your own enums in methods because in this case, there is no guarantee that you will get the result which you actually expected.

Below, you can see an example of usage enums in methods of data providers.

class mimesis.enums.Algorithm(value)

Provides algorithms which available.

An argument for hash().

BLAKE2B = 'blake2b'

BLAKE2S = 'blake2s'

MD5 = 'md5'

SHA1 = 'sha1'

SHA224 = 'sha224'

SHA256 = 'sha256'

SHA384 = 'sha384'

SHA512 = 'sha512'

class mimesis.enums.AudioFile(value)

Provides the audio file types.

An argument for audio()

AAC = 'aac'

MP3 = 'mp3'

class mimesis.enums.CardType(value)

Provides credit card types.

An argument for credit_card_number().

AMERICAN_EXPRESS = 'American Express'

MASTER_CARD = 'MasterCard'

VISA = 'Visa'

class mimesis.enums.CompressedFile(value)

Provides the compressed file types.

An argument for compressed()

GZIP = 'gz'

ZIP = 'zip'

class mimesis.enums.CountryCode(value)

Provides types of country codes.

An argument for country_code().

A2 = 'a2'

A3 = 'a3'

FIFA = 'fifa'

IOC = 'ioc'

NUMERIC = 'numeric'

class mimesis.enums.DSNType(value)

An enumeration.

COUCHBASE = ('couchbase', 8092)

MEMCACHED = ('memcached', 11211)

MONGODB = ('mongodb', 27017)

MYSQL = ('mysql', 3306)

POSTGRES = ('postgres', 5432)

RABBITMQ = ('rabbitmq', 5672)

REDIS = ('redis', 6379)

class mimesis.enums.DocumentFile(value)

Provides the document file types.

An argument for document()

DOCX = 'docx'

PDF = 'pdf'

PPTX = 'pptx'

XLSX = 'xlsx'

class mimesis.enums.EANFormat(value)

Provides formats of EAN.

An argument for ean().

EAN13 = 'ean-13'

EAN8 = 'ean-8'

class mimesis.enums.EmojyCategory(value)

An enumeration.

ACTIVITIES = 'activities'

ANIMALS_AND_NATURE = 'animals_and_nature'

DEFAULT = 'smileys_and_emotion'

FLAGS = 'flags'

FOOD_AND_DRINK = 'food_and_drink'

OBJECTS = 'objects'

PEOPLE_AND_BODY = 'people_and_body'

SMILEYS_AND_EMOTION = 'smileys_and_emotion'

SYMBOLS = 'symbols'

TRAVEL_AND_PLACES = 'travel_and_places'

class mimesis.enums.FileType(value)

Provides file types.

An argument for extension() and file_name().

AUDIO = 'audio'

COMPRESSED = 'compressed'

DATA = 'data'

EXECUTABLE = 'executable'

IMAGE = 'image'

SOURCE = 'source'

TEXT = 'text'

VIDEO = 'video'

class mimesis.enums.Gender(value)

Represents genders.

An argument for a lot of methods which are taking parameter gender.

FEMALE = 'female'

MALE = 'male'

class mimesis.enums.ISBNFormat(value)

Provides formats of ISBN.

An argument for isbn().

ISBN10 = 'isbn-10'

ISBN13 = 'isbn-13'

class mimesis.enums.ImageFile(value)

Provides the image file types.

An argument for image()

GIF = 'gif'

JPG = 'jpg'

PNG = 'png'

class mimesis.enums.Locale(value)

This class provides access to the supported locales from one place.

An argument for all local-depend providers.

CS = 'cs'

DA = 'da'

DE = 'de'

DEFAULT = 'en'

DE_AT = 'de-at'

DE_CH = 'de-ch'

EL = 'el'

EN = 'en'

EN_AU = 'en-au'

EN_CA = 'en-ca'

EN_GB = 'en-gb'

ES = 'es'

ES_MX = 'es-mx'

ET = 'et'

FA = 'fa'

FI = 'fi'

FR = 'fr'

HR = 'hr'

HU = 'hu'

IS = 'is'

IT = 'it'

JA = 'ja'

KK = 'kk'

KO = 'ko'

NL = 'nl'

NL_BE = 'nl-be'

NO = 'no'

PL = 'pl'

PT = 'pt'

PT_BR = 'pt-br'

RU = 'ru'

SK = 'sk'

SV = 'sv'

TR = 'tr'

UK = 'uk'

ZH = 'zh'

classmethod values()

Return type:

List[str]

class mimesis.enums.MeasureUnit(value)

Provide unit names.

An argument for measure_unit().

AMOUNT_OF_SUBSTANCE = ('mole', 'mol')

ANGLE = ('radian', 'r')

ELECTRICAL_CONDUCTANCE = ('siemens', 'S')

ELECTRIC_CAPACITANCE = ('farad', 'F')

ELECTRIC_CHARGE = ('coulomb', 'C')

ELECTRIC_RESISTANCE = ('ohm', 'Ω')

ENERGY = ('joule', 'J')

FLUX = ('watt', 'W')

FORCE = ('newton', 'N')

FREQUENCY = ('hertz', 'Hz')

INDUCTANCE = ('henry', 'H')

INFORMATION = ('byte', 'b')

MAGNETIC_FLUX = ('weber', 'Wb')

MAGNETIC_FLUX_DENSITY = ('tesla', 'T')

MASS = ('gram', 'gr')

POWER = ('watt', 'W')

PRESSURE = ('pascal', 'P')

RADIOACTIVITY = ('becquerel', 'Bq')

SOLID_ANGLE = ('steradian', '㏛')

TEMPERATURE = ('Celsius', '°C')

THERMODYNAMIC_TEMPERATURE = ('kelvin', 'K')

VOLTAGE = ('volt', 'V')

class mimesis.enums.MetricPrefixSign(value)

Provides prefix signs.

An argument for metric_prefix()`().

NEGATIVE = 'negative'

POSITIVE = 'positive'

class mimesis.enums.MimeType(value)

Provides common mime types.

An argument for mime_type().

APPLICATION = 'application'

AUDIO = 'audio'

IMAGE = 'image'

MESSAGE = 'message'

TEXT = 'text'

VIDEO = 'video'

class mimesis.enums.NumType(value)

Provides the number types.

An argument for matrix().

COMPLEX = 'complexes'

DECIMAL = 'decimals'

FLOAT = 'floats'

INTEGER = 'integers'

class mimesis.enums.PortRange(value)

Represents port ranges.

An argument for port().

ALL = (1, 65535)

EPHEMERAL = (49152, 65535)

REGISTERED = (1024, 49151)

WELL_KNOWN = (1, 1023)

class mimesis.enums.TLDType(value)

Provides top level domain types.

An argument for a few methods which are taking parameter tld_type.

CCTLD = 'cctld'

GEOTLD = 'geotld'

GTLD = 'gtld'

STLD = 'stld'

UTLD = 'utld'

class mimesis.enums.TimestampFormat(value)

An enumeration.

ISO_8601 = 2

POSIX = 1

RFC_3339 = 3

class mimesis.enums.TimezoneRegion(value)

Provides regions of timezones.

An argument for timezone().

AFRICA = 'Africa'

AMERICA = 'America'

ANTARCTICA = 'Antarctica'

ARCTIC = 'Arctic'

ASIA = 'Asia'

ATLANTIC = 'Atlantic'

AUSTRALIA = 'Australia'

EUROPE = 'Europe'

INDIAN = 'Indian'

PACIFIC = 'Pacific'

class mimesis.enums.TitleType(value)

Represents title types.

An argument for title().

ACADEMIC = 'academic'

TYPICAL = 'typical'

class mimesis.enums.URLScheme(value)

Provides URL schemes.

An argument for some methods of Internet().

FTP = 'ftp'

HTTP = 'http'

HTTPS = 'https'

SFTP = 'sftp'

WS = 'ws'

WSS = 'wss'

class mimesis.enums.VideoFile(value)

Provides the vide file types.

An argument for video()

MOV = 'mov'

MP4 = 'mp4'