tweethon 0.8.1
A python wrapper around the Twitter API.  Updated often and drop in replacement for twitter-python (aka its a fork)
License: Apache License 2.0
Keywords: twitter api

-*- markdown -*-

# Python Twitter #

_A python wrapper around the Twitter API_

* Author: `Jeremy Rossi <jeremy@jeremyrossi.com>`
* Org Author: `DeWitt Clinton <dewitt@google.com>`

## Introduction ##

This library provides a pure python interface for the Twitter API.

Twitter (http://twitter.com) provides a service that allows people to
connect via the web, IM, and SMS.  Twitter exposes a web services API 
(http://twitter.com/help/api) and this library is intended to make
it even easier for python programmers to use. 
  
## Building ##

### From source: ###

Install the dependencies:

* [simplejson](http://cheeseshop.python.org/pypi/simplejson)

Download the latest tweethonlibrary from:

* [tweethon](http://bitbucket.org/jrossi/tweethon/)


Untar the source distribution and run:

    $ python setup.py build
    $ python setup.py install

### Testing: ###

With setuptools installed:

    $ python setup.py test

Without setuptools installed:

    $ python tweethon_test.py

## Getting the code ##

View the trunk at:

  http://bitbucket.org/jrossi/tweethon/src/

Check out the latest development version anonymously with mercurial:

    $ hg clone http://bitbucket.org/jrossi/tweethon/

## Documentation ##

View the last release API documentation at:

* [PyTwitter](http://bitbucket.org/jrossi/tweethon/wiki/Home)

## Using ##

The library provides a python wrapper around the Twitter API and
the twitter data model.

### Model: ###

The three model classes are `twitter.Status`, `twitter.User`, and
`twitter.DirectMessage`.  The API methods return instances of these
classes.

To read the full API for `twitter.Status`, `twitter.User`, or
`twitter.DirectMessage`, run:

    $ pydoc tweethon.Status
    $ pydoc tweethon.User
    $ pydoc tweethon.DirectMessage

### API: ###

The API is exposed via the `twitter.Api` class.

To create an instance of the `twitter.Api` class:

    >>> import tweethong
    >>> api = tweethon.Api()

To create an instance of the `twitter.Api` with login credentials (many API
calls required the client to be authenticated):

    >>> api = tweethon.Api(username='username', password='password) 

To fetch the most recently posted public twitter status messages:

    >>> statuses = api.GetPublicTimeline()
    >>> print [s.user.name for s in statuses]
    [u'DeWitt', u'Kesuke Miyagi', u'ev', u'Buzz Andersen', u'Biz Stone'] 

To fetch a single user's public status messages, where "user" is either
a Twitter "short name" or their user id.

    >>> statuses = api.GetUserTimeline(user)
    >>> print [s.text for s in statuses]

To fetch a list a user's friends (requires authentication):

    >>> users = api.GetFriends()
    >>> print [u.name for u in users]

To post a twitter status message (requires authentication):

    >>> status = api.PostUpdate(username, password, 'I love python-twitter!')
    >>> print status.text
    I love python-twitter!

There are many more API methods, to read the full API documentation:

    $ pydoc tweethon.Api

## Convert from python-twitter ## 

PyTwitter is a complete fork of the python-twitter codebase.  I am planning on keeping 
tweethon as drop in replacement for python-twitter.  To make this work seamlessly use
the following import idiom:

    >>> import tweethon as twitter

## More Information ##

## Contributors ##

Additional thanks to Pierre-Jean Coudert, Omar Kilani, Jodok Batlogg,
edleaf,glen.tregoning, Brad Choate, Jim Cortez, Jason Lemoine, Thomas
Dyson, Robert Laquey, and the rest of the python-twitter mailing list.

## License ##

> Copyright 2007 Google Inc. All Rights Reserved.
> 
> Licensed under the Apache License, Version 2.0 (the 'License');
> you may not use this file except in compliance with the License.
> You may obtain a copy of the License at
> 
>     http://www.apache.org/licenses/LICENSE-2.0
> 
> Unless required by applicable law or agreed to in writing, software
> distributed under the License is distributed on an 'AS IS' BASIS,
> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
> See the License for the specific language governing permissions and
> limitations under the License.

2009-03-11

 Added page parameter to GetReplies, GetFriends, GetFollowers, and GetDirectMessages

2009-03-03

  Added count parameter to GetFriendsTimeline

2009-03-01
  Add PostUpdates, which automatically splits long text into multiple updates.

2009-02-25

  Add in_reply_to_status_id to api.PostUpdate

2009-02-21

  Wrap any error responses in a TwitterError
  Add since_id to GetFriendsTimeline and GetUserTimeline

2009-02-20

  Added since and since_id to Api.GetReplies

2008-07-10

  Added new properties to User and Status classes.
  Removed spurious self-import of the twitter module
  Added a NOTICE file
  Require simplejson 2.x or later
  Added get/create/destroy favorite flags for status messages.
  Bug fix for non-tty devices.

2007-09-13
 
  Unset the executable bit on README.

2007-09-13

  Released version 0.5.
  Added back support for setuptools (conditionally)
  Added support for X-Twitter-* HTTP headers
  Fixed the tests to work across all timezones
  Removed the 140 character limit from PostUpdate  
  Added support for per-user tmp cache directories

2007-06-13

  Released 0.4.
  Fixed a unicode error that prevented tweet.py from working.
  Added DestroyStatus
  Added DestroyDirectMessage
  Added CreateFriendship
  Added DestoryFriendship

2007-06-03

  Fixed the bug that prevented unicode strings being posted
  Username and password now set on twitter.Api, not individual method calls
  Added SetCredentials and ClearCredentials
  Added GetUser ("users/show" in the twitter web api)
  Added GetFeatured
  Added GetDirectMessages
  Added GetStatus ("statuses/show" in the twitter web api)
  Added GetReplies
  Added optional since_id parameter on GetPublicTimeline
  Added optional since parameter on GetUserTimeline 
  Added optional since and user parameters on GetFriendsTimeline
  Added optional user parameter on GetFriends 
  
2007-04-27
  
  Modified examples/twitter-to-xhtml.py to handle unicode
  Dropped dependency on setuptools (too complicated/buggy)
  Added unicode test cases
  Fixed issue 2 "Rename needs an unlink in front"
  
2007-04-02

  Released 0.3.
  Use gmtime not localtime to calculate relative_created_at.

2007-03-26

  Released 0.2
  GetUserTimeline can accept userid or username.

2007-03-21

  Calculate relative_created_at on the fly

2007-01-28

  Released 0.1
  Initial checkin of python-twitter