requests-gracedb Documentation

requests-gracedb provides a generic REST API client for GraceDB and similar LIGO/Virgo API services. It uses the powerful Requests package for reliable and high-throughput HTTP connection pooling.

Quick Start

Install with pip:

pip install requests-gracedb

API

class requests_gracedb.Session(url=None, cert=None, username=None, password=None, force_noauth=False, fail_if_noauth=False, cert_reload=False, cert_reload_timeout=300, **kwargs)

Bases: requests_gracedb.auth.SessionAuthMixin, requests_gracedb.errors.SessionErrorMixin, requests_gracedb.file.SessionFileMixin, requests_gracedb.user_agent.SessionUserAgentMixin, requests.sessions.Session

A requests.Session subclass that adds behaviors that are common to ligo.org REST API services such as that of GraceDB.

It adds the following behaviors to the session:

• GraceDB-style authentication (see SessionAuthMixin)
• Raise exceptions based on HTTP status codes (see SessionErrorMixin)
• Automatically load POSTed files from disk, automatically guess MIME types (see SessionFileMixin)
• Add User-Agent string based on Python package name and version (see SessionUserAgentMixin)

class requests_gracedb.auth.SessionAuthMixin(url=None, cert=None, username=None, password=None, force_noauth=False, fail_if_noauth=False, cert_reload=False, cert_reload_timeout=300, **kwargs)

Bases: object

A mixin for requests.Session to add support for all GraceDB authentication mechanisms.

Parameters:

• url (str) – GraceDB Client URL.
• cert (str, tuple) – Client-side X.509 certificate. May be either a single filename if the certificate and private key are concatenated together, or a tuple of the filenames for the certificate and private key.
• username (str) – Username for basic auth.
• password (str) – Password for basic auth.
• force_noauth (bool, default=False) – If true, then do not use any authentication at all.
• fail_if_noauth (bool, default=False) – If true, then raise an exception if authentication credentials are not provided.
• cert_reload (bool, default=False) – If true, then automatically reload the client certificate before it expires.
• cert_reload_timeout (int, default=300) – Reload the certificate this many seconds before it expires.

Notes

When a new Session instance is created, the following sources of authentication are tried, in order:

1. If the force_noauth keyword argument is true, then perform no authentication at all.
2. If the cert keyword argument is provided, then use X.509 client certificate authentication.
3. If the username and password keyword arguments are provided, then use basic auth.
4. Look for a default X.509 client certificate in:
   1. the environment variables X509_USER_CERT and X509_USER_KEY
   2. the environment variable X509_USER_PROXY
   3. the file /tmp/x509up_uUID, where UID is your numeric user ID, if the file exists and is readable
   4. the files ~/.globus/usercert.pem and ~/.globus/userkey.pem, if they exist and are readable
5. Read the netrc file [1] located at ~/.netrc, or at the path stored in the environment variable NETRC, and look for a username and password matching the hostname in the URL.
6. If the fail_if_noauth keyword argument is true, and no authentication source was found, then raise a ValueError.

References

[1]	The .netrc file. https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html

HTTPS adapter to close connections with expired client certificates.

class requests_gracedb.cert_reload.CertReloadingHTTPAdapter(cert_reload_timeout=0, **kwargs)

Bases: requests.adapters.HTTPAdapter

A mixin for requests.Session to automatically reload the client X.509 certificates if the version that is stored in the session is going to expire soon.

Parameters:cert_reload_timeout (int) – Reload the certificate if it expires within this many seconds from now.

requests_gracedb.cert_reload.load_x509_certificate(filename)

Load an X.509 certificate from a file.

Parameters:filename (str) – The name of the certificate file. Returns:cert – The parsed certificate. Return type:cryptography.x509.Certificate

class requests_gracedb.errors.SessionErrorMixin(**kwargs)

Bases: object

A mixin for requests.Session to raise exceptions for HTTP errors.

class requests_gracedb.file.SessionFileMixin

Bases: object

A mixin for requests.Session to add features for file uploads.

The requests.Session.request() method takes a files argument which is a dictionary of {fieldname: fileobject}, where fileobject may be a file-like object or a tuple of 2-4 elements consisting of the filename, file content, MIME type, and any custom headers.

This mixin adds the following features:

• The MIME type is automatically guessed from the filename.
• If the file content is None, then the filename is treated as a path, and the file is opened and read. If the filename is -, then the file content is read from stdin.

class requests_gracedb.user_agent.SessionUserAgentMixin(**kwargs)

Bases: object

A mixin for requests.Session to add a User-Agent header.