thorn — Thorn 1.3.0 documentation

# thorn

Python Webhook and Event Framework

class `thorn.` `Thorn`(dispatcher=None, set_as_current=True)
  `Dispatcher`
  `Event`
  `ModelEvent`
  `Request`
  `Settings`
  `Subscriber`
  `Subscribers`
  `autodetect_env`(apply=<operator.methodcaller object>)
  `config`
  `dispatcher`
  `dispatchers` = {u'default': u'thorn.dispatch.base:Dispatcher', u'celery': u'thorn.dispatch.celery:Dispatcher', u'disabled': u'thorn.dispatch.disabled:Dispatcher'}
  `env`
  `environments` = set([u'thorn.environment.django:DjangoEnv'])
  `event_cls` = u'thorn.events:Event'
  `hmac_sign`
  `model_event_cls` = u'thorn.events:ModelEvent'
  `model_reverser`
  `request_cls` = u'thorn.request:Request'
  `reverse`
  `set_current`()
  `set_default`()
  `settings`
  `settings_cls` = u'thorn.conf:Settings'
  `signals`
  `subclass_with_self`(Class, name=None, attribute=u'app', reverse=None, keep_reduce=False, **kw)

    Subclass an app-compatible class by setting its app attribute to this instance.

    App-compatible means the class has an ‘app’ attribute providing the default app, e.g.: `class Foo(object): app = None`.

    Parameters: | Class – The class to subclass. name – Custom name for the target subclass. attribute – Name of the attribute holding the app. Default is `"app"`. reverse – Reverse path to this object used for pickling purposes. E.g. for `app.AsyncResult` use `"AsyncResult"`. keep_reduce – If enabled a custom `__reduce__` implementation will not be provided.

  `webhook_model`

class `thorn.` `Event`(name, timeout=None, dispatcher=None, retry=None, retry_max=None, retry_delay=None, app=None, recipient_validators=None, subscribers=None, request_data=None, allow_keepalive=None, **kwargs)

  Webhook Event.

  - Parameters: | name – Name of this event. Namespaces can be dot-separated, and if so subscribers can glob-match based on the parts in the name (e.g. `"order.created"`). timeout – Default request timeout for this event. retry – Enable/disable retries when dispatching this event fails (disabled by default). retry_max – Max number of retries (3 by default). retry_delay – Delay between retries (60 seconds by default). recipient_validators – List of functions validating the recipient URL string. Functions must return False if the URL is blocked. Default is to only allow HTTP and HTTPS, with respective reserved ports 80 and 443, and to block internal IP networks, and can be changed using the `THORN_RECIPIENT_VALIDATORS` setting:
        recipient_validators=[
            thorn.validators.block_internal_ips(),
            thorn.validators.ensure_protocol('http', 'https'),
            thorn.validators.ensure_port(80, 443),
        ]
  WARNING: `block_internal_ips()` will only test for reserved internal networks, and not private networks with a public IP address. You can block those using `block_cidr_network`. subscribers – Additional subscribers, as a list of URLs, subscriber model objects, or callback functions returning these request_data – Optional mapping of extra data to inject into event payloads, allow_keepalive – Flag to disable HTTP connection keepalive for this event only. Keepalive is enabled by default.

  `allow_keepalive` = True
  `app` = None
  `dispatcher`
  `prepare_payload`(data)
  `prepare_recipient_validators`(validators)
  `prepared_recipient_validators`
  `recipient_validators` = None
  `send`(data, sender=None, on_success=None, on_error=None, timeout=None, on_timeout=None)

    Send event to all subscribers.

    Parameters: | data – Event payload (must be json serializable). sender – Optional event sender, as a `User` instance. timeout – Specify custom HTTP request timeout overriding the `THORN_EVENT_TIMEOUT` setting. on_success – Callback called for each HTTP request if the request succeeds. Must take single `Request` argument. on_timeout – Callback called for each HTTP request if the request times out. Takes two arguments: a `Request`, and the time out exception instance. on_error – Callback called for each HTTP request if the request fails. Takes two arguments: a `Request` argument, and the error exception instance. context – Extra context to pass to subscriber callbacks

  `subscribers`

class `thorn.` `ModelEvent`(name, *args, **kwargs)

  Event related to model changes.

  This event type follows a specific payload format:

      {"event": "(str)event_name",
       "ref": "(URL)model_location",
       "sender": "(User pk)optional_sender",
       "data": {"event specific data": "value"}}

  Parameters: | name – Name of event. reverse – A function that takes a model instance and returns the canonical URL for that resource. sender_field – Field used as a sender for events, e.g. `"account.user"`, will use `instance.account.user`. $field__$op – Optional filter arguments to filter the model instances to dispatch for. These keyword arguments can be defined just like the arguments to a Django query set, the only difference being that you have to specify an operator for every field: this means `last_name="jerry"` does not work, and you have to use `last_name__eq="jerry"` instead. See `Q` for more information. signal_dispatcher – Custom `signal_dispatcher` used to connect this event to a model signal.

  `connect_model`(model)
  `dispatches_on_change`()
  `dispatches_on_create`()
  `dispatches_on_delete`()
  `dispatches_on_m2m_add`(related_field)
  `dispatches_on_m2m_clear`(related_field)
  `dispatches_on_m2m_remove`(related_field)
  `instance_data`(instance)

    Get event data from `instance.webhook_payload()`.

  `instance_sender`(instance)

    Get event `sender` from model instance.

  `on_signal`(instance, **kwargs)
  `send`(instance, data=None, sender=None, **kwargs)

    Send event for model `instance`.

    Parameters: | data – Event specific data.

    See `Event.send()` for more arguments supported.

  `send_from_instance`(instance, context={}, **kwargs)
  `should_dispatch`(instance, **kwargs)
  `signal_dispatcher`
  `to_message`(data, instance=None, sender=None, ref=None)

class `thorn.` `Q`(*args, **kwargs)

  Object query node.

  This class works like `django.db.models.Q`, but is used for filtering regular Python objects instead of database rows.

  Examples

  - Match object with `last_name` attribute set to “Costanza”:

        Q(last_name__eq="Costanza")

  - Match object with `author.last_name` attribute set to “Benes”:

        Q(author__last_name__eq="Benes")

  - You are not allowed to specify any key without an operator, event though the following would be fine using Django`s Q objects:

        Q(author__last_name="Benes")   # <-- ERROR, will raise ValueError

  - Attributes can be nested arbitrarily deep:

        Q(a__b__c__d__e__f__g__x__gt=3.03)

  - The special `*__eq=True` means “match any true-ish value”:

        Q(author__account__is_staff__eq=True)

  - Similarly the `*__eq=False` means “match any false-y” value”:

        Q(author__account__is_disabled=False)

  See Supported operators.

  Returns: | `collections.Callable`, to match an object with the given predicates, call the return value with the object to match: `Q(x__eq==808)(obj)`.

  `apply_op`(getter, op, rhs, obj, *args)
  `apply_trans_op`(getter, op, rhs, obj)
  `branches` = {False: <built-in function truth>, True: <built-in function not_>}
  `compile`(fields)
  `compile_node`(field)

    Compiles node into a cached function that performs the match.

    Returns: | unary `collections.Callable` taking the object to match.

  `compile_op`(lhs, rhs, opcode)
  `gate`
  `gates` = {u'AND': <built-in function all>, u'OR': <built-in function any>}
  `operators` = {u'gt': <built-in function gt>, u'is': <built-in function is_>, u'now_eq': <function compare>, u'now_endswith': <function compare>, u'endswith': <function endswith>, u'now_gt': <function compare>, u'in': <function reversed>, u'eq': <built-in function eq>, u'now_ne': <function compare>, u'gte': <built-in function ge>, u'contains': <built-in function contains>, u'ne': <built-in function ne>, u'lt': <built-in function lt>, u'now_not_in': <function compare>, u'startswith': <function startswith>, u'now_lt': <function compare>, u'now_lte': <function compare>, u'now_gte': <function compare>, u'not': <function <lambda>>, u'true': <function <lambda>>, u'not_in': <function reversed>, u'is_not': <built-in function is_not>, u'now_in': <function compare>, u'now_is': <function compare>, u'now_is_not': <function compare>, u'lte': <built-in function le>, u'now_contains': <function compare>, u'now_startswith': <function compare>}
  `prepare_opcode`(O, rhs)
  `prepare_statement`(lhs, rhs)
  `stack`

class `thorn.` `model_reverser`(view_name, *args, **kwargs)

  Describes how to get the canonical URL for a model instance.

  Examples

      >>> model_reverser('article-detail', uuid='uuid')
      # for an article instance will generate the URL by calling:
      >>> reverse('article_detail', kwargs={'uuid': instance.uuid})

      >>> model_reverser('article-detail', 'category.name', uuid='uuid')
      # for an article instance will generate the URL by calling:
      >>> reverse('article-detail',
      ...         args=[instance.category.name],
      ...         kwargs={'uuid': instance.uuid},
      ... )

class `thorn.` `webhook_model`(on_create=None, on_change=None, on_delete=None, reverse=None, sender_field=None, **kwargs)

  Decorates models to send webhooks based changes to that model.

  Parameters: | on_create – Event to dispatch whenever an instance of this model is created (`post_save`). on_change – Event to dispatch whenever an instance of this model is changed (`post_save`). on_delete – Event to dispatch whenever an instance of this model is deleted (`post_delete`). on_$event – Additional user defined events., sender_field – Default field used as a sender for events, e.g. `"account.user"`, will use `instance.account.user`. Individual events can override the sender field user. reverse – A `thorn.reverse.model_reverser` instance (or any callable taking an model instance as argument), that describes how to get the URL for an instance of this model. Individual events can override the reverser used.

  Examples

  Simple article model, where the URL reference is retrieved by `reverse('article-detail', kwargs={'uuid': article.uuid})`:

      @webhook_model(
          on_create=ModelEvent('article.created'),
          on_change=ModelEvent('article.changed'),
          on_delete=ModelEvent('article.removed'),
          on_deactivate=ModelEvent(
              'article.deactivate', deactivated__eq=True,
          )
          reverse=model_reverser('article-detail', uuid='uuid'),
      )
      class Article(models.Model):
          uuid = models.UUIDField()

  The URL may not actually exist after deletion, so maybe we want to point the reference to something else in that special case, like a category that can be reversed by doing `reverse('category-detail', args=[article.category.name])`.

  We can do that by having the `on_delete` event override the reverser used for that event only:

      @webhook_model(
          on_create=ModelEvent('article.created'),
          on_change=ModelEvent('article.changed'),
          on_delete=ModelEvent(
              'article.removed',
              reverse=model_reverser('category-detail', 'category.name'),
          ),

          on_hipri_delete=ModelEvent(
              'article.internal_delete', priority__gte=30.0,
          ).dispatches_on_delete(),

          reverse=model_reverser('article-detail', uuid='uuid'),
      )
      class Article(model.Model):
          uuid = models.UUIDField()
          category = models.ForeignKey('category')

  `connect_events`(events, **kwargs)
  `contribute_to_event`(event)
  `data`
  `update_events`(events, **kwargs)