| Name | beaker-py JSON |
| Version |
2.4.7
JSON |
| download |
| home_page | None |
| Summary | A Python Beaker client |
| upload_time | 2025-07-21 21:18:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Beaker-py [](https://pypi.org/project/beaker-py/)
A lightweight pure-Python client for Beaker.
## Quick Links
- 📝 Docs and examples:
- [API docs](https://beaker-py-docs.allen.ai/)
- [Integration test examples](https://github.com/allenai/beaker/tree/main/bindings/python/src/integration_tests)
- [v1 → v2 migration guide](https://github.com/allenai/beaker/blob/main/bindings/python/MIGRATION_GUIDE.md)
- 🌍 Ecosystem:
- [beaker-gantry](https://github.com/allenai/beaker-gantry)
- [beaker-run-action](https://github.com/allenai/beaker-run-action)
## 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 client with the `.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 `beaker.cluster.*` methods. For example:
```python
beaker.cluster.get("ai2/jupiter-cirrascale-2")
```
- Manage [**Datasets**](https://beaker-docs.apps.allenai.org/concept/datasets.html) with `beaker.dataset.*` methods. For example:
```python
beaker.dataset.create(dataset_name, source_dir)
```
- Manage [**Experiments**](https://beaker-docs.apps.allenai.org/concept/experiments.html) with `beaker.experiment.*` and `beaker.workload.*` methods. For example:
```python
beaker.experiment.create(spec=spec, name=name)
```
- Manage [**Groups**](https://beaker-docs.apps.allenai.org/concept/groups.html) with `beaker.group.*` methods. For example:
```python
beaker.group.create(name)
```
- Manage [**Images**](https://beaker-docs.apps.allenai.org/concept/images.html) with `beaker.image.*` methods. For example:
```python
beaker.image.update(image, name=name)
```
- Manage [**Secrets**](https://beaker-docs.apps.allenai.org/concept/secrets.html) with `beaker.secret.*` methods. For example:
```python
beaker.secret.write(name, value)
```
- Manage [**Workspaces**](https://beaker-docs.apps.allenai.org/concept/workspaces.html) with `beaker.workspace.*` methods. For example:
```python
beaker.workspace.create("ai2/new_workspace")
```
- Track **Jobs** with `beaker.job.*` methods. For example:
```python
beaker.job.logs(job, follow=True)
```
- Create and process [**Queues**](https://beaker-docs.apps.allenai.org/concept/queues.html) with `beaker.queue.*` 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 [beaker-gantry](https://github.com/allenai/beaker-gantry) 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.
## Development
After [installing from source](#installing-from-source), you can run checks and tests locally with:
```bash
make checks
```
### Releases
At the moment releases need to be published manually by following these steps:
1. Ensure you've authenticated with [PyPI](https://pypi.org/) through a `~/.pypirc` file and have write permissions to the [beaker-py project](https://pypi.org/project/beaker-py/).
2. Ensure the target release version defined in `src/beaker/version.py` is correct, or change the version on the fly by adding the `Make` argument `BEAKER_PY_VERSION=X.X.X` to the command in the next step.
3. Ensure the CHANGELOG.md has a section at the top for the new release (`## vX.X.X - %Y-%m-%d`).
4. Run `make publish` for a stable release or `make publish-nightly` for a nightly pre-release.
Raw data
{
"_id": null,
"home_page": null,
"name": "beaker-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Allen Institute for Artificial Intelligence <contact@allenai.org>, Pete Walsh <petew@allenai.org>",
"download_url": "https://files.pythonhosted.org/packages/57/ba/36b1c114dbb911902e4707908233a1fc62befbb94ff6ca8eb471dbc78a02/beaker_py-2.4.7.tar.gz",
"platform": null,
"description": "# Beaker-py [](https://pypi.org/project/beaker-py/)\n\nA lightweight pure-Python client for Beaker.\n\n## Quick Links\n\n- \ud83d\udcdd Docs and examples:\n - [API docs](https://beaker-py-docs.allen.ai/)\n - [Integration test examples](https://github.com/allenai/beaker/tree/main/bindings/python/src/integration_tests)\n - [v1 \u2192 v2 migration guide](https://github.com/allenai/beaker/blob/main/bindings/python/MIGRATION_GUIDE.md)\n- \ud83c\udf0d Ecosystem:\n - [beaker-gantry](https://github.com/allenai/beaker-gantry)\n - [beaker-run-action](https://github.com/allenai/beaker-run-action)\n\n## Installing\n\n### Installing with `pip`\n\n**beaker-py** is available [on PyPI](https://pypi.org/project/beaker-py/). Just run\n\n```bash\npip install beaker-py\n```\n\n### Installing from source\n\nTo install **beaker-py** from source, first clone [the repository](https://github.com/allenai/beaker):\n\n```bash\ngit clone https://github.com/allenai/beaker.git\n```\n\nThen create or activate a Python virtual environment, and run:\n\n```bash\ncd beaker/bindings/python\nmake dev-install\n```\n\n## Quick start\n\nIf you've already configured the [Beaker command-line client](https://github.com/allenai/beaker/),\n**beaker-py** will find and use the existing configuration file (usually located at `$HOME/.beaker/config.yml`) or `BEAKER_TOKEN` environment variable.\n\nThen you can instantiate the Beaker client with the `.from_env()` class method:\n\n```python\nfrom beaker import Beaker\n\nwith Beaker.from_env() as beaker:\n ...\n```\n\nWith the Python client, you can:\n\n- Query [**Clusters**](https://beaker-docs.apps.allenai.org/concept/clusters.html) with `beaker.cluster.*` methods. For example:\n\n ```python\n beaker.cluster.get(\"ai2/jupiter-cirrascale-2\")\n ```\n\n- Manage [**Datasets**](https://beaker-docs.apps.allenai.org/concept/datasets.html) with `beaker.dataset.*` methods. For example:\n\n ```python\n beaker.dataset.create(dataset_name, source_dir)\n ```\n\n- Manage [**Experiments**](https://beaker-docs.apps.allenai.org/concept/experiments.html) with `beaker.experiment.*` and `beaker.workload.*` methods. For example:\n\n ```python\n beaker.experiment.create(spec=spec, name=name)\n ```\n\n- Manage [**Groups**](https://beaker-docs.apps.allenai.org/concept/groups.html) with `beaker.group.*` methods. For example:\n\n ```python\n beaker.group.create(name)\n ```\n\n- Manage [**Images**](https://beaker-docs.apps.allenai.org/concept/images.html) with `beaker.image.*` methods. For example:\n\n ```python\n beaker.image.update(image, name=name)\n ```\n\n- Manage [**Secrets**](https://beaker-docs.apps.allenai.org/concept/secrets.html) with `beaker.secret.*` methods. For example:\n\n ```python\n beaker.secret.write(name, value)\n ```\n\n- Manage [**Workspaces**](https://beaker-docs.apps.allenai.org/concept/workspaces.html) with `beaker.workspace.*` methods. For example:\n\n ```python\n beaker.workspace.create(\"ai2/new_workspace\")\n ```\n\n- Track **Jobs** with `beaker.job.*` methods. For example:\n\n ```python\n beaker.job.logs(job, follow=True)\n ```\n\n- Create and process [**Queues**](https://beaker-docs.apps.allenai.org/concept/queues.html) with `beaker.queue.*` methods. For example:\n\n ```python\n beaker.queue.create(\"my-work-queue\", batch_size=4)\n ```\n\nIf 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).\n\n### Example workflow\n\nLaunch and follow an experiment like [beaker-gantry](https://github.com/allenai/beaker-gantry) does:\n\n```python\nimport time\nfrom beaker import Beaker, BeakerExperimentSpec, BeakerJobPriority\n\n\nwith Beaker.from_env() as beaker:\n # Build experiment spec...\n spec = BeakerExperimentSpec.new(\n description=\"beaker-py test run\",\n beaker_image=\"petew/hello-world\",\n priority=BeakerJobPriority.low,\n preemptible=True,\n )\n\n # Create experiment workload...\n workload = beaker.experiment.create(spec=spec)\n\n # Wait for job to be created...\n while (job := beaker.workload.get_latest_job(workload)) is None:\n print(\"waiting for job to start...\")\n time.sleep(1.0)\n\n # Follow logs...\n print(\"Job logs:\")\n for job_log in beaker.job.logs(job, follow=True):\n print(job_log.message.decode())\n```\n\nSee the [integration tests](https://github.com/allenai/beaker/tree/main/bindings/python/src/integration_tests) for more examples.\n\n## Development\n\nAfter [installing from source](#installing-from-source), you can run checks and tests locally with:\n\n```bash\nmake checks\n```\n\n### Releases\n\nAt the moment releases need to be published manually by following these steps:\n\n1. Ensure you've authenticated with [PyPI](https://pypi.org/) through a `~/.pypirc` file and have write permissions to the [beaker-py project](https://pypi.org/project/beaker-py/).\n2. Ensure the target release version defined in `src/beaker/version.py` is correct, or change the version on the fly by adding the `Make` argument `BEAKER_PY_VERSION=X.X.X` to the command in the next step.\n3. Ensure the CHANGELOG.md has a section at the top for the new release (`## vX.X.X - %Y-%m-%d`).\n4. Run `make publish` for a stable release or `make publish-nightly` for a nightly pre-release.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python Beaker client",
"version": "2.4.7",
"project_urls": {
"Changelog": "https://github.com/allenai/beaker/blob/main/bindings/python/CHANGELOG.md",
"Documentation": "https://beaker-py-docs.allen.ai",
"Homepage": "https://github.com/allenai/beaker",
"Repository": "https://github.com/allenai/beaker"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d9a4f8bd11c85ad607325dd4a0ef30ec93984771c61fe24e903630729db6b50b",
"md5": "c031178b7f5ee5cb4552b244b2c37eb5",
"sha256": "cf4b7894facd39e84c43a95f42cb4963d3db0ceb002de9154a6eef285eb4604e"
},
"downloads": -1,
"filename": "beaker_py-2.4.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c031178b7f5ee5cb4552b244b2c37eb5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 99316,
"upload_time": "2025-07-21T21:18:51",
"upload_time_iso_8601": "2025-07-21T21:18:51.915417Z",
"url": "https://files.pythonhosted.org/packages/d9/a4/f8bd11c85ad607325dd4a0ef30ec93984771c61fe24e903630729db6b50b/beaker_py-2.4.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "57ba36b1c114dbb911902e4707908233a1fc62befbb94ff6ca8eb471dbc78a02",
"md5": "0e61aa95335c82c8b3bbb1de01c09403",
"sha256": "7dde7adc46418b5b1c27721ed4f0b5ec836cbc6f058987d429c36f7e48d74755"
},
"downloads": -1,
"filename": "beaker_py-2.4.7.tar.gz",
"has_sig": false,
"md5_digest": "0e61aa95335c82c8b3bbb1de01c09403",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 88328,
"upload_time": "2025-07-21T21:18:53",
"upload_time_iso_8601": "2025-07-21T21:18:53.627101Z",
"url": "https://files.pythonhosted.org/packages/57/ba/36b1c114dbb911902e4707908233a1fc62befbb94ff6ca8eb471dbc78a02/beaker_py-2.4.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 21:18:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "allenai",
"github_project": "beaker",
"github_not_found": true,
"lcname": "beaker-py"
}
