API Reference

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

Builtin Data Providers

BrazilSpecProvider

class mimesis.builtins.BrazilSpecProvider(seed=None)

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

class Meta

The name of the provider.

__init__(seed=None)

Initialize attributes.

cnpj(with_mask=True)

Get a random CNPJ.

Parameters

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

Return type

str

Returns

Random cnpj.

Example

77.732.230/0001-70

cpf(with_mask=True)

Get a random CPF.

Parameters

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

Return type

str

Returns

Random CPF.

Example

001.137.297-40

DenmarkSpecProvider

class mimesis.builtins.DenmarkSpecProvider(seed=None)

Class that provides special data for Denmark (da).

class Meta

The name of the provider.

__init__(seed=None)

Initialize attributes.

cpr()

Generate a random CPR number (Central Person Registry).

Return type

str

Returns

CPR number.

Example

0105865167

GermanySpecProvider

class mimesis.builtins.GermanySpecProvider(seed=None)

Specific-provider of misc data for Germany.

class Meta

The name of the provider.

__init__(seed=None)

Initialize attributes.

noun(plural=False)

Return a random noun in German.

Parameters

plural (bool) – Return noun in plural.

Return type

str

Returns

Noun.

NetherlandsSpecProvider

class mimesis.builtins.NetherlandsSpecProvider(seed=None)

Class that provides special data for Netherlands (nl).

class Meta

The name of the provider.

__init__(seed=None)

Initialize attributes.

bsn()

Generate a random, but valid Burgerservicenummer.

Return type

str

Returns

Random BSN.

Example

255159705

burgerservicenummer()

Generate a random, but valid Burgerservicenummer.

An alias for self.bsn()

Return type

str

RussiaSpecProvider

class mimesis.builtins.RussiaSpecProvider(seed=None)

Class that provides special data for Russia (ru).

class Meta

The name of the provider.

__init__(seed=None)

Initialize attributes.

bic()

Generate random BIC (Bank ID Code).

Return type

str

Returns

BIC.

Example
generate_sentence()

Generate sentence from the parts.

Return type

str

Returns

Sentence.

inn()

Generate random, but valid INN.

Return type

str

Returns

INN.

kpp()

Generate random KPP.

Return type

str

Returns

‘KPP’.

Example
ogrn()

Generate random valid OGRN.

Return type

str

Returns

OGRN.

Example
passport_number()

Generate random passport number.

Return type

int

Returns

Number.

Example

560430

passport_series(year=None)

Generate random series of passport.

Parameters

year (int or None) – Year of manufacture.

Return type

str

Returns

Series.

Example

02 15.

patronymic(gender=None)

Generate random patronymic name.

Parameters

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

Return type

str

Returns

Patronymic name.

Example

Алексеевна.

series_and_number()

Generate a random passport number and series.

Return type

str

Returns

Series and number.

Example

57 16 805199.

snils()

Generate snils with special algorithm.

Return type

str

Returns

SNILS.

Example

UkraineSpecProvider

class mimesis.builtins.UkraineSpecProvider(seed=None)

Class that provides special data for Ukraine (uk).

class Meta

The name of the provider.

__init__(seed=None)

Initialize attributes.

patronymic(gender=None)

Generate random patronymic name.

Parameters

gender (str or int) – Gender of person.

Return type

str

Returns

Patronymic name.

USASpecProvider

class mimesis.builtins.USASpecProvider(seed=None)

Class that provides special data for USA (en).

class Meta

The name of the provider.

__init__(seed=None)

Initialize attributes.

personality(category='mbti')

Generate a type of personality.

Parameters

category (str) – Category.

Returns

Personality type.

Return type

str or int

Example

ISFJ.

ssn()

Generate a random, but valid SSN.

Return type

str

Returns

SSN.

Example

569-66-5801

tracking_number(service='usps')

Generate random tracking number.

Supported services: USPS, FedEx and UPS.

Parameters

service (str) – Post service.

Return type

str

Returns

Tracking number.

PolandSpecProvider

class mimesis.builtins.PolandSpecProvider(seed=None)

Class that provides special data for Poland (pl).

class Meta

The name of the provider.

__init__(seed=None)

Initialize attributes.

nip()

Generate random valid 10-digit NIP.

Return type

str

Returns

Valid 10-digit NIP

pesel(birth_date=None, gender=None)

Generate random 11-digit PESEL.

Parameters
  • birth_date (Optional[datetime]) – Initial birth date (optional)

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

Return type

str

Returns

Valid 11-digit PESEL

regon()

Generate random valid 9-digit REGON.

Return type

str

Returns

Valid 9-digit REGON

Decorators

Decorators for the public API and for internal purpose.

mimesis.decorators.romanized(locale='')

Romanize the Cyrillic text.

Transliterate the Cyrillic language from the Cyrillic script into the Latin alphabet.

Note

At this moment it works only for ru, uk, kk.

Parameters

locale (str) – Locale code.

Return type

Callable

Returns

Latinized text.

Custom Exceptions

UnsupportedAlgorithm

class mimesis.exceptions.UnsupportedAlgorithm

Raised when the user wants to use an unsupported algorithm.

UnsupportedField

class mimesis.exceptions.UnsupportedField(name=None)

Raises when field is not supported.

UnsupportedLocale

class mimesis.exceptions.UnsupportedLocale(locale=None)

Raised when a locale isn’t supported.

UndefinedField

class mimesis.exceptions.UndefinedField

Raises when field is None.

UndefinedSchema

class mimesis.exceptions.UndefinedSchema

Raised when schema is empty.

UnacceptableField

class mimesis.exceptions.UnacceptableField

Raises when the field has an unacceptable format.

NonEnumerableError

class mimesis.exceptions.NonEnumerableError(enum_obj)

Raised when object is not instance of Enum.

Base Providers

BaseProvider

class mimesis.providers.BaseProvider(seed=None)

This is a base class for all providers.

__init__(seed=None)

Initialize attributes.

Parameters

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

Return type

None

reseed(seed=None)

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[int, str, bytes, bytearray, None]) – Seed for random. When set to None the current system time is used.

Return type

None

BaseDataProvider

class mimesis.providers.BaseDataProvider(locale='en', seed=None)

This is a base class for all data providers.

__init__(locale='en', seed=None)

Initialize attributes for data providers.

Parameters
  • locale (str) – Current locale.

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

Return type

None

get_current_locale()

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='en')

Context manager which allows overriding current locale.

Temporarily overrides current locale for locale-dependent providers.

Parameters

locale (str) – Locale.

Return type

Generator[BaseDataProvider, None, None]

Returns

Provider with overridden locale.

pull(self, datafile='')

Pull the content from the JSON and memorize one.

Opens JSON file file in the folder data/locale and get content from the file and memorize ones using lru_cache.

Parameters

datafile (str) – The name of file.

Returns

The content of the file.

Raises

UnsupportedLocale – if locale is not supported.

Generic Providers

Generic

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

Class which contain all providers at one.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes lazily.

Parameters
  • args – Arguments.

  • kwargs – Keyword arguments.

Return type

None

add_provider(cls)

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)

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

Parameters

providers (Type[BaseProvider]) – Custom providers.

Return type

None

Returns

None

Locale-Dependent Providers

Address

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

Class for generate fake address data.

This object provides all the data related to geographical location.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters

locale – Current locale.

Return type

None

address()

Generate a random full address.

Return type

str

Returns

Full address.

calling_code()

Get a random calling code of random country.

Return type

str

Returns

Calling code.

city()

Get a random city.

Return type

str

Returns

City name.

continent(code=False)

Get a random continent name or continent code.

Parameters

code (bool) – Return code of continent.

Return type

str

Returns

Continent name.

coordinates(dms=False)

Generate random geo coordinates.

Parameters

dms (bool) – DMS format.

Return type

dict

Returns

Dict with coordinates.

country(allow_random=False)

Get the country of the current locale.

Allow_random

Return a random country name.

Return type

str

Returns

The Country.

country_code(fmt=<CountryCode.A2: 'a2'>)

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

fmt (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)

Get a random region.

An alias for state().

Return type

str

latitude(dms=False)

Generate a random value of latitude.

Parameters

dms (bool) – DMS format.

Return type

Union[str, float]

Returns

Value of longitude.

longitude(dms=False)

Generate a random value of longitude.

Parameters

dms (bool) – DMS format.

Return type

Union[str, float]

Returns

Value of longitude.

postal_code()

Generate a postal code for current locale.

Return type

str

Returns

Postal code.

prefecture(*args, **kwargs)

Get a random prefecture.

An alias for state().

Return type

str

province(*args, **kwargs)

Get a random province.

An alias for state().

Return type

str

region(*args, **kwargs)

Get a random region.

An alias for state().

Return type

str

state(abbr=False)

Get a random administrative district of country.

Parameters

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

Return type

str

Returns

Administrative district.

street_name()

Get a random street name.

Return type

str

Returns

Street name.

street_number(maximum=1400)

Generate a random street number.

Parameters

maximum (int) – Maximum value.

Return type

str

Returns

Street number.

street_suffix()

Get a random street suffix.

Return type

str

Returns

Street suffix.

zip_code()

Generate a zip code.

An alias for postal_code().

Return type

str

Returns

Zip code.

Business

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

Class for generating data for business.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters

locale – Current locale.

company()

Get a random company name.

Return type

str

Returns

Company name.

company_type(abbr=False)

Get a random type of business entity.

Parameters

abbr (bool) – Abbreviated company type.

Return type

str

Returns

Types of business entity.

copyright()

Generate a random copyright.

Return type

str

Returns

Copyright of company.

cryptocurrency_iso_code()

Get symbol of random cryptocurrency.

Return type

str

Returns

Symbol of cryptocurrency.

cryptocurrency_symbol()

Get a cryptocurrency symbol.

Return type

str

Returns

Symbol of cryptocurrency.

currency_iso_code(allow_random=False)

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()

Get a currency symbol for current locale.

Returns

Currency symbol.

price(minimum=10.0, maximum=1000.0)

Generate a random price.

Parameters
  • minimum (float) – Max value of price.

  • maximum (float) – Min value of price.

Return type

str

Returns

Price.

price_in_btc(minimum=0, maximum=2)

Generate random price in BTC.

Parameters
  • minimum (float) – Minimum value of price.

  • maximum (float) – Maximum value of price.

Return type

str

Returns

Price in BTC.

Datetime

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

Class for generating data related to the date and time.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters

locale – Current locale.

static bulk_create_datetimes(date_start, date_end, **kwargs)

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

See datetime module documentation for more: https://docs.python.org/3.7/library/datetime.html#timedelta-objects

Parameters
  • date_start (datetime) – Begin of the range.

  • date_end (datetime) – End of the range.

  • kwargs – Keyword arguments for datetime.timedelta

Return type

List[datetime]

Returns

List of datetime objects

Raises

ValueError: When date_start/date_end not passed and when date_start larger than date_end.

century()

Get a random century.

Return type

str

Returns

Century.

date(start=2000, end=2019)

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=2035, timezone=None)

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()

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)

Get a random day of week.

Parameters

abbr (bool) – Abbreviated day name.

Return type

str

Returns

Day of the week.

formatted_date(fmt='', **kwargs)

Generate random date as string.

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

  • kwargs – Keyword arguments for date()

Return type

str

Returns

Formatted date.

formatted_datetime(fmt='', **kwargs)

Generate datetime string in human readable format.

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

  • kwargs – Keyword arguments for datetime()

Return type

str

Returns

Formatted datetime string.

formatted_time(fmt='')

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()

Get a random GMT offset value.

Return type

str

Returns

GMT Offset.

month(abbr=False)

Get a random month.

Parameters

abbr (bool) – Abbreviated month name.

Return type

str

Returns

Month name.

periodicity()

Get a random periodicity string.

Return type

str

Returns

Periodicity.

time()

Generate a random time object.

Return type

time

Returns

datetime.time object.

timestamp(posix=True, **kwargs)

Generate random timestamp.

Parameters
  • posix (bool) – POSIX time.

  • kwargs – Kwargs for datetime().

Return type

Union[str, int]

Returns

Timestamp.

timezone()

Get a random timezone.

Return type

str

Returns

Timezone.

week_date(start=2017, end=2018)

Get week number with year.

Parameters
  • start (int) – From start.

  • end (int) – To end.

Return type

str

Returns

Week number.

year(minimum=1990, maximum=2050)

Generate a random year.

Parameters
  • minimum (int) – Minimum value.

  • maximum (int) – Maximum value.

Return type

int

Returns

Year.

Food

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

Class for generating data related to food.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters

locale – Current locale.

dish()

Get a random dish.

Return type

str

Returns

Dish name.

Example

Ratatouille.

drink()

Get a random drink.

Return type

str

Returns

Alcoholic drink.

Example

Vodka.

fruit()

Get a random fruit or berry.

Return type

str

Returns

Fruit name.

Example

Banana.

spices()

Get a random spices or herbs.

Return type

str

Returns

Spices or herbs.

Example

Anise.

vegetable()

Get a random vegetable.

Return type

str

Returns

Vegetable name.

Example

Tomato.

Person

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

Class for generating personal data.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters
  • locale – Current locale.

  • seed – Seed.

Return type

None

academic_degree()

Get a random academic degree.

Return type

str

Returns

Degree.

Example

Bachelor.

age(minimum=16, maximum=66)

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
avatar(size=256)

Generate a random avatar..

Parameters

size (int) – Size of avatar.

Return type

str

Returns

Link to avatar.

blood_type()

Get a random blood type.

Return type

str

Returns

Blood type (blood group).

Example

A+

email(domains=None)

Generate a random email.

Parameters

domains (list or tuple) – List of custom domains for emails.

Return type

str

Returns

Email address.

Example

foretime10@live.com

full_name(gender=None, reverse=False)

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)

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)

Generate a random height in M (Meter).

Parameters
  • minimum (float) – Minimum value.

  • maximum (float) – Maximum value.

Return type

str

Returns

Height.

Example

1.85.

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

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()

Get a random language.

Return type

str

Returns

Random language.

Example

Irish.

last_name(gender=None)

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)

Generate a random name.

Parameters

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

Return type

str

Returns

Name.

Example

John.

nationality(gender=None)

Get a random nationality.

Parameters

gender (Optional[Gender]) – Gender.

Return type

str

Returns

Nationality.

Example

Russian

occupation()

Get a random job.

Return type

str

Returns

The name of job.

Example

Programmer.

password(length=8, hashed=False)

Generate a password or hash of password.

Parameters
  • length (int) – Length of password.

  • hashed (bool) – MD5 hash.

Return type

str

Returns

Password or hash of password.

Example

k6dv2odff9#4h

political_views()

Get a random political views.

Return type

str

Returns

Political views.

Example

Liberal.

sexual_orientation(symbol=False)

Get a random (LOL) sexual orientation.

Parameters

symbol (bool) – Unicode symbol.

Return type

str

Returns

Sexual orientation.

Example

Heterosexuality.

social_media_profile(site=None)

Generate profile for random social network.

Return type

str

Returns

Profile in some network.

Example

http://facebook.com/some_user

surname(gender=None)

Generate a random surname.

Parameters

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

Return type

str

Returns

Surname.

Example

Smith.

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

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)

Generate a random title for name.

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

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

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

Return type

str

Returns

The title.

Raises

NonEnumerableError – if gender or title_type in incorrect format.

Example

PhD.

university()

Get a random university.

Return type

str

Returns

University name.

Example

MIT.

username(template=None)

Generate username by template.

Supported template placeholders: (U, l, d)

Supported separators: (-, ., _)

Template must contain at least one “U” or “l” placeholder.

If template is None one of the following templates is used: (‘U_d’, ‘U.d’, ‘U-d’, ‘UU-d’, ‘UU.d’, ‘UU_d’, ‘ld’, ‘l-d’, ‘Ud’, ‘l.d’, ‘l_d’, ‘default’)

Parameters

template (Optional[str]) – Template.

Return type

str

Returns

Username.

Raises

ValueError – If template is not supported.

Example

Celloid1873

views_on()

Get a random views on.

Return type

str

Returns

Views on.

Example

Negative.

weight(minimum=38, maximum=90)

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)

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()

Get a random worldview.

Return type

str

Returns

Worldview.

Example

Pantheism.

Science

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

Class for generating pseudo-scientific data.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters
  • locale – Current language.

  • seed – Seed.

atomic_number()

Generate random atomic number.

Return type

int

Returns

Atomic number

Example

92

chemical_element(name_only=True)

Generate a random chemical element.

Parameters

name_only (bool) – If False then will be returned dict.

Returns

Name of chemical element or dict.

Return type

dict or str

Example

{‘Symbol’: ‘S’, ‘Name’: ‘Sulfur’, ‘Atomic number’: ‘16’}

dna_sequence(length=10)

Generate a random DNA sequence.

Parameters

length (int) – Length of block.

Return type

str

Returns

DNA sequence.

Example

GCTTTAGACC

math_formula()

Get a random mathematical formula.

Return type

str

Returns

Math formula.

Example

A = (ab)/2.

rna_sequence(length=10)

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)

Class for generating text data.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters
  • locale – Current locale.

  • seed – Seed.

alphabet(lower_case=False)

Get an alphabet for current locale.

Parameters

lower_case (bool) – Return alphabet in lower case.

Return type

list

Returns

Alphabet.

answer()

Get a random answer in current language.

Return type

str

Returns

An answer.

Example

No

color()

Get a random name of color.

Return type

str

Returns

Color name.

Example

Red.

hex_color(safe=False)

Generate a random hex color.

Parameters

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

Return type

str

Returns

Hex color code.

Example

#d8346b

level()

Generate a random level of danger or something else.

Return type

str

Returns

Level.

Example

critical.

quote()

Get a random quote.

Return type

str

Returns

Quote from movie.

Example

“Bond… James Bond.”

rgb_color(safe=False)

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()

Get a random sentence from text.

Return type

str

Returns

Sentence.

swear_word()

Get a random swear word.

Return type

str

Returns

Swear word.

Example

Damn.

text(quantity=5)

Generate the text.

Parameters

quantity (int) – Quantity of sentences.

Return type

str

Returns

Text.

title()

Get a random title.

Return type

str

Returns

The title.

word()

Get a random word.

Return type

str

Returns

Single word.

Example

Science.

words(quantity=5)

Generate lis of the 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

Clothing

class mimesis.Clothing(seed=None)

Class for generate data related to clothing.

class Meta

Class for metadata.

custom_size(minimum=40, maximum=62)

Generate clothing size using custom format.

Parameters
  • minimum (int) – Minimum value.

  • maximum (int) – Maximum value.

Return type

int

Returns

Clothing size.

european_size()

Generate a random clothing size in European format.

Return type

int

Returns

Clothing size.

international_size()

Get a random size in international format.

Return type

str

Returns

Clothing size.

Code

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

Class that provides methods for generating codes.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters

locale – Current locale.

ean(fmt=None)

Generate EAN.

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

Parameters

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

Return type

str

Returns

EAN.

Raises

NonEnumerableError – if fmt is not enum EANFormat.

imei()

Generate a random IMEI.

Return type

str

Returns

IMEI.

isbn(fmt=None, locale='en')

Generate ISBN for current locale.

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

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

  • locale (str) – Locale code.

Return type

str

Returns

ISBN.

Raises

NonEnumerableError – if fmt is not enum ISBNFormat.

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

Generate a random ISSN.

Parameters

mask (str) – Mask of ISSN.

Return type

str

Returns

ISSN.

locale_code()

Get a random locale code (MS-LCID).

See Windows Language Code Identifier Reference for more information.

Return type

str

Returns

Locale code.

pin(mask='####')

Generate a random PIN code.

Parameters

mask (str) – Mask of pin code.

Return type

str

Returns

PIN code.

Choice

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

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

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters
  • args – Arguments.

  • kwargs – Keyword arguments.

Return type

None

Cryptographic

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

Class that provides cryptographic data.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters

seed – Seed.

Return type

None

hash(algorithm=None)

Generate random hash.

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

Parameters

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

Return type

str

Returns

Hash.

Raises

NonEnumerableError – if algorithm is not supported.

mnemonic_phrase(length=12)

Generate pseudo mnemonic phrase.

Parameters

length (int) – Number of words.

Return type

str

Returns

Mnemonic code.

static token_bytes(entropy=32)

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)

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)

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

Returns

URL-safe token.

uuid(version=None)

Generate random UUID.

Parameters

version (Optional[int]) – UUID version.

Return type

str

Returns

UUID

Development

class mimesis.Development(seed=None)

Class for getting fake data for Developers.

class Meta

Class for metadata.

boolean()

Get a random boolean value.

Return type

bool

Returns

True of False.

os()

Get a random operating system or distributive name.

Return type

str

Returns

The name of OS.

Example

Gentoo

programming_language()

Get a random programming language from the list.

Return type

str

Returns

Programming language.

Example

Erlang.

software_license()

Get a random software license.

Return type

str

Returns

License name.

Example

The BSD 3-Clause License.

version(calver=False, pre_release=False)

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)

Class for generate data related to files.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters
  • args – Arguments.

  • kwargs – Keyword arguments.

extension(file_type=None)

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)

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)

Get a random mime type from list.

Parameters

type – Enum object MimeType.

Return type

str

Returns

Mime type.

size(minimum=1, maximum=100)

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=None)

Class for generate data related to hardware.

class Meta

Class for metadata.

cpu()

Get a random CPU name.

Return type

str

Returns

CPU name.

Example

Intel® Core i7.

cpu_codename()

Get a random CPU code name.

Return type

str

Returns

CPU code name.

Example

Cannonlake.

cpu_frequency()

Get a random frequency of CPU.

Return type

str

Returns

Frequency of CPU.

Example

4.0 GHz.

cpu_model_code()

Get a random CPU model.

Return type

str

Returns

CPU model.

generation()

Get a random generation.

Return type

str

Returns

Generation of something.

Example

6th Generation.

graphics()

Get a random graphics.

Return type

str

Returns

Graphics.

Example

Intel® Iris™ Pro Graphics 6200.

manufacturer()

Get a random manufacturer.

Return type

str

Returns

Manufacturer.

Example

Dell.

phone_model()

Get a random phone model.

Return type

str

Returns

Phone model.

Example

Nokia Lumia 920.

ram_size()

Get a random size of RAM.

Return type

str

Returns

RAM size.

Example

16GB.

ram_type()

Get a random RAM type.

Return type

str

Returns

Type of RAM.

Example

DDR3.

resolution()

Get a random screen resolution.

Return type

str

Returns

Resolution of screen.

Example

1280x720.

screen_size()

Get a random size of screen in inch.

Return type

str

Returns

Screen size.

Example

13″.

ssd_or_hdd()

Get a random value from list.

Return type

str

Returns

HDD or SSD.

Example

512GB SSD.

Internet

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

Class for generating data related to the internet.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters
  • args – Arguments.

  • kwargs – Keyword arguments.

content_type(mime_type=None)

Get a random HTTP content type.

Return type

str

Returns

Content type.

Example

Content-Type: application/json

emoji()

Get a random emoji shortcut code.

Return type

str

Returns

Emoji code.

Example
kissing

hashtags(quantity=4)

Generate a list of hashtags.

Parameters

quantity (int) – The quantity of hashtags.

Return type

Union[str, list]

Returns

The list of hashtags.

Raises

NonEnumerableError – if category is not in Hashtag.

Example

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

home_page(tld_type=None)

Generate a random home page.

Parameters

tld_type (Optional[TLDType]) – TLD type.

Return type

str

Returns

Random home page.

Example

http://www.fontir.info

http_method()

Get a random HTTP method.

Return type

str

Returns

HTTP method.

Example

POST

http_status_code()

Get a random HTTP status code.

Return type

int

Returns

HTTP status.

Example

200

http_status_message()

Get a random HTTP status message.

Return type

str

Returns

HTTP status message.

Example

200 OK

static image_placeholder(width=1920, height=1080)

Generate a link to the image placeholder.

Parameters
  • width (Union[int, str]) – Width of image.

  • height (Union[int, str]) – Height of image.

Return type

str

Returns

URL to image placeholder.

ip_v4(with_port=False)

Generate a random IPv4 address.

Parameters

with_port (bool) – Add port to IP.

Return type

str

Returns

Random IPv4 address.

Example

19.121.223.58

ip_v6()

Generate a random IPv6 address.

Return type

str

Returns

Random IPv6 address.

Example

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

mac_address()

Generate a random MAC address.

Return type

str

Returns

Random MAC address.

Example

00:16:3e:25:e7:b1

network_protocol(layer=None)

Get a random network protocol form OSI model.

Parameters

layer (Optional[Layer]) – Enum object Layer.

Return type

str

Returns

Protocol name.

Example

AMQP

port(port_range=<PortRange.ALL: (1, 65535)>)

Generate random port.

Parameters

port_range (PortRange) – Range enum object.

Return type

int

Returns

Port number.

Raises

NonEnumerableError – if port_range is not in PortRange.

Example

8080

static stock_image(width=1920, height=1080, keywords=None, writable=False)

Generate random stock image (JPEG) hosted on Unsplash.

Note

This method required an active HTTP connection.

Parameters
  • width (Union[int, str]) – Width of the image.

  • height (Union[int, str]) – Height of the image.

  • keywords (Optional[List[str]]) – List of search keywords.

  • writable (bool) – Return image as sequence ob bytes.

Return type

Union[str, bytes]

Returns

Link to the image.

top_level_domain(tld_type=None)

Return random top level domain.

Parameters

tld_type (Optional[TLDType]) – Enum object DomainType

Return type

str

Returns

Top level domain.

Raises

NonEnumerableError – if tld_type not in DomainType.

user_agent()

Get a random user agent.

Return type

str

Returns

User agent.

Example

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

Numbers

class mimesis.Numbers(seed=None)

Class for generating numbers.

class Meta

Class for metadata.

between(minimum=1, maximum=1000)

Generate a random number between minimum and maximum.

Parameters
  • minimum (int) – Minimum of range.

  • maximum (int) – Maximum of range.

Return type

int

Returns

Number.

digit(to_bin=False)

Get a random digit.

Parameters

to_bin (bool) – If True then convert to binary.

Return type

Union[str, int]

Returns

Digit.

Example
floats(n=2)

Generate a list of random float numbers.

Parameters

n (int) – Raise 10 to the ‘n’ power.

Return type

List[float]

Returns

The list of floating-point numbers.

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

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.

  • length (int) – Length of list.

Return type

List[int]

Returns

List of integers.

Example

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

static primes(start=1, end=999)

Generate a list of prime numbers.

Parameters
  • start (int) – First value of range.

  • end (int) – Last value of range.

Return type

List[int]

Returns

A list of prime numbers from start to end.

rating(maximum=5.0)

Generate a random rating for something.

Parameters

maximum (float) – Maximum value (default is 5.0).

Return type

float

Returns

Rating.

Example

4.7

Path

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

Class that provides methods and property for generate paths.

class Meta

Class for metadata.

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

Initialize attributes.

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

Parameters

platform (str) – Required platform type.

Return type

None

dev_dir()

Generate a random path to development directory.

Return type

str

Returns

Path.

Example

/home/sherrell/Development/Python

home()

Generate a home path.

Return type

str

Returns

Home path.

Example

/home

project_dir()

Generate a random path to project directory.

Return type

str

Returns

Path to project.

Example

/home/sherika/Development/Falcon/mercenary

root()

Generate a root dir path.

Return type

str

Returns

Root dir.

Example

/

user()

Generate a random user.

Return type

str

Returns

Path to user.

Example

/home/oretha

users_folder()

Generate a random path to user’s folders.

Return type

str

Returns

Path.

Example

/home/taneka/Pictures

Structure

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

Class for generating structured data.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters
  • locale – Current locale.

  • seed – Seed.

Return type

None

css()

Generate a random snippet of CSS.

Return type

str

Returns

CSS.

css_property()

Generate a random snippet of CSS that assigns value to a property.

Return type

str

Returns

CSS property.

Examples

‘background-color: #f4d3a1’

html()

Generate a random HTML tag with text inside and some attrs set.

Return type

str

Returns

HTML.

Examples

‘<span class=”select” id=”careers”> Ports are created with the built-in function open_port. </span>’

html_attribute_value(tag=None, attribute=None)

Generate random value for specified HTML tag attribute.

Parameters
  • tag (Optional[str]) – An HTML tag.

  • attribute (Optional[str]) – An attribute of the specified tag.

Return type

str

Returns

An attribute.

Raises

NotImplementedError – if tag is unsupported.

Transport

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

Class for generating data related to transports.

class Meta

Class for metadata.

__init__(*args, **kwargs)

Initialize attributes.

Parameters
  • locale – Current locale.

  • seed – Seed.

Return type

None

airplane(model_mask='###')

Generate a dummy airplane model.

Parameters

model_mask (str) – Mask of truck model. Here ‘@’ is a placeholder of characters and ‘#’ is a placeholder of digits.

Return type

str

Returns

Airplane model.

Example

Boeing 727.

car()

Get a random vehicle.

Return type

str

Returns

A vehicle.

Example

Tesla Model S.

truck(model_mask='#### @@')

Generate a truck model.

Parameters

model_mask (str) – Mask of truck model. Here ‘@’ is a placeholder of characters and ‘#’ is a placeholder of digits.

Return type

str

Returns

Dummy truck model.

Example

Caledon-966O.

vehicle_registration_code(locale=None)

Get vehicle registration code of country.

Parameters

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

Return type

str

Returns

Vehicle registration code.

UnitSystem

class mimesis.UnitSystem(seed=None)

Class for generating data related to units.

class Meta

Class for metadata.

prefix(sign=None, symbol=False)

Get a random prefix for the International System of Units.

Parameters
  • sign (Optional[PrefixSign]) – Sing of number.

  • symbol (bool) – Return symbol of prefix.

Return type

str

Returns

Prefix for SI.

Raises

NonEnumerableError – if sign is not supported.

Example

mega

unit(name=None, symbol=False)

Get unit name.

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

  • symbol – Return only symbol

Returns

Unit.

Schema

AbstractField

class mimesis.schema.AbstractField(locale='en', seed=None, providers=None)

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

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

>>> _ = AbstractField('en', 0xf)
>>> surname = _('surname')
>>> isinstance(surname, str)
True

Field

mimesis.schema.Field

alias of mimesis.schema.AbstractField

Schema

class mimesis.schema.Schema(schema)

Class which return list of filled schemas.

create(iterations=1)

Return filled schema.

Create a list of a filled schemas with elements in an amount of iterations.

Parameters

iterations (int) – Amount of iterations.

Return type

List[Dict[str, Any]]

Returns

List of willed schemas.

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.

Example:
>>> from mimesis import Person
>>> from mimesis.enums import Gender
>>> person = Person()
>>> name = person.name(gender=Gender.FEMALE)
>>> name in person._data['names']['female']
True
class mimesis.enums.Algorithm

Provides algorithms which available.

MD5 = 'md5'
SHA1 = 'sha1'
SHA224 = 'sha224'
SHA256 = 'sha256'
SHA384 = 'sha384'
SHA512 = 'sha512'
class mimesis.enums.CardType

Provides credit card types.

An argument for credit_card_number().

AMERICAN_EXPRESS = 'American Express'
MASTER_CARD = 'MasterCard'
VISA = 'Visa'
class mimesis.enums.CountryCode

Provides types of country codes.

An argument for country_code().

A2 = 'a2'
A3 = 'a3'
FIFA = 'fifa'
IOC = 'ioc'
NUMERIC = 'numeric'
class mimesis.enums.EANFormat

Provides formats of EAN.

An argument for ean().

EAN13 = 'ean-13'
EAN8 = 'ean-8'
class mimesis.enums.FileType

Provides file types.

AUDIO = 'audio'
COMPRESSED = 'compressed'
DATA = 'data'
EXECUTABLE = 'executable'
IMAGE = 'image'
SOURCE = 'source'
TEXT = 'text'
VIDEO = 'video'
class mimesis.enums.Gender

Represents genders.

An argument for a lot of methods which takes argument gender.

FEMALE = 'female'
MALE = 'male'
class mimesis.enums.ISBNFormat

Provides formats of ISBN.

An argument for isbn().

ISBN10 = 'isbn-10'
ISBN13 = 'isbn-13'
class mimesis.enums.Layer

Provides network protocol layers.

An argument for network_protocol().

APPLICATION = 'application'
NETWORK = 'network'
PHYSICAL = 'physical'
PRESENTATION = 'presentation'
SESSION = 'session'
TRANSPORT = 'transport'
class mimesis.enums.MimeType

Provides common mime types.

An argument for mime_type().

APPLICATION = 'application'
AUDIO = 'audio'
IMAGE = 'image'
MESSAGE = 'message'
TEXT = 'text'
VIDEO = 'video'
class mimesis.enums.PortRange

Represents port ranges.

An argument for port().

ALL = (1, 65535)
EPHEMERAL = (49152, 65535)
REGISTERED = (1024, 49151)
WELL_KNOWN = (1, 1023)
class mimesis.enums.PrefixSign

Provides prefix signs.

An argument for prefix()`().

NEGATIVE = 'negative'
POSITIVE = 'positive'
class mimesis.enums.SocialNetwork

Provides most popular social networks.

An argument for social_media_profile()`().

FACEBOOK = 'facebook'
INSTAGRAM = 'instagram'
TWITTER = 'twitter'
VK = 'vk'
class mimesis.enums.TLDType

Provides top level domain types.

An argument for top_level_domain().

CCTLD = 'cctld'
GEOTLD = 'geotld'
GTLD = 'gtld'
STLD = 'stld'
UTLD = 'utld'
class mimesis.enums.TitleType

Represents title types.

An argument for title().

ACADEMIC = 'academic'
TYPICAL = 'typical'
class mimesis.enums.UnitName

Provide unit names.

An argument for 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')