Skip to main content

Easy Facebook integration for Django.

Project description

ECL Facebook

ECL Facebook is a Facebook library for Python 2.7+. It makes the Facebook API a joy to use and has built-in integration for Django and Flask.

If you have an issue to report or a feature request, add it at https://github.com/elmcitylabs/ECL-Facebook/issues.

Installation

ECL Facebook is on PyPi, and we recommend installing via pip

$ pip install ecl-facebook

Configuration

If you’d like to use ECL Facebook for a stand alone application (e.g., in a script you’re writing to download your tweets), you’ll need to set the environment variables FACEBOOK_KEY, FACEBOOK_SECRET, FACEBOOK_REDIRECT_URL, and FACEBOOK_SCOPE with the values appropriate for your Facebook application.

export FACEBOOK_KEY="256064624431781"
export FACEBOOK_SECRET="4925935cb93e3446eff851ddaf5fad07"
export FACEBOOK_REDIRECT_URL="http://example.com/oauth/complete"
export FACEBOOK_SCOPE="email"

If you’re only interested in integration with Django, read the section below.

Authentication

We’ve made authentication very simple. Probably too simple, to be honest.

>>> from ecl_facebook.settings import DIALOG_URL
>>> DIALOG_URL
https://www.facebook.com/dialog/oauth?scope=email&redirect_uri=http%3A%2F%2Fexample.com%2Fredirect&client_id=340516819320318

After opening this URL in your browser and allowing the application, you’ll be redirected to a page with a URL similar to the following.

http://example.com/redirect?code=AQDOvI5wqlwNXQ6AK9jepHW4LUKboJk7v9yLGeaFNCDCs1hchWpCYoqDF0FZFLS03YOZJ1lLhrzQrQ7PNWD2iiZZ6IBaW0KG6255_e3prYu60QZd6_IOIiC1z0U3w2SWJDiq_rtD0KQtcJk__YvZa1XSicZA5fnyEtEZBE3XzNpEgzp1fZZ8HEeQCrqazGjUNjU#_=_

You’ll need to paste this code in the code variable below.

>>> from ecl_facebook import Facebook
>>> code = "AQDOvI5wqlwNXQ6AK9jepHW4LUKboJk7v9yLGeaFNCDCs1hchWpCYoqDF0FZFLS03YOZJ1lLhrzQrQ7PNWD2iiZZ6IBaW0KG6255_e3prYu60QZd6_IOIiC1z0U3w2SWJDiq_rtD0KQtcJk__YvZa1XSicZA5fnyEtEZBE3XzNpEgzp1fZZ8HEeQCrqazGjUNjU"
>>> facebook = Facebook()
>>> data = facebook.oauth.access_token(code=code)
>>> data
<Objectifier#dict access_token=str expires=str>

Congratulations, you have successfully authenticated with Facebook. data is an Objectifier object which should contains your token and its expiration time.

To call the API, use your newly-acquired access token and access token secret.

>>> facebook = Facebook(data.access_token)
>>> facebook.me()
<Objectifier#dict username=unicode first_name=unicode last_name=unicode verified=bool name=unicode locale=unicode gender=unicode email=unicode link=unicode timezone=int updated_time=unicode id=unicode>

So, yeah. That’s it. Be fruitful and multiply.

Integrating with Django

What we did above is easy. For Django projects, we’ve made it even easier. In your views file,

from django.contrib.auth import authenticate, login
from django.http import HttpResponseRedirect

from ecl_facebook.django_decorators import facebook_begin, facebook_callback
from ecl_facebook import Facebook

from .models import User

# ...

@facebook_begin
def oauth_facebook_begin(request):
    pass

@facebook_callback
def oauth_facebook_complete(request, access_token, error):
    if error is None:
        facebook = Facebook(token)
        fbuser = facebook.me()
        user, _ = User.objects.get_or_create(facebook_id=fbuser.id, defaults={
            'access_token': access_token})
        user = authenticate(id=user.id)
        login(request, user)
        return HttpResponseRedirect(reverse('home'))
    else:
        # handle authentication exception
        pass

Of course, you’ll need to have a URL with the name home defined in your URLs file. Now, add these values to your settings.

# The User model that you'll be using to authenticate with Facebook.
PRIMARY_USER_MODEL = "app.User"

AUTHENTICATION_BACKENDS = (
    # ...
    'ecl_facebook.backends.FacebookAuthBackend',
)

FACEBOOK_KEY = "256064624431781"
FACEBOOK_SECRET = "4925935cb93e3446eff851ddaf5fad07"
FACEBOOK_REDIRECT_URL = "http://example.com/oauth/complete"
FACEBOOK_SCOPE = "email"

There’s also setting called FACEBOOK_CSRF_TOKEN_REQUIRED, which is True by default. We don’t suggest you change this one unless you have a really good reason.

Then map the above views in your urls.py.

# ...

urlpatterns = patterns('app.views',
    # ...
    url(r'^oauth/facebook/begin$', 'oauth_facebook_begin'),
    url(r'^oauth/facebook/complete$', 'oauth_facebook_complete'),
)

You’re done. Oh, you might also want to add some fields for storing the Facebook-related fields in your user model.

TODO

  • Decorators for other popular Python frameworks.

  • More comprehensive test suite.

  • More users!

Contributing, feedback, and questions

Indices and tables

  • genindex

  • modindex

  • search

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ecl_facebook-1.4.1.tar.gz (9.0 kB view details)

Uploaded Source

File details

Details for the file ecl_facebook-1.4.1.tar.gz.

File metadata

  • Download URL: ecl_facebook-1.4.1.tar.gz
  • Upload date:
  • Size: 9.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for ecl_facebook-1.4.1.tar.gz
Algorithm Hash digest
SHA256 75e01a39ed21616acee7a186f3a1c274dd19dd1b47a56292fa223b7120135de4
MD5 76f446e5dab6f311e337c505f197af87
BLAKE2b-256 bffa6951aaa4340980278544feaf830ad16a053ed258beccbe9fdd35f25db233

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page