API Documentation

This API Documentation is currently a catch-all. We’re going to merge the API docs into the hand created docs as we have time to integrate them.

Client

fedora.client is used to interact with Fedora Services.

Changed in version 0.3.21: Deprecate DictContainer in favor of bunch.Bunch

Changed in version 0.3.35: Add the openid clients

Module author: Ricky Zhou <ricky@fedoraproject.org>

Module author: Luke Macken <lmacken@redhat.com>

Module author: Toshio Kuratomi <tkuratom@redhat.com>

exception fedora.client.AppError(name, message, extras=None)

Error condition that the server is passing back to the client.

exception fedora.client.AuthError

Error during authentication. For instance, invalid password.

exception fedora.client.CLAError

CLA Error

class fedora.client.DictContainer(*args, **kwargs)
exception fedora.client.FASError

FAS Error

exception fedora.client.FedoraClientError

Base Exception for problems which originate within the Clients.

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.

Problems returned while talking to the Services should be returned via a FedoraServiceError instead.

exception fedora.client.FedoraServiceError

Base Exception for any problem talking with the Service.

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.

exception fedora.client.ServerError(url, status, msg)

Unable to talk to the server properly.

This includes network errors and 500 response codes. If the error was generated from an http response, code is the HTTP response code. Otherwise, code will be -1.

Generic Clients

BaseClient

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='tg-visit', cache_session=True, retries=None, timeout=None)

A client for interacting with web services.

logout()

Logout from the server.

send_request(method, req_params=None, file_params=None, auth=False, retries=None, timeout=None, **kwargs)

Make an HTTP request to a server method.

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.

Parameters

  • method – Method to call on the server. It’s a url fragment that comes after the base_url set in __init__().

  • req_params – Extra parameters to send to the server.

  • file_params – 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.

  • auth – If True perform auth to the server, else do not.

  • retries – 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 retries value set on the instance or in __init__() (which defaults to zero, no retries).

  • timeout – 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 timeout value set on the instance or in __init__() (which defaults to 120s).

Return type

Bunch

Returns

The data from the server

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

Changed in version 0.3.33: * Added the timeout kwarg

Deprecated, use session_id instead.

The session cookie is saved in a file in case it is needed in consecutive runs of BaseClient.

property session_id

The session_id.

The session id is saved in a file in case it is needed in consecutive runs of BaseClient.

ProxyClient

class fedora.client.ProxyClient(base_url, useragent=None, session_name='tg-visit', 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.

If you want something that can manage one user’s connection to a Fedora Service, then look into using BaseClient instead.

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.)

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 ProxyClient instance.

useragent

Changes the useragent string that is reported to the web server.

session_name

Name of the cookie that holds the authentication value.

If True, then the session information is saved locally as a cookie. This is here for backwards compatibility. New code should set this to False when constructing the ProxyClient.

debug

If True, then more verbose logging is performed to aid in debugging issues.

insecure

If True 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.

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.

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.

Changed in version 0.3.33: Added the timeout attribute

property debug

When True, we log extra debugging statements. When False, we only log errors.

log = <Logger fedora.client.proxyclient (WARNING)>
send_request(method, req_params=None, auth_params=None, file_params=None, retries=None, timeout=None)

Make an HTTP request to a server method.

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. Note that path parameters should be set by adding onto the method, not via req_params.

Parameters

  • method – Method to call on the server. It’s 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 req_params.

  • req_params – dict containing extra parameters to send to the server

  • auth_params –

    dict containing one or more means of authenticating to the server. Valid entries in this dict are:

    cookie

    Deprecated Use session_id instead. If both cookie and session_id are set, only session_id will be used. A Cookie.SimpleCookie to send as a session cookie to the server

    session_id

    Session id to put in a cookie to construct an identity for the server

    username

    Username to send to the server

    password

    Password to use with username to send to the server

    httpauth

    If set to basic 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 basic.

    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.

  • file_params – 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.

  • retries – 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 retries value set on the instance or in __init__().

  • 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 the timeout value set on the instance or in __init__().

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.

Return type

tuple of session information and data from server

Changed in version 0.3.17: No longer send tg_format=json parameter. We rely solely on the Accept: application/json header now.

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

Changed in version 0.3.33: Added the timeout kwarg

OpenIdBaseClient

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.

has_cookies()
login(username, password, otp=None)

Open a session for the user.

Log in the user with the specified username and password against the FAS OpenID server.

Parameters

  • username – the FAS username of the user that wants to log in

  • password – the FAS password of the user that wants to log in

  • otp – currently unused. Eventually a way to send an otp to the API that the API can use.

send_request(method, auth=False, verb='POST', **kwargs)

Make an HTTP request to a server method.

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.

Parameters

  • method – Method to call on the server. It’s a url fragment that comes after the base_url set in __init__().

  • auth – If True perform auth to the server, else do not.

  • req_params – Extra parameters to send to the server.

  • file_params – 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.

  • verb – HTTP verb to use. GET and POST are currently supported. POST is the default.

property session_key
fedora.client.openidbaseclient.requires_login(func)

Decorator function for get or post requests requiring login.

Decorate a controller method that requires the user to be authenticated. Example:

from fedora.client.openidbaseclient import requires_login

@requires_login
def rename_user(new_name):
    user = new_name
    # [...]

OpenIdProxyClient

class fedora.client.OpenIdProxyClient(base_url, login_url=None, useragent=None, session_name='session', 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.

If you want something that can manage one user’s connection to a Fedora Service, then look into using OpenIdBaseClient instead.

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.)

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 OpenIdProxyClient instance.

useragent

Changes the useragent string that is reported to the web server.

session_name

Name of the cookie that holds the authentication value.

debug

If True, then more verbose logging is performed to aid in debugging issues.

insecure

If True 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.

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.

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.

property debug

When True, we log extra debugging statements. When False, we only log errors.

login(username, password, otp=None)

Open a session for the user.

Log in the user with the specified username and password against the FAS OpenID server.

Parameters

  • username – the FAS username of the user that wants to log in

  • password – the FAS password of the user that wants to log in

  • otp – currently unused. Eventually a way to send an otp to the API that the API can use.

Returns

a tuple containing both the response from the OpenID provider and the session used to by this provider.

send_request(method, verb='POST', req_params=None, auth_params=None, file_params=None, retries=None, timeout=None, headers=None)

Make an HTTP request to a server method.

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. Note that path parameters should be set by adding onto the method, not via req_params.

Parameters

  • method – Method to call on the server. It’s 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 req_params.

  • req_params – dict containing extra parameters to send to the server

  • auth_params –

    dict containing one or more means of authenticating to the server. Valid entries in this dict are:

    cookie

    Deprecated Use session_id instead. If both cookie and session_id are set, only session_id will be used. A Cookie.SimpleCookie to send as a session cookie to the server

    session_id

    Session id to put in a cookie to construct an identity for the server

    username

    Username to send to the server

    password

    Password to use with username to send to the server

    httpauth

    If set to basic 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 basic.

    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.

  • file_params – 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.

  • retries – 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 retries value set on the instance or in __init__().

  • 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 the timeout value set on the instance or in __init__().

  • headers – A dictionary containing specific headers to add to the request made.

Returns

A tuple of session_id and data.

Return type

tuple of session information and data from server

Clients for Specific Services

Wiki

class fedora.client.Wiki(base_url='https://fedoraproject.org/w/', *args, **kwargs)
api_high_limits = False
check_api_limits()

Checks whether you have the ‘apihighlimits’ right or not.

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 ‘start’ keyword argument.

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).

Modifying the remainder of the keyword arguments will return less/more data.

get_recent_changes(now, then, limit=500)

Get recent wiki changes from now until then

login(username, password)
print_recent_changes(days=7, show=10)

Service

Transforming SQLAlchemy Objects into JSON