From dfb8a16a555f047945a0af1aa405cf67164eaaa5 Mon Sep 17 00:00:00 2001 From: acrefoot Date: Wed, 29 May 2013 14:00:27 -0400 Subject: [PATCH] [api version bump] Update API documentation in the example scripts Give better examples, and rewrite options parsing to be more consistent across examples. Make it more obvious that you can use "--user" and "--api-key" with our python examples. This bumps our python bindings to v0.1.9 (imported from commit 297468088f864b7d585e567dc45523ea681f1856) --- README | 16 ++++++++++-- bin/humbug-send | 3 +++ demos/rss-bot | 17 +++--------- demos/twitter-bot | 12 ++------- demos/twitter-search-bot | 13 ++-------- examples/curl-examples | 8 +++--- examples/edit-message | 26 +++++++++++-------- examples/get-public-streams | 6 +++-- examples/humbugrc | 4 +-- examples/list-members | 4 ++- examples/list-subscriptions | 6 +++-- examples/print-messages | 8 +++--- examples/print-next-message | 6 +++-- examples/send-message | 16 ++++++------ examples/subscribe | 8 +++--- examples/unsubscribe | 8 +++--- humbug/__init__.py | 6 ++--- integrations/git/humbug_git_config.py | 2 +- .../org/humbug/jira/HumbugListener.groovy | 4 +-- integrations/nagios/humbugrc.example | 2 +- integrations/svn/humbug_svn_config.py | 2 +- integrations/trac/humbug_trac_config.py | 2 +- 22 files changed, 92 insertions(+), 87 deletions(-) diff --git a/README b/README index 86d1a1e..755db36 100644 --- a/README +++ b/README @@ -30,7 +30,12 @@ file is as follows: key= email= -You can obtain your Humbug API key from the Humbug settings page. +Alternatively, you may explicitly use "--user" and "--api-key" in our +examples, which is especially useful if you are running several bots +which share a home directory. + +You can obtain your Humbug API key, create bots, and manage bots all +from your Humbug [settings page](https://humbughq.com/#settings). A typical simple bot sending API messages will look as follows: @@ -38,7 +43,7 @@ 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") + humbug_client = humbug.Client(email="your-bot@example.com") When you want to send a message: @@ -69,3 +74,10 @@ API directly from existing scripts. humbug-send hamlet@example.com cordelia@example.com -m \ "Conscience doth make cowards of us all." + +Alternatively, if you don't want to use your ~/.humbugrc file: + + humbug-send --user shakespeare-bot@example.com \ + --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \ + hamlet@example.com cordelia@example.com -m \ + "Conscience doth make cowards of us all." diff --git a/bin/humbug-send b/bin/humbug-send index dc8d593..cb4a4ca 100755 --- a/bin/humbug-send +++ b/bin/humbug-send @@ -58,6 +58,9 @@ def main(argv=None): Examples: %prog --stream denmark --subject castle -m "Something is rotten in the state of Denmark." %prog hamlet@example.com cordelia@example.com -m "Conscience doth make cowards of us all." + + These examples assume you have a proper '~/.humbugrc'. You may also set your credentials with the + '--user' and '--api-key' arguments. """ sys.path.append(os.path.join(os.path.dirname(__file__), '..')) diff --git a/demos/rss-bot b/demos/rss-bot index 162d474..3c8e581 100755 --- a/demos/rss-bot +++ b/demos/rss-bot @@ -25,7 +25,8 @@ To use this script: 1. Create an RSS feed file containing 1 feed URL per line (default feed file location: ~/.cache/humbug-rss/rss-feeds) 2. Subscribe to the stream that will receive RSS updates (default stream: rss) -3. Test the script by running it manually, like this: +3. create a ~/.humbugrc, or specify user and api-key with command line arguments +4. Test the script by running it manually, like this: /usr/local/share/humbug/demos/rss-bot @@ -40,14 +41,6 @@ stream every 5 minutes is: */5 * * * * /usr/local/share/humbug/demos/rss-bot""" parser = optparse.OptionParser(usage) -parser.add_option('--email', - dest='email', - help='The email address for your Humbug account.', - metavar='EMAIL') -parser.add_option('--api-key', - dest='api_key', - help='API key for that user [default: read ~/.humbug-api-key]', - action='store') parser.add_option('--stream', dest='stream', help='The stream to which to send RSS messages.', @@ -63,11 +56,7 @@ parser.add_option('--feed-file', help='The file containing a list of RSS feed URLs to follow, one URL per line', default=os.path.join(RSS_DATA_DIR, "rss-feeds"), action='store') -parser.add_option('--site', - dest='site', - default="https://humbughq.com", - help=optparse.SUPPRESS_HELP, - action='store') +parser.add_option_group(humbug.generate_option_group(parser)) (opts, args) = parser.parse_args() def mkdir_p(path): diff --git a/demos/twitter-bot b/demos/twitter-bot index 0e0d95d..cbe9d0f 100755 --- a/demos/twitter-bot +++ b/demos/twitter-bot @@ -16,7 +16,7 @@ def write_config(config, since_id, user): parser = optparse.OptionParser(r""" -%prog --user foo@humbughq.com --twitter-id twitter_handle +%prog --user foo@example.com --api-key 0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 --twitter-id twitter_handle Slurp tweets on your timeline into a specific humbug stream. @@ -44,18 +44,9 @@ parser = optparse.OptionParser(r""" Depends on: twitter-python """) -parser.add_option('--user', - help='Humbug user email address', - metavar='EMAIL') -parser.add_option('--api-key', - help='API key for that user [default: read ~/.humbugrc]') parser.add_option('--twitter-id', help='Twitter username to poll for new tweets from"', metavar='URL') -parser.add_option('--site', - default="https://humbughq.com", - help='Humbug site [default: https://humbughq.com]', - metavar='URL') parser.add_option('--stream', help='Default humbug stream to write tweets to') parser.add_option('--limit-tweets', @@ -63,6 +54,7 @@ parser.add_option('--limit-tweets', type='int', help='Maximum number of tweets to push at once') +parser.add_option_group(humbug.generate_option_group(parser)) (options, args) = parser.parse_args() if not options.twitter_id: diff --git a/demos/twitter-search-bot b/demos/twitter-search-bot index 2475cf6..c33a66d 100755 --- a/demos/twitter-search-bot +++ b/demos/twitter-search-bot @@ -18,7 +18,7 @@ def write_config(config, since_id): parser = optparse.OptionParser(r""" -%prog --user foo@humbughq.com --search="@nprnews,quantum physics" +%prog --user foo@humbughq.com --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 --search="@nprnews,quantum physics" Send Twitter search results to a Humbug stream. @@ -63,20 +63,10 @@ Make sure to go the application you created and click "create my access token" as well. Fill in the values displayed. """) -parser.add_option('--user', - help='Humbug user email address', - metavar='EMAIL') -parser.add_option('--api-key', - help='API key for that user [default: read ~/.humbugrc]') parser.add_option('--search', dest='search_terms', help='Terms to search on', action='store') -parser.add_option('--site', - dest='site', - default="https://humbughq.com", - help=optparse.SUPPRESS_HELP, - action='store') parser.add_option('--stream', dest='stream', help='The stream to which to send tweets', @@ -87,6 +77,7 @@ parser.add_option('--limit-tweets', type='int', help='Maximum number of tweets to send at once') +parser.add_option_group(humbug.generate_option_group(parser)) (opts, args) = parser.parse_args() if not opts.search_terms: diff --git a/examples/curl-examples b/examples/curl-examples index 58513e6..6d39afc 100755 --- a/examples/curl-examples +++ b/examples/curl-examples @@ -2,13 +2,13 @@ # Two quick API tests using curl curl https://humbughq.com/api/v1/send_message \ - -d "api-key=YOUR_API_KEY" \ - -d "email=YOUR_EMAIL" \ + -d "api-key=BOT_API_KEY" \ + -d "email=BOT_EMAIL" \ -d "type=private" -d "content=test" \ -d "to=RECIPIENT_EMAIL" curl https://humbughq.com/api/v1/get_messages \ - -d "api-key=YOUR_API_KEY" \ - -d "email=YOUR_EMAIL" + -d "api-key=BOT_API_KEY" \ + -d "email=BOT_EMAIL" # Or replace https://humbughq.com with your local test instance diff --git a/examples/edit-message b/examples/edit-message index bf9d4aa..182b9d6 100755 --- a/examples/edit-message +++ b/examples/edit-message @@ -25,25 +25,29 @@ import sys from os import path import optparse -usage = """edit-message [options] --message= --content= --subject= +usage = """edit-message [options] --message= --subject= --content= --user= --api-key= -Edits a message +Edits a message that you sent -Example: edit-message --message="348135" --subject="my subject" --message="test message" +Example: edit-message --message-id="348135" --subject="my subject" --content="test message" --user=othello-bot@example.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 + +You can omit --user and --api-key arguments if you have a properly set up ~/.humbugrc """ -parser = optparse.OptionParser(usage=usage) -parser.add_option('--subject', default="") -parser.add_option('--message', default="") -parser.add_option('--site', default='https://humbughq.com') -parser.add_option('--content', default="") -(options, args) = parser.parse_args() sys.path.insert(0, path.join(path.dirname(__file__), '..')) import humbug -client = humbug.Client(site=options.site) + +parser = optparse.OptionParser(usage=usage) +parser.add_option('--message-id', default="") +parser.add_option('--subject', default="") +parser.add_option('--content', default="") +parser.add_option_group(humbug.generate_option_group(parser)) +(options, args) = parser.parse_args() + +client = humbug.init_from_options(options) message_data = { - "message_id": options.message, + "message_id": options.message_id, } if options.subject != "": message_data["subject"] = options.subject diff --git a/examples/get-public-streams b/examples/get-public-streams index 20e2f19..3995b1d 100755 --- a/examples/get-public-streams +++ b/examples/get-public-streams @@ -25,11 +25,13 @@ import sys from os import path import optparse -usage = """get-public-streams --user= [options] +usage = """get-public-streams --user= --api-key= [options] Prints out all the public streams in the realm. -Example: get-public-streams --user=tabbott@humbughq.com +Example: get-public-streams --user=othello-bot@example.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 + +You can omit --user and --api-key arguments if you have a properly set up ~/.humbugrc """ sys.path.append(path.join(path.dirname(__file__), '..')) diff --git a/examples/humbugrc b/examples/humbugrc index 0636fe1..45fb0a8 100644 --- a/examples/humbugrc +++ b/examples/humbugrc @@ -1,4 +1,4 @@ ; Save this file as ~/.humbugrc [api] -key= -email= +key= +email= diff --git a/examples/list-members b/examples/list-members index d0aff93..3d61109 100755 --- a/examples/list-members +++ b/examples/list-members @@ -25,9 +25,11 @@ import sys from os import path import optparse -usage = """list-members [options] +usage = """list-members --user= --api-key= [options] List the names and e-mail addresses of the people in your realm. + +You can omit --user and --api-key arguments if you have a properly set up ~/.humbugrc """ sys.path.append(path.join(path.dirname(__file__), '..')) diff --git a/examples/list-subscriptions b/examples/list-subscriptions index cb41721..64e2a9b 100755 --- a/examples/list-subscriptions +++ b/examples/list-subscriptions @@ -25,11 +25,13 @@ import sys from os import path import optparse -usage = """list-subscriptions --user= [options] +usage = """list-subscriptions --user= --api-key= [options] Prints out a list of the user's subscriptions. -Example: list-subscriptions --user=tabbott@humbughq.com +Example: list-subscriptions --user=tabbott@humbughq.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 + +You can omit --user and --api-key arguments if you have a properly set up ~/.humbugrc """ sys.path.append(path.join(path.dirname(__file__), '..')) import humbug diff --git a/examples/print-messages b/examples/print-messages index 0fa531a..58acedc 100755 --- a/examples/print-messages +++ b/examples/print-messages @@ -25,11 +25,13 @@ import sys from os import path import optparse -usage = """print-messages --user= [options] +usage = """print-messages --user= --api-key= [options] -Prints out each message received by the indicated user. +Prints out each message received by the indicated bot or user. -Example: print-messages --user=tabbott@humbughq.com +Example: print-messages --user=tabbott@humbughq.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 + +You can omit --user and --api-key arguments if you have a properly set up ~/.humbugrc """ sys.path.append(path.join(path.dirname(__file__), '..')) import humbug diff --git a/examples/print-next-message b/examples/print-next-message index 2d6c07e..342e9cf 100755 --- a/examples/print-next-message +++ b/examples/print-next-message @@ -25,11 +25,13 @@ import sys from os import path import optparse -usage = """print-next-message --user= [options] +usage = """print-next-message --user= --api-key= [options] Prints out the next message received by the user. -Example: print-next-messages --user=tabbott@humbughq.com +Example: print-next-messages --user=tabbott@humbughq.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 + +You can omit --user and --api-key arguments if you have a properly set up ~/.humbugrc """ sys.path.append(path.join(path.dirname(__file__), '..')) import humbug diff --git a/examples/send-message b/examples/send-message index c6bba2c..0132ef3 100755 --- a/examples/send-message +++ b/examples/send-message @@ -24,30 +24,30 @@ import sys from os import path import optparse +import humbug -usage = """send-message [options] +usage = """send-message --user= --api-key= [options] Sends a test message to the specified recipients. -Example: send-message --sender=you@example.com --type=stream commits --subject="my subject" --message="test message" -Example: send-message --sender=you@example.com user1@example.com user2@example.com +Example: send-message --user=your-bot@example.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 --type=stream commits --subject="my subject" --message="test message" +Example: send-message --user=your-bot@example.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 user1@example.com user2@example.com + +You can omit --user and --api-key arguments if you have a properly set up ~/.humbugrc """ parser = optparse.OptionParser(usage=usage) -parser.add_option('--api-key') -parser.add_option('--sender') parser.add_option('--subject', default="test") parser.add_option('--message', default="test message") -parser.add_option('--site', default='https://humbughq.com') parser.add_option('--type', default='private') +parser.add_option_group(humbug.generate_option_group(parser)) (options, args) = parser.parse_args() if len(args) == 0: parser.error("You must specify recipients") sys.path.append(path.join(path.dirname(__file__), '..')) -import humbug client = humbug.Client( - email=options.sender, + email=options.user, api_key=options.api_key, verbose=True, site=options.site) diff --git a/examples/subscribe b/examples/subscribe index bac9c74..14b8931 100755 --- a/examples/subscribe +++ b/examples/subscribe @@ -25,12 +25,14 @@ import sys from os import path import optparse -usage = """subscribe --user= [options] --streams= +usage = """subscribe --user= --api-key= [options] --streams= Ensures the user is subscribed to the listed streams. -Examples: subscribe --user=tabbott@humbughq.com --streams=foo - subscribe --user=tabbott@humbughq.com --streams='foo bar' +Examples: subscribe --user=tabbott@humbughq.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 --streams=foo + subscribe --user=tabbott@humbughq.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 --streams='foo bar' + +You can omit --user and --api-key arguments if you have a properly set up ~/.humbugrc """ sys.path.append(path.join(path.dirname(__file__), '..')) import humbug diff --git a/examples/unsubscribe b/examples/unsubscribe index 3e23bed..455073f 100755 --- a/examples/unsubscribe +++ b/examples/unsubscribe @@ -25,12 +25,14 @@ import sys from os import path import optparse -usage = """unsubscribe --user= [options] --streams= +usage = """unsubscribe --user= --api-key= [options] --streams= Ensures the user is not subscribed to the listed streams. -Examples: unsubscribe --user=tabbott@humbughq.com --streams=foo - unsubscribe --user=tabbott@humbughq.com --streams='foo bar' +Examples: unsubscribe --user=tabbott@humbughq.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 --streams=foo + unsubscribe --user=tabbott@humbughq.com --api-key=a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 --streams='foo bar' + +You can omit --user and --api-key arguments if you have a properly set up ~/.humbugrc """ sys.path.append(path.join(path.dirname(__file__), '..')) import humbug diff --git a/humbug/__init__.py b/humbug/__init__.py index 8969539..afeceda 100644 --- a/humbug/__init__.py +++ b/humbug/__init__.py @@ -33,7 +33,7 @@ from distutils.version import LooseVersion from ConfigParser import SafeConfigParser -__version__ = "0.1.8" +__version__ = "0.1.9" # Check that we have a recent enough version # Older versions don't provide the 'json' attribute on responses. @@ -52,10 +52,10 @@ def generate_option_group(parser): action='store') group.add_option('--user', dest='email', - help='Email address of the calling user.') + help='Email address of the calling bot or user.') group.add_option('--config-file', action='store', - help='Location of an ini file containing the above information.') + help='Location of an ini file containing the\nabove information. (default ~/.humbugrc)') group.add_option('-v', '--verbose', action='store_true', help='Provide detailed output.') diff --git a/integrations/git/humbug_git_config.py b/integrations/git/humbug_git_config.py index f505d5b..3e0cda3 100644 --- a/integrations/git/humbug_git_config.py +++ b/integrations/git/humbug_git_config.py @@ -23,7 +23,7 @@ # Change these values to configure authentication for the plugin -HUMBUG_USER = "git@example.com" +HUMBUG_USER = "git-bot@example.com" HUMBUG_API_KEY = "0123456789abcdef0123456789abcdef" # commit_notice_destination() lets you customize where commit notices diff --git a/integrations/jira/org/humbug/jira/HumbugListener.groovy b/integrations/jira/org/humbug/jira/HumbugListener.groovy index 3dac87e..c1e440f 100644 --- a/integrations/jira/org/humbug/jira/HumbugListener.groovy +++ b/integrations/jira/org/humbug/jira/HumbugListener.groovy @@ -20,9 +20,9 @@ import org.apache.commons.httpclient.NameValuePair class HumbugListener extends AbstractIssueEventListener { Logger LOGGER = Logger.getLogger(HumbugListener.class.getName()); - // Your humbug account's email address + // The email address of one of the bots you created on your Humbug settings page. String humbugEmail = "" - // Your humbug API key + // That bot's API key. String humbugAPIKey = "" // What stream to send messages to. Must already exist. diff --git a/integrations/nagios/humbugrc.example b/integrations/nagios/humbugrc.example index 9cbd1ba..cb7cc97 100644 --- a/integrations/nagios/humbugrc.example +++ b/integrations/nagios/humbugrc.example @@ -1,5 +1,5 @@ # Fill these values in with the appropriate values for your realm, and # then install this value at /etc/nagios3/humbugrc [api] -email = nagios@example.com +email = nagios-bot@example.com key = 0123456789abcdef0123456789abcdef diff --git a/integrations/svn/humbug_svn_config.py b/integrations/svn/humbug_svn_config.py index 4789117..4de0376 100644 --- a/integrations/svn/humbug_svn_config.py +++ b/integrations/svn/humbug_svn_config.py @@ -23,7 +23,7 @@ # Change these values to configure authentication for the plugin -HUMBUG_USER = "svn@example.com" +HUMBUG_USER = "svn-bot@example.com" HUMBUG_API_KEY = "0123456789abcdef0123456789abcdef" # commit_notice_destination() lets you customize where commit notices diff --git a/integrations/trac/humbug_trac_config.py b/integrations/trac/humbug_trac_config.py index 07f2202..4b2d0f9 100644 --- a/integrations/trac/humbug_trac_config.py +++ b/integrations/trac/humbug_trac_config.py @@ -23,7 +23,7 @@ # See humbug_trac.py for installation and configuration instructions # Change these constants to configure the plugin: -HUMBUG_USER = "trac@example.com" +HUMBUG_USER = "trac-bot@example.com" HUMBUG_API_KEY = "0123456789abcdef0123456789abcdef" STREAM_FOR_NOTIFICATIONS = "trac" TRAC_BASE_TICKET_URL = "https://trac.example.com/ticket"