Overview

Perry Prop 8 Tweeter
====================

Introduction
------------

This (tweet_perry.py) is a script that scrapes a particular label in a gmail
mailbox for the Perry v. Schwarzenegger electronic notifications of docket
updates (NDAs). When it finds new ones, it posts summaries to Twitter.

It can optionally create a local cache (exposed via a provided public URL)
of the NDAs. If this is done, the public URL is included in the Tweet. The
script is intended to be run from a cronjob or similar; it remembers the last
time it was run and only posts notifications of new NDAs.

This is currently supporting the Twitter feed @Prop8USCA
<http://twitter.com/Prop8USCA>.

Dependencies
------------

o Python 2.7 (or 2.6 with argparse)
o python-argparse (or Python 2.7)
    To install with easy_install:
        # easy_install argparse
o python-twython
    To install with easy_install:
        # easy_install twython
    Or, install from source hosted at:
        <https://github.com/ryanmcgrath/twython>
o python-simplejson
    To install with easy_install:
        # easy_install simplejson
o python-oauth2
    To install with easy_install:
        # easy_install oauth2
o xoauth.py
    Provided in this source distribution, or available from Google from:
        <http://code.google.com/p/google-mail-xoauth-tools/source/browse/#svn/trunk/python>

Usage
-----

usage: tweet_perry.py [-h] --twitter-consumer-key TWITTER_CONSUMER_KEY
                      --twitter-consumer-secret TWITTER_CONSUMER_SECRET
                      --twitter-access-key TWITTER_ACCESS_KEY
                      --twitter-access-secret TWITTER_ACCESS_SECRET
                      --gmail-token GMAIL_TOKEN --gmail-secret GMAIL_SECRET
                      --gmail-user GMAIL_USER [--gmail-label GMAIL_LABEL]
                      [--last-run-file LAST_RUN_FILE]
                      [--read-messages-file READ_MESSAGES_FILE]
                      [--cache-path CACHE_PATH]
                      [--cache-url-prefix CACHE_URL_PREFIX] [-t]
    
    Options:
    -h
        Print usage and exit.
    --twitter-consumer-key TWITTER_CONSUMER_KEY
        where TWITTER_CONSUMER_KEY is the application consumer key for Twitter.
    --twitter-consumer-secret TWITTER_CONSUMER_SECRET
        where TWITTER_CONSUMER_SECRET is the application consumer key.
    --twitter-access-key TWITTER_ACCESS_KEY
        where TWITTER_ACCESS_KEY is the approved user access token.
    --twitter-access-secret TWITTER_ACCESS_SECRET
        where TWITTER_ACCESS_SECRET is the approved user acces token secret.
    --gmail-token GMAIL_TOKEN
        where GMAIL_TOKEN is the approved Gmail (X)Oauth token
    --gmail-secret GMAIL_SECRET
        where GMAIL_SECRET is the approved Gmail (X)Oauth secret
    --gmail-user GMAIL_USER
        where GMAIL_USER is the Gmail user name
    --gmail-label GMAIL_LABEL
        Optional. GMAIL_LABEL is the label assigned to the messages to read
        from Gmail. If not provided, it defaults to 'Perry Prop8'
    --last-run-file LAST_RUN_FILE
        Optional. LAST_RUN_FILE is the path+filename of the file to store the
        last date that the script was run. If not provided, defaults to
        'last_run.dat' in the working directory.
    --read-messages-file READ_MESSAGES_FILE
        Optional. READ_MESSAGES_FILE is the path+filename of the file to store
        a representation of all of the messages we've read so far, so as to
        prevent duplicate Tweets (since IMAP won't respect times in SENTSINCE
        queries, only dates.)
    --cache-path CACHE_PATH
        Optional. CACHE_PATH is the path to the parent directory to cache
        local web versions of the notice of docket activity (NDA) emails. If
        not provided, the emails will not be cached.
    --cache-url-prefix CACHE_URL_PREFIX
        Optional. Only valid if --cache-path is provided. The prefix of the
        URL to Tweet for the web caches. If not provided, defaults to
        'http://pr8.in/'
    -t
        Test mode. Does everything except Tweet.

Copyright Notice
----------------

 Copyright 2010 George Louthan <http://georgerloutha.nthefourth.com>

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.