Skip to content

Python quickstart

Create a notebook Session, open it, and keep your results before cleaning up. Run these examples on the computer where you installed and authenticated the client. Each code block can run as a separate script.

Choose a compatible client

Install and set up first. These examples use the released v1.5.2 client. Read the upgrade guide when moving from v1.4.1.

Use the same tab throughout: Sync Python for a normal script, or Async Python for an application using async and await.

Running async examples in a notebook

Define main() without its final if __name__ block. In the next cell, run await main() instead of asyncio.run(main()).

1. Authenticate

Terminal on your computer
canfar login cadc
canfar image ls --kind notebook

Choose an image from that listing. Replace the example image below if it is unavailable on your server. For SRCNet or direct Python login, see authentication and server selection.

2. Create a notebook

create_notebook.py
from canfar.sessions import Session

with Session() as session:
    ids = session.create(
        kind="notebook",
        image="images.canfar.net/skaha/astroml:latest",
        name="quickstart-notebook",
        cores=2,
        ram=4,
    )
    print(ids)
create_notebook.py
import asyncio

from canfar.sessions import AsyncSession

async def main() -> None:
    async with AsyncSession() as session:
        ids = await session.create(
            kind="notebook",
            image="images.canfar.net/skaha/astroml:latest",
            name="quickstart-notebook",
            cores=2,
            ram=4,
        )
        print(ids)

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

You receive a list of successfully created Session IDs. Copy the ID and replace SESSION_ID in the following examples. If the list is empty, inspect the error before continuing. Creation does not mean the application is ready.

3. Inspect and connect

open_notebook.py
from canfar.sessions import Session

with Session() as session:
    ids = ["SESSION_ID"]
    print(session.info(ids))
    session.connect(ids)
open_notebook.py
import asyncio

from canfar.sessions import AsyncSession

async def main() -> None:
    async with AsyncSession() as session:
        ids = ["SESSION_ID"]
        print(await session.info(ids))
        await session.connect(ids)

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

info() returns a list of dictionaries containing Session details. connect() opens a browser link for a ready Session and returns None. If it is still Pending, inspect the events below, then repeat this step when it reaches Running. Run your analysis in the notebook before cleaning up.

4. Read events and logs

inspect_notebook.py
from canfar.sessions import Session

with Session() as session:
    ids = ["SESSION_ID"]
    print(session.events(ids))
    print(session.logs(ids))
inspect_notebook.py
import asyncio

from canfar.sessions import AsyncSession

async def main() -> None:
    async with AsyncSession() as session:
        ids = ["SESSION_ID"]
        print(await session.events(ids))
        print(await session.logs(ids))

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

Events return a list of dictionaries; logs return a dictionary keyed by Session ID. A failed request may be omitted from these results. With verbose=True, these methods log their output and return None instead.

5. Clean up

Save your work first

Save notebooks and results under /arc or another persistent destination. Deleting a Session discards /scratch and unsaved application state. Closing a Python client or browser tab does not delete the remote Session.

Delete only the ID you created:

delete_notebook.py
from canfar.sessions import Session

with Session() as session:
    ids = ["SESSION_ID"]
    print(session.destroy(ids))
delete_notebook.py
import asyncio

from canfar.sessions import AsyncSession

async def main() -> None:
    async with AsyncSession() as session:
        ids = ["SESSION_ID"]
        print(await session.destroy(ids))

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

Each requested ID maps to True or False, indicating whether its deletion request succeeded. Keep failed IDs for investigation.

Next steps