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

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.

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.

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

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

Get a random country.

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.

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

Get code of the currency.

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.

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

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

__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+
child_count(max_children=5)

Get a count of children.

Parameters:max_children (int) – Maximum count of children.
Return type:int
Returns:Ints. Depend on previous generated age.
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 templates: (‘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:KeyError – 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.

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

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

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.

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

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

__init__(*args, **kwargs)

Initialize attributes.

Parameters:seed – Seed.
Return type:None
bytes(entropy=32)

Generate byte string containing entropy bytes.

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

Parameters:entropy (int) – Number of bytes.
Return type:bytes
Returns:Bytes.
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.
salt(size=16)

Generate salt chars (not cryptographically safe).

Parameters:size (int) – Salt size.
Return type:str
Returns:Salt.
token(entropy=32)

Generate hexadecimal string.

Parameters:entropy (int) – Number of bytes.
Return type:str
Returns: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.

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.

__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

Games

class mimesis.Games(seed=None)

Class for generating data related to the games.

game()

Get a random game from list of games.

Return type:str
Returns:Name of the game.
Example:Battlefield 1
gaming_platform()

Get random gaming platform.

Return type:str
Returns:Gaming platform
Example:PlayStation 4 Pro
genre()

Get a random genre of game.

Return type:str
Returns:Genre.
Example:Shooter
pegi_rating()

Get a random PEGI rating.

Return type:str
Returns:PEGI rating.
Example:PEGI 18
score(minimum=1, maximum=10)

Score of game.

Parameters:
  • minimum (int) – Maximum value.
  • maximum (int) – Minimum value.
Return type:

float

Returns:

Score.

score_phrase()

Get a random score phrase.

Return type:str
Returns:Score phrase.
Example:Great

Hardware

class mimesis.Hardware(seed=None)

Class for generate data related to hardware.

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.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:
  • args – Arguments.
  • kwargs – Keyword arguments.
category_of_website()

Get random category of torrent portal.

Returns:Category name.
Example:Video/TV shows
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.

subreddit(nsfw=False, full_url=False)

Get a random subreddit from the list.

Parameters:
  • nsfw (bool) – NSFW subreddit.
  • full_url (bool) – Full URL address.
Return type:

str

Returns:

Subreddit or URL to subreddit.

Example:

https://www.reddit.com/r/flask/

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.

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.

__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:Optional[str]
Returns:Path.
Example:/home/sherrell/Development/Python/mercenary
home()

Generate a home path.

Return type:Optional[str]
Returns:Home path.
Example:/home/
project_dir()

Generate a random path to project directory.

Return type:Optional[str]
Returns:Path to project.
Example:/home/sherika/Development/Falcon/mercenary
root()

Generate a root dir path.

Return type:Optional[str]
Returns:Root dir.
Example:/
user()

Generate a random user.

Return type:Optional[str]
Returns:Path to user.
Example:/home/oretha
users_folder()

Generate a random path to user’s folders.

Return type:Optional[str]
Returns:Path.
Example:/home/taneka/Pictures

Structure

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

Class for generating structured data.

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

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

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