# Bacalhau Python SDK :snake:
This is the official Python SDK for Bacalhau, named `bacalhau-sdk`.
It is a **high-level** SDK that ships the client-side logic (e.g. signing requests) needed to query the endpoints.
Please take a look at [the examples](./examples) for snippets to create, list and inspect jobs.
Under the hood, this SDK uses [`bacalhau-apiclient`](../clients) (autogenerated via [Swagger](https://swagger.io/tools/swagger-codegen/)/OpenAPI) to interact with the API.
Please make sure to use this SDK library in your Python projects, instead of the lower level `bacalhau-apiclient`.
The latter is listed as a dependency of this SDK and will be installed automatically when you follow the installation instructions below.
## Features
- List, create and inspect Bacalhau jobs using Python objects :balloon:
- Use the production network, or set the following environment variables to target any Bacalhau network out there:
- `BACALHAU_API_HOST`
- `BACALHAU_API_PORT`
- Generate a key pair used to sign requests stored in the path specified by the `BACALHAU_DIR` env var (default: `~/.bacalhau`)
## Install
### From PyPi:
```console
$ pip install bacalhau-sdk
```
### From source:
Clone the public repository:
```console
$ git clone https://github.com/bacalhau-project/bacalhau/
```
Once you have a copy of the source, you can install it with:
```console
$ cd python/
$ pip install .
```
## Initialize
Likewise the Bacalhau CLI, this SDK uses a key pair to be stored in `BACALHAU_DIR` used for signing requests.
If a key pair is not found there, it will create one for you.
## Example Use
Let's submit a Hello World job and then fetch its output data's CID.
We start by importing this sdk, namely `bacalhau_sdk`, used to create and submit a job create request.
Then we import `bacalhau_apiclient` (installed automatically with this sdk), it provides various object models that compose a job create request.
These are used to populate a simple python dictionary that will be passed over to the `submit` util method.
```python
import pprint
from bacalhau_apiclient.models.job import Job
from bacalhau_apiclient.models.task import Task
from bacalhau_apiclient.models.all_of_execution_published_result import SpecConfig
from bacalhau_apiclient.models.api_put_job_request import (
ApiPutJobRequest as PutJobRequest,
)
from bacalhau_sdk.jobs import Jobs
task = Task(
name="My Main task",
engine=SpecConfig(
type="docker",
params=dict(
Image="ubuntu:latest",
Entrypoint=["/bin/bash"],
Parameters=["-c", "echo Hello World"],
),
),
publisher=SpecConfig(),
)
job = Job(name="A Simple Docker Job", type="batch", count=1, tasks=[task])
put_job_request = PutJobRequest(job=job)
jobs = Jobs()
put_job_response = jobs.put(put_job_request)
pprint.pprint(put_job_response)
```
The script above prints the following object, the `job.metadata.id` value is our newly created job id!
```python
{
'job': {
'constraints': [],
'count': 1,
'create_time': 1719930417160015000,
'id': 'j-df836f6a-6920-44e4-9683-27f6ec1921e2',
'labels': {},
'meta': {'bacalhau.org/requester.id': 'node-0'},
'modify_time': 1719930417160015000,
'name': 'A Simple Docker Job',
'namespace': 'default',
'priority': 0,
'revision': 1,
'state': {'message': None, 'state_type': 'Pending'},
'tasks': [{'engine': {'params': {'Entrypoint': ['/bin/bash'],
'Image': 'ubuntu:latest',
'Parameters': ['-c',
'echo Hello World']},
'type': 'docker'},
'env': None,
'input_sources': None,
'meta': None,
'name': 'My Main task',
'network': {'domains': None, 'type': 'None'},
'publisher': {'params': None, 'type': ''},
'resources': {'cpu': None,
'disk': None,
'gpu': None,
'memory': None},
'result_paths': None,
'timeouts': {'execution_timeout': None,
'queue_timeout': None,
'total_timeout': 1800}}],
'type': 'batch',
'version': 0
}
}
```
We can then use the `results` method to fetch, among other fields, the output data's CID.
```python
from bacalhau_sdk.jobs import Jobs
jobs = Jobs()
print(results(jobs.results(job_id="710a0bc2-81d1-4025-8f80-5327ca3ce170")))
```
The line above prints the following dictionary:
```python
{'results': [{'data': {'cid': 'QmYEqqNDdDrsRhPRShKHzsnZwBq3F59Ti3kQmv9En4i5Sw',
'metadata': None,
'name': 'job-710a0bc2-81d1-4025-8f80-5327ca3ce170-shard-0-host-QmYgxZiySj3MRkwLSL4X2MF5F9f2PMhAE3LV49XkfNL1o3',
'path': None,
'source_path': None,
'storage_source': 'IPFS',
'url': None},
'node_id': 'QmYgxZiySj3MRkwLSL4X2MF5F9f2PMhAE3LV49XkfNL1o3',
'shard_index': None}]}
```
Congrats, that was a good start! 🎈
Please find more code snippets in [the examples folder](./examples) (more examples published in the near future).
## Devstack
You can set the environment variables `BACALHAU_API_HOST` and `BACALHAU_API_PORT` to point this SDK to your Bacalhau API (e.g. [local devstack](../docs/running_locally.md)).
## Developers guide
We use Poetry to manage this package, take a look at [their official docs](https://python-poetry.org/docs/) to install it.
Note, all targets in the Makefile use poetry as well!
To develop this SDK locally, create a dedicated poetry virtual environment and install the root package (i.e. `bacalhau_sdk`) and its dependencies:
```shell
$ poetry install --no-interaction --with test,dev -vvv
Creating virtualenv bacalhau-sdk-9mIcLX8U-py3.9 in /Users/enricorotundo/Library/Caches/pypoetry/virtualenvs
Using virtualenv: /Users/enricorotundo/Library/Caches/pypoetry/virtualenvs/bacalhau-sdk-9mIcLX8U-py3.9
Installing dependencies from lock file
...
```
Note the line above installs the root package (i.e. `bacalhau_sdk`) in editable mode, that is, any change to its source code is reflected immediately without the need for re-packaging and re-installing it. Easy peasy!
Then install the pre-commit hooks and test it:
```shell
$ make install-pre-commit
$ make pre-commit
```
Raw data
{
"_id": null,
"home_page": "https://github.com/bacalhau-project/bacalhau/",
"name": "bacalhau-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.8.1",
"maintainer_email": null,
"keywords": "bacalhau, Filecoin, IPFS, cod, compute over data, verifiable computation",
"author": "Enrico Rotundo",
"author_email": "team@bacalhau.org",
"download_url": "https://files.pythonhosted.org/packages/79/70/7113d53299399a922824d9d4855935f1f1e023558a6bcd4f82343edce825/bacalhau_sdk-1.4.1.tar.gz",
"platform": null,
"description": "# Bacalhau Python SDK :snake:\n\nThis is the official Python SDK for Bacalhau, named `bacalhau-sdk`.\nIt is a **high-level** SDK that ships the client-side logic (e.g. signing requests) needed to query the endpoints.\nPlease take a look at [the examples](./examples) for snippets to create, list and inspect jobs.\nUnder the hood, this SDK uses [`bacalhau-apiclient`](../clients) (autogenerated via [Swagger](https://swagger.io/tools/swagger-codegen/)/OpenAPI) to interact with the API.\n\nPlease make sure to use this SDK library in your Python projects, instead of the lower level `bacalhau-apiclient`.\nThe latter is listed as a dependency of this SDK and will be installed automatically when you follow the installation instructions below.\n\n## Features\n\n- List, create and inspect Bacalhau jobs using Python objects :balloon:\n- Use the production network, or set the following environment variables to target any Bacalhau network out there:\n - `BACALHAU_API_HOST`\n - `BACALHAU_API_PORT`\n- Generate a key pair used to sign requests stored in the path specified by the `BACALHAU_DIR` env var (default: `~/.bacalhau`)\n\n## Install\n\n### From PyPi:\n\n```console\n$ pip install bacalhau-sdk\n```\n\n### From source:\n\nClone the public repository:\n\n```console\n$ git clone https://github.com/bacalhau-project/bacalhau/\n```\n\nOnce you have a copy of the source, you can install it with:\n\n```console\n$ cd python/\n$ pip install .\n```\n\n## Initialize\n\nLikewise the Bacalhau CLI, this SDK uses a key pair to be stored in `BACALHAU_DIR` used for signing requests.\nIf a key pair is not found there, it will create one for you.\n\n## Example Use\n\nLet's submit a Hello World job and then fetch its output data's CID.\nWe start by importing this sdk, namely `bacalhau_sdk`, used to create and submit a job create request.\nThen we import `bacalhau_apiclient` (installed automatically with this sdk), it provides various object models that compose a job create request.\nThese are used to populate a simple python dictionary that will be passed over to the `submit` util method.\n\n```python\nimport pprint\n\nfrom bacalhau_apiclient.models.job import Job\nfrom bacalhau_apiclient.models.task import Task\nfrom bacalhau_apiclient.models.all_of_execution_published_result import SpecConfig\nfrom bacalhau_apiclient.models.api_put_job_request import (\n ApiPutJobRequest as PutJobRequest,\n)\nfrom bacalhau_sdk.jobs import Jobs\n\ntask = Task(\n name=\"My Main task\",\n engine=SpecConfig(\n type=\"docker\",\n params=dict(\n Image=\"ubuntu:latest\",\n Entrypoint=[\"/bin/bash\"],\n Parameters=[\"-c\", \"echo Hello World\"],\n ),\n ),\n publisher=SpecConfig(),\n)\n\njob = Job(name=\"A Simple Docker Job\", type=\"batch\", count=1, tasks=[task])\nput_job_request = PutJobRequest(job=job)\njobs = Jobs()\n\nput_job_response = jobs.put(put_job_request)\npprint.pprint(put_job_response)\n```\n\nThe script above prints the following object, the `job.metadata.id` value is our newly created job id!\n\n```python\n{ \n 'job': { \n 'constraints': [],\n 'count': 1,\n 'create_time': 1719930417160015000,\n 'id': 'j-df836f6a-6920-44e4-9683-27f6ec1921e2',\n 'labels': {},\n 'meta': {'bacalhau.org/requester.id': 'node-0'},\n 'modify_time': 1719930417160015000,\n 'name': 'A Simple Docker Job',\n 'namespace': 'default',\n 'priority': 0,\n 'revision': 1,\n 'state': {'message': None, 'state_type': 'Pending'},\n 'tasks': [{'engine': {'params': {'Entrypoint': ['/bin/bash'],\n 'Image': 'ubuntu:latest',\n 'Parameters': ['-c',\n 'echo Hello World']},\n 'type': 'docker'},\n 'env': None,\n 'input_sources': None,\n 'meta': None,\n 'name': 'My Main task',\n 'network': {'domains': None, 'type': 'None'},\n 'publisher': {'params': None, 'type': ''},\n 'resources': {'cpu': None,\n 'disk': None,\n 'gpu': None,\n 'memory': None},\n 'result_paths': None,\n 'timeouts': {'execution_timeout': None,\n 'queue_timeout': None,\n 'total_timeout': 1800}}],\n 'type': 'batch',\n 'version': 0\n }\n}\n```\n\nWe can then use the `results` method to fetch, among other fields, the output data's CID.\n\n```python\nfrom bacalhau_sdk.jobs import Jobs\n\njobs = Jobs()\nprint(results(jobs.results(job_id=\"710a0bc2-81d1-4025-8f80-5327ca3ce170\")))\n```\n\nThe line above prints the following dictionary:\n\n```python\n{'results': [{'data': {'cid': 'QmYEqqNDdDrsRhPRShKHzsnZwBq3F59Ti3kQmv9En4i5Sw',\n 'metadata': None,\n 'name': 'job-710a0bc2-81d1-4025-8f80-5327ca3ce170-shard-0-host-QmYgxZiySj3MRkwLSL4X2MF5F9f2PMhAE3LV49XkfNL1o3',\n 'path': None,\n 'source_path': None,\n 'storage_source': 'IPFS',\n 'url': None},\n 'node_id': 'QmYgxZiySj3MRkwLSL4X2MF5F9f2PMhAE3LV49XkfNL1o3',\n 'shard_index': None}]}\n```\n\nCongrats, that was a good start! \ud83c\udf88\nPlease find more code snippets in [the examples folder](./examples) (more examples published in the near future).\n\n## Devstack\n\nYou can set the environment variables `BACALHAU_API_HOST` and `BACALHAU_API_PORT` to point this SDK to your Bacalhau API (e.g. [local devstack](../docs/running_locally.md)).\n\n## Developers guide\n\nWe use Poetry to manage this package, take a look at [their official docs](https://python-poetry.org/docs/) to install it.\nNote, all targets in the Makefile use poetry as well!\n\nTo develop this SDK locally, create a dedicated poetry virtual environment and install the root package (i.e. `bacalhau_sdk`) and its dependencies:\n\n```shell\n$ poetry install --no-interaction --with test,dev -vvv\nCreating virtualenv bacalhau-sdk-9mIcLX8U-py3.9 in /Users/enricorotundo/Library/Caches/pypoetry/virtualenvs\nUsing virtualenv: /Users/enricorotundo/Library/Caches/pypoetry/virtualenvs/bacalhau-sdk-9mIcLX8U-py3.9\nInstalling dependencies from lock file\n...\n```\n\nNote the line above installs the root package (i.e. `bacalhau_sdk`) in editable mode, that is, any change to its source code is reflected immediately without the need for re-packaging and re-installing it. Easy peasy!\n\nThen install the pre-commit hooks and test it:\n\n```shell\n$ make install-pre-commit\n\n$ make pre-commit\n```\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Compute over Data framework for public, transparent, and optionally verifiable computation using IPFS & Filecoin.",
"version": "1.4.1",
"project_urls": {
"Bug Tracker": "https://github.com/bacalhau-project/bacalhau/issues",
"Documentation": "https://docs.bacalhau.org/",
"Homepage": "https://github.com/bacalhau-project/bacalhau/",
"Repository": "https://github.com/bacalhau-project/bacalhau/"
},
"split_keywords": [
"bacalhau",
" filecoin",
" ipfs",
" cod",
" compute over data",
" verifiable computation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f0a8d3560837d82456e3a1693235b8d68b4bd73502cc5702e8a734217ddeeb6c",
"md5": "3d745a99b536054a1b03641865d32707",
"sha256": "db6dd24d1b53dc522e9bb064d009dcb48bab573f2bfd67f725683b8074040fc0"
},
"downloads": -1,
"filename": "bacalhau_sdk-1.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d745a99b536054a1b03641865d32707",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.8.1",
"size": 7769,
"upload_time": "2024-07-04T13:37:56",
"upload_time_iso_8601": "2024-07-04T13:37:56.855500Z",
"url": "https://files.pythonhosted.org/packages/f0/a8/d3560837d82456e3a1693235b8d68b4bd73502cc5702e8a734217ddeeb6c/bacalhau_sdk-1.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "79707113d53299399a922824d9d4855935f1f1e023558a6bcd4f82343edce825",
"md5": "30ba33c43522e6e455d56f80d1027185",
"sha256": "7e5a9711f8a2ed98847684d29fb1fc365f4a97b7050271781557615488534aef"
},
"downloads": -1,
"filename": "bacalhau_sdk-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "30ba33c43522e6e455d56f80d1027185",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.8.1",
"size": 10558,
"upload_time": "2024-07-04T13:37:58",
"upload_time_iso_8601": "2024-07-04T13:37:58.536967Z",
"url": "https://files.pythonhosted.org/packages/79/70/7113d53299399a922824d9d4855935f1f1e023558a6bcd4f82343edce825/bacalhau_sdk-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-04 13:37:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bacalhau-project",
"github_project": "bacalhau",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"circle": true,
"lcname": "bacalhau-sdk"
}