## File: README.md --- **Documentation**: [https://mimesis.name/](https://mimesis.name/) --- Mimesis ([/mɪˈmiːsɪs](https://mimesis.name/master/about.html#what-does-name-mean)) is a Python library for generating fake but realistic data in multiple languages and locales. It can generate names, addresses, dates, phone numbers, emails, financial data, and many other types of values. It is commonly used to populate test databases, mock API responses, generate JSON or XML fixtures, create sample datasets, and anonymize production data. Mimesis provides a simple, consistent API that makes it easy to generate realistic data for development and testing. The key features are: - **Multilingual**: Supports 47 different locales. - **Extensibility**: Supports custom data providers and custom field handlers. - **Ease of use**: Features a simple design and clear documentation for straightforward data generation. - **Performance**: Widely recognized as the fastest data generator among Python solutions. - **Data variety**: Includes various data providers designed for different use cases. - **Schema-based generators**: Offers schema-based data generators to effortlessly produce data of any complexity. - **Relational data**: Supports generating related datasets with foreign keys and nested schemas. - **Intuitive**: Great editor support. Fully typed, so you get autocompletion almost everywhere. ## Installation To install Mimesis, use pip: ``` ~ pip install mimesis ``` ## Documentation You can find the complete documentation on the [Read the Docs](https://mimesis.name/). It is divided into several sections: - [About Mimesis](https://mimesis.name/latest/about.html) - [Quickstart](https://mimesis.name/latest/quickstart.html) - [Locales](https://mimesis.name/latest/locales.html) - [Data Providers](https://mimesis.name/latest/providers.html) - [Structured Data Generation](https://mimesis.name/latest/schema.html) - [Relational Data Generation](https://mimesis.name/latest/relational.html) - [Random and Seed](https://mimesis.name/latest/random_and_seed.html) - [Integration with factory_boy](https://mimesis.name/latest/factory_plugin.html) - [API Reference](https://mimesis.name/latest/api.html) - [Changelog](https://mimesis.name/latest/index.html#changelog) You can improve it by sending pull requests to this repository. ## Usage Import a data provider that corresponds to the data type you need. For example, the [Person](https://mimesis.name/latest/api.html#person) provider gives access to personal information, including name, surname, email, and other related fields: ```python from mimesis import Person from mimesis.locales import Locale person = Person(Locale.EN) person.full_name() # Output: 'Brande Sears' person.email(domains=['example.com']) # Output: 'roccelline1878@example.com' person.email(domains=['mimesis.name'], unique=True) # Output: 'f272a05d39ec46fdac5be4ac7be45f3f@mimesis.name' person.telephone(mask='1-4##-8##-5##3') # Output: '1-436-896-5213' ``` ## License Mimesis is licensed under the MIT License. See [LICENSE](https://github.com/lk-geimfari/mimesis/blob/master/LICENSE) for more information. --- ## File: docs/about.rst ============= About Mimesis ============= What is Mimesis? ---------------- **Mimesis** provides a perfect solution for generating data. It effectively populates databases, creates intricate JSON/XML files, anonymizes production data, and generates high-quality Pandas dataframes. If you require these functions, Mimesis is the ideal tool for you. Mimesis **is not** an object factory intended for use with a specific database or ORM. However, this does not mean that it cannot be used with an ORM. In fact, it can be easily integrated with an ORM using third-party libraries like `mimesis-factory `_ or others. Features -------- The key features are: - **Multilingual**: Supports 47 different locales. - **Extensibility**: Supports custom data providers and custom field handlers. - **Ease of use**: Features a simple design and clear documentation for straightforward data generation. - **Performance**: Widely recognized as the fastest data generator among Python solutions. See :doc:`benchmarks`. - **Data variety**: Includes various data providers designed for different use cases. - **Schema-based generators**: Offers schema-based data generators to effortlessly produce data of any complexity. - **Relational data**: Supports generating related datasets with foreign keys and nested schemas via :class:`~mimesis.builder.SchemaBuilder` (see :doc:`relational`). - **Intuitive**: Great editor support. Fully typed, so you get autocompletion almost everywhere. What is fake data? ------------------ Fake data refers to data that is not useful or sensitive, but is used to occupy a space where real data is typically located. This type of data can act as a placeholder for both testing and operational purposes. In testing, it can also serve as stubs or placeholders. What does the name mean? ------------------------ Mimesis (`/maɪˈmiːsəs/ `_; `Ancient Greek `_: μίμησις (*mīmēsis*), from μιμεῖσθαι (*mīmeisthai*), "to imitate", from μῖμος (mimos), "imitator, actor") is a term of critical and philosophical significance, rooted in Ancient Greek, with various connotations such as imitation, representation, mimicry, receptivity, nonsensuous similarity, resemblance, expression, and the presentation of the self. Why octopus? ------------ Octopuses are fascinating creatures, and some families of octopuses have incredible `mimicry `_ abilities. `Thaumoctopus mimicus `_ is a particularly impressive example, and if you haven't heard of it yet, you should definitely read up on this remarkable species. Check out that spotty bastard. Isn't it badass as hell? .. image:: _static/thaumoctopus_mimicus.jpg :width: 700 :target: https://mimesis.name/ --- ## File: docs/additional-info.rst .. _additional-info: License ======= MIT License Copyright (c) 2017-Present Isaak Uchakaev and contributors. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Contributors ============ Mimesis is written and maintained by Isaak Uchakaev (Likid Geimfari: `lk-geimfari`_) and various contributors: Maintainers ~~~~~~~~~~~ - Likid Geimfari (`lk-geimfari`_) - Sobolev Nikita (`sobolevn`_) Patches and Suggestions ~~~~~~~~~~~~~~~~~~~~~~~ - Kevin Schellenberg (`wikkiewikkie`_) - Casey Weed (`Battleroid`_) - Alessandro Martini (`martini97`_) - Amin Alaee (`aminalaee`_) - Baurzhan Muftakhidinov (`crayxt`_) - Benjamin Schwarze (`benjixx`_) - Bill DeRusha (`bderusha`_) - David Poggi (`drpoggi`_) - Eliz Kiliç (`el`_) - Flavio Curella (`fcurella`_) - FliegendeWurst (`FliegendeWurst`_) - JLWT90 (`jlwt90`_) - Jack McMorrow (`jackmcmorrow`_) - Jakub Wilk (`jwilk`_) - Jeremy Costava (`Costava`_) - Jin Yang (`redus`_) - Json701 (`jasonwaiting-dev`_) - Jérôme Christ (`jeromechrist`_) - Michael Crilly (`mrcrilly`_) - Michael Hand (`mipaaa`_) - Paul Walters (`PaulWaltersDev`_) - Philipp Offermann (`offermann`_) - Sobolev Nikita (`sobolevn`_) - Rafael Passos (`auyer`_) - Ranwise (`ranwise`_) - Sambuddha Basu (`sammyshj`_) - Thomas Carroll (`Uncleleech`_) - Tsimpitas Dimitris `TsimpDim`_ - Vladislav Glinsky (`cl0ne`_) - Yn-Coder (`yn-coder`_) - Dmytro Zelinskyi (`zelds`_) - axcel (`axce1`_) - Ruslan Valerievich (`Valerievich`_) - Simon (`DefaltSimon`_) - dy (`duckyou`_) .. _lk-geimfari: https://github.com/lk-geimfari .. _sobolevn: https://github.com/sobolevn .. _duckyou: https://github.com/duckyou .. _wikkiewikkie: https://github.com/wikkiewikkie .. _Valerievich: https://github.com/Valerievich .. _Battleroid: https://github.com/Battleroid .. _martini97: https://github.com/martini97 .. _aminalaee: https://github.com/aminalaee .. _crayxt: https://github.com/crayxt .. _benjixx: https://github.com/benjixx .. _bderusha: https://github.com/bderusha .. _drpoggi: https://github.com/drpoggi .. _el: https://github.com/el .. _fcurella: https://github.com/fcurella .. _FliegendeWurst: https://github.com/FliegendeWurst .. _jlwt90: https://github.com/jlwt90 .. _jackmcmorrow: https://github.com/jackmcmorrow .. _jwilk: https://github.com/jwilk .. _Costava: https://github.com/Costava .. _redus: https://github.com/redus .. _jasonwaiting-dev: https://github.com/jasonwaiting-dev .. _jeromechrist: https://github.com/jeromechrist .. _mrcrilly: https://github.com/mrcrilly .. _mipaaa: https://github.com/mipaaa .. _PaulWaltersDev: https://github.com/PaulWaltersDev .. _offermann: https://github.com/offermann .. _auyer: https://github.com/auyer .. _ranwise: https://github.com/ranwise .. _sammyshj: https://github.com/sammyshj .. _Uncleleech: https://github.com/Uncleleech .. _TsimpDim: https://github.com/TsimpDim .. _cl0ne: https://github.com/cl0ne .. _yn-coder: https://github.com/yn-coder .. _zelds: https://github.com/zelds .. _axce1: https://github.com/axce1 .. _DefaltSimon: https://github.com/DefaltSimon .. _(ceccoemi): https://github.com/ceccoemi Disclaimer ========== The creators of Mimesis do not hold themselves accountable for how you employ the library's functionalities or the data generated with it. Mimesis is designed to facilitate testing and is intended for legitimate use. Mimesis should not be used for illicit purposes. --- ## File: docs/api.rst .. _api-reference: === API === This part of the documentation covers all the public interfaces of *Mimesis*. Random module ============= .. autoclass:: mimesis.random.Random :members: :special-members: __init__ Keys module =========== .. automodule:: mimesis.keys :members: Shortcuts ========= .. automodule:: mimesis.shortcuts :members: Custom Exceptions ================= .. automodule:: mimesis.exceptions :members: Base Providers ============== BaseProvider ------------ .. autoclass:: mimesis.providers.BaseProvider :members: :special-members: __init__ BaseDataProvider ---------------- .. autoclass:: mimesis.providers.BaseDataProvider :members: :special-members: __init__ Generic Providers ================= Generic ------- .. autoclass:: mimesis.Generic :members: :special-members: __init__ Localized Providers =================== Address ------- .. autoclass:: mimesis.Address :members: :special-members: __init__ Finance ------- .. autoclass:: mimesis.Finance :members: :special-members: __init__ Datetime -------- .. autoclass:: mimesis.Datetime :members: :special-members: __init__ Food ---- .. autoclass:: mimesis.Food :members: :special-members: __init__ Person -------- .. autoclass:: mimesis.Person :members: :special-members: __init__ Text ---- .. autoclass:: mimesis.Text :members: :special-members: __init__ Universal Providers =================== BinaryFile ---------- .. autoclass:: mimesis.BinaryFile :members: :special-members: __init__ Code ---- .. autoclass:: mimesis.Code :members: :special-members: __init__ Choice ------ .. autoclass:: mimesis.Choice :members: :special-members: __init__ Cryptographic ------------- .. autoclass:: mimesis.Cryptographic :members: :special-members: __init__ Development ----------- .. autoclass:: mimesis.Development :members: :special-members: __init__ File ---- .. autoclass:: mimesis.File :members: :special-members: __init__ Hardware -------- .. autoclass:: mimesis.Hardware :members: :special-members: __init__ Internet -------- .. autoclass:: mimesis.Internet :members: :special-members: __init__ Numeric ------- .. autoclass:: mimesis.Numeric :members: :special-members: __init__ Path ---- .. autoclass:: mimesis.Path :members: :special-members: __init__ Payment ------- .. autoclass:: mimesis.Payment :members: :special-members: __init__ Transport --------- .. autoclass:: mimesis.Transport :members: :special-members: __init__ Science ------- .. autoclass:: mimesis.Science :members: :special-members: __init__ Schema-based Generators ======================= BaseField --------- .. autoclass:: mimesis.schema.BaseField :members: :special-members: __call__, __init__ Field ------ .. autoclass:: mimesis.schema.Field :members: Fieldset -------- .. autoclass:: mimesis.schema.Fieldset :members: Schema ------ .. autoclass:: mimesis.schema.Schema :members: :special-members: __init__ SchemaContext ------------- .. autoclass:: mimesis.schema.SchemaContext :members: :special-members: __init__ SchemaBuilder ------------- .. autoclass:: mimesis.builder.SchemaBuilder :members: :special-members: __init__ SchemaRef --------- .. autoclass:: mimesis.builder.SchemaRef :members: :special-members: __init__, __call__ Enums ===== .. automodule:: mimesis.enums :members: :undoc-members: --- ## File: docs/factory_plugin.rst .. _factory_plugin: Integration with factory_boy ============================ .. versionadded:: 15.0.0 You no longer need any third-party packages to integrate Mimesis with ``factory_boy``. Mimesis requires ``factory_boy`` to be installed, but it's not a hard dependency. Therefore, you'll need to install it manually, like this: .. code-block:: bash poetry add --group dev factory_boy Alternatively, you can include it as an extra when installing Mimesis itself, like so: .. code-block:: bash poetry add --group dev mimesis[factory] Usage ----- Look at the example below and you’ll understand how it works: .. code-block:: python class Account(object): def __init__(self, username, email, name, surname, age): self.username = username self.email = email self.name = name self.surname = surname self.age = age Now, use the ``FactoryField`` class to define how fake data is generated: .. code-block:: python import factory from mimesis.plugins.factory import FactoryField from account import Account class AccountFactory(factory.Factory): class Meta(object): model = Account username = FactoryField('username', template='l_d') name = FactoryField('name', gender='female') surname = FactoryField('surname', gender='female') age = FactoryField('age', minimum=18, maximum=90) email = factory.LazyAttribute( lambda instance: '{0}@example.org'.format(instance.username) ) access_token = FactoryField('token', entropy=32) See `factory_boy `_ documentation for more information about how to use factories. Configuration ------------- You can also define custom field handlers for your factories. To do this, you need to define an attribute named ``field_handlers`` in the ``Params`` class of your factory. Just like this: .. code-block:: python import factory from mimesis.plugins.factory import FactoryField class FactoryWithCustomFieldHandlers(factory.Factory): class Meta(object): model = Guest # Your model here class Params(object): field_handlers = [ ("num", lambda rand, **kwargs: rand.randint(1, 99)), ("nick", lambda rand, **kwargs: rand.choice(["john", "alice"])), ] age = FactoryField("num") nickname = FactoryField("nick") See `Custom Field Handlers `_ for more information about how to define custom field handlers. Factories and pytest -------------------- We also recommend using `pytest-factoryboy `_. This way it will be possible to integrate your factories into pytest fixtures. --- ## File: docs/glossary.rst Glossary -------- .. _glossary: .. glossary:: :sorted: field A string that represents a method of a data provider. fieldset A list of fields. provider A class that provides various data generators. locale A locale that represents country-specific data for locale-dependent data providers. See :py:class:`~mimesis.enums.Locale` localized provider A provider that depends on external JSON files with localized data. universal provider A provider without external dependencies that can be used for any locale. key function A callable that transforms the result of a field after generation. Key functions are applied using the ``key`` parameter in field operations. See :py:mod:`~mimesis.keys` field handler A custom callable that generates data for a field. Field handlers accept a :py:class:`~mimesis.random.Random` instance and keyword arguments, and can be registered using :py:meth:`~mimesis.schema.BaseField.register_handler` or the :py:meth:`~mimesis.schema.BaseField.handle` decorator. schema context A context object passed to :meth:`~mimesis.schema.Schema.map` transformers that need more than the item itself. It exposes the current row index, schema seed, and shared run metadata set via :meth:`~mimesis.schema.Schema.with_context` (for example tenant or environment labels). See :py:class:`~mimesis.schema.SchemaContext` and the guide section *Transforming Items with map() and SchemaContext* in :doc:`schema`. schema builder A declarative builder for generating related fake datasets with foreign keys, nested schemas, and automatic dependency resolution. See :py:class:`~mimesis.builder.SchemaBuilder` and :doc:`relational`. --- ## File: docs/index.rst Mimesis: Fake Data Generator ============================ `Mimesis `_ is a Python library for generating fake but realistic data in multiple languages and locales. It can generate names, addresses, dates, phone numbers, emails, financial data, and many other types of values. It is commonly used to populate test databases, mock API responses, generate JSON or XML fixtures, create sample datasets, and anonymize production data. Mimesis provides a simple, consistent API that makes it easy to generate realistic data for development and testing. .. include:: contents.rst.inc --- ## File: docs/installation.rst ============ Installation ============ Compatibility ------------- Mimesis is compatible with Python version 3.10 or higher (including PyPy 3.10). To work with Mimesis on Python versions 3.8 and 3.9, the final compatible version is Mimesis 11.1.0. Install this specific version to ensure compatibility. Dependencies ------------ Mimesis has no hard dependencies, but you need to install `pytz` to add timezone support for some methods of the :class:`~mimesis.Datetime` provider. Install Mimesis --------------- .. note:: To prevent unintended upgrades, it is **highly advisable** to always specify the version of mimesis that you are using by pinning it. The latest version of Mimesis is: .. image:: https://img.shields.io/pypi/v/mimesis?color=bright-green :target: https://pypi.org/project/mimesis/ :alt: PyPi Version Within the pre-activated environment, use the following command to install Mimesis: .. code-block:: sh (env) ➜ pip install mimesis Use the following command to install Mimesis in Jupyter Notebook: .. code-block:: sh (env) ➜ ! pip install mimesis Installation using *poetry* is pretty much the same: .. code-block:: sh (env) ➜ poetry add --group dev mimesis If you want to work with the latest Mimesis code before it's released, install or update the code from the master branch: .. code-block:: sh (env) ➜ git clone git@github.com:lk-geimfari/mimesis.git (env) ➜ cd mimesis/ (env) ➜ make install Optional Dependencies --------------------- To enable the ``factory_boy`` plugin, you need to install Mimesis with the corresponding extra, as shown below: .. code-block:: sh (env) ➜ poetry add --group dev mimesis[factory] --- ## File: docs/locales.rst .. _locale: Locales ======= Mimesis supports multiple locales. This means that you can generate data in different languages and for different countries. The default locale for all providers is English (United States) (``Locale.EN``). You have to import the :class:`~mimesis.enums.Locale` object first, like this: .. code-block:: python from mimesis.locales import Locale Now you can specify a locale when creating providers, and they will return data that is appropriate for the language or country associated with that locale: .. code-block:: python from mimesis import Address from mimesis.locales import Locale de = Address(locale=Locale.DE) ru = Address(locale=Locale.RU) de.region() # Output: 'Brandenburg' ru.federal_subject() # Output: 'Алтайский край' de.address() # Output: 'Mainzer Landstraße 912' ru.address() # Output: 'ул. Пехотная 125' See the table below for more details. Overriding locale ----------------- Sometimes you need only some data from another locale, and creating a new instance for such cases is not ideal, so it's better to temporarily override the current locale for the provider's instance: .. code-block:: python from mimesis import Person from mimesis.locales import Locale person = Person(locale=Locale.EN) person.full_name() # Output: 'Ozie Melton' with person.override_locale(Locale.RU): person.full_name() # Output: 'Симона Богданова' person.full_name() # Output: 'Waldo Foster' You can also use it with :class:`~mimesis.Generic()`: .. code-block:: python from mimesis import Generic from mimesis.locales import Locale generic = Generic(locale=Locale.EN) generic.text.word() # Output: 'anyone' with generic.text.override_locale(Locale.FR): generic.text.word() # Output: 'mieux' generic.text.word() # Output: 'responsibilities' Supported locales ----------------- Mimesis currently includes support for 47 different locales (see :class:`~mimesis.enums.Locale` for more details). The table below lists all supported locales and their associated countries. ======= ======= ==================== ==================== ==================== Country Code Associated attribute Name Native Name ======= ======= ==================== ==================== ==================== 🇦🇪 `ar-ae` **Locale.AR_AE** Arabic U.A.E العربية 🇩🇿 `ar-dz` **Locale.AR_DZ** Arabic Algeria العربية 🇪🇬 `ar-eg` **Locale.AR_EG** Arabic Egypt العربية 🇯🇴 `ar-jo` **Locale.AR_JO** Arabic Jordan العربية 🇰🇼 `ar-kw` **Locale.AR_KW** Arabic Kuwait العربية 🇲🇦 `ar-ma` **Locale.AR_MA** Arabic Morocco العربية 🇴🇲 `ar-om` **Locale.AR_OM** Arabic Oman العربية 🇶🇦 `ar-qa` **Locale.AR_QA** Arabic Qatar العربية 🇸🇦 `ar-sa` **Locale.AR_SA** Arabic Saudi Arabia العربية 🇸🇾 `ar-sy` **Locale.AR_SY** Arabic Syria العربية 🇹🇳 `ar-tn` **Locale.AR_TN** Arabic Tunisia العربية 🇾🇪 `ar-ye` **Locale.AR_YE** Arabic Yemen العربية 🇨🇿 `cs` **Locale.CS** Czech Česky 🇩🇰 `da` **Locale.DA** Danish Dansk 🇩🇪 `de` **Locale.DE** German Deutsch 🇦🇹 `de-at` **Locale.DE_AT** Austrian German Deutsch 🇨🇭 `de-ch` **Locale.DE_CH** Swiss German Deutsch 🇬🇷 `el` **Locale.EL** Greek Ελληνικά 🇺🇸 `en` **Locale.EN** English English 🇦🇺 `en-au` **Locale.EN_AU** Australian English English 🇨🇦 `en-ca` **Locale.EN_CA** Canadian English English 🇬🇧 `en-gb` **Locale.EN_GB** British English English 🇪🇸 `es` **Locale.ES** Spanish Español 🇲🇽 `es-mx` **Locale.ES_MX** Mexican Spanish Español 🇪🇪 `et` **Locale.ET** Estonian Eesti 🇮🇷 `fa` **Locale.FA** Farsi فارسی 🇫🇮 `fi` **Locale.FI** Finnish Suomi 🇫🇷 `fr` **Locale.FR** French Français 🇭🇷 `hr` **Locale.HR** Croatian Hrvatski 🇭🇺 `hu` **Locale.HU** Hungarian Magyar 🇮🇸 `is` **Locale.IS** Icelandic Íslenska 🇮🇹 `it` **Locale.IT** Italian Italiano 🇯🇵 `ja` **Locale.JA** Japanese 日本語 🇰🇿 `kk` **Locale.KK** Kazakh Қазақша 🇰🇷 `ko` **Locale.KO** Korean 한국어 🇳🇱 `nl` **Locale.NL** Dutch Nederlands 🇧🇪 `nl-be` **Locale.NL_BE** Belgian Dutch Nederlands 🇳🇴 `no` **Locale.NO** Norwegian Norsk 🇵🇱 `pl` **Locale.PL** Polish Polski 🇵🇹 `pt` **Locale.PT** Portuguese Português 🇧🇷 `pt-br` **Locale.PT_BR** Brazilian Portuguese Português Brasileiro 🇷🇺 `ru` **Locale.RU** Russian Русский 🇸🇰 `sk` **Locale.SK** Slovak Slovensky 🇸🇪 `sv` **Locale.SV** Swedish Svenska 🇹🇷 `tr` **Locale.TR** Turkish Türkçe 🇺🇦 `uk` **Locale.UK** Ukrainian Українська 🇨🇳 `zh` **Locale.ZH** Chinese 汉语 ======= ======= ==================== ==================== ====================