================================
Fedora Infrastructure Python API
================================
:Author: Toshio Kuratomi
:Date: 7 Apr 2008
:Version: 0.3.x

The Fedora module provides a python API for services used in Fedora
Infrastructure.  Its major usage is to talk to the Fedora Account System but
it is taking on new packages for dealing with other aspects of Fedora.  For
instance, a base class for interfacing a TurboGears server with a standalone
(commandline or desktop) client and a common set of templates for Fedora
TurboGears applications.

.. contents::

----------
Installing
----------

python-fedora is found in rpm form in Fedora Proper.  Sometimes a new version
will be placed in the Fedora Infrastructure yum repository for testing within
Infrastructure before being released to the general public.

From one of the machines in Fedora Infrastructure you can simply::

  # yum install python-fedora

to get the latest version.

If you want to install from a source checkout, follow these procedures::

  # bzr branch bzr://bzr.fedorahosted.org/bzr/python-fedora/python-fedora-devel
  # cd python-fedora-devel
  # python setup.py install
  
See the configuration notes in each section for information on configuring
your application after install.

---------------------------
Fedora Accounts Integration
---------------------------

This module allows code to integrate with the Fedora Accounts System.  It
provides two modules, a general purpose python API
and a TurboGears Identity Provider.  Because this module has to talk to the
account database it is currently not possible to use it outside of the
Fedora Infrastructure boxes.

General API
===========

Note: This API is not feature complete.  You can retrieve most information
about a person or group but setting information is not possible.  Work is
underway to create FAS2 based on an LDAP server so it is likely that this
FAS API will continue to be a read-only API.  Use the older website.py file
from the fedora-accounts cvs module if you need to write to the database.

Using the general API requires instantiating an AccountSystem object.  You
then use methods on the AccountSystem to get and set information on the
people in the account system.

The AccountSystem object implements basic authorization for the account system.
You tell the account system which user you are connecting as via the
`change_user()` method.  Then you request information from the AccountSystem
object.  The AccountSystem object will only retrieve information or set data
that the authenticated user is allowed to.

At the moment, there are only a few methods implemented.  Full documentation on these methods is available from the AccountSystem's docstrings from the
interpreter or, for instance, by running::

  $ pydoc fas.AccountSystem

from the directory that has fas.py in it.

* verify_user_pass()
* change_user()
* get_user_id()
* get_user_info()


Here's an example of using the AccountSystem::

  from fedora.accounts.fas import AccountSystem
  
  # Get an AccountSystem object.  When no user information is given you are
  # connected as an anonymous user.
  fas = AccountSystem()

  # Set the user connecting to "me"
  fas.change_user('me', 'mypassword')

  # Get the user information for the authorized user.
  MyInfo = fas.get_user_info()

  # Get user information for another user.
  YourInfo = fas.get_user_info('you')

  # Verify that a user-password combination is valid
  try:
      valid = fas.verify_user_pass('me', 'mypassword')
  except AuthError, e:
      # The user was not in the database.  Typically you don't want to tell the
      # application's user whether it was the username or password is bad.
      valid = False

  if not valid:
      print 'The username and password were not valid'

TurboGears Interface
====================

The TurboGears interface uses the general API to connect the TurboGears visit
and identity framework to your Fedora TurboGears application.  It does this
through an identity plugin.  A visit plugin is also provided at this time but
should go away once a few bugs are worked out of the TurboGears code.

Using the TurboGears interface will authenticate your users against the Fedora
Account System database and give your application a login session that can be
shared with other TurboGears applications using the safas identity plugin.

Configuring
-----------
To configure your TurboGears application, you need to set the following
variables in your pkgname/config/app.cfg file::

  visit.on=True
  visit.manager="safas"
  visit.saprovider.model="fedora.accounts.tgfas.Visit"
  identity.on="True"
  identity.failure_url="/login"
  identity.provider="safas"
  identity.saprovider.model.visit="fedora.accounts.tgfas.VisitIdentity"

If you are using sqlobject for your applications db access you may also have to
set this::

  sqlalchemy.dburi='sqlite://'

This is due to a bug in the way TurboGears handles the identity.  The dburi
listed there won't be used within the web application.

------
FAS v2
------

One of the goals for FAS v2 is to have an identity provider that can work
inside or outside of the Fedora network.  To do that we're creating a jsonfas
provider that contacts the FASv2 server over the internet.

FAS v2 -- TurboGears
====================

Configuring the TurboGears interface for fas v2 is almost the same as
configuring it for fas v1.  Here's what you should need::

  fas.url='https://admin.fedoraproject.org/accounts/'
  visit.on=True
  visit.manager="jsonfas"
  identity.on="True"
  identity.failure_url="/login"
  identity.provider="jsonfas"

------------------
TurboGears Widgets
------------------
We've started adding experimental TG Widgets to interact with specific aspects
of Fedora.

-----------------
TurboGears Client
-----------------
There is a module to make writing a client for our TurboGears services very
easy.  Please see the `client documentation`_ for more details

.. _`client documentation`: doc/client.rst
