.\" Man page generated from reStructuredText.
.
.TH "PYTHON-FEDORA" "1" "December 21, 2020" "0.3" "python-fedora"
.SH NAME
python-fedora \- python-fedora 1.1.1
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
The python\-fedora module makes it easier for programmers to create both Fedora
Services and clients that talk to the services.  It\(aqs licensed under the GNU
Lesser General Public License version 2 or later.
.SH FEDORA CLIENT
.INDENT 0.0
.TP
.B Authors
Toshio Kuratomi
Luke Macken
.TP
.B Date
28 May 2008
.TP
.B For Version
0.3.x
.UNINDENT
.sp
The client module allows you to easily code an application that talks to a
\fI\%Fedora Service\fP\&.  It handles the details of decoding the data sent from the
Service into a python data structure and raises an \fI\%Exception\fP if an error is
encountered.
.SS BaseClient
.sp
The \fBBaseClient\fP class is the basis of all your
interactions with the server.  It is flexible enough to be used as is for
talking with a service but is really meant to be subclassed and have methods
written for it that do the things you specifically need to interact with the
\fI\%Fedora Service\fP you care about.  Authors of a \fI\%Fedora Service\fP are
encouraged to provide their own subclasses of
\fBBaseClient\fP that make it easier for other people to use
a particular Service out of the box.
.SS Using Standalone
.sp
If you don\(aqt want to subclass, you can use \fBBaseClient\fP
as a utility class to talk to any \fI\%Fedora Service\fP\&.  There\(aqs three steps to
this.  First you import the \fBBaseClient\fP and \fI\%Exceptions\fP
from the \fBfedora.client\fP module.  Then you create a new
\fBBaseClient\fP with the URL that points to the root of the
\fI\%Fedora Service\fP you\(aqre interacting with.  Finally, you retrieve data from a
method on the server.  Here\(aqs some code that illustrates the process:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from fedora.client import BaseClient, AppError, ServerError

client = BaseClient(\(aqhttps://admin.fedoraproject.org/pkgdb\(aq)
try:
    collectionData = client.send_request(\(aq/collections\(aq, auth=False)
except ServerError as e:
    print(\(aq%s\(aq % e)
except AppError as e:
    print(\(aq%s: %s\(aq % (e.name, e.message))

for collection in collectionData[\(aqcollections\(aq]:
    print(\(aq%s %s\(aq % (collection[\(aqname\(aq], collection[\(aqversion\(aq])
.ft P
.fi
.UNINDENT
.UNINDENT
.SS BaseClient Constructor
.sp
In our example we only provide \fBBaseClient()\fP with the URL fragment it uses
as the base of all requests.  There are several more optional parameters that
can be helpful.
.sp
If you need to make an authenticated request you can specify the username and
password to use when you construct your \fBBaseClient\fP
using the \fBusername\fP and \fBpassword\fP keyword arguments.  If you do not use
these, authenticated requests will try to connect via a cookie that was saved
from previous runs of \fBBaseClient\fP\&.  If that fails as
well, \fBBaseClient\fP will throw an \fI\%Exception\fP which you
can catch in order to prompt for a new username and password:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from fedora.client import BaseClient, AuthError
import getpass
MAX_RETRIES = 5
client = BaseClient(\(aqhttps://admin.fedoraproject.org/pkgdb\(aq,
        username=\(aqfoo\(aq, password=\(aqbar\(aq)
# Note this is simplistic.  It only prompts once for another password.
# Your application may want to loop through this several times.
while (count < MAX_RETRIES):
    try:
        collectionData = client.send_request(\(aq/collections\(aq, auth=True)
    except AuthError as e:
        client.password = getpass.getpass(\(aqRetype password for %s: \(aq % username)
    else:
        # data retrieved or we had an error unrelated to username/password
        break
    count = count + 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Note that although you can set the \fBusername\fP and \fBpassword\fP as shown
above you do have to be careful in cases where your application is
multithreaded or simply processes requests for more than one user with the
same \fBBaseClient\fP\&.  In those cases, you can
accidentally overwrite the \fBusername\fP and \fBpassword\fP between two
requests.  To avoid this, make sure you instantiate a separate
\fBBaseClient\fP for every thread of control or for
every request you handle or use \fBProxyClient\fP
instead.
.UNINDENT
.UNINDENT
.sp
The \fBuseragent\fP parameter is useful for identifying in log files that your
script is calling the server rather than another.  The default value is
\fBFedora BaseClient/VERSION\fP where VERSION is the version of the
\fBBaseClient\fP module.  If you want to override this just
give another string to this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
client = BaseClient(\(aqhttps://admin.fedoraproject.org/pkgdb\(aq,
        useragent=\(aqPackage Database Client/1.0\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBdebug\fP parameter turns on a little extra output when running the
program.  Set it to true if you\(aqre having trouble and want to figure out what
is happening inside of the \fBBaseClient\fP code.
.SS send_request()
.sp
\fBsend_request()\fP is what does the heavy lifting of making a request of the
server, receiving the reply, and turning that into a python dictionary.  The
usage is pretty straightforward.
.sp
The first argument to \fBsend_request()\fP is \fBmethod\fP\&. It contains the name
of the method on the server.  It also has any of the positional parameters
that the method expects (extra path information interpreted by the server for
those building non\-\fI\%TurboGears\fP applications).
.sp
The \fBauth\fP keyword argument is a boolean.  If True, the session cookie for
the user is sent to the server.  If this fails, the \fBusername\fP and
\fBpassword\fP are sent.  If that fails, an \fI\%Exception\fP is raised that you can
handle in your code.
.sp
\fBreq_params\fP contains a dictionary of additional keyword arguments for the
server method.  These would be the names and values returned via a form if it
was a CGI.  Note that parameters passed as extra path information should be
added to the \fBmethod\fP argument instead.
.sp
An example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import BaseClient
client = BaseClient(\(aqhttps://admin.fedoraproject.org/pkgdb/\(aq)
client.send_request(\(aq/package/name/python\-fedora\(aq, auth=False,
        req_params={\(aqcollectionVersion\(aq: \(aq9\(aq, \(aqcollectionName\(aq: \(aqFedora\(aq})
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this particular example, knowing how the server works, \fB/packages/name/\fP
defines the method that the server is going to invoke.  \fBpython\-fedora\fP is a
positional parameter for the name of the package we\(aqre looking up.
\fBauth=False\fP means that we\(aqll try to look at this method without having to
authenticate.  The \fBreq_params\fP sends two additional keyword arguments:
\fBcollectionName\fP which specifies whether to filter on a single distro or
include Fedora, Fedora EPEL, Fedora OLPC, and Red Hat Linux in the output and
\fBcollectionVersion\fP which specifies which version of the distribution to
output for.
.sp
The URL constructed by \fBBaseClient\fP to the server could
be expressed as[#]_:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
https://admin.fedoraproject.org/pkgdb/package/name/python\-fedora/?collectionName=Fedora&collectionVersion=9
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In previous releases of python\-fedora, there would be one further query
parameter:  \fBtg_format=json\fP\&.  That parameter instructed the server to
return the information as JSON data instead of HTML.  Although this is usually
still supported in the server, \fBBaseClient\fP has
deprecated this method.  Servers should be configured  to use an \fBAccept\fP
header to get this information instead.  See the \fI\%JSON output\fP section of the
\fI\%Fedora Service\fP documentation for more information about the server side.
.SS Subclassing
.sp
Building a client using subclassing builds on the information you\(aqve already
seen inside of \fBBaseClient\fP\&.  You might want to use this
if you want to provide a module for third parties to access a particular
\fI\%Fedora Service\fP\&.  A subclass can provide a set of standard methods for
calling the server instead of forcing the user to remember the URLs used to
access the server directly.
.sp
Here\(aqs an example that turns the previous calls into the basis of a python API
to the \fI\%Fedora Package Database\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import getpass
import sys
from fedora.client import BaseClient, AuthError

class MyClient(BaseClient):
    def __init__(self, baseURL=\(aqhttps://admin.fedoraproject.org/pkgdb\(aq,
            username=None, password=None,
            useragent=\(aqPackage Database Client/1.0\(aq, debug=None):
        super(BaseClient, self).__init__(baseURL, username, password,
                useragent, debug)

    def collection_list(self):
        \(aq\(aq\(aqReturn a list of collections.\(aq\(aq\(aq
        return client.send_request(\(aq/collection\(aq)

    def package_owners(self, package, collectionName=None,
            collectionVersion=None):
        \(aq\(aq\(aqReturn a mapping of release to owner for this package.\(aq\(aq\(aq
        pkgData = client.send_request(\(aq/packages/name/%s\(aq % (package),
                {\(aqcollectionName\(aq: collectionName,
                \(aqcollectionVersion\(aq: collectionVersion})
        ownerMap = {}
        for listing in pkgData[\(aqpackageListings\(aq]:
            ownerMap[\(aq\-\(aq.join(listing[\(aqcollection\(aq][\(aqname\(aq],
                    listing[\(aqcollection\(aq][\(aqversion\(aq])] = \e
                    listing[\(aqowneruser\(aq]
        return ownerMap
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A few things to note:
.INDENT 0.0
.IP 1. 3
In our constructor we list a default \fBbaseURL\fP and \fBuseragent\fP\&.  This
is usually a good idea as we know the URL of the \fI\%Fedora Service\fP we\(aqre
connecting to and we want to know that people are using our specific API.
.IP 2. 3
Sometimes we\(aqll want methods that are thin shells around the server methods
like \fBcollection_list()\fP\&.  Other times we\(aqll want to do more
post processing to get specific results as \fBpackage_owners()\fP does.  Both
types of methods are valid if they fit the needs of your API.  If you find
yourself writing more of the latter, though, you may want to consider
getting a new method implemented in the server that can return results more
appropriate to your needs as it could save processing on the server and
bandwidth downloading the data to get information that more closely matches
what you need.
.UNINDENT
.sp
See \fBpydoc fedora.client.fas2\fP for a module that implements a standard
client API for the \fI\%Fedora Account System\fP
.SS Handling Errors
.sp
\fBBaseClient\fP will throw a variety of errors that can be
caught to tell you what kind of error was generated.
.SS Exceptions
.INDENT 0.0
.TP
.B \fBFedoraServiceError\fP
The base of all exceptions raised by
\fBBaseClient\fP\&.  If your code needs to catch any of the
listed errors then you can catch that to do so.
.TP
.B \fBServerError\fP
Raised if there\(aqs a problem communicating with the service.
For instance, if we receive an HTML response instead of JSON.
.TP
.B \fBAuthError\fP
If something happens during authentication, like an invalid
usernsme or password, \fBAuthError\fP will be raised.  You can catch this to
prompt the user for a new usernsme.
.TP
.B \fBAppError\fP
If there is a \fI\%server side error\fP when processing a request,
the \fI\%Fedora Service\fP can alert the client of this by setting certain
flags in the response.  \fBBaseClient\fP  will see these
flags and raise an AppError.  The name of the error will be stored in
AppError\(aqs \fBname\fP field.  The error\(aqs message will be stored in
\fBmessage\fP\&.
.UNINDENT
.SS Example
.sp
Here\(aqs an example of the exceptions in action:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from fedora.client import ServerError, AuthError, AppError, BaseClient
import getpass
MAXRETRIES = 5

client = BaseClient(\(aqhttps://admin.fedoraproject.org/pkgdb\(aq)
for retry in range(0, MAXRETRIES):
    try:
        collectionData = client.send_request(\(aq/collections\(aq, auth=True)
    except AuthError as e:
        from six.moves import input
        client.username = input(\(aqUsername: \(aq).strip()
        client.password = getpass.getpass(\(aqPassword: \(aq)
        continue
    except ServerError as e:
        print(\(aqError talking to the server: %s\(aq % e)
        break
    except AppError as e:
        print(\(aqThe server issued the following exception: %s: %s\(aq % (
              e.name, e.message))

    for collection in collectionData[\(aqcollections\(aq]:
        print(\(aq%s %s\(aq % (collection[0][\(aqname\(aq], collection[0][\(aqversion\(aq]))
.ft P
.fi
.UNINDENT
.UNINDENT
.SS OpenIdBaseClient
.sp
Applications that use OpenId to authenticate are not able to use the standard
BaseClient because the pattern of authenticating is very different.  We\(aqve
written a separate client object called
\fBOpenIdBaseClient\fP to do this.
.SH EXISTING SERVICES
.sp
There are many Services in Fedora.  Many of these have an interface that we
can query and get back information as JSON data.  There is
documentation here about both the services and the client modules that can
access them.
.SS Fedora Account System
.sp
FAS is the Fedora Account System.  It holds the account data for all of our
contributors.
.INDENT 0.0
.TP
.B class fedora.client.AccountSystem(base_url=\(aqhttps://admin.fedoraproject.org/accounts/\(aq, *args, **kwargs)
An object for querying the Fedora Account System.
.sp
The Account System object provides a python API for talking to the Fedora
Account System.  It abstracts the http requests, cookie handling, and
other details so you can concentrate on the methods that are important to
your program.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
If your code is trying to use the AccountSystem object to
connect to fas for multiple users you probably want to use
\fI\%FasProxyClient\fP instead.  If your code is
trying to reuse a single instance of AccountSystem for multiple users
you \fIdefinitely\fP want to use \fI\%FasProxyClient\fP
instead.  Using AccountSystem in these cases may result in a user
being logged in as a different user.  (This may be the case even if
you instantiate a new AccountSystem object for each user if
:attr:cache_session: is True since that creates a file on the file
system that can end up loading session credentials for the wrong
person.
.UNINDENT
.UNINDENT
.sp
Changed in version 0.3.26: Added \fI\%gravatar_url()\fP that returns
a url to a gravatar for a user.

.sp
Changed in version 0.3.33: Renamed \fI\%gravatar_url()\fP to
\fI\%avatar_url()\fP\&.

.INDENT 7.0
.TP
.B avatar_url(username, size=64, default=None, lookup_email=True, service=None)
Returns a URL to an avatar for a given username.
.sp
Avatars are drawn from third party services.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBusername\fP \-\- FAS username to construct a avatar url for
.IP \(bu 2
\fBsize\fP \-\- size of the avatar.  Allowed sizes are 32, 64, 140.
Default: 64
.IP \(bu 2
\fBdefault\fP \-\- If the service does not have a avatar image for the
email address, this url is returned instead.  Default:
the fedora logo at the specified size.
.IP \(bu 2
\fBlookup_email\fP \-\- If true, use the email from FAS for gravatar.com
lookups, otherwise just append @fedoraproject.org to the username.
For libravatar.org lookups, this is ignored.  The openid identifier
of the user is used instead.
Note that gravatar.com lookups will be much slower if lookup_email
is set to True since we\(aqd have to make a query against FAS itself.
.IP \(bu 2
\fBservice\fP \-\- One of \(aqlibravatar\(aq or \(aqgravatar\(aq.
Default: \(aqlibravatar\(aq.
.UNINDENT
.TP
.B Raises
\fBValueError\fP \-\- if the size parameter is not allowed or if the
service is not one of \(aqlibravatar\(aq or \(aqgravatar\(aq
.TP
.B Return type
\fBstr\fP
.TP
.B Returns
url of a avatar for the user
.UNINDENT
.sp
If that user has no avatar entry, instruct the remote service to
redirect us to the Fedora logo.
.sp
If that user has no email attribute, then make a fake request to
the third party service.
.sp
New in version 0.3.26.

.UNINDENT
.INDENT 7.0
.TP
.B create_group(name, display_name, owner, group_type, invite_only=0, needs_sponsor=0, user_can_remove=1, prerequisite=\(aq\(aq, joinmsg=\(aq\(aq, apply_rules=\(aqNone\(aq)
Creates a FAS group.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The short group name (alphanumeric only).
.IP \(bu 2
\fBdisplay_name\fP \-\- A longer version of the group\(aqs name.
.IP \(bu 2
\fBowner\fP \-\- The username of the FAS account which owns the new group.
.IP \(bu 2
\fBgroup_type\fP \-\- The kind of group being created. Current valid options
are git, svn, hg, shell, and tracking.
.IP \(bu 2
\fBinvite_only\fP \-\- Users must be invited to the group, they cannot
join on their own.
.IP \(bu 2
\fBneeds_sponsor\fP \-\- Users must be sponsored into the group.
.IP \(bu 2
\fBuser_can_remove\fP \-\- Users can remove themselves from the group.
.IP \(bu 2
\fBprerequisite\fP \-\- Users must be in the given group (string) before
they can join the new group.
.IP \(bu 2
\fBjoinmsg\fP \-\- A message shown to users when they apply to the group.
.IP \(bu 2
\fBapply_rules\fP \-\- Rules for applying to the group, shown to users
before they apply.
.UNINDENT
.TP
.B Return type
\fBmunch.Munch\fP
.TP
.B Returns
A Munch containing information about the group that was
created.
.UNINDENT
.sp
New in version 0.3.29.

.UNINDENT
.INDENT 7.0
.TP
.B get_config(username, application, attribute)
Return the config entry for the key values.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBusername\fP \-\- Username of the person
.IP \(bu 2
\fBapplication\fP \-\- Application for which the config is set
.IP \(bu 2
\fBattribute\fP \-\- Attribute key to lookup
.UNINDENT
.TP
.B Raises
\fBAppError\fP \-\- if the server returns an exception
.TP
.B Returns
The unicode string that describes the value.  If no entry
matched the username, application, and attribute then None is
returned.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B get_configs_like(username, application, pattern=\(aq*\(aq)
Return the config entries that match the keys and the pattern.
.sp
Note: authentication on the server will prevent anyone but the user
or a fas admin from viewing or changing their configs.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBusername\fP \-\- Username of the person
.IP \(bu 2
\fBapplication\fP \-\- Application for which the config is set
.IP \(bu 2
\fBpattern\fP \-\- A pattern to select values for.  This accepts * as a
wildcard character. Default=\(aq*\(aq
.UNINDENT
.TP
.B Raises
\fBAppError\fP \-\- if the server returns an exception
.TP
.B Returns
A dict mapping \fBattribute\fP to \fBvalue\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B gravatar_url(*args, **kwargs)
\fIDeprecated\fP \- Use avatar_url.
.sp
New in version 0.3.26.

.UNINDENT
.INDENT 7.0
.TP
.B group_by_id(group_id)
Returns a group object based on its id
.UNINDENT
.INDENT 7.0
.TP
.B group_by_name(groupname)
Returns a group object based on its name
.UNINDENT
.INDENT 7.0
.TP
.B group_data(force_refresh=None)
Return administrators/sponsors/users and group type for all groups
.INDENT 7.0
.TP
.B Parameters
\fBforce_refresh\fP \-\- If true, the returned data will be queried from the
database, as opposed to memcached.
.TP
.B Raises
\fBAppError\fP \-\- if the query failed on the server
.TP
.B Returns
A dict mapping group names to the group type and the
user IDs of the administrator, sponsors, and users of the group.
.UNINDENT
.sp
New in version 0.3.8.

.UNINDENT
.INDENT 7.0
.TP
.B group_members(groupname)
Return a list of people approved for a group.
.sp
This method returns a list of people who are in the requested group.
The people are all approved in the group.  Unapproved people are not
shown.  The format of data is:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\e[{\(aqusername\(aq: \(aqperson1\(aq, \(aqrole_type\(aq: \(aquser\(aq},
\e{\(aqusername\(aq: \(aqperson2\(aq, \(aqrole_type\(aq: \(aqsponsor\(aq}]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
role_type can be one of \(aquser\(aq, \(aqsponsor\(aq, or \(aqadministrator\(aq.
.sp
New in version 0.3.2.

.sp
Changed in version 0.3.21: Return a Bunch instead of a DictContainer

.UNINDENT
.INDENT 7.0
.TP
.B property insecure
If this attribute is set to True, do not check server certificates
against their CA\(aqs.  This means that man\-in\-the\-middle attacks are
possible. You might turn this option on for testing against a local
version of a server with a self\-signed certificate but it should be off
in production.
.UNINDENT
.INDENT 7.0
.TP
.B people_by_groupname(groupname)
Return a list of persons for the given groupname.
.INDENT 7.0
.TP
.B Parameters
\fBgroupname\fP \-\- Name of the group to look up
.TP
.B Returns
A list of person objects from the group.  If the group
contains no entries, then an empty list is returned.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B people_by_id()
\fIDeprecated\fP Use people_by_key() instead.
.sp
Returns a dict relating user IDs to human_name, email, username,
and bugzilla email
.sp
Changed in version 0.3.21: Return a Bunch instead of a DictContainer

.UNINDENT
.INDENT 7.0
.TP
.B people_by_key(key=\(aqusername\(aq, search=\(aq*\(aq, fields=None)
Return a dict of people
.sp
For example:
.sp
.nf
.ft C
>>> ret_val = FASCLIENT.people_by_key(
\&...     key=\(aqemail\(aq, search=\(aqtoshio*\(aq, fields=[\(aqid\(aq])
>>> ret_val.keys()
a.badger@[...].com
a.badger+test1@[...].com
a.badger+test2@[...].com
>>> ret_val.values()
100068
102023
102434
.ft P
.fi
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBkey\fP \-\- Key used to organize the returned dictionary.  Valid values
are \(aqid\(aq, \(aqusername\(aq, or \(aqemail\(aq.  Default is \(aqusername\(aq.
.IP \(bu 2
\fBsearch\fP \-\- Pattern to match usernames against.  Defaults to the
\(aq*\(aq wildcard which matches everyone.
.IP \(bu 2
\fBfields\fP \-\- 
.sp
Limit the data returned to a specific list of fields.
The default is to retrieve all fields.
Valid fields are:
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
affiliation
.IP \(bu 2
alias_enabled
.IP \(bu 2
bugzilla_email
.IP \(bu 2
certificate_serial
.IP \(bu 2
comments
.IP \(bu 2
country_code
.IP \(bu 2
creation
.IP \(bu 2
email
.IP \(bu 2
emailtoken
.IP \(bu 2
facsimile
.IP \(bu 2
gpg_keyid
.IP \(bu 2
group_roles
.IP \(bu 2
human_name
.IP \(bu 2
id
.IP \(bu 2
internal_comments
.IP \(bu 2
ircnick
.IP \(bu 2
last_seen
.IP \(bu 2
latitude
.IP \(bu 2
locale
.IP \(bu 2
longitude
.IP \(bu 2
memberships
.IP \(bu 2
old_password
.IP \(bu 2
password
.IP \(bu 2
password_changed
.IP \(bu 2
passwordtoken
.IP \(bu 2
postal_address
.IP \(bu 2
privacy
.IP \(bu 2
roles
.IP \(bu 2
ssh_key
.IP \(bu 2
status
.IP \(bu 2
status_change
.IP \(bu 2
telephone
.IP \(bu 2
timezone
.IP \(bu 2
unverified_email
.IP \(bu 2
username
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Note that for most users who access this data, many of these
fields will be set to None due to security or privacy settings.

.UNINDENT
.TP
.B Returns
a dict relating the key value to the fields.
.UNINDENT
.sp
Changed in version 0.3.21: Return a Bunch instead of a DictContainer

.sp
Changed in version 0.3.26: Fixed to return a list with both people who have signed the CLA
and have not

.UNINDENT
.INDENT 7.0
.TP
.B people_query(constraints=None, columns=None)
Returns a list of dicts representing database rows
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBconstraints\fP \-\- A dictionary specifying WHERE constraints on columns
.IP \(bu 2
\fBcolumns\fP \-\- A list of columns to be selected in the query
.UNINDENT
.TP
.B Raises
\fBAppError\fP \-\- if the query failed on the server (most likely
because  the server was given a bad query)
.TP
.B Returns
A list of dicts representing database rows (the keys of
the dict are the columns requested)
.UNINDENT
.sp
New in version 0.3.12.1.

.UNINDENT
.INDENT 7.0
.TP
.B person_by_id(person_id)
Returns a person object based on its id
.UNINDENT
.INDENT 7.0
.TP
.B person_by_username(username)
Returns a person object based on its username
.UNINDENT
.INDENT 7.0
.TP
.B proxy = None
.UNINDENT
.INDENT 7.0
.TP
.B set_config(username, application, attribute, value)
Set a config entry in FAS for the user.
.sp
Note: authentication on the server will prevent anyone but the user
or a fas admin from viewing or changing their configs.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBusername\fP \-\- Username of the person
.IP \(bu 2
\fBapplication\fP \-\- Application for which the config is set
.IP \(bu 2
\fBattribute\fP \-\- The name of the config key that we\(aqre setting
.IP \(bu 2
\fBvalue\fP \-\- The value to set this to
.UNINDENT
.TP
.B Raises
\fBAppError\fP \-\- if the server returns an exception
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B user_data()
Return user data for all users in FAS
.sp
Note: If the user is not authorized to see password hashes,
\(aq*\(aq is returned for the hash.
.INDENT 7.0
.TP
.B Raises
\fBAppError\fP \-\- if the query failed on the server
.TP
.B Returns
A dict mapping user IDs to a username, password hash,
SSH public key, email address, and status.
.UNINDENT
.sp
New in version 0.3.8.

.UNINDENT
.INDENT 7.0
.TP
.B user_gencert()
Generate a cert for a user
.UNINDENT
.INDENT 7.0
.TP
.B user_id()
Returns a dict relating user IDs to usernames
.UNINDENT
.INDENT 7.0
.TP
.B verify_password(username, password)
Return whether the username and password pair are valid.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBusername\fP \-\- username to try authenticating
.IP \(bu 2
\fBpassword\fP \-\- password for the user
.UNINDENT
.TP
.B Returns
True if the username/password are valid.  False otherwise.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Threadsafe Account System Access
.sp
It is not safe to use a single instance of the
\fI\%AccountSystem\fP object in multiple threads.  This is
because instance variables are used to hold some connection\-specific
information (for instance, the user who is logging in).  For this reason, we
also provide the \fI\%fedora.client.FasProxyClient\fP object.
.sp
This is especially handy when writing authn and authz adaptors that talk to
fas from a multithreaded webserver.
.INDENT 0.0
.TP
.B class fedora.client.FasProxyClient(base_url=\(aqhttps://admin.fedoraproject.org/accounts/\(aq, *args, **kwargs)
A threadsafe client to the Fedora Account System.
.INDENT 7.0
.TP
.B get_user_info(auth_params)
Retrieve information about a logged in user.
.INDENT 7.0
.TP
.B Parameters
\fBauth_params\fP \-\- Auth information for a particular user.  For
instance, this can be a username/password pair or a session_id.
Refer to
\fBfedora.client.proxyclient.ProxyClient.send_request()\fP for all
the legal values for this.
.TP
.B Returns
a tuple of session_id and information about the user.
.TP
.B Raises
\fBAuthError\fP \-\- if the auth_params do not give access
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B group_list(auth_params)
Retrieve a list of groups
.INDENT 7.0
.TP
.B Parameters
\fBauth_params\fP \-\- Auth information for a particular user.  For
instance, this can be a username/password pair or a session_id.
Refer to
\fBfedora.client.proxyclient.ProxyClient.send_request()\fP for all
the legal values for this.
.TP
.B Returns
a tuple of session_id and information about groups.  The
groups information is in two fields:
.INDENT 7.0
.TP
.B groups
contains information about each group
.TP
.B memberships
contains information about which users are members
of which groups
.UNINDENT

.TP
.B Raises
\fBAuthError\fP \-\- if the auth_params do not give access
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B login(username, password)
Login to the Account System
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBusername\fP \-\- username to send to FAS
.IP \(bu 2
\fBpassword\fP \-\- Password to verify the username with
.UNINDENT
.TP
.B Returns
a tuple of the session id FAS has associated with the user
and the user\(aqs account information.  This is similar to what is
returned by
\fBfedora.client.proxyclient.ProxyClient.get_user_info()\fP
.TP
.B Raises
\fBAuthError\fP \-\- if the username and password do not work
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B logout(session_id)
Logout of the Account System
.INDENT 7.0
.TP
.B Parameters
\fBsession_id\fP \-\- a FAS session_id to remove from FAS
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B person_by_id(person_id, auth_params)
Retrieve information about a particular person
.INDENT 7.0
.TP
.B Parameters
\fBauth_params\fP \-\- Auth information for a particular user.  For
instance, this can be a username/password pair or a session_id.
Refer to
\fBfedora.client.proxyclient.ProxyClient.send_request()\fP for all
the legal values for this.
.TP
.B Returns
a tuple of session_id and information about the user.
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fBAppError\fP \-\- if the server returns an exception
.IP \(bu 2
\fBAuthError\fP \-\- if the auth_params do not give access
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B refresh_session(session_id)
Try to refresh a session_id to prevent it from timing out
.INDENT 7.0
.TP
.B Parameters
\fBsession_id\fP \-\- FAS session_id to refresh
.TP
.B Returns
session_id that FAS has set now
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B verify_password(username, password)
Return whether the username and password pair are valid.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBusername\fP \-\- username to try authenticating
.IP \(bu 2
\fBpassword\fP \-\- password for the user
.UNINDENT
.TP
.B Returns
True if the username/password are valid.  False otherwise.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B verify_session(session_id)
Verify that a session is active.
.INDENT 7.0
.TP
.B Parameters
\fBsession_id\fP \-\- session_id to verify is currently associated with a
logged in user
.TP
.B Returns
True if the session_id is valid.  False otherwise.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Bodhi, the Update Server
.sp
Bodhi is used to push updates from the build system to the download
repositories.  It lets packagers send packages to the testing repository or to
the update repository.
.sp
pythyon\-fedora currently supports both the old Bodhi1 interface and the new
Bodhi2 interface.  By using \fBfedora.client.BodhiCLient\fP, the correct one
should be returned to you depending on what is running live on Fedora
Infrastructure servers.
.SH FEDORA SERVICES
.INDENT 0.0
.TP
.B Authors
Toshio Kuratomi
Luke Macken
.TP
.B Date
02 February 2009
.TP
.B For Version
0.3.x
.UNINDENT
.sp
In the loosest sense, a Fedora Service is a web application that sends data
that \fBBaseClient\fP is able to understand.  This document
defines things that a web application must currently do for
\fBBaseClient\fP to understand it.
.SS TurboGears and fedora.tg
.sp
All current Fedora Services are written in TurboGears\&.  Examples in
this document will be for that framework.  However, other frameworks can be
used to write a Service if they can correctly create the data that
\fBBaseClient\fP needs.
.sp
A Fedora Service differs from other web applications in that certain URLs for
the web application are an API layer that the Service can send and receive
JSON data from for \fBBaseClient\fP to interpret.
This imposes certain constraints on what data can be sent and what data can be
received from those URLs.  The \fBfedora.tg\fP module contains functions that
help you write code that communicated well with
\fBBaseClient\fP\&.
.sp
The TurboGears framework separates an application into model,
view, and controller layers.  The model is typically a
database and holds the raw data that the application needs.  The view formats
the data before output.  The controller makes decisions about what data to
retrieve from the model and which view to pass it onto.  The code that you\(aqll
most often need to use from \fBfedora.tg\fP operates on the controller
layer but there\(aqs also code that works on the model and view behind the scenes.
.SS Controllers
.sp
The controller is the code that processes an http request.  It
validates and processes requests and parameters sent by the user, gets data
from the model to satisfy the request, and then passes it onto a view layer to
be returned to the user.  \fBfedora.tg.utils\fP contains several helpful
functions for working with controllers.
.SS URLs as API
.sp
In TurboGears and most web frameworks, a URL is a kind of API for
accessing the data your web app provides.  This data can be made available in
multiple formats.  TurboGears allows you to use one URL to serve
multiple formats by specifying a query parameter or a special header.
.SS Selecting JSON Output
.sp
A URL in TurboGears can serve double duty by returning multiple
formats depending on how it is called.  In most cases, the URL will return
HTML or XHTML by default.  By adding the query parameter, \fBtg_format=json\fP
you can switch from returning the default format to returning JSON
data.  You need to add an \fB@expose(allow_json=True)\fP decorator [1] to your
controller method to tell TurboGears that this controller should
return JSON data:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@expose(allow_json=True)
@expose(template=\(aqmy.templates.amplifypage\(aq)
def amplify(self, data):
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBallow_json=True\fP is a shortcut for this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@expose("json", content_type="text/javascript",
        as_format="json", accept_format="text/javascript")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
That means that the controller method will use the \fBjson\fP template (uses
TurboJson to marshal the returned data to JSON) to return data of type
\fBtext/javascript\fP when either of these conditions is met:  a query param of
\fBtg_format=json\fP or an \fBAccept: text/javascript\fP header is sent.
.sp
\fBBaseClient\fP in python\-fedora 0.1.x and 0.2.x use the
query parameter method of selecting JSON output.
\fBBaseClient\fP 0.2.99.6 and 0.3.x use both the header
method and the query parameter since the argument was made that the header
method is friendlier to other web frameworks.  0.4 intends to use the header
alone.  If you use \fBallow_json=True\fP this change shouldn\(aqt matter.  If you
specify the \fB@expose("json")\fP decorator only \fBaccept_format\fP is set.  So
it is advisable to include both \fBas_format\fP and \fBaccept_format\fP in your
decorator.  Note that this is a limitation of TurboGears <= 1.0.4.4.
If your application is only going to run on TurboGears > 1.0.4.4 you
should be able to use a plain \fB@expose("json")\fP [2]\&.
.IP [1] 5
\fI\%http://docs.turbogears.org/1.0/ExposeDecorator#same\-method\-different\-template\fP
.IP [2] 5
\fI\%http://trac.turbogears.org/ticket/1459#comment:4\fP
.SS Why Two Formats from a Single URL?
.sp
When designing your URLs you might wonder why you\(aqd want to return
JSON and HTML from a single controller method instead of having two
separate controller methods.  For instance, separating the URLs into their own
namespaces might seem logical: \fB/app/json/get_user/USERNAME\fP as opposed to
\fB/app/user/USERNAME\fP\&.  Doing things with two URLs as opposed to one has both
benefits and drawbacks.
.SS Benefits of One Method Handling Multiple Formats
.INDENT 0.0
.IP \(bu 2
Usually less code as there\(aqs only one controller method
.IP \(bu 2
When a user sees a page that they want to get data from, they can get it as
JSON instead of screen scraping.
.IP \(bu 2
Forces the application designer to think more about the API that is being
provided to the users instead of just the needs of the web page they are
creating.
.IP \(bu 2
Makes it easier to see what data an application will need to implement an
alternate interface since you can simply look at the template code to see
what variables are being used on a particular page.
.UNINDENT
.SS Benefits of Multiple Methods for Each Format
.INDENT 0.0
.IP \(bu 2
Avoids special casing for error handlers (See below)
.IP \(bu 2
Separates URLs that you intend users to grab JSON data from URLs
where you only want to display HTML.
.IP \(bu 2
Allows the URLs that support JSON to concentrate on trimming the
size of the data sent while URLs that only return HTML can return whole
objects.
.IP \(bu 2
Organization can be better if you don\(aqt have to include all of the pages
that may only be useful for user interface elements.
.UNINDENT
.sp
Personal use has found that allowing JSON requests on one controller
method works well for cases where you want the user to get data and for
traditional form based user interaction.  AJAX requests have been better
served via dedicated methods.
.SS Return Values
.sp
The toplevel of the return values should be a dict.  This is the natural
return value for TurboGears applications.
.SS Marshaling
.sp
All data should be encoded in JSON before being returned.  This is
normally taken care of automatically by TurboGears and simplejson.  If
you are returning non\-builtin objects you may have to define an \fI\%__json__()\fP
method.
.SS Unicode
.sp
simplejson (and probably other JSON libraries) will take care of
encoding Unicode strings to JSON so be sure that you are passing
Unicode strings around rather than encoded byte strings.
.SS Error Handling
.sp
In python, error conditions are handled by raising an exception.  However,
an exception object will not propagate automatically through a return from
the server.  Instead we set several special variables in the returned data
to inform \fBBaseClient\fP of any errors.
.sp
At present, when \fBBaseClient\fP receives an error it raises an exception of its
own with the exception information from the server inside.  Raising the same
exception as the server is being investigated but may pose security risks so
hasn\(aqt yet been implemented.
.SS exc
.sp
All URLs which return JSON data should set the \fBexc\fP variable when
the method fails unexpectedly (a database call failed, a place where you would
normally raise an exception, or where you\(aqd redirect to an error page if a
user was viewing the HTML version of the web app).  \fBexc\fP should be set to
the name of an exception and \fI\%tg_flash\fP set to the message that would normally
be given to the exception\(aqs constructor.  If the return is a success (expected
values are being returned from the method or a value was updated successfully)
\fBexc\fP may either be unset or set to \fBNone\fP\&.
.SS tg_flash
.sp
When viewing the HTML web app, \fBtg_flash\fP can be set with a message to
display to the user either on the next page load or via an AJAX handler.
When used in conjunction with JSON, \fBexc=EXCEPTIONNAME\fP, and
\fBBaseClient\fP, \fBtg_flash\fP should be set to an error
message that the client can use to identify what went wrong or display to the
user.  It\(aqs equivalent to the message you would normally give when raising an
exception.
.SS Authentication Errors
.sp
Errors in authentication are a special case.  Instead of returning an error
with \fBexc=\(aqAuthError\(aq\fP set, the server should return with \fBresponse.status =
403\fP\&.  \fBBaseClient\fP will see the 403 and raise an
\fIAuthError\fP\&.
.sp
This is the signal for the client to ask the user for new credentials (usually
a new username and password).
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Upstream TurboGears has switched to sending a 401 for
authentication problems.  However, their use of 401 is against the http
specification (It doesn\(aqt set the \(aqWWW\-Authentication\(aq header) and it
causes problems for konqueror and webkit based browsers so we probably
will not be switching.
.UNINDENT
.UNINDENT
.SS Performing Different Actions when Returning JSON
.sp
So far we\(aqve run across three features of TurboGears that provide
value to a web application but don\(aqt work when returning JSON data.
We provide a function that can code around this.
\fBfedora.tg.utils.request_format()\fP will return the format that the page
is being returned as.  Code can use this to check whether JSON output
is expected and do something different based on it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
output = {\(aqtg_flash\(aq: \(aqAn Error Occurred\(aq}
if fedora.tg.utils.request_format() == \(aqjson\(aq:
    output[\(aqexc\(aq] = \(aqServerError\(aq
else:
    output[\(aqtg_template\(aq] = \(aqmy.templates.error\(aq
return output
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example, we return an error through our "exception" mechanism if we
are returning JSON and return an error page by resetting the template
if not.
.SS Redirects
.sp
Redirects do not play well with JSON [3] because TurboGears
is unable to turn the function returned from the redirect into a dictionary
that can be turned into JSON\&.
.sp
Redirects are commonly used to express errors.  This is actually better
expressed using \fI\%tg_template\fP because that method leaves the URL intact.
That allows the end user to look for spelling mistakes in their URL.  If you
need to use a redirect, the same recipe as above will allow you to split your
code paths.
.IP [3] 5
Last checked in TurboGears 1.0.4
.SS tg_template
.sp
Setting what template is returned to a user by setting tg_template in the
return dict (for instance, to display an error page without changing the URL)
is a perfectly valid way to use TurboGears\&.  Unfortunately, since
JSON is simply another template in TurboGears you have to be
sure not to interfere with the generation of JSON data.  You need to
check whether JSON was requested using
\fBfedora.tg.utils.request_format()\fP and only return a different template
if that\(aqs not the case.  The recipe above shows how to do this.
.SS Validators
.sp
Validators are slightly different than the issues we\(aqve encountered so far.
Validators are used to check and convert parameters sent to a controller
method so that only good data is dealt with in the controller method itself.
The problem is that when a validator detects a parameter that is invalid, it
performs a special internal redirect to a method that is its \fBerror_handler\fP\&.
We can\(aqt intercept this redirect because it happens in the decorators before
our method is invoked.  So we have to deal with the aftermath of the redirect
in the \fBerror_handler\fP method:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
class NotNumberValidator(turbogears.validators.FancyValidator):
    messages = {\(aqNumber\(aq: \(aqNumbers are not allowed\(aq}

    def to_python(self, value, state=None):
        try:
            number = turbogears.validators.Number(value.strip())
        except:
            return value
        raise validators.Invalid(self.message(\(aqNumber\(aq, state), value,
                state)

class AmplifyForm(turbogears.widgets.Form):
    template = my.templates.amplifyform
    submit_text = \(aqEnter word to amplify\(aq
    fields = [
            turbogears.widgets.TextField(name=\(aqdata\(aq,
                    validator=NotNumberValidator())
            ]

amplify_form = AmplifyForm()

class mycontroller(RootController):

    @expose(template=\(aqmy.templates.errorpage\(aq, allow_json=True)
    def no_numbers(self, data):
        errors = fedora.tg.utils.jsonify_validation_errors()
        if errors:
            return errors
        # Construct a dict to return the data error message as HTML via
        # the errorpage template
        pass

    @validate(form=amplify_form)
    @error_handler(\(aqno_numbers\(aq)
    @expose(template=\(aqmy.templates.amplifypage\(aq, allow_json=True)
    def amplify(self, data):
        return dict(data=data.upper())
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When a user hits \fBamplify()\fP\(aqs URL, the validator checks whether \fBdata\fP is
a number.  If it is, it redirects to the error_handler, \fBno_numbers()\fP\&.
\fBno_numbers()\fP will normally return HTML which is fine if we\(aqre simply
hitting \fBamplify()\fP from a web browser.  If we\(aqre hitting it from a
\fBBaseClient\fP app, however, we need it to return
JSON data instead.  To do that we use \fBjsonify_validation_errors()\fP
which checks whether there was a validation error and whether we need to
return JSON data.  If both of those are true, it returns a dictionary
with the validation errors.  This dictionary is appropriate for returning from
the controller method in response to a JSON request.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
When defining @error_handler() order of decorators can be important.  The
short story is to always make @validate() and @error_handler() the first
decorators of your method.  The longer version is that this is known to
cause errors with the json request not being honored or skipping identity
checks when the method is its own error handler.
.UNINDENT
.UNINDENT
.SS Expected Methods
.sp
Certain controller methods are necessary in order for
\fBBaseClient\fP to properly talk to your service.
TurboGears can quickstart an application template for you that sets
most of these variables correctly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ tg\-admin quickstart \-i \-s \-p my my
# edit my/my/controllers.py
.ft P
.fi
.UNINDENT
.UNINDENT
.SS login()
.sp
You need to have a \fBlogin()\fP method in your application\(aqs root.  This method
allows \fBBaseClient\fP to authenticate against your Service:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
     @expose(template="my.templates.login")
+    @expose(allow_json=True)
     def login(self, forward_url=None, previous_url=None, \e*args, \e**kw):

         if not identity.current.anonymous \e
             and identity.was_login_attempted() \e
             and not identity.get_identity_errors():
+            # User is logged in
+            if \(aqjson\(aq == fedora.tg.utils.request_format():
+                return dict(user=identity.current.user)
+            if not forward_url:
+                forward_url = turbogears.url(\(aq/\(aq)
             raise redirect(forward_url)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS For non\-TurboGears Implementors
.sp
If you are implementing a server in a non\-TurboGears framework, note that one
of the ways to reach the \fBlogin()\fP method is through special parameters
parsed by the TurboGears framework.
\fBBaseClient\fP uses these parameters instead of invoking
the \fBlogin()\fP method directly as it saves a round trip when authenticating
to the server.  It will be necessary for you to implement handling of these
parameters (passed via \fBPOST\fP) on your application as well.
.sp
The parameters are: \fBuser_name\fP, \fBpassword\fP, and \fBlogin\fP\&.  When these
three parameters are sent to the server, the server authenticates the user
and records their information before deciding what information to return to
them from the URL.
.SS logout()
.sp
The \fBlogout()\fP method is similar to \fBlogin()\fP\&.  It also needs to be
modified to allow people to connect to it via JSON:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-    @expose()
+    @expose(allow_json=True)
     def logout(self):
         identity.current.logout()
+        if \(aqjson\(aq in fedora.tg.utils.request_format():
+            return dict()
         raise redirect("/")
.ft P
.fi
.UNINDENT
.UNINDENT
.SS CSRF Protection
.sp
For an overview of CSRF and how to protect TurboGears 1 based
services, look at this document.
.SS Using SABase
.sp
\fBfedora.tg.json\fP contains several functions that help to convert \fI\%SQLAlchemy\fP
objects into JSON\&.  For the most part, these do their work behind the
scenes.  The \fBSABase\fP object, however, is one that you might need to take an
active role in using.
.sp
When you return an \fI\%SQLAlchemy\fP object in a controller to a template, the
template is able to access any of the relations mapped to it.  So, instead of
having to construct a list of people records from a table and
the the list of groups that each of them are in you can pass in the list of
people and let your template reference the relation properties to get the
groups.  This is extremely convenient for templates but has a negative effect
when returning JSON\&. Namely, the default methods for marshaling
\fI\%SQLAlchemy\fP objects to JSON only return the attributes of the object,
not the relations that are linked to it.  So you can easily run into a
situation where someone querying the JSON data for a page will not
have all the information that a template has access to.
.sp
SABase fixes this by allowing you to specify relations that your
\fI\%SQLAlchemy\fP backed objects should marshal as JSON data.
.sp
Further information on SABase can be found in the API documentation:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pydoc fedora.tg.json
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Example
.sp
SABase is a base class that you can use when defining objects
in your project\(aqs model.  So the first step is defining the classes in your
model to inherit from SABase:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from fedora.tg.json import SABase
from sqlalchemy import Table, Column, Integer, String, MetaData, ForeignKey
from turbogears.database import metadata, mapper

class Person(SABase):
    pass
PersonTable = Table(\(aqperson\(aq, metadata
    Column(\(aqname\(aq, String, primary_key=True),
    )

class Address(SABase):
    pass
AddressTable = Table (
    Column(\(aqid\(aq, Integer, primary_key=True),
    Column(\(aqstreet\(aq, string),
    Column(\(aqperson_id\(aq, Integer, ForeignKey(\(aqperson.name\(aq)
    )

mapper(PersonTable, Person)
mapper(AddressTable, Address, properties = {
    person: relation(Person, backref = \(aqaddresses\(aq),
})
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The next step is to tell SABase which properties should be copied (this
allows you to omit large trees of objects when you only need the data from
a few of them):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@expose(\(aqmy.templates.about_me\(aq)
@expose(allow_json=True)
def my_info(self):
    person = Person.query.filter_by(name=\(aqMyself\(aq).one()
    person.jsonProps = {\(aqPerson\(aq: [\(aqaddresses\(aq]}
    return dict(myself=person}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now, when someone requests JSON data from my_info, they should get
back a record for person that includes a property addresses.  Addresses will
be a list of address records associated with the person.
.SS How it Works
.sp
SABase adds a special \fI\%__json__()\fP method to the class.  By default, this
method returns a dict with all of the attributes that are backed by fields in
the database.
.sp
Adding entries to jsonProps adds the values for those properties to the
returned dict as well.  If you need to override the \fI\%__json__()\fP method in
your class you probably want to call SABase\(aqs \fI\%__json__()\fP unless you know
that neither you nor any future subclasses will need it.
.SS Using __json__()
.sp
Sometimes you need to return an object that isn\(aqt a basic python type (list,
tuple, dict, number. string, etc).  When that occurs, \fI\%simplejson\fP won\(aqt know
how to marshal the data into JSON until you write own method to
transform the values.  If this method is named __json__(), TurboGears
will automatically perform the conversion when you return the object.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
class MyObject(object):
    def _init__(self, number):
        self.someNumber = number
        self.cached = None

    def _calc_data(self):
        if not self.cached:
            self.cached = self.someNumber * 2
        return self.cached

    twiceData = property(_calc_data)

    def __json__(self):
        return {\(aqsomeNumber\(aq: self.someNumber, \(aqtwiceData\(aq: self.twiceData}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this class, you have a variable and a property.  If you were to return it
from a controller method without defining the __json__() method,
TurboGears would give you an error that it was unable to adapt the
object to JSON\&.  The JSON method transforms the object into a
dict with sensibly named values for the variable and property so that
simplejson is able to marshal the data to JSON\&.  Note that you will
often have to choose between space (more data takes more bandwidth to deliver
to the end user) and completeness (you need to return enough data so the
client isn\(aqt looking for another method that can complete its needs) when
returning data.
.SH AUTHENTICATION TO FAS
.sp
The Fedora\-Account\-System has a JSON interface that we make use
of to authenticate users in our web apps.  Currently, there are two modes of
operation.  Some web apps have single sign\-on capability with
FAS\&.  These are the TurboGears applications that use the
\fBjsonfasprovider\fP\&.  Other apps do not have
single sign\-on but they do connect to FAS to verify the
username and password so changing the password in FAS changes it
everywhere.
.SS TurboGears Identity Provider 2
.sp
An identity provider with CSRF protection.
.sp
This will install as a TurboGears identity plugin.  To use it, set the
following in your \fBAPPNAME/config/app.cfg\fP file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
identity.provider=\(aqjsonfas2\(aq
visit.manager=\(aqjsonfas2\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
CSRF\-Protection
.UNINDENT
.UNINDENT
.SS Turbogears Identity Provider 1
.sp
These methods are \fBdeprecated\fP because they do not provide the CSRF
protection of \fI\%TurboGears Identity Provider 2\fP\&.  Please use that identity provider instead.
.SS Django Authentication Backend
.SS Flask Auth Plugin
.SS Flask FAS OpenId Auth Plugin
.sp
The flask_openid provider is an alternative to the flask_fas auth plugin.  It
leverages our FAS\-OpenID server to do authn and authz (group memberships).
Note that not every feature is available with a generic OpenID provider \-\- the
plugin depends on the OpenID provider having certain extensions in order to
provide more than basic OpenID auth.
.INDENT 0.0
.IP \(bu 2
Any compliant OpenID server should allow you to use the basic authn features of OpenID
OpenID authentication core: \fI\%http://openid.net/specs/openid\-authentication\-2_0.html\fP
.IP \(bu 2
Retrieving simple information about the user such as username, human name, email
is done with sreg: \fI\%http://openid.net/specs/openid\-simple\-registration\-extension\-1_0.html\fP
which is an extension supported by many providers.
.IP \(bu 2
Advanced security features such as requiring a user to re\-login to the OpenID
provider or specifying that the user login with a hardware token requires
the PAPE extension:
\fI\%http://openid.net/specs/openid\-provider\-authentication\-policy\-extension\-1_0.html\fP
.IP \(bu 2
To get groups information, the provider must implement the
\fI\%https://dev.launchpad.net/OpenIDTeams\fP extension.
.INDENT 2.0
.IP \(bu 2
We have extended the teams extension so you can request a team name of
\fB_FAS_ALL_GROUPS_\fP to retrieve all the groups that a user belongs to.
Without this addition to the teams extension you will need to manually
configure which groups you are interested in knowing about.  See the
documentation for how to do so.
.UNINDENT
.IP \(bu 2
Retrieving information about whether a user has signed a CLA (For Fedora,
this is the Fedora Project Contributor Agreement).
\fI\%http://fedoraproject.org/specs/open_id/cla\fP
.UNINDENT
.sp
If the provider you use does not support one of these extensions, the plugin
should still work but naturally, it will return empty values for the
information that the extension would have provided.
.SS FAS Flask OpenID Auth Plugin
.INDENT 0.0
.TP
.B Authors
Patrick Uiterwjk
.TP
.B Date
18 February 2013
.TP
.B For Version
0.3.x
.UNINDENT
.sp
The Fedora\-Account\-System has a OpenID provider that applications
can use to authenticate users in web apps. For our Flask applications
we have an identity provider that uses this OpenID service to authenticate users.
It is almost completely compatible with flask_fas except that it does not
use the username/password provided by the client application (it is silently
ignored). It can be configured to use any OpenID authentication service that
implements the OpenID Teams Extension, Simple Registration Extension and
CLA Extension.
.SS Configuration
.sp
The FAS OpenID auth plugin has several config values that can be used to control
how the auth plugin functions.  You can set these in your application\(aqs config
file.
.INDENT 0.0
.TP
.B FAS_OPENID_ENDPOINT
Set this to the OpenID endpoint url you are authenticating against.
Default is "\fI\%http://id.fedoraproject.org/\fP"
.TP
.B FAS_CHECK_CERT
When set, this will check the SSL Certificate for the FAS server to make
sure that it is who it claims to be.  This is useful to set to False when
testing against a local FAS server but should always be set to True in
production.  Default: True
.UNINDENT
.SS Sample Application
.sp
The following is a sample, minimal flask application that uses fas_flask for
authentication:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!/usr/bin/python \-tt
# Flask\-FAS\-OpenID \- A Flask extension for authorizing users with OpenID
# Primary maintainer: Patrick Uiterwijk <puiterwijk@fedoraproject.org>
#
# Copyright (c) 2012\-2013, Red Hat, Inc., Patrick Uiterwijk
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice, this
# list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
# * Neither the name of the Red Hat, Inc. nor the names of its contributors may
# be used to endorse or promote products derived from this software without
# specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS \(aq\(aqAS IS\(aq\(aq AND ANY
# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY
# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

# This is a sample application.

import flask
from flask_fas_openid import fas_login_required, cla_plus_one_required, FAS

# Set up Flask application
app = flask.Flask(__name__)
# Set up FAS extension
fas = FAS(app)

# Application configuration
# SECRET_KEY is necessary for the Flask session system.  It needs to be secret to
# make the sessions secret but if you have multiple servers behind
# a load balancer, the key needs to be the same on each.
app.config[\(aqSECRET_KEY\(aq] = \(aqchange me!\(aq
# Other configuration options for Flask\-FAS\-OpenID:
#     FAS_OPENID_ENDPOINT: the OpenID endpoint URL
#         (default http://id.fedoraproject.org/)
#     FAS_CHECK_CERT: check the SSL certificate of FAS (default True)
# You should use these options\(aq defaults for production applications!
app.config[\(aqFAS_OPENID_ENDPOINT\(aq] = \(aqhttp://id.fedoraproject.org/\(aq
app.config[\(aqFAS_CHECK_CERT\(aq] = True


# Inline templates keep this test application all in one file. Don\(aqt do this in
# a real application. Please.
TEMPLATE_START = """
<h1>Flask\-FAS\-OpenID test app</h1>
{% if g.fas_user %}
    <p>Hello, {{ g.fas_user.username }} &mdash;
    <a href="{{ url_for("logout") }}">Log out</a>
{% else %}
    <p>You are not logged in &mdash;
    <a href="{{ url_for("auth_login", next=request.url) + \(aq\(aq }}">Log in</a>
{% endif %}
&mdash; <a href="{{ url_for("index") }}">Main page</a></p>
"""


@app.route(\(aq/\(aq)
def index():
    data = TEMPLATE_START
    data += \(aq<p><a href="%s">Check if you are cla+1</a></p>\(aq % \e
            flask.url_for(\(aqclaplusone\(aq)
    data += \(aq<p><a href="%s">See a secret message (requires login)</a></p>\(aq % \e
            flask.url_for(\(aqsecret\(aq)
    return flask.render_template_string(data)


@app.route(\(aq/login\(aq, methods=[\(aqGET\(aq, \(aqPOST\(aq])
def auth_login():
    # Your application should probably do some checking to make sure the URL
    # given in the next request argument is sane. (For example, having next set
    # to the login page will cause a redirect loop.) Some more information:
    # http://flask.pocoo.org/snippets/62/
    if \(aqnext\(aq in flask.request.args:
        next_url = flask.request.args[\(aqnext\(aq]
    else:
        next_url = flask.url_for(\(aqindex\(aq)
    # If user is already logged in, return them to where they were last
    if flask.g.fas_user:
        return flask.redirect(next_url)
    return fas.login(return_url=next_url)

@app.route(\(aq/logout\(aq)
def logout():
    if flask.g.fas_user:
        fas.logout()
    return flask.redirect(flask.url_for(\(aqindex\(aq))

# This demonstrates the use of the fas_login_required decorator. The
# secret message can only be viewed by those who are logged in.
@app.route(\(aq/secret\(aq)
@fas_login_required
def secret():
    data = TEMPLATE_START + \(aq<p>Be sure to drink your Ovaltine</p>\(aq
    return flask.render_template_string(data)


# This demonstrates checking for group membership inside of a function.
# The flask_fas adapter also provides a cla_plus_one_required decorator that
# can restrict a url so that you can only access it from an account that has
# cla +1.
@app.route(\(aq/claplusone\(aq)
@cla_plus_one_required
def claplusone():
    data = TEMPLATE_START
    data += \(aq<p>Your account is cla+1.</p>\(aq
    return flask.render_template_string(data)


if __name__ == \(aq__main__\(aq:
    app.run(debug=True)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FAS Who Plugin for TurboGears2
.SS FASWho Plugin
.INDENT 0.0
.TP
.B Authors
Luke Macken
Toshio Kuratomi
.TP
.B Date
3 September 2011
.UNINDENT
.sp
This plugin provides authentication to the Fedora Account System using the
\fIrepoze.who\fP WSGI middleware.  It is designed for use with TurboGears2
but it may be used with any \fIrepoze.who\fP using application.  Like
jsonfas2, faswho has builtin CSRF protection.  This protection
is implemented as a second piece of middleware and may be used with other
\fIrepoze.who\fP authentication schemes.
.SS Authenticating against FAS with TurboGears2
.sp
Setting up authentication against FAS in TurboGears2 is very easy.  It
requires one change to be made to \fBapp/config/app_cfg.py\fP\&.  This change
will take care of registering faswho as the authentication provider, enabling
CSRF protection, switching \fBtg.url()\fP to use
\fBfedora.ta2g.utils.url()\fP instead, and allowing the \fI_csrf_token\fP
parameter to be given to any URL.
.SS Using CSRF middleware with other Auth Methods
.sp
This section needs to be made clearer so that apps like mirrormanager can be
ported to use this.
.SS Templates
.sp
The \fBfedora.tg2.utils\fP module contains some templates to help you
write CSRF aware login forms and buttons.  You can use the
\fBfedora_template()\fP function to integrate them into your
templates:
.sp
The templates themselves come in two flavors.  One set for use with mako and
one set for use with genshi.
.SS Mako
.SS Genshi
.SH JAVASCRIPT
.INDENT 0.0
.TP
.B Authors
Toshio Kuratomi
.TP
.B Date
26 February 2009
.TP
.B For Version
0.3.x
.UNINDENT
.sp
python\-fedora currently provides some JavaScript files to make coding
Fedora\-Services easier.  In the future we may move these to their own
package.
.SS \fI\%fedora.dojo\fP
.sp
\fIModule author: Toshio Kuratomi <\fI\%tkuratom@redhat.com\fP>\fP
.sp
New in version 0.3.10.

.sp
Dojo is one of several JavaScript Toolkits.  It aims to be a standard
library for JavaScript.  The \fI\%fedora.dojo\fP module has JavaScript code
that make use of Dojo to do their work.  It is most appropriate to use
when the Dojo libraries are being used as the JavaScript library for
the app.  However, it is well namespaced and nothing should prevent it from
being used in other apps as well.
.SH API DOCUMENTATION
.sp
This API Documentation is currently a catch\-all.  We\(aqre going to merge the API
docs into the hand created docs as we have time to integrate them.
.SS Client
.sp
fedora.client is used to interact with Fedora Services.
.sp
Changed in version 0.3.21: Deprecate DictContainer in favor of bunch.Bunch

.sp
Changed in version 0.3.35: Add the openid clients

.sp
\fIModule author: Ricky Zhou <\fI\%ricky@fedoraproject.org\fP>\fP
.sp
\fIModule author: Luke Macken <\fI\%lmacken@redhat.com\fP>\fP
.sp
\fIModule author: Toshio Kuratomi <\fI\%tkuratom@redhat.com\fP>\fP
.INDENT 0.0
.TP
.B exception fedora.client.AppError(name, message, extras=None)
Error condition that the server is passing back to the client.
.UNINDENT
.INDENT 0.0
.TP
.B exception fedora.client.AuthError
Error during authentication.  For instance, invalid password.
.UNINDENT
.INDENT 0.0
.TP
.B exception fedora.client.CLAError
CLA Error
.UNINDENT
.INDENT 0.0
.TP
.B class fedora.client.DictContainer(*args, **kwargs)
.UNINDENT
.INDENT 0.0
.TP
.B exception fedora.client.FASError
FAS Error
.UNINDENT
.INDENT 0.0
.TP
.B exception fedora.client.FedoraClientError
Base Exception for problems which originate within the Clients.
.sp
This should be the base class for any exceptions that the Client
generates.  For instance, if the client performs validation before passing
the data on to the Fedora Service.
.sp
Problems returned while talking to the Services should be returned via a
\fIFedoraServiceError\fP instead.
.UNINDENT
.INDENT 0.0
.TP
.B exception fedora.client.FedoraServiceError
Base Exception for any problem talking with the Service.
.sp
When the Client gets an error talking to the server, an exception of this
type is raised.  This can be anything in the networking layer up to an
error returned from the server itself.
.UNINDENT
.INDENT 0.0
.TP
.B exception fedora.client.ServerError(url, status, msg)
Unable to talk to the server properly.
.sp
This includes network errors and 500 response codes.  If the error was
generated from an http response, \fBcode\fP is the HTTP response code.
Otherwise, \fBcode\fP will be \-1.
.UNINDENT
.SS Generic Clients
.SS BaseClient
.INDENT 0.0
.TP
.B class fedora.client.BaseClient(base_url, useragent=None, debug=False, insecure=False, username=None, password=None, httpauth=None, session_cookie=None, session_id=None, session_name=\(aqtg\-visit\(aq, cache_session=True, retries=None, timeout=None)
A client for interacting with web services.
.INDENT 7.0
.TP
.B logout()
Logout from the server.
.UNINDENT
.INDENT 7.0
.TP
.B send_request(method, req_params=None, file_params=None, auth=False, retries=None, timeout=None, **kwargs)
Make an HTTP request to a server method.
.sp
The given method is called with any parameters set in req_params.  If
auth is True, then the request is made with an authenticated session
cookie.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBmethod\fP \-\- Method to call on the server.  It\(aqs a url fragment that
comes after the base_url set in __init__().
.IP \(bu 2
\fBreq_params\fP \-\- Extra parameters to send to the server.
.IP \(bu 2
\fBfile_params\fP \-\- dict of files where the key is the name of the
file field used in the remote method and the value is the local
path of the file to be uploaded.  If you want to pass multiple
files to a single file field, pass the paths as a list of paths.
.IP \(bu 2
\fBauth\fP \-\- If True perform auth to the server, else do not.
.IP \(bu 2
\fBretries\fP \-\- if we get an unknown or possibly transient error from
the server, retry this many times.  Setting this to a negative
number makes it try forever.  Default to use the \fBretries\fP
value set on the instance or in \fB__init__()\fP (which defaults
to zero, no retries).
.IP \(bu 2
\fBtimeout\fP \-\- A float describing the timeout of the connection. The
timeout only affects the connection process itself, not the
downloading of the response body. Default to use the
\fBtimeout\fP value set on the instance or in \fB__init__()\fP
(which defaults to 120s).
.UNINDENT
.TP
.B Return type
Bunch
.TP
.B Returns
The data from the server
.UNINDENT
.sp
Changed in version 0.3.21: * Return data as a Bunch instead of a DictContainer
* Add file_params to allow uploading files

.sp
Changed in version 0.3.33: * Added the timeout kwarg

.UNINDENT
.INDENT 7.0
.TP
.B property session_cookie
\fIDeprecated\fP, use session_id instead.
.sp
The session cookie is saved in a file in case it is needed in
consecutive runs of BaseClient.
.UNINDENT
.INDENT 7.0
.TP
.B property session_id
The session_id.
.sp
The session id is saved in a file in case it is needed in consecutive
runs of BaseClient.
.UNINDENT
.UNINDENT
.SS ProxyClient
.INDENT 0.0
.TP
.B class fedora.client.ProxyClient(base_url, useragent=None, session_name=\(aqtg\-visit\(aq, session_as_cookie=True, debug=False, insecure=False, retries=None, timeout=None)
A client to a Fedora Service.  This class is optimized to proxy multiple
users to a service.  ProxyClient is designed to be threadsafe so that
code can instantiate one instance of the class and use it for multiple
requests for different users from different threads.
.sp
If you want something that can manage one user\(aqs connection to a Fedora
Service, then look into using BaseClient instead.
.sp
This class has several attributes.  These may be changed after
instantiation however, please note that this class is intended to be
threadsafe.  Changing these values when another thread may affect more
than just the thread that you are making the change in.  (For instance,
changing the debug option could cause other threads to start logging debug
messages in the middle of a method.)
.INDENT 7.0
.TP
.B base_url
Initial portion of the url to contact the server.  It is highly
recommended not to change this value unless you know that no other
threads are accessing this \fI\%ProxyClient\fP instance.
.UNINDENT
.INDENT 7.0
.TP
.B useragent
Changes the useragent string that is reported to the web server.
.UNINDENT
.INDENT 7.0
.TP
.B session_name
Name of the cookie that holds the authentication value.
.UNINDENT
.INDENT 7.0
.TP
.B session_as_cookie
If \fBTrue\fP, then the session information is saved locally as
a cookie.  This is here for backwards compatibility.  New code should
set this to \fBFalse\fP when constructing the \fI\%ProxyClient\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B debug
If \fBTrue\fP, then more verbose logging is performed to aid in
debugging issues.
.UNINDENT
.INDENT 7.0
.TP
.B insecure
If \fBTrue\fP then the connection to the server is not checked to be
sure that any SSL certificate information is valid.  That means that
a remote host can lie about who it is.  Useful for development but
should not be used in production code.
.UNINDENT
.INDENT 7.0
.TP
.B retries
Setting this to a positive integer will retry failed requests to the
web server this many times.  Setting to a negative integer will retry
forever.
.UNINDENT
.INDENT 7.0
.TP
.B timeout
A float describing the timeout of the connection. The timeout only
affects the connection process itself, not the downloading of the
response body. Defaults to 120 seconds.
.UNINDENT
.sp
Changed in version 0.3.33: Added the timeout attribute

.INDENT 7.0
.TP
.B property debug
When True, we log extra debugging statements.  When False, we only log
errors.
.UNINDENT
.INDENT 7.0
.TP
.B log = <Logger fedora.client.proxyclient (WARNING)>
.UNINDENT
.INDENT 7.0
.TP
.B send_request(method, req_params=None, auth_params=None, file_params=None, retries=None, timeout=None)
Make an HTTP request to a server method.
.sp
The given method is called with any parameters set in \fBreq_params\fP\&.
If auth is True, then the request is made with an authenticated session
cookie.  Note that path parameters should be set by adding onto the
method, not via \fBreq_params\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBmethod\fP \-\- Method to call on the server.  It\(aqs a url fragment that
comes after the base_url set in __init__().  Note that any
parameters set as extra path information should be listed here,
not in \fBreq_params\fP\&.
.IP \(bu 2
\fBreq_params\fP \-\- dict containing extra parameters to send to the
server
.IP \(bu 2
\fBauth_params\fP \-\- 
.sp
dict containing one or more means of authenticating
to the server.  Valid entries in this dict are:
.INDENT 2.0
.TP
.B cookie
\fBDeprecated\fP Use \fBsession_id\fP instead.  If both
\fBcookie\fP and \fBsession_id\fP are set, only \fBsession_id\fP will
be used.  A \fBCookie.SimpleCookie\fP to send as a session cookie
to the server
.TP
.B session_id
Session id to put in a cookie to construct an identity
for the server
.TP
.B username
Username to send to the server
.TP
.B password
Password to use with username to send to the server
.TP
.B httpauth
If set to \fBbasic\fP then use HTTP Basic Authentication
to send the username and password to the server.  This may be
extended in the future to support other httpauth types than
\fBbasic\fP\&.
.UNINDENT
.sp
Note that cookie can be sent alone but if one of username or
password is set the other must as well.  Code can set all of these
if it wants and all of them will be sent to the server.  Be careful
of sending cookies that do not match with the username in this
case as the server can decide what to do in this case.

.IP \(bu 2
\fBfile_params\fP \-\- dict of files where the key is the name of the
file field used in the remote method and the value is the local
path of the file to be uploaded.  If you want to pass multiple
files to a single file field, pass the paths as a list of paths.
.IP \(bu 2
\fBretries\fP \-\- if we get an unknown or possibly transient error from
the server, retry this many times.  Setting this to a negative
number makes it try forever.  Default to use the \fI\%retries\fP
value set on the instance or in \fB__init__()\fP\&.
.IP \(bu 2
\fBtimeout\fP \-\- A float describing the timeout of the connection. The
timeout only affects the connection process itself, not the
downloading of the response body. Defaults to the \fI\%timeout\fP
value set on the instance or in \fB__init__()\fP\&.
.UNINDENT
.TP
.B Returns
If ProxyClient is created with session_as_cookie=True (the
default), a tuple of session cookie and data from the server.
If ProxyClient was created with session_as_cookie=False, a tuple
of session_id and data instead.
.TP
.B Return type
tuple of session information and data from server
.UNINDENT
.sp
Changed in version 0.3.17: No longer send tg_format=json parameter.  We rely solely on the
Accept: application/json header now.

.sp
Changed in version 0.3.21: * Return data as a Bunch instead of a DictContainer
* Add file_params to allow uploading files

.sp
Changed in version 0.3.33: Added the timeout kwarg

.UNINDENT
.UNINDENT
.SS OpenIdBaseClient
.INDENT 0.0
.TP
.B class fedora.client.OpenIdBaseClient(base_url, login_url=None, useragent=None, debug=False, insecure=False, openid_insecure=False, username=None, cache_session=True, retries=None, timeout=None, retry_backoff_factor=0)
A client for interacting with web services relying on openid auth.
.INDENT 7.0
.TP
.B has_cookies()
.UNINDENT
.INDENT 7.0
.TP
.B login(username, password, otp=None)
Open a session for the user.
.sp
Log in the user with the specified username and password
against the FAS OpenID server.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBusername\fP \-\- the FAS username of the user that wants to log in
.IP \(bu 2
\fBpassword\fP \-\- the FAS password of the user that wants to log in
.IP \(bu 2
\fBotp\fP \-\- currently unused.  Eventually a way to send an otp to the
API that the API can use.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B send_request(method, auth=False, verb=\(aqPOST\(aq, **kwargs)
Make an HTTP request to a server method.
.sp
The given method is called with any parameters set in req_params.  If
auth is True, then the request is made with an authenticated session
cookie.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBmethod\fP \-\- Method to call on the server.  It\(aqs a url fragment that
comes after the \fBbase_url\fP set in \fB__init__()\fP\&.
.IP \(bu 2
\fBauth\fP \-\- If True perform auth to the server, else do not.
.IP \(bu 2
\fBreq_params\fP \-\- Extra parameters to send to the server.
.IP \(bu 2
\fBfile_params\fP \-\- dict of files where the key is the name of the
file field used in the remote method and the value is the local
path of the file to be uploaded.  If you want to pass multiple
files to a single file field, pass the paths as a list of paths.
.IP \(bu 2
\fBverb\fP \-\- HTTP verb to use.  GET and POST are currently supported.
POST is the default.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B property session_key
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B fedora.client.openidbaseclient.requires_login(func)
Decorator function for get or post requests requiring login.
.sp
Decorate a controller method that requires the user to be authenticated.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
from fedora.client.openidbaseclient import requires_login

@requires_login
def rename_user(new_name):
    user = new_name
    # [...]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS OpenIdProxyClient
.INDENT 0.0
.TP
.B class fedora.client.OpenIdProxyClient(base_url, login_url=None, useragent=None, session_name=\(aqsession\(aq, debug=False, insecure=False, openid_insecure=False, retries=None, timeout=None)
A client to a Fedora Service.  This class is optimized to proxy multiple
users to a service.  OpenIdProxyClient is designed to be usable by code
that creates a single instance of this class and uses it in multiple
threads. However it is not completely threadsafe.  See the information
on setting attributes below.
.sp
If you want something that can manage one user\(aqs connection to a Fedora
Service, then look into using \fI\%OpenIdBaseClient\fP
instead.
.sp
This class has several attributes.  These may be changed after
instantiation.  Please note, however, that changing these values when
another thread is utilizing the same instance may affect more than just
the thread that you are making the change in.  (For instance, changing
the debug option could cause other threads to start logging debug
messages in the middle of a method.)
.INDENT 7.0
.TP
.B base_url
Initial portion of the url to contact the server.  It is highly
recommended not to change this value unless you know that no other
threads are accessing this \fI\%OpenIdProxyClient\fP instance.
.UNINDENT
.INDENT 7.0
.TP
.B useragent
Changes the useragent string that is reported to the web server.
.UNINDENT
.INDENT 7.0
.TP
.B session_name
Name of the cookie that holds the authentication value.
.UNINDENT
.INDENT 7.0
.TP
.B debug
If \fBTrue\fP, then more verbose logging is performed to aid in
debugging issues.
.UNINDENT
.INDENT 7.0
.TP
.B insecure
If \fBTrue\fP then the connection to the server is not checked to be
sure that any SSL certificate information is valid.  That means that
a remote host can lie about who it is.  Useful for development but
should not be used in production code.
.UNINDENT
.INDENT 7.0
.TP
.B retries
Setting this to a positive integer will retry failed requests to the
web server this many times.  Setting to a negative integer will retry
forever.
.UNINDENT
.INDENT 7.0
.TP
.B timeout
A float describing the timeout of the connection. The timeout only
affects the connection process itself, not the downloading of the
response body. Defaults to 120 seconds.
.UNINDENT
.INDENT 7.0
.TP
.B property debug
When True, we log extra debugging statements.  When False, we only log
errors.
.UNINDENT
.INDENT 7.0
.TP
.B login(username, password, otp=None)
Open a session for the user.
.sp
Log in the user with the specified username and password
against the FAS OpenID server.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBusername\fP \-\- the FAS username of the user that wants to log in
.IP \(bu 2
\fBpassword\fP \-\- the FAS password of the user that wants to log in
.IP \(bu 2
\fBotp\fP \-\- currently unused.  Eventually a way to send an otp to the
API that the API can use.
.UNINDENT
.TP
.B Returns
a tuple containing both the response from the OpenID
provider and the session used to by this provider.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B send_request(method, verb=\(aqPOST\(aq, req_params=None, auth_params=None, file_params=None, retries=None, timeout=None, headers=None)
Make an HTTP request to a server method.
.sp
The given method is called with any parameters set in \fBreq_params\fP\&.
If auth is True, then the request is made with an authenticated
session cookie.  Note that path parameters should be set by adding
onto the method, not via \fBreq_params\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBmethod\fP \-\- Method to call on the server.  It\(aqs a url fragment that
comes after the base_url set in __init__().  Note that any
parameters set as extra path information should be listed here,
not in \fBreq_params\fP\&.
.IP \(bu 2
\fBreq_params\fP \-\- dict containing extra parameters to send to the
server
.IP \(bu 2
\fBauth_params\fP \-\- 
.sp
dict containing one or more means of
authenticating to the server.  Valid entries in this dict are:
.INDENT 2.0
.TP
.B cookie
\fBDeprecated\fP Use \fBsession_id\fP instead.  If both
\fBcookie\fP and \fBsession_id\fP are set, only \fBsession_id\fP
will be used.  A \fBCookie.SimpleCookie\fP to send as a
session cookie to the server
.TP
.B session_id
Session id to put in a cookie to construct an
identity for the server
.TP
.B username
Username to send to the server
.TP
.B password
Password to use with username to send to the server
.TP
.B httpauth
If set to \fBbasic\fP then use HTTP Basic Authentication
to send the username and password to the server.  This may
be extended in the future to support other httpauth types
than \fBbasic\fP\&.
.UNINDENT
.sp
Note that cookie can be sent alone but if one of username or
password is set the other must as well.  Code can set all of
these if it wants and all of them will be sent to the server.
Be careful of sending cookies that do not match with the
username in this case as the server can decide what to do in
this case.

.IP \(bu 2
\fBfile_params\fP \-\- dict of files where the key is the name of the
file field used in the remote method and the value is the local
path of the file to be uploaded.  If you want to pass multiple
files to a single file field, pass the paths as a list of paths.
.IP \(bu 2
\fBretries\fP \-\- if we get an unknown or possibly transient error
from the server, retry this many times.  Setting this to a
negative number makes it try forever.  Default to use the
\fI\%retries\fP value set on the instance or in \fB__init__()\fP\&.
.IP \(bu 2
\fBtimeout\fP \-\- A float describing the timeout of the connection.
The timeout only affects the connection process itself, not the
downloading of the response body. Defaults to the \fI\%timeout\fP
value set on the instance or in \fB__init__()\fP\&.
.IP \(bu 2
\fBheaders\fP \-\- A dictionary containing specific headers to add to
the request made.
.UNINDENT
.TP
.B Returns
A tuple of session_id and data.
.TP
.B Return type
tuple of session information and data from server
.UNINDENT
.UNINDENT
.UNINDENT
.SS Clients for Specific Services
.SS Wiki
.INDENT 0.0
.TP
.B class fedora.client.Wiki(base_url=\(aqhttps://fedoraproject.org/w/\(aq, *args, **kwargs)
.INDENT 7.0
.TP
.B api_high_limits = False
.UNINDENT
.INDENT 7.0
.TP
.B check_api_limits()
Checks whether you have the \(aqapihighlimits\(aq right or not.
.UNINDENT
.INDENT 7.0
.TP
.B fetch_all_revisions(start=1, flags=True, timestamp=True, user=True, size=False, comment=True, content=False, title=True, ignore_imported_revs=True, ignore_wikibot=False, callback=None)
Fetch data for all revisions. This could take a long time. You can
start at a specific revision by modifying the \(aqstart\(aq keyword argument.
.sp
To ignore revisions made by "ImportUser" and "Admin" set
ignore_imported_revs to True (this is the default). To ignore edits
made by Wikibot set ignore_wikibot to True (False is the default).
.sp
Modifying the remainder of the keyword arguments will return less/more
data.
.UNINDENT
.INDENT 7.0
.TP
.B get_recent_changes(now, then, limit=500)
Get recent wiki changes from \fInow\fP until \fIthen\fP
.UNINDENT
.INDENT 7.0
.TP
.B login(username, password)
.UNINDENT
.INDENT 7.0
.TP
.B print_recent_changes(days=7, show=10)
.UNINDENT
.UNINDENT
.SS Service
.SS Transforming SQLAlchemy Objects into JSON
.SH GLOSSARY
.INDENT 0.0
.TP
.B controller
In MVC design, the controller is in charge of things.  It takes
processes events and decides what data to ask the \fI\%model\fP for,
manipulates the data according to the information in the event, and
decides which \fI\%view\fP to send the results to to be rendered.
.TP
.B CSRF
\fI\%Cross\-site request forgery\fP is a
technique where a malicious website can gain access to another web
site by hijaacking a currently open session that the user has open to
the site.  This technique can also affect identification via SSL
Certificates or anything else that the browser sends to the server
automatically when a request is made.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
CSRF\-Protection
.UNINDENT
.UNINDENT
.TP
.B Dojo
Dojo is a JavaScript toolkit that aims to be a standard library for
JavaScript.  It provides a small core library with useful functions
and an expanded set of scripts that can be added that provide widgets
and other features.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%http://www.dojotoolkit.org\fP
.UNINDENT
.UNINDENT
.TP
.B double submit
A strategy to foil \fI\%CSRF\fP attacks.  This strategy involves
sending the value of the authentication cookie (or something derivable
only from knowing the value of the authentication cookie) in the body
of the request.  Since the \fI\%Same Origin Policy\fP prevents a web
site other than the one originating the cookie from reading what\(aqs in
the cookie, the server can be reasonably assured that the request does
not originate from an unknown request on another website.  Note that
this and other anti\-CSRF measures do not protect against spoofing or
getting a user to actively click on a link on an attacked website by
mistake.
.TP
.B flask
A simple Python web framework that we\(aqre using in parts of Fedora
Infrastructure.  It provides good documentation and simplicity in its
design.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%http://flask.pocoo.org/docs/\fP
.UNINDENT
.UNINDENT
.TP
.B JSON
\fI\%JavaScript Object Notation\fP is a format for
marshalling data.  It is based on a subset of JavaScript that is used
to declare objects.  Compared to xml, JSON is a lightweight, easily
parsed format.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%Wikipedia\(aqs JSON Entry\fP
.UNINDENT
.UNINDENT
.TP
.B model
In MVC design, the layer that deals directly with the data.
.TP
.B OpenID
A specification for single sign on to web services where the
authentication server and the application seeking to have the user
authenticated do not need to have complete trust in each other.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%http://openid.net/get\-an\-openid/what\-is\-openid/\fP
.UNINDENT
.UNINDENT
.TP
.B Same Origin Policy
A web browser security policy that prevents one website from reading:
1) the cookies from another website
2) the response body from another website
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%http://en.wikipedia.org/wiki/Same_origin_policy\fP
.UNINDENT
.UNINDENT
.TP
.B single sign\-on
A feature that allows one login to authenticate a user for multiple
applications.  So logging into one application will authenticate you
for all the applications that support the same single\-sign\-on
infrastructure.
.TP
.B TurboGears
A Python web framework that most of Fedora Infrastructure\(aqs apps are
built on.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%http://www.turbogears.org/\fP
.UNINDENT
.UNINDENT
.TP
.B TurboGears2
The successor to \fI\%TurboGears\fP, TurboGears2 provides a very
similar framework to coders but has some notable differences. It is
based on pylons and paste so it is much more tightly integrated with
\fI\%WSGI\fP\&.  The differences with :ref\(gaTurboGears\(ga1 are largely with
the organization of code and how to configure the application.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%http://www.turbogears.org/\fP
.UNINDENT
.UNINDENT
.TP
.B view
In MVC design, the layer that takes care of formatting and rendering
data for the consumer.  This could be displaying the data as an html
page or marshalling it into \fI\%JSON\fP objects.
.TP
.B WSGI
WSGI is an interface between web servers and web frameworks that
originated in the Python community.  WSGI lets different components
embed each other even if they were originally written for different
python web frameworks.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
glossary
.IP \(bu 2
genindex
.IP \(bu 2
modindex
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
unknown
.SH COPYRIGHT
2007-2020 Red Hat, Inc.
.\" Generated by docutils manpage writer.
.