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.
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>
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.
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.
Error during authentication. For instance, invalid password.
Error condition that the server is passing back to the client.
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.
FAS Error
CLA Error
Errors generated by the PackageDB Client.
A client for interacting with web services.
Logout from the server.
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: |
|
---|---|
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.
The session_id.
The session id is saved in a file in case it is needed in consecutive runs of BaseClient.
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.)
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.
Changes the useragent string that is reported to the web server.
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.
If True, then more verbose logging is performed to aid in debugging issues.
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.
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.
Changed in version 0.3.33: Added the timeout attribute
When True, we log extra debugging statements. When False, we only log errors.
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: |
|
||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
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
A client for interacting with web services relying on openid auth.
Open a session for the user.
Log in the user with the specified username and password against the FAS OpenID server.
Parameters: |
|
---|
The openid_session_id.
The openid session id is saved in a file in case it is needed in consecutive runs of BaseClient.
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: |
|
---|
The session_id.
The session id is saved in a file in case it is needed in consecutive runs of BaseClient.
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
# [...]
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.)
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.
Changes the useragent string that is reported to the web server.
Name of the cookie that holds the authentication value.
If True, then more verbose logging is performed to aid in debugging issues.
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.
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.
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.
When True, we log extra debugging statements. When False, we only log errors.
Open a session for the user.
Log in the user with the specified username and password against the FAS OpenID server.
Parameters: |
|
---|---|
Returns: | a tuple containing both the response from the OpenID provider and the session used to by this provider. |
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: |
|
||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns: | A tuple of session_id and data. |
||||||||||
Return type: | tuple of session information and data from server |
Checks whether you have the ‘apihighlimits’ right or not.
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 wiki changes from now until then
JSON Helper functions. Most JSON code directly related to classes is implemented via the __json__() methods in model.py. These methods define methods of transforming a class into json for a few common types.
A JSON-based API(view) for your app. Most rules would look like:
@jsonify.when("isinstance(obj, YourClass)")
def jsonify_yourclass(obj):
return [obj.val1, obj.val2]
@jsonify can convert your objects to following types: lists, dicts, numbers and strings
Module author: Toshio Kuratomi <tkuratom@redhat.com>
Transform selectresults into lists.
The one special thing is that we bind the special json_props into each descendent. This allows us to specify a json_props on the toplevel query result and it will pass to all of its children.
Parameters: | obj – sqlalchemy Query object to jsonify |
---|---|
Returns : | list representation of the Query with each element in it given a json_props attributes |
Transform SQLAlchemy InstrumentedLists into json.
The one special thing is that we bind the special json_props into each descendent. This allows us to specify a json_props on the toplevel query result and it will pass to all of its children.
Parameters: | obj – One of the sqlalchemy list types to jsonify |
---|---|
Returns : | list of jsonified elements |
Transform SQLAlchemy ResultProxy into json.
The one special thing is that we bind the special json_props into each descendent. This allows us to specify a json_props on the toplevel query result and it will pass to all of its children.
Parameters: | obj – sqlalchemy ResultProxy to jsonify |
---|---|
Returns : | list of jsonified elements |
Transform a set into a list.
simplejson doesn’t handle sets natively so transform a set into a list.
Parameters: | obj – set to jsonify |
---|---|
Returns : | list representation of the set |
Base class for SQLAlchemy mapped objects.
This base class makes sure we have a __json__() method on each SQLAlchemy mapped object that knows how to:
Transform any SA mapped class into json.
This method takes an SA mapped class and turns the “normal” python attributes into json. The properties (from properties in the mapper) are also included if they have an entry in json_props. You make use of this by setting json_props in the controller.
Example controller:
john = model.Person.get_by(name='John')
# Person has a property, addresses, linking it to an Address class.
# Address has a property, phone_nums, linking it to a Phone class.
john.json_props = {'Person': ['addresses'],
'Address': ['phone_nums']}
return dict(person=john)
json_props is a dict that maps class names to lists of properties you want to output. This allows you to selectively pick properties you are interested in for one class but not another. You are responsible for avoiding loops. ie: don’t do this:
john.json_props = {'Person': ['addresses'], 'Address': ['people']}