# 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_sdk.api import submit
from bacalhau_sdk.config import get_client_id
from bacalhau_apiclient.models.storage_spec import StorageSpec
from bacalhau_apiclient.models.spec import Spec
from bacalhau_apiclient.models.job_spec_language import JobSpecLanguage
from bacalhau_apiclient.models.job_spec_docker import JobSpecDocker
from bacalhau_apiclient.models.publisher_spec import PublisherSpec
from bacalhau_apiclient.models.deal import Deal
data = dict(
APIVersion='V1beta1',
ClientID=get_client_id(),
Spec=Spec(
engine="Docker",
publisher_spec=PublisherSpec(type="IPFS"),
docker=JobSpecDocker(
image="ubuntu",
entrypoint=["echo", "Hello World!"],
),
language=JobSpecLanguage(job_context=None),
wasm=None,
resources=None,
timeout=1800,
outputs=[
StorageSpec(
storage_source="IPFS",
name="outputs",
path="/outputs",
)
],
deal=Deal(concurrency=1),
do_not_track=False,
),
)
pprint.pprint(submit(data))
```
The script above prints the following object, the `job.metadata.id` value is our newly created job id!
```python
{'job': {'api_version': 'V1beta1',
'metadata': {'client_id': 'bae9c3b2adfa04cc647a2457e8c0c605cef8ed93bdea5ac5f19f94219f722dfe',
'created_at': '2023-02-01T19:30:21.405209538Z',
'id': '710a0bc2-81d1-4025-8f80-5327ca3ce170'},
'spec': {'Deal': {'Concurrency': 1},
'Docker': {'Entrypoint': ['echo', 'Hello World!'],
'Image': 'ubuntu'},
'Engine': 'Docker',
'ExecutionPlan': {'ShardsTotal': 1},
'Language': {'JobContext': {}},
'Network': {'Type': 'None'},
'Publisher': 'IPFS',
'Resources': {'GPU': ''},
'Sharding': {'BatchSize': 1,
'GlobPatternBasePath': '/inputs'},
'Timeout': 1800,
'Wasm': {'EntryModule': {}},
'outputs': [{'Name': 'outputs',
'StorageSource': 'IPFS',
'path': '/outputs'}]},
'status': {'JobState': {},
'Requester': {'RequesterNodeID': 'QmdZQ7ZbhnvWY1J12XYKGHApJ6aufKyLNSvf8jZBrBaAVL',
'RequesterPublicKey': 'CAASpgIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDVRKPgCfY2fgfrkHkFjeWcqno+MDpmp8DgVaY672BqJl/dZFNU9lBg2P8Znh8OTtHPPBUBk566vU3KchjW7m3uK4OudXrYEfSfEPnCGmL6GuLiZjLf+eXGEez7qPaoYqo06gD8ROdD8VVse27E96LlrpD1xKshHhqQTxKoq1y6Rx4DpbkSt966BumovWJ70w+Nt9ZkPPydRCxVnyWS1khECFQxp5Ep3NbbKtxHNX5HeULzXN5q0EQO39UN6iBhiI34eZkH7PoAm3Vk5xns//FjTAvQw6wZUu8LwvZTaihs+upx2zZysq6CEBKoeNZqed9+Tf+qHow0P5pxmiu+or+DAgMBAAE='}}}}
```
We can then use the `results` method to fetch, among other fields, the output data's CID.
```python
from bacalhau_sdk.api import results
print(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": "",
"docs_url": null,
"requires_python": ">=3.8.1,<3.12",
"maintainer_email": "",
"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/73/ad/933c67302e1663cb7b56f7f7b06ddb217945a9286b198d260dce97da8164/bacalhau_sdk-1.2.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## 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\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_sdk.api import submit\nfrom bacalhau_sdk.config import get_client_id\nfrom bacalhau_apiclient.models.storage_spec import StorageSpec\nfrom bacalhau_apiclient.models.spec import Spec\nfrom bacalhau_apiclient.models.job_spec_language import JobSpecLanguage\nfrom bacalhau_apiclient.models.job_spec_docker import JobSpecDocker\nfrom bacalhau_apiclient.models.publisher_spec import PublisherSpec\nfrom bacalhau_apiclient.models.deal import Deal\n\n\ndata = dict(\n APIVersion='V1beta1',\n ClientID=get_client_id(),\n Spec=Spec(\n engine=\"Docker\",\n publisher_spec=PublisherSpec(type=\"IPFS\"),\n docker=JobSpecDocker(\n image=\"ubuntu\",\n entrypoint=[\"echo\", \"Hello World!\"],\n ),\n language=JobSpecLanguage(job_context=None),\n wasm=None,\n resources=None,\n timeout=1800,\n outputs=[\n StorageSpec(\n storage_source=\"IPFS\",\n name=\"outputs\",\n path=\"/outputs\",\n )\n ],\n deal=Deal(concurrency=1),\n do_not_track=False,\n ),\n)\n\npprint.pprint(submit(data))\n```\n\nThe script above prints the following object, the `job.metadata.id` value is our newly created job id!\n\n```python\n{'job': {'api_version': 'V1beta1',\n 'metadata': {'client_id': 'bae9c3b2adfa04cc647a2457e8c0c605cef8ed93bdea5ac5f19f94219f722dfe',\n 'created_at': '2023-02-01T19:30:21.405209538Z',\n 'id': '710a0bc2-81d1-4025-8f80-5327ca3ce170'},\n 'spec': {'Deal': {'Concurrency': 1},\n 'Docker': {'Entrypoint': ['echo', 'Hello World!'],\n 'Image': 'ubuntu'},\n 'Engine': 'Docker',\n 'ExecutionPlan': {'ShardsTotal': 1},\n 'Language': {'JobContext': {}},\n 'Network': {'Type': 'None'},\n 'Publisher': 'IPFS',\n 'Resources': {'GPU': ''},\n 'Sharding': {'BatchSize': 1,\n 'GlobPatternBasePath': '/inputs'},\n 'Timeout': 1800,\n 'Wasm': {'EntryModule': {}},\n 'outputs': [{'Name': 'outputs',\n 'StorageSource': 'IPFS',\n 'path': '/outputs'}]},\n 'status': {'JobState': {},\n 'Requester': {'RequesterNodeID': 'QmdZQ7ZbhnvWY1J12XYKGHApJ6aufKyLNSvf8jZBrBaAVL',\n 'RequesterPublicKey': 'CAASpgIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDVRKPgCfY2fgfrkHkFjeWcqno+MDpmp8DgVaY672BqJl/dZFNU9lBg2P8Znh8OTtHPPBUBk566vU3KchjW7m3uK4OudXrYEfSfEPnCGmL6GuLiZjLf+eXGEez7qPaoYqo06gD8ROdD8VVse27E96LlrpD1xKshHhqQTxKoq1y6Rx4DpbkSt966BumovWJ70w+Nt9ZkPPydRCxVnyWS1khECFQxp5Ep3NbbKtxHNX5HeULzXN5q0EQO39UN6iBhiI34eZkH7PoAm3Vk5xns//FjTAvQw6wZUu8LwvZTaihs+upx2zZysq6CEBKoeNZqed9+Tf+qHow0P5pxmiu+or+DAgMBAAE='}}}}\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.api import results\n\nprint(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",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Compute over Data framework for public, transparent, and optionally verifiable computation using IPFS & Filecoin.",
"version": "1.2.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": "3fc74e55f8a116f28ed90e596cda94956d7166c67deb1c236119ea0173c787e5",
"md5": "747353f54df7f31e66856df65da6558c",
"sha256": "c0a14ca243721281d7cff75774c29c340e8a60a2375f1974f0bbc37f482f9865"
},
"downloads": -1,
"filename": "bacalhau_sdk-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "747353f54df7f31e66856df65da6558c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<3.12",
"size": 12024,
"upload_time": "2024-01-30T21:49:41",
"upload_time_iso_8601": "2024-01-30T21:49:41.871879Z",
"url": "https://files.pythonhosted.org/packages/3f/c7/4e55f8a116f28ed90e596cda94956d7166c67deb1c236119ea0173c787e5/bacalhau_sdk-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "73ad933c67302e1663cb7b56f7f7b06ddb217945a9286b198d260dce97da8164",
"md5": "5e685845a4413404bdd61790446c08ae",
"sha256": "82be23d0959d437c0482afdd28bb2c68ca40c653765ce737a7bb7fdbc321b0f8"
},
"downloads": -1,
"filename": "bacalhau_sdk-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "5e685845a4413404bdd61790446c08ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<3.12",
"size": 15526,
"upload_time": "2024-01-30T21:49:43",
"upload_time_iso_8601": "2024-01-30T21:49:43.704581Z",
"url": "https://files.pythonhosted.org/packages/73/ad/933c67302e1663cb7b56f7f7b06ddb217945a9286b198d260dce97da8164/bacalhau_sdk-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-30 21:49:43",
"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"
}
JSON
