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.
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)[source]¶ 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
)
- GraceDB-style authentication
(see
-
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)[source]¶ 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:
- If the
force_noauth
keyword argument is true, then perform no authentication at all. - If the
cert
keyword argument is provided, then use X.509 client certificate authentication. - If the
username
andpassword
keyword arguments are provided, then use basic auth. - Look for a default X.509 client certificate in:
- the environment variables
X509_USER_CERT
andX509_USER_KEY
- the environment variable
X509_USER_PROXY
- the file
/tmp/x509up_uUID
, whereUID
is your numeric user ID, if the file exists and is readable - the files
~/.globus/usercert.pem
and~/.globus/userkey.pem
, if they exist and are readable
- the environment variables
- Read the netrc file [1] located at
~/.netrc
, or at the path stored in the environment variableNETRC
, and look for a username and password matching the hostname in the URL. - If the
fail_if_noauth
keyword argument is true, and no authentication source was found, then raise aValueError
.
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)[source]¶ 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)[source]¶ 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)[source]¶ Bases:
object
A mixin for
requests.Session
to raise exceptions for HTTP errors.
-
class
requests_gracedb.file.
SessionFileMixin
[source]¶ 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)[source]¶ Bases:
object
A mixin for
requests.Session
to add a User-Agent header.