diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 2214bde..6eb26a3 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -16,6 +16,14 @@ are used for versioning (schema follows below): 0.3.4 to 0.4). - All backwards incompatible changes are mentioned in this document. +0.10.5 +------ +*Unreleased* + +- Add benchmarks section to the main README. +- Improve docs. Add a dedicated section on files creation. +- Minor clean-up. + 0.10.4 ------ 2024-10-17 diff --git a/README.rst b/README.rst index 3d9f004..0b3b664 100644 --- a/README.rst +++ b/README.rst @@ -24,6 +24,7 @@ fake.py .. _Recipes: https://fakepy.readthedocs.io/en/latest/recipes.html .. _Factories: https://fakepy.readthedocs.io/en/latest/factories.html .. _Customization: https://fakepy.readthedocs.io/en/latest/customization.html +.. _Creating files: https://fakepy.readthedocs.io/en/latest/creating_files.html .. _Creating PDF: https://fakepy.readthedocs.io/en/latest/creating_pdf.html .. _Creating DOCX: https://fakepy.readthedocs.io/en/latest/creating_docx.html .. _Creating ODT: https://fakepy.readthedocs.io/en/latest/creating_odt.html @@ -121,6 +122,7 @@ Documentation - For various ready to use code examples see the `Recipes`_. - For tips on how to use the factories see the `Factories`_. - For customization tips see the `Customization`_. +- For generic information on how to create files see `Creating files`_. - For tips on ``PDF`` creation see `Creating PDF`_. - For tips on ``DOCX`` creation see `Creating DOCX`_. - For tips on ``ODT`` creation see `Creating ODT`_. diff --git a/docs/_static/examples/creating_pdf/text_pdf_bytes_2b.py b/docs/_static/examples/creating_pdf/text_pdf_bytes_2b.py new file mode 100644 index 0000000..3857ed1 --- /dev/null +++ b/docs/_static/examples/creating_pdf/text_pdf_bytes_2b.py @@ -0,0 +1,4 @@ +from fake import FAKER, TextPdfGenerator + +texts = ["Page 1 content", "Page 2 content", "Page 3 content"] +pdf_bytes = FAKER.pdf(texts=texts, generator=TextPdfGenerator) diff --git a/docs/creating_files.rst b/docs/creating_files.rst new file mode 100644 index 0000000..03ab72c --- /dev/null +++ b/docs/creating_files.rst @@ -0,0 +1,94 @@ +Creating files +============== + +.. Internal references + +.. _fake.py: https://github.com/barseghyanartur/fake.py/ +.. _Creating archives: https://fakepy.readthedocs.io/en/latest/creating_archives.html +.. _Creating DOCX: https://fakepy.readthedocs.io/en/latest/creating_docx.html +.. _Creating images: https://fakepy.readthedocs.io/en/latest/creating_images.html +.. _Creating ODT: https://fakepy.readthedocs.io/en/latest/creating_odt.html +.. _Creating PDF: https://fakepy.readthedocs.io/en/latest/creating_pdf.html + +Creation of specific file formats is extensively covered in dedicated +sections: + +- `Creating archives`_ +- `Creating DOCX`_ +- `Creating images`_ +- `Creating ODT`_ +- `Creating PDF`_ + +This section covers basic concepts of file generation within `fake.py`_. + +It's possible to generate either bytes or files on the file system. + +- When generating bytes, the returned value is ``BytesValue``. + +- When generating files on the file system, the returned value + is ``StringValue``. + +Both ``BytesValue`` and ``StringValue`` behave like ``bytes`` and ``str`` +respectively, but have a ``data`` (``dict``) property, which contains useful +meta-data about the specific kind of file. + +For generated files, it will always have the following: + +- ``storage``: Storage class that was used to generate the file. +- ``filename``: Absolute file path. It's important to know, that string + representation of the file contains a relative file path. + +---- + +See the example below for a graphic PDF generation: + +.. container:: jsphinx-toggle-emphasis + + .. code-block:: python + :name: test_pdf_file + :emphasize-lines: 3 + + from fake import FAKER + + pdf_file = FAKER.pdf_file() + + print(pdf_file) + # tmp/tmpnvwoa2ap.pdf + + print(pdf_file.data["filename"]) + # /tmp/tmp/tmpnvwoa2ap.pdf + + print(pdf_file.data) + # {'storage': , + # 'filename': '/tmp/tmp/tmpragc8wyr.pdf', + # 'content': None} + +---- + +See the example below for a text PDF generation: + +.. container:: jsphinx-toggle-emphasis + + .. code-block:: python + :name: test_text_pdf_file + :emphasize-lines: 3 + + from fake import FAKER + + pdf_file = FAKER.text_pdf_file() + + print(pdf_file) + # tmp/tmpragc8wyr.pdf + + print(pdf_file.data["filename"]) + # /tmp/tmp/tmpragc8wyr.pdf + + print(pdf_file.data) + # {'storage': , + # 'filename': '/tmp/tmp/tmpragc8wyr.pdf', + # 'content': 'If dutch beats although complex.'} + +Note, that text PDF does contain full text of the entire document in the +``content`` key. + +---- diff --git a/docs/creating_pdf.rst b/docs/creating_pdf.rst index 78a01da..c9ba65a 100644 --- a/docs/creating_pdf.rst +++ b/docs/creating_pdf.rst @@ -52,6 +52,25 @@ See the example below for ``texts`` tweak: ---- +For full clarity, see another example below for ``texts`` tweak: + +.. container:: jsphinx-download + + .. literalinclude:: _static/examples/creating_pdf/text_pdf_bytes_2b.py + :language: python + :lines: 3- + + *See the full example* + :download:`here <_static/examples/creating_pdf/text_pdf_bytes_2b.py>` + +The produced PDF will consist of 3 pages: + +- Content of the first would be: ``Page 1 content`` +- Content of the second page would be: ``Page 1 content`` +- Content of the third page would be: ``Page 3 content`` + +---- + See the example below for ``nb_pages`` tweak: .. container:: jsphinx-download