Writing an exporter plugin¶

An Exporter is a method to export the product and order data in pretix for later use in another program.

In this document, we will walk through the creation of an exporter output plugin step by step.

Please read Creating a plugin first, if you haven’t already.

Exporter registration¶

The exporter API does not make a lot of usage from signals, however, it does use a signal to get a list of all available exporters. Your plugin should listen for this signal and return the subclass of pretix.base.exporter.BaseExporter that we’ll provide in this plugin:

from django.dispatch import receiver

from pretix.base.signals import register_data_exporters


@receiver(register_data_exporters, dispatch_uid="exporter_myexporter")
def register_data_exporter(sender, **kwargs):
    from .exporter import MyExporter
    return MyExporter

Some exporters might also prove to be useful, when provided on an organizer-level. In order to declare your exporter as capable of providing exports spanning multiple events, your plugin should listen for this signal and return the subclass of pretix.base.exporter.BaseExporter that we’ll provide in this plugin:

from django.dispatch import receiver

from pretix.base.signals import register_multievent_data_exporters


@receiver(register_multievent_data_exporters, dispatch_uid="multieventexporter_myexporter")
def register_multievent_data_exporter(sender, **kwargs):
    from .exporter import MyExporter
    return MyExporter

If your exporter supports both event-level and multi-event level exports, you will need to listen for both signals.

The exporter class¶

class pretix.base.exporter.BaseExporter¶

The central object of each exporter is the subclass of BaseExporter.

BaseExporter.event¶: The default constructor sets this property to the event we are currently working for. This will be None if the exporter is run for multiple events.

BaseExporter.events¶: The default constructor sets this property to the list of events to work on, regardless of whether the exporter is called for one or multiple events.

BaseExporter.identifier¶

A short and unique identifier for this exporter. This should only contain lowercase letters and in most cases will be the same as your package name.

This is an abstract attribute, you must override this!

BaseExporter.verbose_name¶

A human-readable name for this exporter. This should be short but self-explaining. Good examples include ‘Orders as JSON’ or ‘Orders as Microsoft Excel’.

This is an abstract attribute, you must override this!

BaseExporter.description¶: A description for this exporter.

BaseExporter.category¶: A category name for this exporter, or None.

BaseExporter.export_form_fields¶

When the event’s administrator visits the export page, this method is called to return the configuration fields available.

It should therefore return a dictionary where the keys should be field names and the values should be corresponding Django form fields.

We suggest that you return an OrderedDict object instead of a dictionary. Your implementation could look like this:

@property
def export_form_fields(self):
    return OrderedDict(
        [
            ('tab_width',
             forms.IntegerField(
                 label=_('Tab width'),
                 default=4
             ))
        ]
    )

BaseExporter.repeatable_read¶

If True, this exporter will be run in a REPEATABLE READ transaction. This ensures consistent results for all queries performed by the exporter, but creates a performance burden on the database server. We recommend to disable this for exporters that take very long to run and do not rely on this behavior, such as export of lists to CSV files.

Defaults to True for now, but default may change in future versions.

BaseExporter.render(form_data: dict) → Tuple[str, str, bytes | None]¶

Render the exported file and return a tuple consisting of a filename, a file type and file content.

Parameters:

form_data (dict) – The form data of the export details form
output_file – You can optionally accept a parameter that will be given a file handle to write the output to. In this case, you can return None instead of the file content.

Note: If you use a ModelChoiceField (or a ModelMultipleChoiceField), the form_data will not contain the model instance but only it’s primary key (or a list of primary keys) for reasons of internal serialization when using background tasks.

This is an abstract method, you must override this!

BaseExporter.available_for_user(user) → bool¶: Allows to do additional checks whether an exporter is available based on the user who calls it. Note that user may be None e.g. during API usage.

classmethod BaseExporter.get_required_event_permission() → str¶: The permission level required to use this exporter for events. For multi-event-exports, this will be used to limit the selection of events. Will be ignored if the OrganizerLevelExportMixin mixin is used. The default implementation returns "event.orders:read".

On organizer level, by default exporters are expected to handle on a set of events and the system will automatically add a form field that allows the selection of events, limited to events the user has correct permissions for. If this does not fit your organizer, because it is not related to events, you should also inherit from the following class:

class pretix.base.exporter.OrganizerLevelExportMixin¶

classmethod OrganizerLevelExportMixin.get_required_organizer_permission() → str¶

The permission level required to use this exporter. Must be set for organizer-level exports. Set to None to allow everyone with any access to the organizer.

get_required_event_permission will be ignored on this class.