# superb-data-klient
**superb-data-klient** offers a streamlined interface to access various services of the *Superb Data Kraken platform* (**SDK**). With the library, you can
effortlessly fetch and index data, manage indices, spaces and organizations on the **SDK**.
Designed primarily for a Jupyter Hub environment within the platform, it's versatile enough to be set up in other environments too.
## Installation and Supported Versions
```console
$ python -m pip install superb-data-klient
```
## Usage
### Authentication
To begin, authenticate against the SDK's OIDC provider. This is achieved when instantiating the client object:
1. **System Environment Variables** (recommended for Jupyter environments):
```python
import superbdataklient as sdk
client = sdk.SDKClient()
```
This approach leverages environment variables **SDK_ACCESS_TOKEN** and **SDK_REFRESH_TOKEN**.
2. **Login Credentials**:
``` python
import superbdataklient as sdk
sdk.SDKClient(username='hasslethehoff', password='lookingforfreedom')
```
3. **Authentication Code Flow**:
If none of the above mentioned authentication methods fit, authentication is fulfilled via code-flow.
**CAUTION** Beware that this method only works in a browser-environment.
### Configuration
While the default settings cater to the standard SDK instance, configurations for various other instances are also available.
#### Setting Environment
``` python
import superbdataklient as sdk
client = sdk.SDKClient(env='sdk-dev')
client = sdk.SDKClient(env='sdk')
```
#### Overwriting Settings
``` python
client = sdk.SDKClient(domain='mydomain.ai', realm='my-realm', client_id='my-client-id', api_version='v13.37')
```
#### Proxy
To Use the SDK Client behind a company proxy a user might add the following config parameters to the constructor.
**NOTE**: The environment Variables "http_proxy" and "https_proxy" will overwrite the settings in the SDKClient.
So remove them before configuring the SDKClient.
```python
client = SDKClient(username='hasslethehoff',
password='lookingforfreedom',
proxy_http="http://proxy.example.com:8080",
proxy_https="https://proxy.example.com:8080",
proxy_user="proxyusername",
proxy_pass="proxyuserpassword")
```
---
### Examples
#### Organizations
Get details of all organizations, or retrieve by ID or name:
``` python
client.organization_get_all()
client.organization_get_by_id(1337)
client.organization_get_by_name('my-organization')
```
#### Spaces
To retrieve spaces related to an organization:
``` python
organization_id = 1234
client.space_get_all(organization_id)
client.space_get_by_id(organization_id, space_id)
client.space_get_by_name(organization_id, space)
```
#### Index
<!--
TODO: implement after search service works without all_access ()
List all accessible indices:
``` python
indices = client.index_get_all()
```
-->
Retrieve a specific document:
``` python
document = client.index_get_document(index_name, doc_id)
```
Fetch all documents within an index:
``` python
documents = client.index_get_all_documents("index_name")
```
Iterate through documents using a generator:
``` python
documents = client.index_get_documents("index-name")
for document in documents:
print(document)
```
Index multiple documents:
``` python
documents = [
{"_id": 123, "name": "document01", "value": "value"},
{"_id": 1337, "name": "document02", "value": "value"}
]
index_name = "index"
client.index_documents(documents, index_name)
```
Note: The optional **_id** field is used as the document ID for indexing in OpenSearch.
Filter indices by organization, space, and type:
``` python
client.index_filter_by_space("my-organization", "my-space", "index-type")
```
For all spaces in an organization, use `*` instead of a space name. Available **index_type** values are **ANALYSIS** or **MEASUREMENTS**.
Create an application index:
``` python
mapping = {
...
}
client.application_index_create("my-application-index", "my-organization", "my-space", mapping)
```
Remove an application index by its name:
``` python
client.application_index_delete("my-organization_my-space_analysis_my-application-index")
```
#### Storage
List files in Storage:
``` python
files = client.storage_list_blobs("my-organization", "space")
```
Download specific files from Storage:
``` python
files = ['file01.txt', 'directory/file02.json']
client.storage_download_files(organization='my-organization', space='my-space', files=files, local_dir='tmp')
```
Use regex patterns for file downloads:
``` python
files = ['file01.txt', 'directory/file02.json']
client.storage_download_files_with_regex(organization='my-organization', space='my-space', files=files, local_dir='tmp', regex=r'.*json$')
```
Upload files from a local directory. Ensure the presence of a valid `meta.json` if the `metadataGenerate` property on the space is not set to `true`:
``` python
files = ['meta.json', 'file01.txt', 'file02.txt']
client.storage_upload_files_to_loadingzone(organization='my-organization', space='my-space', files= files, local_dir='tmp')
```
Raw data
{
"_id": null,
"home_page": "",
"name": "superb-data-klient",
"maintainer": "Team SDK",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "sdk@efs-techhub.com",
"keywords": "sdk,superb data kraken,superbdataklient,super data klient,superb-data-klient,superb,data,klient",
"author": "",
"author_email": "\"Team SDK | e:fs TechHub GmbH\" <sdk@efs-techhub.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/64/46d9b38152555c97190ba5956e1065cfed255f4c5a0ce9135764af43668d/superb-data-klient-1.2.0.tar.gz",
"platform": null,
"description": "\n\n\n\n\n\n# superb-data-klient\n\n\n**superb-data-klient** offers a streamlined interface to access various services of the *Superb Data Kraken platform* (**SDK**). With the library, you can\neffortlessly fetch and index data, manage indices, spaces and organizations on the **SDK**.\n\nDesigned primarily for a Jupyter Hub environment within the platform, it's versatile enough to be set up in other environments too.\n\n\n## Installation and Supported Versions\n\n```console\n$ python -m pip install superb-data-klient\n```\n\n## Usage\n\n\n### Authentication\n\n\nTo begin, authenticate against the SDK's OIDC provider. This is achieved when instantiating the client object:\n\n1. **System Environment Variables** (recommended for Jupyter environments):\n ```python\n import superbdataklient as sdk\n client = sdk.SDKClient()\n ```\n This approach leverages environment variables **SDK_ACCESS_TOKEN** and **SDK_REFRESH_TOKEN**.\n\n\n2. **Login Credentials**:\n ``` python\n import superbdataklient as sdk\n sdk.SDKClient(username='hasslethehoff', password='lookingforfreedom')\n ```\n\n3. **Authentication Code Flow**:\n\n If none of the above mentioned authentication methods fit, authentication is fulfilled via code-flow.\n\n **CAUTION** Beware that this method only works in a browser-environment.\n\n### Configuration\n\n\nWhile the default settings cater to the standard SDK instance, configurations for various other instances are also available.\n\n\n#### Setting Environment\n\n``` python\nimport superbdataklient as sdk\nclient = sdk.SDKClient(env='sdk-dev')\nclient = sdk.SDKClient(env='sdk')\n```\n\n#### Overwriting Settings\n\n``` python\nclient = sdk.SDKClient(domain='mydomain.ai', realm='my-realm', client_id='my-client-id', api_version='v13.37')\n```\n\n\n#### Proxy\nTo Use the SDK Client behind a company proxy a user might add the following config parameters to the constructor. \n**NOTE**: The environment Variables \"http_proxy\" and \"https_proxy\" will overwrite the settings in the SDKClient. \nSo remove them before configuring the SDKClient.\n```python\nclient = SDKClient(username='hasslethehoff', \n password='lookingforfreedom', \n proxy_http=\"http://proxy.example.com:8080\", \n proxy_https=\"https://proxy.example.com:8080\", \n proxy_user=\"proxyusername\", \n proxy_pass=\"proxyuserpassword\")\n```\n\n---\n### Examples\n\n\n#### Organizations\n\n\nGet details of all organizations, or retrieve by ID or name:\n\n``` python\nclient.organization_get_all()\nclient.organization_get_by_id(1337)\nclient.organization_get_by_name('my-organization')\n```\n\n#### Spaces\n\n\nTo retrieve spaces related to an organization:\n\n``` python\norganization_id = 1234\nclient.space_get_all(organization_id)\nclient.space_get_by_id(organization_id, space_id)\nclient.space_get_by_name(organization_id, space)\n```\n\n#### Index\n\n\n<!--\nTODO: implement after search service works without all_access ()\n\nList all accessible indices:\n\n``` python\nindices = client.index_get_all()\n```\n-->\n\nRetrieve a specific document:\n\n``` python\ndocument = client.index_get_document(index_name, doc_id)\n``` \n\nFetch all documents within an index:\n\n``` python\ndocuments = client.index_get_all_documents(\"index_name\")\n```\n\nIterate through documents using a generator:\n\n``` python\ndocuments = client.index_get_documents(\"index-name\")\nfor document in documents:\n print(document)\n```\n\nIndex multiple documents:\n\n``` python\ndocuments = [\n {\"_id\": 123, \"name\": \"document01\", \"value\": \"value\"},\n {\"_id\": 1337, \"name\": \"document02\", \"value\": \"value\"}\n]\nindex_name = \"index\"\nclient.index_documents(documents, index_name)\n``` \n\nNote: The optional **_id** field is used as the document ID for indexing in OpenSearch.\n\nFilter indices by organization, space, and type:\n\n``` python\nclient.index_filter_by_space(\"my-organization\", \"my-space\", \"index-type\")\n```\n\nFor all spaces in an organization, use `*` instead of a space name. Available **index_type** values are **ANALYSIS** or **MEASUREMENTS**.\n\nCreate an application index:\n\n``` python\nmapping = {\n ...\n}\nclient.application_index_create(\"my-application-index\", \"my-organization\", \"my-space\", mapping)\n```\n\nRemove an application index by its name:\n\n``` python\nclient.application_index_delete(\"my-organization_my-space_analysis_my-application-index\")\n```\n\n#### Storage\n\n\nList files in Storage:\n\n``` python\nfiles = client.storage_list_blobs(\"my-organization\", \"space\")\n```\n\nDownload specific files from Storage:\n\n``` python\nfiles = ['file01.txt', 'directory/file02.json']\nclient.storage_download_files(organization='my-organization', space='my-space', files=files, local_dir='tmp')\n```\n\nUse regex patterns for file downloads:\n\n``` python\nfiles = ['file01.txt', 'directory/file02.json']\nclient.storage_download_files_with_regex(organization='my-organization', space='my-space', files=files, local_dir='tmp', regex=r'.*json$')\n```\n\nUpload files from a local directory. Ensure the presence of a valid `meta.json` if the `metadataGenerate` property on the space is not set to `true`:\n\n``` python\nfiles = ['meta.json', 'file01.txt', 'file02.txt']\nclient.storage_upload_files_to_loadingzone(organization='my-organization', space='my-space', files= files, local_dir='tmp')\n```\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A Python API wrapping services of the Superb Data Kraken (SDK)",
"version": "1.2.0",
"project_urls": null,
"split_keywords": [
"sdk",
"superb data kraken",
"superbdataklient",
"super data klient",
"superb-data-klient",
"superb",
"data",
"klient"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cce13679e1ff214e6402b48c418139187d4b8771ae9011eda70ffcdc6fd0e141",
"md5": "540acff9bbf4abf6964b2d6cef31561c",
"sha256": "795606ee12b6a85c3ddd611faeff911d6de5c9b6b5f53b88dd39297e3af03a38"
},
"downloads": -1,
"filename": "superb_data_klient-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "540acff9bbf4abf6964b2d6cef31561c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18141,
"upload_time": "2024-03-06T10:09:50",
"upload_time_iso_8601": "2024-03-06T10:09:50.883230Z",
"url": "https://files.pythonhosted.org/packages/cc/e1/3679e1ff214e6402b48c418139187d4b8771ae9011eda70ffcdc6fd0e141/superb_data_klient-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bb6446d9b38152555c97190ba5956e1065cfed255f4c5a0ce9135764af43668d",
"md5": "8b5e4b278f9299b58f85679c69207d25",
"sha256": "fb5f6ef9fdb8d35b2afd6cc40d1c29a1e3883ebc1b3ff44759ae75a15812c0ed"
},
"downloads": -1,
"filename": "superb-data-klient-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "8b5e4b278f9299b58f85679c69207d25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 21393,
"upload_time": "2024-03-06T10:09:52",
"upload_time_iso_8601": "2024-03-06T10:09:52.707927Z",
"url": "https://files.pythonhosted.org/packages/bb/64/46d9b38152555c97190ba5956e1065cfed255f4c5a0ce9135764af43668d/superb-data-klient-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-06 10:09:52",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "superb-data-klient"
}
JSON