Session usage

All of the functions introduced in the Top-level API accept a session keyword to enable reusing a connection to a GWDataFind host.

For example:

Example use of a gwdatafind.Session to reuse a connection.

>>> from gwdatafind import (
...     find_observatories,
...     find_urls,
...     Session,
... )
>>> with Session() as sess:
...     obs = find_observatories(
...         host="datafind.gw-openscience.org",
...         session=sess,
...     )
...     print(obs)
...     urls = {}
...     for ifo in obs:
...         urls[ifo] = find_urls(
...             ifo,
...             "{}1_GWOSC_O2_4KHZ_R1".format(ifo),
...             1187008880,
...             1187008884,
...             host="datafind.gw-openscience.org",
...             session=sess,
...         )
...     print(urls)
['H', 'V', 'L']
{'H': ['file://localhost/cvmfs/gwosc.osgstorage.org/gwdata/O2/strain.4k/frame.v1/H1/1186988032/H-H1_GWOSC_O2_4KHZ_R1-1187008512-4096.gwf'],
 'V': ['file://localhost/cvmfs/gwosc.osgstorage.org/gwdata/O2/strain.4k/frame.v1/V1/1186988032/V-V1_GWOSC_O2_4KHZ_R1-1187008512-4096.gwf'],
 'L': ['file://localhost/cvmfs/gwosc.osgstorage.org/gwdata/O2/strain.4k/frame.v1/L1/1186988032/L-L1_GWOSC_O2_4KHZ_R1-1187008512-4096.gwf']}

In the above example the connection to datafind.gw-openscience.org is held open and reused to simplify subsequent queries and minimise the risk of network communication issues.

The gwdatafind.Session object is just an import of igwn_auth_utils.Session, a wrapper around requests.Session that automatically handles IGWN authorisation credentials/tokens. For more details on credential or token usage, see Authentication and authorisation.