Metadata-Version: 1.1
Name: birdfeeder
Version: 0.1.1
Summary: A newslynx-opinionated wrapper around twython
Home-page: http://github.com/newslynx/birdfeeder
Author: Brian Abelson
Author-email: brian@newslynx.org
License: MIT
Description: |travis-img| birdfeeder ====== *Feed on tweets*
        
        Install
        -------
        
        ::
        
            pip install birdfeeder
        
        Test
        ----
        
        Requires ``nose``
        
        ::
        
            nosetests
        
        Usage
        -----
        
        ``birdfeeder`` simplifies ``twython`` by taking care of alot the common
        problems in working with the Twitter API, including:
        
        -  pagination
        -  rate limiting
        -  url unshortening
        -  error handling
        
        Thus far, we've implemented 5 methods: ``connect``, ``search``,
        ``list_timeline``, ``user_timeline``, and ``user_stats`` (a custom
        method):
        
        Connect
        ~~~~~~~
        
        If you have ``TWT_API_KEY``, ``TWT_API_SECRET``, ``TWT_ACCESS_TOKEN``,
        and ``TWT_ACCESS_SECRET`` set as environmental variables, you can use
        all the methods without explicitly connecting. However, if you want to
        explicitly connect beforehand, you can also pass in a connection as
        ``conn`` to any method:
        
        .. code:: python
        
            import birdfeeder
        
            conn = birdfeeder.connect() 
        
            tweets = birdfeeder.search(q="hello world", count=10, conn=conn)
            for t in tweets:
              print t
        
        In addition, you can also pass in an authenticated user's token with
        ``access_token``:
        
        .. code:: python
        
            import birdfeeder
        
            for t in birdfeeder.search(q="hello world", access_token="authenticed_users_token"):
              print t
        
        Search
        ~~~~~~
        
        .. code:: python
        
            import birdfeeder
        
            tweets = birdfeeder.search(q="hello world", count=10)
            for t in tweets:
              print t
        
        List Timeline
        ~~~~~~~~~~~~~
        
        .. code:: python
        
            import birdfeeder
        
            tweets = birdfeeder.list_timeline(owner_screen_name = 'cspan', slug = 'members-of-congress', count=100)
            for t in tweets:
              print t 
        
        User Timeline
        ~~~~~~~~~~~~~
        
        .. code:: python
        
            import birdfeeder 
        
            tweets = birdfeeder.user_timeline(screen_name = 'newslynx')
            for t in tweets:
              print t
        
        User Stats
        ~~~~~~~~~~
        
        This returns a dictionary of stats about a user, with the time it ran.
        It's intended for creating a time series of a user's metadata:
        
        .. code:: python
        
            import birdfeeder 
        
            stats = birdfeeder.user_stats(screen_name = "newslynx")
            print stats
        
        Pagination
        ----------
        
        With ``birdfeeder``, pagination is simple, just add ``pagination=True``
        to any method, ie:
        
        .. code:: python
        
            import birdfeeder
        
            tweets = birdfeeder.user_timeline(screen_name = 'newslynx', count = 5, pagination=True)
            for t in tweets:
              print t
        
        This will keep track of the ``max_id`` of each request and iterate
        through results until everything has been retrieved (or until otherwise
        specified - more below). For each request, it will wait for a defualt of
        15 seconds so as to avoid rate limiting.
        
        Concurrency
        -----------
        
        add concurrency to any method via ``gevent``:
        
        .. code:: python
        
        
            tweets = birdfeeder.user_timeline(screen_name="brianabelson", concurrent=True)
            for t in tweets:
              print t
        
        Custom Options
        --------------
        
        We've added some custom options for each method, they are as follows:
        
        -  ``throttle`` - the time in seconds to wait between each request (only
           relevant when ``paginate = True``)
        -  ``max_requests`` - the maximum number of requests to make (only
           relevant when ``paginate = True``)
        -  ``wait`` - the default number of seconds to wait after an error
        -  ``backoff`` - the factor to multiply ``wait`` by after each error
        -  ``timeout`` - the time in seconds at which point we should abandon an
           error prone request. Here, ``birdfeeder`` will log a warning, but
           will otherwise fail silently.
        
        Here are the default arguments for all methods:
        
        .. code:: python
        
            default_kws = {
              'paginate' : False,
              'concurrent': False,
              'num_workers': 20,
              'max_id': None,
              'throttle' : 15,
              'count' : 200,
              'max_requests' : None,
              'wait': 1,
              'backoff': 2,
              'timeout': 30
            }
        
        Streaming
        ---------
        
        Finally, we've included a simple streaming API client (from
        `here <http://twython.readthedocs.org/en/latest/usage/streaming_api.html>`__).
        With this, you can pass in three functions on initialization: a parsing
        function, a storage function, and an error function, ie:
        
        .. code:: python
        
            from birdfeeder import Stream 
        
            def parse(data):
              return data['text']
        
            def store(data):
              print data 
        
            def error(status_code, data):
              pass
        
            s = Stream(parse=parse, store=store, error=error)
            s.statuses.filter(track='twitter')
        
        Acknowledgements
        ----------------
        
        To write this library, I heavily referenced Jeremy Singer-Vine's
        excellent ```twick`` <https://github.com/jsvine/twick>`__.
        
        .. |travis-img| image:: https://travis-ci.org/newslynx/birdfeeder.svg
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
