API

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

Random

Implements various helpers which are used in the various data providers.

This module contains custom Random() class where implemented a lot of methods which are not included in standard random.Random, but frequently used in this project.

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

Custom class for the possibility of extending.

The class is a subclass of the class random.Random from the module random of the standard library, which provides the custom methods.

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.

generate_string(str_seq, length=10)[source]

Generate random string created from string sequence.

Parameters
  • str_seq (str) – String sequence of letters or digits.

  • length (int) – Max value.

Return type

str

Returns

Single string.

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.

randstr(unique=False, length=None)[source]

Generate random string value.

This method can be especially useful when you need to generate only unique values in your provider. Just pass parameter unique=True.

Basically, this method is just a simple wrapper around uuid.UUID.

Parameters
  • unique (bool) – Generate only unique values.

  • length (Optional[int]) – Length of string. Default range is [a, b].

Return type

str

Returns

Random string.

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

mimesis.random.get_random_item(enum, rnd=None)[source]

Get random item of enum object.

Parameters
Return type

Any

Returns

Random item of enum.

Builtin Data Providers

BrazilSpecProvider

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

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

class Meta[source]

The name of the provider.

__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).

class Meta[source]

The name of the provider.

__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).

class Meta[source]

The name of the provider.

__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).

class Meta[source]

The name of the provider.

__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).

class Meta[source]

The name of the provider.

__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).

class Meta[source]

The name of the provider.

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

mimesis.shortcuts.romanize(string, locale)[source]

Romanize a given string.

Supported locales are:

Locale.RU Locale.UK Locale.KK

Parameters
Return type

str

Returns

Romanized string.

Custom Exceptions

Custom exceptions which are used in Mimesis.

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

This is a base class for all providers.

__init__(*, seed=<mimesis.types._MissingSeed object>, **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

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

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

This is a base class for all data providers.

__init__(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>)[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.

Return type

None

Returns

None

Raises

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

add_providers(*providers)[source]

Add a lot of custom providers to Generic() object.

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

Locale-Dependent Providers

Address

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

Class for generate fake address data.

This object provides all the data related to geographical location.

class Meta[source]

Class for metadata.

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

Initialize attributes.

Parameters

locale – Current locale.

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

Get the country of the current locale.

Parameters

allow_random (bool) – Return a random country name.

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.

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(*args, **kwargs)[source]

Class for generating finance data.

class Meta[source]

Class for metadata.

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

Initialize attributes.

Parameters

locale – Current locale.

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(*args, **kwargs)[source]

Class for generating data related to the date and time.

class Meta[source]

Class for metadata.

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

Initialize attributes.

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=2000, 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(posix=True, **kwargs)[source]

Generate random timestamp.

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(*args, **kwargs)[source]

Class for generating data related to food.

class Meta[source]

Class for metadata.

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

Initialize attributes.

Parameters

locale – Current locale.

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.

class Meta[source]

Class for metadata.

__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

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.

telephone(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.

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

You can create many different usernames using masks.

  • C stands for capitalized username.

  • U stands for uppercase username.

  • l stands for lowercase username.

  • d stands for digits in 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.

Science

class mimesis.Science(*, seed=<mimesis.types._MissingSeed object>, **kwargs)[source]

Class for generating pseudo-scientific data.

class Meta[source]

Class for metadata.

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

Text

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

Class for generating text data.

class Meta[source]

Class for metadata.

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

Initialize attributes.

Parameters
  • locale – Current locale.

  • seed – Seed.

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.

swear_word()[source]

Get a random swear word.

Return type

str

Returns

Swear word.

Example

Damn.

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

class Meta[source]

Class for metadata.

__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>, **kwargs)[source]

A class, which provides methods for generating codes.

class Meta[source]

Class for metadata.

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

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

class Meta[source]

Class for metadata.

Cryptographic

class mimesis.Cryptographic(*, seed=<mimesis.types._MissingSeed object>, **kwargs)[source]

Class that provides cryptographic data.

class Meta[source]

Class for metadata.

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.

class Meta[source]

Class for metadata.

__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

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

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

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.

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(*args, **kwargs)[source]

Class for generate data related to files.

class Meta[source]

Class for metadata.

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

Initialize attributes.

Parameters
  • args (Any) – Arguments.

  • kwargs (Any) – Keyword arguments.

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>, **kwargs)[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.

class Meta[source]

Class for metadata.

__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

Content-Type: 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.

class Meta[source]

Class for metadata.

__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

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

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

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

class Meta[source]

Class for metadata.

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

class Meta[source]

Class for metadata.

__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>, **kwargs)[source]

Class for generating data related to transports.

class Meta[source]

Class for metadata.

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.

Schema-based Generators

BaseField

class mimesis.schema.BaseField(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>, providers=None)[source]

BaseField is a class for generating data by the name of the method.

Instance of this object takes any string which represents the name of any method of any supported data provider (Generic) and the **kwargs of the method.

See perform for more details.

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.

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

  • key (Optional[Callable[[Any], Any]]) – A key function (or any other 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.

Field

class mimesis.schema.Field(locale=Locale.EN, seed=<mimesis.types._MissingSeed object>, providers=None)[source]

Greedy field.

The field whcih evaluates immediately.

Warning

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

If you doing this:

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

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

Forewarned is forearmed.

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

Schema

class mimesis.schema.Schema(schema)[source]

Class which return list of filled schemas.

__init__(schema)[source]

Initialize schema.

Parameters

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

__mul__(other)[source]

Multiplies the schema by the number of iterations.

Schema multiplication is not lazy, so it will be performed immediately (in fact, you’re using create() under the hood).

Warning

Multiplying the large and nested schema with a large number is obviously a stupid idea, so be reasonable on choosing a multiplier.

Usage:

schema = Schema(lambda: {
    'email': _('username'),
    'token': _('token_hex', key=lambda x: x[:8])
})
print(schema * 2)
print(2 * schema)

Note

Keep in mind the priority and order of multipliers.

Instead of doing this:

>>> schema * 2 * 10

Where you evaluate the schema 2 times and then multiply the resulting list 10 times, you should do this:

>>> schema * (2 * 10) # Evaluates the schema 20 times.

In other words, the first multiplier evaluetes the schema:

>>> 1 * schema * 5

The result will be:

[
    {"email": "efforts1859@test.com", "token": "f4a29754"},
    {"email": "efforts1859@test.com", "token": "f4a29754"},
    {"email": "efforts1859@test.com", "token": "f4a29754"},
    {"email": "efforts1859@test.com", "token": "f4a29754"},
    {"email": "efforts1859@test.com", "token": "f4a29754"},
]

Because schema is evaluated first (1 * schema), and then the second multiplier is applied on the result of the first expression since.

Parameters

other (int) – The multiplier.

Return type

List[Dict[str, Any]]

create(iterations=1)[source]

Creates a list of a fulfilled schemas.

Note

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

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

Parameters

iterations (int) – Number of iterations.

Return type

List[Dict[str, Any]]

Returns

List of fulfilled schemas.

iterator(iterations=1)[source]

Fulfills schema in a lazy way.

Parameters

iterations (int) – Number of iterations.

Return type

Iterator[Dict[str, Any]]

Returns

List of fulfilled schemas.

loop()[source]

Fulfills a schema infinitely in a lazy way.

This method can be useful when you have some dynamic conditions in depend on which the generation must be interrupted.

Since data mimesis provides are limited, frequent calls of this method can cause data duplication.

Before using this method, ask yourself: Do I really need this? In most cases, the answer is: Nah, iterator() is enough.

Do not use this method without interrupt conditions, otherwise, you’re risking running out of memory.

If you’re accepting all risks below and want to suppress the warnings then use warnings.catch_warnings

Warning

Never (seriously) call list, tuple, set or any other callable which tries to evaluate the whole lazy object on this method — infinite called infinite for a reason.

Return type

Iterator[Dict[str, Any]]

Returns

An infinite iterator with fulfilled schemas.

to_csv(file_path, iterations=100, **kwargs)[source]

Export a schema as a CSV file.

Parameters
  • file_path (str) – File path.

  • iterations (int) – The required number of rows.

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

New in version 5.3.0

Return type

None

to_json(file_path, iterations=100, **kwargs)[source]

Export a schema as a JSON file.

Parameters
  • file_path (str) – File path.

  • iterations (int) – The required number of rows.

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

New in version 5.3.0

Return type

None

to_pickle(file_path, iterations=100, **kwargs)[source]

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

Parameters
  • file_path (str) – File path.

  • iterations (int) – The required number of rows.

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

New in version 5.3.0

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