-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
345 lines (230 loc) · 13.1 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
Welcome to the Gnip Python convenience library!
== Overview ==
This library provides a Python API for accessing Gnip web services. This library
supports activities related to publishing and subscribing to data.
== Dependencies ==
The following libraries are required by this library.
- iso8601-0.1.4 - http://pypi.python.org/pypi/iso8601
- pyjavaproperties-0.3 - http://pypi.python.org/pypi/pyjavaproperties/0.3
- elementtree-1.2.7_20070827_preview - http://effbot.org/zone/element-index.htm
- httplib2-0.4 - http://code.google.com/p/httplib2/
== Installing ==
Simply run the setup.py script provided.
% sudo python setup.py install
== Quick Start ==
Gnip has a test publisher "gnip-test-publisher":
https://prod.gnipcentral.com/gnip/publishers/gnip-test-publisher/notification/
The following example retrieves notification data from the current bucket for
"gnip-test-publisher." Please note that the current bucket is not static and
therefore will contain a variable amount of data, but you'll get quick feedback
to know if you can connect and access the public notification data.
import gnip
gnip = gnip.Gnip("<your account email>","<your account password>")
response = gnip.get_publisher_notifications("gnip", "gnip-test-publisher")
print response.result
You should see an Activities object.
== Debugging ==
no additional debugging info at this time
== Running the Client Library Tests ==
If you have downloaded the complete Gnip Client library source, the unit tests
will be in the test/ directory. Before running the tests, you will need to
configure the username, password, and connection information used to connect
to a Gnip server. To do this, add the ./test/gnip_account.properties file
that contains the following properties:
gnip.password=your-gnip-password
gnip.test.publisher=your-test-publisher
Note, for the tests to pass, you must reference a Gnip test publisher that
exists and that you own and thus can be used for publishing activities
from a unit test. The "gnip-test-publisher" does not work for the tests.
For more information about creating a Gnip Publisher, see:
http://prod.gnipcentral.com
To run the tests, type:
% python regression.py
==== Subscriber Actions ====
=== Notification vs. Activity ===
As a subscriber you can retrieve notification data or activity data. The main
difference between these two types of data buckets are:
*** Notifications contain a reduced meta-data subset of attributes for an activity
*** Activities contain full data, including the raw payload. There are some
restrictions on activity data. You can only request unfiltered activities
on publishers that you own (have authorization access to). You can create
filters on any publisher and request activity data.
=== Example 1: Retrieve all recent activities at a publisher ===
As a consumer one thing you might be interested in immediately is
grabbing data from a publisher. To do this you must create a connection to Gnip
using your username and password. Once the connection is established you can
get the publisher and request the stream. These examples uses the publisher
"gnip-test-publisher".
*** Notification data stream request ***
import gnip
gnip = gnip.Gnip("<your account email>","<your account password>")
response = gnip.get_publisher_notifications("gnip", "gnip-test-publisher")
print response.code
You should see '200'.
You can also view the current notifications bucket via web on the Gnip site:
https://prod.gnipcentral.com/gnip/publishers/gnip-test-publisher/notification/current.xml
*** Notification data stream request with optional date param ***
import gnip
gnip = gnip.Gnip("<your account email>","<your account password>")
response = gnip.get_publisher_notifications("gnip", "gnip-test-publisher", datetime.datetime.utcnow() - datetime.timedelta(minutes=1))
print response.code
You should see '200'.
You can see the running list of notification buckets on the Gnip site:
https://prod.gnipcentral.com/gnip/publishers/gnip-test-publisher/notification/
=== Example 2: Filter notifications or activities by a set of users ===
You can create a filter to stream activity data for the users you care about.
Posts from the users that have already occurred will not be included in a
filter. Therefore any new filter you create will be empty until the users you
specify perform an action (make a tweet, digg a story, create a bookmark in
delicious, etc.).
You can only retrieve activity data (full data) from publishers that you don't own
by creating a filter.
The test actor for "gnip-test-publisher" is "joeblow". To test your filter, be sure
"joeblow" appears in your rule set.
The following examples illustrate creating filters for both notification and activity
data. Additionally, the two examples show how to use/not use the post URL parameter.
*** Notificiation Filter without POST URL ***
Note that the full data (second parameter) of the filter object must be set to
false. This example does not include a POST URL, meaning you'll have to poll
Gnip for the results when you need them. The following snippet creates (and
retrieves) a notification filter called "myNotificationFilter" on the publisher
gnip-test-publisher.
import gnip
from gnip import *
gnip = gnip.Gnip("<your account email>","<your account password>")
my_filter = filter.Filter(name="myNotificationFilter", full_data=False, post_url=None, rules=[Rule("actor", "you"), Rule("actor", "mary"), Rule("actor", "joeblow")])
gnip.create_filter("gnip", "gnip-test-publisher", my_filter)
response = gnip.get_filter_notifications("gnip", "gnip-test-publisher", "myNotificationFilter")
print response.code
You should see '200'
You can also see your filters list for each publisher by going to the Gnip site:
https://prod.gnipcentral.com/gnip/publishers/gnip-test-publisher/filters
You can view notification buckets on the Gnip site by going to:
https://prod.gnipcentral.com/gnip/publishers/gnip-test-publisher/filters/myNotificationFilter/notification
*** Activity Filter with POST URL ***
Note that the full data (second parameter) of the filter object must be set to
true to view activity data. This example includes the optional POST URL,
meaning Gnip will POST via an HTTP HEAD request to this URL. The following
snippet creates (and gets) a notification filter called "myActivityFilter" on
the publisher gnip-test-publisher.
If you want notifications to be sent to a script on your server for processing,
you must ensure that the postURL parameter you set responds successfully to an
HTTP HEAD request. (note that this example will throw an error because the POST
URL is invalid).
import gnip
from gnip import *
gnip = gnip.Gnip("<your account email>","<your account password>")
my_filter = filter.Filter(name="myActivityFilter", full_data=True, post_url=None, rules=[Rule("actor", "you"), Rule("actor", "mary"), Rule("actor", "joeblow")])
gnip.create_filter("gnip", "gnip-test-publisher", my_filter)
response = gnip.get_filter_activities("gnip", "gnip-test-publisher", "myActivityFilter")
print response.code
You should see '200'.
Your actors list should be (not necessarily in this order): you, mary, joeblow
You can also see your filters list for each publisher by going to the Gnip site:
https://prod.gnipcentral.com/gnip/publishers/gnip-test-publisher/filters
You can view notification buckets on the Gnip site by going to:
https://prod.gnipcentral.com/gnip/publishers/gnip-test-publisher/filters/myActivityFilter/activity
=== Example 3: Add rules to an existing filter ===
You can add rules later to an existing filter. The following code snippet adds
two new rules to the filter we created above, myNotificationFilter:
import gnip
gnip = gnip.Gnip("<your account email>","<your account password>")
gnip.add_rules_to_filter("gnip", "gnip-test-publisher", "myNotificationFilter",
rules=[Rule("actor", "sam"), Rule("actor", "judy")])
response = gnip.find_filter("gnip", "gnip-test-publisher", "myNotificationFilter")
print response.code
You should see '200'.
=== Example 4: Delete a filter ===
Filters can be easily deleted. The following code sample deletes the filter
that was created above:
import gnip
gnip = gnip.Gnip("<your account email>","<your account password>")
response = gnip.delete_filter("gnip", "gnip-test-publisher", "myNotificationFilter");
print response.code
You should see '200'.
=== Example 5: Retrieve activities from a publisher ===
*** Activity Data Stream Request ***
NOTE: You must create a filter (see Example 2 above) before you can view
activities for a publisher that you do not own.
import gnip
gnip = gnip.Gnip("<your account email>","<your account password>")
response = gnip.get_publisher_notifications("gnip", "gnip-test-publisher")
print response.code
You can also view the current activity bucket via web on the Gnip site:
https://prod.gnipcentral.com/gnip/publishers/gnip-test-publisher/activity/current.xml
*** Activity Data Stream Request with Date Param ***
NOTE: You must create a filter (see Example 3 below) before you can view
activities for a publisher that you do not own.
import gnip
import datetime
gnip = gnip.Gnip("<your account email>","<your account password>")
response = gnip.get_publisher_notifications("gnip", "gnip-test-publisher", datetime.datetime.utcnow() - datetime.timedelta(minutes=1))
print response.code
You can see the running list of activity buckets on the Gnip site:
https://prod.gnipcentral.com/gnip/publishers/gnip-test-publisher/activity/
==== Publisher Actions ====
In order to utilize the publisher API, you must first create a publisher. The
publisher name should be descriptive to you. Currently publisher's you create
are private to your account only, and fall under the "my" scope. For now,
publishers cannot be deleted once they are created, so be mindful when naming
and testing your publishers.
Publishers must have one or more rule types specified so that filters can be
created based on the rule types. The following rule types are supported by Gnip:
Actor
To
Regarding
Source
Tag
=== Example 1: Create a publisher
import gnip
from gnip import *
gnip = gnip.Gnip("<your account email>","<your account password>")
my_publisher = publisher.Publisher("myPublisher", ["actor", "tag"])
response = gnip.create_publisher(my_publisher)
print response.code
You should see a response message of "Success".
=== Example 2: Updating a publisher
The following example takes an existing publisher and updates it with a new
rule type.
import gnip
gnip = gnip.Gnip("<your account email>","<your account password>")
my_publisher = gnip.get_publisher("my", "myPublisher")
my_publisher.rule_types.append("to")
response = gnip.update_publisher(my_publisher)
print response.code
You should see a response message of "Success".
=== Example 3: Publishing activities
Here is how you can publish activities to the activity stream:
import gnip
from gnip import *
gnip = gnip.Gnip("<your account email>","<your account password>")
a_payload = payload.Payload(title="Title",
body="Body",
media_urls=[xml_objects.URL(value="http://media1.com", meta_url="http://media1.com/meta"), xml_objects.URL(value="http://media2.com", meta_url="http://media2.com/meta")],
raw="raw")
an_activity = activity.Activity(action="update",
activity_id="12345",
url="http://example.com",
sources=["web"],
places=[place.Place(xml_objects.Point(40.000, -105.002), feature_name="testPlace")],
actors=[xml_objects.Actor(value="bob", meta_url="http://bob.com", uid="12345")],
destination_urls=[xml_objects.URL(value="http://destination1.com", meta_url="http://destination1.com/meta")],
tags=[xml_objects.Tag(meta_url="http://tag1.com", value="tag1"), xml_objects.Tag(meta_url="http://tag2.com", value="tag2")],
tos=[xml_objects.To(value="you", meta_url="http://you.com")],
regarding_urls=[xml_objects.URL(value="http://regarding1.com", meta_url="http://regarding2.com"), xml_objects.URL(value="http://regarding1.com", meta_url="http://regarding2.com")],
payload=a_payload)
an_activity.set_at_from_string("2008-07-02T11:16:16+00:00")
response = gnip.publish_activities("myPublisher", activities.Activities([an_activity]))
print response.code
=== Contributing ===
Contributions to this library are welcome.
Source :: git://github.com/gnip/gnip-python.git
Community Site :: http://groups.google.com/group/gnip-community
Mailing List :: [email protected]
To get started create a clone of the main repository,
<git://github.com/gnip/gnip-python.git>, and start improving it. Feel
discuss any changes you are making on the mailing list to get feed
back from the other users. Once you are ready to publish your changes
you can send them to the mailing list or, if you are using GitHub,
send a pull request to the owner of the main repositiory.