f2f4a2f8bd
Previously, if users of our code put the API folder in their pyshared they would have to import it as "humbug.humbug". By moving Humbug's API into a directory named "humbug" and moving the API into __init__, you can just "import humbug". (imported from commit 1d2654ae57f8ecbbfe76559de267ec4889708ee8)
64 lines
2 KiB
Plaintext
64 lines
2 KiB
Plaintext
#### Dependencies
|
|
|
|
The Humbug API Python bindings require the following Python libraries:
|
|
|
|
* simplejson
|
|
* requests (version >= 0.12)
|
|
|
|
#### Using the API
|
|
|
|
For now, the only fully supported API operation is sending a message.
|
|
The other API queries work, but are under active development, so
|
|
please make sure we know you're using them so that we can notify you
|
|
as we make any changes to them.
|
|
|
|
The easiest way to use these API bindings is to base your tools off
|
|
of the example tools under api/examples in this distribution.
|
|
|
|
If you place your API key in `~/.humbugrc` the Python API bindings will
|
|
automatically read it in. The format of the config file is as follows:
|
|
|
|
[api]
|
|
key=<api key from the web interface>
|
|
email=<your email address>
|
|
|
|
You can obtain your Humbug API key from the Humbug settings page.
|
|
|
|
A typical simple bot sending API messages will look as follows:
|
|
|
|
At the top of the file:
|
|
|
|
# Make sure the Humbug API distribution's root directory is in sys.path, then:
|
|
import humbug
|
|
humbug_client = humbug.Client(email="your_email@example.com")
|
|
|
|
When you want to send a message:
|
|
|
|
message = {
|
|
"type": "stream",
|
|
"to": ["support"],
|
|
"subject": "your subject",
|
|
"content": "your content",
|
|
}
|
|
humbug_client.send_message(message)
|
|
|
|
Additional examples:
|
|
|
|
client.send_message({'type': 'stream', 'content': 'Humbug rules!',
|
|
'subject': 'feedback', 'to': ['support']})
|
|
client.send_message({'type': 'private', 'content': 'Humbug rules!',
|
|
'to': ['user1@example.com', 'user2@example.com']})
|
|
|
|
send_message() returns a dict guaranteed to contain the following
|
|
keys: msg, result. For successful calls, result will be "success" and
|
|
msg will be the empty string. On error, result will be "error" and
|
|
msg will describe what went wrong.
|
|
|
|
#### Sending messages
|
|
|
|
You can use the included `api/bin/humbug-send` script to send messages via the
|
|
API directly from existing scripts.
|
|
|
|
humbug-send hamlet@example.com cordelia@example.com -m \
|
|
"Conscience doth make cowards of us all."
|