# beaker-py

A lightweight pure-Python RPC-based client for Beaker.

```{seealso}
There are also higher-level Python packages available for interacting with Beaker, such as **[Gantry](/gantry/index)**.
```

## Installing

### Installing with `pip`

**beaker-py** is available [on PyPI](https://pypi.org/project/beaker-py/). Just run

```bash
pip install beaker-py
```

### Installing from source

To install **beaker-py** from source, first clone [the repository](https://github.com/allenai/beaker):

```bash
git clone https://github.com/allenai/beaker.git
```

Then create or activate a Python virtual environment, and run:

```bash
cd beaker/bindings/python
make dev-install
```

## Quick start

If you've already configured the [Beaker command-line client](https://github.com/allenai/beaker/),
**beaker-py** will find and use the existing configuration file (usually located at `$HOME/.beaker/config.yml`) or `BEAKER_TOKEN` environment variable.

Then you can instantiate the Beaker {class}`Python client <beaker.Beaker>` with the {meth}`Beaker.from_env() <beaker.Beaker.from_env>` class method:

```python
from beaker import Beaker

with Beaker.from_env() as beaker:
    ...
```

With the Python client, you can:

- Query [**Clusters**](https://beaker-docs.apps.allenai.org/concept/clusters.html) with {data}`Beaker.cluster <beaker._cluster.ClusterClient>` methods. For example:

  ```python
  beaker.cluster.get("ai2/jupiter-cirrascale-2")
  ```

- Manage [**Datasets**](https://beaker-docs.apps.allenai.org/concept/datasets.html) with {data}`Beaker.dataset <beaker._dataset.DatasetClient>` methods. For example:

  ```python
  beaker.dataset.create(dataset_name, source_dir)
  ```

- Manage [**Experiments**](https://beaker-docs.apps.allenai.org/concept/experiments.html) with {data}`Beaker.experiment <beaker._experiment.ExperimentClient>` and {data}`Beaker.workload <beaker._workload.WorkloadClient>` methods. For example:

  ```python
  beaker.experiment.create(spec=spec, name=name)
  ```

- Manage [**Groups**](https://beaker-docs.apps.allenai.org/concept/groups.html) with {data}`Beaker.group <beaker._group.GroupClient>` methods. For example:

  ```python
  beaker.group.create(name)
  ```

- Manage [**Images**](https://beaker-docs.apps.allenai.org/concept/images.html) with {data}`Beaker.image <beaker._image.ImageClient>` methods. For example:

  ```python
  beaker.image.update(image, name=name)
  ```

- Manage [**Secrets**](https://beaker-docs.apps.allenai.org/concept/secrets.html) with {data}`Beaker.secret <beaker._secret.SecretClient>` methods. For example:

  ```python
  beaker.secret.write(name, value)
  ```

- Manage [**Workspaces**](https://beaker-docs.apps.allenai.org/concept/workspaces.html) with {data}`Beaker.workspace <beaker._workspace.WorkspaceClient>` methods. For example:

  ```python
  beaker.workspace.create("ai2/new_workspace")
  ```

- Track **Jobs** with {data}`Beaker.job <beaker._job.JobClient>` methods. For example:

  ```python
  beaker.job.logs(job, follow=True)
  ```

- Create and process [**Queues**](https://beaker-docs.apps.allenai.org/concept/queues.html) with {data}`Beaker.queue <beaker._queue.QueueClient>` methods. For example:

  ```python
  beaker.queue.create("my-work-queue", batch_size=4)
  ```

If you're coming from [v1 of beaker-py](https://github.com/allenai/beaker-py), consider reading the [migration guide](https://github.com/allenai/beaker/blob/main/bindings/python/MIGRATION_GUIDE.md).

### Example workflow

Launch and follow an experiment like **[Gantry](/gantry/index)** does:

```python
import time
from beaker import Beaker, BeakerExperimentSpec, BeakerJobPriority


with Beaker.from_env() as beaker:
    # Build experiment spec...
    spec = BeakerExperimentSpec.new(
        description="beaker-py test run",
        beaker_image="petew/hello-world",
        priority=BeakerJobPriority.low,
        preemptible=True,
    )

    # Create experiment workload...
    workload = beaker.experiment.create(spec=spec)

    # Wait for job to be created...
    while (job := beaker.workload.get_latest_job(workload)) is None:
        print("waiting for job to start...")
        time.sleep(1.0)

    # Follow logs...
    print("Job logs:")
    for job_log in beaker.job.logs(job, follow=True):
        print(job_log.message.decode())
```

See the [integration tests](https://github.com/allenai/beaker/tree/main/bindings/python/src/integration_tests) for more examples.

```{toctree}
:hidden:
:caption: Methods

api/clusters
api/datasets
api/experiments
api/workloads
api/groups
api/images
api/secrets
api/workspaces
api/jobs
api/queues
```

```{toctree}
:hidden:
:caption: API Reference

api/client
api/types/index
api/exceptions
```

```{toctree}
:hidden:
:caption: Ecosystem

gantry/index
```

```{toctree}
:hidden:
:caption: Development

CHANGELOG <https://github.com/allenai/beaker/blob/main/bindings/python/CHANGELOG.md>
GitHub Repository <https://github.com/allenai/beaker>
```


# Indices and tables

- {ref}`genindex`
- {ref}`modindex`