Skip to content

Python client

The CANFAR Python client provides authenticated access to Sessions, Container Images, VOSpace Services, and Science Platform metadata.

Install and authenticate

Install the client first. These examples use v1.5.2; unreleased additions are marked separately in What's new.

canfar login cadc

The CLI stores the Authentication Record and Server Selection used by default by Python clients. Python OIDC login is also available as canfar.login() and canfar.alogin(); see Install and set up.

Core workflows

  • Create Sessions

    Launch notebooks, desktops, CARTA, Firefly, contributed apps, or headless workloads with Session or AsyncSession.

    Quickstart

  • Read data

    Address VOSpace Services through explicit Storage Identifiers and standard fsspec methods.

    Data access

  • Inspect platform state

    Query available resources, Container Images, and Science Platform Server capacity.

    Python API reference

Try the same task in Python

Both examples list your running notebooks and print the returned records. Choose Sync Python for a normal script, or Async Python when your application already uses async and await.

list_notebooks.py
from canfar.sessions import Session

with Session() as session:
    notebooks = session.fetch(kind="notebook", status="Running")
    print(notebooks)
list_notebooks.py
import asyncio

from canfar.sessions import AsyncSession

async def main() -> None:
    async with AsyncSession() as session:
        notebooks = await session.fetch(kind="notebook", status="Running")
        print(notebooks)

if __name__ == "__main__":
    asyncio.run(main())

An empty list means no notebooks match those filters. Follow the Python tutorial to create, inspect, and clean up a Session.

Using the async example in Jupyter

Define main() without the final if __name__ block, then run await main() in another cell. Jupyter already has an event loop.

Main modules

Module Use
canfar.sessions Create, fetch, inspect, connect, log, and destroy Sessions.
canfar.images List Container Images or fetch parsed image details.
canfar.storage List Storage Identifiers and build explicit fsspec filesystems.
canfar.context Read resource limits advertised by a Science Platform Server.
canfar.overview Check Science Platform Server availability.
canfar.authentication Login and manage saved Authentication Records.
canfar.client Compose lower-level synchronous or asynchronous HTTP clients.