Sync client¶

Quickstart¶

Here is a short example of using sync client to interact with backend.

Create client object:

>>> from horizon.client.sync import HorizonClientSync
>>> from horizon.client.auth import LoginPassword
>>> client = HorizonClientSync(
...     base_url="http://some.domain.com/api",
...     auth=LoginPassword(login="me", password="12345"),
... )

Check for credentials and issue access token:

>>> client.authorize()

Create namespace with name "my_namespace":

>>> from horizon.commons.schemas.v1 import NamespaceCreateRequestV1
>>> created_namespace = client.create_namespace(NamespaceCreateRequestV1(name="my_namespace"))
>>> created_namespace
NamespaceResponseV1(
    id=1,
    name="my_namespace",
    description="",
)

Create HWM with name "my_hwm" in this namespace:

>>> from horizon.commons.schemas.v1 import HWMCreateRequestV1
>>> hwm = HWMCreateRequestV1(
...     namespace_id=created_namespace.id,
...     name="my_hwm",
...     type="column_int",
...     value=123,
... )
>>> created_hwm = client.create_hwm(hwm)
>>> created_hwm
HWMResponseV1(
    id=1,
    namespace_id=1,
    name="my_hwm",
    description="",
    type="column_int",
    value=123,
    entity="",
    expression="",
)

Update HWM with name "my_hwm" in this namespace:

>>> from horizon.commons.schemas.v1 import HWMUpdateRequestV1
>>> hwm_change = HWMUpdateRequestV1(value=234)
>>> updated_hwm = client.update_hwm(created_hwm.id, hwm_change)
>>> updated_hwm
HWMResponseV1(
    id=1,
    namespace_id=1,
    name="my_hwm",
    description="",
    type="column_int",
    value=234,
    entity="",
    expression="",
)

Reference¶

`HorizonClientSync` ¶

Sync Horizon client implementation, based on authlib and requests.

Parameters:

base_url (AnyHttpUrl) –

URL of Horizon API, e.g. https://some.domain.com/api
auth (BaseAuth) –

Authentication class
retry (RetryConfig, default: <dynamic> ) –

Configuration for request retries.
timeout (TimeoutConfig, default: <dynamic> ) –

Configuration for request timeouts.
session (OAuth2Session | None, default: None ) –

Custom session object. Inherited from requests.Session, so you can pass custom session options.

Examples:

Using default parameters:

>>> from horizon.client.auth import LoginPassword
>>> from horizon.client.sync import HorizonClientSync
>>> client = HorizonClientSync(
...     base_url="https://some.domain.com/api",
...     auth=LoginPassword(login="me", password="12345"),
... )

Customize retry and timeout:

>>> from horizon.client.auth import LoginPassword
>>> from horizon.client.sync import HorizonClientSync, RetryConfig, TimeoutConfig
>>> client = HorizonClientSync(
...     base_url="https://some.domain.com/api",
...     auth=LoginPassword(login="me", password="12345"),
...     retry=RetryConfig(total=2, backoff_factor=10, status_forcelist=[500, 503]),
...     timeout=TimeoutConfig(request_timeout=3.5),
... )

`authorize()` ¶

Fetch and set access token (if required).

Raises:

AuthorizationError –

Authorization failed

Examples:

>>> client.authorize()

`ping()` ¶

Ping Horizon server.

Examples:

>>> client.ping()
PingResponse(status="ok")

`whoami()` ¶

Get current user info.

Examples:

>>> client.whoami()
UserResponseV1(
    id=1,
    username="me",
)

>>> client.whoami()  # for a superadmin user:
UserResponseV1WithAdmin(
    id=1,
    username="admin",
    is_admin=True,
)

`paginate_namespaces(query=None)` ¶

Get page with namespaces.

Parameters:

query (NamespacePaginateQueryV1 | None, default: None ) –

Namespace query parameters

Returns:

PageResponseV1[NamespaceResponseV1] –

List of namespaces, limited and filtered by query parameters.

Examples:

Get all namespaces:

>>> client.paginate_namespaces()
PageResponseV1[NamespaceResponseV1](
    meta=PageMetaResponseV1(
        page=1,
        pages_count=1,
        total_count=10,
        page_size=20,
        has_next=False,
        has_previous=False,
        next_page=None,
        previous_page=None,
    ),
    items=[NamespaceResponseV1(...), ...],
)

Get all namespaces starting with a page number and page size:

>>> from horizon.commons.schemas.v1 import NamespacePaginateQueryV1
>>> namespace_query = NamespacePaginateQueryV1(page=2, page_size=20)
>>> client.paginate_namespaces(query=namespace_query)
PageResponseV1[NamespaceResponseV1](
    meta=PageMetaResponseV1(
        page=2,
        pages_count=3,
        total_count=50,
        page_size=20,
        has_next=True,
        has_previous=True,
        next_page=3,
        previous_page=1,
    ),
    items=[NamespaceResponseV1(...), ...],
)

Search for namespace with specific name:

>>> from horizon.commons.schemas.v1 import NamespacePaginateQueryV1
>>> namespace_query = NamespacePaginateQueryV1(name="my_namespace")
>>> client.paginate_namespaces(query=namespace_query)
PageResponseV1[NamespaceResponseV1](
    meta=PageMetaResponseV1(
        page=1,
        pages_count=1,
        total_count=1,
        page_size=10,
        has_next=False,
        has_previous=False,
        next_page=None,
        previous_page=None,
    ),
    items=[
        NamespaceResponseV1(name="my_namespace", ...),
    ],
)

`get_namespace(namespace_id)` ¶

Get namespace by name.

Parameters:

namespace_id (int) –

Namespace name to get

Returns:

NamespaceResponseV1 –

Namespace

Raises:

EntityNotFoundError –

Namespace not found

Examples:

>>> client.get_namespace(namespace_id=123)
NamespaceResponseV1(
    id=123,
    name="my_namespace",
    ...
)

`create_namespace(data)` ¶

Create new namespace.

Parameters:

data (NamespaceCreateRequestV1) –

Namespace to create

Returns:

NamespaceResponseV1 –

Created namespace

Raises:

EntityAlreadyExistsError –

Namespace with the same name already exists

Examples:

>>> from horizon.commons.schemas.v1 import NamespaceCreateRequestV1
>>> to_create = NamespaceCreateRequestV1(name="my_namespace")
>>> client.create_namespace(data=to_create)
NamespaceResponseV1(
    id=123,
    name="my_namespace",
    ...
)

`update_namespace(namespace_id, changes)` ¶

Update existing namespace.

Parameters:

namespace_id (int) –

Namespace name to update
changes (NamespaceUpdateRequestV1) –

Changes to namespace object

Returns:

NamespaceResponseV1 –

Updated namespace

Raises:

EntityNotFoundError –

Namespace not found
EntityAlreadyExistsError –

Namespace with the same name already exists
PermissionDeniedError –

Permission denied for performing the requested action.

Examples:

>>> from horizon.commons.schemas.v1 import NamespaceUpdateRequestV1
>>> to_update = NamespaceUpdateRequestV1(name="new_namespace_name")
>>> client.update_namespace(namespace_id=123, changes=to_update)
NamespaceResponseV1(
    id=123,
    name="new_namespace_name",
    ...
)

`delete_namespace(namespace_id)` ¶

Delete existing namespace.

Parameters:

namespace_id (int) –

Namespace name to delete

Raises:

EntityNotFoundError –

Namespace not found
PermissionDeniedError –

Permission denied for performing the requested action.

Examples:

>>> client.delete_namespace(namespace_id=123)

`paginate_hwm(query)` ¶

Get page with HWMs.

Parameters:

query (HWMPaginateQueryV1) –

HWM query parameters

Returns:

PageResponseV1[HWMResponseV1] –

List of HWM, limited and filtered by query parameters.

Examples:

Get all HWM in namespace with specific id:

>>> from horizon.commons.schemas.v1 import HWMPaginateQueryV1
>>> hwm_query = HWMPaginateQueryV1(namespace_id=123)
>>> client.paginate_hwm(query=hwm_query)
PageResponseV1[HWMResponseV1](
    meta=PageMetaResponseV1(
        page=1,
        pages_count=2,
        total_count=10,
        page_size=10,
        has_next=True,
        has_previous=False,
        next_page=2,
        previous_page=None,
    ),
    items=[HWMResponseV1(namespace_id=123, ...), ...],
)

Get all HWM in namespace starting with a page number and page size:

>>> from horizon.commons.schemas.v1 import HWMPaginateQueryV1
>>> hwm_query = HWMPaginateQueryV1(namespace_id=123, page=2, page_size=20)
>>> client.paginate_hwm(query=hwm_query)
PageResponseV1[HWMResponseV1](
    meta=PageMetaResponseV1(
        page=2,
        pages_count=3,
        total_count=50,
        page_size=20,
        has_next=True,
        has_previous=True,
        next_page=3,
        previous_page=1,
    ),
    items=[HWMResponseV1(namespace_id=123, ...), ...],
)

Search for HWM with specific namespace and name:

>>> from horizon.commons.schemas.v1 import HWMPaginateQueryV1
>>> hwm_query = HWMPaginateQueryV1(namespace_id=123, name="my_hwm")
>>> client.paginate_hwm(query=hwm_query)
PageResponseV1[HWMResponseV1](
    meta=PageMetaResponseV1(
        page=1,
        pages_count=1,
        total_count=1,
        page_size=10,
        has_next=False,
        has_previous=False,
        next_page=None,
        previous_page=None,
    ),
    items=[
        HWMResponseV1(namespace_id=123, name="my_hwm", ...),
    ],
)

`get_hwm(hwm_id)` ¶

Get HWM.

Parameters:

hwm_id (int) –

HWM id to get

Returns:

HWMResponseV1 –

HWM

Raises:

EntityNotFoundError –

HWM not found

Examples:

>>> client.get_hwm(hwm_id=234)
HWMResponseV1(
    id=234,
    namespace_id=123,
    name="my_hwm",
    ...
)

`create_hwm(data)` ¶

Create new HWM.

Parameters:

data (HWMCreateRequestV1) –

HWM data

Returns:

HWMResponseV1 –

Created HWM

Raises:

EntityNotFoundError –

Namespace not found
EntityAlreadyExistsError –

HWM with the same name already exists
PermissionDeniedError –

Permission denied for performing the requested action.

Examples:

>>> from horizon.commons.schemas.v1 import HWMCreateRequestV1
>>> to_create = HWMCreateRequestV1(
...     namespace_id=123,
...     name="my_hwm",
...     type="column_int",
...     value=5678,
... )
>>> client.create_hwm(data=to_create)
HWMResponseV1(
    namespace_id=123,
    id=234,
    name="my_hwm",
    type="column_int",
    value=5678,
    ...,
)

`update_hwm(hwm_id, changes)` ¶

Update existing HWM.

Parameters:

hwm_id (int) –

HWM id to update
changes (HWMUpdateRequestV1) –

HWM changes

Returns:

HWMResponseV1 –

Updated HWM

Raises:

EntityNotFoundError –

HWM not found
EntityAlreadyExistsError –

HWM with the same name already exists
PermissionDeniedError –

Permission denied for performing the requested action.

Examples:

>>> from horizon.commons.schemas.v1 import HWMUpdateRequestV1
>>> to_update = HWMUpdateRequestV1(type="column_int", value=5678)
>>> client.update_hwm(hwm_id=234, changes=to_update)
HWMResponseV1(
    namespace_id=123,
    id=234,
    name="my_hwm",
    type="column_int",
    value=5678,
    ...,
)

`delete_hwm(hwm_id)` ¶

Delete existing HWM.

Parameters:

hwm_id (int) –

HWM id to delete

Raises:

EntityNotFoundError –

HWM not found
PermissionDeniedError –

Permission denied for performing the requested action.

Examples:

>>> client.delete_hwm(hwm_id=234)

`bulk_delete_hwm(namespace_id, hwm_ids)` ¶

Bulk delete HWMs.

Note

Method ignores HWMs that are not related to provided namespace.

Parameters:

namespace_id (int) –

Namespace ID where the HWMs belong.
hwm_ids (list[int]) –

List of HWM IDs to be deleted.

Raises:

PermissionDeniedError –

Permission denied for performing the requested action.

Examples:

>>> client.bulk_delete_hwm(
...     namespace_id=123,
...     hwm_ids=[234, 345, 456]
... )

`bulk_copy_hwm(data)` ¶

Copy HWMs from one namespace to another.

Note

Method ignores HWMs that are not related to provided source namespace, or does not exist.

Parameters:

data (HWMBulkCopyRequestV1) –

HWM copy data

Returns:

HWMListResponseV1 –

Copied HWMs

Raises:

EntityNotFoundError –

Raised if any of the specified namespaces not found.
PermissionDeniedError –

Permission denied for performing the requested action.

Examples:

>>> from horizon.commons.schemas.v1 import HWMBulkCopyRequestV1
>>> copy_data = HWMBulkCopyRequestV1(
...     source_namespace_id=123,
...     target_namespace_id=456,
...     hwm_ids=[1, 2, 3],
...     with_history=True,
... )
>>> copied_hwms = client.bulk_copy_hwm(data=copy_data)
[HWMResponseV1(...), HWMResponseV1(...), HWMResponseV1(...)]

`get_namespace_permissions(namespace_id)` ¶

Get permissions for a namespace.

Parameters:

namespace_id (int) –

The ID of the namespace to get permissions for.

Returns:

PermissionsResponseV1 –

The permissions of the namespace.

Raises:

EntityNotFoundError –

Namespace or provided user not found.
PermissionDeniedError –

Permission denied for performing the requested action.

Examples:

>>> client.get_namespace_permissions(namespace_id=234)

`update_namespace_permissions(namespace_id, changes)` ¶

Update permissions for a namespace.

Parameters:

namespace_id (int) –

The ID of the namespace to update permissions for.
changes (PermissionsUpdateRequestV1) –

The changes to apply to the namespace's permissions.

Returns:

PermissionsResponseV1 –

Actual permissions of the namespace.

Raises:

EntityNotFoundError –

Namespace or provided user not found.
PermissionDeniedError –

Permission denied for performing the requested action.
BadRequestError –

Bad request with incorrect operating logic.

Examples:

>>> from horizon.commons.schemas.v1 import PermissionsUpdateRequestV1, PermissionUpdateRequestItemV1
>>> to_update = PermissionsUpdateRequestV1(
...     permissions=[
...         PermissionUpdateRequestItemV1(username="new_owner", role="OWNER"),
...         PermissionUpdateRequestItemV1(username="add_developer", role="DEVELOPER"),
...         PermissionUpdateRequestItemV1(username="make_read_only", role=None),
...     ]
... )
>>> client.update_namespace_permissions(namespace_id=234, changes=to_update)

`paginate_hwm_history(query)` ¶

Get page with HWM changes history.

Parameters:

query (HWMHistoryPaginateQueryV1) –

HWM history query parameters

Returns:

PageResponseV1[HWMHistoryResponseV1] –

List of HWM history items, limited and filtered by query parameters.

Examples:

Get all changes of specific HWM:

>>> from horizon.commons.schemas.v1 import HWMPaginateQueryV1
>>> hwm_query = HWMPaginateQueryV1(hwm_id=234)
>>> client.paginate_hwm(query=hwm_query)
PageResponseV1[HWMHistoryResponseV1](
    meta=PageMetaResponseV1(
        page=1,
        pages_count=2,
        total_count=10,
        page_size=10,
        has_next=True,
        has_previous=False,
        next_page=2,
        previous_page=None,
    ),
    items=[HWMHistoryResponseV1(hwm_id=234, ...), ...],
)

Get all changes of specific HWM starting with a page number and page size:

>>> from horizon.commons.schemas.v1 import HWMPaginateQueryV1
>>> hwm_query = HWMPaginateQueryV1(hwm_id=234, page=2, page_size=20)
>>> client.paginate_hwm(query=hwm_query)
PageResponseV1[HWMHistoryResponseV1](
    meta=PageMetaResponseV1(
        page=2,
        pages_count=3,
        total_count=50,
        page_size=20,
        has_next=True,
        has_previous=True,
        next_page=3,
        previous_page=1,
    ),
    items=[HWMHistoryResponseV1(hwm_id=234, ...), ...],
)

`paginate_namespace_history(query)` ¶

Get page with namespace changes history.

Parameters:

query (NamespaceHistoryPaginateQueryV1) –

Namespace history query parameters

Returns:

PageResponseV1[NamespaceHistoryResponseV1] –

List of namespace history items, limited and filtered by query parameters.

Examples:

Get all changes of specific namespace:

>>> from horizon.commons.schemas.v1 import NamespacePaginateQueryV1
>>> namespace_query = NamespacePaginateQueryV1(namespace_id=234)
>>> client.paginate_namespace(query=namespace_query)
PageResponseV1[NamespaceHistoryResponseV1](
    meta=PageMetaResponseV1(
        page=1,
        pages_count=2,
        total_count=10,
        page_size=10,
        has_next=True,
        has_previous=False,
        next_page=2,
        previous_page=None,
    ),
    items=[NamespaceHistoryResponseV1(namespace_id=234, ...), ...],
)

Get all changes of specific namespace starting with a page number and page size:

>>> from horizon.commons.schemas.v1 import NamespacePaginateQueryV1
>>> namespace_query = NamespacePaginateQueryV1(namespace_id=234, page=2, page_size=20)
>>> client.paginate_namespace(query=namespace_query)
PageResponseV1[NamespaceHistoryResponseV1](
    meta=PageMetaResponseV1(
        page=2,
        pages_count=3,
        total_count=50,
        page_size=20,
        has_next=True,
        has_previous=True,
        next_page=3,
        previous_page=1,
    ),
    items=[NamespaceHistoryResponseV1(namespace_id=234, ...), ...],
)

`RetryConfig` ¶

Configuration for request retries in case of network errors or specific status codes. If provided, it customizes the retry behavior for requests made by the client. urllib3 retry documentation.

Parameters:

total ¶
(int, default: 3 ) –

The maximum number of retry attempts to make.
backoff_factor ¶
(float, default: 0.1 ) –

A backoff factor to apply between attempts after the second try.
status_forcelist ¶
(list[int], default: [502, 503, 504] ) –

A set of HTTP status codes that we should force a retry on.
backoff_jitter ¶
(float | None, default: None ) –

A random jitter amount (between 0 and 1) to add to the backoff delay. Helps to avoid "thundering herd" issues by randomizing the delay times between retries.

Note

Requires urllib>2.0

`TimeoutConfig` ¶

Configuration for connection and request timeouts. If provided, it customizes the timeout behavior for requests made by the client. requests timeout documentation.

Parameters:

connection_timeout ¶
(float, default: 3 ) –

The maximum number of seconds to wait for a connection to the server.
request_timeout ¶
(float, default: 5 ) –

The maximum number of seconds to wait for a response from the server.

Sync client¶

Quickstart¶

Reference¶

`HorizonClientSync` ¶

`authorize()` ¶

`ping()` ¶

`whoami()` ¶

`paginate_namespaces(query=None)` ¶

`get_namespace(namespace_id)` ¶

`create_namespace(data)` ¶

`update_namespace(namespace_id, changes)` ¶

`delete_namespace(namespace_id)` ¶

`paginate_hwm(query)` ¶

`get_hwm(hwm_id)` ¶

`create_hwm(data)` ¶

`update_hwm(hwm_id, changes)` ¶

`delete_hwm(hwm_id)` ¶

`bulk_delete_hwm(namespace_id, hwm_ids)` ¶

`bulk_copy_hwm(data)` ¶

`get_namespace_permissions(namespace_id)` ¶

`update_namespace_permissions(namespace_id, changes)` ¶

`paginate_hwm_history(query)` ¶

`paginate_namespace_history(query)` ¶

`RetryConfig` ¶

`total` ¶

`backoff_factor` ¶

`status_forcelist` ¶

`backoff_jitter` ¶

`TimeoutConfig` ¶

`connection_timeout` ¶

`request_timeout` ¶

Sync client¶

Quickstart¶

Reference¶

HorizonClientSync ¶

authorize() ¶

ping() ¶

whoami() ¶

paginate_namespaces(query=None) ¶

get_namespace(namespace_id) ¶

create_namespace(data) ¶

update_namespace(namespace_id, changes) ¶

delete_namespace(namespace_id) ¶

paginate_hwm(query) ¶

get_hwm(hwm_id) ¶

create_hwm(data) ¶

update_hwm(hwm_id, changes) ¶

delete_hwm(hwm_id) ¶

bulk_delete_hwm(namespace_id, hwm_ids) ¶

bulk_copy_hwm(data) ¶

get_namespace_permissions(namespace_id) ¶

update_namespace_permissions(namespace_id, changes) ¶

paginate_hwm_history(query) ¶

paginate_namespace_history(query) ¶

RetryConfig ¶

total ¶

backoff_factor ¶

status_forcelist ¶

backoff_jitter ¶

TimeoutConfig ¶

connection_timeout ¶

request_timeout ¶

`HorizonClientSync` ¶

`authorize()` ¶

`ping()` ¶

`whoami()` ¶

`paginate_namespaces(query=None)` ¶

`get_namespace(namespace_id)` ¶

`create_namespace(data)` ¶

`update_namespace(namespace_id, changes)` ¶

`delete_namespace(namespace_id)` ¶

`paginate_hwm(query)` ¶

`get_hwm(hwm_id)` ¶

`create_hwm(data)` ¶

`update_hwm(hwm_id, changes)` ¶

`delete_hwm(hwm_id)` ¶

`bulk_delete_hwm(namespace_id, hwm_ids)` ¶

`bulk_copy_hwm(data)` ¶

`get_namespace_permissions(namespace_id)` ¶

`update_namespace_permissions(namespace_id, changes)` ¶

`paginate_hwm_history(query)` ¶

`paginate_namespace_history(query)` ¶

`RetryConfig` ¶

`total` ¶

`backoff_factor` ¶

`status_forcelist` ¶

`backoff_jitter` ¶

`TimeoutConfig` ¶

`connection_timeout` ¶

`request_timeout` ¶