diff --git a/docs/_static/examples/creating_image/png_1.py b/docs/_static/examples/creating_image/png_1.py deleted file mode 100644 index e69de29..0000000 diff --git a/docs/_static/examples/creating_image/png_bytes_1.py b/docs/_static/examples/creating_image/png_bytes_1.py new file mode 100644 index 0000000..3708c30 --- /dev/null +++ b/docs/_static/examples/creating_image/png_bytes_1.py @@ -0,0 +1,3 @@ +from fake import FAKER + +png_bytes = FAKER.png() diff --git a/docs/_static/examples/creating_image/png_bytes_2.py b/docs/_static/examples/creating_image/png_bytes_2.py new file mode 100644 index 0000000..153383c --- /dev/null +++ b/docs/_static/examples/creating_image/png_bytes_2.py @@ -0,0 +1,3 @@ +from fake import FAKER + +png_bytes = FAKER.png(size=(500, 500), color=(127, 127, 127)) diff --git a/docs/_static/examples/creating_image/png_file_1.py b/docs/_static/examples/creating_image/png_file_1.py new file mode 100644 index 0000000..e95f3e1 --- /dev/null +++ b/docs/_static/examples/creating_image/png_file_1.py @@ -0,0 +1,3 @@ +from fake import FAKER + +png_file = FAKER.png_file() diff --git a/docs/_static/examples/creating_image/png_file_2.py b/docs/_static/examples/creating_image/png_file_2.py new file mode 100644 index 0000000..f0b38e7 --- /dev/null +++ b/docs/_static/examples/creating_image/png_file_2.py @@ -0,0 +1,3 @@ +from fake import FAKER + +png_file = FAKER.png_file(size=(500, 500), color=(127, 127, 127)) diff --git a/docs/_static/examples/creating_pdf/graphic_pdf_bytes_1.py b/docs/_static/examples/creating_pdf/graphic_pdf_bytes_1.py new file mode 100644 index 0000000..f4b04e3 --- /dev/null +++ b/docs/_static/examples/creating_pdf/graphic_pdf_bytes_1.py @@ -0,0 +1,3 @@ +from fake import FAKER, GraphicPdfGenerator + +pdf_bytes = FAKER.pdf(generator=GraphicPdfGenerator) diff --git a/docs/_static/examples/creating_pdf/graphic_pdf_bytes_2.py b/docs/_static/examples/creating_pdf/graphic_pdf_bytes_2.py new file mode 100644 index 0000000..5822ec7 --- /dev/null +++ b/docs/_static/examples/creating_pdf/graphic_pdf_bytes_2.py @@ -0,0 +1,3 @@ +from fake import FAKER, GraphicPdfGenerator + +pdf_bytes = FAKER.pdf(nb_pages=100, generator=GraphicPdfGenerator) diff --git a/docs/_static/examples/creating_pdf/graphic_pdf_file_1.py b/docs/_static/examples/creating_pdf/graphic_pdf_file_1.py new file mode 100644 index 0000000..312b236 --- /dev/null +++ b/docs/_static/examples/creating_pdf/graphic_pdf_file_1.py @@ -0,0 +1,3 @@ +from fake import FAKER, GraphicPdfGenerator + +pdf_file = FAKER.pdf_file(generator=GraphicPdfGenerator) diff --git a/docs/_static/examples/creating_pdf/graphic_pdf_file_2.py b/docs/_static/examples/creating_pdf/graphic_pdf_file_2.py new file mode 100644 index 0000000..377e696 --- /dev/null +++ b/docs/_static/examples/creating_pdf/graphic_pdf_file_2.py @@ -0,0 +1,3 @@ +from fake import FAKER, GraphicPdfGenerator + +pdf_file = FAKER.pdf_file(nb_pages=100, generator=GraphicPdfGenerator) diff --git a/docs/_static/examples/creating_pdf/pdf_1.py b/docs/_static/examples/creating_pdf/pdf_1.py deleted file mode 100644 index e69de29..0000000 diff --git a/docs/_static/examples/creating_pdf/text_pdf_bytes_1.py b/docs/_static/examples/creating_pdf/text_pdf_bytes_1.py new file mode 100644 index 0000000..7c2ff75 --- /dev/null +++ b/docs/_static/examples/creating_pdf/text_pdf_bytes_1.py @@ -0,0 +1,3 @@ +from fake import FAKER, TextPdfGenerator + +pdf_bytes = FAKER.pdf(generator=TextPdfGenerator) diff --git a/docs/_static/examples/creating_pdf/text_pdf_bytes_2.py b/docs/_static/examples/creating_pdf/text_pdf_bytes_2.py new file mode 100644 index 0000000..7e032bb --- /dev/null +++ b/docs/_static/examples/creating_pdf/text_pdf_bytes_2.py @@ -0,0 +1,4 @@ +from fake import FAKER, TextPdfGenerator + +texts = FAKER.sentences() +pdf_bytes = FAKER.pdf(texts=texts, generator=TextPdfGenerator) diff --git a/docs/_static/examples/creating_pdf/text_pdf_bytes_3.py b/docs/_static/examples/creating_pdf/text_pdf_bytes_3.py new file mode 100644 index 0000000..c72899d --- /dev/null +++ b/docs/_static/examples/creating_pdf/text_pdf_bytes_3.py @@ -0,0 +1,3 @@ +from fake import FAKER, TextPdfGenerator + +pdf_bytes = FAKER.pdf(nb_pages=100, generator=TextPdfGenerator) diff --git a/docs/_static/examples/creating_pdf/text_pdf_file_1.py b/docs/_static/examples/creating_pdf/text_pdf_file_1.py new file mode 100644 index 0000000..257a39b --- /dev/null +++ b/docs/_static/examples/creating_pdf/text_pdf_file_1.py @@ -0,0 +1,3 @@ +from fake import FAKER, TextPdfGenerator + +pdf_file = FAKER.pdf_file(generator=TextPdfGenerator) diff --git a/docs/_static/examples/creating_pdf/text_pdf_file_2.py b/docs/_static/examples/creating_pdf/text_pdf_file_2.py new file mode 100644 index 0000000..f7b2527 --- /dev/null +++ b/docs/_static/examples/creating_pdf/text_pdf_file_2.py @@ -0,0 +1,4 @@ +from fake import FAKER, TextPdfGenerator + +texts = FAKER.sentences() +pdf_file = FAKER.pdf_file(texts=texts, generator=TextPdfGenerator) diff --git a/docs/_static/examples/creating_pdf/text_pdf_file_3.py b/docs/_static/examples/creating_pdf/text_pdf_file_3.py new file mode 100644 index 0000000..c5dfb5e --- /dev/null +++ b/docs/_static/examples/creating_pdf/text_pdf_file_3.py @@ -0,0 +1,3 @@ +from fake import FAKER, TextPdfGenerator + +pdf_file = FAKER.pdf_file(nb_pages=100, generator=TextPdfGenerator) diff --git a/docs/_static/examples/creating_pdf/text_pdf_file_django_1.py b/docs/_static/examples/creating_pdf/text_pdf_file_django_1.py new file mode 100644 index 0000000..2be1313 --- /dev/null +++ b/docs/_static/examples/creating_pdf/text_pdf_file_django_1.py @@ -0,0 +1,6 @@ +from django.conf import settings +from fake import FAKER, TextPdfGenerator, FileSystemStorage + +STORAGE = FileSystemStorage(root_path=settings.MEDIA_ROOT, rel_path="tmp") + +pdf_file = FAKER.pdf_file(generator=TextPdfGenerator, storage=STORAGE) diff --git a/docs/_static/examples/creating_pdf/text_pdf_file_pydantic_1.py b/docs/_static/examples/creating_pdf/text_pdf_file_pydantic_1.py new file mode 100644 index 0000000..b744521 --- /dev/null +++ b/docs/_static/examples/creating_pdf/text_pdf_file_pydantic_1.py @@ -0,0 +1,9 @@ +from pathlib import Path +from fake import FAKER, TextPdfGenerator, FileSystemStorage + +BASE_DIR = Path(__file__).resolve().parent.parent +MEDIA_ROOT = BASE_DIR / "media" + +STORAGE = FileSystemStorage(root_path=MEDIA_ROOT, rel_path="tmp") + +pdf_file = FAKER.pdf_file(generator=TextPdfGenerator, storage=STORAGE) diff --git a/docs/_static/examples/factories/django_factories_1.py b/docs/_static/examples/factories/django_factories_1.py new file mode 100644 index 0000000..a941d9e --- /dev/null +++ b/docs/_static/examples/factories/django_factories_1.py @@ -0,0 +1,46 @@ +from django.conf import settings +from django.contrib.auth.models import User +from fake import ( + DjangoModelFactory, + Factory, + FileSystemStorage, + SubFactory, + pre_save, +) + +from article.models import Article + +STORAGE = FileSystemStorage(root_path=settings.MEDIA_ROOT, rel_path="tmp") + + +class UserFactory(DjangoModelFactory): + username = Factory.username() + first_name = Factory.first_name() + last_name = Factory.last_name() + email = Factory.email() + last_login = Factory.date_time() + is_superuser = False + is_staff = False + is_active = Factory.pybool() + date_joined = Factory.date_time() + + class Meta: + model = User + + @pre_save + def __set_password(instance): + instance.set_password("test") + + +class ArticleFactory(DjangoModelFactory): + title = Factory.sentence() + slug = Factory.slug() + content = Factory.text() + image = Factory.png_file(storage=STORAGE) + pub_date = Factory.date() + safe_for_work = Factory.pybool() + minutes_to_read = Factory.pyint(min_value=1, max_value=10) + author = SubFactory(UserFactory) + + class Meta: + model = Article diff --git a/docs/_static/examples/factories/django_models_1.py b/docs/_static/examples/factories/django_models_1.py new file mode 100644 index 0000000..2979637 --- /dev/null +++ b/docs/_static/examples/factories/django_models_1.py @@ -0,0 +1,19 @@ +from django.conf import settings +from django.db import models +from django.utils import timezone + + +class Article(models.Model): + title = models.CharField(max_length=255) + slug = models.SlugField(unique=True) + content = models.TextField() + image = models.ImageField(null=True, blank=True) + pub_date = models.DateTimeField(default=timezone.now) + safe_for_work = models.BooleanField(default=False) + minutes_to_read = models.IntegerField(default=5) + author = models.ForeignKey( + settings.AUTH_USER_MODEL, on_delete=models.CASCADE + ) + + def __str__(self): + return self.title diff --git a/docs/_static/examples/factories/pydantic_factories_1.py b/docs/_static/examples/factories/pydantic_factories_1.py new file mode 100644 index 0000000..86311de --- /dev/null +++ b/docs/_static/examples/factories/pydantic_factories_1.py @@ -0,0 +1,41 @@ +from pathlib import Path + +from fake import Factory, FileSystemStorage, ModelFactory, SubFactory + +from article.models import Article, User + +BASE_DIR = Path(__file__).resolve().parent.parent +MEDIA_ROOT = BASE_DIR / "media" + +STORAGE = FileSystemStorage(root_path=MEDIA_ROOT, rel_path="tmp") + + +class UserFactory(ModelFactory): + id = Factory.pyint() + username = Factory.username() + first_name = Factory.first_name() + last_name = Factory.last_name() + email = Factory.email() + last_login = Factory.date_time() + is_superuser = False + is_staff = False + is_active = Factory.pybool() + date_joined = Factory.date_time() + + class Meta: + model = User + + +class ArticleFactory(ModelFactory): + id = Factory.pyint() + title = Factory.sentence() + slug = Factory.slug() + content = Factory.text() + image = Factory.png_file(storage=STORAGE) + pub_date = Factory.date() + safe_for_work = Factory.pybool() + minutes_to_read = Factory.pyint(min_value=1, max_value=10) + author = SubFactory(UserFactory) + + class Meta: + model = Article diff --git a/docs/_static/examples/factories/pydantic_models_1.py b/docs/_static/examples/factories/pydantic_models_1.py new file mode 100644 index 0000000..3d40dbc --- /dev/null +++ b/docs/_static/examples/factories/pydantic_models_1.py @@ -0,0 +1,36 @@ +from datetime import datetime +from typing import Optional + +from pydantic import BaseModel, Field + + +class User(BaseModel): + id: int + username: str = Field(..., max_length=255) + first_name: str = Field(..., max_length=255) + last_name: str = Field(..., max_length=255) + email: str = Field(..., max_length=255) + password: Optional[str] = Field("", max_length=255) + last_login: Optional[datetime] + is_superuser: bool = Field(default=False) + is_staff: bool = Field(default=False) + is_active: bool = Field(default=True) + date_joined: Optional[datetime] + + def __str__(self): + return self.username + + +class Article(BaseModel): + id: int + title: str = Field(..., max_length=255) + slug: str = Field(..., max_length=255, unique=True) + content: str + image: Optional[str] = None # Use str to represent the image path or URL + pub_date: datetime = Field(default_factory=datetime.now) + safe_for_work: bool = False + minutes_to_read: int = 5 + author: User + + def __str__(self): + return self.title diff --git a/docs/_static/examples/factories/tortoise_factories_1.py b/docs/_static/examples/factories/tortoise_factories_1.py new file mode 100644 index 0000000..c6e8d7e --- /dev/null +++ b/docs/_static/examples/factories/tortoise_factories_1.py @@ -0,0 +1,41 @@ +from pathlib import Path + +from fake import Factory, FileSystemStorage, SubFactory, TortoiseModelFactory + +from article.models import Article, User + +BASE_DIR = Path(__file__).resolve().parent.parent +MEDIA_ROOT = BASE_DIR / "media" + +STORAGE = FileSystemStorage(root_path=MEDIA_ROOT, rel_path="tmp") + + +class UserFactory(TortoiseModelFactory): + id = Factory.pyint() + username = Factory.username() + first_name = Factory.first_name() + last_name = Factory.last_name() + email = Factory.email() + last_login = Factory.date_time() + is_superuser = False + is_staff = False + is_active = Factory.pybool() + date_joined = Factory.date_time() + + class Meta: + model = User + + +class ArticleFactory(TortoiseModelFactory): + id = Factory.pyint() + title = Factory.sentence() + slug = Factory.slug() + content = Factory.text() + image = Factory.png_file(storage=STORAGE) + pub_date = Factory.date_time() + safe_for_work = Factory.pybool() + minutes_to_read = Factory.pyint(min_value=1, max_value=10) + author = SubFactory(UserFactory) + + class Meta: + model = Article diff --git a/docs/_static/examples/factories/tortoise_models_1.py b/docs/_static/examples/factories/tortoise_models_1.py new file mode 100644 index 0000000..b61ecaa --- /dev/null +++ b/docs/_static/examples/factories/tortoise_models_1.py @@ -0,0 +1,36 @@ +from datetime import datetime + +from tortoise import fields +from tortoise.models import Model + + +class User(Model): + id = fields.IntField(pk=True) + username = fields.CharField(max_length=255) + first_name = fields.CharField(max_length=255) + last_name = fields.CharField(max_length=255) + email = fields.CharField(max_length=255) + password = fields.CharField(max_length=255, null=True, blank=True) + last_login = fields.DatetimeField(null=True, blank=True) + is_superuser = fields.BooleanField(default=False) + is_staff = fields.BooleanField(default=False) + is_active = fields.BooleanField(default=True) + date_joined = fields.DatetimeField(null=True, blank=True) + + def __str__(self): + return self.title + + +class Article(Model): + id = fields.IntField(pk=True) + title = fields.CharField(max_length=255) + slug = fields.CharField(max_length=255, unique=True) + content = fields.TextField() + image = fields.TextField(null=True, blank=True) + pub_date = fields.DatetimeField(default=datetime.now) + safe_for_work = fields.BooleanField(default=False) + minutes_to_read = fields.IntField(default=5) + author = fields.ForeignKeyField("models.User", on_delete=fields.CASCADE) + + def __str__(self): + return self.title diff --git a/docs/creating_images.rst b/docs/creating_images.rst index b4031a5..bcc2fee 100644 --- a/docs/creating_images.rst +++ b/docs/creating_images.rst @@ -4,62 +4,24 @@ Creating images .. _faker-file: https://pypi.org/project/faker-file/ -.. External references +Creating images could be a challenging task. The goal of this library +is to help you out with basic tasks. You can easily generate very basic +graphic images, but no custom shapes. Paper size is A4. -.. _imgkit: https://pypi.org/project/imgkit/ -.. _Pillow: https://pillow.readthedocs.io/ -.. _WeasyPrint: https://pypi.org/project/weasyprint/ -.. _wkhtmltopdf: https://wkhtmltopdf.org/ +If you don't like how PDF files are generated by this library, you can +check the `faker-file`_ package, which can produce pretty comprehensive PDFs. -Creating images could be a challenging task. System dependencies on one -side, large variety of many image formats on another. - -Underlying creation of image files has been delegated to an abstraction layer -of image generators. If you don't like how image files are generated or format -you need isn't supported, you can create your own layer, using your favourite -library. - -Generally speaking, in `faker-file`_ each file provider represents a certain -file type (with only a few exceptions). For generating a file in PNG format -you should use `PngFileProvider`. For JPEG you would use `JpegFileProvider`. - -Image providers ---------------- -Currently, there are 3 types of image providers implemented: - -- Graphic-only image providers. -- Mixed-content image providers. -- Image augmentation providers. - -The graphic-only image providers are only capable of producing random -graphics. - -The mixed-content image providers can produce an image consisting of -both text and graphics. Moreover, text comes in variety of different -headings (such as h1, h2, h3, etc), paragraphs and tables. - -Image augmentation providers simply augment existing images in a various, -declaratively random, ways, such as: flip, resize, lighten, darken, -grayscale and others. +Supported image formats +----------------------- +Currently, 4 image formats are supported: -Image generators ----------------- -The following image generators are available. - -- ``PilImageGenerator``, built on top of the `Pillow`_. It's the generator - that will likely won't ask for any system dependencies that you don't - yet have installed. -- ``ImgkitImageGenerator`` (default), built on top of the `imgkit`_ - and `wkhtmltopdf`_. Extremely easy to work with. Supports many formats. -- ``WeasyPrintImageGenerator``, built on top of the `WeasyPrint`_. - Easy to work with. Supports formats that `imgkit`_ does not. - -Building mixed-content images using `imgkit`_ ---------------------------------------------- -While `imgkit`_ generator is heavier and has `wkhtmltopdf`_ as a system -dependency, it produces better quality images and has no issues with fonts -or unicode characters. +- ``PNG``. +- ``SVG``. +- ``BMP``. +- ``GIF``. +Generating images as bytes +-------------------------- See the following full functional snippet for generating images using `imgkit`_. .. container:: jsphinx-download @@ -88,7 +50,8 @@ characters (or any other number that fits your needs). See the example below: *See the full example* :download:`here <_static/examples/creating_images/imgkit_2.py>` ----- +Generating files +---------------- To have a longer text, increase the value of ``max_nb_chars`` accordingly. See the example below: @@ -101,145 +64,3 @@ See the example below: *See the full example* :download:`here <_static/examples/creating_images/imgkit_3.py>` - ----- - -As mentioned above, it's possible to diversify the generated context with -images, paragraphs, tables and pretty much everything that you could think of, -although currently only images, paragraphs and tables are supported out of -the box. In order to customise the blocks image file is built from, -the ``DynamicTemplate`` class is used. See the example below for usage -examples: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_images/imgkit_4.py - :language: python - :lines: 2-7, 13- - - *See the full example* - :download:`here <_static/examples/creating_images/imgkit_4.py>` - -Building mixed-content images using `WeasyPrint`_ -------------------------------------------------- -While `WeasyPrint`_ generator isn't better or faster than the `imgkit`_, it -supports formats that `imgkit`_ doesn't (and vice-versa) and therefore is a -good alternative to. - -See the following snippet for generating images using `WeasyPrint`_. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_images/weasyprint_1.py - :language: python - :lines: 2-4, 9- - - *See the full example* - :download:`here <_static/examples/creating_images/weasyprint_1.py>` - ----- - -All examples shown for `imgkit`_ apply for `WeasyPrint`_ generator, however -when building images files from blocks (paragraphs, images and tables), the -imports shall be adjusted: - -As mentioned above, it's possible to diversify the generated context with -images, paragraphs, tables and pretty much everything else that you could -think of, although currently only images, paragraphs and tables are supported. -In order to customise the blocks image file is built from, the -``DynamicTemplate`` class is used. See the example below for usage examples: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_images/weasyprint_2.py - :language: python - :lines: 3-7, 15- - - *See the full example* - :download:`here <_static/examples/creating_images/weasyprint_2.py>` - -Building mixed-content images using `Pillow`_ ---------------------------------------------- -Usage example: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_images/pillow_1.py - :language: python - :lines: 2, 7- - - *See the full example* - :download:`here <_static/examples/creating_images/pillow_1.py>` - ----- - -With options: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_images/pillow_2.py - :language: python - :lines: 8- - - *See the full example* - :download:`here <_static/examples/creating_images/pillow_2.py>` - ----- - -All examples shown for `imgkit`_ and `WeasyPrint`_ apply to `Pillow`_ generator, -however when building image files from blocks (paragraphs, images and tables), -the imports shall be adjusted. See the example below: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_images/pillow_3.py - :language: python - :lines: 3-7, 13- - - *See the full example* - :download:`here <_static/examples/creating_images/pillow_3.py>` - -Creating graphics-only images using `Pillow`_ ---------------------------------------------- -There are so called ``graphic`` image file providers available. Produced image -files would not contain text, so don't use it when you need text based content. -However, sometimes you just need a valid image file, without caring much about -the content. That's where graphic image providers comes to rescue: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_images/pillow_4.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/creating_images/pillow_4.py>` - -The generated file will contain a random graphic (consisting of lines and -shapes of different colours). - ----- - -One of the most useful arguments supported is ``size``. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_images/pillow_5.py - :language: python - :lines: 7- - - *See the full example* - :download:`here <_static/examples/creating_images/pillow_5.py>` - -Augment existing images ------------------------ -Augment the input image with a series of random augmentation methods. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_images/augment_1.py - :language: python - :lines: 2-15, 17, 19-20, 28- - - *See the full example* - :download:`here <_static/examples/creating_images/augment_1.py>` diff --git a/docs/creating_pdf.rst b/docs/creating_pdf.rst index becc3f5..5aa2600 100644 --- a/docs/creating_pdf.rst +++ b/docs/creating_pdf.rst @@ -2,45 +2,30 @@ Creating PDF ============ .. External references -.. _pdfkit: https://pypi.org/project/pdfkit/ -.. _Pillow: https://pillow.readthedocs.io/ -.. _reportlab: https://pypi.org/project/reportlab/ -.. _wkhtmltopdf: https://wkhtmltopdf.org/ +.. _faker-file: https://pypi.org/project/faker-file/ PDF is certainly one of the most complicated formats out there. And certainly one of the formats most of the developers will be having trouble -with, as there are many versions and dialects. That makes it almost impossible -and highly challenging to have **just one right way** of creating PDF files. -That's why, creation of PDF files has been delegated to an abstraction layer -of PDF generators. If you don't like how PDF files are generated, you can -create your own layer, using your favourite library. - -Currently, there are three PDF generators implemented: - -- ``PdfkitPdfGenerator`` (default), built on top of the `pdfkit`_ - and `wkhtmltopdf`_. -- ``ReportlabPdfGenerator``, build on top of the famous `reportlab`_. -- ``PilPdfGenerator``, build on top of the `Pillow`_. Produced PDFs would - contain images only (even texts are stored as images), unlike `pdfkit`_ or - `reportlab`_ based solutions, where PDFs would simply contain selectable - text. However, it's the generator that will likely won't ask for any - system dependencies that you don't yet have installed. - -Building PDF with text using `pdfkit`_ --------------------------------------- -While `pdfkit`_ generator is heavier and has `wkhtmltopdf`_ as a system -dependency, it produces better quality PDFs and has no issues with fonts -or unicode characters. - -See the following full functional snippet for generating PDF using `pdfkit`_. +with, as there are many versions and dialects. + +The goal of this library is to help you out with basic tasks. You can easily +generate PDFs with 100 pages (paper size is A4), having a little text on each. +Or you can generate PDFs with images. Currently, you can't have both at the +same time. + +If you don't like how PDF files are generated by this library, you can +check the `faker-file`_ package, which can produce pretty comprehensive PDFs. + +Building PDF with text +---------------------- .. container:: jsphinx-download - .. literalinclude:: _static/examples/creating_pdf/pdfkit_1.py + .. literalinclude:: _static/examples/creating_pdf/text_pdf_1.py :language: python *See the full example* - :download:`here <_static/examples/creating_pdf/pdfkit_1.py>` + :download:`here <_static/examples/creating_pdf/text_pdf_1.py>` The generated PDF will have 10,000 characters of text, which is about 2 pages. @@ -94,93 +79,6 @@ class is used. See the example below for usage examples: *See the full example* :download:`here <_static/examples/creating_pdf/pdfkit_4.py>` -Building PDFs with text using `reportlab`_ ------------------------------------------- -While `reportlab`_ generator is much lighter than the `pdfkit`_ and does not -have system dependencies, but might produce PDF files with questionable -encoding when generating unicode text. - -See the following full functional snippet for generating PDF using `reportlab`_. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_pdf/reportlab_1.py - :language: python - :lines: 4-7, 11- - - *See the full example* - :download:`here <_static/examples/creating_pdf/reportlab_1.py>` - ----- - -All examples shown for `pdfkit`_ apply for `reportlab`_ generator, however -when building PDF files from blocks (paragraphs, images, tables and page -breaks), the imports shall be adjusted. - -As mentioned above, it's possible to diversify the generated context with -images, paragraphs, tables, manual text break and pretty much everything that -is supported by PDF format specification, although currently only images, -paragraphs, tables and manual text breaks are supported. In order to customise -the blocks PDF file is built from, the ``DynamicTemplate`` class is used. -See the example below for usage examples: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_pdf/reportlab_2.py - :language: python - :lines: 4-9, 17- - - *See the full example* - :download:`here <_static/examples/creating_pdf/reportlab_2.py>` - -Building PDFs with text using `Pillow`_ ---------------------------------------- -Usage example: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_pdf/pillow_1.py - :language: python - :lines: 3-6, 10- - - *See the full example* - :download:`here <_static/examples/creating_pdf/pillow_1.py>` - ----- - -With options: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_pdf/pillow_2.py - :language: python - :lines: 10- - - *See the full example* - :download:`here <_static/examples/creating_pdf/pillow_2.py>` - ----- - -All examples shown for `pdfkit`_ and `reportlab`_ apply to `Pillow`_ generator, -however when building PDF files from blocks (paragraphs, images, tables and page -breaks), the imports shall be adjusted. - -As mentioned above, it's possible to diversify the generated context with -images, paragraphs, tables, manual text break and pretty much everything that -is supported by PDF format specification, although currently only images, -paragraphs, tables and manual text breaks are supported. In order to customise -the blocks PDF file is built from, the ``DynamicTemplate`` class is used. -See the example below for usage examples: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/creating_pdf/pillow_3.py - :language: python - :lines: 3-8, 16- - - *See the full example* - :download:`here <_static/examples/creating_pdf/pillow_3.py>` - Creating PDFs with graphics using `Pillow`_ ------------------------------------------- There's a so called `graphic` PDF file provider available. Produced PDF files diff --git a/docs/factories.rst b/docs/factories.rst new file mode 100644 index 0000000..f626b60 --- /dev/null +++ b/docs/factories.rst @@ -0,0 +1,2 @@ +Factories +========= diff --git a/docs/recipes.rst b/docs/recipes.rst index eef4d9a..b5b38f3 100644 --- a/docs/recipes.rst +++ b/docs/recipes.rst @@ -1,847 +1,2 @@ Recipes ======= - -Create a TXT file with static content -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Content of the file is ``Lorem ipsum``. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/txt_file_1.py - :language: python - :lines: 7- - - *See the full example* - :download:`here <_static/examples/recipes/txt_file_1.py>` - -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``. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/docx_file_1.py - :language: python - :lines: 7- - - *See the full example* - :download:`here <_static/examples/recipes/docx_file_1.py>` - -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``. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/zip_file_1.py - :language: python - :lines: 7- - - *See the full example* - :download:`here <_static/examples/recipes/zip_file_1.py>` - -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``. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/zip_file_2.py - :language: python - :lines: 2, 7- - - *See the full example* - :download:`here <_static/examples/recipes/zip_file_2.py>` - -Create a ZIP file of 9 DOCX files with content generated from template -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 9 DOCX files in the ZIP archive. -- Content is generated dynamically from given template. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/zip_file_3.py - :language: python - :lines: 2, 7- - - *See the full example* - :download:`here <_static/examples/recipes/zip_file_3.py>` - -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. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/zip_file_4.py - :language: python - :lines: 2-5, 10- - - *See the full example* - :download:`here <_static/examples/recipes/zip_file_4.py>` - -Create a ZIP file with variety of different file types within -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 50 files in the ZIP archive (limited to DOCX, EPUB and TXT types). -- Content is generated dynamically. -- Prefix the filename of the archive itself with ``zzz_archive_``. -- Inside the ZIP, put all files in directory ``zzz``. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/zip_file_5.py - :language: python - :lines: 2-7, 9-10, 14- - - *See the full example* - :download:`here <_static/examples/recipes/zip_file_5.py>` - -Another way to create a ZIP file with variety of different file types within -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 3 files in the ZIP archive (1 DOCX, and 2 XML types). -- Content is generated dynamically. -- Filename of the archive itself is ``alice-looking-through-the-glass.zip``. -- Files inside the archive have fixed name (passed with ``basename`` argument). - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/zip_file_6.py - :language: python - :lines: 2-6, 11- - - *See the full example* - :download:`here <_static/examples/recipes/zip_file_6.py>` - -Note, that ``count`` argument (not shown in the example, but commonly -accepted by inner functions) will be simply ignored here. - -Create an EML file consisting of TXT files with static content -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 5 TXT files in the EML email (default value is 5). -- Content of all files is ``Lorem ipsum``. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/eml_file_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/eml_file_1.py>` - -Create a EML file consisting of 3 DOCX files with dynamically generated content -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 3 DOCX files in the EML email. -- Content is generated dynamically. -- Content is limited to 1024 chars. -- Prefix the filenames in email with ``xxx_``. -- Prefix the filename of the email itself with ``zzz``. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/eml_file_2.py - :language: python - :lines: 3, 7- - - *See the full example* - :download:`here <_static/examples/recipes/eml_file_2.py>` - -Create a nested EML file -~~~~~~~~~~~~~~~~~~~~~~~~ -Create a EML file which contains 5 EML files which contain 5 EML files which -contain 5 DOCX files. - -- 5 EML files in the EML file. -- Content is generated dynamically. -- Prefix the filenames in EML email with ``nested_level_1_``. -- Prefix the filename of the EML email itself with ``nested_level_0_``. -- Each of the EML files inside the EML file in their turn contains 5 other EML - files, prefixed with ``nested_level_2_``, which in their turn contain 5 - DOCX files. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/eml_file_3.py - :language: python - :lines: 3-6, 10- - - *See the full example* - :download:`here <_static/examples/recipes/eml_file_3.py>` - -Create an EML file with variety of different file types within -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 10 files in the EML file (limited to DOCX, EPUB and TXT types). -- Content is generated dynamically. -- Prefix the filename of the EML itself with ``zzz``. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/eml_file_4.py - :language: python - :lines: 3-8, 17- - - *See the full example* - :download:`here <_static/examples/recipes/eml_file_4.py>` - -Create a PDF file with predefined template containing dynamic fixtures -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Content template is predefined and contains dynamic fixtures. -- Wrap lines after 80 chars. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/pdf_file_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/pdf_file_1.py>` - -Create a DOCX file with table and image using ``DynamicTemplate`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When pre-defined templating and dynamic fixtures are not enough and -full control is needed, you can use ``DynamicTemplate`` wrapper. -It takes a list of content modifiers -(tuples): ``(func: Callable, kwargs: dict)``. Each callable should accept -the following arguments: - -- `provider`: Faker ``Generator`` instance or ``Faker`` instance. -- `document`: Document instance. Implementation specific. -- `data`: Dictionary. Used primarily for observability. -- `counter`: Integer. Index number of the content modifier. -- `**kwargs`: Dictionary. Useful to pass implementation-specific arguments. - -The following example shows how to generate a DOCX file with paragraph, table -and image. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/docx_file_mixed_1.py - :language: python - :lines: 2-8, 13- - - *See the full example* - :download:`here <_static/examples/recipes/docx_file_mixed_1.py>` - -Create a ODT file with table and image using ``DynamicTemplate`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Similarly to previous section, the following example shows how to generate an -ODT file with table and image. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/odt_file_mixed_1.py - :language: python - :lines: 3-10, 12- - - *See the full example* - :download:`here <_static/examples/recipes/odt_file_mixed_1.py>` - -Create a PDF using `reportlab` generator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/pdf_file_reportlab_1.py - :language: python - :lines: 3-5, 9- - - *See the full example* - :download:`here <_static/examples/recipes/pdf_file_reportlab_1.py>` - -Create a PDF using `pdfkit` generator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Note, that at the moment, ``pdfkit`` is the default generator. However, -you could set it explicitly as follows: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/pdf_file_pdfkit_1.py - :language: python - :lines: 3-5, 9- - - *See the full example* - :download:`here <_static/examples/recipes/pdf_file_pdfkit_1.py>` - -Create a graphic PDF file using `Pillow` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Graphic PDF file does not contain text. Don't use it when you need text based -content. However, sometimes you just need a valid file in PDF format, without -caring much about the content. That's where a GraphicPdfFileProvider comes to -rescue: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/pdf_file_pillow_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/pdf_file_pillow_1.py>` - -The generated file will contain a random graphic (consisting of lines and -shapes of different colours). One of the most useful arguments supported is -``size``. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/pdf_file_pillow_2.py - :language: python - :lines: 7- - - *See the full example* - :download:`here <_static/examples/recipes/pdf_file_pillow_2.py>` - -Graphic providers -~~~~~~~~~~~~~~~~~ -Graphic file providers does not contain text. Don't use it when you need text -based content. However, sometimes you just need a valid image file with -graphics of a certain size. That's where graphic file providers help. - -Supported files formats are: `BMP`, `GIF`, `ICO`, `JPEG`, `PDF`, `PNG`, `SVG` -`TIFF` and `WEBP`. - -Create an ICO file -^^^^^^^^^^^^^^^^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/graphic_ico_file_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/graphic_ico_file_1.py>` - -Create a JPEG file -^^^^^^^^^^^^^^^^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/graphic_jpeg_file_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/graphic_jpeg_file_1.py>` - -Create a PNG file -^^^^^^^^^^^^^^^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/graphic_png_file_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/graphic_png_file_1.py>` - -Create a WEBP file -^^^^^^^^^^^^^^^^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/graphic_webp_file_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/graphic_webp_file_1.py>` - -Create a MP3 file -~~~~~~~~~~~~~~~~~ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/mp3_file_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/mp3_file_1.py>` - -Create a MP3 file by explicitly specifying MP3 generator class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Google Text-to-Speech -^^^^^^^^^^^^^^^^^^^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/mp3_file_gtts_1.py - :language: python - :lines: 3-5, 9- - - *See the full example* - :download:`here <_static/examples/recipes/mp3_file_gtts_1.py>` - ----- - -You can tune arguments too: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/mp3_file_gtts_2.py - :language: python - :lines: 10- - - *See the full example* - :download:`here <_static/examples/recipes/mp3_file_gtts_2.py>` - -Refer to https://gtts.readthedocs.io/en/latest/module.html#languages-gtts-lang -for list of accepted values for ``lang`` argument. - -Refer to https://gtts.readthedocs.io/en/latest/module.html#localized-accents -for list of accepted values for ``tld`` argument. - -Microsoft Edge Text-to-Speech -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/mp3_file_edge_tts_1.py - :language: python - :lines: 3-5, 9- - - *See the full example* - :download:`here <_static/examples/recipes/mp3_file_edge_tts_1.py>` - ----- - -You can tune arguments too: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/mp3_file_edge_tts_2.py - :language: python - :lines: 10- - - *See the full example* - :download:`here <_static/examples/recipes/mp3_file_edge_tts_2.py>` - -Run ``edge-tts -l`` from terminal for list of available voices. - -Create a MP3 file with custom MP3 generator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Default MP3 generator class is ``GttsMp3Generator`` which uses Google -Text-to-Speech services to generate an MP3 file from given or -randomly generated text. It does not require additional services to -run and the only dependency here is the ``gtts`` package. You can -however implement your own custom MP3 generator class and pass it to -te ``mp3_file`` method in ``mp3_generator_cls`` argument instead of the -default ``GttsMp3Generator``. Read about quotas of Google Text-to-Speech -services `here `_. - -Usage with custom MP3 generator class. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/mp3_file_custom_1.py - :language: python - :lines: 2, 4, 9- - - *See the full example* - :download:`here <_static/examples/recipes/mp3_file_custom_1.py>` - -See exact implementation of -`marytts_mp3_generator `_ -in the examples. - -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. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/random_file_from_dir_1.py - :language: python - :lines: 2, 4, 7, 12- - - *See the full example* - :download:`here <_static/examples/recipes/random_file_from_dir_1.py>` - -File from path given -~~~~~~~~~~~~~~~~~~~~ -- Create an exact copy of a file under a different name. -- Prefix of the destination file would be ``zzz``. -- ``path`` is the absolute path to the file to copy. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/file_from_path_1.py - :language: python - :lines: 3-4, 7, 11- - - *See the full example* - :download:`here <_static/examples/recipes/file_from_path_1.py>` - -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 -^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/file_of_size_bin_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/file_of_size_bin_1.py>` - -TXT -^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/file_of_size_txt_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/file_of_size_txt_1.py>` - -Generate a files using multiprocessing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Generate 10 DOCX files -^^^^^^^^^^^^^^^^^^^^^^ -- Use template. -- Generate 10 DOCX files. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/files_multiprocessing_1.py - :language: python - :lines: 1, 4-6, 8- - - *See the full example* - :download:`here <_static/examples/recipes/files_multiprocessing_1.py>` - -Randomize the file format -^^^^^^^^^^^^^^^^^^^^^^^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/files_multiprocessing_2.py - :language: python - :lines: 4-10, 36- - - *See the full example* - :download:`here <_static/examples/recipes/files_multiprocessing_2.py>` - -Generating files from existing documents using NLP augmentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the following example: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/augment_file_from_dir_1.py - :language: python - :lines: 2-4, 9, 15, 22- - - *See the full example* - :download:`here <_static/examples/recipes/augment_file_from_dir_1.py>` - -Generated file will resemble text of the original document, but -will not be the same. This is useful when you don't want to -test on text generated by ``Faker``, but rather something that -makes more sense for your use case, still want to ensure -uniqueness of the documents. - -The following file types are supported: - -- ``DOCX`` -- ``EML`` -- ``EPUB`` -- ``ODT`` -- ``PDF`` -- ``RTF`` -- ``TXT`` - ----- - -By default, all supported files are eligible for random selection. You could -however narrow that list by providing ``extensions`` argument: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/augment_file_from_dir_2.py - :language: python - :lines: 23- - - *See the full example* - :download:`here <_static/examples/recipes/augment_file_from_dir_2.py>` - ----- - -Actual augmentation of texts is delegated to an abstraction layer of text -augmenters. Currently, two augmenters are implemented. Default one is based on -`textaugment`_ (which is in its' turn based on `nltk`_) is very lightweight -and speedy, but produces less accurate results. Another one is based on -`nlpaug`_, which is way more sophisticated, but at the cost of speed. - -nlpaug augmenter -~~~~~~~~~~~~~~~~ -By default ``bert-base-multilingual-cased`` model is used, which is -pretrained on the top 104 languages with the largest Wikipedia using a -masked language modeling (MLM) objective. If you want to use a different -model, specify the proper identifier in the ``model_path`` argument. -Some well working options for ``model_path`` are: - -- ``bert-base-multilingual-cased`` -- ``bert-base-multilingual-uncased`` -- ``bert-base-cased`` -- ``bert-base-uncased`` -- ``bert-base-german-cased`` -- ``GroNLP/bert-base-dutch-cased`` - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/augment_file_from_dir_3.py - :language: python - :lines: 5-7, 25- - - *See the full example* - :download:`here <_static/examples/recipes/augment_file_from_dir_3.py>` - -Refer to ``nlpaug`` -`docs `__ -and check `Textual augmenters` examples. - -textaugment augmenter -~~~~~~~~~~~~~~~~~~~~~ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/augment_file_from_dir_4.py - :language: python - :lines: 5-7, 25- - - *See the full example* - :download:`here <_static/examples/recipes/augment_file_from_dir_4.py>` - - -Using `raw=True` features in tests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you pass ``raw=True`` argument to any provider or inner function, -instead of creating a file, you will get ``bytes`` back (or to be -totally correct, ``bytes``-like object ``BytesValue``, which is basically -bytes enriched with meta-data). You could then use the ``bytes`` content -of the file to build a test payload as shown in the example test below: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/raw_1.py - :language: python - :lines: 16- - - *See the full example* - :download:`here <_static/examples/recipes/raw_1.py>` - -Create a HTML file from predefined template -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you want to generate a file in a format that is not (yet) supported, -you can try to use ``GenericFileProvider``. In the following example, -an HTML file is generated from a template. - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/generic_file_1.py - :language: python - :lines: 2-3, 5- - - *See the full example* - :download:`here <_static/examples/recipes/generic_file_1.py>` - -Working with storages -~~~~~~~~~~~~~~~~~~~~~ -AWS S3 storage -^^^^^^^^^^^^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/aws_s3_storage_1.py - :language: python - :lines: 3, 7- - - *See the full example* - :download:`here <_static/examples/recipes/aws_s3_storage_1.py>` - ----- - -Depending on the ORM or framework you're using, you might want to tweak the -``root_path`` and ``rel_path`` values. Especially if you store files in -directories (like ``your-bucket-name/path/to/the/file.ext``). - -For instance, if you use ``Django`` and ``django-storages``, and want to -store the files inside ``/user/uploads`` directory the following would be -correct: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/aws_s3_storage_2.py - :language: python - :lines: 8-12 - - *See the full example* - :download:`here <_static/examples/recipes/aws_s3_storage_2.py>` - -Google Cloud Storage -^^^^^^^^^^^^^^^^^^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/google_cloud_storage_1.py - :language: python - :lines: 3, 7- - - *See the full example* - :download:`here <_static/examples/recipes/google_cloud_storage_1.py>` - ----- - -Similarly to ``AWSS3Storage``, if you use ``Django`` and ``django-storages``, -and want to store the files inside ``/user/uploads`` directory the following -would be correct: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/google_cloud_storage_2.py - :language: python - :lines: 8-12 - - *See the full example* - :download:`here <_static/examples/recipes/google_cloud_storage_2.py>` - -SFTP storage -^^^^^^^^^^^^ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/sftp_storage_1.py - :language: python - :lines: 3, 7- - - *See the full example* - :download:`here <_static/examples/recipes/sftp_storage_1.py>` - -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 -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/factory_boy_models_1.py - :language: python - :lines: 4-11 - - *See the full example* - :download:`here <_static/examples/recipes/factory_boy_models_1.py>` - -Correspondent ``factory_boy`` factory -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. literalinclude:: _static/examples/recipes/factory_boy_factory_1.py - :language: python - :lines: 1-87 - -And then somewhere in your code: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/factory_boy_factory_1.py - :language: python - :lines: 91- - - *See the full example* - :download:`here <_static/examples/recipes/factory_boy_factory_1.py>` - ----- - -Randomize provider choice -~~~~~~~~~~~~~~~~~~~~~~~~~ -.. literalinclude:: _static/examples/recipes/factory_boy_factory_2.py - :language: python - :lines: 1, 4, 6, 27, 30-49, 55-95 - -And then somewhere in your code: - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/factory_boy_factory_2.py - :language: python - :lines: 98- - - *See the full example* - :download:`here <_static/examples/recipes/factory_boy_factory_2.py>` - -Use a different locale -~~~~~~~~~~~~~~~~~~~~~~ -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/factory_boy_factory_3.py - :language: python - :lines: 23-24 - - *See the full example* - :download:`here <_static/examples/recipes/factory_boy_factory_3.py>` - -Other Django usage examples -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Faker example with AWS S3 storage** - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/aws_s3_storage_3.py - :language: python - :lines: 2, 4- - - *See the full example* - :download:`here <_static/examples/recipes/aws_s3_storage_3.py>` - ----- - -**factory-boy example with AWS S3 storage** - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/aws_s3_storage_4.py - :language: python - :lines: 2, 4-6, 9- - - *See the full example* - :download:`here <_static/examples/recipes/aws_s3_storage_4.py>` - ----- - -**Flexible storage selection** - -.. container:: jsphinx-download - - .. literalinclude:: _static/examples/recipes/flexible_storage_1.py - :language: python - :lines: 2- - - *See the full example* - :download:`here <_static/examples/recipes/flexible_storage_1.py>` diff --git a/examples/pydantic/article/models.py b/examples/pydantic/article/models.py index 3d40dbc..5a7f184 100644 --- a/examples/pydantic/article/models.py +++ b/examples/pydantic/article/models.py @@ -3,6 +3,11 @@ from pydantic import BaseModel, Field +__all__ = ( + "Article", + "User", +) + class User(BaseModel): id: int diff --git a/examples/tortoise/article/models.py b/examples/tortoise/article/models.py index b61ecaa..44bd3e9 100644 --- a/examples/tortoise/article/models.py +++ b/examples/tortoise/article/models.py @@ -3,6 +3,11 @@ from tortoise import fields from tortoise.models import Model +__all__ = ( + "Article", + "User", +) + class User(Model): id = fields.IntField(pk=True) diff --git a/fake.py b/fake.py index e8ecdc5..1670ae4 100644 --- a/fake.py +++ b/fake.py @@ -1546,7 +1546,7 @@ async def async_save(): class TestFaker(unittest.TestCase): def setUp(self) -> None: - self.faker = Faker() + self.faker = FAKER def test_first_name(self) -> None: first_name: str = self.faker.first_name()