Creating DOCX
=============
.. External references

.. _faker-file: https://pypi.org/project/faker-file/

The goal of this library is to help you out with basic tasks. You can easily
generate DOCX files with 100 pages (paper size is A4), having a little text
on each.

If you don't like how DOCX files are generated by this library, you can
check the `faker-file`_ package, which can produce complex DOCX documents.

If you need bytes
-----------------

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_docx/docx_bytes_1.py
        :name: test_creating_docx_docx_bytes_1
        :language: python
        :lines: 1-3

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

The generated DOCX 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_docx/docx_bytes_2.py
        :name: test_creating_docx_docx_bytes_2
        :language: python
        :lines: 3-4

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

----

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

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_docx/docx_bytes_3.py
        :name: test_creating_docx_docx_bytes_3
        :language: python
        :lines: 3

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

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

    .. literalinclude:: _static/examples/creating_docx/docx_file_1.py
        :name: test_creating_docx_docx_file_1
        :language: python
        :lines: 3

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

----

With ``texts`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_docx/docx_file_2.py
        :name: test_creating_docx_docx_file_2
        :language: python
        :lines: 3-4

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

----

With ``nb_pages`` tweak:

.. container:: jsphinx-download

    .. literalinclude:: _static/examples/creating_docx/docx_file_3.py
        :name: test_creating_docx_docx_file_3
        :language: python
        :lines: 3

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

----

Using text templates:

.. container:: jsphinx-toggle-emphasis-replace

    .. code-block:: python
        :name: test_text_templates
        :emphasize-lines: 1-26

        from fake import FAKER, StringTemplate

        template = """
        {date(start_date='-7d')}
        {name}
        {sentence(nb_words=2, suffix='')} {pyint(min_value=1, max_value=99)}
        {randomise_string(value='#### ??', digits='123456789')} {city}

        Dear friend,

        {text(nb_chars=1000, allow_overflow=True)}

        Sincerely yours,

        {name}
        {email}
        {domain_name}
        """
        # DOCX file of 1 page
        docx_file_1 = FAKER.docx_file(
            texts=[StringTemplate(template)],
        )
        # DOCX file of 10 pages
        docx_file_10 = FAKER.docx_file(
            texts=[StringTemplate(template) for _ in range(10)],
        )

        # Tests
        assert isinstance(docx_file_1, str)
        assert docx_file_1.data["storage"].exists(docx_file_1)
        assert isinstance(docx_file_10, str)
        assert docx_file_10.data["storage"].exists(docx_file_10)

----

.. raw:: html

    &nbsp;