**************************************************************
*Python Sdk for the Facebook Graph Api*
**************************************************************
| **fb** is a python sdk for the Facebook Graph Api. The sdk provides three methods
| for interacting largely with facebook. publish(), get_object() and delete()
| In addtion to the three, there is one helper method to view the structure of
| objects returned from facebook, show_fields()
*Installation*
------------------
| **sudo pip install fb**
|
*1. Publishing to Facebook*
===========================
| For publishing, use the publish() method. Publishing means creating objects like:
| a wall post, a like, events and albums, etc. Currently photo upload
| is not supported. The method returns the id of the object created.
| At `developers.facebook.com/docs/reference/api/publishing/ <http://developers.facebook.com/docs/reference/api/publishing/>`_
| under **'Other Objects'**, see list of publish categories except "photos".
====================================
*Examples*
====================================
| import fb
| # Go to `developers.facebook.com/tools/explorer <http://developers.facebook.com/tools/explorer>`_ to generate test token
| token="*the facebook token you are going to use*"
| facebook=fb.graph.api(token)
|
| *#Post on the current user's wall*
| facebook.publish(cat="feed", id="me", message="My facebook status")
|
| *#Like an object(wall post, photo and anything thats likable in facebook) with id=object_id*
| facebook.publish(cat="likes", id=object_id)
|
| *#Comment on an objects thats commentable*
| facebook.publish(cat="comments", id=object_id, message="My comment")
|
| *#Create an album*
| facebook.publish(cat="albums", id="me", name="Album Name", message="Album Details")
|
| *Create an event*
| facebook.publish(cat="events", id="me", name="My Event", start_time="2013-10-16-12:20", end_time="2013-10-18-14:30" )
*Important*
-----------
| In addition to 'cat' (the category) and 'id', publish takes any parameter thats
| valid for the publish category(cat). Like "message" for wall post, "name" for albums,
| nothing for likes, etc. Check facebook doc for full list of valid parameters
| for each kind of publishing. If you find that a parameter is raising error,
| it maybe because this sdk does not yet support the parameter,please report such cases
| to the author.
*2. Fetch Objects from Facebook*
================================
| Objects can be fetched in two ways using the get_object() method.
| Fetch "single" object with it's given "fields" passed in a list.
| Or retrieve "multiple" objects passed with their "ids" in a list.
| The method returns the object as python dictionary containing related fields
=============================================
*Examples*
=============================================
| *#Retrieve given fields for a single object*
| object=facebook.get_object(cat="single", id=object_id, fields=["name", "email" ] )
|
| *#Retrieve ALL fields for a single object*
| object=facebook.get_object(cat="single", id=object_id, fields=[ ] )
|
| *#Rertieve multiple objects*
| object=facebook.get_object(cat="multiple", ids=['zuck', 'me'] )
*3. Delete Objects*
===================
| Deleting objects is simple. use the delete method and pass the id of the
| object to be deleted. Note that a "like" has no id in facebook, so in case of deleting
| a "LIKE", you have to pass the id of the object liked and the category of the delete
| which is "likes".
=============================================
*Examples*
=============================================
| *#Delete a status*
| facebook.delete(id=status_id)
|
| *#Delete a comment*
| facebook.delete(id=comment_id)
|
| *#Delete a "LIKE"*
| facebook.delete(cat="likes", id=object_id)
*4. The Helper Methods*
==============================
| As of version 0.4.0, there is one helper method, *show_fields()*. Using this method,
| it is possible to view the structure of the objects returned by facebook. This will help
| further manipulate the fetched objects for individual needs.
=============================================
*Examples*
=============================================
| *#Get "friends" and "education" of the current user*
| friends_and_education=facebook.get_object(cat='single', id='me', fields=['friends', 'education'])
| *#Display the Structure of the object returned from facebook graph*
| facebook.show_fields(friends_and_education)
|
| The method will print the following:
| ______________________
| education(list)
| school
| id
| name
| type
| year
| id
| name
| friends
| paging
| next
| data(list)
| name
| id
| id
| _______________________
| The above are all dictionary keys with sub-keys. Some of the keys are prefixed by "(list)"
| which means their values are saved inside a list and should be accessed through indexing.
| In line with the structure printed by the method, we can access various parts of the object
| fetched from facebook as shown below
|
| *# "name" of schools attended*
| friends_and_education['education'][0]['school']['name']
| friends_and_education['education'][1]['school']['name'] and so on........
|
| *# "type" of the nth school in the object*
| friends_and_education['education'][n]['type']
|
| *#"name" of the nth friend in the object*
| friends_and_education['friends']['data'][n]['name']
|
| *#"name" and "id" of all friends*
| friends_and_education['friends']['data']
|
| **Note:**
| The idea behind introducing the show_fields() method is to help developers
| get a visual overview of the internal structure of objects retrieved from facebook graph
| so that they can write their own methods easily to further meet their needs.
*Reporting issues*
==================
| Please report bugs `here <https://github.com/blaklites/fb/issues>`_. Or email to *blaklites@gmail.com*