API

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

Random module

class mimesis.random.Random(x=None)[source]

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)[source]

Get random value of enum object.

Parameters:

enum (Any) – Enum object.

Return type:

Any

Returns:

Random value of enum.

custom_code(mask='@###', char='@', digit='#')[source]

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)[source]

Generate n random bytes.

Return type:

bytes

randints(amount=3, a=1, b=100)[source]

Generate list of random integers.

Parameters:
  • amount (int) – Amount 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 amount less or equal to zero.

uniform(a, b, precision=15)[source]

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)[source]

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 is 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)[source]

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)[source]

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>)[source]

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

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

Initialize attributes.

cnpj(with_mask=True)[source]

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)[source]

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>)[source]

Class that provides special data for Denmark (da).

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

Initialize attributes.

cpr()[source]

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>)[source]

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

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

Initialize attributes.

bsn()[source]

Generate a random, but valid Burgerservicenummer.

Return type:

str

Returns:

Random BSN.

Example:

255159705

burgerservicenummer()[source]

Generate a random, but valid Burgerservicenummer.

An alias for self.bsn()

Return type:

str

RussiaSpecProvider

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

Class that provides special data for Russia (ru).

class Meta[source]

The name of the provider.

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

Initialize attributes.

bic()[source]

Generate random BIC (Bank ID Code).

Return type:

str

Returns:

BIC.

Example:
generate_sentence()[source]

Generate sentence from the parts.

Return type:

str

Returns:

Sentence.

inn()[source]

Generate random, but valid INN.

Return type:

str

Returns:

INN.

kpp()[source]

Generate random KPP.

Return type:

str

Returns:

‘KPP’.

Example:
ogrn()[source]

Generate random valid OGRN.

Return type:

str

Returns:

OGRN.

Example:
passport_number()[source]

Generate random passport number.

Return type:

int

Returns:

Number.

Example:

560430

passport_series(year=None)[source]

Generate random series of passport.

Parameters:

year (int or None) – Year of manufacture.

Return type:

str

Returns:

Series.

Example:

02 15.

patronymic(gender=None)[source]

Generate random patronymic name.

Parameters:

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

Return type:

str

Returns:

Patronymic name.

Example:

Алексеевна.

series_and_number()[source]

Generate a random passport number and series.

Return type:

str

Returns:

Series and number.

Example:

57 16 805199.

snils()[source]

Generate snils with special algorithm.

Return type:

str

Returns:

SNILS.

Example:

UkraineSpecProvider

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

Class that provides special data for Ukraine (uk).

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

Initialize attributes.

patronymic(gender=None)[source]

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>)[source]

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

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

Initialize attributes.

ssn()[source]

Generate a random, but valid SSN.

Return type:

str

Returns:

SSN.

Example:

569-66-5801

tracking_number(service='usps')[source]

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>)[source]

Class that provides special data for Poland (pl).

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

Initialize attributes.

nip()[source]

Generate random valid 10-digit NIP.

Return type:

str

Returns:

Valid 10-digit NIP

pesel(birth_date=None, gender=None)[source]

Generate random 11-digit PESEL.

Parameters:
Return type:

str

Returns:

Valid 11-digit PESEL

regon()[source]

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)[source]

Calculate a checksum for num using the Luhn algorithm.

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.FieldArityError[source]
exception mimesis.exceptions.FieldError(name=None)[source]
exception mimesis.exceptions.FieldsetError[source]

Raised when a resulting fieldset is empty.

exception mimesis.exceptions.LocaleError(locale)[source]

Raised when a locale isn’t supported.

exception mimesis.exceptions.NonEnumerableError(enum_obj)[source]

Raised when object is not instance of Enum.

exception mimesis.exceptions.SchemaError[source]

Raised when a schema is unsupported.

Base Providers

BaseProvider

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

This is a base class for all providers.

Attr:

random: Instance of mimesis.random.Random.

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

Initialize attributes.

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

Parameters:
reseed(seed=<mimesis.types._MissingSeed object>)[source]

Reseed 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 (Union[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)[source]

Validate enum parameter of method in subclasses of BaseProvider.

Parameters:
  • item (Any) – Item of enum object.

  • enum (Any) – Enum object.

Return type:

Any

Returns:

Value of item.

Raises:

NonEnumerableError – if item not in enum.

BaseDataProvider

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

This is a base class for all data providers.

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

Initialize attributes for data providers.

Parameters:
extract(keys, default=None)[source]

Extracts nested values from JSON file by list of keys.

Parameters:
  • keys (List[str]) – List of keys (order extremely matters).

  • default (Optional[Any]) – Default value.

Return type:

Any

Returns:

Data.

get_current_locale()[source]

Get 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)[source]

Context manager which 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.

Generic Providers

Generic

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

Class which contain all providers at one.

class Meta[source]

Class for metadata.

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

Initialize attributes lazily.

add_provider(cls, **kwargs)[source]

Add a custom provider to 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)[source]

Add numerous custom providers to the 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>)[source]

Reseed the internal random generator.

Overrides method BaseProvider.reseed().

Parameters:

seed (Union[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)[source]

Class for generate fake address data.

This object provides all the data related to geographical location.

address()[source]

Generate a random full address.

Return type:

str

Returns:

Full address.

calling_code()[source]

Get a random calling code of random country.

Return type:

str

Returns:

Calling code.

city()[source]

Get a random city.

Return type:

str

Returns:

City name.

continent(code=False)[source]

Get a random continent name or continent code.

Parameters:

code (bool) – Return code of continent.

Return type:

str

Returns:

Continent name.

coordinates(dms=False)[source]

Generate random geo coordinates.

Parameters:

dms (bool) – DMS format.

Return type:

Dict[str, Union[str, float]]

Returns:

Dict with coordinates.

country()[source]

Get a random country.

Return type:

str

Returns:

The Country.

country_code(code=CountryCode.A2)[source]

Get a random code of country.

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

Parameters:

code (Optional[CountryCode]) – Enum object CountryCode.

Return type:

str

Returns:

Country code in selected format.

Raises:

KeyError – if fmt is not supported.

default_country()[source]

Get the country associated with the current locale.

Return type:

str

Returns:

The country associated with current locale.

federal_subject(*args, **kwargs)[source]

Get a random region.

An alias for state().

Return type:

str

latitude(dms=False)[source]

Generate a random value of latitude.

Parameters:

dms (bool) – DMS format.

Return type:

Union[str, float]

Returns:

Value of longitude.

longitude(dms=False)[source]

Generate a random value of longitude.

Parameters:

dms (bool) – DMS format.

Return type:

Union[str, float]

Returns:

Value of longitude.

postal_code()[source]

Generate a postal code for current locale.

Return type:

str

Returns:

Postal code.

prefecture(*args, **kwargs)[source]

Get a random prefecture.

An alias for state().

Return type:

str

province(*args, **kwargs)[source]

Get a random province.

An alias for state().

Return type:

str

region(*args, **kwargs)[source]

Get a random region.

An alias for state().

Return type:

str

state(abbr=False)[source]

Get a random administrative district of country.

Parameters:

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

Return type:

str

Returns:

Administrative district.

street_name()[source]

Get a random street name.

Return type:

str

Returns:

Street name.

street_number(maximum=1400)[source]

Generate a random street number.

Parameters:

maximum (int) – Maximum value.

Return type:

str

Returns:

Street number.

street_suffix()[source]

Get a random street suffix.

Return type:

str

Returns:

Street suffix.

zip_code()[source]

Generate 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)[source]

Class for generating finance data.

bank()[source]

Get a random bank name.

Return type:

str

Returns:

Bank name.

company()[source]

Get a random company name.

Return type:

str

Returns:

Company name.

company_type(abbr=False)[source]

Get a random type of business entity.

Parameters:

abbr (bool) – Abbreviated company type.

Return type:

str

Returns:

Types of business entity.

cryptocurrency_iso_code()[source]

Get symbol of random cryptocurrency.

Return type:

str

Returns:

Symbol of cryptocurrency.

cryptocurrency_symbol()[source]

Get a cryptocurrency symbol.

Return type:

str

Returns:

Symbol of cryptocurrency.

currency_iso_code(allow_random=False)[source]

Get code of the currency for current locale.

Parameters:

allow_random (bool) – Get a random ISO code.

Return type:

str

Returns:

Currency code.

currency_symbol()[source]

Get a currency symbol for current locale.

Return type:

str

Returns:

Currency symbol.

price(minimum=500, maximum=1500)[source]

Generate 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)[source]

Generate 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()[source]

Returns stock exchange name.

Return type:

str

Returns:

Returns exchange name.

stock_name()[source]

Returns stock name.

Return type:

str

Returns:

Stock name.

stock_ticker()[source]

Returns random stock ticker.

Return type:

str

Returns:

Ticker.

Datetime

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

Class for generating data related to the date and time.

static bulk_create_datetimes(date_start, date_end, **kwargs)[source]

Bulk create datetime objects.

This method creates 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:
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()[source]

Get a random century.

Return type:

str

Returns:

Century.

date(start=2000, end=2023)[source]

Generate random date object.

Parameters:
  • start (int) – Minimum value of year.

  • end (int) – Maximum value of year.

Return type:

date

Returns:

Formatted date.

datetime(start=2023, end=2023, timezone=None)[source]

Generate 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()[source]

Generate a random day of month, from 1 to 31.

Return type:

int

Returns:

Random value from 1 to 31.

day_of_week(abbr=False)[source]

Get a random day of week.

Parameters:

abbr (bool) – Abbreviated day name.

Return type:

str

Returns:

Day of the week.

formatted_date(fmt='', **kwargs)[source]

Generate 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)[source]

Generate 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='')[source]

Generate string formatted time.

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()[source]

Get a random GMT offset value.

Return type:

str

Returns:

GMT Offset.

month(abbr=False)[source]

Get a random month.

Parameters:

abbr (bool) – Abbreviated month name.

Return type:

str

Returns:

Month name.

periodicity()[source]

Get a random periodicity string.

Return type:

str

Returns:

Periodicity.

time()[source]

Generate a random time object.

Return type:

time

Returns:

datetime.time object.

timestamp(fmt=TimestampFormat.POSIX, **kwargs)[source]

Generate 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:
Return type:

Union[str, int]

Returns:

Timestamp.

timezone(region=None)[source]

Get a random timezone.

Parameters:

region (Optional[TimezoneRegion]) – Timezone region.

Return type:

str

Returns:

Timezone.

week_date(start=2017, end=2023)[source]

Get week number with year.

Parameters:
  • start (int) – From start.

  • end (int) – To end.

Return type:

str

Returns:

Week number.

year(minimum=1990, maximum=2023)[source]

Generate 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)[source]

Class for generating data related to food.

dish()[source]

Get a random dish.

Return type:

str

Returns:

Dish name.

Example:

Ratatouille.

drink()[source]

Get a random drink.

Return type:

str

Returns:

Alcoholic drink.

Example:

Vodka.

fruit()[source]

Get a random fruit or berry.

Return type:

str

Returns:

Fruit name.

Example:

Banana.

spices()[source]

Get a random spices or herbs.

Return type:

str

Returns:

Spices or herbs.

Example:

Anise.

vegetable()[source]

Get a random vegetable.

Return type:

str

Returns:

Vegetable name.

Example:

Tomato.

Person

class mimesis.Person(*args, **kwargs)[source]

Class for generating personal data.

__init__(*args, **kwargs)[source]

Initialize attributes.

Parameters:
  • locale – Current locale.

  • seed – Seed.

academic_degree()[source]

Get a random academic degree.

Return type:

str

Returns:

Degree.

Example:

Bachelor.

age(minimum=16, maximum=66)[source]

Get a random integer value.

Parameters:
  • maximum (int) – Maximum value of age.

  • minimum (int) – Minimum value of age.

Return type:

int

Returns:

Random integer.

Example:
blood_type()[source]

Get a random blood type.

Return type:

str

Returns:

Blood type (blood group).

Example:

A+

email(domains=None, unique=False)[source]

Generate 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)[source]

Generate a random first name.

..note: An alias for self.name().

Parameters:

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

Return type:

str

Returns:

First name.

full_name(gender=None, reverse=False)[source]

Generate 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(iso5218=False, symbol=False)[source]

Get a random gender.

Get 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.

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

  • symbol (bool) – Symbol of gender.

Return type:

Union[str, int]

Returns:

Title of gender.

Example:

Male

height(minimum=1.5, maximum=2.0)[source]

Generate a random height in meters.

Parameters:
  • minimum (float) – Minimum value.

  • maximum (float) – Maximum value.

Return type:

str

Returns:

Height.

Example:

1.85.

identifier(mask='##-##/##')[source]

Generate a random identifier by mask.

With this method you can generate any identifiers that you need. Simply select the mask that you need.

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()[source]

Get a random language.

Return type:

str

Returns:

Random language.

Example:

Irish.

last_name(gender=None)[source]

Generate a random last name.

..note: An alias for self.surname().

Parameters:

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

Return type:

str

Returns:

Last name.

name(gender=None)[source]

Generate a random name.

Parameters:

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

Return type:

str

Returns:

Name.

Example:

John.

nationality(gender=None)[source]

Get a random nationality.

Parameters:

gender (Optional[Gender]) – Gender.

Return type:

str

Returns:

Nationality.

Example:

Russian

occupation()[source]

Get a random job.

Return type:

str

Returns:

The name of job.

Example:

Programmer.

password(length=8, hashed=False)[source]

Generate 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='#')[source]

Generate 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()[source]

Get a random political views.

Return type:

str

Returns:

Political views.

Example:

Liberal.

sex(*args, **kwargs)[source]

An alias for method self.gender().

See docstrings of method self.gender() for details.

Parameters:
  • args (Any) – Positional arguments.

  • kwargs (Any) – Keyword arguments.

Return type:

Union[str, int]

Returns:

Sex

surname(gender=None)[source]

Generate a random surname.

Parameters:

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

Return type:

str

Returns:

Surname.

Example:

Smith.

title(gender=None, title_type=None)[source]

Generate a random title for name.

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

Parameters:
Return type:

str

Returns:

The title.

Raises:

NonEnumerableError – if gender or title_type in incorrect format.

Example:

PhD.

university()[source]

Get a random university.

Return type:

str

Returns:

University name.

Example:

MIT.

username(mask=None, drange=(1800, 2100))[source]

Generate 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:
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()[source]

Get a random views on.

Return type:

str

Returns:

Views on.

Example:

Negative.

weight(minimum=38, maximum=90)[source]

Generate a random weight in Kg.

Parameters:
  • minimum (int) – min value

  • maximum (int) – max value

Return type:

int

Returns:

Weight.

Example:
work_experience(working_start_age=22)[source]

Get a work experience.

Parameters:

working_start_age (int) – Age then person start to work.

Return type:

int

Returns:

Depend on previous generated age.

worldview()[source]

Get a random worldview.

Return type:

str

Returns:

Worldview.

Example:

Pantheism.

Text

class mimesis.Text(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>, *args, **kwargs)[source]

Class for generating text data.

alphabet(lower_case=False)[source]

Get an alphabet for current locale.

Parameters:

lower_case (bool) – Return alphabet in lower case.

Return type:

List[str]

Returns:

Alphabet.

answer()[source]

Get a random answer in current language.

Return type:

str

Returns:

An answer.

Example:

No

color()[source]

Get a random name of color.

Return type:

str

Returns:

Color name.

Example:

Red.

hex_color(safe=False)[source]

Generate a random hex color.

Parameters:

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

Return type:

str

Returns:

Hex color code.

Example:

#d8346b

level()[source]

Generate a random level of danger or something else.

Return type:

str

Returns:

Level.

Example:

critical.

quote()[source]

Get a random quote.

Return type:

str

Returns:

Quote from movie.

Example:

“Bond… James Bond.”

rgb_color(safe=False)[source]

Generate a random rgb color tuple.

Parameters:

safe (bool) – Get safe RGB tuple.

Return type:

Tuple[int, ...]

Returns:

RGB tuple.

Example:

(252, 85, 32)

sentence()[source]

Get a random sentence from text.

Return type:

str

Returns:

Sentence.

text(quantity=5)[source]

Generate the text.

Parameters:

quantity (int) – Quantity of sentences.

Return type:

str

Returns:

Text.

title()[source]

Get a random title.

Return type:

str

Returns:

The title.

word()[source]

Get a random word.

Return type:

str

Returns:

Single word.

Example:

Science.

words(quantity=5)[source]

Generate 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)[source]

Class for generating binary data

__init__(*args, **kwargs)[source]

Initialize attributes.

Parameters:
  • locale – Current locale.

  • seed – Seed.

audio(*, file_type=AudioFile.MP3)[source]

Generates 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)[source]

Generates 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)[source]

Generates 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)[source]

Generates 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)[source]

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)[source]

A class, which provides methods for generating codes.

ean(fmt=None)[source]

Generate EAN.

To change 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()[source]

Generate a random IMEI.

Return type:

str

Returns:

IMEI.

isbn(fmt=None, locale=Locale.EN)[source]

Generate ISBN for current locale.

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

Parameters:
Return type:

str

Returns:

ISBN.

Raises:

NonEnumerableError – if code is not enum ISBNFormat.

issn(mask='####-####')[source]

Generate a random ISSN.

Parameters:

mask (str) – Mask of ISSN.

Return type:

str

Returns:

ISSN.

locale_code()[source]

Get a random locale code (MS-LCID).

See Windows Language Code Identifier Reference for more information.

Return type:

str

Returns:

Locale code.

pin(mask='####')[source]

Generate 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)[source]

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

choice(*args, **kwargs)[source]

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)[source]

Class that provides cryptographic data.

hash(algorithm=None)[source]

Generate 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()[source]

Generate BIP-39-compatible mnemonic phrase.

Return type:

str

Returns:

Mnemonic phrase.

static token_bytes(entropy=32)[source]

Generate 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)[source]

Return 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)[source]

Return 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()[source]

Generate UUID4 string.

Return type:

str

Returns:

UUID4 as string.

static uuid_object()[source]

Generate UUID4 object.

Return type:

UUID

Returns:

UUID4 object.

Development

class mimesis.Development(*args, **kwargs)[source]

Class for getting fake data for Developers.

__init__(*args, **kwargs)[source]

Initialize attributes.

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

Parameters:
boolean()[source]

Get a random boolean value.

Return type:

bool

Returns:

True of False.

dsn(dsn_type=None, **kwargs)[source]

Generates a random DSN (Data Source Name).

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

  • kwargs (Any) – Additional arguments for Internet.hostname().

Return type:

str

ility()[source]

Get a random system quality attribute.

An alias for system_quality_attribute().

Return type:

str

os()[source]

Get a random operating system or distributive name.

Return type:

str

Returns:

The name of OS.

Example:

Gentoo

programming_language()[source]

Get a random programming language from the list.

Return type:

str

Returns:

Programming language.

Example:

Erlang.

software_license()[source]

Get a random software license.

Return type:

str

Returns:

License name.

Example:

The BSD 3-Clause License.

system_quality_attribute()[source]

Get 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(calver=False, pre_release=False)[source]

Generate version number.

Parameters:
  • calver (bool) – Calendar versioning.

  • pre_release (bool) – Pre-release.

Return type:

str

Returns:

Version.

Example:

0.2.1

File

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

Class for generate data related to files.

extension(file_type=None)[source]

Get a random file extension from list.

Parameters:

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

Return type:

str

Returns:

Extension of the file.

Example:

.py

file_name(file_type=None)[source]

Get a random file name with some extension.

Parameters:

file_type (Optional[FileType]) – Enum object FileType

Return type:

str

Returns:

File name.

Example:

legislative.txt

mime_type(type_=None)[source]

Get a random mime type from list.

Parameters:

type – Enum object MimeType.

Return type:

str

Returns:

Mime type.

size(minimum=1, maximum=100)[source]

Get size of file.

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)[source]

Class for generate data related to hardware.

class Meta[source]

Class for metadata.

cpu()[source]

Get a random CPU name.

Return type:

str

Returns:

CPU name.

Example:

Intel® Core i7.

cpu_codename()[source]

Get a random CPU code name.

Return type:

str

Returns:

CPU code name.

Example:

Cannonlake.

cpu_frequency()[source]

Get a random frequency of CPU.

Return type:

str

Returns:

Frequency of CPU.

Example:

4.0 GHz.

generation()[source]

Get a random generation.

Return type:

str

Returns:

Generation of something.

Example:

6th Generation.

graphics()[source]

Get a random graphics.

Return type:

str

Returns:

Graphics.

Example:

Intel® Iris™ Pro Graphics 6200.

manufacturer()[source]

Get a random manufacturer.

Return type:

str

Returns:

Manufacturer.

Example:

Dell.

phone_model()[source]

Get a random phone model.

Return type:

str

Returns:

Phone model.

Example:

Nokia Lumia 920.

ram_size()[source]

Get a random size of RAM.

Return type:

str

Returns:

RAM size.

Example:

16GB.

ram_type()[source]

Get a random RAM type.

Return type:

str

Returns:

Type of RAM.

Example:

DDR3.

resolution()[source]

Get a random screen resolution.

Return type:

str

Returns:

Resolution of screen.

Example:

1280x720.

screen_size()[source]

Get a random size of screen in inch.

Return type:

str

Returns:

Screen size.

Example:

13″.

ssd_or_hdd()[source]

Get a random value from list.

Return type:

str

Returns:

HDD or SSD.

Example:

512GB SSD.

Internet

class mimesis.Internet(*args, **kwargs)[source]

Class for generating data related to the internet.

__init__(*args, **kwargs)[source]

Initialize attributes.

Parameters:
  • args (Any) – Arguments.

  • kwargs (Any) – Keyword arguments.

content_type(mime_type=None)[source]

Get a random HTTP content type.

Return type:

str

Returns:

Content type.

Example:

application/json

emoji()[source]

Get a random emoji shortcut code.

Return type:

str

Returns:

Emoji code.

Example:
kissing:

hashtags(quantity=4)[source]

Generate a list of hashtags.

Parameters:

quantity (int) – The quantity of hashtags.

Return type:

List[str]

Returns:

The list of hashtags.

Raises:

NonEnumerableError – if category is not in Hashtag.

Example:

[‘#love’, ‘#sky’, ‘#nice’]

hostname(tld_type=None, subdomains=None)[source]

Generate a random hostname without a scheme.

Parameters:
Return type:

str

Returns:

Hostname.

http_method()[source]

Get a random HTTP method.

Return type:

str

Returns:

HTTP method.

Example:

POST

http_request_headers()[source]

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()[source]

Generate 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()[source]

Get a random HTTP status code.

Return type:

int

Returns:

HTTP status.

Example:

200

http_status_message()[source]

Get a random HTTP status message.

Return type:

str

Returns:

HTTP status message.

Example:

200 OK

ip_v4()[source]

Generate a random IPv4 address as string.

Example:

19.121.223.58

Return type:

str

ip_v4_object()[source]

Generate random ipaddress.IPv4Address object.

Return type:

IPv4Address

Returns:

ipaddress.IPv4Address object.

ip_v4_with_port(port_range=PortRange.ALL)[source]

Generate 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()[source]

Generate 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()[source]

Generate random ipaddress.IPv6Address object.

Return type:

IPv6Address

Returns:

ipaddress.IPv6Address object.

mac_address()[source]

Generate a random MAC address.

Return type:

str

Returns:

Random MAC address.

Example:

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

path(*args, **kwargs)[source]

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)[source]

Generate 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()[source]

Generates a random public DNS.

Example:

1.1.1.1

Return type:

str

query_parameters(length=None)[source]

Generate 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)[source]

Generate arbitrary query string of given length.

Parameters:

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

Return type:

str

Returns:

Query string.

slug(parts_count=None)[source]

Generate 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)[source]

Generate a random stock image URL hosted on Unsplash.

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

Parameters:
Return type:

str

Returns:

URL of the image.

tld(*args, **kwargs)[source]

Generates random top level domain.

An alias for top_level_domain()

Return type:

str

top_level_domain(tld_type=TLDType.CCTLD)[source]

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)[source]

Generate a random URI.

Parameters:
Return type:

str

Returns:

URI.

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

Generate a random URL.

Parameters:
Return type:

str

Returns:

URL.

user_agent()[source]

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)[source]

A provider for generating numeric data.

__init__(*args, **kwargs)[source]

Initialize attributes.

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

Parameters:
complex_number(start_real=0.0, end_real=1.0, start_imag=0.0, end_imag=1.0, precision_real=15, precision_imag=15)[source]

Generate 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)[source]

Generate 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)[source]

Generate 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)[source]

Generate a decimal number as decimal.Decimal objects.

Parameters:
  • start (float) – Start range.

  • end (float) – End range.

  • n (int) – Length of the list.

Return type:

List[Decimal]

Returns:

A list of random decimal numbers.

float_number(start=-1000.0, end=1000.0, precision=15)[source]

Generate 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)[source]

Generate 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)[source]

Generate incremental 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)[source]

Generate 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)[source]

Generate a list of random integers.

Integers can be negative or positive numbers. .. note: You can use both positive and negative numbers.

Parameters:
  • start (int) – Start.

  • end (int) – End.

  • n (int) – Length of list.

Return type:

List[int]

Returns:

List of integers.

Example:

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

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

Generate m x n matrix with random numbers.

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

See code for more details.

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[Union[int, float, complex, Decimal]]]

Returns:

A matrix of random numbers.

Path

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

Class that provides methods and property for generate paths.

__init__(platform='linux', *args, **kwargs)[source]

Initialize attributes.

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

Parameters:

platform (str) – Required platform type.

dev_dir()[source]

Generate a random path to development directory.

Return type:

str

Returns:

Path.

Example:

/home/sherrell/Development/Python

home()[source]

Generate a home path.

Return type:

str

Returns:

Home path.

Example:

/home

project_dir()[source]

Generate a random path to project directory.

Return type:

str

Returns:

Path to project.

Example:

/home/sherika/Development/Falcon/mercenary

root()[source]

Generate a root dir path.

Return type:

str

Returns:

Root dir.

Example:

/

user()[source]

Generate a random user.

Return type:

str

Returns:

Path to user.

Example:

/home/oretha

users_folder()[source]

Generate a random path to user’s folders.

Return type:

str

Returns:

Path.

Example:

/home/taneka/Pictures

Payment

class mimesis.Payment(*args, **kwargs)[source]

Class that provides data related to payments.

__init__(*args, **kwargs)[source]

Initialize attributes.

Parameters:
  • args (Any) – Arguments.

  • kwargs (Any) – Keyword arguments.

bitcoin_address()[source]

Generate 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()[source]

Generate a random CID.

Return type:

str

Returns:

CID code.

Example:

7452

credit_card_expiration_date(minimum=16, maximum=25)[source]

Generate 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()[source]

Generate a random credit card network.

Return type:

str

Returns:

Credit card network

Example:

MasterCard

credit_card_number(card_type=None)[source]

Generate 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)[source]

Generate credit card owner.

Parameters:

gender (Gender's enum object.) – Gender of credit card owner.

Return type:

Dict[str, str]

Returns:

cvv()[source]

Generate a random CVV.

Return type:

str

Returns:

CVV code.

Example:

069

ethereum_address()[source]

Generate 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()[source]

Generate 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)[source]

Class for generating data related to transports.

airplane()[source]

Generate a dummy airplane model.

Return type:

str

Returns:

Airplane model.

Example:

Boeing 727.

car()[source]

Get a random vehicle.

Return type:

str

Returns:

A vehicle.

Example:

Tesla Model S.

manufacturer()[source]

Get a random car manufacturer.

Return type:

str

Returns:

A car manufacturer

Example:

Tesla.

vehicle_registration_code(locale=None)[source]

Get vehicle registration code of country.

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)[source]

Class for generating pseudo-scientific data.

dna_sequence(length=10)[source]

Generate a random DNA sequence.

Parameters:

length (int) – Length of block.

Return type:

str

Returns:

DNA sequence.

Example:

GCTTTAGACC

measure_unit(name=None, symbol=False)[source]

Get unit name from International System of Units.

Parameters:
Return type:

str

Returns:

Unit.

metric_prefix(sign=None, symbol=False)[source]

Get a random prefix for the International System of Units.

Parameters:
Return type:

str

Returns:

Metric prefix for SI measure units.

Raises:

NonEnumerableError – if sign is not supported.

Example:

mega

rna_sequence(length=10)[source]

Generate 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>, providers=None)[source]
get_random_instance()[source]

Get random object from Generic.

Return type:

Random

Returns:

Random object.

perform(name=None, key=None, **kwargs)[source]

Performs the value of the field by its name.

It takes any string which 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 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:

Value which represented by method.

Raises:

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

register_field(field_name, field_handler)[source]

Register a new field handler.

Parameters:
Return type:

None

register_fields(fields)[source]

Register a 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>)[source]

Reseed the random generator.

Parameters:

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

Return type:

None

unregister_all_fields()[source]

Unregister all field handlers.

Return type:

None

Returns:

None.

unregister_field(field_name)[source]

Unregister a field handler.

Parameters:

field_name (str) – Name of the field.

Return type:

None

unregister_fields(field_names=())[source]

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>, providers=None)[source]

Greedy field.

The field which 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)[source]

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)[source]

Class which return list of filled schemas.

__init__(schema, iterations=10)[source]

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()[source]

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)[source]

Export a schema as a CSV file.

Parameters:
Return type:

None

New in version 5.3.0

to_json(file_path, **kwargs)[source]

Export a schema as a JSON file.

Parameters:
  • file_path (str) – File path.

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

Return type:

None

New in version 5.3.0

to_pickle(file_path, **kwargs)[source]

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

Parameters:
  • file_path (str) – File path.

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

Return type:

None

New in version 5.3.0

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 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)[source]

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)[source]

Provides the audio file types.

An argument for audio()

AAC = 'aac'
MP3 = 'mp3'
class mimesis.enums.CardType(value)[source]

Provides credit card types.

An argument for credit_card_number().

AMERICAN_EXPRESS = 'American Express'
MASTER_CARD = 'MasterCard'
VISA = 'Visa'
class mimesis.enums.CompressedFile(value)[source]

Provides the compressed file types.

An argument for compressed()

GZIP = 'gz'
ZIP = 'zip'
class mimesis.enums.CountryCode(value)[source]

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)[source]

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)[source]

Provides the document file types.

An argument for document()

DOCX = 'docx'
PDF = 'pdf'
PPTX = 'pptx'
XLSX = 'xlsx'
class mimesis.enums.EANFormat(value)[source]

Provides formats of EAN.

An argument for ean().

EAN13 = 'ean-13'
EAN8 = 'ean-8'
class mimesis.enums.FileType(value)[source]

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)[source]

Represents genders.

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

FEMALE = 'female'
MALE = 'male'
class mimesis.enums.ISBNFormat(value)[source]

Provides formats of ISBN.

An argument for isbn().

ISBN10 = 'isbn-10'
ISBN13 = 'isbn-13'
class mimesis.enums.ImageFile(value)[source]

Provides the image file types.

An argument for image()

GIF = 'gif'
JPG = 'jpg'
PNG = 'png'
class mimesis.enums.Locale(value)[source]

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

An argument for all locale-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'
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()[source]
Return type:

List[str]

class mimesis.enums.MeasureUnit(value)[source]

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)[source]

Provides prefix signs.

An argument for metric_prefix()`().

NEGATIVE = 'negative'
POSITIVE = 'positive'
class mimesis.enums.MimeType(value)[source]

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)[source]

Provides the number types.

An argument for matrix().

COMPLEX = 'complexes'
DECIMAL = 'decimals'
FLOAT = 'floats'
INTEGER = 'integers'
class mimesis.enums.PortRange(value)[source]

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)[source]

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)[source]

An enumeration.

ISO_8601 = 2
POSIX = 1
RFC_3339 = 3
class mimesis.enums.TimezoneRegion(value)[source]

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)[source]

Represents title types.

An argument for title().

ACADEMIC = 'academic'
TYPICAL = 'typical'
class mimesis.enums.URLScheme(value)[source]

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)[source]

Provides the vide file types.

An argument for video()

MOV = 'mov'
MP4 = 'mp4'