refactor: move some utils into core

src/pretix/base/datasync/datasync.py

@@ -150,7 +150,6 @@ StaticMapping = namedtuple('StaticMapping', ('pk', 'pretix_model', 'external_obj
 
 class OutboundSyncProvider:
     max_attempts = 5
-    syncer_class = None
 
     def __init__(self, event):
         self.event = event
@@ -197,9 +196,39 @@ class OutboundSyncProvider:
         info = cls.get_external_link_info(event, external_link_href, external_link_display_name)
         return make_link(info, '{val}')
 
+    """
+    Optionally override to configure a different retry backoff behavior
+    """
     def next_retry_date(self, sq):
         return datetime.now() + timedelta(hours=1)
 
+    """
+    Optionally override this method to exclude certain orders from sync by returning False
+    """
+    def order_valid_for_sync(self, order):
+        return True
+
+    """
+    Implementations must override this property to provide the data mappings as a list of objects.
+
+    They can return instances of the StaticMapping namedtuple defined above, or create their own
+    class (e.g. a Django model).
+
+    The returned objects must have at least the following properties:
+    - pk:                   unique identifier
+    - pretix_model:         which pretix model to use as data source in this mapping. possible values are
+                            the keys of sourcefields.AVAILABLE_MODELS
+    - external_object_type: destination object type in the target system. opaque string of maximum 128 characters.
+    - pretix_pk:            which pretix data field should be used to identify the mapped object. any
+                            DataFieldInfo.key returned by sourcefields.get_data_fields for the combination of
+                            Event and pretix_model
+    - external_pk:          destination identifier field in the target system
+    - property_mapping:     mapping configuration as generated by PropertyMappingFormSet.to_property_mapping_json()
+    """
+    @property
+    def mappings(self):
+        raise NotImplementedError
+
     def sync_queued_orders(self, queued_orders):
         for sq in queued_orders:
             try:
@@ -240,13 +269,6 @@ class OutboundSyncProvider:
                 })
                 sq.delete()
 
-    def order_valid_for_sync(self, order):
-        return True
-
-    @property
-    def mappings(self):
-        raise NotImplementedError
-
     @cached_property
     def data_fields(self):
         return {
@@ -284,7 +306,25 @@ class OutboundSyncProvider:
     This method is called for each object that needs to be created/updated in the external system -- which these are is
     determined by the implementation of the `mapping` property.
 
-    TODO: describe the parameters
+    :param pk_field: Identifier field in the target system as provided in mapping.external_pk
+    :param pk_value: Identifier contents as retrieved from the property specified by mapping.pretix_pk of the model
+                     specified by mapping.pretix_model
+    :param properties: All properties defined in mapping.property_mapping, as list of three-tuples
+                       (external_field, value, overwrite)
+    :param inputs: All pretix model instances from which data can be retrieved for this mapping
+    :param mapping: The mapping object as returned by self.mappings
+    :param mapped_objects: Information about objects that were synced in the same sync run, by mapping definitions
+                           *before* the current one in order of self.mappings.
+                           Type is a dictionary {mapping.pk: [list of return values of this method]}
+                           Useful to create associations between objects in the target system.
+    :return: {
+                "object_type": mapping.external_object_type,
+                "pk_field": pk_field,
+                "pk_value": pk_value,
+                "external_link_href": "https://external-system.example.com/backend/link/to/contact/123/",
+                "external_link_display_name": "Contact #123 - Jane Doe",
+                "...optionally further values you need in mapped_objects for association": 123456789,
+             }
 
     This method needs to be idempotent, i.e. calling it multiple times with the same input values should create
     only a single object in the target system.