twitter_bot_utils

Python utilities for twitter bots

Project description

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 library. It also provides shortcuts for setting up command line tools with argparse.

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.

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

# ~/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:

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:

# The config keyword argument will set a custom file location
twitter = twitter_bot_utils.api.API('MyBotName', config='special/file/path.yaml')

Without user authentication

Some 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 the users section. Then use the app keyword argument:

import twitter_bot_utils

twitter = twitter_bot_utils.api.API(app='my_app_name', config_file='path/to/config.yaml')

twitter.search(q="Twitter searches don't require user authentication")

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.

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 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:

import argparse
import twitter_bot_utils as tbu

# This sets up an argparse.ArgumentParser with the default arguments
parent = tbu.args.parent()
parser = argparse.ArgumentParser('Description', parents=[parent])
parser.add_argument('-m', '--my-arg')

args = parser.parse_args()

# Set up a logger named 'MyBot'
# Parse the default args. For instance, if --verbose is set, the logger will output to stdout.
# The default arguments include 'verbose', which will enable logger.debug() statements
logger = tbu.args.add_logger('MyBot', args.verbose)

# Generate a tweet somehow
tweet = my_tweet_function(args.my_arg)

twitter = tbu.api.API('MyBot', **vars(args))

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:

# 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:

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.

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 '

Command Line Utilities

twitter-auto-follow: Follow accounts that follow your bot
twitter-fave-mentions: Favorite your bots’ mentions

Project details

Release history Release notifications | RSS feed

0.14.0

Apr 15, 2023

0.13

Dec 27, 2021

0.12.1

Sep 6, 2020

0.12.0

May 11, 2020

0.11.6.post1

Dec 5, 2017

0.11.6

Dec 5, 2017

0.11.5

Mar 20, 2017

0.11.4

Aug 26, 2016

0.11.3

Jul 14, 2016

0.11.2

May 12, 2016

0.11.1

Apr 18, 2016

0.11.0

Apr 18, 2016

0.10.5

Feb 14, 2016

0.10.4

Dec 30, 2015

0.10.3

Dec 29, 2015

0.10.2

Dec 23, 2015

0.10.1

Dec 22, 2015

0.10.post1

Dec 22, 2015

0.10.0

Dec 22, 2015

0.9.7.1

Nov 10, 2015

0.9.7

Nov 9, 2015

This version

0.9.5.2

Oct 14, 2015

0.9.5.1

Oct 14, 2015

0.9.5

Oct 13, 2015

0.9.4

Oct 13, 2015

0.9.3

Oct 2, 2015

0.9.2

Oct 2, 2015

0.9.1.post1

Sep 30, 2015

0.9.1

Sep 30, 2015

0.9.post2

Jul 28, 2015

0.9.post1

Jul 28, 2015

0.9

Jul 27, 2015

0.8.1

Mar 23, 2015

0.8.post1

Mar 20, 2015

0.8

Mar 20, 2015

0.7.post2

Mar 20, 2015

0.7

Mar 17, 2015

0.6.7

Mar 10, 2015

0.6.5

Feb 17, 2015

0.6.4

Feb 15, 2015

0.6.3

Feb 14, 2015

0.6.2.1

Jan 13, 2015

0.6.2

Dec 18, 2014

0.6.1

Dec 18, 2014

0.6

Dec 18, 2014

0.5.2

Dec 18, 2014

0.5.1

Dec 16, 2014

0.5

Dec 16, 2014

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

twitter_bot_utils-0.9.5.2.tar.gz (14.4 kB view details)

Uploaded Oct 14, 2015 Source

Built Distribution

twitter_bot_utils-0.9.5.2-py3-none-any.whl (18.9 kB view details)

Uploaded Oct 14, 2015 Python 3

File details

Details for the file twitter_bot_utils-0.9.5.2.tar.gz.

File metadata

Download URL: twitter_bot_utils-0.9.5.2.tar.gz
Upload date: Oct 14, 2015
Size: 14.4 kB
Tags: Source
Uploaded using Trusted Publishing? No

File hashes

Hashes for twitter_bot_utils-0.9.5.2.tar.gz
Algorithm	Hash digest
SHA256	`003e47dac26dce4aceb103f684379f6396bdb4c8173a6c6a2a24d6eec53b83fc`
MD5	`9e1122afe65f5b18b3a04c663be47841`
BLAKE2b-256	`819a641709d817a5aeb5dee53c3c9554362ae2bfbc1a4328ca8d11524f0b1bf4`

See more details on using hashes here.

File details

Details for the file twitter_bot_utils-0.9.5.2-py3-none-any.whl.

File metadata

Download URL: twitter_bot_utils-0.9.5.2-py3-none-any.whl
Upload date: Oct 14, 2015
Size: 18.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No

File hashes

Hashes for twitter_bot_utils-0.9.5.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`6d8780465374ff57bcfa5ceb4f19b5337e5710b7267a27f4e4d532c384226c95`
MD5	`2d5d2349b37bc9e22b1f88f66669e276`
BLAKE2b-256	`4a0260960a6487723288de3738b3fadd555c73b770c7b5927e6ad823c6f49f3e`