Metadata-Version: 1.0
Name: twitter_bot_utils
Version: 0.6.2
Summary: Python utilities for twitter bots
Home-page: http://github.com/fitnr/twitter_bot_utils
Author: Neil Freeman
Author-email: contact@fakeisthenewreal.org
License: GPL
Description: twitter bot utils
        =================
        
        Twitter bot utils make it a little easier to set up a Twitter bot, with
        an eye to making config and command-line options easy to manage and
        reproduce. They're intended for managing a small-to-medium-sized coterie
        of Twitter accounts on one machine. The package is a super-simple
        wrapper for the excellent `Tweepy <http://tweepy.org>`__ library. It
        also provides shortcuts for setting up command line tools with
        `argparse <https://docs.python.org/3/library/argparse.html>`__.
        
        This package is intended to assist with the creation of bots for
        artistic or personal projects. Don't use it to spam or harrass people.
        
        Works with Python 2.7 and 3.4 (2.6 & 3.3 probably work, too).
        
        Install with ``pip install twitter_bot_utils``.
        
        Setting up a tweepy API
        -----------------------
        
        The main goal of Twitter bot utils is to create Tweepy instances with
        authentication data stored in a simple conf file. This gives botmakers a
        simple, reusable place to store keys outside of source control.
        
        By default, twitter\_bot\_utils will read settings from a YAML or JSON
        config file. By default, it looks in the ~/ and ~/bots directories for
        files named "bots.yaml", "bots.json", or "botrc". Custom config files
        can be set, too, of course.
        
        .. code:: python
        
            from twitter_bot_utils import api
        
            # Automatically check for a config file in the above-named directories
            twitter = api.API('MyBotName')
        
            # Specify a specific config file
            twitter = api.API('MyBotName', config='path/to/config.yaml')
        
            # This is possible, although you should consider just using Tweepy directly
            twitter = api.API('MyBotName', consumer_key='...', consumer_secret='...', key='...', secret='...')
        
        Twitter bot utils comes with some built-in command line parsers, and the
        API object will also happily consume the result of
        ``argparse.parser.parse_args()`` (see below for details).
        
        Config file setup
        ~~~~~~~~~~~~~~~~~
        
        Custom settings in the config are available at runtime, so use the
        config file for any special settings you want.
        
        Example config file layout (This is YAML, JSON works, too):
        
        .. code:: yaml
        
            # ~/bots.yaml
        
            users:
                # twitter screen_name
                MyBotName:
                    key: $oauth_key
                    secret: $oauth_key_secret
                    # The app key should match a key in apps below
                    app: my_app_name
                    custom_setting: 'hello world'
        
                other_bot:
                    key: ...
                    secret: ...
                    app: my_app_name
        
            apps:
                my_app_name:
                    consumer_key: ...
                    consumer_secret: ...
        
            foo: bar
        
        Using the config settings:
        
        .. code:: python
        
            import twitter_bot_utils
        
            # Look for config in the default places mentioned above:
            twitter = twitter_bot_utils.api.API('MyBotName')
        
            twitter.config['foo']
            # returns 'bar'
        
            # The current user and app are also available:
            twitter.user['custom_setting']
            # hello world
        
        Setting a custom config file is simple:
        
        .. code:: python
        
            # The config keyword argument will set a custom file location
            twitter = twitter_bot_utils.api.API('MyBotName', config='special/file/path.yaml')
        
        Recent tweets
        -------------
        
        Basically, the ``twitter_bot_utils.api.API`` object is a wrapper for
        Tweepy with some configuration reading options added. It also adds three
        convenience methods for finding recent tweets, since it's often useful
        to know what a bot has done recently without setting up a whole backend
        for saving the bot's tweets.
        
        .. code:: python
        
            twitter = api.API('MyBotName')
        
            twitter.last_tweet
            # id of most recent tweet from MyBotName
        
            twitter.last_reply
            # id of most recent reply from MyBotName
        
            twitter.last_retweet
            # id of most recent retweet from MyBotName
        
            # Example: what's happened since the last time the bot was active?
            twitter.search('#botALLY', since_id=twitter.last_tweet)
        
        Default Command Line Options
        ----------------------------
        
        Some useful command line flags are available by default:
        
        -  ``-n, --dry-run``: Don't tweet, just output to stdout
        -  ``-v, --verbose``: Log to stdout
        -  ``-c, --config``: path to a config file. This is a JSON or YAML file
           laid out according to the below format.
        
        You can also pass authentication arguments with these options arguments.
        
        -  ``--key``: Twitter user key
        -  ``--secret``: Twitter user secret
        -  ``--consumer-key``: Twitter application consumer key
        -  ``--consumer-secret``: Twitter application consumer secret
        
        Say this is ``yourapp.py``:
        
        .. code:: python
        
            import logging
            import twitter_bot_utils
        
            # This sets up an argparse.ArgumentParser with some default arguments, which are explained below
            parser = twitter_bot_utils.setup_args('MyBot', description='Tweet something')
        
            parser.add_argument('-m', '--my-arg', help="You're passing an argument to argparse.ArgumentParser")
        
            args = parser.parse_args()
        
            # Parse the default args. For instance, if --verbose is set, the logger will output to stdout.
            twitter_bot_utils.defaults('MyBot', args)
        
            # That's right, utils set up a logger for you.
            # It has the same name as the first argument to setup_args
            logger = logging.getLogger('MyBot')
        
            # Do logic here to generate a tweet somehow
            tweet = my_tweet_function(args.my_arg)
        
            logger.info("Generated "+ tweet)
        
            # Use args.dry_run to control tweeting
            if not args.dry_run:
                twitter.update_status(tweet)
        
        Then on the command line:
        
        .. code:: bash
        
            # Looks for settings in a config file (e.g. bots.yaml, see config section above)
            # Outputs results to stdout, doesn't publish anything 
            $ python yourapp.py --dry-run --verbose
            Generated <EXAMPLE TWEET>
        
            # Authenicate with these values instead of the config file
            $ python yourapp.py --verbose --consumer-key $ck --consumer-secret $cs --key $user_key --secret $user_secret
            Generated <EXAMPLE TWEET 2>
        
        Helpers
        -------
        
        Checking for entities
        ~~~~~~~~~~~~~~~~~~~~~
        
        Easily check if tweets have specific entities:
        
        .. code:: python
        
            import twitter_bot_utils
        
            # Don't set include_entities to False and expect the below to work
            statuses = twitter.search('example search', include_entities=True)
        
            status = status[0]
        
            twitter_bot_utils.helpers.has_mention(status)
            # returns True if status has one or more mentions, otherwise False 
        
            twitter_bot_utils.helpers.has_hashtag(status)
            # returns True if status has one or more hashtags, otherwise False 
        
            twitter_bot_utils.helpers.has_media(status)
            # returns True if status has one or more media entities (images, video), otherwise False 
        
            twitter_bot_utils.helpers.has_entities(status)
            # returns True if status has any entities
        
            # These also exist:
            # twitter_bot_utils.helpers.has_url
            # twitter_bot_utils.helpers.has_symbol
        
        Filtering out entities
        ~~~~~~~~~~~~~~~~~~~~~~
        
        Easily remove entities from a tweet's text.
        
        .. code:: python
        
            import twitter_bot_utils
        
            api = twitter_bot_utils.api.API('MyBotName')
        
            results = api.search("special topic")
        
            results[0].text
            # 'This is an example tweet with a #hashtag and a link http://foo.com'
        
            twitter_bot_utils.helpers.remove_entity(results[0], 'hashtags')
            # 'This is an example tweet with a  and a link http://foo.com'
        
            twitter_bot_utils.helpers.remove_entity(results[0], 'urls')
            # 'This is an example tweet with a #hashtag and a link '
        
            # Remove multiple entities with remove_entities.
            twitter_bot_utils.helpers.remove_entities(results[0], ['urls', 'hashtags', 'media'])
            # 'This is an example tweet with a  and a link '
        
        
Platform: UNKNOWN
