============================================================
djhipchat2: The most complete HipChat integration for Django
============================================================
djhipchat2 is the Swiss Army knife for HipChat integration. It provides:
- Configurable backend support, including local memory for testing
- Logging integration
- Out-of-the-box integration with Celery_ for asynchronous sending
- Management command
- Testing
Installation
============
1. Install: ``pip install djhipchat2``
2. Add ``djhipchat2`` to your ``INSTALLED_APPS``.
3. Configure your backend, or leave it as the default.
Usage
=====
djhipchat.send_message
----------------------
This will send a HipChat message using the default backend. The parameters mirror those of the HipChat messaging API, defined here: https://www.hipchat.com/docs/api/method/rooms/message.
These are the parameters:
* ``room_id``: The ID of the HipChat room to send to. Room IDs can be found here: https://{{your-account}}.hipchat.com/rooms/ids
* ``sender``: The sender of the message. Must be less than 15 characters long. May contain letters, numbers, -, _, and spaces. (Note: in the HipChat API this is specified as ``from``. It's been changed so it's not a Python keyword.)
* ``message``: The text or HTML of the message.
* ``message_format``: Should be ``text`` or ``html``. The default is ``html``
* ``notify``: Should be `True` if the message should trigger a notification in the room. The default is ``False``
* ``color``: The color of the message. One of "yellow", "red", "green", "purple", "gray", or "random". The default is "yellow".
djhipchat.get_backend
---------------------
Get a reference to a HipChat backend. Each backend has one defined method: ``send_message`` which has the same parameters as ``djhipchat.send_message``.
Logger
------
Integrate HipChat into your server logging: this defines a logging handler that sends the message to a HipChat room. You can configure a logger to notify members of the room, or also configure multiple colors for log levels using the same handler. Here is a sample:
::
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'handlers': {
'djhipchat': {
'level': 'INFO',
'class': 'djhipchat.logger.HipChatHandler',
'token': '{{your_token_here}}',
'room' : '{{your_room_id_here}}',
'sender': 'Myapp',
'notify': True,
'color':'green',
'colors': {
'ERROR':'red',
'CRITICAL':'red',
'WARNING':'yellow',
}
}
},
'loggers': {
'test_handler': {
'handlers': ['djhipchat'],
'level': 'INFO',
'propagate': False,
},
}
}
This is inspired by: https://gist.github.com/hugorodgerbrown/3176710
Management command
------------------
This app provides a management command to easily send a message to the configured backend. The usage is simple: ``python manage.py hipchat <room_id> <message>``
Options are available at: ``python manage.py help hipchat``
Configuration
=============
HIPCHAT_BACKEND
---------------
Specifies the default backend to use. The default is ``djhipchat.backends.locmem.HipChatBackend``
HIPCHAT_API_TOKEN
-----------------
Specifies the HipChat API token. This is theoretically optional except for the request backend, but that's probably what you want to use in production anyway.
HIPCHAT_DEFAULT_SENDER
----------------------
The default sender if not specified in a send_message call. If not specified, the default is "Django".
HIPCHAT_CELERY_BACKEND
----------------------
When using the Celery backend, it needs a "synchronous" backend to actually send the message. There is no default, so you must specify this in order to use the Celery backend.
Backends
========
djhipchat.backends.celery.HipChatBackend
----------------------------------------
This backend sends all messages through a Celery_ task. In order to use this backend, you must have celery installed and specify a synchronous backend in the ``HIPCHAT_CELERY_BACKEND`` setting.
djhipchat.backends.dummy.HipChatBackend
---------------------------------------
Just what is sounds like: this backend does nothing.
djhipchat.backends.locmem.HipChatBackend
----------------------------------------
Similar to the locmem email backend in Django, this collects all messages into an array at ``djhipchat.sent_messages``. You can use this for testing.
djhipchat.backends.request.HipChatBackend
-----------------------------------------
This is the default backend, which actually sends your message to HipChat.
.. _Celery: http://www.celeryproject.org/