| Name | orchestra-sdk JSON |
| Version |
0.0.22
JSON |
| download |
| home_page | None |
| Summary | Orchestra SDK for updating self-hosted Tasks. |
| upload_time | 2024-11-15 16:19:22 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8.0 |
| license | Copyright 2024 Orchestra Technologies Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
python
logging
data
orchestration
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Orchestra Python SDK
This is a lightweight SDK that allows [Orchestra](https://www.getorchestra.io/) to interact with self-hosted applications (Tasks).
The basic premise is for your self-hosted Task to send back status updates and logs to Orchestra. This is done via HTTP requests. The Task must be started by Orchestra.
## Installation
```bash
pip install orchestra-sdk
```
You initialise the package by creating an instance of the `OrchestraSDK` class. It requires the API key that will connect with Orchestra - this can be found in [your settings page](https://app.getorchestra.io/settings). Orchestra will attempt to automatically set the other environment variables when the Task is triggered:
- `ORCHESTRA_WEBHOOK_URL`: The URL to send status updates to
- `ORCHESTRA_TASK_RUN_ID`: The UUID of the Task being executed
If these are not in your environment, you can set them manually after initialising the `OrchestraSDK` class.
There are also optional configuration values:
- `send_logs`: send the contents of a log file to Orchestra associated with the task (default = False)
- `log_file_path`: the path to the log file to send to Orchestra (default = "orchestra.log")
```python
from orchestra_sdk.orchestra import OrchestraSDK
orchestra = OrchestraSDK(api_key="your_api_key")
# If not set in the environment:
orchestra.task_run_id = "your_task_run_id"
orchestra.webhook_url = "your_webhook_url"
```
Orchestra recommends retrieving the API key from some secret store that you have configured. If that is not possible, you can set the API key as an environment variable and read that value in your code.
If you are using the AWS Lambda Task type from Orchestra, you can use the following helper function to ensure the correct configuration has been applied:
```python
from orchestra_sdk.orchestra import OrchestraSDK
orchestra = OrchestraSDK(api_key="your_api_key")
def handler(event, context):
orchestra.configure_aws_lambda_event(event)
# Your code here
```
## Task decorator
The decorator will handle updating the Task in Orchestra automatically. It will send a `RUNNING` status update when the function is called, and then send a `SUCCEEDED` or `FAILED` status update when the function finishes.
```python
from orchestra_sdk.orchestra import OrchestraSDK
orchestra = OrchestraSDK(api_key="your_api_key")
@orchestra.run()
def my_function(arg1, arg2=1):
print("Running complex process")
```
1. The decorator will firstly read and validate the environment variables
1. It will send a `RUNNING` status update to Orchestra
1. Your function will then run
1. If an exception is raised, the decorator will send a `FAILED` status update to Orchestra
1. If the function finishes without an error being raised, regardless of the return value, the decorator will send a `SUCCEEDED` status update to Orchestra
1. If `send_logs` is enabled, the contents of the logs will also be sent.
## Updating Tasks manually
For additional control over when to update the status of the Task, or for sending messages to Orchestra, you can use the `update_task` method of the `OrchestraSDK` class.
```python
from orchestra_sdk.enum import TaskRunStatus
from orchestra_sdk.orchestra import OrchestraSDK
orchestra = OrchestraSDK(api_key="your_api_key")
def my_function(arg1, arg2=1):
print("Start my complex process")
orchestra.update_task(status=TaskRunStatus.RUNNING, message="Starting process.")
print("Running complex process")
fn_result = complex_process()
if fn_result == 0:
orchestra.update_task(status=TaskRunStatus.SUCCEEDED)
else:
orchestra.update_task(status=TaskRunStatus.FAILED, message="Process failed")
```
- If the function fails or throws an exception, Orchestra might not register that the Task has failed, which could have downstream consequences on your pipeline. Consider wrapping your function in a try/except block and calling `update_task` with `status=TaskRunStatus.FAILED` in the except block.
## Sending logs
To send logs associated to the Task, enable the `send_logs` flag when initialising the `OrchestraSDK` class. The logs will be sent to Orchestra when the Task finishes and the decorator is being used.
An example logging configuration is shown below:
```python
import logging
import sys
from orchestra_sdk.orchestra import OrchestraSDK
orchestra = OrchestraSDK(
api_key="your_api_key",
send_logs=True,
log_file="a.log"
)
def test_function():
# Setup logging configuration
logger = logging.getLogger()
logger.setLevel(logging.INFO)
# File handler
file_handler = logging.FileHandler(orchestra.log_file)
file_handler.setLevel(logging.INFO)
file_formatter = logging.Formatter(
"%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
file_handler.setFormatter(file_formatter)
# Console handler
console_handler = logging.StreamHandler(sys.stdout)
console_handler.setLevel(logging.INFO)
console_formatter = logging.Formatter(
"%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
console_handler.setFormatter(console_formatter)
# Adding handlers to the logger
logger.addHandler(file_handler)
logger.addHandler(console_handler)
logger.info("Hello, World!")
```
Raw data
{
"_id": null,
"home_page": null,
"name": "orchestra-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": null,
"keywords": "python, logging, data, orchestration",
"author": null,
"author_email": "Orchestra Technologies <support@getorchestra.io>",
"download_url": "https://files.pythonhosted.org/packages/0c/64/900ceb172ef6464cf49717b9c44978e30e32dfba3f872af2a19fd6431578/orchestra_sdk-0.0.22.tar.gz",
"platform": null,
"description": "# Orchestra Python SDK\n\n\n\nThis is a lightweight SDK that allows [Orchestra](https://www.getorchestra.io/) to interact with self-hosted applications (Tasks).\n\nThe basic premise is for your self-hosted Task to send back status updates and logs to Orchestra. This is done via HTTP requests. The Task must be started by Orchestra.\n\n## Installation\n\n```bash\npip install orchestra-sdk\n```\n\nYou initialise the package by creating an instance of the `OrchestraSDK` class. It requires the API key that will connect with Orchestra - this can be found in [your settings page](https://app.getorchestra.io/settings). Orchestra will attempt to automatically set the other environment variables when the Task is triggered:\n\n- `ORCHESTRA_WEBHOOK_URL`: The URL to send status updates to\n- `ORCHESTRA_TASK_RUN_ID`: The UUID of the Task being executed\n\nIf these are not in your environment, you can set them manually after initialising the `OrchestraSDK` class.\n\nThere are also optional configuration values:\n\n- `send_logs`: send the contents of a log file to Orchestra associated with the task (default = False)\n- `log_file_path`: the path to the log file to send to Orchestra (default = \"orchestra.log\")\n\n```python\nfrom orchestra_sdk.orchestra import OrchestraSDK\n\norchestra = OrchestraSDK(api_key=\"your_api_key\")\n\n# If not set in the environment:\norchestra.task_run_id = \"your_task_run_id\"\norchestra.webhook_url = \"your_webhook_url\"\n```\n\nOrchestra recommends retrieving the API key from some secret store that you have configured. If that is not possible, you can set the API key as an environment variable and read that value in your code.\n\nIf you are using the AWS Lambda Task type from Orchestra, you can use the following helper function to ensure the correct configuration has been applied:\n\n```python\nfrom orchestra_sdk.orchestra import OrchestraSDK\n\norchestra = OrchestraSDK(api_key=\"your_api_key\")\n\ndef handler(event, context):\n orchestra.configure_aws_lambda_event(event)\n # Your code here\n```\n\n## Task decorator\n\nThe decorator will handle updating the Task in Orchestra automatically. It will send a `RUNNING` status update when the function is called, and then send a `SUCCEEDED` or `FAILED` status update when the function finishes.\n\n```python\nfrom orchestra_sdk.orchestra import OrchestraSDK\n\norchestra = OrchestraSDK(api_key=\"your_api_key\")\n\n@orchestra.run()\ndef my_function(arg1, arg2=1):\n print(\"Running complex process\")\n```\n\n1. The decorator will firstly read and validate the environment variables\n1. It will send a `RUNNING` status update to Orchestra\n1. Your function will then run\n1. If an exception is raised, the decorator will send a `FAILED` status update to Orchestra\n1. If the function finishes without an error being raised, regardless of the return value, the decorator will send a `SUCCEEDED` status update to Orchestra\n1. If `send_logs` is enabled, the contents of the logs will also be sent.\n\n## Updating Tasks manually\n\nFor additional control over when to update the status of the Task, or for sending messages to Orchestra, you can use the `update_task` method of the `OrchestraSDK` class.\n\n```python\nfrom orchestra_sdk.enum import TaskRunStatus\nfrom orchestra_sdk.orchestra import OrchestraSDK\n\norchestra = OrchestraSDK(api_key=\"your_api_key\")\n\ndef my_function(arg1, arg2=1):\n print(\"Start my complex process\")\n orchestra.update_task(status=TaskRunStatus.RUNNING, message=\"Starting process.\")\n\n print(\"Running complex process\")\n\n fn_result = complex_process()\n\n if fn_result == 0:\n orchestra.update_task(status=TaskRunStatus.SUCCEEDED)\n else:\n orchestra.update_task(status=TaskRunStatus.FAILED, message=\"Process failed\")\n```\n\n- If the function fails or throws an exception, Orchestra might not register that the Task has failed, which could have downstream consequences on your pipeline. Consider wrapping your function in a try/except block and calling `update_task` with `status=TaskRunStatus.FAILED` in the except block.\n\n## Sending logs\n\nTo send logs associated to the Task, enable the `send_logs` flag when initialising the `OrchestraSDK` class. The logs will be sent to Orchestra when the Task finishes and the decorator is being used.\n\nAn example logging configuration is shown below:\n\n```python\nimport logging\nimport sys\n\nfrom orchestra_sdk.orchestra import OrchestraSDK\n\norchestra = OrchestraSDK(\n api_key=\"your_api_key\",\n send_logs=True,\n log_file=\"a.log\"\n)\n\ndef test_function():\n # Setup logging configuration\n logger = logging.getLogger()\n logger.setLevel(logging.INFO)\n\n # File handler\n file_handler = logging.FileHandler(orchestra.log_file)\n file_handler.setLevel(logging.INFO)\n file_formatter = logging.Formatter(\n \"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n )\n file_handler.setFormatter(file_formatter)\n\n # Console handler\n console_handler = logging.StreamHandler(sys.stdout)\n console_handler.setLevel(logging.INFO)\n console_formatter = logging.Formatter(\n \"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n )\n console_handler.setFormatter(console_formatter)\n\n # Adding handlers to the logger\n logger.addHandler(file_handler)\n logger.addHandler(console_handler)\n\n logger.info(\"Hello, World!\")\n```\n",
"bugtrack_url": null,
"license": "Copyright 2024 Orchestra Technologies Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \u201cSoftware\u201d), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \u201cAS IS\u201d, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Orchestra SDK for updating self-hosted Tasks.",
"version": "0.0.22",
"project_urls": null,
"split_keywords": [
"python",
" logging",
" data",
" orchestration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "df56930c231d1617ce6f25d45cff788f41da5ca5503c17ae6ca239e2ec1b5652",
"md5": "2e5d7a2ce201143096cc4a7eb8e308c3",
"sha256": "f3f704725b53edcaaf3783ff088c53caa6a542983b5724e1eb9e105ef07674f2"
},
"downloads": -1,
"filename": "orchestra_sdk-0.0.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e5d7a2ce201143096cc4a7eb8e308c3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 8750,
"upload_time": "2024-11-15T16:19:21",
"upload_time_iso_8601": "2024-11-15T16:19:21.110031Z",
"url": "https://files.pythonhosted.org/packages/df/56/930c231d1617ce6f25d45cff788f41da5ca5503c17ae6ca239e2ec1b5652/orchestra_sdk-0.0.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0c64900ceb172ef6464cf49717b9c44978e30e32dfba3f872af2a19fd6431578",
"md5": "4ace709944d1b44810e13916ae632cce",
"sha256": "99f6a5bbed5c6f51d0e5625bb634457e64baca8a5408a1ec80b6aca632e91b7d"
},
"downloads": -1,
"filename": "orchestra_sdk-0.0.22.tar.gz",
"has_sig": false,
"md5_digest": "4ace709944d1b44810e13916ae632cce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 10988,
"upload_time": "2024-11-15T16:19:22",
"upload_time_iso_8601": "2024-11-15T16:19:22.907103Z",
"url": "https://files.pythonhosted.org/packages/0c/64/900ceb172ef6464cf49717b9c44978e30e32dfba3f872af2a19fd6431578/orchestra_sdk-0.0.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 16:19:22",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "orchestra-sdk"
}
