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

exception fedora.client.AuthError¶: Error during authentication. For instance, invalid password.

exception fedora.client.AppError(name, message, extras=None)¶: Error condition that the server is passing back to the client.

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 generate. 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.FASError¶: FAS Error

exception fedora.client.CLAError¶: CLA Error

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

session_cookie¶

Deprecated, use session_id instead.

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

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.

session_as_cookie¶: 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

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

log = <logging.Logger object>¶

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.

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.

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

API Documentation¶

Client¶

Generic Clients¶

BaseClient¶

ProxyClient¶

OpenIdBaseClient¶

OpenIdProxyClient¶

Clients for Specific Services¶

Wiki¶

Service¶

Transforming SQLAlchemy Objects into JSON¶

Table Of Contents

Related Topics

This Page