clone from http://code.google.com/p/python-twitter/source/
[python-twitter:python-twitter.git] / README
1 =Python Twitter=
2
3 _A python wrapper around the Twitter API_
4
5 Author: `DeWitt Clinton <dewitt@google.com>`
6
7 ==Introduction==
8
9 This library provides a pure python interface for the Twitter API.
10
11 Twitter (http://twitter.com) provides a service that allows people to
12 connect via the web, IM, and SMS.  Twitter exposes a web services API 
13 (http://twitter.com/help/api) and this library is intended to make
14 it even easier for python programmers to use. 
15
16   
17 ==Building==
18
19 *From source:*
20
21 Install the dependencies:
22
23   http://cheeseshop.python.org/pypi/simplejson
24
25 Download the latest python-twitter library from:
26
27   http://code.google.com/p/python-twitter/
28
29
30 Untar the source distribution and run:
31
32 {{{
33   $ python setup.py build
34   $ python setup.py install
35 }}}
36
37 *Testing*
38
39 With setuptools installed:
40
41 {{{
42   $ python setup.py test
43 }}}
44
45 Without setuptools installed:
46
47 {{{
48   $ python twitter_test.py
49 }}}
50
51 ==Getting the code==
52
53 View the trunk at:
54
55   http://python-twitter.googlecode.com/svn/trunk/
56
57 Check out the latest development version anonymously with:
58
59 {{{
60   $ svn checkout http://python-twitter.googlecode.com/svn/trunk/ python-twitter
61 }}}
62
63 ==Documentation==
64
65 View the last release API documentation at:
66
67   http://static.unto.net/python-twitter/0.6/doc/twitter.html
68
69 ==Using==
70
71 The library provides a python wrapper around the Twitter API and
72 the twitter data model.
73
74 *Model:*
75
76 The three model classes are twitter.Status, twitter.User, and
77 twitter.DirectMessage.  The API methods return instances of these
78 classes.
79
80 To read the full API for twitter.Status, twitter.User, or
81 twitter.DirectMessage, run:
82
83 {{{
84   $ pydoc twitter.Status
85   $ pydoc twitter.User
86   $ pydoc twitter.DirectMessage
87 }}}
88
89 *API:*
90
91 The API is exposed via the twitter.Api class.
92
93 To create an instance of the twitter.Api class:
94
95 {{{
96   >>> import twitter
97   >>> api = twitter.Api()
98 }}}
99
100 To create an instance of the twitter.Api with login credentials (many API
101 calls required the client to be authenticated):
102
103   >>> api = twitter.Api(username='username', password='password) 
104
105 To fetch the most recently posted public twitter status messages:
106
107 {{{
108   >>> statuses = api.GetPublicTimeline()
109   >>> print [s.user.name for s in statuses]
110   [u'DeWitt', u'Kesuke Miyagi', u'ev', u'Buzz Andersen', u'Biz Stone'] 
111 }}}
112
113 To fetch a single user's public status messages, where "user" is either
114 a Twitter "short name" or their user id.
115
116 {{{
117   >>> statuses = api.GetUserTimeline(user)
118   >>> print [s.text for s in statuses]
119 }}}
120
121 To fetch a list a user's friends (requires authentication):
122
123 {{{
124   >>> users = api.GetFriends()
125   >>> print [u.name for u in users]
126 }}}
127
128 To post a twitter status message (requires authentication):
129
130 {{{ 
131   >>> status = api.PostUpdate(username, password, 'I love python-twitter!')
132   >>> print status.text
133   I love python-twitter!
134 }}}
135
136 There are many more API methods, to read the full API documentation:
137
138 {{{
139   $ pydoc twitter.Api
140 }}}
141
142 ==Todo==
143  
144 Patches and bug reports are welcome, just please keep the style
145 consistent with the original source.
146
147 Add more example scripts.
148
149 The twitter.Status and twitter.User classes are going to be hard
150 to keep in sync with the API if the API changes.  More of the 
151 code could probably be written with introspection.
152
153 Statement coverage of twitter_test is only about 80% of twitter.py.
154
155 The twitter.Status and twitter.User classes could perform more validation
156 on the property setters.
157
158 ==More Information==
159
160 Please visit http://groups.google.com/group/python-twitter for more discussion.
161
162 ==Contributors==
163
164 Additional thanks to Pierre-Jean Coudert, Omar Kilani, Jodok Batlogg,
165 edleaf,glen.tregoning, Brad Choate, Jim Cortez, Jason Lemoine, Thomas
166 Dyson, Robert Laquey, and the rest of the python-twitter mailing list.
167
168 ==License==
169
170 {{{
171   Copyright 2007 Google Inc. All Rights Reserved.
172   
173   Licensed under the Apache License, Version 2.0 (the 'License');
174   you may not use this file except in compliance with the License.
175   You may obtain a copy of the License at
176   
177       http://www.apache.org/licenses/LICENSE-2.0
178   
179   Unless required by applicable law or agreed to in writing, software
180   distributed under the License is distributed on an 'AS IS' BASIS,
181   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
182   See the License for the specific language governing permissions and
183   limitations under the License.
184 }}}