faker-file ¶

Generate files with fake data

Prerequisites ¶

All of core dependencies of this package are MIT licensed. Most of optional dependencies of this package are MIT licensed, while a few are BSD- or Apache 2 licensed. All licenses are mentioned below between the brackets.

Core package requires Python 3.7, 3.8, 3.9, 3.10 or 3.11.
Faker (MIT) is the only required dependency.
Django (BSD) integration with factory_boy (MIT) has been tested with Django 2.2, 3.0, 3.1, 3.2, 4.0 and 4.1.
DOCX file support requires python-docx (MIT).
EPUB file support requires xml2epub (MIT) and jinja2 (BSD).
ICO, JPEG, PNG, SVG and WEBP files support requires imgkit (MIT).
PDF file support requires pdfkit (MIT).
PPTX file support requires python-pptx (MIT).
ODS file support requires tablib (MIT) and odfpy (Apache 2).
XLSX file support requires tablib (MIT) and openpyxl (MIT).
PathyFileSystemStorage storage support requires pathy (Apache 2).
AWSS3Storage storage support requires pathy (Apache 2) and boto3 (Apache 2).
AzureCloudStorage storage support requires pathy (Apache 2) and azure-storage-blob (MIT).
GoogleCloudStorage storage support requires pathy (Apache 2) and google-cloud-storage (Apache 2).

Documentation ¶

Documentation is available on Read the Docs.

Installation ¶

Latest stable version from PyPI ¶

WIth all dependencies

pip install faker-file[all]

Only core

pip install faker-file

With DOCX support

pip install faker-file[docx]

With EPUB support

pip install faker-file[epub]

With images support

pip install faker-file[images]

With XLSX support

pip install faker-file[xlsx]

With ODS support

pip install faker-file[ods]

Or development version from GitHub ¶

pip install https://github.com/barseghyanartur/faker-file/archive/main.tar.gz

Features ¶

Supported file types ¶

BIN
CSV
DOCX
EPUB
ICO
JPEG
ODS
PDF
PNG
RTF
PPTX
SVG
TXT
WEBP
XLSX
ZIP

Additional providers ¶

RandomFileFromDirProvider: Pick a random file from given directory.

Supported file storages ¶

Native file system storage
AWS S3 storage
Azure Cloud Storage
Google Cloud Storage

Usage examples ¶

With `Faker`¶

One way

from faker import Faker
from faker_file.providers.txt_file import TxtFileProvider

FAKER = Faker()

file = TxtFileProvider(FAKER).txt_file()

Or another

from faker import Faker
from faker_file.providers.txt_file import TxtFileProvider

FAKER = Faker()
FAKER.add_provider(TxtFileProvider)

file = FAKER.txt_file()

With `factory_boy`¶

upload/models.py ¶

from django.db import models

class Upload(models.Model):

    # ...
    file = models.FileField()

upload/factories.py ¶

Note, that when using faker-file with Django and native file system storages, you need to pass your MEDIA_ROOT setting as root_path value to the chosen file storage as show below.

import factory
from django.conf import settings
from factory import Faker
from factory.django import DjangoModelFactory
from faker_file.providers.docx_file import DocxFileProvider
from faker_file.storages.filesystem import FileSystemStorage

from upload.models import Upload

FS_STORAGE = FileSystemStorage(
    root_path=settings.MEDIA_ROOT,
    rel_path="tmp"
)
factory.Faker.add_provider(DocxFileProvider)

class UploadFactory(DjangoModelFactory):

    # ...
    file = Faker("docx_file", storage=FS_STORAGE)

    class Meta:
        model = Upload

File storages ¶

All file operations are delegated to a separate abstraction layer of storages.

The following storages are implemented:

FileSystemStorage: Does not have additional requirements.
PathyFileSystemStorage: Requires pathy.
AzureCloudStorage: Requires pathy and Azure related dependencies.
GoogleCloudStorage: Requires pathy and Google Cloud related dependencies.
AWSS3Storage: Requires pathy and AWS S3 related dependencies.

Usage example with storages ¶

FileSystemStorage example ¶

Native file system storage. Does not have dependencies.

import tempfile
from faker import Faker
from faker_file.providers.txt_file import TxtFileProvider
from faker_file.storages.filesystem import FileSystemStorage

FS_STORAGE = FileSystemStorage(
    root_path=tempfile.gettempdir(),  # Use settings.MEDIA_ROOT for Django
    rel_path="tmp",
)

FAKER = Faker()

file = TxtFileProvider(FAKER).txt_file(storage=FS_STORAGE)

FS_STORAGE.exists(file)

PathyFileSystemStorage example ¶

Native file system storage. Requires pathy.

import tempfile
from pathy import use_fs
from faker import Faker
from faker_file.providers.txt_file import TxtFileProvider
from faker_file.storages.cloud import PathyFileSystemStorage

use_fs(tempfile.gettempdir())
PATHY_FS_STORAGE = PathyFileSystemStorage(
    bucket_name="bucket_name",
    root_path="tmp"
    rel_path="sub-tmp",
)

FAKER = Faker()

file = TxtFileProvider(FAKER).txt_file(storage=PATHY_FS_STORAGE)

PATHY_FS_STORAGE.exists(file)

AWSS3Storage example ¶

AWS S3 storage. Requires pathy.

import tempfile
from pathy import use_fs
from faker import Faker
from faker_file.providers.txt_file import TxtFileProvider
from faker_file.storages.aws_s3 import AWSS3Storage

S3_STORAGE = AWSS3Storage(
    bucket_name="bucket_name",
    root_path="tmp",  # Optional
    rel_path="sub-tmp",  # Optional
    # Credentials are optional too. If your AWS credentials are properly
    # set in the ~/.aws/credentials, you don't need to send them
    # explicitly.
    credentials={
        "key_id": "YOUR KEY ID",
        "key_secret": "YOUR KEY SECRET"
    },
)

FAKER = Faker()

file = TxtFileProvider(FAKER).txt_file(storage=S3_STORAGE)

S3_STORAGE.exists(file)

Testing ¶

Simply type:

pytest -vrx

Or use tox:

tox

Or use tox to check specific env:

tox -e py310-django41

Writing documentation ¶

Keep the following hierarchy.

=====
title
=====

header
======

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

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

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

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

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

License ¶

MIT

Support ¶

For any security issues contact me at the e-mail given in the Author section.

For overall issues, go to GitHub.

Author ¶

Artur Barseghyan <artur.barseghyan@gmail.com>

Project documentation ¶

Contents:

Quick start¶

Installation¶

pip install faker-file[all]

Usage¶

With `Faker`¶

Imports and initialization

from faker import Faker
from faker_file.providers.bin_file import BinFileProvider
from faker_file.providers.csv_file import CsvFileProvider
from faker_file.providers.docx_file import DocxFileProvider
from faker_file.providers.epub_file import EpubFileProvider
from faker_file.providers.ico_file import IcoFileProvider
from faker_file.providers.jpeg_file import JpegFileProvider
from faker_file.providers.ods_file import OdsFileProvider
from faker_file.providers.pdf_file import PdfFileProvider
from faker_file.providers.png_file import PngFileProvider
from faker_file.providers.pptx_file import PptxFileProvider
from faker_file.providers.random_file_from_dir import RandomFileFromDirProvider
from faker_file.providers.rtf_file import RtfFileProvider
from faker_file.providers.svg_file import SvgFileProvider
from faker_file.providers.txt_file import TxtFileProvider
from faker_file.providers.webp_file import WebpFileProvider
from faker_file.providers.xlsx_file import XlsxFileProvider
from faker_file.providers.zip_file import ZipFileProvider

FAKER = Faker()
FAKER.add_provider(BinFileProvider)
FAKER.add_provider(CsvFileProvider)
FAKER.add_provider(DocxFileProvider)
FAKER.add_provider(EpubFileProvider)
FAKER.add_provider(IcoFileProvider)
FAKER.add_provider(JpegFileProvider)
FAKER.add_provider(OdsFileProvider)
FAKER.add_provider(PdfFileProvider)
FAKER.add_provider(PngFileProvider)
FAKER.add_provider(PptxFileProvider)
FAKER.add_provider(RandomFileFromDirProvider)
FAKER.add_provider(RtfFileProvider)
FAKER.add_provider(SvgFileProvider)
FAKER.add_provider(TxtFileProvider)
FAKER.add_provider(WebpFileProvider)
FAKER.add_provider(XlsxFileProvider)
FAKER.add_provider(ZipFileProvider)

Usage examples

bin_file = FAKER.bin_file()
csv_file = FAKER.csv_file()
docx_file = FAKER.docx_file()
epub_file = FAKER.epub_file()
ico_file = FAKER.ico_file()
jpeg_file = FAKER.jpeg_file()
ods_file = FAKER.ods_file()
pdf_file = FAKER.pdf_file()
png_file = FAKER.png_file()
pptx_file = FAKER.pptx_file()
rtf_file = FAKER.rtf_file()
svg_file = FAKER.svg_file()
txt_file = FAKER.txt_file()
webp_file = FAKER.webp_file()
xlsx_file = FAKER.xlsx_file()
zip_file = FAKER.zip_file()

With `factory_boy`¶

Imports and initialization

from factory import Faker
from faker_file.providers.bin_file import BinFileProvider
from faker_file.providers.csv_file import CsvFileProvider
from faker_file.providers.docx_file import DocxFileProvider
from faker_file.providers.epub_file import EpubFileProvider
from faker_file.providers.ico_file import IcoFileProvider
from faker_file.providers.jpeg_file import JpegFileProvider
from faker_file.providers.ods_file import OdsFileProvider
from faker_file.providers.pdf_file import PdfFileProvider
from faker_file.providers.png_file import PngFileProvider
from faker_file.providers.pptx_file import PptxFileProvider
from faker_file.providers.random_file_from_dir import RandomFileFromDirProvider
from faker_file.providers.rtf_file import RtfFileProvider
from faker_file.providers.svg_file import SvgFileProvider
from faker_file.providers.txt_file import TxtFileProvider
from faker_file.providers.webp_file import WebpFileProvider
from faker_file.providers.xlsx_file import XlsxFileProvider
from faker_file.providers.zip_file import ZipFileProvider

Faker.add_provider(BinFileProvider)
Faker.add_provider(CsvFileProvider)
Faker.add_provider(DocxFileProvider)
Faker.add_provider(EpubFileProvider)
Faker.add_provider(IcoFileProvider)
Faker.add_provider(JpegFileProvider)
Faker.add_provider(OdsFileProvider)
Faker.add_provider(PdfFileProvider)
Faker.add_provider(PngFileProvider)
Faker.add_provider(PptxFileProvider)
Faker.add_provider(RandomFileFromDirProvider)
Faker.add_provider(RtfFileProvider)
Faker.add_provider(SvgFileProvider)
Faker.add_provider(TxtFileProvider)
Faker.add_provider(WebpFileProvider)
Faker.add_provider(XlsxFileProvider)
Faker.add_provider(ZipFileProvider)

upload/models.py¶

from django.db import models

class Upload(models.Model):
    """Upload model."""

    name = models.CharField(max_length=255, unique=True)
    description = models.TextField(null=True, blank=True)

    # Files
    docx_file = models.FileField(null=True)
    pdf_file = models.FileField(null=True)
    pptx_file = models.FileField(null=True)
    txt_file = models.FileField(null=True)
    zip_file = models.FileField(null=True)

    class Meta:
        verbose_name = "Upload"
        verbose_name_plural = "Upload"

    def __str__(self):
        return self.name

upload/factories.py¶

from django.conf import settings

from factory import Faker
from factory.django import DjangoModelFactory

# Import all providers we want to use
from faker_file.providers.docx_file import DocxFileProvider
from faker_file.providers.pdf_file import PdfFileProvider
from faker_file.providers.pptx_file import PptxFileProvider
from faker_file.providers.txt_file import TxtFileProvider
from faker_file.providers.zip_file import ZipFileProvider

# Import file storage, because we need to customize things in order for it
# to work with Django.
from faker_file.storages.filesystem import FileSystemStorage

from upload.models import Upload

# Add all providers we want to use
Faker.add_provider(DocxFileProvider)
Faker.add_provider(PdfFileProvider)
Faker.add_provider(PptxFileProvider)
Faker.add_provider(TxtFileProvider)
Faker.add_provider(ZipFileProvider)

# Define a file storage.
FS_STORAGE = FileSystemStorage(
    root_path=settings.MEDIA_ROOT,
    rel_path="tmp"
)

class UploadFactory(DjangoModelFactory):
    """Upload factory."""

    name = Faker("text", max_nb_chars=100)
    description = Faker("text", max_nb_chars=1000)

    # Files
    docx_file = Faker("docx_file", storage=FS_STORAGE)
    pdf_file = Faker("pdf_file", storage=FS_STORAGE)
    pptx_file = Faker("pptx_file", storage=FS_STORAGE)
    txt_file = Faker("txt_file", storage=FS_STORAGE)
    zip_file = Faker("zip_file", storage=FS_STORAGE)

    class Meta:
        model = Upload

Recipes¶

When using with `Faker`¶

When using with Faker, there are two ways of using the providers.

Imports and initializations¶

One way

from faker import Faker
from faker_file.providers.bin_file import BinFileProvider
from faker_file.providers.docx_file import DocxFileProvider
from faker_file.providers.pdf_file import PdfFileProvider
from faker_file.providers.pptx_file import PptxFileProvider
from faker_file.providers.txt_file import TxtFileProvider
from faker_file.providers.zip_file import ZipFileProvider

FAKER = Faker()

# Usage example
file = TxtFileProvider(FAKER).txt_file(content="Lorem ipsum")

Or another

from faker import Faker
from faker_file.providers.docx_file import DocxFileProvider
from faker_file.providers.pdf_file import PdfFileProvider
from faker_file.providers.pptx_file import PptxFileProvider
from faker_file.providers.txt_file import TxtFileProvider
from faker_file.providers.zip_file import ZipFileProvider

FAKER = Faker()
FAKER.add_provider(DocxFileProvider)
FAKER.add_provider(PdfFileProvider)
FAKER.add_provider(PptxFileProvider)
FAKER.add_provider(TxtFileProvider)
FAKER.add_provider(ZipFileProvider)

# Usage example
file = FAKER.txt_file(content="Lorem ipsum")

Throughout documentation we will be mixing these approaches.

Create a TXT file with static content¶

Content of the file is Lorem ipsum.

file = TxtFileProvider(FAKER).txt_file(content="Lorem ipsum")

Create a DOCX file with dynamically generated content¶

Content is generated dynamically.
Content is limited to 1024 chars.
Wrap lines after 80 chars.
Prefix the filename with zzz.

file = DocxFileProvider(FAKER).docx_file(
    prefix="zzz",
    max_nb_chars=1_024,
    wrap_chars_after=80,
)

Create a ZIP file consisting of TXT files with static content¶

5 TXT files in the ZIP archive (default value is 5).
Content of all files is Lorem ipsum.

file = ZipFileProvider(FAKER).zip_file(options={"content": "Lorem ipsum"})

Create a ZIP file consisting of 3 DOCX files with dynamically generated content¶

3 DOCX files in the ZIP archive.
Content is generated dynamically.
Content is limited to 1024 chars.
Prefix the filenames in archive with xxx_.
Prefix the filename of the archive itself with zzz.
Inside the ZIP, put all files in directory yyy.

from faker_file.providers.zip_file import create_inner_docx_file
file = ZipFileProvider(FAKER).zip_file(
    prefix="zzz",
    options={
        "count": 3,
        "create_inner_file_func": create_inner_docx_file,
        "create_inner_file_args": {
            "prefix": "xxx_",
            "max_nb_chars": 1_024,
        }
        "directory": "yyy",
    }
)

Create a nested ZIP file¶

Create a ZIP file which contains 5 ZIP files which contain 5 ZIP files which contain 5 DOCX files.

5 ZIP files in the ZIP archive.
Content is generated dynamically.
Prefix the filenames in archive with nested_level_1_.
Prefix the filename of the archive itself with nested_level_0_.
Each of the ZIP files inside the ZIP file in their turn contains 5 other ZIP files, prefixed with nested_level_2_, which in their turn contain 5 DOCX files.

from faker_file.providers.zip_file import create_inner_docx_file, create_inner_zip_file
file = ZipFileProvider(FAKER).zip_file(
    prefix="nested_level_0_",
    options={
        "create_inner_file_func": create_inner_zip_file,
        "create_inner_file_args": {
            "prefix": "nested_level_1_",
            "options": {
                "create_inner_file_func": create_inner_zip_file,
                "create_inner_file_args": {
                    "prefix": "nested_level_2_",
                    "options": {
                        "create_inner_file_func": create_inner_docx_file,
                    }
                },
            }
        },
    }
)

Create a TXT file with static content¶

file = FAKER.txt_file(content="Lorem ipsum dolor sit amet")

Create a DOCX file with dynamically generated content¶

Content is generated dynamically.
Content is limited to 1024 chars.
Wrap lines after 80 chars.
Prefix the filename with zzz.

file = FAKER.docx_file(
    prefix="zzz",
    max_nb_chars=1_024,
    wrap_chars_after=80,
)

Create a PDF file with predefined template containing dynamic fixtures¶

Content template is predefined and contains dynamic fixtures.
Wrap lines after 80 chars.

template = """
{{date}} {{city}}, {{country}}

Hello {{name}},

{{text}} {{text}} {{text}}

{{text}} {{text}} {{text}}

{{text}} {{text}} {{text}}

Address: {{address}}

Best regards,

{{name}}
{{address}}
{{phone_number}}
"""

file = FAKER.pdf_file(content=template, wrap_chars_after=80)

Pick a random file from a directory given¶

Create an exact copy of the randomly picked file under a different name.
Prefix of the destination file would be zzz.
source_dir_path is the absolute path to the directory to pick files from.

from faker_file.providers.random_file_from_dir import (
    RandomFileFromDirProvider,
)

file = RandomFileFromDirProvider(FAKER).random_file_from_dir(
    source_dir_path="/tmp/tmp/",
    prefix="zzz",
)

Generate a file of a certain size¶

The only two file types for which it is easy to foresee the file size are BIN and TXT. Note, that size of BIN files is always exact, while for TXT it is approximate.

BIN¶

file = BinFileProvider(FAKER).bin_file(length=1024**2)  # 1 Mb
file = BinFileProvider(FAKER).bin_file(length=3*1024**2)  # 3 Mb
file = BinFileProvider(FAKER).bin_file(length=10*1024**2)  # 10 Mb

file = BinFileProvider(FAKER).bin_file(length=1024)  # 1 Kb
file = BinFileProvider(FAKER).bin_file(length=3*1024)  # 3 Kb
file = BinFileProvider(FAKER).bin_file(length=10*1024)  # 10 Kb

TXT¶

file = TxtFileProvider(FAKER).txt_file(max_nb_chars=1024**2)  # 1 Mb
file = TxtFileProvider(FAKER).txt_file(max_nb_chars=3*1024**2)  # 3 Mb
file = TxtFileProvider(FAKER).txt_file(max_nb_chars=10*1024**2)  # 10 Mb

file = TxtFileProvider(FAKER).txt_file(max_nb_chars=1024)  # 1 Kb
file = TxtFileProvider(FAKER).txt_file(max_nb_chars=3*1024)  # 3 Kb
file = TxtFileProvider(FAKER).txt_file(max_nb_chars=10*1024)  # 10 Kb

When using with `Django` (and `factory_boy`)¶

When used with Django (to generate fake data with factory_boy factories), the root_path argument of the correspondent file storage shall be provided. Otherwise (although no errors will be triggered) the generated files will reside outside the MEDIA_ROOT directory (by default in /tmp/ on Linux) and further operations with those files through Django will cause SuspiciousOperation exception.

Basic example¶

Imaginary `Django` model¶

from django.db import models

class Upload(models.Model):
    """Upload model."""

    name = models.CharField(max_length=255, unique=True)
    description = models.TextField(null=True, blank=True)

    # Files
    docx_file = models.FileField(null=True)
    pdf_file = models.FileField(null=True)
    pptx_file = models.FileField(null=True)
    txt_file = models.FileField(null=True)
    zip_file = models.FileField(null=True)
    file = models.FileField(null=True)

    class Meta:
        verbose_name = "Upload"
        verbose_name_plural = "Upload"

    def __str__(self):
        return self.name

Correspondent `factory_boy` factory¶

from django.conf import settings

from factory import Faker
from factory.django import DjangoModelFactory

# Import all providers we want to use
from faker_file.providers.docx_file import DocxFileProvider
from faker_file.providers.pdf_file import PdfFileProvider
from faker_file.providers.pptx_file import PptxFileProvider
from faker_file.providers.txt_file import TxtFileProvider
from faker_file.providers.zip_file import ZipFileProvider

# Import file storage, because we need to customize things in order for it
# to work with Django.
from faker_file.storages.filesystem import FileSystemStorage

from upload.models import Upload

# Add all providers we want to use
Faker.add_provider(DocxFileProvider)
Faker.add_provider(PdfFileProvider)
Faker.add_provider(PptxFileProvider)
Faker.add_provider(TxtFileProvider)
Faker.add_provider(ZipFileProvider)

# Define a file storage. When working with Django and FileSystemStorage
# you need to set the value of `root_path` argument to
# `settings.MEDIA_ROOT`.
FS_STORAGE = FileSystemStorage(
    root_path=settings.MEDIA_ROOT,
    rel_path="tmp"
)

class UploadFactory(DjangoModelFactory):
    """Upload factory."""

    name = Faker("text", max_nb_chars=100)
    description = Faker("text", max_nb_chars=1000)

    # Files
    docx_file = Faker("docx_file", storage=FS_STORAGE)
    pdf_file = Faker("pdf_file", storage=FS_STORAGE)
    pptx_file = Faker("pptx_file", storage=FS_STORAGE)
    txt_file = Faker("txt_file", storage=FS_STORAGE)
    zip_file = Faker("zip_file", storage=FS_STORAGE)
    file = Faker("txt_file", storage=FS_STORAGE)

    class Meta:
        model = Upload

Randomize provider choice¶

from random import choice

from factory import LazyAttribute
from faker import Faker as FakerFaker

FAKER = FakerFaker()

PROVIDER_CHOICES = [
    lambda: DocxFileProvider(FAKER).docx_file(storage=FS_STORAGE),
    lambda: PdfFileProvider(FAKER).pdf_file(storage=FS_STORAGE),
    lambda: PptxFileProvider(FAKER).pptx_file(storage=FS_STORAGE),
    lambda: TxtFileProvider(FAKER).txt_file(storage=FS_STORAGE),
    lambda: ZipFileProvider(FAKER).zip_file(storage=FS_STORAGE),
]

def pick_random_provider(*args, **kwargs):
    return choice(PROVIDER_CHOICES)()

class UploadFactory(DjangoModelFactory):
    """Upload factory that randomly picks a file provider."""

    # ...
    file = LazyAttribute(pick_random_provider)
    # ...

Use a different locale¶

from factory import Faker
from factory.django import DjangoModelFactory
from faker_file.providers.ods_file import OdsFileProvider

Faker._DEFAULT_LOCALE = "hy_AM"  # Set locale to Armenian

Faker.add_provider(OdsFileProvider)

class UploadFactory(DjangoModelFactory):
    """Base Upload factory."""

    name = Faker("text", max_nb_chars=100)
    description = Faker("text", max_nb_chars=1000)
    file = Faker("ods_file")

    class Meta:
        """Meta class."""

        model = Upload

Other Django usage examples¶

Faker example with AWS S3 storage

from django.conf import settings
from faker import Faker
from faker_file.providers.pdf_file import PdfFileProvider
from faker_file.storages.aws_s3 import AWSS3Storage

FAKER = Faker()
STORAGE = AWSS3Storage(
    bucket_name=settings.AWS_STORAGE_BUCKET_NAME,
    root_path="",
    rel_path="",
)
FAKER.add_provider(PdfFileProvider)

file = PdfFileProvider(FAKER).pdf_file(storage=STORAGE)

factory-boy example with AWS S3 storage

import factory

from django.conf import settings
from factory import Faker
from factory.django import DjangoModelFactory
from faker_file.storages.aws_s3 import AWSS3Storage

from upload.models import Upload

STORAGE = AWSS3Storage(
    bucket_name=settings.AWS_STORAGE_BUCKET_NAME,
    root_path="",
    rel_path="",
)

Faker.add_provider(PdfFileProvider)

class UploadFactory(DjangoModelFactory):
    name = Faker('word')
    description = Faker('text')
    file = Faker("pdf_file", storage=STORAGE)

    class Meta:
        model = Upload

upload = UploadFactory()

Flexible storage selection

from django.conf import settings
from django.core.files.storage import default_storage
from faker_file.storages.aws_s3 import AWSS3Storage
from faker_file.storages.filesystem import FileSystemStorage
from storages.backends.s3boto3 import S3Boto3Storage

# Faker doesn't know anything about Django. That's why, if we want to
# support remote storages, we need to manually check which file storage
# backend is used. If `Boto3` storage backend (of the `django-storages`
# package) is used we use the correspondent `AWSS3Storage` class of the
# `faker-file`.
# Otherwise, fall back to native file system storage (`FileSystemStorage`)
# of the `faker-file`.
if isinstance(default_storage, S3Boto3Storage):
    STORAGE = AWSS3Storage(
        bucket_name=settings.AWS_STORAGE_BUCKET_NAME,
        credentials={
            "key_id": settings.AWS_ACCESS_KEY_ID,
            "key_secret": settings.AWS_SECRET_ACCESS_KEY,
        },
        rel_path="tmp",
    )
else:
    STORAGE = FileSystemStorage(
        root_path=settings.MEDIA_ROOT,
        rel_path="tmp",
    )

Release history and notes¶

Sequence based identifiers are used for versioning (schema follows below):

major.minor[.revision]

It’s always safe to upgrade within the same minor version (for example, from 0.3 to 0.3.4).
Minor version changes might be backwards incompatible. Read the release notes carefully before upgrading (for example, when upgrading from 0.3.4 to 0.4).
All backwards incompatible changes are mentioned in this document.

0.9.3¶

2023-01-03

Add EpubFileProvider provider.

0.9.2¶

2022-12-23

Add RrfFileProvider.
Added SQLAlchemy factory example.

0.9.1¶

2022-12-19

Fixes in cloud storage.
Documentation fixes.

0.9¶

2022-12-17

Add optional encoding argument to CsvFileProvider and PdfFileProvider providers.
Add root_path argument to cloud storages.
Moved all image related code (IcoFileProvider, JpegFileProvider, PngFileProvider, SvgFileProvider, WebpFileProvider) to ImageMixin. Moved all tabular data related code (OdsFileProvider, XlsxFileProvider) to TabularDataMixin.
Documentation improvements.

0.8¶

2022-12-16

Note, that this release introduces breaking changes!

All file system based operations are moved to a separate abstraction layer of file storages. The following storages have been implemented: FileSystemStorage, PathyFileSystemStorage, AWSS3Storage, GoogleCloudStorage and AzureStorage. The root_path and rel_path params of the providers are deprecated in favour of storages. See the docs more usage examples.

0.7¶

2022-12-12

Added RandomFileFromDirProvider which picks a random file from directory given.
Improved docs.

0.6¶

2022-12-11

Pass optional generator argument to inner functions of the ZipFileProvider.
Added create_inner_zip_file inner function which allows to create nested ZIPs.
Reached test coverage of 100%.

0.5¶

2022-12-10

Note, that this release introduces breaking changes!

Added ODS file support.
Switched to tablib for easy, non-variant support of various formats (XLSX, ODS).
Silence imgkit logging output.

ZipFileProvider allows to pass arbitrary arguments to inner functions. Put all your inner function arguments into a dictionary and pass it in create_inner_file_args key inside options argument. See the example below.

zip_file = ZipFileProvider(None).file(
    prefix="zzz_archive_",
    options={
        "count": 5,
        "create_inner_file_func": create_inner_docx_file,
        "create_inner_file_args": {
            "prefix": "zzz_file_",
            "max_nb_chars": 1_024,
            "content": "{{date}}\r\n{{text}}\r\n{{name}}",
        },
        "directory": "zzz",
    }
)

0.4¶

2022-12-09

Note, that this release introduces breaking changes!

Remove the concept of content generators (and the correspondent content_generator arguments in implemented providers). Instead, allow usage of dynamic fixtures in the provided content argument.
Remove temporary files when creating ZIP archives.
Various improvements and fixes in docs.

0.3¶

2022-12-08

Add support for BIN, CSV and XLSX files.
Better visual representation of generated images and PDFs.

0.2¶

2022-12-07

Added support for ICO, JPEG, PNG, SVG and WEBP files.
Documentation improvements.

0.1¶

2022-12-06

Initial beta release.

Package¶

faker_file package¶

Subpackages¶

faker_file.providers package¶

Subpackages¶

faker_file.providers.mixins package¶

Submodules¶

faker_file.providers.mixins.image_mixin module¶

class faker_file.providers.mixins.image_mixin.ImageMixin[source]¶

Bases: FileMixin

Image mixin.

extension: str¶

formats: List[str]¶

generator: Union[Provider, Faker]¶

numerify: Callable¶

random_element: Callable¶

faker_file.providers.mixins.tablular_data_mixin module¶

class faker_file.providers.mixins.tablular_data_mixin.TabularDataMixin[source]¶

Bases: FileMixin

Tabular data mixin.

extension: str¶

formats: List[str]¶

generator: Union[Provider, Faker]¶

numerify: Callable¶

random_element: Callable¶

Module contents¶

Submodules¶

faker_file.providers.bin_file module¶

class faker_file.providers.bin_file.BinFileProvider(generator: Any)[source]¶

Bases: BaseProvider, FileMixin

BIN file provider.

Usage example:

from faker import Faker from faker_file.providers.bin_file import BinFileProvider

file = BinFileProvider(Faker()).bin_file()

Usage example with options:

file = BinFileProvider(Faker()).bin_file(
prefix=”zzz”, length=1024**2,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = BinFileProvider(Faker()).bin_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, length=1024**2,

)

Usage example with AWS S3 storage:

from faker_file.storages.aws_s3 import AWSS3Storage

file = BinFileProvider(Faker()).bin_file(
storage=AWSS3Storage(bucket_name=”My-test-bucket”), prefix=”zzz”, length=1024**2,

)

bin_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, length: int = 1048576, content: Optional[bytes] = None, **kwargs) → StringValue[source]¶

Generate a CSV file with random text.

Parameters:

storage – Storage class. Defaults to FileSystemStorage.
prefix – File name prefix.
length –
content – File content. If given, used as is.

Returns:

Relative path (from root directory) of the generated file.

extension: str = 'bin'¶

faker_file.providers.csv_file module¶

class faker_file.providers.csv_file.CsvFileProvider(generator: Any)[source]¶

Bases: BaseProvider, FileMixin

CSV file provider.

Usage example:

from faker import Faker from faker_file.providers.csv_file import CsvFileProvider

file = CsvFileProvider(Faker()).csv_file()

Usage example with options:

from faker_file.providers.csv_file import CsvFileProvider

file = CsvFileProvider(Faker()).csv_file(
prefix=”zzz”, num_rows=100, data_columns=(‘{{name}}’, ‘{{sentence}}’, ‘{{address}}’), include_row_ids=True,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = CsvFileProvider(Faker()).csv_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, num_rows=100,

)

csv_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, header: Optional[Sequence[str]] = None, data_columns: Tuple[str, str] = ('{{name}}', '{{address}}'), num_rows: int = 10, include_row_ids: bool = False, content: Optional[str] = None, encoding: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate a CSV file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
header – The header argument expects a list or a tuple of strings that will serve as the header row if supplied.
data_columns – The data_columns argument expects a list or a tuple of string tokens, and these string tokens will be passed to pystr_format() for data generation. Argument Groups are used to pass arguments to the provider methods. Both header and data_columns must be of the same length.
num_rows – The num_rows argument controls how many rows of data to generate, and the include_row_ids argument may be set to True to include a sequential row ID column.
include_row_ids –
content – File content. If given, used as is.
encoding – Encoding.

Returns:

Relative path (from root directory) of the generated file.

extension: str = 'csv'¶

faker_file.providers.docx_file module¶

class faker_file.providers.docx_file.DocxFileProvider(generator: Any)[source]¶

Bases: BaseProvider, FileMixin

DOCX file provider.

Usage example:

from faker import Faker from faker_file.providers.docx_file import DocxFileProvider

file = DocxFileProvider(Faker()).docx_file()

Usage example with options:

file = DocxFileProvider(Faker()).docx_file(
prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = DocxFileProvider(Faker()).docx_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

docx_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, max_nb_chars: int = 10000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate a DOCX file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
max_nb_chars – Max number of chars for the content.
wrap_chars_after – If given, the output string would be separated by line breaks after the given position.
content – File content. Might contain dynamic elements, which are then replaced by correspondent fixtures.

Returns:

Relative path (from root directory) of the generated file.

extension: str = 'docx'¶

faker_file.providers.ico_file module¶

class faker_file.providers.ico_file.IcoFileProvider(generator: Any)[source]¶

Bases: BaseProvider, ImageMixin

ICO file provider.

Usage example:

from faker import Faker from faker_file.providers.png_file import IcoFileProvider

file = IcoFileProvider(Faker()).ico_file()

Usage example with options:

file = IcoFileProvider(Faker()).ico_file(
prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = IcoFileProvider(Faker()).ico_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

extension: str = 'ico'¶

ico_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, max_nb_chars: int = 5000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate an ICO file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
max_nb_chars – Max number of chars for the content.
wrap_chars_after – If given, the output string would be separated by line breaks after the given position.
content – File content. Might contain dynamic elements, which are then replaced by correspondent fixtures.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.jpeg_file module¶

class faker_file.providers.jpeg_file.JpegFileProvider(generator: Any)[source]¶

Bases: BaseProvider, ImageMixin

JPEG file provider.

Usage example:

from faker import Faker from faker_file.providers.jpeg_file import JpegFileProvider

file = JpegFileProvider(None).jpeg_file()

Usage example with options:

file = JpegFileProvider(None).jpeg_file(
prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = JpegFileProvider(Faker()).jpeg_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

extension: str = 'jpg'¶

jpeg_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, max_nb_chars: int = 5000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate a JPEG file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
max_nb_chars – Max number of chars for the content.
wrap_chars_after – If given, the output string would be separated by line breaks after the given position.
content – File content. Might contain dynamic elements, which are then replaced by correspondent fixtures.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.ods_file module¶

class faker_file.providers.ods_file.OdsFileProvider(generator: Any)[source]¶

Bases: BaseProvider, TabularDataMixin

ODS file provider.

Usage example:

from faker import Faker from faker_file.providers.ods_file import OdsFileProvider

file = OdsFileProvider(Faker()).ods_file()

Usage example with options:

from faker import Faker from faker_file.providers.ods_file import OdsFileProvider

file = OdsFileProvider(Faker()).ods_file(
prefix=”zzz”, num_rows=100, data_columns={

“name”: “{{name}}”, “residency”: “{{address}}”,

}, include_row_ids=True,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = OdsFileProvider(Faker()).ods_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, num_rows=100, data_columns={

“name”: “{{name}}”, “residency”: “{{address}}”,

}, include_row_ids=True,

)

extension: str = 'ods'¶

ods_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, data_columns: Optional[Dict[str, str]] = None, num_rows: int = 10, content: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate an ODS file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
data_columns – The data_columns argument expects a list or a tuple of string tokens, and these string tokens will be passed to pystr_format() for data generation. Argument Groups are used to pass arguments to the provider methods. Both header and data_columns must be of the same length.
num_rows – The num_rows argument controls how many rows of data to generate, and the include_row_ids argument may be set to True to include a sequential row ID column.
prefix – File name prefix.
content – List of dicts with content (JSON-like format). If given, used as is.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.pdf_file module¶

class faker_file.providers.pdf_file.PdfFileProvider(generator: Any)[source]¶

Bases: BaseProvider, FileMixin

PDF file provider.

Usage example:

from faker_file.providers.pdf_file import PdfFileProvider

file = PdfFileProvider(None).pdf_file()

Usage example with options:

from faker_file.providers.pdf_file import PdfFileProvider

file = PdfFileProvider(None).pdf_file(
prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = PdfFileProvider(Faker()).pdf_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

extension: str = 'pdf'¶

pdf_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, max_nb_chars: int = 10000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, encoding: Optional[str] = 'utf-8', **kwargs) → StringValue[source]¶

Generate a PDF file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
max_nb_chars – Max number of chars for the content.
wrap_chars_after – If given, the output string would be separated by line breaks after the given position.
content – File content. Might contain dynamic elements, which are then replaced by correspondent fixtures.
encoding – Encoding of the file.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.png_file module¶

class faker_file.providers.png_file.PngFileProvider(generator: Any)[source]¶

Bases: BaseProvider, ImageMixin

PNG file provider.

Usage example:

from faker import Faker from faker_file.providers.png_file import PngFileProvider

file = PngFileProvider(Faker()).png_file()

Usage example with options:

file = PngFileProvider(Faker()).png_file(
prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = PngFileProvider(Faker()).png_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

extension: str = 'png'¶

png_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, max_nb_chars: int = 5000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate a PNG file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
max_nb_chars – Max number of chars for the content.
wrap_chars_after – If given, the output string would be separated by line breaks after the given position.
content – File content. Might contain dynamic elements, which are then replaced by correspondent fixtures.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.pptx_file module¶

class faker_file.providers.pptx_file.PptxFileProvider(generator: Any)[source]¶

Bases: BaseProvider, FileMixin

PPTX file provider.

Usage example:

from faker_file.providers.pptx_file import PptxFileProvider

file = PptxFileProvider(None).pptx_file()

Usage example with options:

from faker_file.providers.pptx_file import PptxFileProvider

file = PptxFileProvider(None).pptx_file(
prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = PptxFileProvider(Faker()).pptx_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

extension: str = 'pptx'¶

pptx_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, max_nb_chars: int = 10000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate a file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
max_nb_chars – Max number of chars for the content.
wrap_chars_after – If given, the output string would be separated by line breaks after the given position.
content – File content. Might contain dynamic elements, which are then replaced by correspondent fixtures.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.random_file_from_dir module¶

class faker_file.providers.random_file_from_dir.RandomFileFromDirProvider(generator: Any)[source]¶

Bases: BaseProvider, FileMixin

Random file from given directory provider.

Usage example:

from faker_file.providers.random_file_from_dir import (
RandomFileFromDirProvider,

)

file = RandomFileFromDirProvider(None).random_file_from_dir(
source_dir_path=”/tmp/tmp/”,

)

Usage example with options:

from faker_file.providers.random_file_from_dir import (
RandomFileFromDirProvider,

)

file = RandomFileFromDirProvider(None).random_file_from_dir(
source_dir_path=”/tmp/tmp/”, prefix=”zzz”,

)

extension: str = ''¶

random_file_from_dir(source_dir_path: str, storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, **kwargs) → StringValue[source]¶

Pick a random file from given directory.

Parameters:

source_dir_path – Source files directory.
root_path – Path of your files root directory (in case of Django it would be settings.MEDIA_ROOT).
rel_path – Relative path (from root directory).
prefix – File name prefix.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.svg_file module¶

class faker_file.providers.svg_file.SvgFileProvider(generator: Any)[source]¶

Bases: BaseProvider, ImageMixin

SVG file provider.

Usage example:

from faker import Faker from faker_file.providers.svg_file import SvgFileProvider

file = SvgFileProvider(Faker()).svg_file()

Usage example with options:

file = SvgFileProvider(Faker()).svg_file(
prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = SvgFileProvider(Faker()).svg_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

extension: str = 'svg'¶

svg_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, max_nb_chars: int = 5000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate an SVG file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
max_nb_chars – Max number of chars for the content.
wrap_chars_after – If given, the output string would be separated by line breaks after the given position.
content – File content. Might contain dynamic elements, which are then replaced by correspondent fixtures.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.txt_file module¶

class faker_file.providers.txt_file.TxtFileProvider(generator: Any)[source]¶

Bases: BaseProvider, FileMixin

TXT file provider.

Usage example:

from faker_file.providers.txt_file import TxtFileProvider

file = TxtFileProvider(None).txt_file()

Usage example with options:

from faker_file.providers.txt_file import TxtFileProvider

file = TxtFileProvider(None).txt_file(
prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = TxtFileProvider(Faker()).txt_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

extension: str = 'txt'¶

txt_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, max_nb_chars: int = 10000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate a TXT file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
max_nb_chars – Max number of chars for the content.
wrap_chars_after – If given, the output string would be separated by line breaks after the given position.
content – File content. Might contain dynamic elements, which are then replaced by correspondent fixtures.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.webp_file module¶

class faker_file.providers.webp_file.WebpFileProvider(generator: Any)[source]¶

Bases: BaseProvider, ImageMixin

WEBP file provider.

Usage example:

from faker import Faker from faker_file.providers.webp_file import WebpFileProvider

file = WebpFileProvider(Faker()).webp_file()

Usage example with options:

file = WebpFileProvider(Faker()).webp_file(
prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = WebpFileProvider(Faker()).webp_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, max_nb_chars=100_000, wrap_chars_after=80,

)

extension: str = 'webp'¶

webp_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, max_nb_chars: int = 5000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate a WEBP file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
max_nb_chars – Max number of chars for the content.
wrap_chars_after – If given, the output string would be separated by line breaks after the given position.
content – File content. Might contain dynamic elements, which are then replaced by correspondent fixtures.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.xlsx_file module¶

class faker_file.providers.xlsx_file.XlsxFileProvider(generator: Any)[source]¶

Bases: BaseProvider, TabularDataMixin

XLSX file provider.

Usage example:

from faker import Faker from faker_file.providers.xlsx_file import XlsxFileProvider

file = XlsxFileProvider(Faker()).xlsx_file()

Usage example with options:

from faker import Faker from faker_file.providers.xlsx_file import XlsxFileProvider

file = XlsxFileProvider(Faker()).xlsx_file(
prefix=”zzz”, num_rows=100, data_columns={

“name”: “{{name}}”, “residency”: “{{address}}”,

}, include_row_ids=True,

)

Usage example with FileSystemStorage storage (for Django):

from django.conf import settings from faker_file.storages.filesystem import FileSystemStorage

file = XlsxFileProvider(Faker()).xlsx_file(

storage=FileSystemStorage(
root_path=settings.MEDIA_ROOT, rel_path=”tmp”,

), prefix=”zzz”, num_rows=100, data_columns={

“name”: “{{name}}”, “residency”: “{{address}}”,

}, include_row_ids=True,

)

extension: str = 'xlsx'¶

xlsx_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, data_columns: Optional[Dict[str, str]] = None, num_rows: int = 10, content: Optional[str] = None, **kwargs) → StringValue[source]¶

Generate a XLSX file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
data_columns – The data_columns argument expects a list or a tuple of string tokens, and these string tokens will be passed to pystr_format() for data generation. Argument Groups are used to pass arguments to the provider methods. Both header and data_columns must be of the same length.
num_rows – The num_rows argument controls how many rows of data to generate, and the include_row_ids argument may be set to True to include a sequential row ID column.
prefix – File name prefix.
content – List of dicts with content (JSON-like format). If given, used as is.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.zip_file module¶

class faker_file.providers.zip_file.ZipFileProvider(generator: Any)[source]¶

Bases: BaseProvider, FileMixin

ZIP file provider.

Usage example:

from faker import Faker from faker_file.providers.zip_file import ZipFileProvider

FAKER = Faker()

file = ZipFileProvider(FAKER).zip_file()

Usage example with options:

from faker_file.providers.zip_file import (
ZipFileProvider, create_inner_docx_file

)

file = ZipFileProvider(FAKER).zip_file(
prefix=”zzz_archive_”, options={

“count”: 5, “create_inner_file_func”: create_inner_docx_file, “create_inner_file_args”: {

“prefix”: “zzz_docx_file_”, “max_nb_chars”: 1_024,

}, “directory”: “zzz”,

}

)

Usage example of nested ZIPs:

file = ZipFileProvider(FAKER).zip_file(

options={
“create_inner_file_func”: create_inner_zip_file, “create_inner_file_args”: {

“options”: {
“create_inner_file_func”: create_inner_docx_file,

}

}

}

)

If you want to see, which files were included inside the zip, check the file.data["files"].

extension: str = 'zip'¶

zip_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, options: Optional[Dict[str, Any]] = None, **kwargs) → StringValue[source]¶

Generate a ZIP file with random text.

Parameters:

storage – Storage. Defaults to FileSystemStorage.
prefix – File name prefix.
options – Options (non-structured) for complex types, such as zip.

Returns:

Relative path (from root directory) of the generated file.

faker_file.providers.zip_file.create_inner_bin_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, length: int = 1048576, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner BIN file.

faker_file.providers.zip_file.create_inner_csv_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, header: Optional[Sequence[str]] = None, data_columns: Tuple[str, str] = ('{{name}}', '{{address}}'), num_rows: int = 10, include_row_ids: bool = False, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner CSV file.

faker_file.providers.zip_file.create_inner_docx_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 10000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner DOCX file.

faker_file.providers.zip_file.create_inner_epub_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 10000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, title: Optional[str] = None, chapter_title: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner EPUB file.

faker_file.providers.zip_file.create_inner_ico_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 5000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner ICO file.

faker_file.providers.zip_file.create_inner_jpeg_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 5000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner JPEG file.

faker_file.providers.zip_file.create_inner_ods_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, data_columns: Optional[Dict[str, str]] = None, num_rows: int = 10, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner ODS file.

faker_file.providers.zip_file.create_inner_pdf_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 10000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner PDF file.

faker_file.providers.zip_file.create_inner_png_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 5000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner PNG file.

faker_file.providers.zip_file.create_inner_pptx_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 10000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner PPTX file.

faker_file.providers.zip_file.create_inner_rtf_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 10000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner RTF file.

faker_file.providers.zip_file.create_inner_svg_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 5000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner SVG file.

faker_file.providers.zip_file.create_inner_txt_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 10000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner TXT file.

faker_file.providers.zip_file.create_inner_webp_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, max_nb_chars: int = 5000, wrap_chars_after: Optional[int] = None, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner WEBP file.

faker_file.providers.zip_file.create_inner_xlsx_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, data_columns: Optional[Dict[str, str]] = None, num_rows: int = 10, content: Optional[str] = None, **kwargs) → StringValue[source]¶: Create inner XLSX file.

faker_file.providers.zip_file.create_inner_zip_file(storage: Optional[BaseStorage] = None, prefix: Optional[str] = None, generator: Optional[Union[Provider, Faker]] = None, options: Optional[Dict[str, Any]] = None, **kwargs) → StringValue[source]¶: Create inner ZIP file.

Module contents¶

faker_file.storages package¶

Submodules¶

faker_file.storages.aws_s3 module¶

class faker_file.storages.aws_s3.AWSS3Storage(bucket_name: str, root_path: Optional[str] = 'tmp', rel_path: Optional[str] = 'tmp', credentials: Optional[Dict[str, Any]] = None, *args, **kwargs)[source]¶

Bases: CloudStorage

AWS S3 Storage.

Usage example:

from faker_file.storages.aws_s3 import AWSS3Storage

s3_storage = AWSS3Storage(
bucket_name=”artur-testing-1”, rel_path=”tmp”,

) file = s3_storage.generate_filename(prefix=”zzz_”, extension=”docx”) s3_storage.write_text(file, “Lorem ipsum”) s3_storage.write_bytes(file, b”Lorem ipsum”)

authenticate(key_id: str, key_secret: str, **kwargs) → None[source]¶: Authenticate to AWS S3.

schema: str = 's3'¶

faker_file.storages.azure_cloud_storage module¶

class faker_file.storages.azure_cloud_storage.AzureCloudStorage(bucket_name: str, root_path: Optional[str] = 'tmp', rel_path: Optional[str] = 'tmp', credentials: Optional[Dict[str, Any]] = None, *args, **kwargs)[source]¶

Bases: CloudStorage

Azure Cloud Storage.

Usage example:

from faker_file.storages.azure_cloud_storage import AzureCloudStorage

azure_storage = AzureCloudStorage(
bucket_name=”artur-testing-1”, rel_path=”tmp”,

) file = azure_storage.generate_filename(prefix=”zzz_”, extension=”docx”) azure_storage.write_text(file, “Lorem ipsum”) azure_storage.write_bytes(file, b”Lorem ipsum”)

authenticate(connection_string: str, **kwargs) → None[source]¶: Authenticate to Azure Cloud Storage.

bucket: Pathy¶

bucket_name: str¶

credentials: Dict[str, str]¶

schema: str = 'azure'¶

faker_file.storages.base module¶

class faker_file.storages.base.BaseStorage(*args, **kwargs)[source]¶

Bases: object

Base storage.

abspath(filename: Any) → str[source]¶: Return absolute path.

exists(filename: Any) → bool[source]¶: Check if file exists.

generate_filename(prefix: str, extension: str) → Any[source]¶: Generate filename.

relpath(filename: Any) → str[source]¶: Return relative path.

write_bytes(filename: Any, data: bytes) → int[source]¶: Write bytes.

write_text(filename: Any, data: str, encoding: Optional[str] = None) → int[source]¶: Write text.

faker_file.storages.cloud module¶

class faker_file.storages.cloud.CloudStorage(bucket_name: str, root_path: Optional[str] = 'tmp', rel_path: Optional[str] = 'tmp', credentials: Optional[Dict[str, Any]] = None, *args, **kwargs)[source]¶

Bases: BaseStorage

Base cloud storage.

abspath(filename: Pathy) → str[source]¶: Return relative path.

authenticate(**kwargs)[source]¶

bucket: Pathy¶

bucket_name: str¶

credentials: Dict[str, str]¶

exists(filename: Union[Pathy, str]) → bool[source]¶: Check if file exists.

generate_filename(prefix: str, extension: str) → Pathy[source]¶: Generate filename.

relpath(filename: Pathy) → str[source]¶: Return relative path.

schema: str = None¶

write_bytes(filename: Pathy, data: bytes) → int[source]¶: Write bytes.

write_text(filename: Pathy, data: str, encoding: Optional[str] = None) → int[source]¶: Write text.

class faker_file.storages.cloud.PathyFileSystemStorage(bucket_name: str, root_path: Optional[str] = 'tmp', rel_path: Optional[str] = 'tmp', credentials: Optional[Dict[str, Any]] = None, *args, **kwargs)[source]¶

Bases: CloudStorage

Pathy FileSystem Storage.

Usage example:

from faker_file.storages.cloud import PathyFileSystemStorage

fs_storage = PathyFileSystemStorage(bucket_name=”artur-testing-1”) file = fs_storage.generate_filename(prefix=”zzz_”, extension=”docx”) fs_storage.write_text(file, “Lorem ipsum”) fs_storage.write_bytes(file, b”Lorem ipsum”)

authenticate(**kwargs) → None[source]¶: Authenticate. Does nothing.

schema: str = 'file'¶

faker_file.storages.filesystem module¶

class faker_file.storages.filesystem.FileSystemStorage(root_path: Optional[str] = '/tmp', rel_path: Optional[str] = 'tmp', *args, **kwargs)[source]¶

Bases: BaseStorage

File storage.

Usage example:

from faker_file.storages.filesystem import FileSystemStorage

storage = FileSystemStorage() file = storage.generate_filename(prefix=”zzz_”, extension=”docx”) storage.write_text(file, “Lorem ipsum”) storage.write_bytes(file, b”Lorem ipsum”)

Initialization with params:

storage = FileSystemStorage()

abspath(filename: str) → str[source]¶: Return absolute path.

exists(filename: str) → bool[source]¶: Write bytes.

generate_filename(prefix: str, extension: str) → str[source]¶: Generate filename.

relpath(filename: str) → str[source]¶: Return relative path.

write_bytes(filename: str, data: bytes) → int[source]¶: Write bytes.

write_text(filename: str, data: str, encoding: Optional[str] = None) → int[source]¶: Write text.

faker_file.storages.google_cloud_storage module¶

class faker_file.storages.google_cloud_storage.GoogleCloudStorage(bucket_name: str, root_path: Optional[str] = 'tmp', rel_path: Optional[str] = 'tmp', credentials: Optional[Dict[str, Any]] = None, *args, **kwargs)[source]¶

Bases: CloudStorage

Google Cloud Storage.

Usage example:

from faker_file.storages.google_cloud_storage import GoogleCloudStorage

gs_storage = GoogleCloudStorage(
bucket_name=”artur-testing-1”, rel_path=”tmp”,

) file = gs_storage.generate_filename(prefix=”zzz_”, extension=”docx”) gs_storage.write_text(file, “Lorem ipsum”) gs_storage.write_bytes(file, b”Lorem ipsum”)

authenticate(json_file_path: str, **kwargs) → None[source]¶: Authenticate to Google Cloud Storage.

bucket: Pathy¶

bucket_name: str¶

credentials: Dict[str, str]¶

schema: str = 'gs'¶

Module contents¶

faker_file.tests package¶

Submodules¶

faker_file.tests.test_django_integration module¶

class faker_file.tests.test_django_integration.DjangoIntegrationTestCase(methodName='runTest')[source]¶

Bases: TestCase

Django integration test case.

FAKER: Faker¶

test_file¶

faker_file.tests.test_providers module¶

class faker_file.tests.test_providers.ProvidersTestCase(methodName='runTest')[source]¶

Bases: TestCase

Providers test case.

FAKER: Faker¶

setUp(*args, **kwargs)[source]¶: Hook method for setting up the test fixture before exercising it.

test_broken_imports¶

test_faker¶

test_standalone_providers¶

test_standalone_providers_allow_failures¶

test_standalone_zip_file¶

test_standalone_zip_file_allow_failures¶

faker_file.tests.test_storages module¶

class faker_file.tests.test_storages.TestStoragesTestCase(methodName='runTest')[source]¶

Bases: TestCase

Test storages.

test_base_storage_exceptions¶

test_cloud_storage_exceptions¶

test_file_system_storage_abspath()[source]¶: Test FileSystemStorage abspath.

test_pathy_file_system_storage_abspath()[source]¶: Test PathyFileSystemStorage abspath.

test_storage¶

test_storage_generate_filename_exceptions¶

test_storage_initialization_exceptions¶

Module contents¶

Submodules¶

faker_file.base module¶

class faker_file.base.FileMixin[source]¶

Bases: object

File mixin.

extension: str¶

formats: List[str]¶

generator: Union[Provider, Faker]¶

numerify: Callable¶

random_element: Callable¶

class faker_file.base.StringValue[source]¶

Bases: str

data: Dict[str, Any] = {}¶

faker_file.constants module¶

faker_file.helpers module¶

faker_file.helpers.wrap_text(text: str, wrap_chars_after: int) → str[source]¶

Quick start¶

Installation¶

Usage¶

With Faker¶

With factory_boy¶

upload/models.py¶

upload/factories.py¶

Recipes¶

When using with Faker¶

Imports and initializations¶

Create a TXT file with static content¶

Create a DOCX file with dynamically generated content¶

Create a ZIP file consisting of TXT files with static content¶

Create a ZIP file consisting of 3 DOCX files with dynamically generated content¶

Create a nested ZIP file¶

Create a TXT file with static content¶

Create a DOCX file with dynamically generated content¶

Create a PDF file with predefined template containing dynamic fixtures¶

Pick a random file from a directory given¶

Generate a file of a certain size¶

BIN¶

TXT¶

When using with Django (and factory_boy)¶

Basic example¶

Imaginary Django model¶

Correspondent factory_boy factory¶

Randomize provider choice¶

Use a different locale¶

Other Django usage examples¶

Release history and notes¶

0.9.3¶

0.9.2¶

0.9.1¶

0.9¶

0.8¶

0.7¶

0.6¶

0.5¶

0.4¶

0.3¶

0.2¶

0.1¶

Package¶

faker_file package¶

Subpackages¶

faker_file.providers package¶

Subpackages¶

faker_file.providers.mixins package¶

Submodules¶

faker_file.providers.mixins.image_mixin module¶

faker_file.providers.mixins.tablular_data_mixin module¶

Module contents¶

Submodules¶

faker_file.providers.bin_file module¶

faker_file.providers.csv_file module¶

faker_file.providers.docx_file module¶

faker_file.providers.ico_file module¶

faker_file.providers.jpeg_file module¶

faker_file.providers.ods_file module¶

faker_file.providers.pdf_file module¶

faker_file.providers.png_file module¶

faker_file.providers.pptx_file module¶

faker_file.providers.random_file_from_dir module¶

faker_file.providers.svg_file module¶

faker_file.providers.txt_file module¶

faker_file.providers.webp_file module¶

faker_file.providers.xlsx_file module¶

faker_file.providers.zip_file module¶

Module contents¶

faker_file.storages package¶

Submodules¶

faker_file.storages.aws_s3 module¶

faker_file.storages.azure_cloud_storage module¶

faker_file.storages.base module¶

faker_file.storages.cloud module¶

faker_file.storages.filesystem module¶

faker_file.storages.google_cloud_storage module¶

Module contents¶

faker_file.tests package¶

Submodules¶

With `Faker`¶

With `factory_boy`¶

When using with `Faker`¶

When using with `Django` (and `factory_boy`)¶

Imaginary `Django` model¶

Correspondent `factory_boy` factory¶