[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)

api/README

@@ -30,7 +30,12 @@ file is as follows:
     key=<api key from the web interface>
     email=<your email address>
 
-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."

api/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__), '..'))

api/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):

api/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:

api/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:

api/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

api/examples/edit-message

@@ -25,25 +25,29 @@ import sys
 from os import path
 import optparse
 
-usage = """edit-message [options] --message=<msg_id> --content=<new content> --subject=<new subject>
+usage = """edit-message [options] --message=<msg_id> --subject=<new subject> --content=<new content> --user=<sender's email address> --api-key=<sender's 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

api/examples/get-public-streams

@@ -25,11 +25,13 @@ import sys
 from os import path
 import optparse
 
-usage = """get-public-streams --user=<email address> [options]
+usage = """get-public-streams --user=<bot's email address> --api-key=<bot's 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__), '..'))

api/examples/humbugrc

@@ -1,4 +1,4 @@
 ; Save this file as ~/.humbugrc
 [api]
-key=<api key from the web interface>
-email=<your email address>
+key=<your bot's api key from the web interface>
+email=<your bot's email address>

api/examples/list-members

@@ -25,9 +25,11 @@ import sys
 from os import path
 import optparse
 
-usage = """list-members [options]
+usage = """list-members --user=<bot's email address> --api-key=<bot's 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__), '..'))

api/examples/list-subscriptions

@@ -25,11 +25,13 @@ import sys
 from os import path
 import optparse
 
-usage = """list-subscriptions --user=<email address> [options]
+usage = """list-subscriptions --user=<bot's email address> --api-key=<bot's 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

api/examples/print-messages

@@ -25,11 +25,13 @@ import sys
 from os import path
 import optparse
 
-usage = """print-messages --user=<email address> [options]
+usage = """print-messages --user=<bot's email address> --api-key=<bot's 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

api/examples/print-next-message

@@ -25,11 +25,13 @@ import sys
 from os import path
 import optparse
 
-usage = """print-next-message --user=<email address> [options]
+usage = """print-next-message --user=<bot's email address> --api-key=<bot's 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

api/examples/send-message

@@ -24,30 +24,30 @@
 import sys
 from os import path
 import optparse
+import humbug
 
-usage = """send-message [options] <recipients>
+usage = """send-message --user=<bot's email address> --api-key=<bot's api key> [options] <recipients>
 
 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)

api/examples/subscribe

@@ -25,12 +25,14 @@ import sys
 from os import path
 import optparse
 
-usage = """subscribe --user=<email address> [options] --streams=<streams>
+usage = """subscribe --user=<bot's email address> --api-key=<bot's api key> [options] --streams=<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

api/examples/unsubscribe

@@ -25,12 +25,14 @@ import sys
 from os import path
 import optparse
 
-usage = """unsubscribe --user=<email address> [options] --streams=<streams>
+usage = """unsubscribe  --user=<bot's email address> --api-key=<bot's api key> [options] --streams=<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

api/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.')

api/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

api/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.

api/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

api/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

api/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"

templates/zephyr/api.html

@@ -13,8 +13,8 @@
 
     <p>We have a <a href="/api/endpoints">well-documented API</a> that allows you to build custom integrations, in addition to our <a href="/integrations">existing integrations</a>. For ease-of-use, we've created a Python module that you can drop in to a project to start interacting with our API.</p>
     <br/>
-    <a href="https://humbughq.com/dist/api/python-humbug_0.1.8.tar.gz" class="btn btn-large btn-primary btn-block" type="button"><i class="icon-download icon-white"></i> Download Python bindings and examples</a>
-    <span class="pull-right muted">Version 0.1.8</span>
+    <a href="https://humbughq.com/dist/api/python-humbug_0.1.9.tar.gz" class="btn btn-large btn-primary btn-block" type="button"><i class="icon-download icon-white"></i> Download Python bindings and examples</a>
+    <span class="pull-right muted">Version 0.1.9</span>
 
     <p>&nbsp;</p>
 
@@ -26,12 +26,16 @@
     <p>You can create bots on your <a href="/#settings" target="_blank">settings page</a>.
     Once you have a bot, you can use its email and API key to send messages.</p>
 
-    <p>Create a bot:<img class="screenshot" src="/static/images/api/create-bot.png" /></p>
+    <p>Create a bot:
+    <img class="screenshot" src="/static/images/api/create-bot.png" /></p>
 
-    <p>Look for the bot's email and API key:<img class="screenshot" src="/static/images/api/bot-key.png" /></p>
+    <p>Look for the bot's email and API key:
+    <img class="screenshot" src="/static/images/api/bot-key.png" /></p>
 
-    <p>If you prefer to send messages as your own user, you can find your API key also on your <a href="/#settings" target="_blank">settings page</a>.</p>
-    <p>When using our python bindings, you must specify the user and API key. Alterantively, if you don't, it will look for these credentials in <code>~/.humbugrc</code>, which you can create as follows:</p>
+    <p>If you prefer to send messages as your own user, you can also find your API key on your <a href="/#settings" target="_blank">settings page</a>.</p>
+    <p>When using our python bindings, you may either specify the user
+    and API key for each Client object that you initialize, or let the binding look for
+    them in your <code>~/.humbugrc</code>, which you can create as follows:</p>
 <div class="codehilite"><pre><span class="k">[api]</span>
 <span class="na">key</span><span class="o">=</span><span class="s">BOT_API_KEY</span>
 <span class="na">email</span><span class="o">=</span><span class="s">BOT_EMAIL_ADDRESS</span>