Package: twitter_bot_utils
twitter bot utilsTwitter 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 excellentTweepylibrary. It also provides shortcuts for setting up command line tools withargparse.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 >= 3.6.Install withpip install twitter_bot_utils.See a basic run through in theHello Worldsection of thedocumentation.AuthenticatingOne hurdle with setting up bots is getting the proper authentication keys. It can be a bit of a pain to log in and out of Twitter's app site. Twitter bot utils comes withtbu auth, a command line helper for this:$ tbu auth --consumer-key 1233... --consumer-secret 345...This will prompt you with an url. Open this in a browser where your bot is logged in, click "Authorize". Twitter will show you an authorization code, enter this on the command line, and presto! your keys will be displayed.tbu authis inspired by a feature oftwurl, Twitter's full-fledged command line tool.Config filesOne goal of Twitter Bot Utils is to create Tweepy instances with authentication data stored in a simple config file. This gives botmakers a simple, reusable place to store keys outside of source control.By default, Twitter bot utils looks for a file calledbots.yaml(or.yml) in the current directory, your home directory (~/) or the~/botsdirectory. Custom config locations can be set, too.These are two ways to lay out a bots config file. The basic way covers just one user and one app:token:...secret:...consumer_key:...consumer_secret:...my_setting:"botsaregood"If you have more than one bot, a simple setup is to have one app for each bot. Visitapps.twitter.com, register the app, and then choose "Create my access token" in the "keys and tokens" tab.general_setting:"allbotssharethissetting"users:# twitter screen_nameMyBotName:token:...secret:...consumer_key:...consumer_secret:...custom_setting:"botsaregreat"other_bot:...If you have one app shared by several bots, create anappssection in the config file:apps:my_app_name:consumer_key:...consumer_secret:...users:MyBotName:token:...secret:...app:my_app_nameThetwitter-authutility will happily read settings from abots.yamlfile set up like this:twitter-auth -c ~/bots.yaml --app my_app_nameUsing config files to talk to TwitterUsing a config file in one of the default locations doesn't require any extra settings:importtwitter_bot_utilsastbu# Automatically check for a config file in the above-named directoriestwitter=tbu.API(screen_name='MyBotName')Thetwitterobject is a fully-authenticated tweepy API object. So you can now do this:twitter.update_status(status='hello world')Thebotsconfig file is also useful for storing keys and parameters for other APIs, or for your own bots.# Get a config settings from your bots config file. This might be the key for a third-party API# Use a general settingtwitter.config['general_setting']# "all bots share this setting"# Settings from the user and app section are also available:twitter.config['custom_setting']# "bots are great"twitter.config['app_setting']# "apple juice"Set a custom config file with theconfig_fileargument:# Specify a specific config file
twitter = tbu.API(screen_name='MyBotName', config_file='path/to/config.yaml')Twitter bot utils comes with some built-in command line parsers, and the API object will also happily consume the result ofargparse.parser.parse_args()(see below for details).Without user authenticationSome Twitter API queries don't require user authentication. To set up an Tweepy API instance without user authentication, set up a bots.yaml file as above, but omit theuserssection. Use the app keyword argument:twitter=tbu.API(app='my_app_name',config_file='path/to/config.yaml')twitter.search(q="Twitter searches don't require user authentication")Recent tweetsThetwitter_bot_utils.APIobject extendstweepy.APIwith some methods useful for bots:Methods to check for the ID of recent tweets:last_tweet,last_reply,last_retweet. These are useful if your bot searches twitter and wants to avoid ingesting the same material.twitter=tbu.API(screen_name='MyBotName')twitter.last_tweet# id of most recent tweet from MyBotNametwitter.last_reply# id of most recent reply from MyBotNametwitter.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)Twitter bot utils also adds a retry inupdate_statuswhen Twitter is over capacity. Ifupdate_statusgets a 503 error from Twitter, it will wait 10 seconds and try again.Default Command Line OptionsIt's useful to package bots as command line apps so that they can be easily run withcron. Twitter bot utils includes some helpers for working withargparse.Some useful command line flags are available by default:-u, --user: Screen name to run as-n, --dry-run: Don't tweet, just output to stdout-v, --verbose: Log to stdout-q, --quiet: Only log errors-c, --config: path to a config file. This is a JSON or YAML file laid out according to the above format. This option isn't needed if the config file is in one of the default places.Say this ismybot.py:importargparseimporttwitter_bot_utilsastbu# This sets up an argparse.ArgumentParser with the default argumentsparent=tbu.args.parent()parser=argparse.ArgumentParser('My Example Bot',parents=[parent])parser.add_argument('--my-arg',type=str,help='A custom argument')args=parser.parse_args()# Set up the tweepy API# Note that you can pass the argparse.Namespace objecttwitter=tbu.API(args)# Generate a tweet somehowtweet=my_tweet_function(args.my_arg)# The API includes an instance of logging# debug logs will output to stdout only if --verbose is set# info logs will output even without --verboseapi.logger.debug("Generated%s",tweet)# Use args.dry_run to control tweetingifnotargs.dry_run:twitter.update_status(tweet)Then on the command line:>pythonmybot.py--help
usage:mybot.py[options]MyExampleBot

optionalarguments:-h,--helpshowthishelpmessageandexit-cPATH,--configPATHbotsconfigfile(jsonoryaml)-uSCREEN_NAME,--userSCREEN_NAMETwitterscreenname-n,--dry-runDon't actually do anything-v, --verbose         Run talkatively-q, --quiet           Run quietly--my-arg MY_ARG       A custom argument# Looks for settings in a config file (e.g. bots.yaml, see config section above)# Prints results to stdout and doesn'tpublishanything>pythonyourapp.py--dry-run--verbose
Generated<EXAMPLETWEET># Run quietly, say in a crontab file>pythonyourapp.py--userMyBotName--quiet
Generated<EXAMPLETWEET2>HelpersChecking for entitiesEasily check if tweets have specific entities:importtwitter_bot_utils# Don't set include_entities to False and expect the below to workstatuses=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 Falsetwitter_bot_utils.helpers.has_hashtag(status)# returns True if status has one or more hashtags, otherwise Falsetwitter_bot_utils.helpers.has_media(status)# returns True if status has one or more media entities (images, video), otherwise Falsetwitter_bot_utils.helpers.has_entities(status)# returns True if status has any entities# These also exist:twitter_bot_utils.helpers.has_urltwitter_bot_utils.helpers.has_symbolFiltering out entitiesThese helpers remove entities from a tweet's text.importtwitter_bot_utilsastbuapi=tbu.API(screen_name='MyBotName')results=api.search("special topic")results[0].text# 'This is an example tweet with a #hashtag and a link http://foo.com'tbu.helpers.remove_entity(results[0],'hashtags')# 'This is an example tweet with a  and a link http://foo.com'tbu.helpers.remove_entity(results[0],'urls')# 'This is an example tweet with a #hashtag and a link '# Remove multiple entities with remove_entities.tbu.helpers.remove_entities(results[0],['urls','hashtags','media'])# 'This is an example tweet with a  and a link 'Command line utilitiesTwitter bot utils includes a command line tool with a few useful subcommands:tbu auth: Authenticate and account with a Twitter app.tbu follow: Follow accounts that follow your bottbu like: Like (aka favorite) your bot's mentionstbu post: Basic command line for posting text and images