Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

Configurable bot that replies to mentions and posts messages to twitter

Project Description

Easy-to-use TwitterBot that posts new messages and replies to mentions. Built on the popular twitter package.


You can use Twitterbot to:
  • Post a new message.
  • Reply to any twitter mentions with a message.


You can get twitterbot from PyPI with:

pip install twitterbot

The development version can be installed with:

pip install -e git://

If you are developing locally, your version can be installed from the project directory with:



Quick Start

By default, settings are populated from environment variables. The authentication variables are required and can be obtained from your Twitter account.


You can optionally set the following environment variables:

    Provides messages to be posted. Defaults to ‘messages.HelloWorldMessageProvider’, a simple provider that always returns “Hello World!”
    Provides storage for since_id. Twitter uses sinFile in which to store last retrieved since_id. Defaults to using the filesystem (‘./.since_id.txt’). You may set a value in the file to start handling mentions at a particular message id.
    If set to True, messages will be logged rather than actually posting them to Twitter.

Setting a Custom Message Provider

You can inject your own message provider by setting the following environment variable:

TWITTER_MESSAGE_PROVIDER = 'bot.messages.MyMessageProvider'

You would then need to create a bot.messages module with a MyMessageProvider class that implements the create() method, e.g.

class MyMessageProvider(object):

    def create(self, mention):
        Create a message
        :param mention: JSON object containing mention details from Twitter
        :return: a message
        return "This is my message!"

Setting a Custom Since_id Provider

You can inject your own since_id provider (e.g. using redis) by setting the following environment variable:

TWITTER_SINCE_ID_PROVIDER = 'bot.since_id.RedisProvider'

You would then need to create a bot.since_id module with a RedisProvider class that implements the get(), set(), and delete() methods, e.g.

import os
import redis
from twitter_bot import SettingsError

class RedisProvider(object):

    def __init__(self, redis_url=None):
        if not redis_url:
            redis_url = os.environ.get('REDISTOGO_URL')
            if not redis_url:
                raise SettingsError("You must supply redis_url or set the REDISTOGO_URL "
                                    "environment variable.")
        self.redis = redis.Redis.from_url(redis_url)

    def get(self):
        return self.redis.get('since_id')

    def set(self, since_id):
        return self.redis.set('since_id', since_id)

    def delete(self):
        return self.redis.delete('since_id')

Overriding Settings

If you require more control over settings, you can subclass Settings:

from twitter_bot import Settings

class MyBotSettings(Settings):
    def __init__(self):
        super(MyBotSettings, self).__init__()
        self.MESSAGE_PROVIDER = 'bot.messages.MyProvider'

Automating the bot

To run the bot as a cron job or Heroku scheduler task, you can make make a small script that uses the provided runner. If you have customized settings, import your own settings class rather than the provided settings.

#!/usr/bin/env python

import sys

from twitter_bot import BotRunner, Settings

if __name__ == '__main__':
    if len(sys.argv) != 2:
        print("You must specify a single command, either 'post_message' or 'reply_to_mentions'")
        result = 1
        result = BotRunner().go(Settings(), sys.argv[1])

Then call the script as follows:

$ ./ post_message
$ ./ reply_to_mentions


Get source:

git clone

Set up virtualenv:

mkvirtualenv twitterbot --python=/path/to/python3
pip install -r requirements/test.txt

Run tests:

coverage run -m nose
coverage report

Run bot:

$ ./ reply_to_mentions  # Check twitter stream for mentions, and reply
$ ./ post_message       # Post a message to twitter

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

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

File Name & Hash SHA256 Hash Help Version File Type Upload Date
(8.2 kB) Copy SHA256 Hash SHA256
Source Apr 23, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting