5-Minute Quick Start (Python Client)

Goal

By the end of this guide, you'll authenticate, launch a compute Session on CANFAR programmatically, inspect it, read logs/events, and clean it up — all from Python.

Prerequisites

• CADC Account — Sign up
• You have logged in at least once to the CANFAR Science Platform and the Harbor Container Registry
• Python 3.10+

Installation

> pip install canfar --upgradeInstalled

Authentication

The Python client automatically uses your active authentication context created by the CLI.

Login to CANFAR Science Platform

canfar auth login

Login Pathways

• If you already have a valid CADC X509 certificate at ~/.ssl/cadcproxy.pem, the CLI will reuse it automatically.
• If you're an SRCnet user, you'll be guided through an OIDC device flow in your browser.

Force Re-Login (optional)

canfar auth login --force

What just happened?

• The CLI discovered available CANFAR/SRCnet servers
• You authenticated and obtained a certificate/token
• The active context was saved for the Python client to use

Your First Notebook Session

Launch a Jupyter notebook session programmatically.

Notebook Sessionasync

from canfar.sessions import Session

session = Session()
session_ids = session.create(
    name="my-first-notebook",
    image="images.canfar.net/skaha/astroml:latest",
    kind="notebook",
    cores=2,
    ram=4,
)
print(session_ids)  # e.g., ["d1tsqexh"]

from canfar.sessions import AsyncSession

session = AsyncSession()
ids = await session.create(
    name="my-first-notebook",
    image="images.canfar.net/skaha/astroml:latest",
    kind="notebook",
    cores=2,
    ram=4,
)
print(ids)  # e.g., ["d1tsqexh"]

What just happened?

• We connected to CANFAR using your active auth context
• A notebook container was requested with 2 CPU cores and 4 GB RAM
• The API returned the newly created session ID(s)

Get Connection URL

Fetch details and extract the connect URL to open your notebook.

Connect to Sessionasync

session.connect(ids)

await session.connect(ids)

Peek Under the Hood

When a session is created, it goes through a series of steps to be fully deployed. You can inspect the events to understand the progress, or capture them for monitoring.

Deployment Eventsasync

session.events(ids, verbose=True)

await session.events(ids, verbose=True)

At any point, you can also inspect the logs from the session. This is especially useful when launching long-running batch jobs.

Session Logsasync

session.logs(ids, verbose=True)

await session.logs(ids, verbose=True)

Clean Up

When you're done, delete your session(s) to free resources for other users.

Destroy Session(s)async

session.destroy(ids)

await session.destroy(ids)

Troubleshooting

• Session won't start?

  Check available resources

  session.stats()
  

  Check events/logs

  session.events(ids, verbose=True)
  session.logs(ids, verbose=True)
  

  Try smaller resources or different image

  session.create(..., cores=1, ram=2, image="images.canfar.net/skaha/astroml:latest")
  

• Authentication issues?

  Force re-authentication

  canfar auth login --force --debug