API Reference

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

Builtin Data Providers

BrazilSpecProvider

class mimesis.builtins.BrazilSpecProvider(*args, **kwargs)

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

class Meta

The name of the provider.

static cnpj(with_mask=True)

Get a random CNPJ.

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

Get a random CPF.

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

GermanySpecProvider

class mimesis.builtins.GermanySpecProvider(*args, **kwargs)

Specific-provider of misc data for Germany.

class Meta

The name of the provider.

__init__(*args, **kwargs)

Initialize attributes.

noun(plural=False)

Return a random noun in German.

Parameters:plural (bool) – Return noun in plural.
Return type:str
Returns:Noun.

JapanSpecProvider

class mimesis.builtins.JapanSpecProvider(*args, **kwargs)

Class that provides special data for ja.

class Meta

The name of the provider.

static full_to_half(text, alnum=True)

Convert all full width katakana to equivalent half width character.

Parameters:
  • text (str) – The text to be converted.
  • alnum (bool) – Convert alphanumeric, default True.
Return type:

str

Returns:

Text with full width characters converted to half width.

static half_to_full(text, alnum=True)

Convert all half width katakana, to equivalent full width character.

Parameters:
  • text (str) – The text to be converted.
  • alnum (bool) – Convert alphanumeric, default True.
Return type:

str

Returns:

Text with half width characters converted to full width.

NetherlandsSpecProvider

class mimesis.builtins.NetherlandsSpecProvider(*args, **kwargs)

Class that provides special data for Netherlands (nl).

class Meta

The name of the provider.

bsn()

Generate a random, but valid Burgerservicenummer.

Return type:str
Returns:Random BSN.
Example:255159705
burgerservicenummer()

Generate a random, but valid Burgerservicenummer.

An alias for self.bsn()

Return type:str

RussiaSpecProvider

class mimesis.builtins.RussiaSpecProvider(*args, **kwargs)

Class that provides special data for Russia (ru).

class Meta

The name of the provider.

__init__(*args, **kwargs)

Initialize attributes.

bic()

Generate random BIC (Bank ID Code).

Return type:

str

Returns:

BIC.

Example:
generate_sentence()

Generate sentence from the parts.

Return type:str
Returns:Sentence.
inn()

Generate random, but valid INN.

Return type:str
Returns:INN.
kpp()

Generate random KPP.

Return type:

str

Returns:

‘KPP’.

Example:
ogrn()

Generate random valid OGRN.

Return type:

str

Returns:

OGRN.

Example:
passport_number()

Generate random passport number.

Return type:int
Returns:Number.
Example:560430
passport_series(year=None)

Generate random series of passport.

Parameters:year (int or None) – Year of manufacture.
Return type:str
Returns:Series.
Example:02 15.
patronymic(gender=None)

Generate random patronymic name.

Parameters:gender (Optional[Gender]) – Gender of person.
Return type:str
Returns:Patronymic name.
Example:Алексеевна.
series_and_number()

Generate a random passport number and series.

Return type:str
Returns:Series and number.
Example:57 16 805199.
snils()

Generate snils with special algorithm.

Return type:

str

Returns:

SNILS.

Example:

UkraineSpecProvider

class mimesis.builtins.UkraineSpecProvider(*args, **kwargs)

Class that provides special data for Ukraine (uk).

class Meta

The name of the provider.

__init__(*args, **kwargs)

Initialize attributes.

patronymic(gender=None)

Generate random patronymic name.

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

USASpecProvider

class mimesis.builtins.USASpecProvider(*args, **kwargs)

Class that provides special data for USA (en).

class Meta

The name of the provider.

personality(category='mbti')

Generate a type of personality.

Parameters:category (str) – Category.
Returns:Personality type.
Return type:str or int
Example:ISFJ.
ssn()

Generate a random, but valid SSN.

Return type:str
Returns:SSN.
Example:569-66-5801
tracking_number(service='usps')

Generate random tracking number.

Supported services: USPS, FedEx and UPS.

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

Decorators

Decorators for the public API and for internal purpose.

mimesis.decorators.romanized(locale='')

Romanize the Cyrillic text.

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

Note

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

Parameters:locale (str) – Locale code.
Return type:Callable
Returns:Latinized text.

Custom Exceptions

UnsupportedAlgorithm

class mimesis.exceptions.UnsupportedAlgorithm

Raised when the user wants to use an unsupported algorithm.

UnsupportedField

class mimesis.exceptions.UnsupportedField(name=None)

Raises when field is not supported.

UnsupportedLocale

class mimesis.exceptions.UnsupportedLocale(locale=None)

Raised when a locale isn’t supported.

UndefinedField

class mimesis.exceptions.UndefinedField

Raises when field is None.

UndefinedSchema

class mimesis.exceptions.UndefinedSchema

Raised when schema is empty.

NonEnumerableError

class mimesis.exceptions.NonEnumerableError(enum_obj)

Raised when object is not instance of Enum.

Usual Data Providers

Address

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

Class for generate fake address data.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:locale – Current locale.
address()

Generate a random full address.

Return type:str
Returns:Full address.
Example:5 Central Sideline.
calling_code()

Get a random calling code of random country.

Return type:str
Returns:Calling code.
Example:+7
city()

Get a random city.

Return type:str
Returns:City name.
Example:Saint Petersburg.
continent(code=False)

Get a random continent name or continent code.

Parameters:code (bool) – Return code of continent.
Return type:str
Returns:Continent name.
Example:Africa (en)
coordinates(dms=False)

Generate random geo coordinates.

Parameters:dms (bool) – DMS format.
Return type:dict
Returns:Dict with coordinates.
Example:{‘latitude’: 8.003968, ‘longitude’: 36.028111}
country()

Get a random country.

Return type:str
Returns:The Country.
Example:Russia.
country_code(fmt=<CountryCode.A2: 'a2'>)

Get a random code of country.

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

Parameters:fmt (Optional[CountryCode]) – Enum object CountryCode.
Return type:str
Returns:Country code in selected format.
Raises:KeyError – if fmt is not supported.
Example:DE
federal_subject(*args, **kwargs)

Get a random region.

Parameters:
  • args – Arguments.
  • kwargs – Keyword arguments.
Return type:

str

Returns:

Federal subject.

latitude(dms=False)

Generate a random value of latitude.

Parameters:dms (bool) – DMS format.
Return type:Union[str, float]
Returns:Value of longitude.
Example:-66.421418
longitude(dms=False)

Generate a random value of longitude.

Parameters:dms (bool) – DMS format.
Return type:Union[str, float]
Returns:Value of longitude.
Example:112.184402
postal_code()

Generate a postal code for current locale.

Return type:str
Returns:Postal code.
Example:389213
prefecture(*args, **kwargs)

Get a random prefecture.

Parameters:
  • args – Arguments.
  • kwargs – Keyword arguments.
Return type:

str

Returns:

Prefecture.

province(*args, **kwargs)

Get a random province.

Parameters:
  • args – Arguments.
  • kwargs – Keyword arguments.
Return type:

str

Returns:

Province.

region(*args, **kwargs)

Get a random region.

Parameters:abbr (bool) – Return ISO 3166-2 code.
Return type:str
Returns:State.
state(abbr=False)

Get a random administrative district of country.

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

Get a random street name.

Return type:str
Returns:Street name.
Example:Candlewood.
street_number(maximum=1400)

Generate a random street number.

Parameters:

maximum (int) – Maximum value.

Return type:

str

Returns:

Street number.

Example:
street_suffix()

Get a random street suffix.

Return type:str
Returns:Street suffix.
Example:Alley.
zip_code()

Generate a zip code.

An alias for method self.postal_code.

Return type:str
Returns:Zip code.

BaseProvider

class mimesis.providers.BaseProvider(seed=None)

This is a base class for all providers.

__init__(seed=None)

Initialize attributes.

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

Reseed the internal random generator.

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

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

Business

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

Class for generating data for business.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:locale – Current locale.
company()

Get a random company name.

Return type:str
Returns:Company name.
Example:Gamma Systems.
company_type(abbr=False)

Get a random type of business entity.

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

Generate a random copyright.

Return type:str
Returns:Copyright of company.
Example:© Komercia, Inc.
cryptocurrency_iso_code()

Get symbol of random cryptocurrency.

Return type:str
Returns:Symbol of cryptocurrency.
cryptocurrency_symbol()

Get a cryptocurrency symbol.

Return type:str
Returns:Symbol of cryptocurrency.
Example:Ƀ
currency_iso_code()

Get code of the currency.

Return type:str
Returns:Currency code.
Example:RUR.
currency_symbol()

Get a currency symbol for current locale.

Returns:Currency symbol.
price(minimum=10.0, maximum=1000.0)

Generate a random price.

Parameters:
  • minimum (float) – Max value of price.
  • maximum (float) – Min value of price.
Return type:

str

Returns:

Price.

Example:

599.99 $.

price_in_btc(minimum=0, maximum=2)

Generate random price in BTC.

Parameters:
  • minimum (float) – Minimum value of price
  • maximum (float) – Maximum value of price.
Return type:

str

Returns:

Price in BTC.

>>> from mimesis import Business
>>> provider  = Business()
>>> provider.price_in_btc(minimum=0.2456789,maximum=0.2456789)
'0.2456789 BTC'

ClothingSize

class mimesis.ClothingSize(locale=None, seed=None)

Class for generate clothing sizes data.

custom_size(minimum=40, maximum=62)

Generate clothing size using custom format.

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

int

Returns:

Clothing size.

Example:

44

european_size()

Generate a random clothing size in European format.

Return type:int
Returns:Clothing size.
Example:42
international_size()

Get a random size in international format.

Return type:str
Returns:Clothing size.
Example:XXL.

Code

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

Class that provides methods for generating codes.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:locale – Current locale.
ean(fmt=None)

Generate EAN.

Default fmt is EAN-13, but you also can use EAN-8.

Parameters:

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

Return type:

str

Returns:

EAN.

Raises:

NonEnumerableError – if fmt is not enum EANFormat.

Example:
imei()

Generate a random IMEI.

Return type:str
Returns:IMEI.
Example:353918052107063
isbn(fmt=None)

Generate ISBN for current locale.

Default fmt is ISBN 10, but you also can use ISBN-13.

Parameters:fmt (Optional[ISBNFormat]) – ISBN format.
Return type:str
Returns:ISBN.
Raises:NonEnumerableError – if fmt is not enum ISBNFormat.
Example:132-1-15411-375-8.
issn(mask='####-####')

Generate a random ISSN.

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

Get a random locale code (MS-LCID).

See Windows Language Code Identifier Reference for more information.

Return type:str
Returns:Locale code.
Example:de-ch
pin(mask='####')

Generate a random PIN code.

Parameters:

mask (str) – Mask of pin code.

Return type:

str

Returns:

PIN code.

Example:

Cryptographic

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

Class that provides cryptographic data.

__init__(*args, **kwargs)

Initialize attributes.

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

Generate byte string containing entropy bytes.

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

Parameters:entropy (int) – Number of bytes.
Returns:Bytes.
Return type:bytes
hash(algorithm=None)

Generate random hash.

Parameters:algorithm (Optional[Algorithm]) – Enum object Algorithm.
Return type:str
Returns:Hash.
Raises:NonEnumerableError – if algorithm is not supported.
mnemonic_phrase(length=12)

Generate pseudo mnemonic phrase.

Parameters:length (int) – Number of words.
Return type:str
Returns:Mnemonic code.
salt(size=16)

Generate salt chars (not cryptographically safe).

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

Generate hexadecimal string.

Parameters:entropy (int) – Number of bytes.
Return type:str
Returns:Token.
uuid(version=None)

Generate random UUID.

Parameters:version (Optional[int]) – UUID version.
Return type:str
Returns:UUID

Datetime

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

Class for generating data related to the date and time.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:locale – Current locale.
century()

Get a random century.

Return type:str
Returns:Century.
Example:XXI
date(start=2000, end=2035, fmt='')

Generate a string representing of random date.

Date can be automatically formatted for the current locale or specified.

Parameters:
  • start (int) – Minimum value of year.
  • end (int) – Maximum value of year.
  • fmt (str) – Format string for date.
Return type:

str

Returns:

Formatted date.

Example:

08/16/88 (en)

datetime(humanized=False, **kwargs)

Generate random datetime.

Parameters:
  • humanized (bool) – Readable representation.
  • kwargs – Keyword arguments (start, end).
Returns:

Datetime.

Return type:

datetime.datetime

Example:

March, 24 2002

day_of_month()

Generate a random day of month, from 1 to 31.

Return type:int
Returns:Random value from 1 to 31.
Example:23
day_of_week(abbr=False)

Get a random day of week.

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

Get a random GMT offset value.

Return type:str
Returns:GMT Offset.
Example:‘UTC +03:00’
month(abbr=False)

Get a random month.

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

Get a random periodicity string.

Return type:str
Returns:Periodicity.
Example:Never.
time(fmt='')

Generate a random time.

Time can be automatically formatted for the current locale or specified.

Parameters:fmt (str) – Format of time.
Return type:str
Returns:Time.
Example:21:30:00
timestamp(posix=True, **kwargs)

Generate random timestamp.

Parameters:
  • posix (bool) – POSIX time.
  • kwargs – Keyword arguments (start, end).
Returns:

Timestamp.

Return type:

str or int

Example:

2018-01-02T06:19:19Z

timezone()

Get a random timezone.

Return type:str
Returns:Timezone.
Example:Europe/Paris
week_date(start=2017, end=2018)

Get week number with year.

Parameters:
  • start (int) – From start.
  • end (int) – To end.
Return type:

str

Returns:

Week number.

Example:

2017-W32

year(minimum=1990, maximum=2050)

Generate a random year.

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

int

Returns:

Year.

Example:

2023

Development

class mimesis.Development(locale=None, seed=None)

Class for getting fake data for Developers.

backend()

Get a random backend stack.

Return type:str
Returns:Stack.
Example:Elixir/Phoenix
boolean()

Get a random boolean value.

Return type:bool
Returns:True of False.
container()

Get a random containerization system.

Return type:str
Returns:Containerization system.
Example:Docker.
database(nosql=False)

Get a random database name.

Parameters:nosql (bool) – only NoSQL databases.
Return type:str
Returns:Database name.
Example:PostgreSQL.
frontend()

Get a random front-end stack.

Return type:str
Returns:Stack.
Example:JS/React.
os()

Get a random operating system or distributive name.

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

Get a random programming language from the list.

Return type:str
Returns:Programming language.
Example:Erlang.
software_license()

Get a random software license.

Return type:str
Returns:License name.
Example:The BSD 3-Clause License.
version(calver=False, pre_release=False)

Generate version number.

Parameters:
  • calver (bool) – Calendar versioning.
  • pre_release (bool) – Pre-release.
Return type:

str

Returns:

Version.

Example:

0.2.1

version_control_system()

Get a random version control system.

Return type:str
Returns:Version control system
Example:Git

File

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

Class for generate data related to files.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:
  • args – Arguments.
  • kwargs – Keyword arguments.
extension(file_type=None)

Get a random file extension from list.

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

Get a random file name with some extension.

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

Get a random mime type from list.

Parameters:type (Optional[MimeType]) – Enum object MimeType.
Return type:str
Returns:Mime type.
size(minimum=1, maximum=100)

Get size of file.

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

str

Returns:

Size of file.

Example:

56 kB

Food

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

Class for generating data related to food.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:locale – Current locale.
dish()

Get a random dish.

Return type:str
Returns:Dish name.
Example:Ratatouille.
drink()

Get a random drink.

Return type:str
Returns:Alcoholic drink.
Example:Vodka.
fruit()

Get a random fruit or berry.

Return type:str
Returns:Fruit name.
Example:Banana.
spices()

Get a random spices or herbs.

Return type:str
Returns:Spices or herbs.
Example:Anise.
vegetable()

Get a random vegetable.

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

Games

class mimesis.Games(locale=None, seed=None)

Class for generating data related to the games.

game()

Get a random game from list of games.

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

Get random gaming platform.

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

Get a random genre of game.

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

Get a random PEGI rating.

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

Score of game.

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

float

Returns:

Score.

score_phrase()

Get a random score phrase.

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

Generic

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

Class which contain all providers at one.

__init__(*args, **kwargs)

Initialize attributes lazily.

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

Add a custom provider to Generic() object.

Parameters:cls – Custom provider.
Return type:None
Returns:None
Raises:TypeError – if cls is not class.
add_providers(*providers)

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

Parameters:providers – Custom providers.
Return type:None
Returns:None

Hardware

class mimesis.Hardware(locale=None, seed=None)

Class for generate data related to hardware.

cpu()

Get a random CPU name.

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

Get a random CPU code name.

Return type:str
Returns:CPU code name.
Example:Cannonlake.
cpu_frequency()

Get a random frequency of CPU.

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

Get a random CPU model.

Return type:str
Returns:CPU model.
generation()

Get a random generation.

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

Get a random graphics.

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

Get a random manufacturer.

Return type:str
Returns:Manufacturer.
Example:Dell.
phone_model()

Get a random phone model.

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

Get a random size of RAM.

Return type:str
Returns:RAM size.
Example:16GB.
ram_type()

Get a random RAM type.

Return type:str
Returns:Type of RAM.
Example:DDR3.
resolution()

Get a random screen resolution.

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

Get a random size of screen in inch.

Return type:str
Returns:Screen size.
Example:13″.
ssd_or_hdd()

Get a random value from list.

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

Internet

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

Class for generating data related to the internet.

__init__(*args, **kwargs)

Initialize attributes.

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

Get random category of torrent portal.

Returns:Category name.
Example:Video/TV shows
content_type(mime_type=None)

Get a random HTTP content type.

Return type:str
Returns:Content type.
Example:Content-Type: application/json
emoji()

Get a random emoji shortcut code.

Return type:

str

Returns:

Emoji code.

Example:
kissing:
hashtags(quantity=4)

Generate a list of hashtags.

Parameters:quantity (int) – The quantity of hashtags.
Returns:The list of hashtags.
Return type:str or list
Raises:NonEnumerableError – if category is not in Hashtag.
Example:[‘#love’, ‘#sky’, ‘#nice’]
home_page(tld_type=None)

Generate a random home page.

Parameters:tld_type (Optional[TLDType]) – TLD type.
Return type:str
Returns:Random home page.
Example:http://www.fontir.info
http_method()

Get a random HTTP method.

Return type:str
Returns:HTTP method.
Example:POST
http_status_code()

Get a random HTTP status code.

Return type:int
Returns:HTTP status.
Example:200
http_status_message()

Get a random HTTP status message.

Return type:str
Returns:HTTP status message.
Example:200 OK
image_by_keyword(keyword='')

Generate image by keyword.

Parameters:keyword (str) – Keyword.
Return type:str
Returns:Link to image.
image_placeholder(width=None, height=None)

Generate a link to the image placeholder.

Parameters:
  • width (str or int) – Width of image.
  • height (str or int) – Height of image.
Return type:

str

Returns:

URL to image placeholder.

ip_v4(with_port=False)

Generate a random IPv4 address.

Parameters:with_port (bool) – Add port to IP.
Return type:str
Returns:Random IPv4 address.
Example:19.121.223.58
ip_v6()

Generate a random IPv6 address.

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

Generate a random MAC address.

Return type:str
Returns:Random MAC address.
Example:00:16:3e:25:e7:b1
network_protocol(layer=None)

Get a random network protocol form OSI model.

Parameters:layer (Optional[Layer]) – Enum object Layer.
Return type:str
Returns:Protocol name.
Example:AMQP
port(port_range=<PortRange.ALL: (1, 65535)>)

Generate random port.

Parameters:port_range (PortRange) – Range enum object.
Return type:int
Returns:Port number.
Raises:NonEnumerableError – if port_range is not in PortRange.
Example:8080
stock_image(width=1900, height=1080, category='')

Generate random stock image hosted on Unsplash.

Parameters:
  • category (str) – Category of images.
  • width (str or int) – Width of the image.
  • height (str or int) – Height of the image.
Return type:

str

Returns:

An image (Link to image).

subreddit(nsfw=False, full_url=False)

Get a random subreddit from the list.

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

str

Returns:

Subreddit or URL to subreddit.

Example:

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

top_level_domain(tld_type=None)

Return random top level domain.

Parameters:tld_type (Optional[TLDType]) – Enum object DomainType
Return type:str
Returns:Top level domain.
Raises:NonEnumerableError – if tld_type not in DomainType.
user_agent()

Get a random user agent.

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

Numbers

class mimesis.Numbers(locale=None, seed=None)

Class for generating numbers.

between(minimum=1, maximum=1000)

Generate a random number between minimum and maximum.

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

int

Returns:

Number.

digit(to_bin=False)

Get a random digit.

Parameters:

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

Return type:

Union[str, int]

Returns:

Digit.

Example:
floats(n=2)

Generate a list of random float numbers.

Parameters:n (int) – Raise 10 to the ‘n’ power.
Return type:List[float]
Returns:The list of floating-point numbers.
integers(start=0, end=10, length=10)

Generate a list of random integers.

Integers can be negative or positive numbers. .. note: You can use both positive and negative numbers.

Parameters:
  • start (int) – Start.
  • end (int) – End.
  • length (int) – Length of list.
Return type:

List[int]

Returns:

List of integers.

Example:

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

static primes(start=1, end=999)

Generate a list of prime numbers.

Parameters:
  • start (int) – First value of range.
  • end (int) – Last value of range.
Return type:

List[int]

Returns:

A list of prime numbers from start to end.

rating(maximum=5.0)

Generate a random rating for something.

Parameters:maximum (float) – Maximum value (default is 5.0).
Return type:float
Returns:Rating.
Example:4.7

Path

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

Class that provides methods and property for generate paths.

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

Initialize attributes.

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

Parameters:platform (str) – Required platform type.
Return type:None
dev_dir()

Generate a random path to development directory.

Return type:Optional[str]
Returns:Path.
Example:/home/sherrell/Development/Python/mercenary
home()

Generate a home path.

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

Generate a random path to project directory.

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

Generate a root dir path.

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

Generate a random user.

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

Generate a random path to user’s folders.

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

Person

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

Class for generating personal data.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:
  • locale – Current locale.
  • seed – Seed.
Return type:

None

academic_degree()

Get a random academic degree.

Return type:str
Returns:Degree.
Example:Bachelor.
age(minimum=16, maximum=66)

Get a random integer value.

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

int

Returns:

Random integer.

Example:
avatar(size=256)

Generate a random avatar..

Parameters:size (int) – Size of avatar.
Return type:str
Returns:Link to avatar.
blood_type()

Get a random blood type.

Return type:str
Returns:Blood type (blood group).
Example:A+
child_count(max_children=5)

Get a count of children.

Parameters:max_children (int) – Maximum count of children.
Return type:int
Returns:Ints. Depend on previous generated age.
email(domains=None)

Generate a random email.

Parameters:domains (list or tuple) – List of custom domains for emails.
Return type:str
Returns:Email address.
Example:foretime10@live.com
favorite_movie()

Get a random movie for current locale.

Return type:str
Returns:The name of the movie.
Example:Interstellar.
favorite_music_genre()

Get a random music genre.

Return type:str
Returns:A music genre.
Example:Ambient.
full_name(gender=None, reverse=False)

Generate a random full name.

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

str

Returns:

Full name.

Example:

Johann Wolfgang.

gender(iso5218=False, symbol=False)

Get a random gender.

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

Parameters:
  • iso5218 (bool) – Codes for the representation of human sexes is an international standard (0 - not known, 1 - male, 2 - female, 9 - not applicable).
  • symbol (bool) – Symbol of gender.
Return type:

Union[str, int]

Returns:

Title of gender.

Example:

Male

height(minimum=1.5, maximum=2.0)

Generate a random height in M (Meter).

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

str

Returns:

Height.

Example:

1.85.

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

Generate a random identifier by mask.

With this method you can generate any identifiers that you need. Simply select the mask that you need.

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

Get a random language.

Return type:str
Returns:Random language.
Example:Irish.
last_name(gender=None)

Generate a random last name.

..note: An alias for self.surname().

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

Get a random level of English.

Return type:str
Returns:Level of english.
Example:Intermediate.
name(gender=None)

Generate a random name.

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

Get a random nationality.

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

Get a random job.

Return type:str
Returns:The name of job.
Example:Programmer.
password(length=8, hashed=False)

Generate a password or hash of password.

Parameters:
  • length (int) – Length of password.
  • hashed (bool) – MD5 hash.
Return type:

str

Returns:

Password or hash of password.

Example:

k6dv2odff9#4h

political_views()

Get a random political views.

Return type:str
Returns:Political views.
Example:Liberal.
sexual_orientation(symbol=False)

Get a random (LOL) sexual orientation.

Parameters:symbol (bool) – Unicode symbol.
Return type:str
Returns:Sexual orientation.
Example:Heterosexuality.
social_media_profile(site=None)

Generate profile for random social network.

Return type:str
Returns:Profile in some network.
Example:http://facebook.com/some_user
surname(gender=None)

Generate a random surname.

Parameters:gender (Optional[Gender]) – Gender’s enum object.
Return type:str
Returns:Surname.
Example:Smith.
telephone(mask='', placeholder='#')

Generate a random phone number.

Parameters:
  • mask (str) – Mask for formatting number.
  • placeholder (str) – A placeholder for a mask (default is #).
Return type:

str

Returns:

Phone number.

Example:

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

title(gender=None, title_type=None)

Generate a random title for name.

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

Parameters:
  • gender (Optional[Gender]) – The gender.
  • title_type (Optional[TitleType]) – TitleType enum object.
Return type:

str

Returns:

The title.

Raises:

NonEnumerableError – if gender or title_type in incorrect format.

Example:

PhD.

university()

Get a random university.

Return type:str
Returns:University name.
Example:MIT.
username(template=None)

Generate username by template.

Supported templates: (‘U_d’, ‘U.d’, ‘U-d’, ‘UU-d’, ‘UU.d’, ‘UU_d’, ‘ld’, ‘l-d’, ‘Ud’, ‘l.d’, ‘l_d’, ‘default’)

Parameters:template (Optional[str]) – Template
Return type:str
Returns:Username.
Raises:KeyError – if template is not supported.
Example:Celloid1873
views_on()

Get a random views on.

Return type:str
Returns:Views on.
Example:Negative.
weight(minimum=38, maximum=90)

Generate a random weight in Kg.

Parameters:
  • minimum (int) – min value
  • maximum (int) – max value
Return type:

int

Returns:

Weight.

Example:
work_experience(working_start_age=22)

Get a work experience.

Parameters:working_start_age (int) – Age then person start to work.
Return type:int
Returns:Depend on previous generated age.
worldview()

Get a random worldview.

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

Science

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

Class for generating pseudo-scientific data.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:
  • locale – Current language.
  • seed – Seed.
atomic_number()

Generate random atomic number.

Return type:int
Returns:Atomic number
Example:92
chemical_element(name_only=True)

Generate a random chemical element.

Parameters:name_only (bool) – If False then will be returned dict.
Returns:Name of chemical element or dict.
Return type:dict or str
Example:{‘Symbol’: ‘S’, ‘Name’: ‘Sulfur’, ‘Atomic number’: ‘16’}
dna(length=10)

Generate a random DNA sequence.

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

Get a random mathematical formula.

Return type:str
Returns:Math formula.
Example:A = (ab)/2.
rna(length=10)

Generate a random RNA sequence.

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

Generate a random link to scientific article on Wikipedia.

Return type:str
Returns:Link to the article.
Example:https://en.wikipedia.org/wiki/Black_hole

Structure

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

Class for generating structured data.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:
  • locale – Current locale.
  • seed – Seed.
Return type:

None

css()

Generate a random snippet of CSS.

Return type:str
Returns:CSS.
css_property()

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

Return type:str
Returns:CSS property.
Examples:‘background-color: #f4d3a1’
html()

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

Return type:str
Returns:HTML.
Examples:‘<span class=”select” id=”careers”> Ports are created with the built-in function open_port. </span>’
html_attribute_value(tag=None, attribute=None)

Generate random value for specified HTML tag attribute.

Parameters:
  • tag (Optional[str]) – An HTML tag.
  • attribute (Optional[str]) – An attribute of the specified tag.
Return type:

str

Returns:

An attribute.

Raises:

NotImplementedError – if tag is unsupported.

json(items=5, max_depth=3, recursive=False)

Generate a random snippet of JSON.

Parameters:
  • items (int) – Number of top-level items to produce.
  • max_depth (int) – Maximum depth of each top-level item.
  • recursive (bool) – When used recursively, will return a Python object instead of JSON string.
Return type:

str

Returns:

JSON

Text

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

Class for generating text data.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:
  • locale – Current locale.
  • seed – Seed.
alphabet(lower_case=False)

Get an alphabet for current locale.

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

Get a random answer in current language.

Return type:str
Returns:An answer.
Example:No
color()

Get a random name of color.

Return type:str
Returns:Color name.
Example:Red.
hex_color(safe=False)

Generate a random hex color.

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

Generate a random level of danger or something else.

Return type:str
Returns:Level.
Example:critical.
quote()

Get a random quote.

Return type:str
Returns:Quote from movie.
Example:“Bond… James Bond.”
rgb_color(safe=False)

Generate a random rgb color tuple.

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

Get a random sentence from text.

Return type:str
Returns:Sentence.
swear_word()

Get a random swear word.

Return type:str
Returns:Swear word.
Example:Damn.
text(quantity=5)

Generate the text.

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

Get a random title.

Return type:str
Returns:The title.
word()

Get a random word.

Return type:str
Returns:Single word.
Example:Science.
words(quantity=5)

Generate lis of the random words.

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

Transport

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

Class for generating data related to transports.

__init__(*args, **kwargs)

Initialize attributes.

Parameters:
  • locale – Current locale.
  • seed – Seed.
Return type:

None

airplane(model_mask='###')

Generate a dummy airplane model.

Parameters:model_mask (str) – Mask of truck model. Here ‘@’ is a placeholder of characters and ‘#’ is a placeholder of digits.
Return type:str
Returns:Airplane model.
Example:Boeing 727.
car()

Get a random vehicle.

Return type:str
Returns:A vehicle.
Example:Tesla Model S.
truck(model_mask='#### @@')

Generate a truck model.

Parameters:model_mask (str) – Mask of truck model. Here ‘@’ is a placeholder of characters and ‘#’ is a placeholder of digits.
Return type:str
Returns:Dummy truck model.
Example:Caledon-966O.
vehicle_registration_code(allow_random=True)

Get vehicle registration code of country.

Parameters:allow_random (bool) – If False return only code for current locale (country).
Return type:str
Returns:Vehicle registration code.

UnitSystem

class mimesis.UnitSystem(locale=None, seed=None)

Class for generating data related to units.

prefix(sign=None, symbol=False)

Get a random prefix for the International System of Units.

Parameters:
  • sign (Optional[PrefixSign]) – Sing of number.
  • symbol (bool) – Return symbol of prefix.
Return type:

str

Returns:

Prefix for SI.

Raises:

NonEnumerableError – if sign is not supported.

Example:

mega

unit(name=None, symbol=False)

Get unit name.

Parameters:
  • name (Optional[UnitName]) – Enum object UnitName.
  • symbol – Return only symbol
Returns:

Unit.

Schema

AbstractField

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

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

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

>>> _ = AbstractField('en', 0xf)
>>> _('full_name')
'Jack Allison'

Field

mimesis.schema.Field

alias of mimesis.schema.AbstractField

Schema

class mimesis.schema.Schema(schema)

Class which return list of filled schemas.

create(iterations=1)

Return filled schema.

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

Parameters:iterations (int) – Amount of iterations.
Return type:List[Any]
Returns:List of willed schemas.

Enums

Implements enums for a lot of methods.

Enums from this module are used in a lot of methods. You should always import enums from this module if you want behavior for the methods that differ from the default behavior.

You should never use your own enums in methods because in this case, there no guarantee that you will get the result which you actually expected.

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

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

Provides algorithms which available.

Value for methods which take argument algorithm.

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

Provides cart types.

Value for a method Payment.credit_card_number() which takes parameter card_type.

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

Provides types of country codes.

Value for method Address.country_code() which takes parameter fmt.

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

Provides formats of EAN.

Value for method Code.ean() which takes parameter fmt.

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

Provides file types.

Value for methods which takes parameter file_type.

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

Represents genders.

Value for a lot of methods which takes argument gender.

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

Provides formats of ISBN.

Value for method Code.isbn() which takes parameter fmt.

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

Provides network protocol layers.

Value for method Internet.network_protocol() which takes parameter layer.

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

Provides common mime types.

Value for method File.mime_type() which takes parameter type_.

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

Represents port ranges.

Value for a method Internet.port() which takes parameter port_range.

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

Provides prefix signs.

Value for method UnitSystem.prefix() which takes parameter sign.

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

Provides most popular social networks.

Value for method Person.social_media_profile() which takes parameter site.

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

Provides top level domain types.

Value for a method Internet.top_level_domain() which takes parameter tld_type.

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

Represents title types.

Value for a method Person.title() which takes parameter``title_type``.

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

Provide unit names.

Value for method UnitSystem.unit() which takes parameter name.

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