Metadata-Version: 2.1
Name: gwcloud-python
Version: 2.1.0
Summary: Wrapper of GWDC API, used for interacting with the GWCloud endpoints
Home-page: https://github.com/gravitationalwavedc/gwcloud_python
License: MIT
Author: Thomas Reichardt
Author-email: treichardt@swin.edu.au
Requires-Python: >=3.7,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Provides-Extra: docs
Requires-Dist: Sphinx (>=5.1.1,<6.0.0) ; extra == "docs"
Requires-Dist: graphene-file-upload (>=1.3.0,<2.0.0)
Requires-Dist: gwdc-python (>=1.0,<2.0)
Requires-Dist: importlib-metadata (>=4.12.0,<5.0.0)
Requires-Dist: jwt (>=1.3.1,<2.0.0)
Requires-Dist: requests (>=2.28.1,<3.0.0)
Requires-Dist: sphinx-rtd-theme (>=1.0.0,<2.0.0) ; extra == "docs"
Requires-Dist: tqdm (>=4.64.0,<5.0.0)
Project-URL: Documentation, https://gwcloud-python.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/gravitationalwavedc/gwcloud_python
Description-Content-Type: text/x-rst

GWCloud Python API
==================

`GWCloud <https://gwcloud.org.au/>`_ is a service used to handle both the submission of `Bilby <https://pypi.org/project/bilby/>`_ jobs to a supercomputer queue and the obtaining of the results produced by these jobs.
While there is a web interface for this service, which is recommended for beginners, this package can be used to allow Bilby job submission and manipulation from Python scripts.

Check out the `documentation <https://gwcloud-python.readthedocs.io/en/latest/>`_ for more information.

Installation
------------

The gwcloud-python package can be installed with

::

    pip install gwcloud-python


Example
-------

::

    >>> from gwcloud_python import GWCloud
    >>> gwc = GWCloud(token='<user_api_token_here>')
    >>> job = gwc.get_official_job_list()[0]
    >>> job.save_corner_plot_files()

    100%|██████████████████████████████████████| 3.76M/3.76M [00:00<00:00, 5.20MB/s]
    All 2 files saved!


GWFlow
------

To upsert a GWFlow job record and upload its pending files::

    from gwcloud_python import GWCloud

    gwc = GWCloud(api_token="<your-token>", endpoint="<endpoint>")

    # Upsert a job (idempotent — creates or updates by sname)
    result = gwc.upsert_gwflow_job(
        sname="S230101a",
        metadata={"key": "value"},
        files=[{"path": "/frames/H1.gwf", "file_name": "H1.gwf", "analysis_uid": "uid-001"}],
    )

    # Upload each pending file
    for pending_file in result.files_pending:
        gwc.upload_gwflow_file(pending_file.id, f"/local/path/{pending_file.file_name}")

To list GWFlow jobs, fetch a job by its super-name, and download one of its files::

    from gwcloud_python import GWCloud

    gwc = GWCloud(api_token="<your-token>", endpoint="<endpoint>")

    jobs = gwc.get_gwflow_job_list(search="S230101a", time_range="all", include_pruned=False)
    job = gwc.get_gwflow_job(sname="S230101a")
    if job is not None and job.files:
        gwc.download_gwflow_file(job.files[0].download_token, "/local/path/file.h5")

Other GWFlow methods include:

- ``get_gwflow_pending_files`` — get all GWFlow files that have not yet been mirrored.
- ``link_bilby_job_to_gwflow`` — link a Bilby job to a GWFlow analysis.

See the `GWFlow guide <https://gwcloud-python.readthedocs.io/en/latest/usage/gwflow.html>`_ in the documentation for more details.

