API ¶

Returns:

Custom code.

randbytes(n=16)[source]¶

Generate n random bytes.

Return type:: bytes

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

Generate a list of random integers.

Parameters:

n (int) – Number of elements.
a (int) – Minimum value of range.
b (int) – Maximum value of range.

Return type:

list[int]

Returns:

List of random integers.

Raises:

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

uniform(a, b, precision=15)[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:

weighted_choice(choices)[source]¶

Returns a random element according to the specified weights.

Parameters:: choices (dict[Any, float]) – A dictionary where keys are choices and values are weights.
Raises:: ValueError – If choices are empty.
Return type:: Any
Returns:: Random key from dictionary.

Keys module¶

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

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

mimesis.keys.maybe(value, probability=0.5)[source]¶

Return a closure (a key function).

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

Parameters:

value (Any) – The value that may be returned.
probability (float) – The probability of returning value.

Return type:

Callable[[Any, Random], Any]

Returns:

A closure that takes two arguments.

mimesis.keys.romanize(locale)[source]¶

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

Supported locales are:

Locale.RU (Russian)
Locale.UK (Ukrainian)
Locale.KK (Kazakh)

Parameters:: locale (Locale) – Locale.
Return type:: Callable[[str], str]
Returns:: A closure that takes a string and returns a romanized string.

Builtin Data Providers¶

BrazilSpecProvider¶

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

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

__init__(seed=<mimesis.types._MissingSeed object>)[source]¶: Initialize attributes.

cnpj(with_mask=True)[source]¶

Get a random CNPJ.

Parameters:: with_mask (bool) – Use cnpj mask (###.###.###-##)
Return type:: str
Returns:: Random cnpj.
Example:: 77.732.230/0001-70

cpf(with_mask=True)[source]¶

Get a random CPF.

Parameters:: with_mask (bool) – Use CPF mask (###.###.###-##).
Return type:: str
Returns:: Random CPF.
Example:: 001.137.297-40

DenmarkSpecProvider¶

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

Class that provides special data for Denmark (da).

__init__(seed=<mimesis.types._MissingSeed object>)[source]¶: Initialize attributes.

cpr()[source]¶

Generate a random CPR number (Central Person Registry).

Return type:: str
Returns:: CPR number.
Example:: 0405420694

NetherlandsSpecProvider¶

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

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

__init__(seed=<mimesis.types._MissingSeed object>)[source]¶: Initialize attributes.

bsn()[source]¶

Generate a random, but valid Burgerservicenummer.

Return type:: str
Returns:: Random BSN.
Example:: 255159705

burgerservicenummer()[source]¶

Generate a random, but valid Burgerservicenummer.

An alias for self.bsn()

Return type:: str

RussiaSpecProvider¶

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

Class that provides special data for Russia (ru).

class Meta[source]¶: The name of the provider.

__init__(seed=<mimesis.types._MissingSeed object>)[source]¶: Initialize attributes.

bic()[source]¶

Generate random BIC (Bank ID Code).

Return type:

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:

Returns:

‘KPP’.

Example:

ogrn()[source]¶

Generate random valid OGRN.

Return type:

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 a special algorithm.

Return type:

Returns:

SNILS.

Example:

UkraineSpecProvider¶

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

Class that provides special data for Ukraine (uk).

__init__(seed=<mimesis.types._MissingSeed object>)[source]¶: Initialize attributes.

patronymic(gender=None)[source]¶

Generate random patronymic name.

Parameters:: gender (str or int) – Gender of person.
Return type:: str
Returns:: Patronymic name.

USASpecProvider¶

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

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

__init__(seed=<mimesis.types._MissingSeed object>)[source]¶: Initialize attributes.

ssn()[source]¶

Generate a random, but valid SSN.

Return type:: str
Returns:: SSN.
Example:: 569-66-5801

tracking_number(service='usps')[source]¶

Generate random tracking number.

Supported services: USPS, FedEx and UPS.

Parameters:: service (str) – Post service.
Return type:: str
Returns:: Tracking number.

PolandSpecProvider¶

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

Class that provides special data for Poland (pl).

__init__(seed=<mimesis.types._MissingSeed object>)[source]¶: Initialize attributes.

nip()[source]¶

Generate random valid 10-digit NIP.

Return type:: str
Returns:: Valid 10-digit NIP

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

Generate random 11-digit PESEL.

Parameters:

birth_date (Optional[datetime]) – Initial birthdate (optional)
gender (Optional[Gender]) – Gender of the person.

Return type:

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.

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

Parameters:: num (str) – The number to calculate a checksum for as a string.
Return type:: str
Returns:: Checksum for number.

Custom Exceptions¶

Custom exceptions which are used in Mimesis.

exception mimesis.exceptions.AliasesTypeError[source]¶: Raised when the aliases attribute is set to a format other than a flat dictionary.

exception mimesis.exceptions.FieldArityError[source]¶: Raised when registering field handler has incompatible arity.

exception mimesis.exceptions.FieldError(name=None)[source]¶: Raised when field is not found.

exception mimesis.exceptions.FieldNameError(name=None)[source]¶: Raised when a field name is invalid.

exception mimesis.exceptions.FieldsetError[source]¶: Raised when a resulting fieldset is empty.

exception mimesis.exceptions.LocaleError(locale)[source]¶: Raised when a locale isn’t supported.

exception mimesis.exceptions.NonEnumerableError(enum_obj)[source]¶: Raised when an object is not an instance of Enum.

exception mimesis.exceptions.SchemaError[source]¶: Raised when a schema is unsupported.

Base Providers¶

BaseProvider¶

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

This is a base class for all providers.

Attr:: random: An instance of mimesis.random.Random.
Attr:: seed: Seed for random.

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

Initialize attributes.

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

Parameters:

seed (UnionType[None, int, float, str, bytes, bytearray, _MissingSeed]) – Seed for random. When set to None the current system time is used.
random (Optional[Random]) – Custom random. See https://github.com/lk-geimfari/mimesis/issues/1313 for details.

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

Reseeds the internal random generator.

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

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

validate_enum(item, enum)[source]¶

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

Parameters:

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

Return type:

Any

Returns:

Value of item.

Raises:

NonEnumerableError – If enums has not such an item.

BaseDataProvider¶

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

This is a base class for all data providers.

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

Initialize attributes for data providers.

Parameters:

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

get_current_locale()[source]¶

Returns current locale.

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

Return type:: str
Returns:: Current locale.

override_locale(locale)[source]¶

Context manager that allows overriding current locale.

Temporarily overrides current locale for locale-dependent providers.

Parameters:: locale (Locale) – Locale.
Return type:: Generator[BaseDataProvider, None, None]
Returns:: Provider with overridden locale.

update_dataset(data)[source]¶

Updates dataset merging a given dict into default data.

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

Return type:: None

Generic Providers¶

Generic¶

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

Adds a custom provider to a Generic() object.

Parameters:

cls (Type[BaseProvider]) – Custom provider.
kwargs (Any) – Keyword arguments for provider.

Raises:

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

Return type:

Returns:

Absolutely none.

add_providers(*providers)[source]¶

Adds multiple custom providers to a Generic() object.

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

Example:

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

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

Parameters:: providers (Type[BaseProvider]) – Custom providers.
Return type:: None
Returns:: None

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

Reseed the internal random generator.

Overrides method BaseProvider.reseed().

Parameters:: seed (UnionType[None, int, float, str, bytes, bytearray, _MissingSeed]) – Seed for random.
Return type:: None
Returns:: None.

Locale-Dependent Providers¶

Address¶

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

Class for generate fake address data.

This object provides all the data related to geographical location.

address()[source]¶

Generates a random full address.

Return type:: str
Returns:: Full address.

calling_code()[source]¶

Generates a random calling code of random country.

Return type:: str
Returns:: Calling code.

city()[source]¶

Generates a random city.

Return type:: str
Returns:: City name.

continent(code=False)[source]¶

Returns a random continent name or continent code.

Parameters:: code (bool) – Return code of a continent.
Return type:: str
Returns:: Continent name.

coordinates(dms=False)[source]¶

Generates random geo coordinates.

Parameters:: dms (bool) – DMS format.
Return type:: dict[str, str | float]
Returns:: Dict with coordinates.

country()[source]¶

Generates a random country.

Return type:: str
Returns:: The Country.

country_code(code=CountryCode.A2)[source]¶

Generates a random code of country.

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

Parameters:: code (Optional[CountryCode]) – Country code.
Return type:: str
Returns:: Country code in selected format.
Raises:: KeyError – if fmt is not supported.

country_emoji_flag()[source]¶

Generates a randomly chosen country emoji flag.

Example:: 🇹🇷
Return type:: str
Returns:: Flag emoji.

default_country()[source]¶

Returns the country associated with the current locale.

Return type:: str
Returns:: The country associated with current locale.

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

Generates a random federal_subject (Russia).

An alias for state().

Return type:: str

iata_code()[source]¶

Generates a random IATA code.

Return type:: str
Returns:: IATA code.

icao_code()[source]¶

Generates a random ICAO code.

Return type:: str
Returns:: ICAO code.

isd_code()[source]¶

Generates a random ISD code.

An alias for calling_code().

Return type:: str

latitude(dms=False)[source]¶

Generates a random value of latitude.

Parameters:: dms (bool) – DMS format.
Return type:: str | float
Returns:: Value of longitude.

longitude(dms=False)[source]¶

Generates a random value of longitude.

Parameters:: dms (bool) – DMS format.
Return type:: str | float
Returns:: Value of longitude.

postal_code()[source]¶

Generates a postal code for current locale.

Return type:: str
Returns:: Postal code.

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

Generates a random prefecture.

An alias for state().

Return type:: str

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

Generates a random province.

An alias for state().

Return type:: str

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

Generates a random region.

An alias for state().

Return type:: str

state(abbr=False)[source]¶

Generates a random administrative district of the country.

Parameters:: abbr (bool) – Return ISO 3166-2 code.
Return type:: str
Returns:: Administrative district.

street_name()[source]¶

Generates a random street name.

Return type:: str
Returns:: Street name.

street_number(maximum=1400)[source]¶

Generates a random street number.

Parameters:: maximum (int) – Maximum value.
Return type:: str
Returns:: Street number.

street_suffix()[source]¶

Generates a random street suffix.

Return type:: str
Returns:: Street suffix.

zip_code()[source]¶

Generates a zip code.

An alias for postal_code().

Return type:: str
Returns:: Zip code.

Finance¶

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

Class to generate finance and business related data.

bank()[source]¶

Generates a random bank name.

Return type:: str
Returns:: Bank name.

company()[source]¶

Generates a random company name.

Return type:: str
Returns:: Company name.

company_type(abbr=False)[source]¶

Generates a random type of business entity.

Parameters:: abbr (bool) – Abbreviated company type.
Return type:: str
Returns:: Types of business entity.

cryptocurrency_iso_code()[source]¶

Generates a random cryptocurrency ISO code.

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]¶

Returns a currency code for current locale.

Parameters:: allow_random (bool) – Get a random ISO code.
Return type:: str
Returns:: Currency code.

currency_symbol()[source]¶

Returns a currency symbol for current locale.

Return type:: str
Returns:: Currency symbol.

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

Generate a random price.

Parameters:

minimum (float) – Minimum value of price.
maximum (float) – Maximum value of price.

Return type:

Returns:

Price.

price_in_btc(minimum=0, maximum=2)[source]¶

Generates a random price in BTC.

Parameters:

minimum (float) – Minimum value of price.
maximum (float) – Maximum value of price.

Return type:

Returns:

Price in BTC.

stock_exchange()[source]¶

Generates a stock exchange name.

Return type:: str
Returns:: Returns exchange name.

stock_name()[source]¶

Generates a stock name.

Return type:: str
Returns:: Stock name.

stock_ticker()[source]¶

Generates a random stock ticker.

Return type:: str
Returns:: Ticker.

Datetime¶

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

Class for generating data related to the date and time.

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

Bulk create datetime objects.

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

You can use the following keyword arguments:

days
hours
minutes
seconds
microseconds

Warning

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

See datetime.timedelta for more details.

Parameters:

date_start (datetime) – Begin of the range.
date_end (datetime) – End of the range.
kwargs (Any) – Keyword arguments for datetime.timedelta

Return type:

list[datetime]

Returns:

List of datetime objects

Raises:

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

century()[source]¶

Generates a random century.

Return type:: str
Returns:: Century.

date(start=2000, end=2024)[source]¶

Generates a random date object.

Parameters:

start (int) – Minimum value of year.
end (int) – Maximum value of year.

Return type:

date

Returns:

Formatted date.

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

Generates random datetime.

Parameters:

start (int) – Minimum value of year.
end (int) – Maximum value of year.
timezone (Optional[str]) – Set custom timezone (pytz required).

Return type:

datetime

Returns:

Datetime

day_of_month()[source]¶

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

Return type:: int
Returns:: Random value from 1 to 31.

day_of_week(abbr=False)[source]¶

Generates a random day of the week.

Parameters:: abbr (bool) – Abbreviated day name.
Return type:: str
Returns:: Day of the week.

duration(min_duration=1, max_duration=10, duration_unit=DurationUnit.MINUTES)[source]¶

Generate a random duration.

The default duration unit is Duration.MINUTES.

When the duration unit is None, then random duration from DurationUnit is chosen.

A timedelta object represents a duration, the difference between two datetime or date instances.

Parameters:

min_duration (int) – Minimum duration.
max_duration (int) – Maximum duration.
duration_unit (Optional[DurationUnit]) – Duration unit.

Return type:

timedelta

Returns:

Duration as timedelta.

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

Generates random date as string.

Parameters:

fmt (str) – The format of date, if None then use standard accepted in the current locale.
kwargs (Any) – Keyword arguments for date()

Return type:

Returns:

Formatted date.

formatted_datetime(fmt='', **kwargs)[source]¶

Generates datetime string in human-readable format.

Parameters:

fmt (str) – Custom format (default is format for current locale)
kwargs (Any) – Keyword arguments for datetime()

Return type:

Returns:

Formatted datetime string.

formatted_time(fmt='')[source]¶

Generates formatted time as string.

Parameters:: fmt (str) – The format of time, if None then use standard accepted in the current locale.
Return type:: str
Returns:: String formatted time.

gmt_offset()[source]¶

Generates a random GMT offset value.

Return type:: str
Returns:: GMT Offset.

month(abbr=False)[source]¶

Generates a random month of the year.

Parameters:: abbr (bool) – Abbreviated month name.
Return type:: str
Returns:: Month name.

periodicity()[source]¶

Generates a random periodicity string.

Return type:: str
Returns:: Periodicity.

time()[source]¶

Generates a random time object.

Return type:: time
Returns:: datetime.time object.

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

Generates a random timestamp in given format.

Supported formats are:

TimestampFormat.POSIX
TimestampFormat.RFC_3339
TimestampFormat.ISO_8601

Example:

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

Parameters:

fmt (TimestampFormat) – Format of timestamp (Default is TimestampFormat.POSIX).
kwargs (Any) – Kwargs for datetime().

Return type:

str | int

Returns:

Timestamp.

timezone(region=None)[source]¶

Generates a random timezone.

Parameters:: region (Optional[TimezoneRegion]) – Timezone region.
Return type:: str
Returns:: Timezone.

week_date(start=2017, end=2024)[source]¶

Generates week number with year.

Parameters:

start (int) – Starting year.
end (int) – Ending year.

Return type:

Returns:

Week number.

year(minimum=1990, maximum=2024)[source]¶

Generates a random year.

Parameters:

minimum (int) – Minimum value.
maximum (int) – Maximum value.

Return type:

int

Returns:

Year.

Food¶

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

Class for generating data related to food.

dish()[source]¶

Generates a random dish name.

Return type:: str
Returns:: Dish name.
Example:: Ratatouille.

drink()[source]¶

Generates a random drink name.

Return type:: str
Returns:: Drink name.
Example:: Vodka.

fruit()[source]¶

Generates a random fruit or berry name.

Return type:: str
Returns:: Fruit name.
Example:: Banana.

spices()[source]¶

Generates a random spices/herb name.

Return type:: str
Returns:: The name of the spices or herbs.
Example:: Anise.

vegetable()[source]¶

Generates a random vegetable name.

Return type:: str
Returns:: Vegetable name.
Example:: Tomato.

Person¶

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

Class for generating personal data.

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

Initialize attributes.

Parameters:

locale – Current locale.
seed – Seed.

academic_degree()[source]¶

Generates a random academic degree.

Return type:: str
Returns:: Degree.
Example:: Bachelor.

birthdate(min_year=1980, max_year=2023)[source]¶

Generates a random birthdate as a datetime.date object.

Parameters:

min_year (int) – Maximum birth year.
max_year (int) – Minimum birth year.

Return type:

date

Returns:

Random date object.

blood_type()[source]¶

Generates a random blood type.

Return type:: str
Returns:: Blood type (blood group).
Example:: A+

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

Generates a random email.

Parameters:

domains (Optional[Sequence[str]]) – List of custom domains for emails.
unique (bool) – Makes email addresses unique.

Return type:

Returns:

Email address.

Raises:

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

Example:

foretime10@live.com

first_name(gender=None)[source]¶

Generates a random first name.

..note: An alias for name().

Parameters:: gender (Optional[Gender]) – Gender’s enum object.
Return type:: str
Returns:: First name.

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

Generates a random full name.

Parameters:

reverse (bool) – Return reversed full name.
gender (Optional[Gender]) – Gender’s enum object.

Return type:

Returns:

Full name.

Example:

Johann Wolfgang.

gender()[source]¶

Generates a random gender title.

Example:: Male
Return type:: str

gender_code()[source]¶

Generate a random ISO/IEC 5218 gender code.

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

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

Return type:: int
Returns:

gender_symbol()[source]¶

Generate a random sex symbol.

Example:: ♂
Return type:: str

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

Generates a random height in meters.

Parameters:

minimum (float) – Minimum value.
maximum (float) – Maximum value.

Return type:

Returns:

Height.

Example:

1.85.

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

Generates a random identifier by mask.

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

Parameters:: mask (str) – The mask. Here @ is a placeholder for characters and # is placeholder for digits.
Return type:: str
Returns:: An identifier.
Example:: 07-97/04

language()[source]¶

Generates a random language name.

Return type:: str
Returns:: Random language.
Example:: Irish.

last_name(gender=None)[source]¶

Generates a random last name.

..note: An alias for surname().

Parameters:: gender (Optional[Gender]) – Gender’s enum object.
Return type:: str
Returns:: Last name.

name(gender=None)[source]¶

Generates a random name.

Parameters:: gender (Optional[Gender]) – Gender’s enum object.
Return type:: str
Returns:: Name.
Example:: John.

nationality(gender=None)[source]¶

Generates a random nationality.

Parameters:: gender (Optional[Gender]) – Gender.
Return type:: str
Returns:: Nationality.
Example:: Russian

occupation()[source]¶

Generates a random job.

Return type:: str
Returns:: The name of job.
Example:: Programmer.

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

Generates a password or hash of password.

Parameters:

length (int) – Length of password.
hashed (bool) – SHA256 hash.

Return type:

Returns:

Password or hash of password.

Example:

k6dv2odff9#4h

phone_number(mask='', placeholder='#')[source]¶

Generates a random phone number.

Parameters:

mask (str) – Mask for formatting number.
placeholder (str) – A placeholder for a mask (default is #).

Return type:

Returns:

Phone number.

Example:

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

political_views()[source]¶

Get a random political views.

Return type:: str
Returns:: Political views.
Example:: Liberal.

sex()[source]¶

An alias for method gender().

Return type:: str
Returns:: Sex.

surname(gender=None)[source]¶

Generates a random surname.

Parameters:: gender (Optional[Gender]) – Gender’s enum object.
Return type:: str
Returns:: Surname.
Example:: Smith.

telephone(*args, **kwargs)[source]¶

An alias for phone_number().

Return type:: str

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

Generates a random title for name.

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

Parameters:

gender (Optional[Gender]) – The gender.
title_type (Optional[TitleType]) – TitleType enum object.

Return type:

Returns:

The title.

Raises:

NonEnumerableError – if gender or title_type in incorrect format.

Example:

PhD.

university()[source]¶

Generates a random university name.

Return type:: str
Returns:: University name.
Example:: MIT.

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

Generates a username by mask.

Masks allow you to generate a variety of usernames.

C stands for capitalized username.
U stands for uppercase username.
l stands for lowercase username.
d stands for digits in the username.

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

Parameters:

mask (Optional[str]) – Mask.
drange (tuple[int, int]) – Digits range.

Raises:

ValueError – If template is not supported.

Return type:

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]¶

Generates a random weight in Kg.

Parameters:

minimum (int) – min value
maximum (int) – max value

Return type:

int

Returns:

Weight.

Example:

worldview()[source]¶

Generates a random worldview.

Return type:: str
Returns:: Worldview.
Example:: Pantheism.

Text¶

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

Class for generating text data.

__init__(*args, **kwargs)[source]¶: Initialize attributes.

alphabet(lower_case=False)[source]¶

Returns an alphabet for current locale.

Parameters:: lower_case (bool) – Return alphabet in lower case.
Return type:: list[str]
Returns:: Alphabet.

answer()[source]¶

Generates a random answer in the current language.

Return type:: str
Returns:: An answer.
Example:: No

color()[source]¶

Generates a random color name.

Return type:: str
Returns:: Color name.
Example:: Red.

emoji(category=EmojyCategory.DEFAULT)[source]¶

Generates a random emoji from the specified category.

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

Parameters:: category (Optional[EmojyCategory]) – EmojyCategory.
Raises:: NonEnumerableError – When category is not supported.
Return type:: str
Returns:: Emoji code.
Example:: 😟

hex_color(safe=False)[source]¶

Generates a random HEX color.

Parameters:: safe (bool) – Get safe Flat UI hex color.
Return type:: str
Returns:: Hex color code.
Example:: #d8346b

level()[source]¶

Generates a word that indicates a level of something.

Return type:: str
Returns:: Level.
Example:: critical.

quote()[source]¶

Generates a random quote.

Return type:: str
Returns:: Random quote.
Example:: “Bond… James Bond.”

rgb_color(safe=False)[source]¶

Generates a random RGB color tuple.

Parameters:: safe (bool) – Get safe RGB tuple.
Return type:: tuple[int, ...]
Returns:: RGB tuple.
Example:: (252, 85, 32)

sentence()[source]¶

Generates a random sentence from the text.

Return type:: str
Returns:: Sentence.

text(quantity=5)[source]¶

Generates the text.

Parameters:: quantity (int) – Quantity of sentences.
Return type:: str
Returns:: Text.

title()[source]¶

Generates a random title.

Return type:: str
Returns:: The title.

word()[source]¶

Generates a random word.

Return type:: str
Returns:: Single word.
Example:: Science.

words(quantity=5)[source]¶

Generates a list of random words.

Parameters:: quantity (int) – Quantity of words. Default is 5.
Return type:: list[str]
Returns:: Word list.
Example:: [science, network, god, octopus, love]

Locale-Independent Providers¶

BinaryFile¶

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

Class for generating binary data

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

Initialize attributes.

Parameters:

locale – Current locale.
seed – Seed.

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

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

Note

This method accepts keyword-only arguments.

Parameters:: file_type (AudioFile) – File extension.
Return type:: bytes
Returns:: File as a sequence of bytes.

compressed(*, file_type=CompressedFile.ZIP)[source]¶

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

Note

This method accepts keyword-only arguments.

Parameters:: file_type (CompressedFile) – File extension.
Return type:: bytes
Returns:: File as a sequence of bytes.

document(*, file_type=DocumentFile.PDF)[source]¶

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

Note

This method accepts keyword-only arguments.

Parameters:: file_type (DocumentFile) – File extension.
Return type:: bytes
Returns:: File as a sequence of bytes.

image(*, file_type=ImageFile.PNG)[source]¶

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

Note

This method accepts keyword-only arguments.

Parameters:: file_type (ImageFile) – File extension.
Return type:: bytes
Returns:: File as a sequence of bytes.

video(*, file_type=VideoFile.MP4)[source]¶

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

Note

This method accepts keyword-only arguments.

Parameters:: file_type (VideoFile) – File extension.
Return type:: bytes
Returns:: File as a sequence of bytes.

Code¶

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

A class, which provides methods for generating codes.

ean(fmt=None)[source]¶

Generates EAN.

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

Parameters:: fmt (Optional[EANFormat]) – Format of EAN.
Return type:: str
Returns:: EAN.
Raises:: NonEnumerableError – if code is not enum EANFormat.

imei()[source]¶

Generates a random IMEI.

Return type:: str
Returns:: IMEI.

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

Generates ISBN for current locale.

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

Parameters:

fmt (Optional[ISBNFormat]) – ISBN format.
locale (Locale) – Locale code.

Return type:

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

Returns:

ISBN.

Raises:

NonEnumerableError – if code is not enum ISBNFormat.

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

Generates a random ISSN.

Parameters:: mask (str) – Mask of ISSN.
Return type:: str
Returns:: ISSN.

locale_code()[source]¶

Generates a random locale code (MS-LCID).

See Windows Language Code Identifier Reference for more information.

Return type:: str
Returns:: Locale code.

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

Generates a random PIN code.

Parameters:: mask (str) – Mask of pin code.
Return type:: str
Returns:: PIN code.

Choice¶

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

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

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

Choice random item form sequence.

Parameters:

args (Any) – Positional arguments.
kwargs (Any) – Keyword arguments.

Return type:

Any

Returns:

Sequence or uncontained element randomly chosen from items.

Cryptographic¶

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

Class that provides cryptographic data.

hash(algorithm=None)[source]¶

Generates random hash.

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

Warning

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

Parameters:: algorithm (Optional[Algorithm]) – Enum object Algorithm.
Return type:: str
Returns:: Hash.
Raises:: NonEnumerableError – When algorithm is unsupported.

mnemonic_phrase()[source]¶

Generates BIP-39 looking mnemonic phrase.

Return type:: str
Returns:: Mnemonic phrase.

static token_bytes(entropy=32)[source]¶

Generates byte string containing entropy bytes.

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

Warning

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

Parameters:: entropy (int) – Number of bytes (default: 32).
Return type:: bytes
Returns:: Random bytes.

static token_hex(entropy=32)[source]¶

Generates a random text string, in hexadecimal.

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

Warning

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

Parameters:: entropy (int) – Number of bytes (default: 32).
Return type:: str
Returns:: Token.

static token_urlsafe(entropy=32)[source]¶

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

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

Warning

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

Parameters:: entropy (int) – Number of bytes (default: 32).
Return type:: str
Returns:: URL-safe token.

uuid()[source]¶

Generates UUID4 string.

Return type:: str
Returns:: UUID4 as string.

static uuid_object()[source]¶

Generates UUID4 object.

Return type:: UUID
Returns:: UUID4 object.

Development¶

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

Class for getting fake data for Developers.

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

Initialize attributes.

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

Parameters:

seed – Seed for random. When set to None the current system time is used.
random – Custom random. See https://github.com/lk-geimfari/mimesis/issues/1313 for details.

boolean()[source]¶

Generates a random boolean value.

Return type:: bool
Returns:: True of False.

calver()[source]¶

Generates a random calendar versioning string.

Return type:: str
Returns:: Calendar versioning string.
Example:: 2016.11.08

ility()[source]¶

Generates a random system quality attribute.

An alias for system_quality_attribute().

Return type:: str

os()[source]¶

Generates a random operating system or distributive name.

Return type:: str
Returns:: The name of OS.
Example:: Gentoo

programming_language()[source]¶

Generates a random programming language from the list.

Return type:: str
Returns:: Programming language.
Example:: Erlang.

software_license()[source]¶

Generates a random software license.

Return type:: str
Returns:: License name.
Example:: The BSD 3-Clause License.

stage()[source]¶

Generates a random stage of development.

Return type:: str
Returns:: Release stage.
Example:: Alpha.

system_quality_attribute()[source]¶

Generates a random system quality attribute.

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

Return type:: str
Returns:: System quality attribute.

version()[source]¶

Generates a random semantic versioning string.

Return type:: str
Returns:: Semantic versioning string.
Example:: 0.2.1

File¶

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

Class for generate data related to files.

extension(file_type=None)[source]¶

Generates a random file extension.

Parameters:: file_type (Optional[FileType]) – Enum object FileType.
Return type:: str
Returns:: Extension of the file.
Example:: .py

file_name(file_type=None)[source]¶

Generates a random file name with an extension.

Parameters:: file_type (Optional[FileType]) – Enum object FileType
Return type:: str
Returns:: File name.
Example:: legislative.txt

mime_type(type_=None)[source]¶

Generates a random mime type.

Parameters:: type – Enum object MimeType.
Return type:: str
Returns:: Mime type.

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

Generates a random file size as string.

Parameters:

minimum (int) – Maximum value.
maximum (int) – Minimum value.

Return type:

Returns:

Size of file.

Example:

56 kB

Hardware¶

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

Class for generate data related to hardware.

class Meta[source]¶: Class for metadata.

cpu()[source]¶

Generates a random CPU name.

Return type:: str
Returns:: CPU name.
Example:: Intel® Core i7.

cpu_codename()[source]¶

Generates a random CPU code name.

Return type:: str
Returns:: CPU code name.
Example:: Cannonlake.

cpu_frequency()[source]¶

Generates a random frequency of CPU.

Return type:: str
Returns:: Frequency of CPU.
Example:: 4.0 GHz.

generation()[source]¶

Generates a random generation.

Return type:: str
Returns:: Generation of something.
Example:: 6th Generation.

graphics()[source]¶

Generates a random graphics card name.

Return type:: str
Returns:: Graphics.
Example:: Intel® Iris™ Pro Graphics 6200.

manufacturer()[source]¶

Generates a random manufacturer of hardware.

Return type:: str
Returns:: Manufacturer.
Example:: Dell.

phone_model()[source]¶

Generates a random phone model.

Return type:: str
Returns:: Phone model.
Example:: Nokia Lumia 920.

ram_size()[source]¶

Generates a random size of RAM.

Return type:: str
Returns:: RAM size.
Example:: 16GB.

ram_type()[source]¶

Generates a random RAM type.

Return type:: str
Returns:: Type of RAM.
Example:: DDR3.

resolution()[source]¶

Generates a random screen resolution.

Return type:: str
Returns:: Resolution of screen.
Example:: 1280x720.

screen_size()[source]¶

Generates a random size of screen in inch.

Return type:: str
Returns:: Screen size.
Example:: 13″.

ssd_or_hdd()[source]¶

Generates a random type of disk.

Return type:: str
Returns:: HDD or SSD.
Example:: 512GB SSD.

Internet¶

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

Class for generating data related to the internet.

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

Initialize attributes.

Parameters:

args (Any) – Arguments.
kwargs (Any) – Keyword arguments.

asn()[source]¶

Generates a random 4-byte ASN.

ASNs reserved for private use are not considered.

Return type:: str
Returns:: ASN number as a string.
Example:: AS123456

content_type(mime_type=None)[source]¶

Generates a random HTTP content type.

Return type:: str
Returns:: Content type.
Example:: application/json

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

Generates a random DSN (Data Source Name).

Parameters:

dsn_type (Optional[DSNType]) – DSN type.
kwargs (Any) – Additional keyword-arguments for hostname method.

Return type:

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

Generates a random hostname without a scheme.

Parameters:

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

Return type:

Returns:

Hostname.

http_method()[source]¶

Generates 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]¶

Generates a random HTTP response headers.

The following headers are included:

Allow
Age
Server
Content-Type
X-Request-ID
Content-Language
Content-Location
Set-Cookie
Upgrade-Insecure-Requests
X-Content-Type-Options
X-XSS-Protection
Connection
X-Frame-Options
Content-Encoding
Cross-Origin-Opener-Policy
Cross-Origin-Resource-Policy
Strict-Transport-Security

Return type:: dict[str, Any]
Returns:: Response headers as dict.

http_status_code()[source]¶

Generates a random HTTP status code.

Return type:: int
Returns:: HTTP status.
Example:: 200

http_status_message()[source]¶

Generates a random HTTP status message.

Return type:: str
Returns:: HTTP status message.
Example:: 200 OK

ip_v4()[source]¶

Generates a random IPv4 address as string.

Example:: 19.121.223.58
Return type:: str

ip_v4_object()[source]¶

Generates a random ipaddress.IPv4Address object.

If you only need special purpose IPv4 addresses, use special_ip_v4_object().

Return type:: IPv4Address
Returns:: ipaddress.IPv4Address object.

ip_v4_with_port(port_range=PortRange.ALL)[source]¶

Generates a random IPv4 address as string.

Parameters:: port_range (PortRange) – PortRange enum object.
Return type:: str
Returns:: IPv4 address as string.
Example:: 19.121.223.58:8000

ip_v6()[source]¶

Generates a random IPv6 address as string.

Return type:: str
Returns:: IPv6 address string.
Example:: 2001:c244:cf9d:1fb1:c56d:f52c:8a04:94f3

ip_v6_object()[source]¶

Generates random ipaddress.IPv6Address object.

Return type:: IPv6Address
Returns:: ipaddress.IPv6Address object.

mac_address()[source]¶

Generates 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:

Returns:

Path.

port(port_range=PortRange.ALL)[source]¶

Generates a random port.

Parameters:: port_range (PortRange) – PortRange enum object.
Return type:: int
Returns:: Port number.
Raises:: NonEnumerableError – if port_range is not in PortRange.
Example:: 8080

public_dns()[source]¶

Generates a random public DNS.

Example:: 1.1.1.1
Return type:: str

query_parameters(length=None)[source]¶

Generates an arbitrary query parameters as a dict.

Parameters:: length (Optional[int]) – Length of query parameters dictionary (maximum is 32).
Return type:: dict[str, str]
Returns:: Dict of query parameters.

query_string(length=None)[source]¶

Generates an arbitrary query string of given length.

Parameters:: length (Optional[int]) – Length of query string.
Return type:: str
Returns:: Query string.

slug(parts_count=None)[source]¶

Generates a random slug of given parts count.

Parameters:: parts_count (Optional[int]) – Slug’s parts count.
Return type:: str
Returns:: Slug.

special_ip_v4(purpose=None)[source]¶

Generates a special purpose IPv4 address as string.

Parameters:: purpose (Optional[IPv4Purpose]) – Enum object enums.IPv4Purpose.
Return type:: str
Returns:: IPv4 address as string.

special_ip_v4_object(purpose=None)[source]¶

Generates a special purpose IPv4 address.

Parameters:: purpose (Optional[IPv4Purpose]) – Enum object enums.IPv4Purpose.
Return type:: IPv4Address
Returns:: IPv4 address.
Raises:: NonEnumerableError – if purpose not in enums.IPv4Purpose.

static stock_image_url(width=1920, height=1080, keywords=None)[source]¶

Generates a random stock image URL hosted on Unsplash.

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

Parameters:

width (int | str) – Width of the image.
height (int | str) – Height of the image.
keywords (Union[list[str], set[str], tuple[str, ...], None]) – Sequence of search keywords.

Return type:

Returns:

URL of the image.

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

Generates a random TLD.

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]¶

Generates a random URI.

Parameters:

scheme (Optional[URLScheme]) – Scheme.
tld_type (Optional[TLDType]) – TLDType.
subdomains (Optional[list[str]]) – List of subdomains (make sure they are valid).
query_params_count (Optional[int]) – Query params.

Return type:

Returns:

URI.

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

Generates a random URL.

Parameters:

scheme (Optional[URLScheme]) – The scheme.
port_range (Optional[PortRange]) – PortRange enum object.
tld_type (Optional[TLDType]) – TLDType.
subdomains (Optional[list[str]]) – List of subdomains (make sure they are valid).

Return type:

Returns:

URL.

user_agent()[source]¶

Get a random user agent.

Return type:: str
Returns:: User agent.
Example:: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:15.0) Gecko/20100101 Firefox/15.0.1

Numeric¶

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

A provider for generating numeric data.

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

Initialize attributes.

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

Parameters:

seed – Seed for random. When set to None the current system time is used.
random – Custom random. See https://github.com/lk-geimfari/mimesis/issues/1313 for details.

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

Generates a random complex number.

Parameters:

start_real (float) – Start real range.
end_real (float) – End real range.
start_imag (float) – Start imaginary range.
end_imag (float) – End imaginary range.
precision_real (int) – Round a real part of number to a given precision.
precision_imag (int) – Round the imaginary part of number to a given precision.

Return type:

complex

Returns:

Complex numbers.

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

Generates a list of random complex numbers.

Parameters:

start_real (float) – Start real range.
end_real (float) – End real range.
start_imag (float) – Start imaginary range.
end_imag (float) – End imaginary range.
precision_real (int) – Round a real part of number to a given precision.
precision_imag (int) – Round the imaginary part of number to a given precision.
n (int) – Length of the list.

Return type:

list[complex]

Returns:

A list of random complex numbers.

decimal_number(start=-1000.0, end=1000.0)[source]¶

Generates a random decimal number.

Parameters:

start (float) – Start range.
end (float) – End range.

Return type:

Decimal

Returns:

decimal.Decimal object.

decimals(start=0.0, end=1000.0, n=10)[source]¶

Generates a list of decimal numbers.

Parameters:

start (float) – Start range.
end (float) – End range.
n (int) – Length of the list.

Return type:

list[Decimal]

Returns:

A list of decimal.Decimal objects.

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

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

Parameters:

start (float) – Start range.
end (float) – End range.
precision (int) – Round a number to a given precision in decimal digits, default is 15.

Return type:

Returns:

Float.

floats(start=0, end=1, n=10, precision=15)[source]¶

Generates a list of random float numbers.

Parameters:

start (float) – Start range.
end (float) – End range.
n (int) – Length of the list.
precision (int) – Round a number to a given precision in decimal digits, default is 15.

Return type:

list[float]

Returns:

The list of floating-point numbers.

increment(accumulator=None)[source]¶

Generates an incrementing number.

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

If accumulator passed then increments number associated with it.

Example:

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

Parameters:: accumulator (Optional[str]) – Accumulator (used to create associative incrementation).
Return type:: int
Returns:: Integer.

integer_number(start=-1000, end=1000)[source]¶

Generates a random integer from start to end.

Parameters:

start (int) – Start range.
end (int) – End range.

Return type:

int

Returns:

Integer.

integers(start=0, end=10, n=10)[source]¶

Generates a list of random integers.

Parameters:

start (int) – Start.
end (int) – End.
n (int) – Length of the list.

Return type:

list[int]

Returns:

List of integers.

Example:

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

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

Generates m x n matrix with a random numbers.

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

Parameters:

m (int) – Number of rows.
n (int) – Number of columns.
num_type (NumType) – NumType enum object.
kwargs (Any) – Other method-specific arguments.

Return type:

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

Returns:

A matrix of random numbers.

Path¶

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

Class that provides methods and property for generate paths.

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

Initialize attributes.

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

Parameters:: platform (str) – Required platform type.

dev_dir()[source]¶

Generates a random path to development directory.

Return type:: str
Returns:: Path.
Example:: /home/sherrell/Development/Python

home()[source]¶

Generates a home path.

Return type:: str
Returns:: Home path.
Example:: /home

project_dir()[source]¶

Generates a random path to project directory.

Return type:: str
Returns:: Path to project.
Example:: /home/sherika/Development/Falcon/mercenary

root()[source]¶

Generates a root dir path.

Return type:: str
Returns:: Root dir.
Example:: /

user()[source]¶

Generates a random user.

Return type:: str
Returns:: Path to user.
Example:: /home/oretha

users_folder()[source]¶

Generates a random path to user’s folders.

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

Payment¶

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

Class that provides data related to payments.

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

Initialize attributes.

Parameters:

args (Any) – Arguments.
kwargs (Any) – Keyword arguments.

bitcoin_address()[source]¶

Generates a random bitcoin address.

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

Return type:: str
Returns:: Bitcoin address.
Example:: 3EktnHQD7RiAE6uzMj2ZifT9YgRrkSgzQX

cid()[source]¶

Generates a random CID.

Return type:: str
Returns:: CID code.
Example:: 7452

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

Generates a random expiration date for credit card.

Parameters:

minimum (int) – Date of issue.
maximum (int) – Maximum of expiration_date.

Return type:

Returns:

Expiration date of credit card.

Example:

03/19.

credit_card_network()[source]¶

Generates a random credit card network.

Return type:: str
Returns:: Credit card network
Example:: MasterCard

credit_card_number(card_type=None)[source]¶

Generates a random credit card number.

Parameters:: card_type (Optional[CardType]) – Issuing Network. Default is Visa.
Return type:: str
Returns:: Credit card number.
Raises:: NotImplementedError – if card_type not supported.
Example:: 4455 5299 1152 2450

credit_card_owner(gender=None)[source]¶

Generates a random credit card owner.

Parameters:: gender (Gender enum.) – Gender of the card owner.
Return type:: dict[str, str]
Returns:

cvv()[source]¶

Generates a random CVV.

Return type:: str
Returns:: CVV code.
Example:: 069

ethereum_address()[source]¶

Generates a random Ethereum address.

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

Return type:: str
Returns:: Ethereum address.
Example:: 0xe8ece9e6ff7dba52d4c07d37418036a89af9698d

paypal()[source]¶

Generates a random PayPal account.

Return type:: str
Returns:: Email of PapPal user.
Example:: wolf235@gmail.com

Transport¶

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

Class for generating data related to transports.

airplane()[source]¶

Generates a random airplane model name.

Return type:: str
Returns:: Airplane model.
Example:: Boeing 727.

car()[source]¶

Generates a random vehicle name.

Return type:: str
Returns:: A vehicle.
Example:: Tesla Model S.

manufacturer()[source]¶

Generates a random car manufacturer.

Return type:: str
Returns:: A car manufacturer
Example:: Tesla.

vehicle_registration_code(locale=None)[source]¶

Returns vehicle registration code.

Parameters:: locale (Optional[Locale]) – Registration code for locale (country).
Return type:: str
Returns:: Vehicle registration code.

Science¶

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

Class for generating pseudo-scientific data.

dna_sequence(length=10)[source]¶

Generates a random DNA sequence.

Parameters:: length (int) – Length of block.
Return type:: str
Returns:: DNA sequence.
Example:: GCTTTAGACC

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

Returns unit name from the International System of Units.

Parameters:

name (Optional[MeasureUnit]) – Enum object UnitName.
symbol (bool) – Return only symbol

Return type:

Returns:

Unit.

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

Generates a random prefix for the International System of Units.

Parameters:

sign (Optional[MetricPrefixSign]) – Sing of prefix (positive/negative).
symbol (bool) – Return the symbol of the prefix.

Return type:

Returns:

Metric prefix for SI measure units.

Raises:

NonEnumerableError – if sign is not supported.

Example:

mega

rna_sequence(length=10)[source]¶

Generates a random RNA sequence.

Parameters:: length (int) – Length of block.
Return type:: str
Returns:: RNA sequence.
Example:: AGUGACACAA

Schema-based Generators¶

BaseField¶

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

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

Base class for fields.

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

Attr:

aliases: A dictionary of aliases for standard fields.

Parameters:

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

get_random_instance()[source]¶

Get a random object from Generic.

Return type:: Random
Returns:: Random object.

handle(field_name=None)[source]¶

Decorator for registering a custom field handler.

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

New in version 12.0.0.

Parameters:: field_name (Optional[str]) – Name of the field. If not specified, the name of the function is used.
Return type:: Callable[[Callable[[Random, Any], Any]], Callable[[Random, Any], Any]]
Returns:: Decorator.

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

Performs the value of the field by its name.

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

Note

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

Allowed delimiters: ., :, / and space:

provider.name
provider:name
provider/name
provider name

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

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

Parameters:

name (Optional[str]) – Name of the method.
key (Optional[Callable[[Any], Any]]) – A key function (any callable object) which will be applied to result.
kwargs (Any) – Kwargs of method.

Return type:

Any

Returns:

The result of method.

Raises:

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

register_handler(field_name, field_handler)[source]¶

Register a new field handler.

Parameters:

field_name (str) – Name of the field.
field_handler (Callable[[Random, Any], Any]) – Callable object.

Return type:

register_handlers(fields)[source]¶

Register the new field handlers.

Parameters:: fields (Sequence[tuple[str, Callable[[Random, Any], Any]]]) – A sequence of sequences with field name and handler.
Return type:: None
Returns:: None.

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

Reseed the random generator.

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

unregister_all_handlers()[source]¶

Unregister all custom field handlers.

Return type:: None
Returns:: None.

unregister_handler(field_name)[source]¶

Unregister a field handler.

Parameters:: field_name (str) – Name of the field.
Return type:: None

unregister_handlers(field_names=())[source]¶

Unregister a field handlers with given names.

Parameters:: field_names (Sequence[str]) – Names of the fields.
Return type:: None
Returns:: None.

Field¶

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

Greedy field (evaluates immediately).

Warning

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

If you are doing this:

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

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

Forewarned is forearmed.

Here is an example of how to use it:

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

Fieldset¶

class mimesis.schema.Fieldset(*args, **kwargs)[source]¶

Greedy fieldset (evaluates immediately).

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

Here is an example:

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

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

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

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

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

Variables:

fieldset_default_iterations – Default iterations. Default is 10.
fieldset_iterations_kwarg – Keyword argument for iterations. Default is i.

Schema¶

class mimesis.schema.Schema(schema, iterations=10)[source]¶

Class which return list of filled schemas.

__init__(schema, iterations=10)[source]¶

Initialize schema.

Parameters:

iterations (int) – Number of iterations. This parameter is keyword-only. The default value is 10.
schema (Callable[[], dict[str, Any]]) – A schema (must be a callable object).

create()[source]¶

Creates a list of a fulfilled schemas.

Note

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

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

Return type:: list[dict[str, Any]]
Returns:: List of fulfilled schemas.

to_csv(file_path, **kwargs)[source]¶

Export a schema as a CSV file.

Parameters:

file_path (str) – The file path.
kwargs (Any) – The keyword arguments for csv.DictWriter class.

Return type:

to_json(file_path, **kwargs)[source]¶

Export a schema as a JSON file.

Parameters:

file_path (str) – File a path.
kwargs (Any) – Extra keyword arguments for json.dump() class.

Return type:

to_pickle(file_path, **kwargs)[source]¶

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

Parameters:

file_path (str) – The file path.
kwargs (Any) – Extra keyword arguments for pickle.dump() class.

Return type: