<commit_before>"""
============
django-slack
============

-------------------------------------
Seamless Slack integration for Django
-------------------------------------

This project provides easy-to-use integration between
`Django <http://www.djangoproject.com/>`_ projects and the
`Slack <https://www.slack.com>`_ group chat and IM tool.

* Uses the templating system, rather than constructing messages "by hand" in
  your ``views.py`` and ``models.py``.

* Easily enabled and disabled in certain environments, preventing DRY
  violations by centralising the logic to avoid sending messages in development
  or staging environments.

* Pluggable backend system for greater control over exactly how messages are
  transmitted to the Slack API (eg. sent asynchronously using your queuing
  system)

Installation
------------

#. Add ``django_slack`` to ``INSTALLED_APPS``.

#. Ensure ``django.template.loaders.app_directories.Loader`` is in your
   ``TEMPLATE_LOADERS``.

Usage
-----

To send a messsage::

    from django_slack import slack_message

    slack_message('path/to/my_message.slack', {
        'foo': Foo.objects.get(pk=17),
    })

Where ``path/to/my_message.slack`` (in your templates directory) might
contain::

    {% extends django_slack %}

    {% block text %}
    Message text here: {{ foo.bar|urlize }}
    {% endblock %}

    {% block channel %}
    #mychannel
    {% endblock %}

Required blocks:

* **text** -- contains the message you wish to send. HTML entities are automatically escaped.

Required blocks which can be defaulted globally and overridden (see *Configuration*):

* **channel** -- ID or name of the room.
* **username** -- Name the message will appear be sent from.
* **token** -- Your Slack authentication token (eg. ``<KEY>``)

Optional blocks:

* **icon_url** -- URL to an image to use as the icon for this message. (eg. `http://lorempixel.com/48/48`)
* **icon_emoji** -- Emoji to use as the icon for this message (eg. `:chart_with_upwards_trend:`). Overrides `icon_url`.


Configuration
-------------

``SLACK_TOKEN``
~~~~~~~~~~~~~~~

Default: ``None``

Your Slack authentication token. You can override on a per-message level by
specifying a ``{% block token %}{% endblock %}`` in your message templates.<commit_msg>Addition of docs exampling Attachments usage.<commit_after>"""
============
django-slack
============

-------------------------------------
Seamless Slack integration for Django
-------------------------------------

This project provides easy-to-use integration between
`Django <http://www.djangoproject.com/>`_ projects and the
`Slack <https://www.slack.com>`_ group chat and IM tool.

* Uses the templating system, rather than constructing messages "by hand" in
  your ``views.py`` and ``models.py``.

* Easily enabled and disabled in certain environments, preventing DRY
  violations by centralising the logic to avoid sending messages in development
  or staging environments.

* Pluggable backend system for greater control over exactly how messages are
  transmitted to the Slack API (eg. sent asynchronously using your queuing
  system)

Installation
------------

#. Add ``django_slack`` to ``INSTALLED_APPS``.

#. Ensure ``django.template.loaders.app_directories.Loader`` is in your
   ``TEMPLATE_LOADERS``.

Usage
-----

To send a messsage::

    from django_slack import slack_message

    slack_message('path/to/my_message.slack', {
        'foo': Foo.objects.get(pk=17),
    })

Where ``path/to/my_message.slack`` (in your templates directory) might
contain::

    {% extends django_slack %}

    {% block text %}
    Message text here: {{ foo.bar|urlize }}
    {% endblock %}

    {% block channel %}
    #mychannel
    {% endblock %}

Required blocks:

* **text** -- contains the message you wish to send. HTML entities are automatically escaped.

Required blocks which can be defaulted globally and overridden (see *Configuration*):

* **channel** -- ID or name of the room.
* **username** -- Name the message will appear be sent from.
* **token** -- Your Slack authentication token (eg. ``<KEY>``)

Optional blocks:

* **icon_url** -- URL to an image to use as the icon for this message. (eg. `http://lorempixel.com/48/48`)
* **icon_emoji** -- Emoji to use as the icon for this message (eg. `:chart_with_upwards_trend:`). Overrides `icon_url`.

Richly-formatted messages
--------------------------
You can send any number of richly-formatted messages as attachments with a given slack message.

To send a message with an attachment.

1. Assemble your attachments as follows::

    attachments = [
        {
         'title': "Richly-formatted message title',
         'text': 'Richly-formatted message body.'
        }
    ]

2. Pass in your attachments to `slack_message` as an optional argument::

    from django_slack import slack_message
    
    slack_message('path/to/my_message.slack', {
        'foo': Foo.objects.get(pk=17),
    }, attachments)

You can assemble and send any number of message objects within the `attachments` list.  
For more information on all available formatting options, please visit the `Slack API Attachments Docs <https://api.slack.com/docs/attachments>`_

Configuration
-------------

``SLACK_TOKEN``
~~~~~~~~~~~~~~~

Default: ``None``

Your Slack authentication token. You can override on a per-message level by
specifying a ``{% block token %}{% endblock %}`` in your message templates.
{'fraction_non_alphanumeric': 0.16105769230769232, 'fraction_numerical': 0.0029585798816568047, 'mean_word_length': 3.1897753679318357, 'pattern_counts': {'":': 0, '<': 10, '<?xml version=': 0, '>': 10, 'https://': 3, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '888086', 'n_tokens_mistral': 1592, 'n_tokens_neox': 1515, 'n_words': 562}