bayesline.apiclient.SettingsRegistryClient#

class bayesline.apiclient.SettingsRegistryClient(client: ApiClient) → None#

__init__(client: ApiClient) → None#

Methods

`__init__`(client)
`change_owner_many`(names_or_ids, new_owner, *)	Move settings objects to a new owner.
`delete_many`(names_or_ids, *[, raise_on_errors])	Delete settings objects from the registry for the given names or identifiers.
`get_identifiers`([which])	Get all identifiers for all settings types covered in this registry.
`get_settings_types`()	Get all settings types covered in this registry.
`grant_many`(*, permission_to, for_settings[, ...])	Grant a permission to a group or user for given settings.
`list_user_names`()	List all users that settings can be granted permissions to.
`read_many`(names_or_ids)	Read settings objects from the registry for the given names or identifiers.
`revoke_many`(*, for_settings[, from_groups, ...])	Revoke a permission from a group or user for given settings.
`save_many`(settings, *[, overwrite, ...])	Save multiple settings objects to the registry.
`update_descriptions`(descriptions, *[, ...])	Update the descriptions of multiple existing settings objects.

__init__(client: ApiClient) → None#

get_identifiers(which: Literal['all', 'mine'] = 'all') → SettingsIdentifiers#

Get all identifiers for all settings types covered in this registry.

Parameters#

whichLiteral[“all”, “mine”], default=”all”: ‘mine’ will only return those identfiers owned by the current user ‘all’ will also return those identifiers that the current user is permissioned to READ.

Returns#

SettingsIdentifiers: The identifiers for all settings types covered in this registry.

save_many(settings: Mapping[str | int, DatasetAwareSettings[Settings]], *, overwrite: bool = False, raise_on_errors: bool = True, descriptions: Mapping[str | int, str] | None = None) → SaveResult#

Save multiple settings objects to the registry.

This method is best effort. Partial execution is possible if some settings objects can be saved and others cannot.

Parameters#

settingsMapping[str | int, DatasetAwareSettings[Settings]]: The settings objects to save, keys being the names or global int ids of the settings objects, values being the settings paired with the dataset they apply to. If int ids are used, the settings objects must exist in the registry, which implies that overwrite must be True. The name is a user defined name for the settings object that must consist of only alphanumeric characters, underscores and hyphens and start with a letter. Other users’ settings can be written/updated (if permissioned) by using either the global int identifier or prefixing the name with the user name, e.g. “sebastian.janisch@bayesline.com/SebastiansSettings”.
overwritebool, default=False: If True, overwrite the settings objects if they already exist. If False, mark an error for settings objects that already exist.
raise_on_errorsbool, default=True: If True, raise an exception if any of the settings objects could not be saved. If False, return a SaveResult object with the errors.
descriptionsMapping[str | int, str] | None, default=None: Optional human readable descriptions keyed like settings, stored as registry metadata alongside the name (not part of the settings payload). A missing key means no description on create and leaves an existing description unchanged on overwrite; an empty string clears it.

Raises#

CouldNotSaveSettingsError: If an error captured by the item result is encountered and raise_on_errors is True
SettingsRegistryError: If an unexpected error occurs while saving the settings objects.

Returns#

SaveResult: Result object for the save operation.

update_descriptions(descriptions: Mapping[str | int, str | None], *, raise_on_errors: bool = True) → SaveResult#

Update the descriptions of multiple existing settings objects.

The description is registry-level metadata (a peer of the name), so this does not modify the settings payloads, does not re-validate the settings against their menus (it works even if stored settings are currently invalid) and does not bump the last-updated timestamps.

Requires write permission on each settings object (its owner always has it). This method is best effort. Partial execution is possible if some descriptions can be updated and others cannot.

Parameters#

descriptionsMapping[str | int, str | None]: The new descriptions keyed by the settings names or global int ids. None (or an empty string) clears a description.
raise_on_errorsbool, default=True: If True, raise an exception if any description could not be updated. If False, return a SaveResult object with the errors.

Raises#

CouldNotSaveSettingsError: If an error captured by the item result is encountered and raise_on_errors is True
SettingsRegistryError: If an unexpected error occurs while updating the descriptions.

Returns#

SaveResult: Result object for the update operation.

read_many(names_or_ids: Sequence[str | int]) → Sequence[SettingValid[T] | SettingInvalid | SettingNotFound | SettingNotPermissioned]#

Read settings objects from the registry for the given names or identifiers.

Parameters#

names_or_ids: Sequence[str | int]: The names or identifiers of the settings objects to read. The identifiers are globally unique integers that is assinged when a setting gets first saved to the registry. The names are user defined names for the settings objects that must consist of only alphanumeric characters, underscores and hyphens and start with a letter. Other users’ settings can be read (if permissioned) by using either the global int identifier or prefixing the name with the user name and a forward slash, e.g. “sebastian.janisch@bayesline.com/SebastiansSettings”.

Returns#

Sequence[SettingResult[Settings[Any]]]: The settings results. For valid results, result.value is a DatasetAwareSettings[Settings]; use result.value.setting and result.value.dataset to access the inner settings and dataset.

delete_many(names_or_ids: Sequence[str | int], *, raise_on_errors: bool = True) → DeleteResult#

Delete settings objects from the registry for the given names or identifiers.

This method is best effort. Partial deletions are possible if some settings objects can be deleted and others cannot.

For a setting to be able to be deleted, it must exist, not be referenced by any other settings and the user must have delete permissions for the setting.

Parameters#

names_or_idsSequence[str | int]: The names or identifiers of the settings objects to delete. The identifier is a globally unique integer that is assinged when a setting gets first saved to the registry. The name is a user defined name for the settings object that must consist of only alphanumeric characters, underscores and hyphens and start with a letter. Other users’ settings can be deleted (if permissioned) by using either the global int identifier or prefixing the name with the user name and a forward slash, e.g. “sebastian.janisch@bayesline.com/SebastiansSettings”.
raise_on_errorsbool, default=True: If True, raise an exception if the settings object could not be deleted (any settings that could be deleted will be deleted). If False, return a DeleteResult object with the errors.

Raises#

CouldNotDeleteSettingsError: If an error captured by the item result is encountered and raise_on_errors is True
SettingsRegistryError: If an unexpected error occurs while deleting the settings objects.

Returns#

DeleteResult: Result object for the delete operation.

grant_many(*, permission_to: Literal['read', 'write', 'delete', 'admin'], for_settings: list[str | int], to_groups: list[str] | None = None, to_users: list[str] | None = None, including_references: bool = False, raise_on_errors: bool = True) → PermissionResult#

Grant a permission to a group or user for given settings.

This method is best effort. Partial execution is possible if some settings objects can be granted permissions and others cannot.

Parameters#

permission_to: Literal[“read”, “write”, “delete”, “admin”]: The type of permission to grant. An option includes permission to the preceding options, e.g. ‘delete’ includes ‘read’, ‘write’, and ‘delete’.
for_settings: list[str | int]: The names or identifiers of the settings objects to read. The identifiers are globally unique integers that is assinged when a setting gets first saved to the registry. The names are user defined names for the settings objects that must consist of only alphanumeric characters, underscores and hyphens and start with a letter. Other users’ settings can be used (if permissioned) by using either the global int identifier or prefixing the name with the user name and a forward slash, e.g. “sebastian.janisch@bayesline.com/SebastiansSettings”. To grant permissions of settings that belong to another user the grantor needs to have ‘admin’ permissions for the setting in question.
to_groups: list[str] | None, default=None: The groups to grant the permission to.
to_users: list[str] | None, default=None: The users to grant the permission to (email address).
including_references: bool, default=False: If True, grant the permission to the settings objects and all settings objects that are referenced by the settings objects. If False, grant the permission to the settings objects only.
raise_on_errors: bool, default=True: If True, raise an exception if the permissions could not be granted. If False, return a PermissionResult object with the errors.

Raises#

CouldNotPermissionSettingsError: If an error captured by the item result is encountered and raise_on_errors is True
SettingsRegistryError: If an unexpected error occurs while permissioning the settings objects.

Returns#

PermissionResult: Result objects for the permissioning operation.

revoke_many(*, for_settings: list[str | int], from_groups: list[str] | None = None, from_users: list[str] | None = None, including_references: bool = False, raise_on_errors: bool = True) → PermissionResult#

Revoke a permission from a group or user for given settings.

This method is best effort. Partial execution is possible if some settings objects can be revoked permissions from and others cannot.

Parameters#

for_settings: list[str | int]: The names or identifiers of the settings objects to read. The identifiers are globally unique integers that is assinged when a setting gets first saved to the registry. The names are user defined names for the settings objects that must consist of only alphanumeric characters, underscores and hyphens and start with a letter. Other users’ settings can be used (if permissioned) by using either the global int identifier or prefixing the name with the user name and a forward slash, e.g. “sebastian.janisch@bayesline.com/SebastiansSettings”. To revoke permissions of settings that belong to another user the revoking user needs to have ‘admin’ permissions for the setting in question.
from_groups: list[str] | None, default=None: The groups to revoke the permission from.
from_users: list[str] | None, default=None: The users to revoke the permission from (email address).
including_references: bool, default=False: If True, revoke the permission from the settings objects and all settings objects that are referenced by the settings objects. If False, revoke the permission from the settings objects only.
raise_on_errors: bool, default=True: If True, raise an exception if the permissions could not be revoked. If False, return a PermissionResult object with the errors.

Raises#

CouldNotPermissionSettingsError: If an error captured by the item result is encountered and raise_on_errors is True
SettingsRegistryError: If an unexpected error occurs while permissioning the settings objects.

Returns#

PermissionResult: Result objects for the permissioning operation.

change_owner_many(names_or_ids: Sequence[str | int], new_owner: str, *, include_references: bool = True, dry_run: bool = False, raise_on_errors: bool = True) → ChangeOwnerResult#

Move settings objects to a new owner.

The settings keep their identifiers and names; only the owner changes, so the fully-qualified <owner>/<name> under which they are addressed changes. Stored references pointing at a moved setting are rewritten to its new qualified name in the same operation, so referrers keep resolving. To move a setting under a different name, save it under the desired name first and move that.

This operation is restricted to administrative roles: moving settings into a shared (reserved) owner requires the business admin role, and moving into the system owner requires the admin role.

This method is best effort per item. Items that fail validation are reported in the result; the remaining valid items are moved atomically.

Parameters#

names_or_idsSequence[str | int]: The names or identifiers of the settings objects to move. Other users’ settings can be addressed by using either the global int identifier or prefixing the name with the user name and a forward slash, e.g. “sebastian.janisch@bayesline.com/SebsSettings”.
new_ownerstr: The owner to move the settings objects to. Either a shared (reserved) owner (e.g. a deployment-wide namespace) or a user (email address).
include_referencesbool, default=True: If True, settings referenced by the moved settings (directly or transitively, including bound datasets) are moved to the new owner as well. References already owned by a reserved owner are left untouched. If False, the settings must not reference settings that would remain under a different (non-reserved) owner.
dry_runbool, default=False: If True, validate and report what would be moved without applying any changes.
raise_on_errorsbool, default=True: If True, raise an exception if any settings object could not be moved. If False, return a ChangeOwnerResult object with the errors.

Raises#

CouldNotChangeOwnerError: If an error captured by the item result is encountered and raise_on_errors is True.
PermissionDeniedError: If the caller does not hold the role required for the move.
SettingsRegistryError: If an unexpected error occurs while moving the settings objects.

Returns#

ChangeOwnerResult: Result object for the change-owner operation.

list_user_names() → Mapping[str, str]#

List all users that settings can be granted permissions to.

Returns#

Mapping[str, str]: Mapping of unique user id (e.g. email) to their names.

bayesline.apiclient.SettingsRegistryClient

Contents

bayesline.apiclient.SettingsRegistryClient#

Parameters#

Returns#

Parameters#

Raises#

Returns#

Parameters#

Raises#

Returns#

Parameters#

Returns#

Parameters#

Raises#

Returns#

Parameters#

Raises#

Returns#

Parameters#

Raises#

Returns#

Parameters#

Raises#

Returns#

Returns#