# fake.py

<!-- External references -->
<!-- Internal references -->
<!-- Related projects -->

Minimalistic, standalone alternative fake data generator with no dependencies.

[![PyPI Version](https://img.shields.io/pypi/v/fake.py.svg)](https://pypi.python.org/pypi/fake.py)[![Supported Python versions](https://img.shields.io/pypi/pyversions/fake.py.svg)](https://pypi.python.org/pypi/fake.py/)[![Build Status](https://github.com/barseghyanartur/fake.py/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/barseghyanartur/fake.py/actions)[![Documentation Status](https://readthedocs.org/projects/fakepy/badge/?version=latest)](http://fakepy.readthedocs.io)[![llms.txt - documentation for LLMs](https://img.shields.io/badge/docs-llms.txt-blue)](https://fakepy.readthedocs.io/en/latest/llms.txt)[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/barseghyanartur/fake.py/#License)[![Coverage](https://coveralls.io/repos/github/barseghyanartur/fake.py/badge.svg?branch=main&service=github)](https://coveralls.io/github/barseghyanartur/fake.py?branch=main)

[fake.py](https://github.com/barseghyanartur/fake.py/) is a standalone, portable library designed for generating various
random data types for testing.

It offers a simplified, dependency-free alternative for creating random
texts, (person) names, URLs, dates, file names, IPs, primitive Python data
types (such as uuid, str, int, float, bool), GEO data such as city,
country, geo-location, country code, latitude, longitude and locales,
IBANs and ISBNs, as well as byte content for multiple file formats
including PDF, DOCX, ODT, RTF, EPUB, PNG, SVG, BMP, GIF,
TIF, PPM, JPG, WAV, ZIP, TAR and EML.

The package also supports file creation on the filesystem and includes
factories (dynamic fixtures) compatible with [Django](https://www.djangoproject.com/), [TortoiseORM](https://tortoise.github.io/),
[Pydantic](https://docs.pydantic.dev/) and [SQLAlchemy](https://www.sqlalchemy.org/) (which means it works with [SQLModel](https://sqlmodel.tiangolo.com/) too).

## Features

- Generation of random texts, (person) names, emails, URLs, dates, IPs, and
  primitive Python data types.
- Support for various file formats (PDF, DOCX, ODT, RTF, EPUB,
  TXT, PNG, SVG, BMP, GIF, TIF, PPM, JPG, WAV, ZIP,
  TAR, EML) and file
  creation on the filesystem.
- Basic factories for integration with [Django](https://www.djangoproject.com/), [Pydantic](https://docs.pydantic.dev/),
  [TortoiseORM](https://tortoise.github.io/) and [SQLAlchemy](https://www.sqlalchemy.org/).
- [CLI](https://fakepy.readthedocs.io/en/latest/cli.html) for generating data from command line.

## Prerequisites

Python 3.9+

## Installation

### pip

```sh
pip install fake.py
```

### Download and copy

`fake.py` is the sole, self-contained module of the package. It includes
tests too. If it’s more convenient to you, you could simply download the
`fake.py` module and include it in your repository.

Since tests are included, it won’t have a negative impact on your test
coverage (you might need to apply [test/coverage configuration tweaks](https://fakepy.readthedocs.io/en/latest/test_configuration_tweaks.html)).

## Documentation

- Documentation is available on [Read the Docs](http://fakepy.readthedocs.io/).
- For various ready to use code examples see the [Recipes](https://fakepy.readthedocs.io/en/latest/recipes.html).
- For tips on how to use the factories see the [Factories](https://fakepy.readthedocs.io/en/latest/factories.html).
- For customisation tips see the [Customisation](https://fakepy.readthedocs.io/en/latest/customisation.html).
- For generic information on how to create files see [Creating files](https://fakepy.readthedocs.io/en/latest/creating_files.html).
- For tips on `PDF` creation see [Creating PDF](https://fakepy.readthedocs.io/en/latest/creating_pdf.html).
- For tips on `DOCX` creation see [Creating DOCX](https://fakepy.readthedocs.io/en/latest/creating_docx.html).
- For tips on `ODT` creation see [Creating ODT](https://fakepy.readthedocs.io/en/latest/creating_odt.html).
- For tips on images creation see [Creating images](https://fakepy.readthedocs.io/en/latest/creating_images.html).
- For tips on archives creation see [Creating archives](https://fakepy.readthedocs.io/en/latest/creating_archives.html).
- For various implementation examples, see the [Examples](https://github.com/barseghyanartur/fake.py/tree/main/examples).
- For tricks on specific content creation see the [Cheat sheet](https://fakepy.readthedocs.io/en/latest/cheatsheet.html).
- For tips on seeding see the [Seed](https://fakepy.readthedocs.io/en/latest/seed.html).
- For CLI documentation, see the [CLI](https://fakepy.readthedocs.io/en/latest/cli.html).
- For guidelines on contributing check the [Contributor guidelines](https://fakepy.readthedocs.io/en/latest/contributor_guidelines.html).

## Usage

### Generate data

#### Person names

```python
from fake import FAKER

FAKER.first_name()  # str
FAKER.first_names()  # list[str]
FAKER.last_name()  # str
FAKER.last_names()  # list[str]
FAKER.name()  # str
FAKER.names()  # list[str]
FAKER.username()  # str
FAKER.usernames()  # list[str]
```

#### Random texts

```python
from fake import FAKER

FAKER.password()  # str
FAKER.paragraph()  # str
FAKER.paragraphs()  # list[str]
FAKER.sentence()  # str
FAKER.sentences()  # list[str]
FAKER.slug()  # str
FAKER.slugs()  # list[str]
FAKER.text()  # str
FAKER.texts()  # list[str]
FAKER.word()  # str
FAKER.words()  # list[str]
```

#### Internet

```python
from fake import FAKER

FAKER.company_email()  # str
FAKER.company_emails()  # list[str]
FAKER.domain_name()  # str
FAKER.email()  # str
FAKER.emails()  # list[str]
FAKER.free_email()  # str
FAKER.free_emails()  # list[str]
FAKER.free_email_domain()  # str
FAKER.image_url()  # str
FAKER.ipv4()  # str
FAKER.tld()  # str
FAKER.url()  # str
```

#### Filenames

```python
from fake import FAKER

FAKER.dir_path()  # str
FAKER.file_extension()  # str
FAKER.file_name()  # str
FAKER.file_path()  # str
FAKER.mime_type()  # str
```

#### Primitive data types

```python
from fake import FAKER

FAKER.pybool()  # bool
FAKER.pyfloat()  # float
FAKER.pyint()  # int
FAKER.pystr()  # str
FAKER.uuid()  # uuid.UUID
```

#### Dates

```python
from fake import FAKER

FAKER.date()  # datetime.date
FAKER.date_time()  # datetime.datetime
FAKER.year()  # int
FAKER.time()  # str
```

#### Geographic data

```python
from fake import FAKER

FAKER.city()  # str
FAKER.country()  # str
FAKER.geo_location()  # str
FAKER.country_code()  # str
FAKER.locale()  # str
FAKER.latitude()  # float
FAKER.longitude()  # float
FAKER.latitude_longitude()  # tuple[float, float]
```

#### Books

```python
from fake import FAKER

FAKER.isbn10()  # str
FAKER.isbn13()  # str
```

#### Banking

```python
from fake import FAKER

FAKER.iban()  # str
```

### Generate files

#### As bytes

```python
from fake import FAKER

FAKER.bmp()  # bytes
FAKER.docx()  # bytes
FAKER.eml()  # bytes
FAKER.epub()  # bytes
FAKER.gif()  # bytes
FAKER.jpg()  # bytes
FAKER.odt()  # bytes
FAKER.pdf()  # bytes
FAKER.png()  # bytes
FAKER.ppm()  # bytes
FAKER.rtf()  # bytes
FAKER.svg()  # bytes
FAKER.tar()  # bytes
FAKER.tif()  # bytes
FAKER.wav()  # bytes
FAKER.zip()  # bytes
```

#### As files on the file system

```python
from fake import FAKER

FAKER.bmp_file()  # str
FAKER.docx_file()  # str
FAKER.eml_file()  # str
FAKER.epub_file()  # str
FAKER.gif_file()  # str
FAKER.jpg_file()  # str
FAKER.odt_file()  # str
FAKER.pdf_file()  # str
FAKER.png_file()  # str
FAKER.ppm_file()  # str
FAKER.rtf_file()  # str
FAKER.svg_file()  # str
FAKER.tar_file()  # str
FAKER.tif_file()  # str
FAKER.txt_file()  # str
FAKER.wav_file()  # str
FAKER.zip_file()  # str
```

### Factories/dynamic fixtures

This is how you could define factories for [Django](https://www.djangoproject.com/)’s built-in `Group`
and `User` models.

*Filename: factories.py*

<!-- pytestmark: django_db -->
```python
from django.contrib.auth.models import Group, User
from fake import (
    DjangoModelFactory,
    FACTORY,
    PostSave,
    PreSave,
    trait,
)


class GroupFactory(DjangoModelFactory):
    """Group factory."""

    name = FACTORY.word()

    class Meta:
        model = Group
        get_or_create = ("name",)


def set_password(user: User, password: str) -> None:
    """Helper function for setting password for the User."""
    user.set_password(password)


def add_to_group(user: User, name: str) -> None:
    """Helper function for adding the User to a Group."""
    group = GroupFactory(name=name)
    user.groups.add(group)


class UserFactory(DjangoModelFactory):
    """User factory."""

    username = FACTORY.username()
    first_name = FACTORY.first_name()
    last_name = FACTORY.last_name()
    email = FACTORY.email()
    date_joined = FACTORY.date_time()
    last_login = FACTORY.date_time()
    is_superuser = False
    is_staff = False
    is_active = FACTORY.pybool()
    password = PreSave(set_password, password="test1234")
    group = PostSave(add_to_group, name="Test group")

    class Meta:
        model = User
        get_or_create = ("username",)

    @trait
    def is_admin_user(self, instance: User) -> None:
        """Trait."""
        instance.is_superuser = True
        instance.is_staff = True
        instance.is_active = True
```

And this is how you could use it:

<!-- continue: test_factories -->
<!-- pytestmark: django_db -->
```python
# Create just one user
user = UserFactory()

# Create 5 users
users = UserFactory.create_batch(5)

# Create a user using `is_admin_user` trait
user = UserFactory(is_admin_user=True)

# Create a user with custom password
user = UserFactory(
    password=PreSave(set_password, password="another-password"),
)

# Add a user to another group
user = UserFactory(
    group=PostSave(add_to_group, name="Another group"),
)

# Or even add user to multiple groups at once
user = UserFactory(
    group_1=PostSave(add_to_group, name="Another group"),
    group_2=PostSave(add_to_group, name="Yet another group"),
)
```

### Customise

Make your own custom providers and utilize factories with them.

*Filename: custom_fake.py*

```python
import random
import string

from fake import Faker, Factory, provider


class CustomFaker(Faker):

    @provider
    def postal_code(self) -> str:
        number_part = "".join(random.choices(string.digits, k=4))
        letter_part = "".join(random.choices(string.ascii_uppercase, k=2))
        return f"{number_part} {letter_part}"


FAKER = CustomFaker()
FACTORY = Factory(FAKER)
```

Now you can use it as follows (make sure to import your custom instances
of `FAKER` and `FACTORY`):

```python
from custom_fake import FAKER  # Custom `FAKER` instance

FAKER.postal_code()
```

Or as follows:

```python
from fake import ModelFactory

from custom_fake import FACTORY  # Custom `FACTORY` instance


class AddressFactory(ModelFactory):

    # ... other definitions
    postal_code = FACTORY.postal_code()
    # ... other definitions

    class Meta:
        model = Address
```

## Tests

Run the tests with unittest:

```sh
python -m unittest fake.py
```

Or pytest:

```sh
pytest
```

## Differences with alternatives

[fake.py](https://github.com/barseghyanartur/fake.py/) is [Faker](https://faker.readthedocs.io/) + [factory_boy](https://factoryboy.readthedocs.io/) + [faker-file](https://faker-file.readthedocs.io/) in one package,
radically simplified and reduced in features, but without any external
dependencies (not even [Pillow](https://python-pillow.org/) or [dateutil](https://dateutil.readthedocs.io/)).

[fake.py](https://github.com/barseghyanartur/fake.py/) is modelled after the famous [Faker](https://faker.readthedocs.io/) package. Its API is highly
compatible, although drastically reduced. It’s not multilingual and does not
support postal codes or that many raw file formats. However, you could easily
include it in your production setup without worrying about yet another
dependency.

On the other hand, [fake.py](https://github.com/barseghyanartur/fake.py/) factories look quite similar to [factory_boy](https://factoryboy.readthedocs.io/)
factories, although again - drastically simplified and reduced in
features.

The file generation part of [fake.py](https://github.com/barseghyanartur/fake.py/) is modelled after the [faker-file](https://faker-file.readthedocs.io/).
You don’t get a large variety of file types supported and you don’t have that
much control over the content of the files generated, but you get
dependency-free valid files and if that’s all you need, you don’t need to look
further.

However, at any point, if you discover that you “need more”, go for [Faker](https://faker.readthedocs.io/),
[factory_boy](https://factoryboy.readthedocs.io/) and [faker-file](https://faker-file.readthedocs.io/) combination.

## Benchmarks

See [fake-py-benchmarks](https://github.com/barseghyanartur/fake-py-benchmarks) for the details.

## Related projects

- [fake-py-pathy-storage](https://github.com/barseghyanartur/fake-py-pathy-storage): [Pathy](https://github.com/justindujardin/pathy) backed cloud storages for [fake.py](https://github.com/barseghyanartur/fake.py/).
  Supports AWS S3, Google Cloud Storage and Azure Cloud Storage.
- [fake-py-django-storage](https://github.com/barseghyanartur/fake-py-django-storage): [Django](https://www.djangoproject.com/) and [django-storages](https://django-storages.readthedocs.io) backed storages
  for [fake.py](https://github.com/barseghyanartur/fake.py/). Among others, supports AWS S3, Google Cloud Storage and
  Azure Cloud Storage.
- [fake-py-qt](https://github.com/barseghyanartur/fake-py-qt): Graphical user interface to [fake.py](https://github.com/barseghyanartur/fake.py/).
- [fake-py-mcp](https://github.com/barseghyanartur/fake-py-mcp): MCP interface to [fake.py](https://github.com/barseghyanartur/fake.py/) fake-data methods.
- [fake-py-wasm](https://github.com/barseghyanartur/fake-py-wasm): [fake.py](https://github.com/barseghyanartur/fake.py/) on WASM (web assembly).

## Writing documentation

### Section headings

Keep the following hierarchy.

```text
=====
title
=====

header
======

sub-header
----------

sub-sub-header
~~~~~~~~~~~~~~

sub-sub-sub-header
^^^^^^^^^^^^^^^^^^

sub-sub-sub-sub-header
++++++++++++++++++++++

sub-sub-sub-sub-sub-header
**************************
```

### Quality

Documentation is built using [Sphinx](https://www.sphinx-doc.org) and enhanced with the following
specialised tools to ensure a clean, interactive, and fully tested developer
experience:

- [jsphinx](http://jsphinx.readthedocs.io): Provides interactive UI components, including **expandable and
  collapsible code snippets**, allowing for detailed examples without
  cluttering the page.
- [sphinx-no-pragma](http://sphinx-no-pragma.readthedocs.io): A focused extension that **strips pragma comments**
  (like `# noqa` or `# type: ignore`) from the generated documentation,
  keeping the focus entirely on the logic.
- [pytest-codeblock](http://pytest-codeblock.readthedocs.io): For **testing the documentation code snippets**
  (e.g. README.rst, AGENTS.md) `.rst` and `.md` files, ensuring that
  every example remains functional as the codebase evolves.

## License

MIT

## Support

For security issues contact me at the e-mail given in the [Author]() section.

For overall issues, go to [GitHub](https://github.com/barseghyanartur/fake.py/issues).

## Author

Artur Barseghyan <[artur.barseghyan@gmail.com](mailto:artur.barseghyan@gmail.com)>

## Project documentation

Contents:

> ##### Table of Contents
> 
> * [fake.py](#fake-py)
>   * [Features](#features)
>   * [Prerequisites](#prerequisites)
>   * [Installation](#installation)
>     * [pip](#pip)
>     * [Download and copy](#download-and-copy)
>   * [Documentation](#documentation)
>   * [Usage](#usage)
>     * [Generate data](#generate-data)
>       * [Person names](#person-names)
>       * [Random texts](#random-texts)
>       * [Internet](#internet)
>       * [Filenames](#filenames)
>       * [Primitive data types](#primitive-data-types)
>       * [Dates](#dates)
>       * [Geographic data](#geographic-data)
>       * [Books](#books)
>       * [Banking](#banking)
>     * [Generate files](#generate-files)
>       * [As bytes](#as-bytes)
>       * [As files on the file system](#as-files-on-the-file-system)
>     * [Factories/dynamic fixtures](#factories-dynamic-fixtures)
>     * [Customise](#customise)
>   * [Tests](#tests)
>   * [Differences with alternatives](#differences-with-alternatives)
>   * [Benchmarks](#benchmarks)
>   * [Related projects](#related-projects)
>   * [Writing documentation](#writing-documentation)
>     * [Section headings](#section-headings)
>     * [Quality](#quality)
>   * [License](#license)
>   * [Support](#support)
>   * [Author](#author)
>   * [Project documentation](#project-documentation)

* [Recipes](recipes.txt)
  * [Imports and initialization](recipes.txt#imports-and-initialization)
  * [Providers](recipes.txt#providers)
* [Cheat sheet](cheatsheet.txt)
  * [Scientific content](cheatsheet.txt#scientific-content)
* [Creating files](creating_files.txt)
  * [Basics](creating_files.txt#basics)
  * [Clean up files](creating_files.txt#clean-up-files)
* [Creating images](creating_images.txt)
  * [Supported image formats](creating_images.txt#supported-image-formats)
  * [Generating images as bytes](creating_images.txt#generating-images-as-bytes)
  * [Generating files](creating_images.txt#generating-files)
* [Creating PDF](creating_pdf.txt)
  * [Building PDF with text](creating_pdf.txt#building-pdf-with-text)
  * [Building PDF with graphics](creating_pdf.txt#building-pdf-with-graphics)
* [Creating DOCX](creating_docx.txt)
  * [If you need bytes](creating_docx.txt#if-you-need-bytes)
  * [If you need files](creating_docx.txt#if-you-need-files)
* [Creating ODT](creating_odt.txt)
  * [If you need bytes](creating_odt.txt#if-you-need-bytes)
  * [If you need files](creating_odt.txt#if-you-need-files)
* [Creating archives](creating_archives.txt)
  * [Supported archive formats](creating_archives.txt#supported-archive-formats)
  * [ZIP](creating_archives.txt#zip)
  * [TAR](creating_archives.txt#tar)
  * [EML](creating_archives.txt#eml)
* [Factories](factories.txt)
  * [Django example](factories.txt#django-example)
  * [Pydantic example](factories.txt#pydantic-example)
  * [TortoiseORM example](factories.txt#tortoiseorm-example)
  * [Dataclasses example](factories.txt#dataclasses-example)
  * [SQLAlchemy example](factories.txt#sqlalchemy-example)
  * [SQLModel example](factories.txt#sqlmodel-example)
* [Customisation](customisation.txt)
* [Seed](seed.txt)
  * [When Seeding is useful](seed.txt#when-seeding-is-useful)
  * [Best practice](seed.txt#best-practice)
* [Test/coverage configuration tweaks](test_configuration_tweaks.txt)
* [CLI](cli.txt)
  * [Help](cli.txt#help)
  * [Common commands](cli.txt#common-commands)
  * [Customisation](cli.txt#customisation)
* [Security Policy](security.txt)
  * [Reporting a Vulnerability](security.txt#reporting-a-vulnerability)
  * [Supported Versions](security.txt#supported-versions)
* [Contributor guidelines](contributor_guidelines.txt)
  * [Developer prerequisites](contributor_guidelines.txt#developer-prerequisites)
  * [Code standards](contributor_guidelines.txt#code-standards)
  * [Requirements](contributor_guidelines.txt#requirements)
  * [Virtual environment](contributor_guidelines.txt#virtual-environment)
  * [Documentation](contributor_guidelines.txt#id2)
  * [Testing](contributor_guidelines.txt#id3)
  * [Releasing](contributor_guidelines.txt#releasing)
  * [Pull requests](contributor_guidelines.txt#pull-requests)
  * [GitHub Actions](contributor_guidelines.txt#github-actions)
  * [Questions](contributor_guidelines.txt#questions)
  * [Issues](contributor_guidelines.txt#id4)
* [Contributor Covenant Code of Conduct](code_of_conduct.txt)
  * [Our Pledge](code_of_conduct.txt#our-pledge)
  * [Our Standards](code_of_conduct.txt#our-standards)
  * [Enforcement Responsibilities](code_of_conduct.txt#enforcement-responsibilities)
  * [Scope](code_of_conduct.txt#scope)
  * [Enforcement](code_of_conduct.txt#enforcement)
  * [Enforcement Guidelines](code_of_conduct.txt#enforcement-guidelines)
  * [Attribution](code_of_conduct.txt#attribution)
* [Release history and notes](changelog.txt)
  * [0.13.1](changelog.txt#id1)
  * [0.13](changelog.txt#id2)
  * [0.12.2](changelog.txt#id3)
  * [0.12.1](changelog.txt#id4)
  * [0.12](changelog.txt#id5)
  * [0.11.12](changelog.txt#id6)
  * [0.11.11](changelog.txt#id7)
  * [0.11.10](changelog.txt#id8)
  * [0.11.9](changelog.txt#id9)
  * [0.11.8](changelog.txt#id10)
  * [0.11.7](changelog.txt#id11)
  * [0.11.6](changelog.txt#id12)
  * [0.11.5](changelog.txt#id13)
  * [0.11.4](changelog.txt#id14)
  * [0.11.3](changelog.txt#id15)
  * [0.11.2](changelog.txt#id16)
  * [0.11.1](changelog.txt#id17)
  * [0.11](changelog.txt#id18)
  * [0.10.5](changelog.txt#id19)
  * [0.10.4](changelog.txt#id20)
  * [0.10.3](changelog.txt#id21)
  * [0.10.2](changelog.txt#id22)
  * [0.10.1](changelog.txt#id23)
  * [0.10](changelog.txt#id24)
  * [0.9.9](changelog.txt#id25)
  * [0.9.8](changelog.txt#id26)
  * [0.9.7](changelog.txt#id27)
  * [0.9.6](changelog.txt#id28)
  * [0.9.5](changelog.txt#id29)
  * [0.9.4](changelog.txt#id30)
  * [0.9.3](changelog.txt#id31)
  * [0.9.2](changelog.txt#id32)
  * [0.9.1](changelog.txt#id33)
  * [0.9](changelog.txt#id34)
  * [0.8.4](changelog.txt#id35)
  * [0.8.3](changelog.txt#id36)
  * [0.8.2](changelog.txt#id37)
  * [0.8.1](changelog.txt#id38)
  * [0.8](changelog.txt#id39)
  * [0.7.5](changelog.txt#id40)
  * [0.7.4](changelog.txt#id41)
  * [0.7.3](changelog.txt#id42)
  * [0.7.2](changelog.txt#id43)
  * [0.7.1](changelog.txt#id44)
  * [0.7](changelog.txt#id45)
  * [0.6.9](changelog.txt#id46)
  * [0.6.8](changelog.txt#id47)
  * [0.6.7](changelog.txt#id48)
  * [0.6.6](changelog.txt#id49)
  * [0.6.5](changelog.txt#id50)
  * [0.6.4](changelog.txt#id51)
  * [0.6.3](changelog.txt#id52)
  * [0.6.2](changelog.txt#id53)
  * [0.6.1](changelog.txt#id54)
  * [0.6](changelog.txt#id55)
  * [0.5](changelog.txt#id56)
  * [0.4.1](changelog.txt#id57)
  * [0.4](changelog.txt#id58)
  * [0.3.1](changelog.txt#id59)
  * [0.3](changelog.txt#id60)
  * [0.2](changelog.txt#id61)
  * [0.1.3](changelog.txt#id62)
  * [0.1.2](changelog.txt#id63)
  * [0.1.1](changelog.txt#id64)
  * [0.1](changelog.txt#id65)
* [Package](package.txt)
  * [fake module](fake.txt)
* [Indices and tables](package.txt#indices-and-tables)