| Name | highlighter-sdk JSON |
| Version |
2.4.73
JSON |
| download |
| home_page | None |
| Summary | Package to interact with the Highlighter Perception System |
| upload_time | 2024-12-20 07:25:31 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <=3.12.5,>=3.10 |
| license | APACHE 2.0 |
| keywords |
enterprise
perception
system
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img width="640" src="https://highlighter-public.s3.ap-southeast-2.amazonaws.com/web/assets/Highlighter_Logo_Primary_Horizontal_RGB.png" alt="Highlighter logo">
</div>
<br />
<a href=“”></a>
<div align="center">
<a href="https://highlighter-docs.netlify.app/">📘 Documentation</a> |
<a href="#installation">🛠️ Installation</a> |
<a href="mailto:support@highlighter.ai"> 🤔 Reporting Issues</a>
</div>
<h1>Highlighter SDK</h1>
The Highlighter SDK Python library provides convenient access to the [Highlighter](https://highlighter.ai) API from applications written in Python. There is also a CLI to access the Highlighter API in your shell.
The library also provides other features. For example:
* Easy configuration for fast setup and use across multiple Highlighter accounts.
* Functions to help get datasets in and out of Highlighter
* Helpers for pagination.
# Installation
```console
pip install highlighter-sdk
```
# API Tokens, Environment Variables and Profiles
If you have just a single set of Highlighter credentials you can simply set
the appropriate environment variables.
```
export HL_WEB_GRAPHQL_ENDPOINT="https://<client-account>.highlighter.ai/graphql"
export HL_WEB_GRAPHQL_API_TOKEN="###"
# Only required if you have datasets stored outside Highlighter's managed
# aws s3 storage
export AWS_ACCESS_KEY_ID=###
export AWS_SECRET_ACCESS_KEY=###
export AWS_DEFAULT_REGION=###
```
If you have several Highlighter credentials we suggest you use the
**profiles** option. You can create a `~/.highlighter-profiles.yaml` via the
cli.
```console
hl config create --name my-profile --api-token ### --endpoint https://...
```
Other commands for managing your profiles can be seen with the `--help` flag,
If you're a *Maverick Renegade* you can manage the `~/.highlighter-profiles.yaml`
manually. Below is an example,
```yaml
# Example ~/.highlighter-profiles.yaml
my_profile:
endpoint_url: https://<client-account>.highlighter.ai/graphql
api_token: ###
# Only required if you have datasets stored outside Highlighter's managed
# aws s3 storage
cloud:
- type: aws-s3
aws_access_key_id: ###
aws_secret_access_key: ###
aws_default_region: ###
```
To use as a profile in the cli simply use,
```console
hl --profile <profile-name> <command>
```
In a script you can use,
```python
# in a script
from highlighter.client import HLClient
client = HLClient.from_profile("profile-name")
```
Additionally `HLClient` can be initialized using environment variables or
by passing credentials direcly
```python
from highlighter.client import HLClient
client = HLClient.get_client()
# or
api_token = "###"
endpoint_url = "https://...highligher.ai/graphql
client = HLCient.from_credential(api_token, endpoint_url)
```
Finally, if you are in the position where you want to write a specified profile's
credentials to an evnironment file such as `.env` or `.envrc` you can use
the `write` command. This will create or append to the specified file.
```console
hl --profile my-profile write .envrc
```
## Python API
Once you have a `HLClient` object you can use it perform queries or mutations. Here is a simple example.
```python
from highlighter.client import HLClient
from pydantic import BaseModel
client = HLClient.get_client()
# You don't always need to define your own BaseModels
# many common BaseModels are defined in highlighter.base_models
# this is simply for completeness
class ObjectClassType(BaseModel):
id: int
name: str
id = 1234 # add an object class id from you account
result = client.ObjectClass(
return_type=ObjectClassType,
id=id,
)
print(result)
```
Some queries may return arbitrarily many results. These queries are
paginated and are called `Connections` and the queries are named accordingly.
We have provided a `paginate` function to help with these `Connections`
```python
from highlighter.core import paginate
from highlighter.client import HLClient
from pydantic import BaseModel
client = HLClient.get_client()
uuids = [
"abc123-abc123-abc123-abc123",
"xyz456-xyz456-xyz456-xyz456",
]
# The following BaseModels are all defined in
# highlighter.base_models. They are simply here
# for completeness
class PageInfo(BaseModel):
hasNextPage: bool
endCursor: Optional[str]
class ObjectClass(BaseModel):
id: str
uuid: str
name: str
class ObjectClassTypeConnection(BaseModel):
pageInfo: PageInfo
nodes: List[ObjectClass]
generator = paginate(
client..objectClassConnection,
ObjectClassTypeConnection,
uuid=uuids,
)
for object_class in generator:
print(object_class)
```
## Datasets
Highlighter SDK provides a dataset representation that can populated
from several sources `{HighlighterWeb.Assessments | Local files {.hdf, records.json, coco.json} | S3Bucket}`.
Once populated the `Highlighter.Datasets` object contains 2 `Pandas.DataFrames`
(`data_files_df` and `annotations_df`) that you can manipulate as required. When you're
ready you can write to disk or upload to Highligher using one of the `Writer` classes
to dump your data to disk in a format that can be consumed by your downstream code.
If you need you can also roll-your-own `Writer` by implementing the `highlighter.datasets.interfaces.IWriter` interface.
## CLI Tab Completion
<table>
<tr>
<th>Console</th>
<td>
</td>
</tr>
<tr>
<th>Shell</th>
<td>
Add this to your <code>~/.bashrc</code>:<br>
<code>eval "$(_HL_COMPLETE=bash_source hl)"</code><br>
</td>
</tr>
<tr>
<th>ZSH</th>
<td>
Add this to your <code>~/.zshrc</code>:<br>
<code>eval "$(_HL_COMPLETE=zsh_source hl)"</code><br>
</td>
</tr>
<tr>
<th>Fish</th>
<td>
Add this to <code>~/.config/fish/completions/hl.fish</code>:<br>
<code>_HL_COMPLETE=fish_source hl | source</code>
</td>
</tr>
</table>
For more information, see the [Click documentation](https://click.palletsprojects.com/en/8.1.x/shell-completion/#enabling-completion)
## Documentation
See https://highlighter-docs.netlify.app/
Raw data
{
"_id": null,
"home_page": null,
"name": "highlighter-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.12.5,>=3.10",
"maintainer_email": null,
"keywords": "enterprise perception system",
"author": null,
"author_email": "Joshua Patterson <joshua.patterson@silverpond.com.au>, Jono Chang <jonathan.chang@silverpond.com.au>, Simon Hudson <simon.hudson@silverpond.com.au>",
"download_url": "https://files.pythonhosted.org/packages/92/09/42e991378a00f69ec64ce177030efa9bb81ef388b3dfcbaa616102f96fc9/highlighter_sdk-2.4.73.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img width=\"640\" src=\"https://highlighter-public.s3.ap-southeast-2.amazonaws.com/web/assets/Highlighter_Logo_Primary_Horizontal_RGB.png\" alt=\"Highlighter logo\">\n</div>\n\n<br />\n\n<a href=\u201c\u201d></a>\n<div align=\"center\">\n<a href=\"https://highlighter-docs.netlify.app/\">\ud83d\udcd8 Documentation</a> |\n<a href=\"#installation\">\ud83d\udee0\ufe0f Installation</a> |\n<a href=\"mailto:support@highlighter.ai\"> \ud83e\udd14 Reporting Issues</a> \n</div>\n\n<h1>Highlighter SDK</h1>\n\n\nThe Highlighter SDK Python library provides convenient access to the [Highlighter](https://highlighter.ai) API from applications written in Python. There is also a CLI to access the Highlighter API in your shell.\n\nThe library also provides other features. For example:\n\n* Easy configuration for fast setup and use across multiple Highlighter accounts.\n* Functions to help get datasets in and out of Highlighter\n* Helpers for pagination.\n\n\n# Installation\n\n```console\npip install highlighter-sdk\n```\n\n\n# API Tokens, Environment Variables and Profiles\n\nIf you have just a single set of Highlighter credentials you can simply set\nthe appropriate environment variables.\n\n```\nexport HL_WEB_GRAPHQL_ENDPOINT=\"https://<client-account>.highlighter.ai/graphql\"\nexport HL_WEB_GRAPHQL_API_TOKEN=\"###\"\n\n# Only required if you have datasets stored outside Highlighter's managed\n# aws s3 storage\nexport AWS_ACCESS_KEY_ID=###\nexport AWS_SECRET_ACCESS_KEY=###\nexport AWS_DEFAULT_REGION=###\n```\n\nIf you have several Highlighter credentials we suggest you use the\n**profiles** option. You can create a `~/.highlighter-profiles.yaml` via the\ncli.\n\n```console\nhl config create --name my-profile --api-token ### --endpoint https://...\n```\n\nOther commands for managing your profiles can be seen with the `--help` flag,\n\nIf you're a *Maverick Renegade* you can manage the `~/.highlighter-profiles.yaml`\nmanually. Below is an example,\n\n```yaml\n# Example ~/.highlighter-profiles.yaml\n\nmy_profile:\n endpoint_url: https://<client-account>.highlighter.ai/graphql\n api_token: ###\n\n # Only required if you have datasets stored outside Highlighter's managed\n # aws s3 storage\n cloud:\n - type: aws-s3\n aws_access_key_id: ###\n aws_secret_access_key: ###\n aws_default_region: ###\n```\n\nTo use as a profile in the cli simply use,\n\n```console\nhl --profile <profile-name> <command>\n```\n\nIn a script you can use,\n\n```python\n# in a script\nfrom highlighter.client import HLClient\n\nclient = HLClient.from_profile(\"profile-name\")\n```\n\nAdditionally `HLClient` can be initialized using environment variables or\nby passing credentials direcly\n\n```python\nfrom highlighter.client import HLClient\n\nclient = HLClient.get_client()\n\n# or\n\napi_token = \"###\"\nendpoint_url = \"https://...highligher.ai/graphql\nclient = HLCient.from_credential(api_token, endpoint_url)\n```\n\nFinally, if you are in the position where you want to write a specified profile's\ncredentials to an evnironment file such as `.env` or `.envrc` you can use\nthe `write` command. This will create or append to the specified file.\n\n```console\nhl --profile my-profile write .envrc\n```\n\n## Python API\n\nOnce you have a `HLClient` object you can use it perform queries or mutations. Here is a simple example.\n\n```python\nfrom highlighter.client import HLClient\nfrom pydantic import BaseModel\n\nclient = HLClient.get_client()\n\n# You don't always need to define your own BaseModels\n# many common BaseModels are defined in highlighter.base_models\n# this is simply for completeness\nclass ObjectClassType(BaseModel):\n id: int\n name: str\n\nid = 1234 # add an object class id from you account\n\nresult = client.ObjectClass(\n return_type=ObjectClassType,\n id=id,\n )\n\nprint(result)\n```\n\nSome queries may return arbitrarily many results. These queries are\npaginated and are called `Connections` and the queries are named accordingly.\nWe have provided a `paginate` function to help with these `Connections`\n\n```python\nfrom highlighter.core import paginate\nfrom highlighter.client import HLClient\nfrom pydantic import BaseModel\n\nclient = HLClient.get_client()\nuuids = [\n \"abc123-abc123-abc123-abc123\",\n \"xyz456-xyz456-xyz456-xyz456\",\n]\n\n# The following BaseModels are all defined in\n# highlighter.base_models. They are simply here\n# for completeness\nclass PageInfo(BaseModel):\n hasNextPage: bool\n endCursor: Optional[str]\n\nclass ObjectClass(BaseModel):\n id: str\n uuid: str\n name: str\n\nclass ObjectClassTypeConnection(BaseModel):\n pageInfo: PageInfo\n nodes: List[ObjectClass]\n\ngenerator = paginate(\n client..objectClassConnection,\n ObjectClassTypeConnection,\n uuid=uuids,\n )\n\nfor object_class in generator:\n print(object_class)\n```\n\n## Datasets\n\nHighlighter SDK provides a dataset representation that can populated\nfrom several sources `{HighlighterWeb.Assessments | Local files {.hdf, records.json, coco.json} | S3Bucket}`.\nOnce populated the `Highlighter.Datasets` object contains 2 `Pandas.DataFrames`\n(`data_files_df` and `annotations_df`) that you can manipulate as required. When you're\nready you can write to disk or upload to Highligher using one of the `Writer` classes\nto dump your data to disk in a format that can be consumed by your downstream code.\nIf you need you can also roll-your-own `Writer` by implementing the `highlighter.datasets.interfaces.IWriter` interface.\n\n## CLI Tab Completion\n\n<table>\n <tr>\n <th>Console</th>\n <td>\n </td>\n </tr>\n <tr>\n <th>Shell</th>\n <td>\n Add this to your <code>~/.bashrc</code>:<br>\n <code>eval \"$(_HL_COMPLETE=bash_source hl)\"</code><br>\n </td>\n </tr>\n <tr>\n <th>ZSH</th>\n <td>\n Add this to your <code>~/.zshrc</code>:<br>\n <code>eval \"$(_HL_COMPLETE=zsh_source hl)\"</code><br>\n </td>\n </tr>\n <tr>\n <th>Fish</th>\n <td>\n Add this to <code>~/.config/fish/completions/hl.fish</code>:<br>\n <code>_HL_COMPLETE=fish_source hl | source</code>\n </td>\n </tr>\n</table>\n\nFor more information, see the [Click documentation](https://click.palletsprojects.com/en/8.1.x/shell-completion/#enabling-completion)\n\n## Documentation\n\nSee https://highlighter-docs.netlify.app/\n",
"bugtrack_url": null,
"license": "APACHE 2.0",
"summary": "Package to interact with the Highlighter Perception System",
"version": "2.4.73",
"project_urls": {
"Documentation": "https://highlighter-docs.netlify.app/"
},
"split_keywords": [
"enterprise",
"perception",
"system"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad49718fc8cf0271a4fcd6a8812d630f34e0c3fd0c506892cc32711673002793",
"md5": "e24bc224b37d39ff79db86ffe5dbc9e5",
"sha256": "97fe0b59ce98f3fc5f512095fb10287818043a18edd9a40ac7db8a36bfdd2929"
},
"downloads": -1,
"filename": "highlighter_sdk-2.4.73-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e24bc224b37d39ff79db86ffe5dbc9e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<=3.12.5,>=3.10",
"size": 140049,
"upload_time": "2024-12-20T07:25:40",
"upload_time_iso_8601": "2024-12-20T07:25:40.033552Z",
"url": "https://files.pythonhosted.org/packages/ad/49/718fc8cf0271a4fcd6a8812d630f34e0c3fd0c506892cc32711673002793/highlighter_sdk-2.4.73-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "920942e991378a00f69ec64ce177030efa9bb81ef388b3dfcbaa616102f96fc9",
"md5": "e6de8c422ae9945d1a71d029ce350d22",
"sha256": "59a70118820b45eb81dc29179c512108236c05fbbf6ebd950886c5cf482b1b81"
},
"downloads": -1,
"filename": "highlighter_sdk-2.4.73.tar.gz",
"has_sig": false,
"md5_digest": "e6de8c422ae9945d1a71d029ce350d22",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.12.5,>=3.10",
"size": 103869,
"upload_time": "2024-12-20T07:25:31",
"upload_time_iso_8601": "2024-12-20T07:25:31.997793Z",
"url": "https://files.pythonhosted.org/packages/92/09/42e991378a00f69ec64ce177030efa9bb81ef388b3dfcbaa616102f96fc9/highlighter_sdk-2.4.73.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-20 07:25:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "highlighter-sdk"
}
