This release is a pre-release and may not be stable for production use.
Beaker-py 
A lightweight pure-Python client for Beaker.
Quick Links
- 📝 Docs and examples:
- 🌍 Ecosystem:
Installing
Installing with pip
beaker-py is available on PyPI. Just run
pip install beaker-py
Installing from source
To install beaker-py from source, first clone the repository:
git clone https://github.com/allenai/beaker.git
Then create or activate a Python virtual environment, and run:
cd beaker/bindings/python
make dev-install
Quick start
If you've already configured the Beaker command-line client,
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 client with the .from_env() class method:
from beaker import Beaker
with Beaker.from_env() as beaker:
...
With the Python client, you can:
-
Query Clusters with
beaker.cluster.*methods. For example:beaker.cluster.get("ai2/jupiter-cirrascale-2")
-
Manage Datasets with
beaker.dataset.*methods. For example:beaker.dataset.create(dataset_name, source_dir)
-
Manage Experiments with
beaker.experiment.*andbeaker.workload.*methods. For example:beaker.experiment.create(spec=spec, name=name)
-
Manage Groups with
beaker.group.*methods. For example:beaker.group.create(name)
-
Manage Images with
beaker.image.*methods. For example:beaker.image.update(image, name=name)
-
Manage Secrets with
beaker.secret.*methods. For example:beaker.secret.write(name, value)
-
Manage Workspaces with
beaker.workspace.*methods. For example:beaker.workspace.create("ai2/new_workspace")
-
Track Jobs with
beaker.job.*methods. For example:beaker.job.logs(job, follow=True)
-
Create and process Queues with
beaker.queue.*methods. For example:beaker.queue.create("my-work-queue", batch_size=4)
If you're coming from v1 of beaker-py, consider reading the migration guide.
Example workflow
Launch and follow an experiment like beaker-gantry does:
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 for more examples.
Development
After installing from source, you can run checks and tests locally with:
make checks
Releases
At the moment releases need to be published manually by following these steps:
- Ensure you've authenticated with PyPI through a
~/.pypircfile and have write permissions to the beaker-py project. The local~/.pypircfile looks like:
[distutils]
index-servers = pypi
[pypi]
username = __token__
password = #beaker-py pypi API token from 1pass#
- Ensure the target release version defined in
src/beaker/version.pyis correct, or change the version on the fly by adding theMakeargumentBEAKER_PY_VERSION=X.X.Xto the command in the next step. - Ensure the CHANGELOG.md has a section at the top for the new release (
## vX.X.X - %Y-%m-%d). - Run
make publishfor a stable release ormake publish-nightlyfor a nightly pre-release.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file beaker_py-2.5.7.dev20260402.tar.gz.
File metadata
- Download URL: beaker_py-2.5.7.dev20260402.tar.gz
- Upload date:
- Size: 104.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.12.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
46657021198acccf3f208b73d3ac39a92533f7f15a2b6acb398f17620e7acea9
|
|
| MD5 |
2e9b65a8080a274a933d2596f320aade
|
|
| BLAKE2b-256 |
622c4de68dcf2f98d2cd783045f87087529dade04f120916693b65ef52fe3645
|
File details
Details for the file beaker_py-2.5.7.dev20260402-py3-none-any.whl.
File metadata
- Download URL: beaker_py-2.5.7.dev20260402-py3-none-any.whl
- Upload date:
- Size: 116.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.12.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6399d0d2af2b739400ca285abefa7eddb479c52562ffa407a47811af4931f41b
|
|
| MD5 |
ef205cc7ded75f8383296bd9261f99bd
|
|
| BLAKE2b-256 |
5d6dd4e62e3efe6768580da40da0aafcd115c10570b44dcd9699e8173cf0d156
|
