From e5301dcdc551fa43b61766d86338a777045dc675 Mon Sep 17 00:00:00 2001 From: luelista Date: Fri, 5 Sep 2025 18:27:04 +0200 Subject: [PATCH] Clarify plugin signal docstrings (#5397) --- src/pretix/base/signals.py | 16 +++--- src/pretix/control/signals.py | 42 +++++++++------- src/pretix/plugins/sendmail/signals.py | 2 +- src/pretix/plugins/ticketoutputpdf/signals.py | 2 +- src/pretix/presale/signals.py | 50 +++++++++---------- src/pretix/presale/style.py | 2 +- 6 files changed, 60 insertions(+), 54 deletions(-) diff --git a/src/pretix/base/signals.py b/src/pretix/base/signals.py index 2b17fccf6..8e1842200 100644 --- a/src/pretix/base/signals.py +++ b/src/pretix/base/signals.py @@ -99,24 +99,24 @@ def is_app_active(sender, app, allow_legacy_plugins=False): elif isinstance(sender, Organizer) and allow_legacy_plugins: # Deprecated behaviour: Event plugins that are registered on organizer level are considered active for # all organizers in the context of signals that used to be global signals before the introduction of - # organizer-level plugin. A deprecation warning is emitted at .connect() time. + # organizer plugins. A deprecation warning is emitted at .connect() time. enabled = True else: - raise ImproperlyConfigured(f"Cannot check if event-level plugin is active on {type(sender)}") + raise ImproperlyConfigured(f"Cannot check if event plugin is active on {type(sender)}") elif level == PLUGIN_LEVEL_ORGANIZER: if isinstance(sender, Organizer): enabled = app.name in sender.get_plugins() elif isinstance(sender, Event): enabled = app.name in sender.organizer.get_plugins() else: - raise ImproperlyConfigured(f"Cannot check if organizer-level plugin is active on {type(sender)}") + raise ImproperlyConfigured(f"Cannot check if organizer plugin is active on {type(sender)}") elif level == PLUGIN_LEVEL_EVENT_ORGANIZER_HYBRID: if isinstance(sender, Organizer): enabled = app.name in sender.get_plugins() elif isinstance(sender, Event): enabled = app.name in sender.get_plugins() and app.name in sender.organizer.get_plugins() else: - raise ImproperlyConfigured(f"Cannot check if hybrid event/organizer-level plugin is active on {type(sender)}") + raise ImproperlyConfigured(f"Cannot check if hybrid event/organizer plugin is active on {type(sender)}") else: raise ImproperlyConfigured("Unknown plugin level") @@ -230,7 +230,7 @@ class PluginSignal(Generic[T], django.dispatch.Signal): class EventPluginSignal(PluginSignal[Event]): """ This is an extension to Django's built-in signals which differs in a way that it sends - out it's events only to receivers which belong to plugins that are enabled for the given + out its events only to receivers which belong to plugins that are enabled for the given Event. """ type = Event @@ -254,7 +254,7 @@ class EventPluginSignal(PluginSignal[Event]): class OrganizerPluginSignal(PluginSignal[Organizer]): """ This is an extension to Django's built-in signals which differs in a way that it sends - out it's events only to receivers which belong to plugins that are enabled for the given + out its events only to receivers which belong to plugins that are enabled for the given Organizer. """ type = Organizer @@ -898,7 +898,7 @@ This signals allows you to add fees to an order while it is being created. You a return a list of ``OrderFee`` objects that are not yet saved to the database (because there is no order yet). -As with all plugin signals, the ``sender`` keyword argument will contain the event. A ``positions`` +As with all event plugin signals, the ``sender`` keyword argument will contain the event. A ``positions`` argument will contain the cart positions and ``invoice_address`` the invoice address (useful for tax calculation). The argument ``meta_info`` contains the order's meta dictionary. The ``total`` keyword argument will contain the total cart sum without any fees. You should not rely on this @@ -916,7 +916,7 @@ This signals allows you to return a human-readable description for a fee type ba and ``internal_type`` attributes of the ``OrderFee`` model that you get as keyword arguments. You are expected to return a string or None, if you don't know about this fee. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ allow_ticket_download = EventPluginSignal() diff --git a/src/pretix/control/signals.py b/src/pretix/control/signals.py index 5e1b6b76a..fb5088acc 100644 --- a/src/pretix/control/signals.py +++ b/src/pretix/control/signals.py @@ -52,7 +52,7 @@ This signal allows you to put code inside the HTML ```` tag of every page in the backend. You will get the request as the keyword argument ``request`` and are expected to return plain HTML. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ nav_event = EventPluginSignal() @@ -77,7 +77,7 @@ The latter method also allows you to register navigation items as a sub-item of If you use this, you should read the documentation on :ref:`how to deal with URLs ` in pretix. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ nav_topbar = GlobalSignal() @@ -131,7 +131,7 @@ Arguments: 'request' This signal is sent out to include custom HTML in the top part of the the event dashboard. Receivers should return HTML. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. An additional keyword argument ``subevent`` *can* contain a sub-event. """ @@ -146,7 +146,7 @@ should return a list of dictionaries, where each dictionary can have the keys: * priority (int, used for ordering, higher comes first, default is 1) * url (str, optional, if the full widget should be a link) -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. An additional keyword argument ``subevent`` *can* contain a sub-event. """ @@ -173,7 +173,7 @@ Arguments: 'form' This signal allows you to add additional HTML to the form that is used for modifying vouchers. You receive the form object in the ``form`` keyword argument. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ voucher_form_class = EventPluginSignal() @@ -189,7 +189,7 @@ an asynchronous context. For the bulk creation form, ``save()`` is not called. I you can implement ``post_bulk_save(saved_vouchers)`` which may be called multiple times for every batch persisted to the database. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ voucher_form_validation = EventPluginSignal() @@ -200,7 +200,7 @@ This signal allows you to add additional validation to the form that is used for creating and modifying vouchers. You will receive the form instance in the ``form`` argument and the current data state in the ``data`` argument. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ quota_detail_html = EventPluginSignal() @@ -210,7 +210,7 @@ Arguments: 'quota' This signal allows you to append HTML to a Quota's detail view. You receive the quota as argument in the ``quota`` keyword argument. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ organizer_edit_tabs = DeprecatedSignal() @@ -241,8 +241,14 @@ If your linked view should stay in the tab-like context of this page, we recomme that you use ``pretix.control.views.organizer.OrganizerDetailViewMixin`` for your view and your template inherits from ``pretixcontrol/organizers/base.html``. -This is a regular django signal (no pretix event signal). Receivers will be passed -the keyword arguments ``organizer`` and ``request``. +This is an organizer plugin signal (not an event-level signal). Organizer and +hybrid plugins, will receive it if they're active for the current organizer. + +**Deprecation Notice:** Currently, event plugins can always receive this signal, +regardless of activation. In the future, event plugins will not be allowed to register +to organizer-level signals. + +Receivers will be passed the keyword arguments ``organizer`` and ``request``. """ order_info = EventPluginSignal() @@ -251,7 +257,7 @@ Arguments: ``order``, ``request`` This signal is sent out to display additional information on the order detail page -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. Additionally, the argument ``order`` and ``request`` are available. """ @@ -261,7 +267,7 @@ Arguments: ``order``, ``position``, ``request`` This signal is sent out to display additional buttons for a single position of an order. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. Additionally, the argument ``order`` and ``request`` are available. """ @@ -279,7 +285,7 @@ If your linked view should stay in the tab-like context of this page, we recomme that you use ``pretix.control.views.event.EventSettingsViewMixin`` for your view and your template inherits from ``pretixcontrol/event/settings_base.html``. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. A second keyword argument ``request`` will contain the request object. """ @@ -290,7 +296,7 @@ Arguments: 'request' This signal is sent out to include template snippets on the settings page of an event that allows generating a pretix Widget code. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. A second keyword argument ``request`` will contain the request object. """ @@ -308,7 +314,7 @@ Your forms may also have two special properties: ``template`` with a template th included to render the form, and ``title``, which will be used as a headline. Your template will be passed a ``form`` variable with your form. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ item_formsets = EventPluginSignal() @@ -326,7 +332,7 @@ Your formset needs to have two special properties: ``template`` with a template included to render the formset and ``title`` that will be used as a headline. Your template will be passed a ``formset`` variable with your formset. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ subevent_forms = EventPluginSignal() @@ -347,7 +353,7 @@ Your forms may also have two special properties: ``template`` with a template th included to render the form, and ``title``, which will be used as a headline. Your template will be passed a ``form`` variable with your form. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ oauth_application_registered = GlobalSignal() @@ -381,5 +387,5 @@ You are required to set ``prefix`` on your form instance. You are required to im method on your form that returns a new, filtered query set. You are required to implement a ``filter_to_strings()`` method on your form that returns a list of strings describing the currently active filters. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ diff --git a/src/pretix/plugins/sendmail/signals.py b/src/pretix/plugins/sendmail/signals.py index 0bb80c535..39fa11683 100644 --- a/src/pretix/plugins/sendmail/signals.py +++ b/src/pretix/plugins/sendmail/signals.py @@ -247,7 +247,7 @@ sendmail_view_classes = EventPluginSignal() This signal allows you to register subclasses of ``pretix.plugins.sendmail.views.BaseSenderView`` that should be discovered by this plugin. -As with all plugin signals, the ``sender`` keyword will contain the event. +As with all event plugin signals, the ``sender`` keyword will contain the event. """ diff --git a/src/pretix/plugins/ticketoutputpdf/signals.py b/src/pretix/plugins/ticketoutputpdf/signals.py index d0978b516..bd3464f5f 100644 --- a/src/pretix/plugins/ticketoutputpdf/signals.py +++ b/src/pretix/plugins/ticketoutputpdf/signals.py @@ -205,5 +205,5 @@ The ``layout`` keyword argument will contain the layout which has been originall If you implement this signal and do not want to override the layout, make sure to return the ``layout`` keyword argument which you have been passed. -As with all plugin signals, the ``sender`` keyword will contain the event. +As with all event plugin signals, the ``sender`` keyword will contain the event. """ diff --git a/src/pretix/presale/signals.py b/src/pretix/presale/signals.py index 9c425a7f5..f3f9cc8d7 100644 --- a/src/pretix/presale/signals.py +++ b/src/pretix/presale/signals.py @@ -74,7 +74,7 @@ This signal allows you to put code inside the HTML ```` tag of every page in the frontend. You will get the request as the keyword argument ``request`` and are expected to return plain HTML. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. **Note:** If PCI DSS compliance is important to you and you keep an inventory according to rule 6.4.3 of PCI DSS, all plugins that are not required to load on a payment page should @@ -91,7 +91,7 @@ This signal allows you to put code inside the HTML ```` tag of the seatingframe page in the frontend. You will get the request as the keyword argument ``request`` and are expected to return plain HTML. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ html_page_header = EventPluginSignal() @@ -102,7 +102,7 @@ This signal allows you to put code right in the beginning of the HTML ```` of every page in the frontend. You will get the request as the keyword argument ``request`` and are expected to return plain HTML. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ html_footer = EventPluginSignal() @@ -113,7 +113,7 @@ This signal allows you to put code before the end of the HTML ```` tag of every page in the frontend. You will get the request as the keyword argument ``request`` and are expected to return plain HTML. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. **Note:** If PCI DSS compliance is important to you and you keep an inventory according to rule 6.4.3 of PCI DSS, all plugins that are not required to load on a payment page should @@ -128,7 +128,7 @@ Arguments: ``request`` The signal ``pretix.presale.signals.footer_link`` allows you to add links to the footer of an event page. You are expected to return a dictionary containing the keys ``label`` and ``url``. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ global_footer_link = GlobalSignal() @@ -146,7 +146,7 @@ order can be completed. This is typically used for something like "accept the te Receivers are expected to return a dictionary where the keys are globally unique identifiers for the message and the values can be arbitrary HTML. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ checkout_flow_steps = EventPluginSignal() @@ -154,7 +154,7 @@ checkout_flow_steps = EventPluginSignal() This signal is sent out to retrieve pages for the checkout flow. Receivers are expected to return a subclass of ``pretix.presale.checkoutflow.BaseCheckoutFlowStep``. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ voucher_redeem_info = EventPluginSignal() @@ -163,7 +163,7 @@ Arguments: ``voucher`` This signal is sent out to display additional information on the "redeem a voucher" page -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ order_meta_from_request = EventPluginSignal() @@ -195,7 +195,7 @@ Arguments: ``request`` This signals allows you to add HTML content to the confirmation page that is presented at the end of the checkout process, just before the order is being created. -As with all plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` +As with all event plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` argument will contain the request object. """ @@ -206,7 +206,7 @@ Arguments: ``request``, ``invoice_address``, ``total``, ``positions``, ``payment This signals allows you to add fees to a cart. You are expected to return a list of ``OrderFee`` objects that are not yet saved to the database (because there is no order yet). -As with all plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` +As with all event plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` argument will contain the request object and ``invoice_address`` the invoice address (useful for tax calculation). The ``total`` keyword argument will contain the total cart sum without any fees. You should not rely on this ``total`` value for fee calculations as other fees might interfere. @@ -220,7 +220,7 @@ and by default only asks for the email address. You are supposed to return a dic form fields with globally unique keys. The validated form results will be saved into the ``contact_form_data`` entry of the order's meta_info dictionary. -As with all plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` +As with all event plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` argument will contain the request object. """ @@ -234,7 +234,7 @@ form. You are supposed to return a dictionary of dictionaries with globally uniq value-dictionary should contain one or more of the following keys: ``initial``, ``disabled``, ``validators``. The key of the dictionary should be the name of the form field. -As with all plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` +As with all event plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` argument will contain the request object. The ``order`` argument is ``None`` during the checkout process and contains an order if the customer is trying to change an existing order. """ @@ -252,7 +252,7 @@ The ``position`` keyword argument will contain either a ``CartPosition`` object object, depending on whether the form is called as part of the order checkout or for changing an order later. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ question_form_fields_overrides = EventPluginSignal() @@ -268,7 +268,7 @@ for user-defined questions. The ``position`` keyword argument will contain a ``CartPosition`` or ``OrderPosition`` object. -As with all plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` +As with all event plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` argument will contain the request object. """ @@ -278,7 +278,7 @@ Arguments: ``order``, ``request`` This signal is sent out to display additional information on the order detail page -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ position_info = EventPluginSignal() @@ -287,7 +287,7 @@ Arguments: ``order``, ``position``, ``request`` This signal is sent out to display additional information on the position detail page -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ order_info_top = EventPluginSignal() @@ -296,7 +296,7 @@ Arguments: ``order``, ``request`` This signal is sent out to display additional information on top of the order detail page -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ position_info_top = EventPluginSignal() @@ -305,7 +305,7 @@ Arguments: ``order``, ``position``, ``request`` This signal is sent out to display additional information on top of the position detail page -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ process_request = EventPluginSignal() @@ -321,7 +321,7 @@ won't be processed any further down the stack. WARNING: Be very careful about using this signal as listening to it makes it really easy to cause serious performance problems. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ process_response = EventPluginSignal() @@ -338,7 +338,7 @@ return the ``response`` parameter. WARNING: Be very careful about using this signal as listening to it makes it really easy to cause serious performance problems. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. """ front_page_top = EventPluginSignal() @@ -348,7 +348,7 @@ Arguments: ``request``, ``subevent`` This signal is sent out to display additional information on the frontpage above the list of products and but below a custom frontpage text. -As with all plugin signals, the ``sender`` keyword argument will contain the event. The +As with all event plugin signals, the ``sender`` keyword argument will contain the event. The receivers are expected to return HTML. """ @@ -360,7 +360,7 @@ This signal is sent out to render a seating plan, if one is configured for the s You will be passed the ``request`` as a keyword argument. If applicable, a ``subevent`` or ``voucher`` argument might be given. -As with all plugin signals, the ``sender`` keyword argument will contain the event. The +As with all event plugin signals, the ``sender`` keyword argument will contain the event. The receivers are expected to return HTML. """ @@ -371,7 +371,7 @@ Arguments: ``request``, ``subevent`` This signal is sent out to display additional information on the frontpage below the list of products. -As with all plugin signals, the ``sender`` keyword argument will contain the event. The +As with all event plugin signals, the ``sender`` keyword argument will contain the event. The receivers are expected to return HTML. """ @@ -382,7 +382,7 @@ Arguments: ``request``, ``subevent`` This signal is sent out to display additional information on the frontpage below the list of products if the front page is shown in the widget. -As with all plugin signals, the ``sender`` keyword argument will contain the event. The +As with all event plugin signals, the ``sender`` keyword argument will contain the event. The receivers are expected to return HTML. """ @@ -393,7 +393,7 @@ Arguments: 'request' If any receiver of this signal returns ``True``, all input fields during checkout (contact data, invoice address, confirmations) will be optional, except for questions. Use with care! -As with all plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` +As with all event plugin signals, the ``sender`` keyword argument will contain the event. A ``request`` argument will contain the request object. """ diff --git a/src/pretix/presale/style.py b/src/pretix/presale/style.py index c19d41cc1..bbde358e7 100644 --- a/src/pretix/presale/style.py +++ b/src/pretix/presale/style.py @@ -67,7 +67,7 @@ register_event_fonts = EventPluginSignal() """ Return a dictionaries of the following structure. Paths should be relative to static root or an absolute URL. In the latter case, the fonts won't be available for PDF-rendering. -As with all plugin signals, the ``sender`` keyword argument will contain the event. +As with all event plugin signals, the ``sender`` keyword argument will contain the event. { "font name": {