Creating PDF
============
.. External references

.. _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.

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 complex PDF documents.

Building PDF with text
----------------------
If you need bytes
~~~~~~~~~~~~~~~~~

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/text_pdf_bytes_1.py
        :name: test_creating_pdf_text_pdf_bytes_1
        :language: python
        :lines: 1-3

    *See the full example*
    :download:`here <_static/examples/creating_pdf/text_pdf_bytes_1.py>`

The generated PDF will consist of a single page with little text on it.

If you want to control the number of pages created, you could:

- Pass a list of texts to the ``texts`` argument.
- Pass the number of pages to the ``nb_pages`` argument.

----

See the example below for ``texts`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/text_pdf_bytes_2.py
        :name: test_creating_pdf_text_pdf_bytes_2
        :language: python
        :lines: 3-4

    *See the full example*
    :download:`here <_static/examples/creating_pdf/text_pdf_bytes_2.py>`

----

For full clarity, see another example below for ``texts`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/text_pdf_bytes_2b.py
        :name: test_creating_pdf_text_pdf_bytes_2b
        :language: python
        :lines: 3-4

    *See the full example*
    :download:`here <_static/examples/creating_pdf/text_pdf_bytes_2b.py>`

The produced PDF will have 3 pages:

- The first will show: ``Page 1 content``
- The second page will show: ``Page 2 content``
- The third page will show: ``Page 3 content``

----

See the example below for ``nb_pages`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/text_pdf_bytes_3.py
        :name: test_creating_pdf_text_pdf_bytes_3
        :language: python
        :lines: 3

    *See the full example*
    :download:`here <_static/examples/creating_pdf/text_pdf_bytes_3.py>`

If you need files
~~~~~~~~~~~~~~~~~
.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/text_pdf_file_1.py
        :name: test_creating_pdf_text_pdf_file_1
        :language: python
        :lines: 3

    *See the full example*
    :download:`here <_static/examples/creating_pdf/text_pdf_file_1.py>`

----

With ``texts`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/text_pdf_file_2.py
        :name: test_creating_pdf_text_pdf_file_2
        :language: python
        :lines: 3-4

    *See the full example*
    :download:`here <_static/examples/creating_pdf/text_pdf_file_2.py>`

----

With ``nb_pages`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/text_pdf_file_3.py
        :name: test_creating_pdf_text_pdf_file_3
        :language: python
        :lines: 3

    *See the full example*
    :download:`here <_static/examples/creating_pdf/text_pdf_file_3.py>`

Building PDF with graphics
--------------------------
If you need bytes
~~~~~~~~~~~~~~~~~

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/graphic_pdf_bytes_1.py
        :name: test_creating_pdf_graphic_pdf_bytes_1
        :language: python
        :lines: 1-3

    *See the full example*
    :download:`here <_static/examples/creating_pdf/graphic_pdf_bytes_1.py>`

The generated PDF will consist of a single page with a coloured square on it.

If you want a PDF with more pages, provide the ``nb_pages`` argument.

----

See the example below for ``nb_pages`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/graphic_pdf_bytes_2.py
        :name: test_creating_pdf_graphic_pdf_bytes_2
        :language: python
        :lines: 3

    *See the full example*
    :download:`here <_static/examples/creating_pdf/graphic_pdf_bytes_2.py>`

If you need files
~~~~~~~~~~~~~~~~~
.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/graphic_pdf_file_1.py
        :name: test_creating_pdf_graphic_pdf_file_1
        :language: python
        :lines: 3

    *See the full example*
    :download:`here <_static/examples/creating_pdf/graphic_pdf_file_1.py>`

----

With ``nb_pages`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_pdf/graphic_pdf_file_2.py
        :name: test_creating_pdf_graphic_pdf_file_2
        :language: python
        :lines: 3

    *See the full example*
    :download:`here <_static/examples/creating_pdf/graphic_pdf_file_2.py>`

----

.. raw:: html

    &nbsp;