Metadata-Version: 2.5
Name: xlsxdocument
Version: 1.4.0
Summary: Easily create XLSX documents with Django
Project-URL: Homepage, https://github.com/matthiask/xlsxdocument/
Author-email: Matthias Kestenholz <mk@feinheit.ch>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.10
Requires-Dist: django>=3.2
Requires-Dist: openpyxl
Description-Content-Type: text/x-rst

============
XLSXDocument
============

This is a wrapper for openpyxl_ which makes creating XLSX documents with
the purpose of exporting data less boring:

.. code-block:: python

    from xlsxdocument import XLSXDocument

    def xlsx_export(request):
        some_data = Bla.objects.all()

        xlsx = XLSXDocument()
        xlsx.table_from_queryset(Bla.objects.all())
        return xlsx.to_response("bla.xlsx")


Adding in additional cells at the end is also possible:

.. code-block:: python

    xlsx = XLSXDocument()
    xlsx.table_from_queryset(
        Bla.objects.all(),
        additional=[(
            "Full URL",
            lambda instance: "https://example.com%s" % (
                instance.get_absolute_url(),
            ),
        )],
    )


For lower-level control, use ``add_sheet()`` and ``table()`` directly to
build sheets from arbitrary data:

.. code-block:: python

    xlsx = XLSXDocument()
    xlsx.add_sheet("Sales")
    xlsx.table(
        titles=["Product", "Quantity", "Price"],
        rows=[
            ["Widget A", 10, 9.99],
            ["Widget B", 5, 24.99],
        ],
    )
    return xlsx.to_response("sales.xlsx")

Strings starting with ``=`` are written as text, not as formulas, since
exported data is often untrusted (formula injection). Wrap intentional
formulas in ``Formula``:

.. code-block:: python

    from xlsxdocument import Formula, XLSXDocument

    xlsx.table(
        titles=["Product", "Quantity"],
        rows=[
            ["Widget A", 10],
            ["Widget B", 5],
            ["Total", Formula("=SUM(B2:B3)")],
        ],
    )

You can also add multiple sheets to a single document:

.. code-block:: python

    xlsx = XLSXDocument()

    xlsx.add_sheet("Orders")
    xlsx.table(["ID", "Customer", "Total"], orders_data)

    xlsx.add_sheet("Products")
    xlsx.table(["SKU", "Name", "Stock"], products_data)

    return xlsx.to_response("export.xlsx")


You can also easily add the facility to export rows to Django's
administration interface:

.. code-block:: python

    from django.contrib import admin
    from django.utils.translation import gettext_lazy as _

    from xlsxdocument import export_selected

    from app import models


    class AttendanceAdmin(admin.ModelAdmin):
        list_filter = ["event"]
        actions = [export_selected]


    admin.site.register(models.Event)
    admin.site.register(models.Attendance, AttendanceAdmin)


If you require additional columns with ``export_selected`` use this
snippet instead:

.. code-block:: python

    from xlsxdocument import create_export_selected

    class AttendanceAdmin(...):
        actions = [
            create_export_selected(
                additional=[
                    # ... see above
                ]
            )
        ]


.. _openpyxl: https://openpyxl.readthedocs.io/
