API¶

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

Random module¶

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

A custom random class.

It is a subclass of the random.Random class from the standard library’s random module. The class incorporates additional custom methods.

This class can be extended according to specific requirements.

choice_enum_item(enum)[source]¶

Get random value of enum object.

Parameters:: enum (Any) – Enum object.
Return type:: Any
Returns:: Random value of enum.

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

Generate custom code using ascii uppercase and random integers.

Parameters:

mask (str) – Mask of code.
char (str) – Placeholder for characters.
digit (str) – Placeholder for digits.

Return type:

str

Returns:

Custom code.

randbytes(n=16)[source]¶

Generate n random bytes.

Return type:: bytes

randints(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 n is less than or equal to zero.

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

Get a random number in the range [a, b) or [a, b] depending on rounding.

Parameters:

a (float) – Minimum value.
b (float) – Maximum value.
precision (int) – Round a number to a given precision in decimal digits, default is 15.

Return type:

float

weighted_choice(choices)[source]¶

Returns a random element according to the specified weights.

Parameters:: choices (dict[Any, float]) – A dictionary where keys are choices and values are weights.
Raises:: ValueError – If choices 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.apply_if(condition, transform, otherwise=None)[source]¶

Apply transform only if the condition is true.

Example:

>>> field("word", key=apply_if(lambda x: len(x) > 3, str.upper, str.lower))
'FIELDS'

Parameters:

condition (Callable[[Any], bool]) – Condition function.
transform (Callable[[Any], Any]) – Transform function to apply if condition is True.
otherwise (Optional[Callable[[Any], Any]]) – Optional transform to apply if condition is False.

Return type:

Callable[[Any], Any]

Returns:

A closure that conditionally transforms the result.

mimesis.keys.base64_encode(value)[source]¶

Encode as base64.

Parameters:: value (str) – Input string to encode.
Return type:: str
Returns:: Base64 encoded string.
Raises:: TypeError – If result is not a string.

Example:

>>> field("word", key=base64_encode)
'cHJlcGFyZWQ='

mimesis.keys.camel_case(value)[source]¶

Convert to camelCase.

Example:

>>> field("sentence", key=camel_case)
'makeMeASandwich.'

Parameters:: value (str) – Input string to convert.
Return type:: str
Returns:: camelCase string.
Raises:: TypeError – If result is not a string.

mimesis.keys.hash_with(algorithm='sha256')[source]¶

Return a function that hashes a string using the given algorithm.

Supported algorithms are those available in hashlib.algorithms_available.

Example:

>>> field("password", key=hash_with("sha1"))
'd3e7130d657733468b10c1fd207c4d62b7180cda'

Parameters:

algorithm (str) – Hash algorithm name.

Return type:

Callable[[str], str]

Returns:

A closure that hashes a string.

Raises:

ValueError – If algorithm is not supported.
TypeError – If result is not a string.

mimesis.keys.join(sep=', ')[source]¶

Join list items with separator.

Example:

>>> field("words", quantity=3, key=join(" | "))
'pci | promise | excel'

Parameters:: sep (str) – Separator string.
Return type:: Callable[[list[Any]], str]
Returns:: A closure that joins items.
Raises:: TypeError – If the result is not iterable.

mimesis.keys.kebab_case(value)[source]¶

Convert to kebab-case.

Parameters:: value (str) – Input string to convert.
Return type:: str
Returns:: kebab-case string.
Raises:: TypeError – If result is not a string.

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 the 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.pipe(*functions)[source]¶

Pipe multiple key functions together.

Example:

>>> field("full_name", key=pipe(str.lower, slugify, prefix("user-")))
'user-john-doe'

Parameters:: functions (Callable[[Any], Any] | Callable[[Any, Optional[Random]], Any]) – Key functions to pipe together.
Return type:: Callable[[Any], Any] | Callable[[Any, Optional[Random]], Any]
Returns:: A closure that applies all functions in sequence.

mimesis.keys.prefix(text)[source]¶

Add a prefix to the result.

Example:

>>> field("word", key=prefix("user_"))
'user_order'

Parameters:: text (str) – Prefix text to add.
Return type:: Callable[[str], str]
Returns:: A closure that adds a prefix.
Raises:: TypeError – If result is not a string.

mimesis.keys.redact(replacement='[REDACTED]')[source]¶

Replace the entire value with redaction marker.

Example:

>>> field("password", key=redact("[CLASSIFIED]"))
'[CLASSIFIED]'

Parameters:: replacement (str) – Replacement text.
Return type:: Callable[[Any], str]
Returns:: A closure that returns the replacement text.

mimesis.keys.remove_whitespace(value)[source]¶

Remove all whitespace.

Parameters:: value (str) – Input string.
Return type:: str
Returns:: String with all whitespace removed.
Raises:: TypeError – If result is not a string.

mimesis.keys.reverse(value)[source]¶

Reverse the string.

Parameters:: value (str) – Input string to reverse.
Return type:: str
Returns:: Reversed string.
Raises:: TypeError – If result is not a string.

Example:

>>> field("word", key=reverse)
'ebircsed'

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.

mimesis.keys.slugify(value)[source]¶

Convert to URL-friendly slug.

Example:

>>> field("sentence", key=slugify)
'where-are-my-pants'

Parameters:: value (str) – Input string to slugify.
Return type:: str
Returns:: URL-friendly slug.
Raises:: TypeError – If result is not a string.

mimesis.keys.snake_case(value)[source]¶

Convert to snake_case.

Example:

>>> field("full_name", key=snake_case)
'michael_caldwell'

Parameters:: value (str) – Input string to convert.
Return type:: str
Returns:: snake_case string.
Raises:: TypeError – If result is not a string.

mimesis.keys.suffix(text)[source]¶

Add a suffix to the result.

Example:

>>> field("word", key=suffix(".io"))
'ecipe.io'

Parameters:: text (str) – Suffix text to add.
Return type:: Callable[[str], str]
Returns:: A closure that adds a suffix.
Raises:: TypeError – If result is not a string.

mimesis.keys.truncate(max_length, suffix='...')[source]¶

Truncate to maximum length.

Example:

>>> field("sentence", key=truncate(20))
'Ports are created...'

Parameters:

max_length (int) – Maximum length of the result.
suffix (str) – Suffix to add when truncating.

Return type:

Callable[[str], str]

Returns:

A closure that truncates a string.

Raises:

TypeError – If result is not a string.
ValueError – If max_length is not positive.

mimesis.keys.urlsafe_base64_encode(value)[source]¶

Encode as URL-safe base64.

Parameters:: value (str) – Input string to encode.
Return type:: str
Returns:: URL-safe base64 encoded string.
Raises:: TypeError – If result is not a string.

Example:

>>> field("word", key=urlsafe_base64_encode)
'YXBwZWFscw=='

mimesis.keys.wrap(before='<', after='>')[source]¶

Wrap the result with before and after strings.

Example:

>>> field("word", key=wrap("[", "]"))
'[dynamics]'

Parameters:

before (str) – String to prepend.
after (str) – String to append.

Return type:

Callable[[str], str]

Returns:

A closure that wraps a string.

Raises:

TypeError – If the result is not a string.

Shortcuts¶

This module provides internal utility 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 used by Mimesis.

exception mimesis.exceptions.AliasesTypeError[source]¶: Raised when aliases is not a flat dictionary.

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

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

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

exception mimesis.exceptions.FieldsetError[source]¶: Raised when the fieldset iteration count is invalid.

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 a member of the expected Enum.

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

Base Providers¶

BaseProvider¶

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

This is a base class for all providers.

Variables:

random – An instance of mimesis.random.Random.
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 the enum does not have 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 for 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 a default locale for all providers.

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 contains all providers in one place.

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:

None

Returns:

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.

Localized Providers¶

Address¶

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

Class for generating 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 a 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 country code.

Default format is A2 (ISO 3166-1-alpha2). You can change it by passing the code parameter.

Parameters:: code (Optional[CountryCode]) – Country code format.
Return type:: str
Returns:: Country code in the selected format.
Raises:: NonEnumerableError – If code is not a valid CountryCode.

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 the 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 latitude.

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 the 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

secondary_address()[source]¶

Generates a random secondary address.

Secondary addresses are used for apartments, suites, units, etc.

Return type:: str
Returns:: Secondary address.
Example:: Apt. 42 Suite 1200 Unit B

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:: Type 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 the 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 the current locale.

Return type:: str
Returns:: Currency symbol.

price(minimum=500, maximum=1500, precision=2, as_decimal=False)[source]¶

Generate a random price.

Parameters:

minimum (float) – Minimum value of price.
maximum (float) – Maximum value of price.
precision (int) – Number of decimal places (default 2).
as_decimal (bool) – If True, returns Decimal for high-precision.

Return type:

float | Decimal

Returns:

Price as float or Decimal.

price_in_btc(minimum=0, maximum=2, precision=8, as_decimal=False)[source]¶

Generates a random price in BTC.

Parameters:

minimum (float) – Minimum value of price.
maximum (float) – Maximum value of price.
precision (int) – Number of decimal places (default 8 for satoshi).
as_decimal (bool) – If True, returns Decimal for high-precision.

Return type:

float | Decimal

Returns:

Price in BTC as float or Decimal.

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) – Start 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 are not passed, when date_start is 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=2026)[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=2026, end=2026, 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 a random date as a string.

Parameters:

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

Return type:

str

Returns:

Formatted date.

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

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:

str

Returns:

Formatted datetime string.

formatted_time(fmt='')[source]¶

Generates formatted time as a 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.

future_date(days=30)[source]¶

Generates a random date in the future.

Parameters:: days (int) – Maximum number of days in the future.
Return type:: date
Returns:: A date object between tomorrow and days from now.

future_datetime(days=30, seconds=None, timezone=None)[source]¶

Generates a random datetime in the future.

Parameters:

days (int) – Maximum number of days in the future (ignored if seconds is set).
seconds (Optional[int]) – Maximum number of seconds in the future (overrides days).
timezone (Optional[str]) – Set custom timezone (pytz required).

Return type:

datetime

Returns:

A datetime object between now and the specified time in the future.

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.

past_date(days=30)[source]¶

Generates a random date in the past.

Parameters:: days (int) – Maximum number of days in the past.
Return type:: date
Returns:: A date object between days ago and yesterday.

past_datetime(days=30, seconds=None, timezone=None)[source]¶

Generates a random datetime in the past.

Parameters:

days (int) – Maximum number of days in the past (ignored if seconds is set).
seconds (Optional[int]) – Maximum number of seconds in the past (overrides days).
timezone (Optional[str]) – Set custom timezone (pytz required).

Return type:

datetime

Returns:

A datetime object between the specified time ago and now.

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 the 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=2026)[source]¶

Generates week number with year.

Parameters:

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

Return type:

str

Returns:

Week number.

year(minimum=1990, maximum=2026)[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 spice or 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) – Minimum birth year.
max_year (int) – Maximum 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:

str

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:

str

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.

ISO/IEC 5218 defines a language-neutral single-digit code for the representation of human sexes (0 — not known, 1 — male, 2 — female, 9 — not applicable).

Return type:: int
Returns:: Gender code.

gender_symbol()[source]¶

Generate a random gender 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:

str

Returns:

Height.

Example:

1.85.

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

Generates a random identifier using a 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 a job.
Example:: Programmer.

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

Generates a password or a hash of a password.

Parameters:

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

Return type:

str

Returns:

Password or hash of a password.

Example:

k6dv2odff9#4h

patronymic(gender=None)[source]¶

Generates a random patronymic name.

Patronymics are available only for Locale.RU and Locale.UK.

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

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

Generates a random phone number.

Parameters:

mask (str) – Mask for formatting number.
placeholder (str) – A placeholder for a mask (default is #).
e164 (bool) – If True, returns phone number in E.164 format (e.g., +14155552671).

Return type:

str

Returns:

Phone number.

Example:

Default: +7-(963)-409-11-22 E.164: +79634091122

political_views()[source]¶

Get 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 a 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:

str

Returns:

The title.

Raises:

NonEnumerableError – if gender or title_type has an 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 using a 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 mask is not supported.

Return type:

str

Returns:

Username as string.

Example:

>>> username(mask="C_C_d")
Cotte_Article_1923
>>> username(mask="U.l.d")
ELKINS.wolverine.2013
>>> username(mask="l_l_d", drange=(1900, 2021))
plasmic_blockader_1907

views_on()[source]¶

Get a random «views on» value.

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 the 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=EmojiCategory.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[EmojiCategory]) – EmojiCategory.
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]

Universal 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 the 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 the 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 the 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 the 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 a video file of the 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 that 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 an ISBN for the 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:

str

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

Choose a random item from a sequence.

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

Parameters:

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

Return type:

Any

Returns:

Sequence or single element randomly chosen from items.

Cryptographic¶

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

Class that provides pseudo-cryptographic data.

api_key(prefix='', length=32, fmt='hex')[source]¶

Generate API key.

Parameters:

prefix (str) – Optional prefix (e.g., sk_, pk_, api_).
length (int) – Length of the random part (default: 32).
fmt (str) – Format of the key - ‘hex’ or ‘base64’ (default: ‘hex’).

Return type:

str

Returns:

API key string.

Raises:

ValueError – If format is not ‘hex’ or ‘base64’.

Example:

>>> from mimesis import Cryptographic
>>> crypto = Cryptographic()
>>> crypto.api_key()
'a3d2f5e8b9c1d4e7f0a2b5c8d1e4f7a0'
>>> crypto.api_key(prefix="sk_")
'sk_a3d2f5e8b9c1d4e7f0a2b5c8d1e4f7a0'
>>> crypto.api_key(prefix="pk_", fmt="base64")
'pk_dGVzdGluZ3Rlc3Rpbmc'

certificate_fingerprint(algorithm='sha256')[source]¶

Generate certificate fingerprint.

Parameters:: algorithm (str) – Hash algorithm - ‘sha256’ or ‘sha1’.
Return type:: str
Returns:: Certificate fingerprint in colon-separated hex format.
Raises:: ValueError – If algorithm is not supported.

Example:

>>> from mimesis import Cryptographic
>>> crypto = Cryptographic()
>>> crypto.certificate_fingerprint()
'A3:D2:F5:E8:B9:C1:D4:E7:F0:A2:B5:C8:D1:E4:F7:A0'
>>> crypto.certificate_fingerprint(algorithm="sha1")
'A3:D2:F5:E8:B9:C1:D4:E7:F0:A2:B5:C8:D1:E4:F7:A0:B1:C2:D3:E4'

hash(algorithm=None)[source]¶

Generates 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 – When algorithm is unsupported.

jwt(payload=None, algorithm='HS256')[source]¶

Generate JWT-like token structure for testing.

Parameters:

payload (Optional[dict[str, Any]]) – JWT payload (claims). If None, generates a default payload.
algorithm (str) – JWT algorithm (default: HS256).

Return type:

str

Returns:

JWT-like token string.

Example:

>>> from mimesis import Cryptographic
>>> crypto = Cryptographic()
>>> crypto.jwt()
'eyJhbGc...'
>>> crypto.jwt(payload={"user_id": 123, "role": "admin"})
'eyJhbGc...'

mnemonic_phrase()[source]¶

Generates a BIP-39-like mnemonic phrase.

Return type:: str
Returns:: Mnemonic phrase.

token_bytes(entropy=32)[source]¶

Generates a byte string containing entropy random bytes.

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

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.

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

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.

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.

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 or 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 distribution 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 generating 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 a string.

Parameters:

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

Return type:

str

Returns:

Size of file.

Example:

56 kB

Hardware¶

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

Class for generating 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 inches.

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

cloud_region(separator='-')[source]¶

Generates a random cloud provider region identifier.

This generates region identifiers commonly used by cloud providers like AWS, Azure, GCP, etc.

Parameters:: separator (str) – Separator between parts (default is “-“).
Return type:: str
Returns:: Cloud region identifier.
Example:: eu-west-1 us-east-2 ap-southeast-3

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

Return type:

str

Returns:

DSN as a string.

Raises:

NonEnumerableError – If dsn_type is not a valid DSNType.

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:

str

Returns:

Hostname.

http_method()[source]¶

Generates a random HTTP method.

Return type:: str
Returns:: HTTP method.
Example:: POST

http_request_headers()[source]¶

Generates 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 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 a string.

Example:: 19.121.223.58
Return type:: str

ip_v4_cidr()[source]¶

Generates a random valid IPv4 CIDR notation.

The generated CIDR represents a valid network address where host bits are properly zeroed according to the prefix length.

Return type:: str
Returns:: IPv4 CIDR notation.
Example:: 192.168.1.0/24

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 a 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 a string.

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

ip_v6_cidr()[source]¶

Generates a random valid IPv6 CIDR notation.

The generated CIDR represents a valid network address where host bits are properly zeroed according to the prefix length.

Return type:: str
Returns:: IPv6 CIDR notation.
Example:: 2001:db8::/32

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:

str

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 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 with a given number of parts.

Parameters:: parts_count (Optional[int]) – Number of parts in the slug.
Return type:: str
Returns:: Slug.

special_ip_v4(purpose=None)[source]¶

Generates a special purpose IPv4 address as a 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:

str

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

str

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:

str

Returns:

URL.

user_agent()[source]¶

Get a random user agent.

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

Numeric¶

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

A provider for generating numeric data.

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

Initialize attributes.

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

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:

float

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 for keyed increments).
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 an m x n matrix with 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 properties for generating 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 a user’s folder.

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) – Minimum two-digit year.
maximum (int) – Maximum two-digit year.

Return type:

str

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 a valid address.

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

paypal()[source]¶

Generates a random PayPal account.

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

Transport¶

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

Class for generating data related to transport.

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 a 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 a unit name from the International System of Units.

Parameters:

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

Return type:

str

Returns:

Unit.

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

Generates a random prefix for the International System of Units.

Parameters:

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

Return type:

str

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

Base class for field and fieldset generators.

Variables:: aliases – A dictionary of aliases for standard fields.

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

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

Returns 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 the result.
kwargs (Any) – Keyword arguments of the method.

Return type:

Any

Returns:

The result of the method.

Raises:

FieldError – If the field is missing or invalid.
AliasesTypeError – If aliases is not a flat dictionary.

register_handler(field_name, field_handler)[source]¶

Parameters:

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

Return type:

None

register_handlers(fields)[source]¶

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 field handlers with the 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 instantiate 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, seed=<mimesis.types._MissingSeed object>)[source]¶

Class which returns a list of filled schemas.

__init__(schema, iterations=10, seed=<mimesis.types._MissingSeed object>)[source]¶

Initialize schema.

Parameters:

schema (Callable[[], dict[str, Any]]) – A schema (must be a callable object).
iterations (int) – Number of iterations.
seed (UnionType[None, int, float, str, bytes, bytearray, _MissingSeed]) – Seed for random generator.

create()[source]¶

Creates a list of filled schemas.

Note

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

If you need a lazy version of this method, just use iterator() or the iterator protocol of Schema

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

iterator()[source]¶

Return an iterator for the schema.

Return type:: Schema
Returns:: Iterator object.

map(fn)[source]¶

Transform each generated item.

Parameters:: fn (Callable[..., Any]) – Function to transform items. Can accept (item) or (item, context).
Return type:: Schema
Returns:: Self for chaining.

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

Export a schema as a CSV file.

Parameters:

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

Return type:

None

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

Export a schema as a JSON file.

Parameters:

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

Return type:

None

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

Return type:

None

with_context(**kwargs)[source]¶

Add custom context data.

Parameters:: kwargs (Any) – Custom context values.
Return type:: Schema
Returns:: Self for chaining.

SchemaContext¶

class mimesis.schema.SchemaContext(index, seed=<mimesis.types._MissingSeed object>, custom=None)[source]¶

Context object passed to transformation functions.

Variables:

index – Current iteration index (0-based).
iteration – Current iteration number (1-based).
seed – Current seed state.
custom – Custom context data.

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

Initialize context.

Parameters:

index (int) – Current iteration index (0-based).
seed (UnionType[None, int, float, str, bytes, bytearray, _MissingSeed]) – Current seed state.
custom (Optional[dict[str, Any]]) – Custom context data.

SchemaBuilder¶

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

Unified builder for generating related fake data.

Example:

from mimesis import SchemaBuilder
from mimesis.locales import Locale

sb = SchemaBuilder(Locale.EN, seed=0xFF)

users = sb.schema(
    "users",
    {
        "id": sb.f("increment"),
        "username": sb.f("username"),
        "email": sb.f("email"),
    },
)

posts = sb.schema(
    "posts",
    {
        "id": sb.f("increment"),
        "title": sb.f("sentence"),
        "user_id": sb.ref(users).id,
    },
)

data = sb.create(users=10, posts=50)

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

Initialize the SchemaBuilder.

Parameters:

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

choice(items)[source]¶

Create a lazy random choice from items.

Parameters:: items (Sequence[Any]) – Sequence of items to choose from.
Return type:: LazyChoice
Returns:: A lazy choice that resolves during data generation.
Raises:: ValueError – If items is empty.

Example:

sb.choice(["active", "inactive", "pending"])

clear()[source]¶

Clear all generated data (keeps schema definitions).

Return type:: None

create(**counts)[source]¶

Generate all schemas with specified counts.

Schemas are automatically sorted by dependencies, so you can pass them in any order.

Parameters:: counts (int) – Schema names are mapped to their counts.
Return type:: dict[str, list[dict[str, Any]]]
Returns:: Dictionary of schema names to generated data lists.
Raises:: ValueError – If a schema name is not defined or a count is negative.

Example:

data = sb.create(
    users=10,
    posts=50,
    comments=200,
)

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

Create a lazy field that evaluates during generation.

Parameters:

name (str) – Field name (e.g., “username”, “person.email”).
key (Optional[Callable[[Any], Any]]) – Optional key function to transform the result.
kwargs (Any) – Additional arguments for the field method.

Return type:

LazyField

Returns:

A lazy field that resolves during data generation.

Example:

sb.f("username")
sb.f("person.email", domains=["example.com"])
sb.f("full_name", key=str.upper)

ref(schema)[source]¶

Create a reference to another schema for foreign keys.

Parameters:: schema (SchemaRef) – The SchemaRef returned by sb.schema().
Return type:: SchemaRefProxy
Returns:: A proxy that allows field access for FK references.
Raises:: TypeError – If schema is not a SchemaRef.

Example:

users = sb.schema("users", {"id": sb.f("increment")})

posts = sb.schema(
    "posts",
    {
        "user_id": sb.ref(users).id,  # FK to users.id
        "author": sb.ref(users),  # Whole user record
    },
)

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

Reseed all random generators.

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

reset()[source]¶

Reset builder completely (clears schemas and generated data).

Return type:: None

schema(name, schema)[source]¶

Define a schema and return a reference.

Parameters:

name (str) – Unique name for this schema.
schema (dict[str, Any]) – Dictionary defining the schema fields.

Return type:

SchemaRef

Returns:

A SchemaRef for FK references and nesting.

Example:

users = sb.schema(
    "users",
    {
        "id": sb.f("increment"),
        "username": sb.f("username"),
        "profile": {
            "bio": sb.f("text"),
        },
    },
)

weighted_choice(items, weights)[source]¶

Create a lazy weighted random choice.

Parameters:

items (Sequence[Any]) – Sequence of items to choose from.
weights (Sequence[float]) – Weights for each item (must match items length).

Return type:

LazyWeightedChoice

Returns:

A lazy weighted choice that resolves during data generation.

Raises:

ValueError – If items is empty or lengths do not match.

Example:

sb.weighted_choice(["common", "rare", "legendary"], [0.7, 0.25, 0.05])

SchemaRef¶

class mimesis.builder.SchemaRef(name, definition)[source]¶

Reference to a defined schema.

Returned by sb.schema(). Used for:

Foreign keys via sb.ref(schema_ref).field
Nesting via schema_ref(count=N)

Example:

users = sb.schema("users", {"id": sb.f("increment")})

posts = sb.schema(
    "posts",
    {
        "user_id": sb.ref(users).id,  # Foreign key
    },
)

companies = sb.schema(
    "companies",
    {
        "name": sb.f("company"),
        "employees": users(count=5),  # Nested users
    },
)

__call__(*, count=1)[source]¶

Create a nested embedding of this schema.

Parameters:: count (int) – Number of items to generate and embed.
Return type:: NestedSchema
Returns:: A NestedSchema that resolves to a list of items.
Raises:: ValueError – If count is less than 1.

__init__(name, definition)[source]¶

Initialize schema reference.

Parameters:

name (str) – The schema name.
definition (dict[str, Any]) – The schema definition dict.

property name: str¶: Return the schema name.

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 is no guarantee that you will get the result which you actually expected.

Below, you can see an example of using enums in methods of data providers.

class mimesis.enums.Algorithm(value)[source]¶

Provides algorithms that are available.

An argument for hash().

BLAKE2B = 'blake2b'¶

BLAKE2S = 'blake2s'¶

MD5 = 'md5'¶

SHA1 = 'sha1'¶

SHA224 = 'sha224'¶

SHA256 = 'sha256'¶

SHA384 = 'sha384'¶

SHA3_224 = 'sha3_224'¶

SHA3_256 = 'sha3_256'¶

SHA3_384 = 'sha3_384'¶

SHA3_512 = 'sha3_512'¶

SHA512 = 'sha512'¶

SHAKE128 = 'shake_128'¶

SHAKE256 = 'shake_256'¶

class mimesis.enums.AudioFile(value)[source]¶

Provides the audio file types.

An argument for audio()

AAC = 'aac'¶

MP3 = 'mp3'¶

class mimesis.enums.CardType(value)[source]¶

Provides credit card types.

An argument for credit_card_number().

AMERICAN_EXPRESS = 'American Express'¶

MASTER_CARD = 'MasterCard'¶

VISA = 'Visa'¶

class mimesis.enums.CompressedFile(value)[source]¶

Provides the compressed file types.

An argument for compressed()

GZIP = 'gz'¶

ZIP = 'zip'¶

class mimesis.enums.CountryCode(value)[source]¶

Provides types of country codes.

An argument for country_code().

A2 = 'a2'¶

A3 = 'a3'¶

FIFA = 'fifa'¶

IOC = 'ioc'¶

NUMERIC = 'numeric'¶

class mimesis.enums.DSNType(value)[source]¶

Provides DSN types for database connections.

An argument for dsn().

COUCHBASE = ('couchbase', 8092)¶

MEMCACHED = ('memcached', 11211)¶

MONGODB = ('mongodb', 27017)¶

MYSQL = ('mysql', 3306)¶

POSTGRES = ('postgres', 5432)¶

RABBITMQ = ('rabbitmq', 5672)¶

REDIS = ('redis', 6379)¶

class mimesis.enums.DocumentFile(value)[source]¶

Provides the document file types.

An argument for document()

DOCX = 'docx'¶

PDF = 'pdf'¶

PPTX = 'pptx'¶

XLSX = 'xlsx'¶

class mimesis.enums.DurationUnit(value)[source]¶

Provides duration units.

An argument for duration().

DAYS = 'days'¶

HOURS = 'hours'¶

MICROSECONDS = 'microseconds'¶

MILLISECONDS = 'milliseconds'¶

MINUTES = 'minutes'¶

SECONDS = 'seconds'¶

WEEKS = 'weeks'¶

class mimesis.enums.EANFormat(value)[source]¶

Provides formats of EAN.

An argument for ean().

EAN13 = 'ean-13'¶

EAN8 = 'ean-8'¶

class mimesis.enums.EmojiCategory(value)[source]¶

Provides emoji categories.

An argument for emoji().

ACTIVITIES = 'activities'¶

ANIMALS_AND_NATURE = 'animals_and_nature'¶

DEFAULT = 'smileys_and_emotion'¶

FLAGS = 'flags'¶

FOOD_AND_DRINK = 'food_and_drink'¶

OBJECTS = 'objects'¶

PEOPLE_AND_BODY = 'people_and_body'¶

SMILEYS_AND_EMOTION = 'smileys_and_emotion'¶

SYMBOLS = 'symbols'¶

TRAVEL_AND_PLACES = 'travel_and_places'¶

mimesis.enums.EmojyCategory¶: alias of EmojiCategory

class mimesis.enums.FileType(value)[source]¶

Provides file types.

An argument for extension() and file_name().

AUDIO = 'audio'¶

COMPRESSED = 'compressed'¶

DATA = 'data'¶

EXECUTABLE = 'executable'¶

IMAGE = 'image'¶

SOURCE = 'source'¶

TEXT = 'text'¶

VIDEO = 'video'¶

class mimesis.enums.Gender(value)[source]¶

Represents genders.

An argument for a lot of methods which take the parameter gender.

FEMALE = 'female'¶

MALE = 'male'¶

class mimesis.enums.IPv4Purpose(value)[source]¶

Provides IPv4 address ranges for different purposes.

An argument for special_ip_v4_object().

We use integer representation of IP addresses instead of IPv4Network objects for better performance.

AMT = (3224682752, 3224683007)¶

AS112_V4 = (3223307264, 3223307519)¶

BENCHMARKING = (3323068416, 3323199487)¶

DIRECT_DELEGATION_AS112_SERVICE = (3232706560, 3232706815)¶

IETF_PROTOCOL_ASSIGNMENTS = (3221225472, 3221225727)¶

IPV4_DUMMY_ADDRESS = (3221225480, 3221225480)¶

IPV4_SERVICE_CONTINUITY_PREFIX = (3221225472, 3221225479)¶

LIMITED_BROADCAST = (4294967295, 4294967295)¶

LINK_LOCAL = (2851995648, 2852061183)¶

LOOBACK = (2130706432, 2147483647)¶

PORT_CONTROL_PROTOCOL_ANYCAST = (3221225481, 3221225481)¶

PRIVATE_USE_1 = (167772160, 184549375)¶

PRIVATE_USE_2 = (2886729728, 2887778303)¶

PRIVATE_USE_3 = (3232235520, 3232301055)¶

RESERVED = (4026531840, 4294967295)¶

SHARE_ADDRESS_SPACE = (1681915904, 1686110207)¶

TEST_NET_1 = (3221225984, 3221226239)¶

TEST_NET_2 = (3325256704, 3325256959)¶

TEST_NET_3 = (3405803776, 3405804031)¶

THIS_NETWORK = (0, 16777215)¶

TURN_RELAY_ANYCAST = (3221225482, 3221225482)¶

class mimesis.enums.ISBNFormat(value)[source]¶

Provides formats of ISBN.

An argument for isbn().

ISBN10 = 'isbn-10'¶

ISBN13 = 'isbn-13'¶

class mimesis.enums.ImageFile(value)[source]¶

Provides the image file types.

An argument for image()

GIF = 'gif'¶

JPG = 'jpg'¶

PNG = 'png'¶

class mimesis.enums.Locale(value)[source]¶

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

An argument for all locale-dependent providers.

AR_AE = 'ar-ae'¶

AR_DZ = 'ar-dz'¶

AR_EG = 'ar-eg'¶

AR_JO = 'ar-jo'¶

AR_KW = 'ar-kw'¶

AR_MA = 'ar-ma'¶

AR_OM = 'ar-om'¶

AR_QA = 'ar-qa'¶

AR_SA = 'ar-sa'¶

AR_SY = 'ar-sy'¶

AR_TN = 'ar-tn'¶

AR_YE = 'ar-ye'¶

AZ = 'az'¶

CS = 'cs'¶

DA = 'da'¶

DE = 'de'¶

DEFAULT = 'en'¶

DE_AT = 'de-at'¶

DE_CH = 'de-ch'¶

EL = 'el'¶

EN = 'en'¶

EN_AU = 'en-au'¶

EN_CA = 'en-ca'¶

EN_GB = 'en-gb'¶

ES = 'es'¶

ES_MX = 'es-mx'¶

ET = 'et'¶

FA = 'fa'¶

FI = 'fi'¶

FR = 'fr'¶

HR = 'hr'¶

HU = 'hu'¶

IS = 'is'¶

IT = 'it'¶

JA = 'ja'¶

KK = 'kk'¶

KO = 'ko'¶

NL = 'nl'¶

NL_BE = 'nl-be'¶

NO = 'no'¶

PL = 'pl'¶

PT = 'pt'¶

PT_BR = 'pt-br'¶

RU = 'ru'¶

SK = 'sk'¶

SV = 'sv'¶

TR = 'tr'¶

UK = 'uk'¶

ZH = 'zh'¶

classmethod values()[source]¶

Return a list of all locale values.

Return type:: list[str]

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

Provides unit names.

An argument for measure_unit().

AMOUNT_OF_SUBSTANCE = ('mole', 'mol')¶

ANGLE = ('radian', 'r')¶

ELECTRICAL_CONDUCTANCE = ('siemens', 'S')¶

ELECTRIC_CAPACITANCE = ('farad', 'F')¶

ELECTRIC_CHARGE = ('coulomb', 'C')¶

ELECTRIC_RESISTANCE = ('ohm', 'Ω')¶

ENERGY = ('joule', 'J')¶

FLUX = ('watt', 'W')¶

FORCE = ('newton', 'N')¶

FREQUENCY = ('hertz', 'Hz')¶

INDUCTANCE = ('henry', 'H')¶

INFORMATION = ('byte', 'b')¶

MAGNETIC_FLUX = ('weber', 'Wb')¶

MAGNETIC_FLUX_DENSITY = ('tesla', 'T')¶

MASS = ('gram', 'gr')¶

POWER = ('watt', 'W')¶

PRESSURE = ('pascal', 'P')¶

RADIOACTIVITY = ('becquerel', 'Bq')¶

SOLID_ANGLE = ('steradian', '㏛')¶

TEMPERATURE = ('Celsius', '°C')¶

THERMODYNAMIC_TEMPERATURE = ('kelvin', 'K')¶

VOLTAGE = ('volt', 'V')¶

class mimesis.enums.MetricPrefixSign(value)[source]¶

Provides prefix signs.

An argument for metric_prefix()`().

NEGATIVE = 'negative'¶

POSITIVE = 'positive'¶

class mimesis.enums.MimeType(value)[source]¶

Provides common mime types.

An argument for mime_type().

APPLICATION = 'application'¶

AUDIO = 'audio'¶

IMAGE = 'image'¶

MESSAGE = 'message'¶

TEXT = 'text'¶

VIDEO = 'video'¶

class mimesis.enums.NumType(value)[source]¶

Provides the number types.

An argument for matrix().

COMPLEX = 'complexes'¶

DECIMAL = 'decimals'¶

FLOAT = 'floats'¶

INTEGER = 'integers'¶

class mimesis.enums.PortRange(value)[source]¶

Represents port ranges.

An argument for port().

ALL = (1, 65535)¶

EPHEMERAL = (49152, 65535)¶

REGISTERED = (1024, 49151)¶

WELL_KNOWN = (1, 1023)¶

class mimesis.enums.TLDType(value)[source]¶

Provides top level domain types.

An argument for a few methods which take the parameter tld_type.

CCTLD = 'cctld'¶

GEOTLD = 'geotld'¶

GTLD = 'gtld'¶

STLD = 'stld'¶

UTLD = 'utld'¶

class mimesis.enums.TimestampFormat(value)[source]¶

Provides timestamp output formats.

An argument for timestamp().

ISO_8601 = 2¶

POSIX = 1¶

RFC_3339 = 3¶

class mimesis.enums.TimezoneRegion(value)[source]¶

Provides regions of timezones.

An argument for timezone().

AFRICA = 'Africa'¶

AMERICA = 'America'¶

ANTARCTICA = 'Antarctica'¶

ARCTIC = 'Arctic'¶

ASIA = 'Asia'¶

ATLANTIC = 'Atlantic'¶

AUSTRALIA = 'Australia'¶

EUROPE = 'Europe'¶

INDIAN = 'Indian'¶

PACIFIC = 'Pacific'¶

class mimesis.enums.TitleType(value)[source]¶

Represents title types.

An argument for title().

ACADEMIC = 'academic'¶

TYPICAL = 'typical'¶

class mimesis.enums.URLScheme(value)[source]¶

Provides URL schemes.

An argument for some methods of Internet().

FTP = 'ftp'¶

HTTP = 'http'¶

HTTPS = 'https'¶

SFTP = 'sftp'¶

WS = 'ws'¶

WSS = 'wss'¶

class mimesis.enums.VideoFile(value)[source]¶

Provides the video file types.

An argument for video()

MOV = 'mov'¶

MP4 = 'mp4'¶