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:

[email protected]
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.