bayesline.api.AsyncTypedSettingsRegistry

class bayesline.api.AsyncTypedSettingsRegistry

Abstract base class for typed settings registries.

A typed settings registry covers exactly one settings type, e.g. UniverseSettings.

The second type parameter M is the corresponding SettingsMenu subtype (e.g. UniverseSettingsMenu) and narrows the return type of available_settings.

__init__()

Methods

__init__()
available_settings(dataset_name)	Return the menu the validator validates against for this dataset.
delete(name_or_id, *[, raise_on_errors])	Delete a settings object from the registry for the given name or identifier.
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 the settings type covered by this registry.
grant(*, permission_to, for_setting[, ...])	Grant a permission to a group or user for given settings.
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(name_or_id)	Read a settings object from the registry for the given name or identifier.
read_many(names_or_ids)	Read settings objects from the registry for the given names or identifiers.
revoke(*, for_setting[, from_groups, ...])	Revoke a permission from a group or user for given settings.
revoke_many(*, for_settings[, from_groups, ...])	Revoke a permission from a group or user for given settings.
save(name_or_id, settings, *[, overwrite, ...])	Save (or update) a settings object to the registry.
save_many(settings, *[, overwrite, ...])	Save multiple settings objects to the registry.

Attributes

settings_type

Get the settings type covered by this registry.

abstract property settings_type: type[T]

Get the settings type covered by this registry.

Returns

type[T]

The settings type covered by this registry.

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

Get all identifiers for the settings type covered by 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

All identifiers for the settings type covered by this registry.

abstract async save(name_or_id: str | int, settings: DatasetAwareSettings[T], *, overwrite: bool = False, raise_on_errors: bool = True) → SaveItemResult

Save (or update) a settings object to the registry.

Parameters

name_or_idstr | int

The name of the settings object to save or the global int id of the settings object to update. If int id is 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”.

settingsDatasetAwareSettings[T]

The settings object paired with the dataset it applies to. Use settings.with_dataset(dataset) on a plain Settings to obtain the wrapper.

overwritebool, default=False

If True, overwrite the settings object if it already exists. If False, mark an error if the settings object already exists.

raise_on_errorsbool, default=True

If True, raise an exception if the settings object could not be saved. If False, return a SaveItemResult 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 saving the settings object.

Returns

SaveItemResult

Result object for the save operation.

abstract async save_many(settings: Mapping[str | int, DatasetAwareSettings[T]], *, overwrite: bool = False, raise_on_errors: bool = True) → 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[T]]

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.

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.

abstract async read(name_or_id: str | int) → SettingValid[T] | SettingInvalid | SettingNotFound | SettingNotPermissioned

Read a settings object from the registry for the given name or identifier.

The setting must be of the correct type for this registry.

Parameters

name_or_idstr | int

The name or identifier of the settings object to read. 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 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

SettingResult[T]

The settings result. For valid results, result.value is a DatasetAwareSettings[T] — use result.value.setting for the bare settings and result.value.dataset for the dataset.

abstract async 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.

The settings must be of the correct type for this registry.

Parameters

names_or_idsSequence[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[T]]

The settings results. For valid results, result.value is a DatasetAwareSettings[T]; use result.value.setting for the bare settings and result.value.dataset for the dataset.

abstract async delete(name_or_id: str | int, *, raise_on_errors: bool = True) → DeleteItemResult

Delete a settings object from the registry for the given name or identifier.

The setting must be of the correct type for this registry.

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

name_or_idstr | int

The name or identifier of the settings object to delete. 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 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. If False, return a DeleteItemResult 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 object.

Returns

DeleteItemResult

Result object for the delete operation.

abstract async 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.

The settings must be of the correct type for this registry.

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.

abstract async grant(*, permission_to: Literal['read', 'write', 'delete', 'admin'], for_setting: str | int, to_groups: list[str] | None = None, to_users: list[str] | None = None, including_references: bool = False, raise_on_errors: bool = True) → PermissionItemResult

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

The settings must be of the correct type for this registry.

Parameters

permission_toLiteral[“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_settingstr | int

The name or identifier of the settings object to grant permissions to. The identifier is globally unique integers that is assinged when a setting gets first saved to the registry. The name is user defined for the settings object 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 either ‘admin’ permissions for the setting in question.

to_groupslist[str] | None, default=None

The groups to grant the permission to.

to_userslist[str] | None, default=None

The users to grant the permission to (email address).

including_referencesbool, 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_errorsbool, default=True

If True, raise an exception if the permissions could not be granted. If False, return a PermissionItemResult 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

PermissionItemResult

Result object for the permissioning operation.

abstract async 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.

The settings must be of the correct type for this registry.

Parameters

permission_toLiteral[“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_settingslist[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_groupslist[str] | None, default=None

The groups to grant the permission to.

to_userslist[str] | None, default=None

The users to grant the permission to (email address).

including_referencesbool, 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_errorsbool, 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 object for the permissioning operation.

abstract async revoke(*, for_setting: str | int, from_groups: list[str] | None = None, from_users: list[str] | None = None, including_references: bool = False, raise_on_errors: bool = True) → PermissionItemResult

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

The settings must be of the correct type for this registry.

Parameters

for_settingstr | 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_groupslist[str] | None, default=None

The groups to revoke the permission from.

from_userslist[str] | None, default=None

The users to revoke the permission from (email address).

including_referencesbool, 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_errorsbool, default=True

If True, raise an exception if the permissions could not be revoked. If False, return a PermissionItemResult 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

PermissionItemResult

Result object for the permissioning operation.

abstract async 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.

The settings must be of the correct type for this registry.

Parameters

for_settingslist[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_groupslist[str] | None, default=None

The groups to revoke the permission from.

from_userslist[str] | None, default=None

The users to revoke the permission from (email address).

including_referencesbool, 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_errorsbool, 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 object for the permissioning operation.

abstract async 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.

abstract async available_settings(dataset_name: str) → M

Return the menu the validator validates against for this dataset.

Settings menus contain supersets of the settings options that are available for the given dataset.

Parameters

dataset_namestr

The name of the dataset to get the settings menu for.

Returns

M

The settings menu for this loader for the given dataset.