<p align="center">
<a href="https://github.com/Kicksaw-Consulting/trailwatch-python-sdk/actions/workflows/test.yml?query=event%3Apush+branch%3Amain" target="_blank">
<img src="https://github.com/Kicksaw-Consulting/trailwatch-python-sdk/actions/workflows/test.yml/badge.svg?branch=main&event=push" alt="Test">
</a>
<a href="https://pypi.org/project/trailwatch" target="_blank">
<img src="https://badge.fury.io/py/trailwatch.svg" alt="PyPI Package">
</a>
</p>
- [Installation](#installation)
- [Using TrailWatch](#using-trailwatch)
- [Decorator](#decorator)
- [Context Manager](#context-manager)
- [Connectors](#connectors)
- [AWS Connector](#aws-connector)
- [Salesforce Connector](#salesforce-connector)
- [Control Execution Status](#control-execution-status)
- [Partial Success](#partial-success)
- [Timeout](#timeout)
- [Send a File](#send-a-file)
- [Using With Other Decorators](#using-with-other-decorators)
# Installation
Install the SDK (supports AWS server):
```shell
pip install trailwatch
```
Install with Salesforce connector support:
```shell
pip install trailwatch[salesforce]
```
# Using TrailWatch
## Decorator
This is the recommended way to use TrailWatch. Decorator will automatically
assign job name and description based on the function name and docstring.
```python
from trailwatch import configure, watch
from trailwatch.connectors.aws import AwsConnectorFactory
configure(
project="My project name",
project_description="My project description",
environment="production",
connectors=[
AWSConnectorFactory(
url="https://<random>.execute-api.us-west-2.amazonaws.com",
api_key="my_key",
)
],
loggers=["__main__", "integration"],
)
@watch()
def handler(event, context):
# Do your thing
return
```
## Context Manager
Decorator uses this context manager internally. You can use the context manager
directly if you need more control over the execution or if you want to report a portion
of the execution (code block) as a separate job.
```python
from trailwatch import configure, TrailwatchContext
from trailwatch.connectors.aws import AwsConnectorFactory
configure(
project="My project name",
project_description="My project description",
environment="production",
connectors=[
AWSConnectorFactory(
url="https://<random>.execute-api.us-west-2.amazonaws.com",
api_key="my_key",
)
],
loggers=["__main__", "integration"],
)
def handler(event, context):
# Other code
with TrailwatchContext(
job="My Job",
job_description="My job description",
) as execution:
# Do your thing
return
# Other code
```
# Connectors
TwailWatch SDK works by attaching connectors to the execution context. Connectors
are responsible for tracking execution flow and for creating a record in their
respective systems. Connectors should be configured using the `configure` function
by provividing a list of connector factories in the `connectors` argument.
## AWS Connector
AWS connector is used to send execution information to AWS TrailWatch service deployed
in client's AWS account. To use AWS connector, you will need to deploy the TrailWatch
service first and then obtain URL and API key from the service.
```python
from trailwatch.connectors.aws import AwsConnectorFactory
configure(
# Other configuration parameters
connectors=[
AWSConnectorFactory(
url="url",
api_key="key",
)
],
)
```
## Salesforce Connector
Salesforce connector is used to send execution information to Kicksaw Integration App
deployed to client's Salesforce org. To use Salesforce connector, you will need to
deploy the Kicksaw Integration App first and then obtain credentials required to sign
in to the Salesforce org.
```python
from trailwatch.connectors.salesforce import SalesforceConnectorFactory
configure(
# Other configuration parameters
connectors=[
SalesforceConnectorFactory(
username="username",
password="password",
security_token="token",
domain="domain",
)
],
)
```
# Control Execution Status
## Partial Success
Raise a `PartialSuccess` exception to indicate that the execution was partially
successful. This exception is handled by TrailWatch to set execution status to `partial`
and will not be propagated to the caller.
```python
from trailwatch.exceptions import PartialSuccessError
@watch()
def handler(event, context):
# Do your thing
# You find out that only a subset of the work was successful
# Log information about the failure normally using the logger
raise PartialSuccessError
```
## Timeout
You can set timeout on a function to force it to stop after a certain amount of time.
This will raise `TimeoutError` and set the execution status to `timeout`.
> :warning: When using timeout inside AWS Lambda or Azure Function you will need to
> set the TrailWatch timeout to a value lower than the timeout you set on the cloud
> function. Otherwise, function can timeout before TrailWatch has a chance to set the
> status.
```python
@watch(timeout=10)
def handler(event, context):
# Do something that takes more than 10 seconds
...
```
Or using the context manager:
```python
def handler(event, context):
with TrailwatchContext(
job="My Job",
job_description="My job description",
timeout=10,
) as execution:
# Do something that takes more than 10 seconds
...
```
# Send a File
Some connectors support attaching (sending) files to be associated with the execution.
To send a file, use the `send_file` method on the `TrailwatchContext` object.
Three methods are available to send a file:
- `send_file` - send a file from the local filesystem
- `send_fileobj` - send a file-like object (stream or open file object)
- `send_file_content` - send a file content as a string or bytes
```python
def handler(event, context):
with TrailwatchContext(
job="My Job",
job_description="My job description",
) as execution:
execution.send_file("my_file.txt", "/path/to/my_file.txt")
execution.send_fileobj("my_file.txt", open("my_file.txt", "rb"))
execution.send_file_content("my_file.txt", "Hello from file!")
```
When using the decorator, you will need to add an extra argument
`trailwatch_execution_context` to the function you are decorating
to receive the `TrailwatchContext` object.
```python
from trailwatch import TrailwatchContext
@watch()
def handler(event, context, trailwatch_execution_context: TrailwatchContext):
trailwatch_execution_context.send_file("my_file.txt", "/path/to/my_file.txt")
```
Connectors supporting sending files:
- AWS Connector
# Using With Other Decorators
When using TrailWatch with other decorators, make sure that TrailWatch decorator
is the innermost decorator. This is because TrailWatch decorator may inject
the context argument into the function and other decorators (like FastAPI) can
get confused by this argument.
```python
from fastapi import FastAPI, Path
from pydantic import BaseModel
app = FastAPI()
class Model(BaseModel):
name: str
@app.post("/my_endpoint/{resource_id}")
@watch()
def my_endpoint(
trailwatch_execution_context: TrailwatchContext
model: Model,
resource_id: str = Path(..., title="The ID of the resource to get"),
):
# Do your thing
return
```
Raw data
{
"_id": null,
"home_page": "https://www.kicksaw.com/",
"name": "trailwatch",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "George Bocharov",
"author_email": "george@kicksaw.com",
"download_url": "https://files.pythonhosted.org/packages/7d/fe/fd9c09981a661dd53d8005347aa55a6f1ad911f92a8f05d6bdef744ba4cb/trailwatch-1.0.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"https://github.com/Kicksaw-Consulting/trailwatch-python-sdk/actions/workflows/test.yml?query=event%3Apush+branch%3Amain\" target=\"_blank\">\n <img src=\"https://github.com/Kicksaw-Consulting/trailwatch-python-sdk/actions/workflows/test.yml/badge.svg?branch=main&event=push\" alt=\"Test\">\n </a>\n <a href=\"https://pypi.org/project/trailwatch\" target=\"_blank\">\n <img src=\"https://badge.fury.io/py/trailwatch.svg\" alt=\"PyPI Package\">\n </a>\n</p>\n\n- [Installation](#installation)\n- [Using TrailWatch](#using-trailwatch)\n - [Decorator](#decorator)\n - [Context Manager](#context-manager)\n- [Connectors](#connectors)\n - [AWS Connector](#aws-connector)\n - [Salesforce Connector](#salesforce-connector)\n- [Control Execution Status](#control-execution-status)\n - [Partial Success](#partial-success)\n - [Timeout](#timeout)\n- [Send a File](#send-a-file)\n- [Using With Other Decorators](#using-with-other-decorators)\n\n# Installation\n\nInstall the SDK (supports AWS server):\n\n```shell\npip install trailwatch\n```\n\nInstall with Salesforce connector support:\n\n```shell\npip install trailwatch[salesforce]\n```\n\n# Using TrailWatch\n\n## Decorator\n\nThis is the recommended way to use TrailWatch. Decorator will automatically\nassign job name and description based on the function name and docstring.\n\n```python\nfrom trailwatch import configure, watch\nfrom trailwatch.connectors.aws import AwsConnectorFactory\n\nconfigure(\n project=\"My project name\",\n project_description=\"My project description\",\n environment=\"production\",\n connectors=[\n AWSConnectorFactory(\n url=\"https://<random>.execute-api.us-west-2.amazonaws.com\",\n api_key=\"my_key\",\n )\n ],\n loggers=[\"__main__\", \"integration\"],\n)\n\n\n@watch()\ndef handler(event, context):\n # Do your thing\n return\n```\n\n## Context Manager\n\nDecorator uses this context manager internally. You can use the context manager\ndirectly if you need more control over the execution or if you want to report a portion\nof the execution (code block) as a separate job.\n\n```python\nfrom trailwatch import configure, TrailwatchContext\nfrom trailwatch.connectors.aws import AwsConnectorFactory\n\nconfigure(\n project=\"My project name\",\n project_description=\"My project description\",\n environment=\"production\",\n connectors=[\n AWSConnectorFactory(\n url=\"https://<random>.execute-api.us-west-2.amazonaws.com\",\n api_key=\"my_key\",\n )\n ],\n loggers=[\"__main__\", \"integration\"],\n)\n\n\ndef handler(event, context):\n # Other code\n with TrailwatchContext(\n job=\"My Job\",\n job_description=\"My job description\",\n ) as execution:\n # Do your thing\n return\n # Other code\n```\n\n# Connectors\n\nTwailWatch SDK works by attaching connectors to the execution context. Connectors\nare responsible for tracking execution flow and for creating a record in their\nrespective systems. Connectors should be configured using the `configure` function\nby provividing a list of connector factories in the `connectors` argument.\n\n## AWS Connector\n\nAWS connector is used to send execution information to AWS TrailWatch service deployed\nin client's AWS account. To use AWS connector, you will need to deploy the TrailWatch\nservice first and then obtain URL and API key from the service.\n\n```python\nfrom trailwatch.connectors.aws import AwsConnectorFactory\n\nconfigure(\n # Other configuration parameters\n connectors=[\n AWSConnectorFactory(\n url=\"url\",\n api_key=\"key\",\n )\n ],\n)\n```\n\n## Salesforce Connector\n\nSalesforce connector is used to send execution information to Kicksaw Integration App\ndeployed to client's Salesforce org. To use Salesforce connector, you will need to\ndeploy the Kicksaw Integration App first and then obtain credentials required to sign\nin to the Salesforce org.\n\n```python\nfrom trailwatch.connectors.salesforce import SalesforceConnectorFactory\n\nconfigure(\n # Other configuration parameters\n connectors=[\n SalesforceConnectorFactory(\n username=\"username\",\n password=\"password\",\n security_token=\"token\",\n domain=\"domain\",\n )\n ],\n)\n```\n\n# Control Execution Status\n\n## Partial Success\n\nRaise a `PartialSuccess` exception to indicate that the execution was partially\nsuccessful. This exception is handled by TrailWatch to set execution status to `partial`\nand will not be propagated to the caller.\n\n```python\nfrom trailwatch.exceptions import PartialSuccessError\n\n\n@watch()\ndef handler(event, context):\n # Do your thing\n # You find out that only a subset of the work was successful\n # Log information about the failure normally using the logger\n raise PartialSuccessError\n```\n\n## Timeout\n\nYou can set timeout on a function to force it to stop after a certain amount of time.\nThis will raise `TimeoutError` and set the execution status to `timeout`.\n\n> :warning: When using timeout inside AWS Lambda or Azure Function you will need to\n> set the TrailWatch timeout to a value lower than the timeout you set on the cloud\n> function. Otherwise, function can timeout before TrailWatch has a chance to set the\n> status.\n\n```python\n@watch(timeout=10)\ndef handler(event, context):\n # Do something that takes more than 10 seconds\n ...\n```\n\nOr using the context manager:\n\n```python\ndef handler(event, context):\n with TrailwatchContext(\n job=\"My Job\",\n job_description=\"My job description\",\n timeout=10,\n ) as execution:\n # Do something that takes more than 10 seconds\n ...\n```\n\n# Send a File\n\nSome connectors support attaching (sending) files to be associated with the execution.\nTo send a file, use the `send_file` method on the `TrailwatchContext` object.\nThree methods are available to send a file:\n\n- `send_file` - send a file from the local filesystem\n- `send_fileobj` - send a file-like object (stream or open file object)\n- `send_file_content` - send a file content as a string or bytes\n\n```python\ndef handler(event, context):\n with TrailwatchContext(\n job=\"My Job\",\n job_description=\"My job description\",\n ) as execution:\n execution.send_file(\"my_file.txt\", \"/path/to/my_file.txt\")\n execution.send_fileobj(\"my_file.txt\", open(\"my_file.txt\", \"rb\"))\n execution.send_file_content(\"my_file.txt\", \"Hello from file!\")\n```\n\nWhen using the decorator, you will need to add an extra argument\n`trailwatch_execution_context` to the function you are decorating\nto receive the `TrailwatchContext` object.\n\n```python\nfrom trailwatch import TrailwatchContext\n\n@watch()\ndef handler(event, context, trailwatch_execution_context: TrailwatchContext):\n trailwatch_execution_context.send_file(\"my_file.txt\", \"/path/to/my_file.txt\")\n```\n\nConnectors supporting sending files:\n\n- AWS Connector\n\n# Using With Other Decorators\n\nWhen using TrailWatch with other decorators, make sure that TrailWatch decorator\nis the innermost decorator. This is because TrailWatch decorator may inject\nthe context argument into the function and other decorators (like FastAPI) can\nget confused by this argument.\n\n```python\nfrom fastapi import FastAPI, Path\nfrom pydantic import BaseModel\n\napp = FastAPI()\n\n\nclass Model(BaseModel):\n name: str\n\n\n@app.post(\"/my_endpoint/{resource_id}\")\n@watch()\ndef my_endpoint(\n trailwatch_execution_context: TrailwatchContext\n model: Model,\n resource_id: str = Path(..., title=\"The ID of the resource to get\"),\n):\n # Do your thing\n return\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python SDK for TrailWatch by Kicksaw",
"version": "1.0.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "840a0296374665505b9a2955e7115c6aba9123075c43ebd11b115406ceea0f94",
"md5": "ef28489576bf22424d3d3f94ce6a7be0",
"sha256": "713f345f326531678cee1c18e3a338e365f16ac5c1a882b5aa0f450ccbe878af"
},
"downloads": -1,
"filename": "trailwatch-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ef28489576bf22424d3d3f94ce6a7be0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 20012,
"upload_time": "2023-04-24T18:20:39",
"upload_time_iso_8601": "2023-04-24T18:20:39.572066Z",
"url": "https://files.pythonhosted.org/packages/84/0a/0296374665505b9a2955e7115c6aba9123075c43ebd11b115406ceea0f94/trailwatch-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7dfefd9c09981a661dd53d8005347aa55a6f1ad911f92a8f05d6bdef744ba4cb",
"md5": "aecce886dbee7394eab35dc5a2e98f55",
"sha256": "208cd11e0f908c728d8168a34c16b81185973883af62238dc800b910cb1398d8"
},
"downloads": -1,
"filename": "trailwatch-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "aecce886dbee7394eab35dc5a2e98f55",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 18101,
"upload_time": "2023-04-24T18:20:41",
"upload_time_iso_8601": "2023-04-24T18:20:41.232093Z",
"url": "https://files.pythonhosted.org/packages/7d/fe/fd9c09981a661dd53d8005347aa55a6f1ad911f92a8f05d6bdef744ba4cb/trailwatch-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-24 18:20:41",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "trailwatch"
}
JSON