= Gnip Client

This library provides a Python API for accessing
Gnip (http://gnipcentral.com) web services.  There are two basic
roles for using Gnip: subscribers and publishers.  This library
provides a single interface for both roles.

== Consumer

=== Example 1: Retrieve all recent activities at a publisher

As a consumer one thing you might be interested in immediately is to
grab recent activity at a particular publisher.  To do this you must
create a connection to Gnip using your user name and password.  Once
that connection is established you can get the publisher and request
its activities stream.  

    gnip = Gnip("[email protected]", "my-password")
    gnip.get_publisher_notifications("digg")

Alternatively, to retrieve the raw XML of the activities, do:

    gnip.get_publisher_notifications_xml("digg")


=== Example 2: Retrieve all activities at a publisher around a specific time

Some times you will want to get activity information from before now.
Doing this look much like getting the recent activity, except that you
past a time when getting the activity stream.  This will return the
activity stream as it existed around that time.  The results will be
include some activities before and after the time you specify.

    gnip = Gnip("[email protected]", "my-password")
    gnip.get_publisher_notifications("digg", datetime.datetime.utcnow() - 
        datetime.timedelta(minutes=30)) # 30 minutes ago


=== Example 3: Create an activity stream that includes only activities
    done by users you care about.

If you would like to filter a set of publishers by the user that
performed the activity you may create a filter to do so.  Once
created a filter's activity stream is retrieved much like a
publishers.  Activity that has already occured will not be included in
a filter.  Therefore any new filter will be empty until some
new matching activity has occured.

Note: Filter names must be unique across the system so you might
want to attach your username to the logical name of any filters
you create.

    gnip = Gnip("[email protected]", "my-password")

    my_filter = Filter(name="test-filter", 
        rules=[["actor", "me"], ["actor", "you"], ["actor", "bob"]])

    gnip.create_filter("digg", my_filter)
    gnip.get_filter_notifications("digg", my_filter)

=== Example 4: Delete a filter

If you decide you no longer need a filter you have created in the
past you can remove it.

    gnip = Gnip("[email protected]", "my-password")

    gnip.delete_filter("digg", "test-filter")

== Publisher

=== Example 1: Create a publisher and publish some activities

If you are interested in publishing activity you will need to create a
publisher.  Once the publisher resource is created, activities can be
published in it's activity stream.

    gnip = Gnip("[email protected]", "my-password")
    gnip.publish("digg")
    
    activity = Activity("joe", datetime.datetime.utcnow(), "post", 
        "http://mydomain.com/joe/my-new-blog-post");
    gnip.publish_activities(my_publisher, [activity])

== Additional notes

There are test cases included in the files "*Test.py". The test
cases also provide examples of usage. Note that you'll need to fill in the
information for the TEST_* constants at the top of the class, in order for
the test cases to work properly.

Docstrings are included for each class and method.

== Required libraries

DAVClient - http://pypi.python.org/pypi/davclient
 Note: please use the slightly modified version that is included

iso8601 - http://pypi.python.org/pypi/iso8601

== 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.