Time machine mode [Z#23129725] (#3961)

Allows organizers to test their shop as if it were a different date and time.

Implemented using a time_machine_now() function which is used instead of regular now(), which can overlay the real date time with a value from a ContextVar, assigned from a session value in EventMiddleware.

For more information, see doc/development/implementation/timemachine.rst

---------

Co-authored-by: Richard Schreiber <schreiber@rami.io>
Co-authored-by: Raphael Michel <michel@rami.io>

doc/development/implementation/index.rst

@@ -19,3 +19,4 @@ Contents:
    permissions
    logging
    locking
+   timemachine

doc/development/implementation/timemachine.rst

@@ -0,0 +1,32 @@
+Time machine mode
+=================
+
+In test mode, pretix provides a "time machine" feature which allows event organizers
+to test their shop as if it were a different date and time. To enable this feature, they can
+click on the "time machine"-link in the test mode warning box on the event page.
+
+Internally, this time machine mode is implemented by calling our custom :py:meth:`time_machine_now()`
+function instead of :py:meth:`django.utils.timezone.now()` in all places where the fake time should be
+taken into account. If you add code that uses the current date and time for checking whether some
+product can be bought, you should use :py:meth:`time_machine_now`.
+
+.. autofunction:: pretix.base.timemachine.time_machine_now
+
+Background tasks
+----------------
+
+The time machine datetime is passed through the request flow via a thread-local variable (ContextVar).
+Therefore, if you call a background task in the order process, where time_machine_now should be
+respected, you need to pass it through manually as shown in the example below:
+
+.. code-block:: python
+
+    @app.task()
+    def my_task(self, override_now_dt: datetime=None) -> None:
+        with time_machine_now_assigned(override_now_dt):
+            # ...do something that uses time_machine_now()
+
+    my_task.apply_async(kwargs={'override_now_dt': time_machine_now(default=None)})
+
+
+.. autofunction:: pretix.base.timemachine.time_machine_now_assigned

doc/development/implementation/urlconfig.rst

@@ -90,6 +90,10 @@ as its first argument and can be used like this::
     <a href="{% eventurl request.event "presale:event.checkout" step="payment" %}">Pay</a>
     <a href="{% abseventurl request.event "presale:event.checkout" step="payment" %}">Pay</a>
 
+To generate absolute URLs on the main domain, you can use the ``absurl`` template tag::
+
+    {% load eventurl %}
+    <a href="{% absmainurl "control:event.settings" organizer=request.event.organizer.slug event=request.event.slug %}">Event settings</a>
 
 Implementation details
 ----------------------