==========
faker-file
==========
**Create files with fake data**. In many formats. With no efforts.
.. image:: https://img.shields.io/pypi/v/faker-file.svg
:target: https://pypi.python.org/pypi/faker-file
:alt: PyPI Version
.. image:: https://img.shields.io/pypi/pyversions/faker-file.svg
:target: https://pypi.python.org/pypi/faker-file/
:alt: Supported Python versions
.. image:: https://github.com/barseghyanartur/faker-file/workflows/test/badge.svg?branch=main
:target: https://github.com/barseghyanartur/faker-file/actions
:alt: Build Status
.. image:: https://readthedocs.org/projects/faker-file/badge/?version=latest
:target: http://faker-file.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://img.shields.io/badge/license-MIT-blue.svg
:target: https://github.com/barseghyanartur/faker-file/#License
:alt: MIT
.. image:: https://coveralls.io/repos/github/barseghyanartur/faker-file/badge.svg?branch=main&service=github
:target: https://coveralls.io/github/barseghyanartur/faker-file?branch=main
:alt: Coverage
.. Internal references
.. _faker-file: https://github.com/barseghyanartur/faker-file/
.. _Read the Docs: http://faker-file.readthedocs.io/
.. _Quick start: https://faker-file.readthedocs.io/en/latest/quick_start.html
.. _Recipes: https://faker-file.readthedocs.io/en/latest/recipes.html
.. _Creating PDF: https://faker-file.readthedocs.io/en/latest/creating_pdf.html
.. _Creating DOCX: https://faker-file.readthedocs.io/en/latest/creating_docx.html
.. _Creating ODT: https://faker-file.readthedocs.io/en/latest/creating_odt.html
.. _Creating images: https://faker-file.readthedocs.io/en/latest/creating_images.html
.. _CLI: https://faker-file.readthedocs.io/en/latest/cli.html
.. _Methodology: https://faker-file.readthedocs.io/en/latest/methodology.html
.. _Contributor guidelines: https://faker-file.readthedocs.io/en/latest/contributor_guidelines.html
.. Related projects
.. _faker-file-api: https://github.com/barseghyanartur/faker-file-api
.. _faker-file-ui: https://github.com/barseghyanartur/faker-file-ui
.. _faker-file-wasm: https://github.com/barseghyanartur/faker-file-wasm
.. _faker-file-qt: https://github.com/barseghyanartur/faker-file-qt
.. Demos
.. _REST API demo: https://faker-file-api.onrender.com/docs/
.. _UI frontend demo: https://faker-file-ui.vercel.app/
.. _WASM frontend demo: https://faker-file-wasm.vercel.app/
.. External references
.. _Apache Tika: https://tika.apache.org/
.. _Django: https://www.djangoproject.com/
.. _Faker: https://faker.readthedocs.io/
.. _Jinja2: https://jinja.palletsprojects.com/
.. _Pillow: https://pypi.org/project/Pillow/
.. _PyQT5: https://pypi.org/project/PyQt5/
.. _PyTorch: https://pytorch.org/
.. _WeasyPrint: https://pypi.org/project/weasyprint/
.. _azure-storage-blob: https://pypi.org/project/azure-storage-blob/
.. _boto3: https://pypi.org/project/boto3/
.. _edge-tts: https://pypi.org/project/edge-tts/
.. _factory_boy: https://factoryboy.readthedocs.io/
.. _gTTS: https://gtts.readthedocs.io/
.. _google-cloud-storage: https://pypi.org/project/google-cloud-storage/
.. _imgkit: https://pypi.org/project/imgkit/
.. _nltk: https://www.nltk.org/
.. _nlpaug: https://nlpaug.readthedocs.io/
.. _numpy: https://numpy.org/
.. _odfpy: https://pypi.org/project/odfpy/
.. _openpyxl: https://openpyxl.readthedocs.io/
.. _pandas: https://pandas.pydata.org/
.. _pdf2image: https://pypi.org/project/pdf2image/
.. _paramiko: http://paramiko.org/
.. _pathy: https://pypi.org/project/pathy/
.. _pdfkit: https://pypi.org/project/pdfkit/
.. _poppler: https://poppler.freedesktop.org/
.. _python-docx: https://python-docx.readthedocs.io/
.. _python-pptx: https://python-pptx.readthedocs.io/
.. _reportlab: https://pypi.org/project/reportlab/
.. _tablib: https://tablib.readthedocs.io/
.. _textaugment: https://pypi.org/project/textaugment/
.. _tika: https://pypi.org/project/tika/
.. _transformers: https://pypi.org/project/transformers/
.. _wkhtmltopdf: https://wkhtmltopdf.org/
.. _xml2epub: https://pypi.org/project/xml2epub/
.. Licenses
.. _GPL 2.0: https://opensource.org/license/gpl-2-0/
.. _BSD 3 clause: https://opensource.org/license/bsd-3-clause/
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`-, `Apache 2`-, `GPL` or `HPND` licensed.
All licenses are mentioned below between the brackets.
- Core package requires Python 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`` starting from version 2.2 to 4.2 (although only
maintained versions of Django are currently being tested against).
- ``BMP``, ``GIF`` and ``TIFF`` file support requires either just
`Pillow`_ (`HPND`), or a combination of `WeasyPrint`_ (`BSD`),
`pdf2image`_ (`MIT`), `Pillow`_ (`HPND`) and `poppler`_ (`GPLv2`).
- ``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 either just `Pillow`_ (`HPND`), or a combination of
`imgkit`_ (`MIT`) and `wkhtmltopdf`_ (`LGPLv3`).
- ``MP3`` file support requires `gTTS`_ (`MIT`) or `edge-tts`_ (`GPLv3`).
- ``PDF`` file support requires either `Pillow`_ (`HPND`), or a combination of
`pdfkit`_ (`MIT`) and `wkhtmltopdf`_ (`LGPLv3`), or `reportlab`_ (`BSD`).
- ``PPTX`` file support requires `python-pptx`_ (`MIT`).
- ``ODP`` and ``ODT`` file support requires `odfpy`_ (`Apache 2`).
- ``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`).
- ``SFTPStorage`` storage support requires `paramiko`_ (`LGLPv2.1`).
- ``AugmentFileFromDirProvider`` provider requires either a combination of
`textaugment`_ (`MIT`) and `nltk`_ (`Apache 2`) or a combination of
`nlpaug`_ (`MIT`), `PyTorch`_ (`BSD`), `transformers`_ (`Apache 2`),
`numpy`_ (`BSD`), `pandas`_ (`BSD`), `tika`_ (`Apache 2`) and
`Apache Tika`_ (`Apache 2`).
Documentation
=============
- Documentation is available on `Read the Docs`_.
- For bootstrapping check the `Quick start`_.
- For various ready to use code examples see the `Recipes`_.
- For tips on ``PDF`` creation see `Creating PDF`_.
- For tips on ``DOCX`` creation see `Creating DOCX`_.
- For tips on ``ODT`` creation see `Creating ODT`_.
- For tips on images creation see `Creating images`_.
- For CLI options see the `CLI`_.
- Read the `Methodology`_.
- For guidelines on contributing check the `Contributor guidelines`_.
Online demos and related projects
=================================
Check the demo(s) and related projects below:
- `REST API demo`_ (based on `faker-file-api`_ REST API)
- `UI frontend demo`_ (based on `faker-file-ui`_ UI frontend)
- `WASM frontend demo`_ (based on `faker-file-wasm`_ WASM frontend)
- `faker-file-qt`_ GUI application (based on `PyQT5`_).
Installation
============
Latest stable version from PyPI
-------------------------------
**WIth all dependencies**
.. code-block:: sh
pip install faker-file'[all]'
**Only core**
.. code-block:: sh
pip install faker-file
**With most common dependencies**
*Everything, except ML libraries which are required for data augmentation only*
.. code-block:: sh
pip install faker-file'[common]'
**With DOCX support**
.. code-block:: sh
pip install faker-file'[docx]'
**With EPUB support**
.. code-block:: sh
pip install faker-file'[epub]'
**With images support**
.. code-block:: sh
pip install faker-file'[images]'
**With PDF support**
.. code-block:: sh
pip install faker-file'[pdf]'
**With MP3 support**
.. code-block:: sh
pip install faker-file'[mp3]'
**With XLSX support**
.. code-block:: sh
pip install faker-file'[xlsx]'
**With ODS support**
.. code-block:: sh
pip install faker-file'[ods]'
**With ODT support**
.. code-block:: sh
pip install faker-file'[odt]'
**With data augmentation support**
.. code-block:: sh
pip install faker-file'[data-augmentation]'
**With GoogleCloudStorage support**
.. code-block:: sh
pip install faker-file'[gcs]'
**With AzureCloudStorage support**
.. code-block:: sh
pip install faker-file'[azure]'
**With AWSS3Storage support**
.. code-block:: sh
pip install faker-file'[s3]'
Or development version from GitHub
----------------------------------
.. code-block:: sh
pip install https://github.com/barseghyanartur/faker-file/archive/main.tar.gz
Features
========
Supported file types
--------------------
- ``BIN``
- ``BMP``
- ``CSV``
- ``DOCX``
- ``EML``
- ``EPUB``
- ``ICO``
- ``GIF``
- ``JPEG``
- ``JSON``
- ``MP3``
- ``ODS``
- ``ODT``
- ``ODP``
- ``PDF``
- ``PNG``
- ``RTF``
- ``PPTX``
- ``SVG``
- ``TAR``
- ``TIFF``
- ``TXT``
- ``WEBP``
- ``XLSX``
- ``XML``
- ``ZIP``
For all image formats (``BMP``, ``ICO``, ``GIF``, ``JPEG``, ``PNG``, ``SVG``,
``TIFF`` and ``WEBP``) and ``PDF``, there are both graphic-only and
mixed-content file providers (that also have text-to-image capabilities).
Additional providers
--------------------
- ``AugmentFileFromDirProvider``: Make an augmented copy of randomly picked
file from given directory. The following types are supported : ``DOCX``,
``EML``, ``EPUB``, ``ODT``, ``PDF``, ``RTF`` and ``TXT``.
- ``AugmentRandomImageFromDirProvider``: Augment a random image file from
given directory. The following types are supported : ``BMP``, ``GIF``,
``JPEG``, ``PNG``, ``TIFF`` and ``WEBP``.
- ``AugmentImageFromPathProvider``: Augment an image file from given path.
Supported file types are the same as for
``AugmentRandomImageFromDirProvider`` provider.
- ``GenericFileProvider``: Create files in any format from raw bytes or a
predefined template.
- ``RandomFileFromDirProvider``: Pick a random file from given directory.
- ``FileFromPathProvider``: File from given path.
Supported file storages
-----------------------
- Native file system storage
- AWS S3 storage
- Azure Cloud Storage
- Google Cloud Storage
- SFTP storage
Usage examples
==============
With ``Faker``
--------------
**Recommended way**
.. code-block:: python
:name: test_usage_examples_with_faker_recommended_way
from faker import Faker
# Import the file provider we want to use
from faker_file.providers.txt_file import TxtFileProvider
FAKER = Faker() # Initialise Faker instance
FAKER.add_provider(TxtFileProvider) # Register the TXT file provider
file = FAKER.txt_file() # Generate a TXT file
# Meta-data is stored inside a ``data`` attribute (``dict``).
# The following line would produce something like /tmp/tmp/tmphzzb8mot.txt
print(file.data["filename"])
# The following line would produce a text generated by Faker, used as
# the content of the generated file.
print(file.data["content"])
.. note::
Note, that in this case ``file`` value is a ``StringValue`` instance,
which inherits from ``str`` but contains meta-data such as absolute
path to the generated file, and text used to generate the file, stored
in ``filename`` and ``content`` keys of the ``data`` attribute
respectively. See `Meta-data`_ for more information.
If you just need ``bytes`` back (instead of creating the file), provide
the ``raw=True`` argument (works with all provider classes and inner
functions):
.. container:: jsphinx-toggle-emphasis
.. code-block:: python
:name: test_usage_examples_with_faker_raw_recommended_way
from faker import Faker
from faker_file.providers.txt_file import TxtFileProvider
FAKER = Faker()
FAKER.add_provider(TxtFileProvider)
raw = FAKER.txt_file(raw=True)
.. note::
Note, that in this case ``file`` value is a ``BytesValue`` instance,
which inherits from ``bytes`` but contains meta-data such as absolute
path to the generated file, and text used to generate the file, stored
in ``filename`` and ``content`` keys of the ``data`` attribute
respectively. See `Meta-data`_ for more information.
**But this works too**
.. code-block:: python
:name: test_rst_readme_usage_examples_with_faker_but_this_works_too
from faker import Faker
from faker_file.providers.txt_file import TxtFileProvider
FAKER = Faker()
file = TxtFileProvider(FAKER).txt_file()
If you just need ``bytes`` back:
.. container:: jsphinx-toggle-emphasis
.. code-block:: python
:name: test_rst_readme_usage_examples_with_faker_raw_but_this_works_too
from faker import Faker
from faker_file.providers.txt_file import TxtFileProvider
FAKER = Faker()
raw = TxtFileProvider(FAKER).txt_file(raw=True)
With ``factory_boy``
--------------------
upload/models.py
~~~~~~~~~~~~~~~~
.. code-block:: python
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.
.. code-block:: python
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
Meta-data
=========
The return value of any file provider file generator function is either
``StringValue`` or ``BytesValue``, which inherit from ``str`` and ``bytes``
respectively.
Both ``StringValue`` and ``BytesValue`` instances have a meta data attribute
named ``data`` (type ``dict``). Various file providers use ``data`` to
store meta-data, such as ``filename`` (absolute path to the generated file;
valid for all file providers), or ``content`` (text used when generating the
file; valid for most file providers, except ``FileFromPathProvider``,
``RandomFileFromDirProvider``, ``TarFileProvider`` and ``ZipFileProvider``).
All file providers store an absolute path to the generated file in ``filename``
key of the ``data`` attribute and instance of the storage used in ``storage``
key. See the table below.
+-----------+-----------------------------------------------------------------+
| Key name | File provider |
+===========+=================================================================+
| filename | all |
+-----------+-----------------------------------------------------------------+
| storage | all |
+-----------+-----------------------------------------------------------------+
| content | all except FileFromPathProvider, RandomFileFromDirProvider, |
| | TarFileProvider, ZipFileProvider and all graphic file providers |
| | such as GraphicBmpFileProvider, GraphicGifFileProvider, |
| | GraphicIcoFileProvider, GraphicJpegFileProvider, |
| | GraphicPdfFileProvider, GraphicPngFileProvider, |
| | GraphicTiffFileProvider and GraphicWebpFileProvider |
+-----------+-----------------------------------------------------------------+
| inner | only EmlFileProvider, TarFileProvider and ZipFileProvider |
+-----------+-----------------------------------------------------------------+
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.
- ``SFTPStorage``: Requires `paramiko`_ and related dependencies.
Usage example with storages
---------------------------
`FileSystemStorage` example
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Native file system storage. Does not have dependencies.
- ``root_path``: Path to the root directory. Given the example of Django,
this would be the path to the ``MEDIA_ROOT`` directory. It's important
to know, that ``root_path`` will not be embedded into the string
representation of the file. Only ``rel_path`` will.
- ``rel_path``: Relative path from the root directory. Given the example of
Django, this would be the rest of the path to the file.
.. code-block:: python
:name: test_usage_examples_example_with_storages_filesystemstorage
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``.
.. code-block:: python
:name: test_usage_examples_example_with_storages_pathyfilesystemstorage
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`` and ``boto3``.
.. code-block:: python
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:
.. code-block:: sh
pytest -vrx
Or use tox:
.. code-block:: sh
tox
Or use tox to check specific env:
.. code-block:: sh
tox -e py310-django41
Writing documentation
=====================
Keep the following hierarchy.
.. code-block:: text
=====
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 security issues contact me at the e-mail given in the `Author`_ section.
For overall issues, go to `GitHub <https://github.com/barseghyanartur/faker-file/issues>`_.
Author
======
Artur Barseghyan <artur.barseghyan@gmail.com>
Citation
========
Please, use the following entry when citing `faker-file`_ in your research:
.. code-block:: latex
@software{faker-file,
author = {Artur Barseghyan},
title = {faker-file: Create files with fake data. In many formats. With no efforts.},
year = {2022-2024},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {https://github.com/barseghyanartur/faker-file},
}
Raw data
{
"_id": null,
"home_page": "https://github.com/barseghyanartur/faker-file/",
"name": "faker-file",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "factories, fake file, fake files, fake-file-generator, fake-files-generator, faker, faker-file, file-generator, files, files-generator, test file, test files, test-file-generator, test-files-generator, testing",
"author": "Artur Barseghyan",
"author_email": "artur.barseghyan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/dd/95/2cc9ac2c66dbd6fc94a300a602886074b0aea4c49d19555727dd97006237/faker_file-0.17.14.tar.gz",
"platform": null,
"description": "==========\nfaker-file\n==========\n**Create files with fake data**. In many formats. With no efforts.\n\n.. image:: https://img.shields.io/pypi/v/faker-file.svg\n :target: https://pypi.python.org/pypi/faker-file\n :alt: PyPI Version\n\n.. image:: https://img.shields.io/pypi/pyversions/faker-file.svg\n :target: https://pypi.python.org/pypi/faker-file/\n :alt: Supported Python versions\n\n.. image:: https://github.com/barseghyanartur/faker-file/workflows/test/badge.svg?branch=main\n :target: https://github.com/barseghyanartur/faker-file/actions\n :alt: Build Status\n\n.. image:: https://readthedocs.org/projects/faker-file/badge/?version=latest\n :target: http://faker-file.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://img.shields.io/badge/license-MIT-blue.svg\n :target: https://github.com/barseghyanartur/faker-file/#License\n :alt: MIT\n\n.. image:: https://coveralls.io/repos/github/barseghyanartur/faker-file/badge.svg?branch=main&service=github\n :target: https://coveralls.io/github/barseghyanartur/faker-file?branch=main\n :alt: Coverage\n\n.. Internal references\n\n.. _faker-file: https://github.com/barseghyanartur/faker-file/\n.. _Read the Docs: http://faker-file.readthedocs.io/\n.. _Quick start: https://faker-file.readthedocs.io/en/latest/quick_start.html\n.. _Recipes: https://faker-file.readthedocs.io/en/latest/recipes.html\n.. _Creating PDF: https://faker-file.readthedocs.io/en/latest/creating_pdf.html\n.. _Creating DOCX: https://faker-file.readthedocs.io/en/latest/creating_docx.html\n.. _Creating ODT: https://faker-file.readthedocs.io/en/latest/creating_odt.html\n.. _Creating images: https://faker-file.readthedocs.io/en/latest/creating_images.html\n.. _CLI: https://faker-file.readthedocs.io/en/latest/cli.html\n.. _Methodology: https://faker-file.readthedocs.io/en/latest/methodology.html\n.. _Contributor guidelines: https://faker-file.readthedocs.io/en/latest/contributor_guidelines.html\n\n.. Related projects\n\n.. _faker-file-api: https://github.com/barseghyanartur/faker-file-api\n.. _faker-file-ui: https://github.com/barseghyanartur/faker-file-ui\n.. _faker-file-wasm: https://github.com/barseghyanartur/faker-file-wasm\n.. _faker-file-qt: https://github.com/barseghyanartur/faker-file-qt\n\n.. Demos\n\n.. _REST API demo: https://faker-file-api.onrender.com/docs/\n.. _UI frontend demo: https://faker-file-ui.vercel.app/\n.. _WASM frontend demo: https://faker-file-wasm.vercel.app/\n\n.. External references\n\n.. _Apache Tika: https://tika.apache.org/\n.. _Django: https://www.djangoproject.com/\n.. _Faker: https://faker.readthedocs.io/\n.. _Jinja2: https://jinja.palletsprojects.com/\n.. _Pillow: https://pypi.org/project/Pillow/\n.. _PyQT5: https://pypi.org/project/PyQt5/\n.. _PyTorch: https://pytorch.org/\n.. _WeasyPrint: https://pypi.org/project/weasyprint/\n.. _azure-storage-blob: https://pypi.org/project/azure-storage-blob/\n.. _boto3: https://pypi.org/project/boto3/\n.. _edge-tts: https://pypi.org/project/edge-tts/\n.. _factory_boy: https://factoryboy.readthedocs.io/\n.. _gTTS: https://gtts.readthedocs.io/\n.. _google-cloud-storage: https://pypi.org/project/google-cloud-storage/\n.. _imgkit: https://pypi.org/project/imgkit/\n.. _nltk: https://www.nltk.org/\n.. _nlpaug: https://nlpaug.readthedocs.io/\n.. _numpy: https://numpy.org/\n.. _odfpy: https://pypi.org/project/odfpy/\n.. _openpyxl: https://openpyxl.readthedocs.io/\n.. _pandas: https://pandas.pydata.org/\n.. _pdf2image: https://pypi.org/project/pdf2image/\n.. _paramiko: http://paramiko.org/\n.. _pathy: https://pypi.org/project/pathy/\n.. _pdfkit: https://pypi.org/project/pdfkit/\n.. _poppler: https://poppler.freedesktop.org/\n.. _python-docx: https://python-docx.readthedocs.io/\n.. _python-pptx: https://python-pptx.readthedocs.io/\n.. _reportlab: https://pypi.org/project/reportlab/\n.. _tablib: https://tablib.readthedocs.io/\n.. _textaugment: https://pypi.org/project/textaugment/\n.. _tika: https://pypi.org/project/tika/\n.. _transformers: https://pypi.org/project/transformers/\n.. _wkhtmltopdf: https://wkhtmltopdf.org/\n.. _xml2epub: https://pypi.org/project/xml2epub/\n\n.. Licenses\n\n.. _GPL 2.0: https://opensource.org/license/gpl-2-0/\n.. _BSD 3 clause: https://opensource.org/license/bsd-3-clause/\n\nPrerequisites\n=============\nAll of core dependencies of this package are `MIT` licensed.\nMost of optional dependencies of this package are `MIT` licensed, while\na few are `BSD`-, `Apache 2`-, `GPL` or `HPND` licensed.\n\nAll licenses are mentioned below between the brackets.\n\n- Core package requires Python 3.9, 3.10 or 3.11.\n- `Faker`_ (`MIT`) is the only required dependency.\n- `Django`_ (`BSD`) integration with `factory_boy`_ (`MIT`) has\n been tested with ``Django`` starting from version 2.2 to 4.2 (although only\n maintained versions of Django are currently being tested against).\n- ``BMP``, ``GIF`` and ``TIFF`` file support requires either just\n `Pillow`_ (`HPND`), or a combination of `WeasyPrint`_ (`BSD`),\n `pdf2image`_ (`MIT`), `Pillow`_ (`HPND`) and `poppler`_ (`GPLv2`).\n- ``DOCX`` file support requires `python-docx`_ (`MIT`).\n- ``EPUB`` file support requires `xml2epub`_ (`MIT`) and `Jinja2`_ (`BSD`).\n- ``ICO``, ``JPEG``, ``PNG``, ``SVG`` and ``WEBP`` files support\n requires either just `Pillow`_ (`HPND`), or a combination of\n `imgkit`_ (`MIT`) and `wkhtmltopdf`_ (`LGPLv3`).\n- ``MP3`` file support requires `gTTS`_ (`MIT`) or `edge-tts`_ (`GPLv3`).\n- ``PDF`` file support requires either `Pillow`_ (`HPND`), or a combination of\n `pdfkit`_ (`MIT`) and `wkhtmltopdf`_ (`LGPLv3`), or `reportlab`_ (`BSD`).\n- ``PPTX`` file support requires `python-pptx`_ (`MIT`).\n- ``ODP`` and ``ODT`` file support requires `odfpy`_ (`Apache 2`).\n- ``ODS`` file support requires `tablib`_ (`MIT`) and `odfpy`_ (`Apache 2`).\n- ``XLSX`` file support requires `tablib`_ (`MIT`) and `openpyxl`_ (`MIT`).\n- ``PathyFileSystemStorage`` storage support requires `pathy`_ (`Apache 2`).\n- ``AWSS3Storage`` storage support requires `pathy`_ (`Apache 2`)\n and `boto3`_ (`Apache 2`).\n- ``AzureCloudStorage`` storage support requires `pathy`_ (`Apache 2`)\n and `azure-storage-blob`_ (`MIT`).\n- ``GoogleCloudStorage`` storage support requires `pathy`_ (`Apache 2`)\n and `google-cloud-storage`_ (`Apache 2`).\n- ``SFTPStorage`` storage support requires `paramiko`_ (`LGLPv2.1`).\n- ``AugmentFileFromDirProvider`` provider requires either a combination of\n `textaugment`_ (`MIT`) and `nltk`_ (`Apache 2`) or a combination of\n `nlpaug`_ (`MIT`), `PyTorch`_ (`BSD`), `transformers`_ (`Apache 2`),\n `numpy`_ (`BSD`), `pandas`_ (`BSD`), `tika`_ (`Apache 2`) and\n `Apache Tika`_ (`Apache 2`).\n\nDocumentation\n=============\n- Documentation is available on `Read the Docs`_.\n- For bootstrapping check the `Quick start`_.\n- For various ready to use code examples see the `Recipes`_.\n- For tips on ``PDF`` creation see `Creating PDF`_.\n- For tips on ``DOCX`` creation see `Creating DOCX`_.\n- For tips on ``ODT`` creation see `Creating ODT`_.\n- For tips on images creation see `Creating images`_.\n- For CLI options see the `CLI`_.\n- Read the `Methodology`_.\n- For guidelines on contributing check the `Contributor guidelines`_.\n\nOnline demos and related projects\n=================================\nCheck the demo(s) and related projects below:\n\n- `REST API demo`_ (based on `faker-file-api`_ REST API)\n- `UI frontend demo`_ (based on `faker-file-ui`_ UI frontend)\n- `WASM frontend demo`_ (based on `faker-file-wasm`_ WASM frontend)\n- `faker-file-qt`_ GUI application (based on `PyQT5`_).\n\nInstallation\n============\nLatest stable version from PyPI\n-------------------------------\n**WIth all dependencies**\n\n.. code-block:: sh\n\n pip install faker-file'[all]'\n\n**Only core**\n\n.. code-block:: sh\n\n pip install faker-file\n\n**With most common dependencies**\n\n*Everything, except ML libraries which are required for data augmentation only*\n\n.. code-block:: sh\n\n pip install faker-file'[common]'\n\n**With DOCX support**\n\n.. code-block:: sh\n\n pip install faker-file'[docx]'\n\n**With EPUB support**\n\n.. code-block:: sh\n\n pip install faker-file'[epub]'\n\n**With images support**\n\n.. code-block:: sh\n\n pip install faker-file'[images]'\n\n**With PDF support**\n\n.. code-block:: sh\n\n pip install faker-file'[pdf]'\n\n**With MP3 support**\n\n.. code-block:: sh\n\n pip install faker-file'[mp3]'\n\n**With XLSX support**\n\n.. code-block:: sh\n\n pip install faker-file'[xlsx]'\n\n**With ODS support**\n\n.. code-block:: sh\n\n pip install faker-file'[ods]'\n\n**With ODT support**\n\n.. code-block:: sh\n\n pip install faker-file'[odt]'\n\n**With data augmentation support**\n\n.. code-block:: sh\n\n pip install faker-file'[data-augmentation]'\n\n**With GoogleCloudStorage support**\n\n.. code-block:: sh\n\n pip install faker-file'[gcs]'\n\n**With AzureCloudStorage support**\n\n.. code-block:: sh\n\n pip install faker-file'[azure]'\n\n**With AWSS3Storage support**\n\n.. code-block:: sh\n\n pip install faker-file'[s3]'\n\nOr development version from GitHub\n----------------------------------\n\n.. code-block:: sh\n\n pip install https://github.com/barseghyanartur/faker-file/archive/main.tar.gz\n\nFeatures\n========\n\nSupported file types\n--------------------\n- ``BIN``\n- ``BMP``\n- ``CSV``\n- ``DOCX``\n- ``EML``\n- ``EPUB``\n- ``ICO``\n- ``GIF``\n- ``JPEG``\n- ``JSON``\n- ``MP3``\n- ``ODS``\n- ``ODT``\n- ``ODP``\n- ``PDF``\n- ``PNG``\n- ``RTF``\n- ``PPTX``\n- ``SVG``\n- ``TAR``\n- ``TIFF``\n- ``TXT``\n- ``WEBP``\n- ``XLSX``\n- ``XML``\n- ``ZIP``\n\nFor all image formats (``BMP``, ``ICO``, ``GIF``, ``JPEG``, ``PNG``, ``SVG``,\n``TIFF`` and ``WEBP``) and ``PDF``, there are both graphic-only and\nmixed-content file providers (that also have text-to-image capabilities).\n\nAdditional providers\n--------------------\n- ``AugmentFileFromDirProvider``: Make an augmented copy of randomly picked\n file from given directory. The following types are supported : ``DOCX``,\n ``EML``, ``EPUB``, ``ODT``, ``PDF``, ``RTF`` and ``TXT``.\n- ``AugmentRandomImageFromDirProvider``: Augment a random image file from\n given directory. The following types are supported : ``BMP``, ``GIF``,\n ``JPEG``, ``PNG``, ``TIFF`` and ``WEBP``.\n- ``AugmentImageFromPathProvider``: Augment an image file from given path.\n Supported file types are the same as for\n ``AugmentRandomImageFromDirProvider`` provider.\n- ``GenericFileProvider``: Create files in any format from raw bytes or a\n predefined template.\n- ``RandomFileFromDirProvider``: Pick a random file from given directory.\n- ``FileFromPathProvider``: File from given path.\n\nSupported file storages\n-----------------------\n- Native file system storage\n- AWS S3 storage\n- Azure Cloud Storage\n- Google Cloud Storage\n- SFTP storage\n\nUsage examples\n==============\nWith ``Faker``\n--------------\n**Recommended way**\n\n.. code-block:: python\n :name: test_usage_examples_with_faker_recommended_way\n\n from faker import Faker\n # Import the file provider we want to use\n from faker_file.providers.txt_file import TxtFileProvider\n\n FAKER = Faker() # Initialise Faker instance\n FAKER.add_provider(TxtFileProvider) # Register the TXT file provider\n\n file = FAKER.txt_file() # Generate a TXT file\n\n # Meta-data is stored inside a ``data`` attribute (``dict``).\n # The following line would produce something like /tmp/tmp/tmphzzb8mot.txt\n print(file.data[\"filename\"])\n # The following line would produce a text generated by Faker, used as\n # the content of the generated file.\n print(file.data[\"content\"])\n\n.. note::\n\n Note, that in this case ``file`` value is a ``StringValue`` instance,\n which inherits from ``str`` but contains meta-data such as absolute\n path to the generated file, and text used to generate the file, stored\n in ``filename`` and ``content`` keys of the ``data`` attribute\n respectively. See `Meta-data`_ for more information.\n\nIf you just need ``bytes`` back (instead of creating the file), provide\nthe ``raw=True`` argument (works with all provider classes and inner\nfunctions):\n\n.. container:: jsphinx-toggle-emphasis\n\n .. code-block:: python\n :name: test_usage_examples_with_faker_raw_recommended_way\n \n\n from faker import Faker\n from faker_file.providers.txt_file import TxtFileProvider\n\n FAKER = Faker()\n FAKER.add_provider(TxtFileProvider)\n\n raw = FAKER.txt_file(raw=True)\n\n.. note::\n\n Note, that in this case ``file`` value is a ``BytesValue`` instance,\n which inherits from ``bytes`` but contains meta-data such as absolute\n path to the generated file, and text used to generate the file, stored\n in ``filename`` and ``content`` keys of the ``data`` attribute\n respectively. See `Meta-data`_ for more information.\n\n**But this works too**\n\n.. code-block:: python\n :name: test_rst_readme_usage_examples_with_faker_but_this_works_too\n\n from faker import Faker\n from faker_file.providers.txt_file import TxtFileProvider\n\n FAKER = Faker()\n\n file = TxtFileProvider(FAKER).txt_file()\n\nIf you just need ``bytes`` back:\n\n.. container:: jsphinx-toggle-emphasis\n\n .. code-block:: python\n :name: test_rst_readme_usage_examples_with_faker_raw_but_this_works_too\n \n\n from faker import Faker\n from faker_file.providers.txt_file import TxtFileProvider\n\n FAKER = Faker()\n\n raw = TxtFileProvider(FAKER).txt_file(raw=True)\n\nWith ``factory_boy``\n--------------------\nupload/models.py\n~~~~~~~~~~~~~~~~\n.. code-block:: python\n\n from django.db import models\n\n class Upload(models.Model):\n\n # ...\n file = models.FileField()\n\nupload/factories.py\n~~~~~~~~~~~~~~~~~~~\nNote, that when using ``faker-file`` with ``Django`` and native file system\nstorages, you need to pass your ``MEDIA_ROOT`` setting as ``root_path`` value\nto the chosen file storage as show below.\n\n.. code-block:: python\n\n import factory\n from django.conf import settings\n from factory import Faker\n from factory.django import DjangoModelFactory\n from faker_file.providers.docx_file import DocxFileProvider\n from faker_file.storages.filesystem import FileSystemStorage\n\n from upload.models import Upload\n\n FS_STORAGE = FileSystemStorage(\n root_path=settings.MEDIA_ROOT,\n rel_path=\"tmp\"\n )\n factory.Faker.add_provider(DocxFileProvider)\n\n class UploadFactory(DjangoModelFactory):\n\n # ...\n file = Faker(\"docx_file\", storage=FS_STORAGE)\n\n class Meta:\n model = Upload\n\nMeta-data\n=========\nThe return value of any file provider file generator function is either\n``StringValue`` or ``BytesValue``, which inherit from ``str`` and ``bytes``\nrespectively.\n\nBoth ``StringValue`` and ``BytesValue`` instances have a meta data attribute\nnamed ``data`` (type ``dict``). Various file providers use ``data`` to\nstore meta-data, such as ``filename`` (absolute path to the generated file;\nvalid for all file providers), or ``content`` (text used when generating the\nfile; valid for most file providers, except ``FileFromPathProvider``,\n``RandomFileFromDirProvider``, ``TarFileProvider`` and ``ZipFileProvider``).\n\nAll file providers store an absolute path to the generated file in ``filename``\nkey of the ``data`` attribute and instance of the storage used in ``storage``\nkey. See the table below.\n\n+-----------+-----------------------------------------------------------------+\n| Key name | File provider |\n+===========+=================================================================+\n| filename | all |\n+-----------+-----------------------------------------------------------------+\n| storage | all |\n+-----------+-----------------------------------------------------------------+\n| content | all except FileFromPathProvider, RandomFileFromDirProvider, |\n| | TarFileProvider, ZipFileProvider and all graphic file providers |\n| | such as GraphicBmpFileProvider, GraphicGifFileProvider, |\n| | GraphicIcoFileProvider, GraphicJpegFileProvider, |\n| | GraphicPdfFileProvider, GraphicPngFileProvider, |\n| | GraphicTiffFileProvider and GraphicWebpFileProvider |\n+-----------+-----------------------------------------------------------------+\n| inner | only EmlFileProvider, TarFileProvider and ZipFileProvider |\n+-----------+-----------------------------------------------------------------+\n\nFile storages\n=============\nAll file operations are delegated to a separate abstraction layer of storages.\n\nThe following storages are implemented:\n\n- ``FileSystemStorage``: Does not have additional requirements.\n- ``PathyFileSystemStorage``: Requires `pathy`_.\n- ``AzureCloudStorage``: Requires `pathy`_ and `Azure` related dependencies.\n- ``GoogleCloudStorage``: Requires `pathy`_ and `Google Cloud` related\n dependencies.\n- ``AWSS3Storage``: Requires `pathy`_ and `AWS S3` related dependencies.\n- ``SFTPStorage``: Requires `paramiko`_ and related dependencies.\n\nUsage example with storages\n---------------------------\n`FileSystemStorage` example\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\nNative file system storage. Does not have dependencies.\n\n- ``root_path``: Path to the root directory. Given the example of Django,\n this would be the path to the ``MEDIA_ROOT`` directory. It's important\n to know, that ``root_path`` will not be embedded into the string\n representation of the file. Only ``rel_path`` will.\n- ``rel_path``: Relative path from the root directory. Given the example of\n Django, this would be the rest of the path to the file.\n\n.. code-block:: python\n :name: test_usage_examples_example_with_storages_filesystemstorage\n\n import tempfile\n from faker import Faker\n from faker_file.providers.txt_file import TxtFileProvider\n from faker_file.storages.filesystem import FileSystemStorage\n\n FS_STORAGE = FileSystemStorage(\n root_path=tempfile.gettempdir(), # Use settings.MEDIA_ROOT for Django\n rel_path=\"tmp\",\n )\n\n FAKER = Faker()\n\n file = TxtFileProvider(FAKER).txt_file(storage=FS_STORAGE)\n\n FS_STORAGE.exists(file)\n\n`PathyFileSystemStorage` example\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nNative file system storage. Requires ``pathy``.\n\n.. code-block:: python\n :name: test_usage_examples_example_with_storages_pathyfilesystemstorage\n\n import tempfile\n from pathy import use_fs\n from faker import Faker\n from faker_file.providers.txt_file import TxtFileProvider\n from faker_file.storages.cloud import PathyFileSystemStorage\n\n use_fs(tempfile.gettempdir())\n PATHY_FS_STORAGE = PathyFileSystemStorage(\n bucket_name=\"bucket_name\",\n root_path=\"tmp\",\n rel_path=\"sub-tmp\",\n )\n\n FAKER = Faker()\n\n file = TxtFileProvider(FAKER).txt_file(storage=PATHY_FS_STORAGE)\n\n PATHY_FS_STORAGE.exists(file)\n\n`AWSS3Storage` example\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nAWS S3 storage. Requires ``pathy`` and ``boto3``.\n\n.. code-block:: python\n\n from faker import Faker\n from faker_file.providers.txt_file import TxtFileProvider\n from faker_file.storages.aws_s3 import AWSS3Storage\n\n S3_STORAGE = AWSS3Storage(\n bucket_name=\"bucket_name\",\n root_path=\"tmp\", # Optional\n rel_path=\"sub-tmp\", # Optional\n # Credentials are optional too. If your AWS credentials are properly\n # set in the ~/.aws/credentials, you don't need to send them\n # explicitly.\n credentials={\n \"key_id\": \"YOUR KEY ID\",\n \"key_secret\": \"YOUR KEY SECRET\"\n },\n )\n\n FAKER = Faker()\n\n file = TxtFileProvider(FAKER).txt_file(storage=S3_STORAGE)\n\n S3_STORAGE.exists(file)\n\nTesting\n=======\nSimply type:\n\n.. code-block:: sh\n\n pytest -vrx\n\nOr use tox:\n\n.. code-block:: sh\n\n tox\n\nOr use tox to check specific env:\n\n.. code-block:: sh\n\n tox -e py310-django41\n\nWriting documentation\n=====================\n\nKeep the following hierarchy.\n\n.. code-block:: text\n\n =====\n title\n =====\n\n header\n ======\n\n sub-header\n ----------\n\n sub-sub-header\n ~~~~~~~~~~~~~~\n\n sub-sub-sub-header\n ^^^^^^^^^^^^^^^^^^\n\n sub-sub-sub-sub-header\n ++++++++++++++++++++++\n\n sub-sub-sub-sub-sub-header\n **************************\n\nLicense\n=======\nMIT\n\nSupport\n=======\nFor security issues contact me at the e-mail given in the `Author`_ section.\n\nFor overall issues, go to `GitHub <https://github.com/barseghyanartur/faker-file/issues>`_.\n\nAuthor\n======\nArtur Barseghyan <artur.barseghyan@gmail.com>\n\nCitation\n========\nPlease, use the following entry when citing `faker-file`_ in your research:\n\n.. code-block:: latex\n\n @software{faker-file,\n author = {Artur Barseghyan},\n title = {faker-file: Create files with fake data. In many formats. With no efforts.},\n year = {2022-2024},\n publisher = {GitHub},\n journal = {GitHub repository},\n howpublished = {https://github.com/barseghyanartur/faker-file},\n }\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate files with fake data.",
"version": "0.17.14",
"project_urls": {
"Bug Tracker": "https://github.com/barseghyanartur/faker-file/issues",
"Changelog": "https://faker-file.readthedocs.io/en/latest/changelog.html",
"Documentation": "https://faker-file.readthedocs.io/",
"Homepage": "https://github.com/barseghyanartur/faker-file/",
"Source Code": "https://github.com/barseghyanartur/faker-file"
},
"split_keywords": [
"factories",
" fake file",
" fake files",
" fake-file-generator",
" fake-files-generator",
" faker",
" faker-file",
" file-generator",
" files",
" files-generator",
" test file",
" test files",
" test-file-generator",
" test-files-generator",
" testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "134860bd940ee7ccd69c40ca4c4cb1c65741a39716dd399183c18b5ea9b7f8f8",
"md5": "3ad9a521d38ac465f735fd40bdae6dde",
"sha256": "430222f89818e1f034dc0876542ea52a420a6c288cefd0a13b54193e0b8cdcbf"
},
"downloads": -1,
"filename": "faker_file-0.17.14-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "3ad9a521d38ac465f735fd40bdae6dde",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.9",
"size": 168157,
"upload_time": "2024-11-15T00:11:36",
"upload_time_iso_8601": "2024-11-15T00:11:36.412572Z",
"url": "https://files.pythonhosted.org/packages/13/48/60bd940ee7ccd69c40ca4c4cb1c65741a39716dd399183c18b5ea9b7f8f8/faker_file-0.17.14-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dd952cc9ac2c66dbd6fc94a300a602886074b0aea4c49d19555727dd97006237",
"md5": "7955498dd1be156c5612b037b511b033",
"sha256": "8c1d6e484ae4b31950dff4b4abd93f0820e0bedddfc56a9bf1c8f41c5acd1301"
},
"downloads": -1,
"filename": "faker_file-0.17.14.tar.gz",
"has_sig": false,
"md5_digest": "7955498dd1be156c5612b037b511b033",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 208401,
"upload_time": "2024-11-15T00:11:39",
"upload_time_iso_8601": "2024-11-15T00:11:39.310984Z",
"url": "https://files.pythonhosted.org/packages/dd/95/2cc9ac2c66dbd6fc94a300a602886074b0aea4c49d19555727dd97006237/faker_file-0.17.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 00:11:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "barseghyanartur",
"github_project": "faker-file",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "faker-file"
}
JSON
