hiro_graph_client package

Submodules

hiro_graph_client.actionwebsocket module

hiro_graph_client.actionwebsocket.logger = <Logger hiro_graph_client.actionwebsocket (WARNING)>

The logger for this module

class hiro_graph_client.actionwebsocket.ActionMessageType(*values)

Bases: str, Enum

ACKNOWLEDGED = 'acknowledged'

NEGATIVE_ACKNOWLEDGED = 'negativeAcknowledged'

SEND_ACTION_RESULT = 'sendActionResult'

SUBMIT_ACTION = 'submitAction'

ERROR = 'error'

CONFIG_CHANGED = 'configChanged'

class hiro_graph_client.actionwebsocket.AbstractActionHandlerMessage(**kwargs)

Bases: object

The structure of an incoming action message

type: ActionMessageType

static type name of field ‘type’ in the json message

classmethod parse(dict_message: dict)

class hiro_graph_client.actionwebsocket.AbstractActionHandlerIdMessage(action_id: str, **kwargs)

Bases: AbstractActionHandlerMessage

The structure of an incoming action message with id

Constructor

Parameters:

action_id – ID. Might be None for messages without an ID.

id: str

class hiro_graph_client.actionwebsocket.AbstractActionHandlerCodeMessage(code: int, message: str, **kwargs)

Bases: AbstractActionHandlerMessage

The structure of an incoming action message with code and message

Constructor

Parameters:

• code – Code number

• message – Message string

code: int

message: str

class hiro_graph_client.actionwebsocket.ActionHandlerSubmit(action_id: str, handler: str, capability: str, parameters: dict, timeout: int)

Bases: AbstractActionHandlerIdMessage

Constructor

Parameters:

• action_id – ID

• handler – Handler name

• capability – Capability name

• parameters – Parameter dict

• timeout – Timeout in milliseconds

type: ActionMessageType = 'submitAction'

static type name of field ‘type’ in the json message

handler: str

capability: str

parameters: dict

timeout: int

Milliseconds

_expires_at: int

Milliseconds

classmethod parse(dict_message: dict)

property expires_at

class hiro_graph_client.actionwebsocket.ActionHandlerResult(action_id: str, result: dict | str)

Bases: AbstractActionHandlerIdMessage

Constructor

Parameters:

• action_id – ID

• result – Result data

type: ActionMessageType = 'sendActionResult'

static type name of field ‘type’ in the json message

result: dict

classmethod parse(dict_message: dict)

stringify_result() → str

class hiro_graph_client.actionwebsocket.ActionHandlerAck(action_id: str, code: int, message: str)

Bases: AbstractActionHandlerIdMessage, AbstractActionHandlerCodeMessage

Constructor

Parameters:

• action_id – ID

• code – Ack code

• message – Ack message

type: ActionMessageType = 'acknowledged'

static type name of field ‘type’ in the json message

classmethod parse(dict_message: dict)

class hiro_graph_client.actionwebsocket.ActionHandlerNack(action_id: str, code: int, message: str)

Bases: AbstractActionHandlerIdMessage, AbstractActionHandlerCodeMessage

Constructor

Parameters:

• action_id – ID

• code – Nack code

• message – Nack message

type: ActionMessageType = 'negativeAcknowledged'

static type name of field ‘type’ in the json message

classmethod parse(dict_message: dict)

class hiro_graph_client.actionwebsocket.ActionHandlerError(code: int, message: str)

Bases: AbstractActionHandlerCodeMessage

Constructor

Parameters:

• code – Error code

• message – Error message

type: ActionMessageType = 'error'

static type name of field ‘type’ in the json message

classmethod parse(dict_message: dict)

class hiro_graph_client.actionwebsocket.ActionHandlerConfigChanged

Bases: AbstractActionHandlerMessage

type: ActionMessageType = 'configChanged'

static type name of field ‘type’ in the json message

classmethod parse(dict_message: dict)

class hiro_graph_client.actionwebsocket.ActionHandlerMessageParser(message: dict | str)

Bases: object

Create an ActionHandlerMessage from a string message or dict.

Create an ActionHandlerMessage from a string message or dict. Return None if no message can be parsed.

Parameters:

message – Message as str or dict

message: dict

parse() → AbstractActionHandlerMessage | None

Create the ActionHandlerMessage

Returns:

Instance of a child of AbstractActionHandlerMessage or None if self.message is empty.

Raises:

UnknownActionException – If the type of self.message is unknown.

class hiro_graph_client.actionwebsocket.ActionItem(job: Job, message: AbstractActionHandlerIdMessage, expires_at: int, retries: int = 4)

Bases: object

An item for the ExpiringStore which carries its timeout and retries

Constructor

Parameters:

• job – Job of the scheduler

• message – AbstractActionHandlerMessage

• expires_at – Expiry of the message in epoch in ms

• retries – Retry counter for ActionStore.retry_get. Defaults to 4.

_scheduled_job: Job

message: AbstractActionHandlerIdMessage

expires_at: int

Epoch time after which this item is invalid

retries: int

Amount of retries this item can be get via the ActionStore.retryGet(). Default is 4

remove()

Remove the job from the scheduler on deletion.

class hiro_graph_client.actionwebsocket.ActionStore

Bases: object

A thread-safe storage implementation with expiring entries

Constructor. Starts the scheduler.

_store: Dict[str, ActionItem]

_store_lock: RLock

_expiry_scheduler: BackgroundScheduler

start_scheduler()

stop_scheduler()

__expiry_remove(message_id: str) → None

Remove a message from the store and log it on logger.isEnabledFor(logging.INFO).

Parameters:

message_id – Id of the message

add(expires_at: int, message: AbstractActionHandlerIdMessage, retries: int = 4) → None

Add message to the store and start its expiry timer.

Parameters:

• expires_at – Epoch in ms when the message expires.

• message – The message itself.

• retries – Retries allowed when self.retry_get is used.

Raises:

• ActionItemExpired – When the expires_at has expired already.

• ActionItemExists – When the id of the message already exists in the store

remove(message_id: str) → None

Remove a message from the store.

Parameters:

message_id – Id of the message

get(message_id: str) → AbstractActionHandlerIdMessage | None

Get a message from the store.

Parameters:

message_id – Id of the message

Returns:

The message or None if message_id is not present in the store.

retry_get(message_id: str) → AbstractActionHandlerIdMessage | None

Get a message from the store. Each time it is returned, its retries counter is decreased. If it reaches 0, the message gets deleted and None gets returned.

Parameters:

message_id – Id of the message

Returns:

The message or None if message_id is not present in the store or its retries counter is 0.

clear() → None

Clear the store. Remove all items from it.

class hiro_graph_client.actionwebsocket.AbstractActionWebSocketHandler(api_handler: AbstractTokenApiHandler, query_params: Dict[str, str] = None)

Bases: AbstractAuthenticatedWebSocketHandler

A handler for actions

Constructor

Parameters:

• api_handler – The TokenApiHandler for this WebSocket.

• query_params – URL Query parameters for this specific websocket. Use Dict[str,str] only here - no boolean Values.

submitStore: ActionStore = None

resultStore: ActionStore = None

__finish_submit(action_id: str, action_handler_result: ActionHandlerResult | None)

Sends the action_handler_result if it is not None and makes sure, that the submitAction is removed from the self.submitStore.

Parameters:

• action_id – ID of the action

• action_handler_result – Result for the submitAction. May be None.

start() → None

Create the WebSocketApp

Raises:

WebSocketException – When the creation of the WebSocketApp fails.

stop() → None

Intentionally closes this websocket and waits for self.run_forever() to return. Call this from another thread than self.run_forever().

on_open(ws: WebSocketApp)

on_close(ws: WebSocketApp, code: int = None, reason: str = None)

on_error(ws: WebSocketApp, error: Exception)

on_message(ws: WebSocketApp, message: str)

Handle incoming action messages

Parameters:

• ws – WebSocketApp

• message – The message payload as str

abstractmethod on_submit_action(action_id: str, capability: str, parameters: dict)

Handle incoming submitAction

Parameters:

• action_id – Id of the action

• capability – Capability of the submitAction

• parameters – Additional parameters for the capability

send_action_result(action_id: str, result: dict | str = None, code: int = None, message: str = None, result_params: dict = None) → None

Send the result of a submitAction. Thread-Safe!

Will create a standard result dict with the parameters result, code or message. See parameter description for more.

{
    "type": "sendActionResult",
    "id": action_id,
    "result": json.dumps({
        "message": message,
        "code": code,
        "data": result
    })

}

If result_params is given, this parameter will be used directly while ignoring the other parameters.

{
    "type": "sendActionResult",
    "id": action_id,
    "result": json.dumps(result_params)
}

Parameters:

• action_id – Required. Id of the submitAction

• result – Result data. Either a dict (which will be serialized into a str), a str or None.

• code – Optional result code. If unset, a default will be used (200 if result is not empty, 204 otherwise).

• message – Optional result message. If unset, a default message will be used.

• result_params – Optional custom data to return as result value in message sendActionResult. Overrides all other optional message parameters. Will be serialized to a string.

abstractmethod on_config_changed()

exception hiro_graph_client.actionwebsocket.ActionException(error_id, message_type)

Bases: Exception

When an unknown action is received

id: str

type: str

exception hiro_graph_client.actionwebsocket.UnknownActionException(error_id, message_type)

Bases: ActionException

When an unknown action is received

exception hiro_graph_client.actionwebsocket.ActionItemExpired(error_id, message_type)

Bases: ActionException

When an action item for the ActionStore has expired

exception hiro_graph_client.actionwebsocket.ActionItemExists(error_id, message_type)

Bases: ActionException

When an action item for the ActionStore already exists

hiro_graph_client.appclient module

class hiro_graph_client.appclient.HiroApp(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO App REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/app.yaml

Constructor

Parameters:

api_handler – External API handler.

get_app(node_id) → dict

HIRO REST query API: GET self._endpoint + ‘/{id}’

Parameters:

node_id – ogit/_id of the node/vertex or edge.

Returns:

The result payload

get_config() → dict

HIRO REST query API: GET self._endpoint + ‘/config’. The token (internal or external) defines the config returned.

Returns:

The result payload

get_content(node_id, path) → Iterator[bytes]

HIRO REST query API: GET self._endpoint + ‘/{id}/content/{path}’. Get the content of an application.

Parameters:

• node_id – ogit/_id of the node/vertex or edge.

• path – filename / path of the desired content.

Returns:

The result payload generator over binary data.

get_manifest(node_id) → dict

HIRO REST query API: GET self._endpoint + ‘/{id}/manifest’. Get the manifest of an application.

Parameters:

node_id – ogit/_id of the node/vertex or edge.

Returns:

The result payload - usually with a binary content.

get_desktop() → dict

HIRO REST query API: GET self._endpoint + ‘/desktop’. List desktop applications.

Returns:

The result payload - usually with a binary content.

hiro_graph_client.authclient module

class hiro_graph_client.authclient.HiroAuth(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO Auth REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/auth.yaml

Constructor

Parameters:

api_handler – External API handler.

get_identity() → dict

HIRO REST query API: GET self._auth_endpoint + ‘/me/account’

Returns:

The result payload

get_avatar() → Iterator[bytes]

HIRO REST query API: GET self._auth_endpoint + ‘/me/avatar’

Returns:

The result payload generator over binary data. Complete binary payload is an image/png.

put_avatar(data: Any, content_type: str = 'image/png') → int

HIRO REST query API: PUT self._auth_endpoint + ‘/me/avatar’

Parameters:

• data – Binary data for image of avatar.

• content_type – Content-Type. Default: image/png

Returns:

The result payload / size of the avatar in bytes.

change_password(old_password: str, new_password: str) → dict

HIRO REST query API: PUT self._auth_endpoint + ‘/me/password’

Parameters:

• old_password – The old password to replace.

• new_password – The new password.

Returns:

The result payload

get_profile() → dict

HIRO REST query API: GET self._auth_endpoint + ‘/me/profile

Returns:

The result payload

post_profile(data: dict) → dict

HIRO REST query API: POST self._auth_endpoint + ‘/me/profile

Parameters:

data – The attributes for the profile. See https://core.engine.datagroup.de/help/specs/?url=definitions/auth.yaml#/[Me]_Identity/post_me_profile

Returns:

The result payload

get_roles() → dict

HIRO REST query API: GET self._auth_endpoint + ‘/me/roles

Returns:

The result payload

get_teams() → dict

HIRO REST query API: GET self._auth_endpoint + ‘/me/teams’

Returns:

The result payload

hiro_graph_client.authzclient module

class hiro_graph_client.authzclient.HiroAuthz(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO Authz REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/authz.yaml

Constructor

Parameters:

api_handler – External API handler.

entitlement(data: dict) → dict

Ask for entitlement decision

HIRO REST query API: POST self._endpoint + ‘/entitlement

Parameters:

data – Entitlement request data. See https://core.engine.datagroup.de/help/specs/?url=definitions/authz.yaml#/[Authorization]_Entitlement/post_entitlement

Returns:

The result payload

hiro_graph_client.client module

class hiro_graph_client.client.HiroGraph(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO Graph REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml

Constructor

Parameters:

api_handler – External API handler.

query(query: str, fields: str = None, limit=-1, offset=0, order: str = None, meta: bool = None, count: bool = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Search/post_query_vertices

Parameters:

• query – The actual query. e.g. ogit\/_type: ogit\/Question for vertices.

• fields – the comma separated list of fields to return

• limit – limit of entries to return

• offset – offset where to start returning entries

• order – order by a field asc|desc, e.g. ogit/name desc

• meta – List detailed metainformations in result payload

• count – Just return the number of found items. Result payload is like {“items”:[&lt;number of items found as int&gt;]}.

Returns:

Result payload

query_gremlin(query: str, root: str, fields: str = None, include_deleted: bool = None, meta: bool = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Search/post_query_gremlin

Parameters:

• query – The actual query. e.g. outE().inV() for gremlin.

• root – ogit/_id of the root node where the gremlin query starts.

• fields – the comma separated list of fields to return

• include_deleted – Include deleted values.

• meta – List detailed metainformations in result payload

Returns:

Result payload

create_node(data: dict, obj_type: str, return_id=False) → dict | str

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Entity/post_new__type_

Parameters:

• data – Payload for the new node/vertex

• obj_type – ogit/_type of the new node/vertex

• return_id – Return only the ogit/_id as string. Default is False to return everything as dict.

Returns:

The result payload

update_node(node_id: str, data: dict) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Entity/post__id_

Parameters:

• data – Payload for the node/vertex

• node_id – ogit/_id of the node/vertex

Returns:

The result payload

delete_node(node_id: str) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Entity/delete__id_

Parameters:

node_id – ogit/_id of the node/vertex

Returns:

The result payload

connect_nodes(from_node_id: str, verb: str, to_node_id: str) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Verb/post_connect__type_

Parameters:

• from_node_id – ogit/_id of the source node/vertex

• verb – verb for the connection

• to_node_id – ogit/_id of the target node/vertex

Returns:

The result payload

disconnect_nodes(from_node_id: str, verb: str, to_node_id: str) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Verb/delete__id_

Parameters:

• from_node_id – ogit/_id of the source node/vertex

• verb – verb for the connection

• to_node_id – ogit/_id of the target node/vertex

Returns:

The result payload

get_node(node_id: str, fields: str = None, meta: bool = None, include_deleted: bool = None, vid: str = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Entity/get__id_

Parameters:

• node_id – ogit/_id of the node/vertex or edge

• fields – Filter for fields

• include_deleted – allow to get if ogit/_is-deleted=true

• vid – get specific version of Entity matching ogit/_v-id

• meta – List detailed metainformations in result payload

Returns:

The result payload

get_nodes(node_ids: list, fields: str = None, meta: bool = None, include_deleted: bool = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Search/get_query_ids

Parameters:

• node_ids – list of ogit/_ids of the node/vertexes or edges

• fields – Filter for fields

• meta – List detailed metainformations in result payload

• include_deleted – allow to get if ogit/_is-deleted=true

Returns:

The result payload

get_node_by_xid(node_id: str, fields: str = None, meta: bool = None, include_deleted: bool = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Search/get_xid__id_

Parameters:

• node_id – ogit/_xid of the node/vertex or edge

• fields – Filter for fields

• meta – List detailed metainformations in result payload

• include_deleted – allow to get if ogit/_is-deleted=true

Returns:

The result payload

get_timeseries(node_id: str, starttime: str = None, endtime: str = None, include_deleted: bool = None, limit: int = None, with_ids: str = None, order: str = 'asc', aggregate: str = None) → List | Dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Timeseries/get__id__values

Parameters:

• node_id – ogit/_id of the node containing timeseries

• starttime – ms since epoch.

• endtime – ms since epoch.

• aggregate – aggregate numeric values for multiple timeseries ids with same timestamp: avg|min|max|sum|none

• order – order by a timestamp asc|desc|none. Default is “asc” here.

• with_ids – list of ids to aggregate in result

• limit – limit of entries to return

• include_deleted – allow to get if ogit/_is-deleted=true

Returns:

The result payload. Either a list of dict or a dict with an error message.

get_timeseries_history(node_id: str, timestamp: str = None, include_deleted: bool = None) → List | Dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Timeseries/get__id__values_history

Parameters:

• node_id – ogit/_id of the node containing timeseries

• timestamp – timestamp in ms

• include_deleted – allow to get if ogit/_is-deleted=true

Returns:

The result payload. Either a list of dict or a dict with an error message.

query_timeseries(starttime: str = None, endtime: str = None, limit: int = None, order: str = 'asc', aggregate: str = None) → List | Dict

Run a query against the graph and return agragated timeseries values for timeseries vertices matching query result. query: Entities with matching ogit/_type:ogit/Timeseries

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Search/get_query_values

Parameters:

• starttime – ms since epoch.

• endtime – ms since epoch.

• aggregate – aggregate numeric values for multiple timeseries ids with same timestamp: avg|min|max|sum|none

• order – order by a timestamp asc|desc|none. Default is “asc” here.

• limit – limit of entries to return

Returns:

The result payload. Either a list of dict or a dict with an error message.

post_timeseries(node_id: str, items: list, synchronous: bool = True, ttl: int = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Storage]_Timeseries/post__id__values

Parameters:

• synchronous – whether the operation should return synchronously. Default is True here.

• ttl – time to live for values to be stored in seconds (overrides /ttl in vertex).

• node_id – ogit/_id of the node containing timeseries

• items – list of timeseries values [{timestamp: (ms since epoch), value: …},…]

Returns:

The result payload

get_attachment(node_id: str, content_id: str = None, include_deleted: bool = None) → Iterator[bytes]

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Blob/get__id__content

Parameters:

• node_id – Id of the attachment node

• content_id – Id of the content within the attachment node. Default is None.

• include_deleted – Whether to be able to access deleted content: Default is False

Returns:

Returns generator over byte chunks from the response body payload.

post_attachment(node_id: str, data: Any, content_type: str = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Storage]_Blob/post__id__content

Parameters:

• node_id – Id of the attachment node

• data – Data to upload in binary form. Can also be an IO object for streaming.

• content_type – Content-Type for data. Defaults to ‘application/octet-stream’ if left unset.

Returns:

The result payload

get_history(node_id: str, ts_from: int = 0, ts_to: int = datetime.datetime(2025, 4, 7, 14, 59, 1, 479675), history_type: str = 'element', version: str = None, vid: str = None, limit=-1, offset=0, include_deleted: bool = None, meta: bool = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_History/get__id__history

Parameters:

• node_id – Id of the node

• ts_from – timestamp in ms where to start returning entries (default: 0)

• ts_to – timestamp in ms where to end returning entries (default: now)

• history_type – Response format: full - full event, element - only event body, diff - diff to previous event. (default: ‘element’)

• version – get entry with specific ogit/_v value

• vid – get specific version of Entity matching ogit/_v-id

• limit – limit of entries to return (default: -1).

• offset – offset where to start returning entries (default: 0)

• include_deleted – allow to get if ogit/_is-deleted=true (default: false)

• meta – return list type attributes with metadata (default: false)

Returns:

The result payload

get_events(ts_from: int = 0, ts_to: int = datetime.datetime(2025, 4, 7, 14, 59, 1, 479679), ogit_type: str = None, jfilter: str = None) → dict

Replays events from history

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Events]_History/get_events_

Parameters:

• ts_from – timestamp in ms where to start returning entries (default: 0)

• ts_to – timestamp in ms where to end returning entries (default: now)

• jfilter – jfilter string to limit matching results

• ogit_type – Entity or Verb ogit/_type for filtering result based on this type

Returns:

The result payload

hiro_graph_client.clientlib module

hiro_graph_client.clientlib.logger = <Logger hiro_graph_client.clientlib (WARNING)>

The logger for this module

class hiro_graph_client.clientlib.SSLConfig(verify: bool = True, cert_file: str = None, key_file: str = None, ca_bundle_file: str = None)

Bases: object

Configuration for SSL connections.

Parameters:

• verify – Verify connections at all. If just set to True without other parameters, defaults will be used.

• cert_file – (optional) Client certificate file (.pem).

• key_file – (optional) Key for the certificate file.

• ca_bundle_file – (optional) The ca_bundle for server certificate verification.

verify: bool

cert_file: str

key_file: str

ca_bundle_file: str

This class contains the configuration for SSL connections, like the files to use.

get_verify()

Get verify parameter as expected by requests library.

Returns:

True, False or a path to a ca_bundle.

get_cert()

Get cert parameter as expected by requests library.

Returns:

Tuple of cert_file, key_file or just cert_file - which can be None.

class hiro_graph_client.clientlib.AbstractAPI(root_url: str = None, session: Session = None, raise_exceptions: bool = True, proxies: dict = None, headers: dict = None, timeout: int = None, client_name: str = None, ssl_config: SSLConfig = None, log_communication_on_error: bool = None, max_tries: int = None, abstract_api=None)

Bases: object

This abstract root class contains the methods for HTTP requests used by all API classes. Also contains several tool methods for handling headers, url query parts and response error checking.

Constructor

A note regarding headers: If you set a value in the dict to None, it will not show up in the HTTP-request headers. Use this to erase entries from existing default headers or headers copied from apstract_api (when given).

Parameters:

• root_url – Root uri of the HIRO API, like https://core.engine.datagroup.de.

• session – The requests.Session object for the connection pool. Required.

• raise_exceptions – Raise exceptions on HTTP status codes that denote an error. Default is True.

• proxies – Proxy configuration for requests. Default is None.

• headers – Optional custom HTTP headers. Will be merged with the internal default headers. Default is None.

• timeout – Optional timeout for requests. Default is 600 (10 min).

• client_name – Optional name for the client. Will also be part of the “User-Agent” header unless headers is given with another value for “User-Agent”. Default is “hiro-graph-client”.

• ssl_config – Optional configuration for SSL connections. If this is omitted, the defaults of requests lib will be used.

• log_communication_on_error – Log socket communication when an error (status_code of HTTP Response) is detected. Default is not to do this.

• max_tries – Max tries for BACKOFF. Default is 2.

• abstract_api – Set all parameters by copying them from the instance given by this parameter. Overrides all other parameters except headers, which will be merged with existing ones.

_root_url: str = None

Servername and context path of the root of the API

_session: Session = None

Reference to the session information

_client_name: str = 'hiro-graph-client'

Used in header ‘User-Agent’

_headers: dict = {}

Common headers for HTTP requests.

ssl_config: SSLConfig

Security configuration and location of certificate files

_proxies: dict = None

Proxy configuration as needed by package ‘requests’.

_raise_exceptions: bool = True

Raise an exception when the status-code of results indicates an error

_timeout: int = 600

Timeout for requests-methods as needed by package ‘requests’.

_log_communication_on_error: bool = False

Dump request and response into logging on errors

_max_tries: int = 2

Retries for backoff

_get_max_tries()

get_root_url()

property user_agent

static _capitalize_header(name: str) → str

get_binary(url: str, accept: str = None) → Iterator[bytes]

Implementation of GET for binary data.

Parameters:

• url – Url to use

• accept – Mimetype for accept. Will be set to / if not given.

Returns:

Yields over raw chunks of the response payload.

post_binary(url: str, data: Any, content_type: str = None, expected_media_type: str = 'application/json') → Any

Implementation of POST for binary data.

Parameters:

• url – Url to use

• data – The payload to POST. This can be anything ‘requests.post(data=…)’ supports.

• content_type – The content type of the data. Defaults to “application/octet-stream” internally if unset.

• expected_media_type – The expected media type. Default is ‘application/json’. If this is set to ‘*’ or ‘/’, any media_type is accepted.

Returns:

The payload of the response

put_binary(url: str, data: Any, content_type: str = None, expected_media_type: str = 'application/json') → Any

Implementation of PUT for binary data.

Parameters:

• url – Url to use

• data – The payload to PUT. This can be anything ‘requests.put(data=…)’ supports.

• content_type – The content type of the data. Defaults to “application/octet-stream” internally if unset.

• expected_media_type – The expected media type. Default is ‘application/json’. If this is set to ‘*’ or ‘/’, any media_type is accepted.

Returns:

The payload of the response

get(url: str, expected_media_type: str = 'application/json') → Any

Implementation of GET

Parameters:

• url – Url to use

• expected_media_type – The expected media type. Default is ‘application/json’. If this is set to ‘*’ or ‘/’, any media_type is accepted.

Returns:

The payload of the response

post(url: str, data: Any, expected_media_type: str = 'application/json') → Any

Implementation of POST

Parameters:

• url – Url to use

• data – The payload to POST

• expected_media_type – The expected media type. Default is ‘application/json’. If this is set to ‘*’ or ‘/’, any media_type is accepted.

Returns:

The payload of the response

put(url: str, data: Any, expected_media_type: str = 'application/json') → Any

Implementation of PUT

Parameters:

• url – Url to use

• data – The payload to PUT

• expected_media_type – The expected media type. Default is ‘application/json’. If this is set to ‘*’ or ‘/’, any media_type is accepted.

Returns:

The payload of the response

patch(url: str, data: Any, expected_media_type: str = 'application/json') → Any

Implementation of PATCH

Parameters:

• url – Url to use

• data – The payload to PUT

• expected_media_type – The expected media type. Default is ‘application/json’. If this is set to ‘*’ or ‘/’, any media_type is accepted.

Returns:

The payload of the response

delete(url: str, expected_media_type: str = 'application/json') → Any

Implementation of DELETE

Parameters:

• url – Url to use

• expected_media_type – The expected media type. Default is ‘application/json’. If this is set to ‘*’ or ‘/’, any media_type is accepted.

Returns:

The payload of the response

_get_proxies() → dict

Create a copy of proxies if they exist or return None

Returns:

copy of self._proxies or None

static _merge_headers(headers: dict, override: dict) → dict

Merge headers with override.

Parameters:

• headers – Headers to merge into.

• override – Dict of headers that override headers. If a header key is set to value None, it will be removed from headers.

Returns:

The merged headers.

_get_headers(override: dict = None) → dict

Create a header dict for requests. Uses abstract method self._handle_token().

Parameters:

override – Dict of headers that override the internal headers. If a header key is set to value None, it will be removed from the headers.

Returns:

A dict containing header values for requests.

static _bool_to_external_str(value: Any) → str | None

Translate bool to string values “true” and “false” if value is a bool.

Parameters:

value – The value to check.

Returns:

String representation of the value or None.

static _get_query_part(params: dict) → str

Create the query part of an url. Keys in params whose values are set to None are removed.

Parameters:

params – A dict of params to use for the query.

Returns:

The query part of an url with a leading ‘?’, or an empty string when query is empty.

_parse_response(res: Response, expected_media_type: str = 'application/json') → Any

Parse the response of the backend.

Parameters:

• res – The result payload

• expected_media_type – The expected media type. Default is ‘application/json’. If this is set to ‘*’ or ‘/’, any media_type is accepted.

Returns:

The result payload. A json type when the result media_type within Content-Type is ‘application/json’ (usually a dict), a str otherwise.

Raises:

• RequestException – On HTTP errors.

• WrongContentTypeError – When the Media-Type of the Content-Type of the Response is not expected_media_type.

_log_communication(res: Response, request_body: bool = True, response_body: bool = True) → None

Log communication that flows across requests’ methods. Contains options to disable logging of the body portions of the requests to avoid dumping large amounts of data and breaking streaming of results.

This log does not log an exact binary representation of the transmitted bodies but uses the encoding defined in res to print it as strings.

Authorization and cookie headers will be obscured by only displaying the last six characters of their values.

Parameters:

• res – The response of a request. Also contains the request.

• request_body – Option to disable the logging of the request_body.

• response_body – Option to disable the logging of the response_body.

_check_status_error(res: Response) → None

Catch exceptions and rethrow them with additional information returned by the error response body.

Parameters:

res – The response

Raises:

requests.exceptions.HTTPError – When an HTTPError occurred.

_get_error_message(json_result: dict) → str

Extract error message from {“error”: { “message”: “(errormessage)” }} or {“error”:”(errormessage)” } if possible. Return the complete JSON as str if not.

Child API classes should overwrite this method if their error messages differ.

Parameters:

json_result – The json dict containing the error message.

Returns:

The extracted error message.

static _check_content_type(res: Response, expected_media_type: str) → None

Raise an Exception if the Content-Type header of the response does not contain the expected_media_type. Compares only the media-type portion of the header (by splitting at ‘;’).

Parameters:

• res – The response object

• expected_media_type – The expected Media-Type.

Raises:

WrongContentTypeError – When the Media-Type of the Content-Type is not expected_media_type or the header is missing completely.

_check_response_ok(res: Response) → bool

Do not rely on res.ok. Everything not between 200 and 399 is an error.

Child API classes should overwrite this method if other custom and valid status codes might occur there.

Parameters:

res – The response object

Returns:

True on good response, false otherwise.

_check_response(res: Response) → None

Root method. No response checking here.

Parameters:

res – The result payload

_handle_token() → str | None

Just return None, therefore a header without Authorization will be created in self._get_headers().

Does not try to obtain or refresh a token.

Returns:

Always None here, derived classes should return a token string.

class hiro_graph_client.clientlib.GraphConnectionHandler(root_url: str = None, custom_endpoints: dict = None, version_info: dict = None, pool_maxsize: int = None, pool_block: bool = None, connection_handler=None, *args, **kwargs)

Bases: AbstractAPI

Contains information about a Graph Connection. This class also handles resolving the current api endpoints. Also creates the requests.Session which will be shared among the API Modules using this connection.

Constructor

Example for custom_endpoints (see params below):

{
    "graph": "/api/graph/7.2",
    "auth": "/api/auth/6.2",
    "action-ws": ("/api/action-ws/1.0", "action-1.0.0")
}

This object creates the requests.Session and requests.adapters.HTTPAdapter for this root_url. The pool_maxsize of such a session can be set via the parameter in the constructor. When a TokenApiHandler is shared between different API objects (like HiroGraph, HiroApp, etc.), this session and its pool are also shared.

See parent AbstractAPI for a description of all remaining parameters.

Parameters:

• root_url – Root url for HIRO, like https://core.engine.datagroup.de.

• custom_endpoints – Optional map of {name:endpoint_path, …} that overrides or adds to the endpoints taken from /api/version. Example see above.

• version_info – Optional full dict of the JSON result received via /api/version. Setting this will use it as the valid API version information and avoids the internal API-call altogether.

• pool_maxsize – Size of a connection pool for a single connection. See requests.adapters.HTTPAdapter. Default is 10. pool_maxsize is ignored when session is set.

• pool_block – Block any connections that exceed the pool_maxsize. Default is False: Allow more connections, but do not cache them. See requests.adapters.HTTPAdapter. pool_block is ignored when session is set.

• connection_handler – Copy parameters from this already existing connection handler. Overrides all other parameters.

• args – Unnamed parameter passthrough for parent class.

• kwargs – Named parameter passthrough for parent class.

_pool_maxsize = 10

Default pool_maxsize for requests.adapters.HTTPAdapter.

_pool_block = False

As used by requests.adapters.HTTPAdapter.

_lock: RLock

Reentrant mutex for thread safety

custom_endpoints: dict = None

Override API endpoints.

_version_info: dict = None

Stores the result of /api/version

static _remove_slash(endpoint: str) → str

get_api_endpoint_of(api_name: str) → str

Determines endpoints of the API names. Loads and caches the current API information if necessary.

Parameters:

api_name – Name of the HIRO API

Returns:

Full url of endpoint for this API

get_websocket_config(api_name: str) → Tuple[str, str, str | None, int | None, dict | None]

Determines endpoints for websockets of the API names. Loads and caches the current API information if necessary. If proxies have been given, the key of the proxy picked needs to be “ws” or “wss” respectively.

Parameters:

api_name – Name of the HIRO API for websockets

Returns:

Tuple of full url of websocket for this API, its protocol, its proxy_host, its proxy port and proxy auth (if any).

get_version(force_update: bool = False) → dict

HIRO REST query API: GET self._endpoint + ‘/api/version’

Parameters:

force_update – Force updating the internal cache with version_info via API request.

Returns:

The result payload

class hiro_graph_client.clientlib.AbstractTokenApiHandler(*args, **kwargs)

Bases: GraphConnectionHandler

Root class for all TokenApiHandler classes. This adds token handling.

Constructor

See parent GraphConnectionHandler for a full description of all remaining parameters.

Parameters:

• args – Unnamed parameter passthrough for parent class.

• kwargs – Named parameter passthrough for parent class.

property token: str

Return the current token.

decode_token() → dict

Return a dict with the decoded token payload from the internal token. This payload contains detailed information about what this token has access to.

Returns:

The dict with the decoded token payload.

Raises:

AuthenticationTokenError – When the token does not contain the base64 encoded data payload.

static decode_token_ext(token: str) → dict

Return a dict with the decoded token payload. This payload contains detailed information about what this token has access to.

Parameters:

token – The token to decode.

Returns:

The dict with the decoded token payload.

Raises:

AuthenticationTokenError – When the token does not contain the base64 encoded data payload.

abstractmethod refresh_token() → None

Refresh the current token.

abstractmethod revoke_token(token_hint: str = 'revoke_token') → None

Revoke a token.

Parameters:

token_hint – The default is to revoke the “revoke_token”. The alternative is “access_token”.

abstractmethod refresh_time() → int | None

Calculate the time after which the token should be refreshed in milliseconds.

Returns:

The timestamp in ms after which the token shall be refreshed or None if the token cannot be refreshed on its own.

class hiro_graph_client.clientlib.FixedTokenApiHandler(token: str = None, *args, **kwargs)

Bases: AbstractTokenApiHandler

TokenApiHandler for a fixed token.

Constructor

See parent AbstractTokenApiHandler for a full description of all remaining parameters.

Parameters:

• token – The fixed token for the HTTP requests.

• args – Unnamed parameter passthrough for parent class. See AbstractTokenApiHandler.

• kwargs – Named parameter passthrough for parent class. See AbstractTokenApiHandler.

_token: str

Stores the fixed token.

property token: str

Return the current token.

refresh_token() → None

Refresh the current token.

revoke_token(token_hint: str = 'revoke_token') → None

Revoke a token.

Parameters:

token_hint – The default is to revoke the “revoke_token”. The alternative is “access_token”.

refresh_time() → int | None

Returns:

Always none

class hiro_graph_client.clientlib.EnvironmentTokenApiHandler(env_var: str = 'HIRO_TOKEN', *args, **kwargs)

Bases: AbstractTokenApiHandler

TokenApiHandler for a fixed token given as an environment variable.

Constructor

See parent AbstractTokenApiHandler for a full description of all remaining parameters.

Parameters:

• env_var – Name of the environment variable with the token.

• args – Unnamed parameter passthrough for parent class.

• kwargs – Named parameter passthrough for parent class.

_env_var: str

Stores the name of the environment variable.

property token: str

Return the current token.

refresh_token() → None

Refresh the current token.

revoke_token(token_hint: str = 'revoke_token') → None

Revoke a token.

Parameters:

token_hint – The default is to revoke the “revoke_token”. The alternative is “access_token”.

refresh_time() → int | None

Returns:

Always none

class hiro_graph_client.clientlib.TokenInfo(token: str = None, refresh_token: str = None, expires_at: int = -1, refresh_offset: int = 5000)

Bases: object

This class stores token information from the auth api.

Constructor

Parameters:

• token – The token string

• refresh_token – A refresh token

• expires_at – Token expiration in ms since epoch

• refresh_offset – Offset in milliseconds that will be subtracted from the expiry time so a token will be refreshed in time. Default is 5 seconds.

token: str = None

The token string

expires_at = -1

Token expiration in ms since epoch

refresh_token: str = None

The refresh token to use - if any.

last_update = 0

Timestamp of when the token has been fetched in ms.

refresh_offset = 5000

Milliseconds of offset for token expiry

static get_epoch_millis() → int

Get timestamp

Returns:

Current epoch in milliseconds

parse_token_result(res: dict, what: str) → None

Parse the result payload and extract token information.

Parameters:

• res – The result payload from the backend.

• what – What token command has been issued (for error messages).

Raises:

• TokenUnauthorizedError – When the token request returned error 401. This usually means, that this token has expired.

• AuthenticationTokenError – When the token request returned any other error.

expired() → bool

Check token expiration.

Returns:

True when the token has been expired (expires_at - refresh_offset) <= get_epoch_mills(). If no expires_at is available, always return False since this token would never expire.

refresh_time() → int | None

Calculate the time after which the token should be refreshed in milliseconds.

Returns:

expires_at - refresh_offset (in ms) or None if refresh is not possible.

clear_token_data(access_token_only: bool)

Handle internal data on a token revoke.

Parameters:

access_token_only – True if only the access token gets revoked.

class hiro_graph_client.clientlib.PasswordAuthTokenApiHandler(username: str = None, password: str = None, client_id: str = None, client_secret: str = None, secure_logging: bool = True, *args, **kwargs)

Bases: AbstractTokenApiHandler

API Tokens will be fetched using this class. It does not handle any automatic token fetching, refresh or token expiry. This has to be checked and triggered by the caller.

The methods of this class are thread-safe, so it can be shared between several HIRO objects.

It is built this way to avoid endless calling loops when resolving tokens.

Constructor

See parent AbstractTokenApiHandler for a full description of all remaining parameters.

Parameters:

• username – Username for authentication

• password – Password for authentication

• client_id – OAuth client_id for authentication

• client_secret – OAuth client_secret for authentication

• secure_logging – If this is enabled, payloads that might contain sensitive information are not logged.

• args – Unnamed parameter passthrough for parent class.

• kwargs – Named parameter passthrough for parent class.

_username: str

_password: str

_client_id: str

_client_secret: str

_secure_logging: bool = True

Avoid logging of sensitive data.

_token_info: TokenInfo = None

Contains all token information

_lock: RLock

Reentrant mutex for thread safety

property endpoint

property token: str

Get the token. Get or refresh it if necessary.

_log_communication(res: Response, request_body: bool = True, response_body: bool = True) → None

Logging under a secure aspect. Hides sensitive information unless self._secure_logging is set to False.

Parameters:

• res – The response of a request. Also contains the request.

• request_body – Option to disable the logging of the request_body. If set to True, will only remain True internally when self._secure_logging is set to False.

• response_body – Option to disable the logging of the response_body. If set to True, will only remain True internally when self._secure_logging is set to False or res.status_code != 200.

get_token() → None

Construct a request to obtain a new token. API self._endpoint + ‘/app’

Raises:

AuthenticationTokenError – When no auth_endpoint is set.

refresh_token() → None

Construct a request to refresh an existing token. API self._endpoint + ‘/refresh’.

Raises:

AuthenticationTokenError – When no auth_endpoint is set.

revoke_token(token_hint: str = 'refresh_token') → None

Revoke a token.

Parameters:

token_hint – The default is to revoke the “revoke_token”. The alternative is “access_token”. (has effect after auth api version 6.6)

refresh_time() → int | None

Calculate refresh time.

Returns:

Timestamp after which the token becomes invalid. Returns None if token cannot be refreshed.

_check_response(res: Response) → None

Response checking. When a refresh_token is present and status_code is 401, raise TokenUnauthorizedError. This can happen when a refresh-token is not valid anymore.

Parameters:

res – The result payload

Raises:

TokenUnauthorizedError – Raised to trigger a retry via self.get_token() in self.refresh_token().

_handle_token() → str | None

Just return None, therefore a header without Authorization will be created in self._get_headers().

Does not try to obtain or refresh a token.

Returns:

token given.

class hiro_graph_client.clientlib.AuthenticatedAPIHandler(api_handler: AbstractTokenApiHandler, api_name: str)

Bases: AbstractAPI

Python implementation for accessing a REST API with authentication.

Constructor

Parameters:

• api_name – Name of the API to use.

• api_handler – External API handler.

_api_handler: AbstractTokenApiHandler

Stores the TokenApiHandler used for this API.

_api_name: str

Name of the API.

property endpoint: str

_check_response(res: Response) → None

Response checking. Tries to refresh the token on status_code 401, then raises RequestException to try again using backoff.

Parameters:

res – The result payload

Raises:

requests.exceptions.RequestException – When an error 401 occurred and the token has been refreshed.

_handle_token() → str | None

Try to return a valid token by obtaining or refreshing it.

Returns:

A valid token.

exception hiro_graph_client.clientlib.AuthenticationTokenError(message: str, code: int = None)

Bases: Exception

Class for unrecoverable failures with access tokens. Contains a message and an optional message code. If the code is None, no code will be printed in __str__().

message: str

code: int

exception hiro_graph_client.clientlib.TokenUnauthorizedError(message: str, code: int = None)

Bases: AuthenticationTokenError

Child of AuthenticationTokenErrors. Used when tokens expire with error 401.

exception hiro_graph_client.clientlib.FixedTokenError(message: str, code: int = None)

Bases: AuthenticationTokenError

Child of AuthenticationTokenErrors. Used when tokens are fixed and cannot be refreshed.

exception hiro_graph_client.clientlib.WrongContentTypeError

Bases: Exception

When the Content-Type of the result is unexpected, i.e. ‘application/json’ was expected, but something else got returned.

hiro_graph_client.eventswebsocket module

hiro_graph_client.eventswebsocket.logger = <Logger hiro_graph_client.eventswebsocket (WARNING)>

The logger for this module

class hiro_graph_client.eventswebsocket.EventMessage(event_id: str, event_timestamp: int, event_body: dict, event_type: str, event_metadata: dict, event_nanotime: int)

Bases: object

The structure of an incoming events message

Constructor

Parameters:

• event_id – ID

• event_timestamp – Timestamp in milliseconds

• event_body – Body dict

• event_type – Type of event. CREATE, UPDATE or DELETE.

• event_metadata – Additional metadata.

• event_nanotime – Nanotime for the event

id: str

timestamp: int

body: dict

type: str

metadata: dict

nanotime: int

classmethod parse(message: str)

Parameters:

message – The message received from the websocket. Will be decoded here.

Returns:

The EventMessage or None if this is not an EventMessage (type or id are missing).

class hiro_graph_client.eventswebsocket.EventsFilter(filter_id: str, filter_content: str, filter_type: str = None)

Bases: object

The event filter structure

Constructor

Parameters:

• filter_id – Unique name/id of the filter

• filter_content – jfilter specification for the filter.

• filter_type – Type of filter. Only ‘jfilter’ (the default when this is None) is possible here atm.

id: str

content: str

type: str

to_dict() → dict

class hiro_graph_client.eventswebsocket.AbstractEventsWebSocketHandler(api_handler: AbstractTokenApiHandler, events_filters: List[EventsFilter], scopes: List[str] = None, query_params: Dict[str, str] = None)

Bases: AbstractAuthenticatedWebSocketHandler

A handler for issue events

Constructor

Parameters:

• api_handler – The TokenApiHandler for this WebSocket.

• events_filters – Filters for the events. These have to be set or the flood of incoming events will be too big.

• scopes – List of ids of non-default scopes to subscribe. These are ogit/_id of the “ogit/DataScope”s (i.e. the scope of your instance) you want to subscribe to. Default is None, which means: Use default scope.

• query_params – URL Query parameters for this specific websocket. Use Dict[str,str] only here, i.e set {“allscopes”: “false”} instead of {“allscopes”: False}. The default here is to set {‘allscopes’: ‘false’}.

_events_filter_messages: Dict[str, EventsFilter] = {}

_initial_messages_lock: RLock

Lock for _events_filter_messages and _scopes

_token_scheduler: BackgroundScheduler

_scopes: List[str] = []

on_open(ws: WebSocketApp)

Register the filters when websocket opens. If this fails, the websocket gets closed again.

Parameters:

ws – The WebSocketApp

Raises:

WebSocketFilterException – When setting the filters failed.

on_close(ws: WebSocketApp, code: int = None, reason: str = None)

Cancel the self._token_refresh_thread. Registered filters remain as they are.

Parameters:

• ws – The WebSocketApp

• code

• reason

on_message(ws: WebSocketApp, message: str)

Create an EventMessage from the incoming message and hand it over to self.on_event.

Parameters:

• ws – The WebSocketApp

• message – The raw message as string

on_error(ws: WebSocketApp, error: Exception)

Does nothing here.

Parameters:

• ws – The WebSocketApp

• error – Exception

on_event(message: EventMessage) → None

Catches all event messages. Distributes them between self.on_create, self.on_update or self.on_delete by default. Overwrite this if you want a catch-all for all event messages.

Parameters:

message – The incoming EventMessage

on_create(message: EventMessage) → None

Called by CREATE events. Skeleton function to be overwritten if needed.

Parameters:

message – The incoming EventMessage

on_update(message: EventMessage) → None

Called by UPDATE events. Skeleton function to be overwritten if needed.

Parameters:

message – The incoming EventMessage

on_delete(message: EventMessage) → None

Called by DELETE events. Skeleton function to be overwritten if needed.

Parameters:

message – The incoming EventMessage

static _get_events_register_message(events_filter: EventsFilter) → str

static _get_subscribe_scope_message(scope_id: str) → str

add_events_filter(events_filter: EventsFilter) → None

remove_events_filter(events_filter_id: str) → None

clear_events_filters() → None

subscribe_scope(scope_id: str)

remove_scope(scope_id: str)

This only removes the scope from the internal list since there is no ‘unsubscribe’. You need to restart the websocket for this change to take effect.

_set_next_token_refresh()

_token_refresh_thread()

exception hiro_graph_client.eventswebsocket.WebSocketFilterException

Bases: WebSocketException

On errors with setting or parsing filter information.

hiro_graph_client.iamclient module

class hiro_graph_client.iamclient.HiroIam(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO IAM REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml

Constructor

Parameters:

api_handler – External API handler.

create_account(data: dict, import_flag: bool = None) → dict

create an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/post_accounts

Parameters:

• import_flag – Default is false

• data – The dict with the account data.

Returns:

Dict with the result

update_account(account_id: str, data: dict) → dict

update an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/post_accounts__id_

Parameters:

• account_id – ogit/_id of the ogit/Auth/Account

• data – The dict with the account data.

Returns:

Dict with the result

get_account(account_id: str, profile: bool = None) → dict

gets an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/get_accounts__id_

Parameters:

• profile – return account with profile. Default false.

• account_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result

delete_account(account_id: str) → dict

deletes an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/delete_accounts__id_

Parameters:

account_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result

activate_account(node_id: str) → dict

activates an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/patch_accounts__id__activate

Parameters:

node_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result

get_account_avatar(account_id: str) → Iterator[bytes]

gets avatar of account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/get_accounts__id__avatar

Parameters:

account_id – ogit/_id of the ogit/Auth/Account

Returns:

Binary content of the avatar

put_account_avatar(account_id: str, data: Any, content_type: str = 'image/png') → str

sets the avatar of account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/put_accounts__id__avatar

Parameters:

• account_id – ogit/_id of the ogit/Auth/Account

• data – Binary data for image of avatar.

• content_type – Content-Type. Default: image/png

Returns:

The result payload / size of the avatar in bytes.

deactivate_account(account_id: str, reason: str) → dict

deactivates an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/patch_accounts__id__deactivate

Parameters:

• reason – reason of deactivation of an ogit/Auth/Account. Available values : UserDeactivated, AdminDeactivated, PasswordExpired, AutoDeactivated, None

• account_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result

put_account_password(account_id: str, data: dict) → dict

set password of account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/put_accounts__id__password

Parameters:

• account_id – ogit/_id of the ogit/Auth/Account

• data – The dict with the new password data.

Returns:

Dict with the result

get_account_profile(account_id: str = None, profile_id: str = None) → dict

get profile of account

You need to specify either profile_id or account_id.

With account_id: https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/get_accounts__id__profile

With profile_id: https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/get_accounts_profile__profileId_

Parameters:

• profile_id – ogit/_id of the ogit/Auth/AccountProfile

• account_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result or an empty dict if neither account_id nor profile_id are given.

get_account_teams(account_id: str, include_virtual: bool = None) → dict

get teams of account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/get_accounts__id__teams

Parameters:

• include_virtual – return virtual teams in output. Default false.

• account_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result

update_account_profile(profile_id: str, data: dict) → dict

updates an account profile https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/post_accounts_profile__profileId_

Parameters:

• data – Dict with the new profile data.

• profile_id – ogit/_id of the ogit/Auth/AccountProfile

Returns:

Dict with the result

create_scope(data: dict) → dict

creates a DataScope https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_DataScope/post_scope

Parameters:

data – Dict with the new scope data.

Returns:

Dict with the result

get_scope(scope_id: str) → dict

retrieves a DataScope https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_DataScope/get_scope__id_

Parameters:

scope_id – ogit/_id of the ogit/Auth/DataScope

Returns:

Dict with the result

update_scope(scope_id: str, data: dict) → dict

updates a DataScope https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_DataScope/put_scope__id_

Parameters:

• scope_id – ogit/_id of the ogit/Auth/DataScope

• data – Dict with the new scope data.

Returns:

Dict with the result

create_organization(data: dict) → dict

creates an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/post_organization

Parameters:

data – Dict with the new organization data.

Returns:

Dict with the result

get_organization_configuration(organization_id: str) → dict

gets configuration of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__configuration

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

update_organization_configuration(organization_id: str, data: dict) → dict

updates configuration of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/put_organization__id__configuration

Parameters:

• organization_id – ogit/_id of the ogit/Auth/Organization

• data – Dict with the new organization data.

Returns:

Dict with the result

get_organization_datasets(organization_id: str) → dict

gets datasets of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__datasets

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_organization_domains(organization_id: str) → dict

gets domains of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__domains

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_organization_roleassignments(organization_id: str) → dict

gets roleassignments of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__roleassignments

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_organization_scopes(organization_id: str) → dict

gets scopes of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__scopes

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_organization_teams(organization_id: str) → dict

gets teams of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__teams

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_organization_avatar(organization_id: str) → Iterator[bytes]

gets avatar of Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__avatar

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Binary content of the avatar

put_organization_avatar(organization_id: str, data: Any, content_type: str = 'image/png') → str

sets the avatar of Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/put_organization__id__avatar

Parameters:

• organization_id – ogit/_id of the ogit/Auth/Organization

• data – Binary data for image of avatar.

• content_type – Content-Type. Default: image/png

Returns:

The result payload / size of the avatar in bytes.

create_domain(data: dict) → dict

creates an Org Domain https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_OrgDomain/post_domain

Parameters:

data – Dict with the new domain data.

Returns:

Dict with the result

get_domain(domain_id: str) → dict

retrieves an Org Domain https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_OrgDomain/get_domain__id_

Parameters:

domain_id – ogit/_id of the ogit/Auth/OrgDomain

Returns:

Dict with the result

delete_domain(domain_id: str) → dict

deletes an Org Domain https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_OrgDomain/delete_domain__id_

Parameters:

domain_id – ogit/_id of the ogit/Auth/OrgDomain

Returns:

Dict with the result

get_domain_organization(domain_id: str) → dict

retrieves an Organization of Org Domain https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_OrgDomain/get_domain__id__organization

Parameters:

domain_id – ogit/_id of the ogit/Auth/OrgDomain

Returns:

Dict with the result

create_role(data: dict) → dict

creates an Auth Role https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Role/post_role

Parameters:

data – Dict with the new role data.

Returns:

Dict with the result

update_role(role_id: str, data: dict) → dict

updates an Auth Role https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Role/put_role__id_

Parameters:

• role_id – ogit/_id of the ogit/Auth/Role

• data – Dict with the new role data.

Returns:

Dict with the result

get_role(role_id: str) → dict

retrieves an Auth Role https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Role/get_role__id_

Parameters:

role_id – ogit/_id of the ogit/Auth/Role

Returns:

Dict with the result

delete_role(role_id: str) → dict

deletes an Auth Role https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Role/delete_role__id_

Parameters:

role_id – ogit/_id of the ogit/Auth/Role

Returns:

Dict with the result

get_roles() → dict

retrieves public roles https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Role/get_roles

Returns:

Dict with the result

create_roleassignment(data: dict) → dict

creates an Auth RoleAssignment https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_RoleAssignment/post_roleassignment

Parameters:

data – Dict with the new roleassignment data.

Returns:

Dict with the result

get_roleassignment(roleassignment_id: str) → dict

retrieves an Auth RoleAssignment https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_RoleAssignment/get_roleassignment__id_

Parameters:

roleassignment_id – ogit/_id of the ogit/Auth/RoleAssignment

Returns:

Dict with the result

delete_roleassignment(roleassignment_id: str) → dict

deletes an Auth RoleAssignment https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_RoleAssignment/delete_roleassignment__id_

Parameters:

roleassignment_id – ogit/_id of the ogit/Auth/RoleAssignment

Returns:

Dict with the result

create_team(data: dict) → dict

creates an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/post_team

Parameters:

data – Dict with the new team data.

Returns:

Dict with the result

update_team(team_id: str, data: dict) → dict

updates an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/put_team__id_

Parameters:

• team_id – ogit/_id of the ogit/Auth/Team

• data – Dict with the new team data.

Returns:

Dict with the result

get_team(team_id: str) → dict

retrieves an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/get_team__id_

Parameters:

team_id – ogit/_id of the ogit/Auth/Team

Returns:

Dict with the result

delete_team(team_id: str) → dict

deletes an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/delete_team__id_

Parameters:

team_id – ogit/_id of the ogit/Auth/Team

Returns:

Dict with the result

get_team_members(team_id: str, profile: bool = None) → dict

gets members of an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/get_team__id__members

Parameters:

• profile – return account with profile. Default False.

• team_id – ogit/_id of the ogit/Auth/Team

Returns:

Dict with the result

add_team_members(team_id: str, data: dict) → dict

adds members to an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/post_team__id__members_add

Parameters:

• team_id – ogit/_id of the ogit/Auth/Team

• data – dict with the account data

Returns:

Dict with the result

remove_team_members(team_id: str, data: dict) → dict

adds members to an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/post_team__id__members_remove

Parameters:

• team_id – ogit/_id of the ogit/Auth/Team

• data – dict with the account data

Returns:

Dict with the result

create_dataset(data: dict) → dict

creates a DataSet https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_DataSet/post_dataset

Parameters:

data – Dict with the new dataset data.

Returns:

Dict with the result

update_dataset(dataset_id: str, data: dict) → dict

updates a DataSet https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_DataSet/put_dataset__id_

Parameters:

• dataset_id – ogit/_id of the ogit/Auth/DataSet

• data – Dict with the new dataset data.

Returns:

Dict with the result

get_dataset(dataset_id: str) → dict

retrieves a DataSet https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_DataSet/get_dataset__id_

Parameters:

dataset_id – ogit/_id of the ogit/Auth/DataSet

Returns:

Dict with the result

delete_dataset(dataset_id: str) → dict

deletes a DataSet https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_DataSet/delete_dataset__id_

Parameters:

dataset_id – ogit/_id of the ogit/Auth/DataSet

Returns:

Dict with the result

hiro_graph_client.kiclient module

class hiro_graph_client.kiclient.HiroKi(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO Ki REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/ki.yaml

Constructor

Parameters:

api_handler – External API handler.

check(data: dict) → dict

Ask if KI is valid

HIRO REST query API: POST self._endpoint + ‘/check

Parameters:

data – KI validation request data. See https://core.engine.datagroup.de/help/specs/?url=definitions/ki.yaml#/[Validatation]_Validate/post_check

Returns:

The result payload

_get_error_message(json_result: dict) → str

Intercept special error messages. These have a key ‘status’ in their dict.

Parameters:

json_result – The incoming JSON containing error information.

Returns:

The error message.

hiro_graph_client.variablesclient module

class hiro_graph_client.variablesclient.HiroVariables(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO Variables REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/variables.yaml

Constructor

Parameters:

api_handler – External API handler.

create_variable(data: dict, subtype: str = None) → dict

Creates new variable

HIRO REST query API: PUT self._endpoint

Parameters:

• data – Variable content. See https://core.engine.datagroup.de/help/specs/?url=definitions/variables.yaml#/[Variables]/put_

• subtype – Query variable. Value of ogit/subType. Optional.

Returns:

The result payload

get_variable(name: str) → dict

Get variable by name. (synonym for self.define(name))

HIRO REST query API: GET self._endpoint + ‘/define’

:param name Variable name. Required. :return: The result payload

define(name: str) → dict

Get variable by name.

HIRO REST query API: GET self._endpoint + ‘/define’

:param name Variable name. Required. :return: The result payload

like(name: str, description: str = None, subtype: str = None, full: bool = None) → List | Dict

Search for similar variables.

HIRO REST query API: GET self._endpoint + ‘/like’

:param name Variable name. Required. :param description: Search by variable description. Optional. :param subtype: Value of ogit/subType. Optional. :param full: Return full variable, not just a name. Optional. Default false. :return: The result payload. Either a list of dict or a dict with an error message.

suggest(name: str, subtype: str = None, full: bool = None) → List | Dict

Search for similar variables.

HIRO REST query API: GET self._endpoint + ‘/suggest’

:param name Variable name. Required. :param subtype: Value of ogit/subType. Optional. :param full: Return full variable, not just a name. Optional. Default false. :return: The result payload. Either a list of dict or a dict with an error message.

hiro_graph_client.version module

hiro_graph_client.websocketlib module

hiro_graph_client.websocketlib.logger = <Logger hiro_graph_client.websocketlib (WARNING)>

The logger for this module

class hiro_graph_client.websocketlib.ErrorMessage(code, message)

Bases: object

The structure of an incoming error message

Constructor

Parameters:

• code – Numerical error code of the error

• message – Error message

code: int

message: str

classmethod parse(message: str)

Parameters:

message – The message received from the websocket. Will be decoded here.

Returns:

The new error message or None if this is not an error message.

to_dict() → dict

class hiro_graph_client.websocketlib.ReaderStatus(*values)

Bases: str, Enum

The states the reader thread can be in.

NONE = 'Not started'

STARTING = 'Starting'

RUNNING_PRELIMINARY = 'Running preliminary (status of token unknown)'

RUNNING = 'Running'

RESTARTING = 'Restarting'

DONE = 'Finished normally'

FAILED = 'Finished because of error'

class hiro_graph_client.websocketlib.AbstractAuthenticatedWebSocketHandler(api_handler: AbstractTokenApiHandler, api_name: str, query_params: Dict[str, str] = None, timeout: int = 5, auto_reconnect: bool = True, remote_exit_codes: List[int] = None)

Bases: object

The basic class for all WebSockets.

Create the websocket

Parameters:

• api_handler – Required: The api handler for authentication.

• api_name – The name of the ws api.

• query_params – URL Query parameters for this specific websocket. Use Dict[str,str] only here, i.e. set {“allscopes”: “false”} instead of {“allscopes”: False}.

• timeout – The timeout for websocket messages. Default is 5sec.

• auto_reconnect – Try to create a new websocket automatically when self.send() fails. If this is set to False, a WebSocketException will be raised instead. The default is True.

• remote_exit_codes – A list of close codes that can come in from the remote side. If one of the codes in this list matches the remote close code, self.run_forever() will exit instead of trying to reconnect. The default is None -> reconnect always. See https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1

_reconnect_delay: int

_ws: WebSocketApp | None = None

MAX_RETRIES = 3

_url: str

_protocol: str

_proxy_hostname: str

_proxy_port: str

_proxy_auth: dict

_api_handler: AbstractTokenApiHandler

_auto_reconnect: bool

_reader_status: ReaderStatus

Tracks the status of the internal reader thread.

_reader_guard: Condition

Meant to protect the startup sequence. *

_ws_guard: RLock

Protects the websocket reference for startup and restart.

_backoff_condition: Condition

_remote_exit_codes: List[int] = []

A list of remote exit codes that will cause the websocket to not reconnect.

_set_error(error: Exception) → None

Log the Exception, store it and set the status to FAILED.

Parameters:

error – The Exception to store.

_check_message(ws: WebSocketApp, message: str) → None

Look for error 401. Try to reconnect with a new token when this is encountered. Set status to ReaderStatus.RESTARTING when a token is no longer valid on error code 401. Set status to ReaderStatus.FAILED when error 401 is received and the token was never valid.

Parameters:

• ws – WebSocketApp

• message – Incoming message as string

_check_open(ws: WebSocketApp) → None

First signal, that the connection has been opened successfully. Then call self.on_open and set self._reader_status to CHECKING_TOKEN if opening succeeded.

Parameters:

ws – WebSocketApp

_check_close(ws: WebSocketApp, code: int, reason: str)

Call self.on_close. When code and reason are None, the stop has been issued locally and not by the remote side.

Parameters:

• ws – WebSocketApp

• code – Code of stop message

• reason – Reason str of stop message

_check_error(ws: WebSocketApp, error: Exception) → None

Just log the error and propagate it to self.on_error.

Parameters:

• ws – WebSocketApp

• error – Exception

_backoff(reconnect_delay: int) → int

Sleeps for reconnect_delay seconds, then returns the delay in seconds for the next try.

Parameters:

reconnect_delay – Delay in seconds to wait.

Returns:

Next value for the delay.

_close(status: str = 1000, reason: str = None)

Close the websocket.

Parameters:

• status – Status code for close message.

• reason – The close message.

abstractmethod on_open(ws: WebSocketApp)

abstractmethod on_close(ws: WebSocketApp, code: int = None, reason: str = None)

abstractmethod on_message(ws: WebSocketApp, message: str)

abstractmethod on_error(ws: WebSocketApp, error: Exception)

start() → None

Create the WebSocketApp

Raises:

WebSocketException – When the creation of the WebSocketApp fails.

_stop(wait_for_shutdown: bool = True) → None

Intentionally closes this websocket. When called by the same thread as self.run_forever() (i.e. by signal handler), wait_for_shutdown needs to be set to False or the method will deadlock.

Parameters:

wait_for_shutdown – Wait until self.run_forever() has returned. Default is True.

stop() → None

Intentionally closes this websocket and waits for self.run_forever() to return. Call this from another thread than self.run_forever().

signal_stop() → None

Intentionally closes this websocket without waiting. This is meant to be used in signal handlers.

restart() → None

Closes the websocket and starts a new one. This needs to be called from another thread than self.run_forever() or it will deadlock.

Raises:

RuntimeError – When no self._ws exists.

run_forever()

Runs and receives incoming messages.

is_active() → bool

Checks whether the websocket is still active. :return: self._reader_status not in [ReaderStatus.NONE, ReaderStatus.DONE, ReaderStatus.FAILED]

send(message: str) → None

Send message across the websocket.

Parameters:

message – Message as string

Raises:

• WebSocketException – When self._auto_reconnect is False: If a message cannot be sent and all retries have been exhausted.

• WebSocketConnectionClosedException – When the websocket is not available at all.

Module contents

Package which contains the classes to communicate with HIRO Graph.

class hiro_graph_client.HiroGraph(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO Graph REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml

Constructor

Parameters:

api_handler – External API handler.

connect_nodes(from_node_id: str, verb: str, to_node_id: str) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Verb/post_connect__type_

Parameters:

• from_node_id – ogit/_id of the source node/vertex

• verb – verb for the connection

• to_node_id – ogit/_id of the target node/vertex

Returns:

The result payload

create_node(data: dict, obj_type: str, return_id=False) → dict | str

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Entity/post_new__type_

Parameters:

• data – Payload for the new node/vertex

• obj_type – ogit/_type of the new node/vertex

• return_id – Return only the ogit/_id as string. Default is False to return everything as dict.

Returns:

The result payload

delete_node(node_id: str) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Entity/delete__id_

Parameters:

node_id – ogit/_id of the node/vertex

Returns:

The result payload

disconnect_nodes(from_node_id: str, verb: str, to_node_id: str) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Verb/delete__id_

Parameters:

• from_node_id – ogit/_id of the source node/vertex

• verb – verb for the connection

• to_node_id – ogit/_id of the target node/vertex

Returns:

The result payload

get_attachment(node_id: str, content_id: str = None, include_deleted: bool = None) → Iterator[bytes]

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Blob/get__id__content

Parameters:

• node_id – Id of the attachment node

• content_id – Id of the content within the attachment node. Default is None.

• include_deleted – Whether to be able to access deleted content: Default is False

Returns:

Returns generator over byte chunks from the response body payload.

get_events(ts_from: int = 0, ts_to: int = datetime.datetime(2025, 4, 7, 14, 59, 1, 479679), ogit_type: str = None, jfilter: str = None) → dict

Replays events from history

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Events]_History/get_events_

Parameters:

• ts_from – timestamp in ms where to start returning entries (default: 0)

• ts_to – timestamp in ms where to end returning entries (default: now)

• jfilter – jfilter string to limit matching results

• ogit_type – Entity or Verb ogit/_type for filtering result based on this type

Returns:

The result payload

get_history(node_id: str, ts_from: int = 0, ts_to: int = datetime.datetime(2025, 4, 7, 14, 59, 1, 479675), history_type: str = 'element', version: str = None, vid: str = None, limit=-1, offset=0, include_deleted: bool = None, meta: bool = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_History/get__id__history

Parameters:

• node_id – Id of the node

• ts_from – timestamp in ms where to start returning entries (default: 0)

• ts_to – timestamp in ms where to end returning entries (default: now)

• history_type – Response format: full - full event, element - only event body, diff - diff to previous event. (default: ‘element’)

• version – get entry with specific ogit/_v value

• vid – get specific version of Entity matching ogit/_v-id

• limit – limit of entries to return (default: -1).

• offset – offset where to start returning entries (default: 0)

• include_deleted – allow to get if ogit/_is-deleted=true (default: false)

• meta – return list type attributes with metadata (default: false)

Returns:

The result payload

get_node(node_id: str, fields: str = None, meta: bool = None, include_deleted: bool = None, vid: str = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Entity/get__id_

Parameters:

• node_id – ogit/_id of the node/vertex or edge

• fields – Filter for fields

• include_deleted – allow to get if ogit/_is-deleted=true

• vid – get specific version of Entity matching ogit/_v-id

• meta – List detailed metainformations in result payload

Returns:

The result payload

get_node_by_xid(node_id: str, fields: str = None, meta: bool = None, include_deleted: bool = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Search/get_xid__id_

Parameters:

• node_id – ogit/_xid of the node/vertex or edge

• fields – Filter for fields

• meta – List detailed metainformations in result payload

• include_deleted – allow to get if ogit/_is-deleted=true

Returns:

The result payload

get_nodes(node_ids: list, fields: str = None, meta: bool = None, include_deleted: bool = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Search/get_query_ids

Parameters:

• node_ids – list of ogit/_ids of the node/vertexes or edges

• fields – Filter for fields

• meta – List detailed metainformations in result payload

• include_deleted – allow to get if ogit/_is-deleted=true

Returns:

The result payload

get_timeseries(node_id: str, starttime: str = None, endtime: str = None, include_deleted: bool = None, limit: int = None, with_ids: str = None, order: str = 'asc', aggregate: str = None) → List | Dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Timeseries/get__id__values

Parameters:

• node_id – ogit/_id of the node containing timeseries

• starttime – ms since epoch.

• endtime – ms since epoch.

• aggregate – aggregate numeric values for multiple timeseries ids with same timestamp: avg|min|max|sum|none

• order – order by a timestamp asc|desc|none. Default is “asc” here.

• with_ids – list of ids to aggregate in result

• limit – limit of entries to return

• include_deleted – allow to get if ogit/_is-deleted=true

Returns:

The result payload. Either a list of dict or a dict with an error message.

get_timeseries_history(node_id: str, timestamp: str = None, include_deleted: bool = None) → List | Dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Timeseries/get__id__values_history

Parameters:

• node_id – ogit/_id of the node containing timeseries

• timestamp – timestamp in ms

• include_deleted – allow to get if ogit/_is-deleted=true

Returns:

The result payload. Either a list of dict or a dict with an error message.

post_attachment(node_id: str, data: Any, content_type: str = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Storage]_Blob/post__id__content

Parameters:

• node_id – Id of the attachment node

• data – Data to upload in binary form. Can also be an IO object for streaming.

• content_type – Content-Type for data. Defaults to ‘application/octet-stream’ if left unset.

Returns:

The result payload

post_timeseries(node_id: str, items: list, synchronous: bool = True, ttl: int = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Storage]_Timeseries/post__id__values

Parameters:

• synchronous – whether the operation should return synchronously. Default is True here.

• ttl – time to live for values to be stored in seconds (overrides /ttl in vertex).

• node_id – ogit/_id of the node containing timeseries

• items – list of timeseries values [{timestamp: (ms since epoch), value: …},…]

Returns:

The result payload

query(query: str, fields: str = None, limit=-1, offset=0, order: str = None, meta: bool = None, count: bool = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Search/post_query_vertices

Parameters:

• query – The actual query. e.g. ogit\/_type: ogit\/Question for vertices.

• fields – the comma separated list of fields to return

• limit – limit of entries to return

• offset – offset where to start returning entries

• order – order by a field asc|desc, e.g. ogit/name desc

• meta – List detailed metainformations in result payload

• count – Just return the number of found items. Result payload is like {“items”:[&lt;number of items found as int&gt;]}.

Returns:

Result payload

query_gremlin(query: str, root: str, fields: str = None, include_deleted: bool = None, meta: bool = None) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Search/post_query_gremlin

Parameters:

• query – The actual query. e.g. outE().inV() for gremlin.

• root – ogit/_id of the root node where the gremlin query starts.

• fields – the comma separated list of fields to return

• include_deleted – Include deleted values.

• meta – List detailed metainformations in result payload

Returns:

Result payload

query_timeseries(starttime: str = None, endtime: str = None, limit: int = None, order: str = 'asc', aggregate: str = None) → List | Dict

Run a query against the graph and return agragated timeseries values for timeseries vertices matching query result. query: Entities with matching ogit/_type:ogit/Timeseries

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Query]_Search/get_query_values

Parameters:

• starttime – ms since epoch.

• endtime – ms since epoch.

• aggregate – aggregate numeric values for multiple timeseries ids with same timestamp: avg|min|max|sum|none

• order – order by a timestamp asc|desc|none. Default is “asc” here.

• limit – limit of entries to return

Returns:

The result payload. Either a list of dict or a dict with an error message.

update_node(node_id: str, data: dict) → dict

https://core.engine.datagroup.de/help/specs/?url=definitions/graph.yaml#/[Graph]_Entity/post__id_

Parameters:

• data – Payload for the node/vertex

• node_id – ogit/_id of the node/vertex

Returns:

The result payload

class hiro_graph_client.HiroAuth(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO Auth REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/auth.yaml

Constructor

Parameters:

api_handler – External API handler.

change_password(old_password: str, new_password: str) → dict

HIRO REST query API: PUT self._auth_endpoint + ‘/me/password’

Parameters:

• old_password – The old password to replace.

• new_password – The new password.

Returns:

The result payload

get_avatar() → Iterator[bytes]

HIRO REST query API: GET self._auth_endpoint + ‘/me/avatar’

Returns:

The result payload generator over binary data. Complete binary payload is an image/png.

get_identity() → dict

HIRO REST query API: GET self._auth_endpoint + ‘/me/account’

Returns:

The result payload

get_profile() → dict

HIRO REST query API: GET self._auth_endpoint + ‘/me/profile

Returns:

The result payload

get_roles() → dict

HIRO REST query API: GET self._auth_endpoint + ‘/me/roles

Returns:

The result payload

get_teams() → dict

HIRO REST query API: GET self._auth_endpoint + ‘/me/teams’

Returns:

The result payload

post_profile(data: dict) → dict

HIRO REST query API: POST self._auth_endpoint + ‘/me/profile

Parameters:

data – The attributes for the profile. See https://core.engine.datagroup.de/help/specs/?url=definitions/auth.yaml#/[Me]_Identity/post_me_profile

Returns:

The result payload

put_avatar(data: Any, content_type: str = 'image/png') → int

HIRO REST query API: PUT self._auth_endpoint + ‘/me/avatar’

Parameters:

• data – Binary data for image of avatar.

• content_type – Content-Type. Default: image/png

Returns:

The result payload / size of the avatar in bytes.

class hiro_graph_client.HiroApp(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO App REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/app.yaml

Constructor

Parameters:

api_handler – External API handler.

get_app(node_id) → dict

HIRO REST query API: GET self._endpoint + ‘/{id}’

Parameters:

node_id – ogit/_id of the node/vertex or edge.

Returns:

The result payload

get_config() → dict

HIRO REST query API: GET self._endpoint + ‘/config’. The token (internal or external) defines the config returned.

Returns:

The result payload

get_content(node_id, path) → Iterator[bytes]

HIRO REST query API: GET self._endpoint + ‘/{id}/content/{path}’. Get the content of an application.

Parameters:

• node_id – ogit/_id of the node/vertex or edge.

• path – filename / path of the desired content.

Returns:

The result payload generator over binary data.

get_desktop() → dict

HIRO REST query API: GET self._endpoint + ‘/desktop’. List desktop applications.

Returns:

The result payload - usually with a binary content.

get_manifest(node_id) → dict

HIRO REST query API: GET self._endpoint + ‘/{id}/manifest’. Get the manifest of an application.

Parameters:

node_id – ogit/_id of the node/vertex or edge.

Returns:

The result payload - usually with a binary content.

class hiro_graph_client.HiroIam(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO IAM REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml

Constructor

Parameters:

api_handler – External API handler.

activate_account(node_id: str) → dict

activates an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/patch_accounts__id__activate

Parameters:

node_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result

add_team_members(team_id: str, data: dict) → dict

adds members to an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/post_team__id__members_add

Parameters:

• team_id – ogit/_id of the ogit/Auth/Team

• data – dict with the account data

Returns:

Dict with the result

create_account(data: dict, import_flag: bool = None) → dict

create an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/post_accounts

Parameters:

• import_flag – Default is false

• data – The dict with the account data.

Returns:

Dict with the result

create_dataset(data: dict) → dict

creates a DataSet https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_DataSet/post_dataset

Parameters:

data – Dict with the new dataset data.

Returns:

Dict with the result

create_domain(data: dict) → dict

creates an Org Domain https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_OrgDomain/post_domain

Parameters:

data – Dict with the new domain data.

Returns:

Dict with the result

create_organization(data: dict) → dict

creates an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/post_organization

Parameters:

data – Dict with the new organization data.

Returns:

Dict with the result

create_role(data: dict) → dict

creates an Auth Role https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Role/post_role

Parameters:

data – Dict with the new role data.

Returns:

Dict with the result

create_roleassignment(data: dict) → dict

creates an Auth RoleAssignment https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_RoleAssignment/post_roleassignment

Parameters:

data – Dict with the new roleassignment data.

Returns:

Dict with the result

create_scope(data: dict) → dict

creates a DataScope https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_DataScope/post_scope

Parameters:

data – Dict with the new scope data.

Returns:

Dict with the result

create_team(data: dict) → dict

creates an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/post_team

Parameters:

data – Dict with the new team data.

Returns:

Dict with the result

deactivate_account(account_id: str, reason: str) → dict

deactivates an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/patch_accounts__id__deactivate

Parameters:

• reason – reason of deactivation of an ogit/Auth/Account. Available values : UserDeactivated, AdminDeactivated, PasswordExpired, AutoDeactivated, None

• account_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result

delete_account(account_id: str) → dict

deletes an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/delete_accounts__id_

Parameters:

account_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result

delete_dataset(dataset_id: str) → dict

deletes a DataSet https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_DataSet/delete_dataset__id_

Parameters:

dataset_id – ogit/_id of the ogit/Auth/DataSet

Returns:

Dict with the result

delete_domain(domain_id: str) → dict

deletes an Org Domain https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_OrgDomain/delete_domain__id_

Parameters:

domain_id – ogit/_id of the ogit/Auth/OrgDomain

Returns:

Dict with the result

delete_role(role_id: str) → dict

deletes an Auth Role https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Role/delete_role__id_

Parameters:

role_id – ogit/_id of the ogit/Auth/Role

Returns:

Dict with the result

delete_roleassignment(roleassignment_id: str) → dict

deletes an Auth RoleAssignment https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_RoleAssignment/delete_roleassignment__id_

Parameters:

roleassignment_id – ogit/_id of the ogit/Auth/RoleAssignment

Returns:

Dict with the result

delete_team(team_id: str) → dict

deletes an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/delete_team__id_

Parameters:

team_id – ogit/_id of the ogit/Auth/Team

Returns:

Dict with the result

get_account(account_id: str, profile: bool = None) → dict

gets an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/get_accounts__id_

Parameters:

• profile – return account with profile. Default false.

• account_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result

get_account_avatar(account_id: str) → Iterator[bytes]

gets avatar of account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/get_accounts__id__avatar

Parameters:

account_id – ogit/_id of the ogit/Auth/Account

Returns:

Binary content of the avatar

get_account_profile(account_id: str = None, profile_id: str = None) → dict

get profile of account

You need to specify either profile_id or account_id.

With account_id: https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/get_accounts__id__profile

With profile_id: https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/get_accounts_profile__profileId_

Parameters:

• profile_id – ogit/_id of the ogit/Auth/AccountProfile

• account_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result or an empty dict if neither account_id nor profile_id are given.

get_account_teams(account_id: str, include_virtual: bool = None) → dict

get teams of account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/get_accounts__id__teams

Parameters:

• include_virtual – return virtual teams in output. Default false.

• account_id – ogit/_id of the ogit/Auth/Account

Returns:

Dict with the result

get_dataset(dataset_id: str) → dict

retrieves a DataSet https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_DataSet/get_dataset__id_

Parameters:

dataset_id – ogit/_id of the ogit/Auth/DataSet

Returns:

Dict with the result

get_domain(domain_id: str) → dict

retrieves an Org Domain https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_OrgDomain/get_domain__id_

Parameters:

domain_id – ogit/_id of the ogit/Auth/OrgDomain

Returns:

Dict with the result

get_domain_organization(domain_id: str) → dict

retrieves an Organization of Org Domain https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_OrgDomain/get_domain__id__organization

Parameters:

domain_id – ogit/_id of the ogit/Auth/OrgDomain

Returns:

Dict with the result

get_organization_avatar(organization_id: str) → Iterator[bytes]

gets avatar of Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__avatar

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Binary content of the avatar

get_organization_configuration(organization_id: str) → dict

gets configuration of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__configuration

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_organization_datasets(organization_id: str) → dict

gets datasets of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__datasets

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_organization_domains(organization_id: str) → dict

gets domains of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__domains

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_organization_roleassignments(organization_id: str) → dict

gets roleassignments of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__roleassignments

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_organization_scopes(organization_id: str) → dict

gets scopes of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__scopes

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_organization_teams(organization_id: str) → dict

gets teams of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/get_organization__id__teams

Parameters:

organization_id – ogit/_id of the ogit/Auth/Organization

Returns:

Dict with the result

get_role(role_id: str) → dict

retrieves an Auth Role https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Role/get_role__id_

Parameters:

role_id – ogit/_id of the ogit/Auth/Role

Returns:

Dict with the result

get_roleassignment(roleassignment_id: str) → dict

retrieves an Auth RoleAssignment https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_RoleAssignment/get_roleassignment__id_

Parameters:

roleassignment_id – ogit/_id of the ogit/Auth/RoleAssignment

Returns:

Dict with the result

get_roles() → dict

retrieves public roles https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Role/get_roles

Returns:

Dict with the result

get_scope(scope_id: str) → dict

retrieves a DataScope https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_DataScope/get_scope__id_

Parameters:

scope_id – ogit/_id of the ogit/Auth/DataScope

Returns:

Dict with the result

get_team(team_id: str) → dict

retrieves an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/get_team__id_

Parameters:

team_id – ogit/_id of the ogit/Auth/Team

Returns:

Dict with the result

get_team_members(team_id: str, profile: bool = None) → dict

gets members of an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/get_team__id__members

Parameters:

• profile – return account with profile. Default False.

• team_id – ogit/_id of the ogit/Auth/Team

Returns:

Dict with the result

put_account_avatar(account_id: str, data: Any, content_type: str = 'image/png') → str

sets the avatar of account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/put_accounts__id__avatar

Parameters:

• account_id – ogit/_id of the ogit/Auth/Account

• data – Binary data for image of avatar.

• content_type – Content-Type. Default: image/png

Returns:

The result payload / size of the avatar in bytes.

put_account_password(account_id: str, data: dict) → dict

set password of account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/put_accounts__id__password

Parameters:

• account_id – ogit/_id of the ogit/Auth/Account

• data – The dict with the new password data.

Returns:

Dict with the result

put_organization_avatar(organization_id: str, data: Any, content_type: str = 'image/png') → str

sets the avatar of Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/put_organization__id__avatar

Parameters:

• organization_id – ogit/_id of the ogit/Auth/Organization

• data – Binary data for image of avatar.

• content_type – Content-Type. Default: image/png

Returns:

The result payload / size of the avatar in bytes.

remove_team_members(team_id: str, data: dict) → dict

adds members to an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/post_team__id__members_remove

Parameters:

• team_id – ogit/_id of the ogit/Auth/Team

• data – dict with the account data

Returns:

Dict with the result

update_account(account_id: str, data: dict) → dict

update an account https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/post_accounts__id_

Parameters:

• account_id – ogit/_id of the ogit/Auth/Account

• data – The dict with the account data.

Returns:

Dict with the result

update_account_profile(profile_id: str, data: dict) → dict

updates an account profile https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Account/post_accounts_profile__profileId_

Parameters:

• data – Dict with the new profile data.

• profile_id – ogit/_id of the ogit/Auth/AccountProfile

Returns:

Dict with the result

update_dataset(dataset_id: str, data: dict) → dict

updates a DataSet https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_DataSet/put_dataset__id_

Parameters:

• dataset_id – ogit/_id of the ogit/Auth/DataSet

• data – Dict with the new dataset data.

Returns:

Dict with the result

update_organization_configuration(organization_id: str, data: dict) → dict

updates configuration of an Auth Organization https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Organization/put_organization__id__configuration

Parameters:

• organization_id – ogit/_id of the ogit/Auth/Organization

• data – Dict with the new organization data.

Returns:

Dict with the result

update_role(role_id: str, data: dict) → dict

updates an Auth Role https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Role/put_role__id_

Parameters:

• role_id – ogit/_id of the ogit/Auth/Role

• data – Dict with the new role data.

Returns:

Dict with the result

update_scope(scope_id: str, data: dict) → dict

updates a DataScope https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_DataScope/put_scope__id_

Parameters:

• scope_id – ogit/_id of the ogit/Auth/DataScope

• data – Dict with the new scope data.

Returns:

Dict with the result

update_team(team_id: str, data: dict) → dict

updates an Auth Team https://core.engine.datagroup.de/help/specs/?url=definitions/iam.yaml#/[Management]_Auth_Team/put_team__id_

Parameters:

• team_id – ogit/_id of the ogit/Auth/Team

• data – Dict with the new team data.

Returns:

Dict with the result

class hiro_graph_client.HiroKi(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO Ki REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/ki.yaml

Constructor

Parameters:

api_handler – External API handler.

_get_error_message(json_result: dict) → str

Intercept special error messages. These have a key ‘status’ in their dict.

Parameters:

json_result – The incoming JSON containing error information.

Returns:

The error message.

check(data: dict) → dict

Ask if KI is valid

HIRO REST query API: POST self._endpoint + ‘/check

Parameters:

data – KI validation request data. See https://core.engine.datagroup.de/help/specs/?url=definitions/ki.yaml#/[Validatation]_Validate/post_check

Returns:

The result payload

class hiro_graph_client.HiroAuthz(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO Authz REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/authz.yaml

Constructor

Parameters:

api_handler – External API handler.

entitlement(data: dict) → dict

Ask for entitlement decision

HIRO REST query API: POST self._endpoint + ‘/entitlement

Parameters:

data – Entitlement request data. See https://core.engine.datagroup.de/help/specs/?url=definitions/authz.yaml#/[Authorization]_Entitlement/post_entitlement

Returns:

The result payload

class hiro_graph_client.HiroVariables(api_handler: AbstractTokenApiHandler)

Bases: AuthenticatedAPIHandler

Python implementation for accessing the HIRO Variables REST API. See https://core.engine.datagroup.de/help/specs/?url=definitions/variables.yaml

Constructor

Parameters:

api_handler – External API handler.

create_variable(data: dict, subtype: str = None) → dict

Creates new variable

HIRO REST query API: PUT self._endpoint

Parameters:

• data – Variable content. See https://core.engine.datagroup.de/help/specs/?url=definitions/variables.yaml#/[Variables]/put_

• subtype – Query variable. Value of ogit/subType. Optional.

Returns:

The result payload

define(name: str) → dict

Get variable by name.

HIRO REST query API: GET self._endpoint + ‘/define’

:param name Variable name. Required. :return: The result payload

get_variable(name: str) → dict

Get variable by name. (synonym for self.define(name))

HIRO REST query API: GET self._endpoint + ‘/define’

:param name Variable name. Required. :return: The result payload

like(name: str, description: str = None, subtype: str = None, full: bool = None) → List | Dict

Search for similar variables.

HIRO REST query API: GET self._endpoint + ‘/like’

:param name Variable name. Required. :param description: Search by variable description. Optional. :param subtype: Value of ogit/subType. Optional. :param full: Return full variable, not just a name. Optional. Default false. :return: The result payload. Either a list of dict or a dict with an error message.

suggest(name: str, subtype: str = None, full: bool = None) → List | Dict

Search for similar variables.

HIRO REST query API: GET self._endpoint + ‘/suggest’

:param name Variable name. Required. :param subtype: Value of ogit/subType. Optional. :param full: Return full variable, not just a name. Optional. Default false. :return: The result payload. Either a list of dict or a dict with an error message.

class hiro_graph_client.GraphConnectionHandler(root_url: str = None, custom_endpoints: dict = None, version_info: dict = None, pool_maxsize: int = None, pool_block: bool = None, connection_handler=None, *args, **kwargs)

Bases: AbstractAPI

Contains information about a Graph Connection. This class also handles resolving the current api endpoints. Also creates the requests.Session which will be shared among the API Modules using this connection.

Constructor

Example for custom_endpoints (see params below):

{
    "graph": "/api/graph/7.2",
    "auth": "/api/auth/6.2",
    "action-ws": ("/api/action-ws/1.0", "action-1.0.0")
}

This object creates the requests.Session and requests.adapters.HTTPAdapter for this root_url. The pool_maxsize of such a session can be set via the parameter in the constructor. When a TokenApiHandler is shared between different API objects (like HiroGraph, HiroApp, etc.), this session and its pool are also shared.

See parent AbstractAPI for a description of all remaining parameters.

Parameters:

• root_url – Root url for HIRO, like https://core.engine.datagroup.de.

• custom_endpoints – Optional map of {name:endpoint_path, …} that overrides or adds to the endpoints taken from /api/version. Example see above.

• version_info – Optional full dict of the JSON result received via /api/version. Setting this will use it as the valid API version information and avoids the internal API-call altogether.

• pool_maxsize – Size of a connection pool for a single connection. See requests.adapters.HTTPAdapter. Default is 10. pool_maxsize is ignored when session is set.

• pool_block – Block any connections that exceed the pool_maxsize. Default is False: Allow more connections, but do not cache them. See requests.adapters.HTTPAdapter. pool_block is ignored when session is set.

• connection_handler – Copy parameters from this already existing connection handler. Overrides all other parameters.

• args – Unnamed parameter passthrough for parent class.

• kwargs – Named parameter passthrough for parent class.

_pool_block = False

As used by requests.adapters.HTTPAdapter.

_pool_maxsize = 10

Default pool_maxsize for requests.adapters.HTTPAdapter.

static _remove_slash(endpoint: str) → str

_version_info: dict = None

Stores the result of /api/version

custom_endpoints: dict = None

Override API endpoints.

get_api_endpoint_of(api_name: str) → str

Determines endpoints of the API names. Loads and caches the current API information if necessary.

Parameters:

api_name – Name of the HIRO API

Returns:

Full url of endpoint for this API

get_version(force_update: bool = False) → dict

HIRO REST query API: GET self._endpoint + ‘/api/version’

Parameters:

force_update – Force updating the internal cache with version_info via API request.

Returns:

The result payload

get_websocket_config(api_name: str) → Tuple[str, str, str | None, int | None, dict | None]

Determines endpoints for websockets of the API names. Loads and caches the current API information if necessary. If proxies have been given, the key of the proxy picked needs to be “ws” or “wss” respectively.

Parameters:

api_name – Name of the HIRO API for websockets

Returns:

Tuple of full url of websocket for this API, its protocol, its proxy_host, its proxy port and proxy auth (if any).

_lock: RLock

Reentrant mutex for thread safety

ssl_config: SSLConfig

Security configuration and location of certificate files

class hiro_graph_client.AbstractTokenApiHandler(*args, **kwargs)

Bases: GraphConnectionHandler

Root class for all TokenApiHandler classes. This adds token handling.

Constructor

See parent GraphConnectionHandler for a full description of all remaining parameters.

Parameters:

• args – Unnamed parameter passthrough for parent class.

• kwargs – Named parameter passthrough for parent class.

decode_token() → dict

Return a dict with the decoded token payload from the internal token. This payload contains detailed information about what this token has access to.

Returns:

The dict with the decoded token payload.

Raises:

AuthenticationTokenError – When the token does not contain the base64 encoded data payload.

static decode_token_ext(token: str) → dict

Return a dict with the decoded token payload. This payload contains detailed information about what this token has access to.

Parameters:

token – The token to decode.

Returns:

The dict with the decoded token payload.

Raises:

AuthenticationTokenError – When the token does not contain the base64 encoded data payload.

abstractmethod refresh_time() → int | None

Calculate the time after which the token should be refreshed in milliseconds.

Returns:

The timestamp in ms after which the token shall be refreshed or None if the token cannot be refreshed on its own.

abstractmethod refresh_token() → None

Refresh the current token.

abstractmethod revoke_token(token_hint: str = 'revoke_token') → None

Revoke a token.

Parameters:

token_hint – The default is to revoke the “revoke_token”. The alternative is “access_token”.

property token: str

Return the current token.

class hiro_graph_client.PasswordAuthTokenApiHandler(username: str = None, password: str = None, client_id: str = None, client_secret: str = None, secure_logging: bool = True, *args, **kwargs)

Bases: AbstractTokenApiHandler

API Tokens will be fetched using this class. It does not handle any automatic token fetching, refresh or token expiry. This has to be checked and triggered by the caller.

The methods of this class are thread-safe, so it can be shared between several HIRO objects.

It is built this way to avoid endless calling loops when resolving tokens.

Constructor

See parent AbstractTokenApiHandler for a full description of all remaining parameters.

Parameters:

• username – Username for authentication

• password – Password for authentication

• client_id – OAuth client_id for authentication

• client_secret – OAuth client_secret for authentication

• secure_logging – If this is enabled, payloads that might contain sensitive information are not logged.

• args – Unnamed parameter passthrough for parent class.

• kwargs – Named parameter passthrough for parent class.

_check_response(res: Response) → None

Response checking. When a refresh_token is present and status_code is 401, raise TokenUnauthorizedError. This can happen when a refresh-token is not valid anymore.

Parameters:

res – The result payload

Raises:

TokenUnauthorizedError – Raised to trigger a retry via self.get_token() in self.refresh_token().

_handle_token() → str | None

Just return None, therefore a header without Authorization will be created in self._get_headers().

Does not try to obtain or refresh a token.

Returns:

token given.

_log_communication(res: Response, request_body: bool = True, response_body: bool = True) → None

Logging under a secure aspect. Hides sensitive information unless self._secure_logging is set to False.

Parameters:

• res – The response of a request. Also contains the request.

• request_body – Option to disable the logging of the request_body. If set to True, will only remain True internally when self._secure_logging is set to False.

• response_body – Option to disable the logging of the response_body. If set to True, will only remain True internally when self._secure_logging is set to False or res.status_code != 200.

_secure_logging: bool = True

Avoid logging of sensitive data.

_token_info: TokenInfo = None

Contains all token information

property endpoint

get_token() → None

Construct a request to obtain a new token. API self._endpoint + ‘/app’

Raises:

AuthenticationTokenError – When no auth_endpoint is set.

refresh_time() → int | None

Calculate refresh time.

Returns:

Timestamp after which the token becomes invalid. Returns None if token cannot be refreshed.

refresh_token() → None

Construct a request to refresh an existing token. API self._endpoint + ‘/refresh’.

Raises:

AuthenticationTokenError – When no auth_endpoint is set.

revoke_token(token_hint: str = 'refresh_token') → None

Revoke a token.

Parameters:

token_hint – The default is to revoke the “revoke_token”. The alternative is “access_token”. (has effect after auth api version 6.6)

property token: str

Get the token. Get or refresh it if necessary.

_lock: RLock

Reentrant mutex for thread safety

_username: str

_password: str

_client_id: str

_client_secret: str

ssl_config: SSLConfig

Security configuration and location of certificate files

class hiro_graph_client.FixedTokenApiHandler(token: str = None, *args, **kwargs)

Bases: AbstractTokenApiHandler

TokenApiHandler for a fixed token.

Constructor

See parent AbstractTokenApiHandler for a full description of all remaining parameters.

Parameters:

• token – The fixed token for the HTTP requests.

• args – Unnamed parameter passthrough for parent class. See AbstractTokenApiHandler.

• kwargs – Named parameter passthrough for parent class. See AbstractTokenApiHandler.

refresh_time() → int | None

Returns:

Always none

refresh_token() → None

Refresh the current token.

revoke_token(token_hint: str = 'revoke_token') → None

Revoke a token.

Parameters:

token_hint – The default is to revoke the “revoke_token”. The alternative is “access_token”.

property token: str

Return the current token.

_token: str

Stores the fixed token.

_lock: RLock

Reentrant mutex for thread safety

ssl_config: SSLConfig

Security configuration and location of certificate files

class hiro_graph_client.EnvironmentTokenApiHandler(env_var: str = 'HIRO_TOKEN', *args, **kwargs)

Bases: AbstractTokenApiHandler

TokenApiHandler for a fixed token given as an environment variable.

Constructor

See parent AbstractTokenApiHandler for a full description of all remaining parameters.

Parameters:

• env_var – Name of the environment variable with the token.

• args – Unnamed parameter passthrough for parent class.

• kwargs – Named parameter passthrough for parent class.

refresh_time() → int | None

Returns:

Always none

refresh_token() → None

Refresh the current token.

revoke_token(token_hint: str = 'revoke_token') → None

Revoke a token.

Parameters:

token_hint – The default is to revoke the “revoke_token”. The alternative is “access_token”.

property token: str

Return the current token.

_env_var: str

Stores the name of the environment variable.

_lock: RLock

Reentrant mutex for thread safety

ssl_config: SSLConfig

Security configuration and location of certificate files

exception hiro_graph_client.AuthenticationTokenError(message: str, code: int = None)

Bases: Exception

Class for unrecoverable failures with access tokens. Contains a message and an optional message code. If the code is None, no code will be printed in __str__().

message: str

code: int

exception hiro_graph_client.FixedTokenError(message: str, code: int = None)

Bases: AuthenticationTokenError

Child of AuthenticationTokenErrors. Used when tokens are fixed and cannot be refreshed.

exception hiro_graph_client.TokenUnauthorizedError(message: str, code: int = None)

Bases: AuthenticationTokenError

Child of AuthenticationTokenErrors. Used when tokens expire with error 401.

class hiro_graph_client.SSLConfig(verify: bool = True, cert_file: str = None, key_file: str = None, ca_bundle_file: str = None)

Bases: object

Configuration for SSL connections.

Parameters:

• verify – Verify connections at all. If just set to True without other parameters, defaults will be used.

• cert_file – (optional) Client certificate file (.pem).

• key_file – (optional) Key for the certificate file.

• ca_bundle_file – (optional) The ca_bundle for server certificate verification.

get_cert()

Get cert parameter as expected by requests library.

Returns:

Tuple of cert_file, key_file or just cert_file - which can be None.

get_verify()

Get verify parameter as expected by requests library.

Returns:

True, False or a path to a ca_bundle.

verify: bool

cert_file: str

key_file: str

ca_bundle_file: str

This class contains the configuration for SSL connections, like the files to use.