# 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

exception `fedora.client.``BodhiClientException`

class `fedora.client.``DictContainer`(*args, **kwargs)

### 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` = <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.

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

## Service

### Transforming SQLAlchemy Objects into JSON