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

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

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

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

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>

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

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

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

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

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)

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

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