========
stepford
========

.. contents::
   :depth: 2

Overview
========

Integration testing is generally a pain. Stepford attempts to 
alleviate as much of that pain as possible for apps requiring integration
with the Facebook Graph API. Stepford is a Python implementation of the
Facebook test user API as defined at https://developers.facebook.com/docs/test_users.

Usage
=====

Getting your app token
----------------------

App tokens are access tokens that are bound to your application. They allow you
to make requests on behalf of your application. Your app access token is
required to interact with Facebook's test user API. There are two methods to
get your app token:

Facebook Tools
``````````````

https://developers.facebook.com/tools/access_token/

Programmatically
````````````````

.. code-block:: python

    from stepford import app_token
    token = app_token([client_id], [client_secret])

.. warning:: App tokens expire the same as other tokens. So, while the Facebook
             tool is useful for retrieving them for immediate use, it will 
             eventually break in an automated environment.

Getting available users
-----------------------

.. code-block:: python

    import stepford
    users = stepford.get([client_id], [app_token])

This returns a list of dicts with test user details. The data is structured 
like so:

.. code-block:: python

    [
        {
            'access_token': [snip],
            'login_url': [snip],
            'id': [snip]
        },
        [...]
    ]

Creating a user
---------------

.. code-block:: python

    import stepford
    user = stepford.create([client_id], [app_token])

Creates a single test user:

.. code-block:: python 

    {
        'access_token': [snip],
        'login_url': [snip],
        'id': [snip]
    }

Updating a user
---------------

Facebook offers the ability to update two test user attributes: name and
password.

.. code-block:: python

    import stepford
    stepford.update(userid, [app_token], name='[name]', pwd='[pwd]')

.. warning:: Changing the user's password will result in the expiry of the
             current token. The only resolution to this (AFAIK) is to do a full
             get of the user list (:meth:`stepford.get`), filtering for that user
             ID.

Deleting users
--------------

.. code-block:: python

    import stepford
    stepford.delete(userid, [app_token]) 

.. note:: Attempting to delete a user who has multiple apps installed will
          result in an exception being raised. Users must have all apps
          (short of the owner app) uninstalled prior to deletion (see
          :meth:`stepford.uninstall`).

Making friends
--------------

:meth:`stepford.connect` takes an arbitrary length (langth <= 1 will result in 
a ``ValueError`` exception) list of users to connect to each other. Each user
object is expected to be of the same format as returned by
:meth:`stepford.create`.

.. code-block:: python

    import stepford
    users = [stepford.create([client_id], [app_token]) for _ in range(10)]
    stepford.connect(*users)

The above code creates 10 users and then creates friendships between each.

Installing apps
---------------

.. code-block:: python

    import stepford
    stepford.install(user['id'], [install_to_app_token], [client_id],
        [app_token], scope='read_stream')

Installing applications to test users is a little odd. You need the app access
token of the app being installed, which makes you unable to install arbitrary
applications. ``client_id`` and ``app_token`` are those of the application used
to create the test user.

Uninstalling apps
-----------------

.. code-block:: python

    import stepford
    stepford.uninstall(user['id'], [client_id], [app_token])

The above uninstalls an app for a test user. The ``client_id`` and
``app_token`` in this case are those of the install app (not the owner app).

Error handling
--------------

All errors generated by the Facebook test user API are translated to
:class:`stepford.FacebookError`, which is a subclass of
:py:class:`urllib2.HTTPError`. In addition to the usual HTTP ``code``
attribute, this class also provides you with the ``api_code``, which can be
used to retrieve the specific Facebook client-facing error code. Additionally,
it translates the JSON error message to ``HTTPError.msg``.

There are a few constants defined in ``stepford.py`` that define either errors
encountered during testing and/or errors defined in Facebook's test user API
docs.

API
===

.. automodule:: stepford
   :members:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`