ISettings

class carb.settings.ISettings

Bases: pybind11_object

The Carbonite Settings interface

Carbonite settings are built on top of the carb.dictionary interface (which is also required in order to use this interface). Many dictionary functions are replicated in settings, but explicitly use the settings database instead of a generic carb.dictionary.Item object.

carb.settings uses keys (or paths) that start with an optional forward-slash and are forward-slash separated (example: “/log/level”). The settings database exists as a root-level carb.dictionary.Item (of type ItemType.DICTIONARY) that is created and maintained by the carb.settings system (typically through the carb.settings.plugin plugin). The root level settings carb.dictionary.Item is accessible through get_settings_dictionary().

Portions of the settings database hierarchy can be subscribed to with subscribe_to_tree_change_events() or individual keys may be subscribed to with subscribe_to_tree_change_events().

Methods

__init__(*args, **kwargs)
create_dictionary_from_settings(self[, path])	Takes a snapshot of a portion of the setting database as a dictionary.Item.
destroy_item(self, arg0)	Destroys the item at the given path.
get(self, path)	Retrieve the stored value at the supplied path as a Python object.
get_as_bool(self, arg0)	Attempts to get the supplied item as a boolean value, either directly or via conversion.
get_as_float(self, arg0)	Attempts to get the supplied item as a floating-point value, either directly or via conversion.
get_as_int(self, arg0)	Attempts to get the supplied item as an integer, either directly or via conversion.
get_as_string(self, arg0)	Attempts to get the supplied item as a string value, either directly or via conversion.
get_settings_dictionary(self[, path])	Access the setting database as a dictionary.Item
initialize_from_dictionary(self, arg0)	Performs a one-time initialization from a given dictionary.Item.
is_accessible_as(self, arg0, arg1)	Checks if the item could be accessible as the provided type, either directly or via a cast.
set(self, path, value)	Sets the given value at the supplied path.
set_bool(self, arg0, arg1)	Sets the boolean value at the supplied path.
set_bool_array(self, arg0, arg1)	Sets the given array at the supplied path.
set_default(self, path, value)
set_default_bool(self, arg0, arg1)	Sets a value at the given path, if and only if one does not already exist.
set_default_float(self, arg0, arg1)	Sets a value at the given path, if and only if one does not already exist.
set_default_int(self, arg0, arg1)	Sets a value at the given path, if and only if one does not already exist.
set_default_string(self, arg0, arg1)	Sets a value at the given path, if and only if one does not already exist.
set_float(self, arg0, arg1)	Sets the floating-point value at the supplied path.
set_float_array(self, arg0, arg1)	Sets the given array at the supplied path.
set_int(self, arg0, arg1)	Sets the integer value at the supplied path.
set_int_array(self, arg0, arg1)	Sets the given array at the supplied path.
set_string(self, arg0, arg1)	Sets the string value at the supplied path.
set_string_array(self, arg0, arg1)	Sets the given array at the supplied path.
subscribe_to_node_change_events(self, arg0, arg1)	Subscribes to node change events about a specific item.
subscribe_to_tree_change_events(self, arg0, arg1)	Subscribes to change events for all items in a subtree.
unsubscribe_to_change_events(self, id)	Unsubscribes from change events.
update(self, arg0, arg1, arg2, arg3)	Merges the source dictionary.Item into the settings database.

__init__(*args, **kwargs)

create_dictionary_from_settings(self: carb.settings._settings.ISettings, path: str = '') → carb.dictionary._dictionary.Item

Takes a snapshot of a portion of the setting database as a dictionary.Item.

Parameters

path – An optional path from root to access. “/” or “” is interpreted to be the settings database root.

destroy_item(self: carb.settings._settings.ISettings, arg0: str) → None

Destroys the item at the given path.

Any objects that reference the given path become invalid and their use is undefined behavior.

Parameters

path – Settings database key path (i.e. “/log/level”).

get(self: carb.settings._settings.ISettings, path: str) → object

Retrieve the stored value at the supplied path as a Python object.

An array value will be returned as a list. If the value does not exist, None will be returned.

Parameters

path – Settings database key path (i.e. “/log/level”).

Returns

A Python object representing the stored value.

get_as_bool(self: carb.settings._settings.ISettings, arg0: str) → bool

Attempts to get the supplied item as a boolean value, either directly or via conversion.

Parameters

path – Settings database key path (i.e. “/log/level”).

Returns

a boolean value representing the stored value. If conversion fails, False is returned.

Return type

Boolean

get_as_float(self: carb.settings._settings.ISettings, arg0: str) → float

Attempts to get the supplied item as a floating-point value, either directly or via conversion.

Parameters

path – Settings database key path (i.e. “/log/level”).

Returns

a floating-point value representing the stored value. If conversion fails, 0.0 is returned.

Return type

Float

get_as_int(self: carb.settings._settings.ISettings, arg0: str) → int

Attempts to get the supplied item as an integer, either directly or via conversion.

Parameters

path – Settings database key path (i.e. “/log/level”).

Returns

an integer value representing the stored value. If conversion fails, 0 is returned.

Return type

Integer

get_as_string(self: carb.settings._settings.ISettings, arg0: str) → str

Attempts to get the supplied item as a string value, either directly or via conversion.

Parameters

path – Settings database key path (i.e. “/log/level”).

Returns

a string value representing the stored value. If conversion fails, “” is returned.

Return type

String

get_settings_dictionary(self: carb.settings._settings.ISettings, path: str = '') → carb.dictionary._dictionary.Item

Access the setting database as a dictionary.Item

Accesses the setting database as a dictionary.Item, which allows use of carb.dictionary functions directly.

WARNING: The root dictionary.Item is owned by carb.settings and must not be altered or destroyed.

Parameters

path – An optional path from root to access. “/” or “” is interpreted to be the settings database root.

initialize_from_dictionary(self: carb.settings._settings.ISettings, arg0: carb.dictionary._dictionary.Item) → None

Performs a one-time initialization from a given dictionary.Item.

NOTE: This function may only be called once. Subsequent calls will result in an error message logged.

Parameters

dictionary – A dictionary.Item to initialize the settings database from. The items are copied into the root of the settings database.

is_accessible_as(self: carb.settings._settings.ISettings, arg0: carb.dictionary._dictionary.ItemType, arg1: str) → bool

Checks if the item could be accessible as the provided type, either directly or via a cast.

Parameters

• itemType – carb.dictionary.ItemType to check for.

• path – Settings database key path (i.e. “/log/level”).

Returns

True if the item is accessible as the provided type; False otherwise.

Return type

boolean

set(self: carb.settings._settings.ISettings, path: str, value: object) → None

Sets the given value at the supplied path.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• value – A Python object. The carb.dictionary.ItemType is inferred from the type of the object; if the type is not supported, the value is ignored. Both tuples and lists are treated as arrays (a special kind of ItemType.DICTIONARY).

set_bool(self: carb.settings._settings.ISettings, arg0: str, arg1: bool) → None

Sets the boolean value at the supplied path.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• value – A boolean value to store.

set_bool_array(self: carb.settings._settings.ISettings, arg0: str, arg1: List[bool]) → None

Sets the given array at the supplied path.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• array – A tuple or list of boolean values.

set_default(self: carb.settings._settings.ISettings, path: str, value: object) → None

set_default_bool(self: carb.settings._settings.ISettings, arg0: str, arg1: bool) → None

Sets a value at the given path, if and only if one does not already exist.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• value – Value that will be stored at the given path if a value does not already exist there.

set_default_float(self: carb.settings._settings.ISettings, arg0: str, arg1: float) → None

Sets a value at the given path, if and only if one does not already exist.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• value – Value that will be stored at the given path if a value does not already exist there.

set_default_int(self: carb.settings._settings.ISettings, arg0: str, arg1: int) → None

Sets a value at the given path, if and only if one does not already exist.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• value – Value that will be stored at the given path if a value does not already exist there.

set_default_string(self: carb.settings._settings.ISettings, arg0: str, arg1: str) → None

Sets a value at the given path, if and only if one does not already exist.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• value – Value that will be stored at the given path if a value does not already exist there.

set_float(self: carb.settings._settings.ISettings, arg0: str, arg1: float) → None

Sets the floating-point value at the supplied path.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• value – A floating-point value to store.

set_float_array(self: carb.settings._settings.ISettings, arg0: str, arg1: List[float]) → None

Sets the given array at the supplied path.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• array – A tuple or list of floating-point values.

set_int(self: carb.settings._settings.ISettings, arg0: str, arg1: int) → None

Sets the integer value at the supplied path.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• value – An integer value to store.

set_int_array(self: carb.settings._settings.ISettings, arg0: str, arg1: List[int]) → None

Sets the given array at the supplied path.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• array – A tuple or list of integer values.

set_string(self: carb.settings._settings.ISettings, arg0: str, arg1: str) → None

Sets the string value at the supplied path.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• value – A string value.

set_string_array(self: carb.settings._settings.ISettings, arg0: str, arg1: List[str]) → None

Sets the given array at the supplied path.

Parameters

• path – Settings database key path (i.e. “/log/level”).

• array – A tuple or list of strings.

subscribe_to_node_change_events(self: carb.settings._settings.ISettings, arg0: str, arg1: Callable[[carb.dictionary._dictionary.Item, carb.settings._settings.ChangeEventType], None]) → carb.settings._settings.SubscriptionId

Subscribes to node change events about a specific item.

When finished with the subscription, call unsubscribe_to_change_events().

Parameters

• path – Settings database key path (i.e. “/log/level”) to subscribe to.

• eventFn – A function that is called for each change event.

subscribe_to_tree_change_events(self: carb.settings._settings.ISettings, arg0: str, arg1: Callable[[carb.dictionary._dictionary.Item, carb.dictionary._dictionary.Item, carb.settings._settings.ChangeEventType], None]) → carb.settings._settings.SubscriptionId

Subscribes to change events for all items in a subtree.

When finished with the subscription, call unsubscribe_to_change_events().

Parameters

• path – Settings database key path (i.e. “/log/level”) to subscribe to.

• eventFn – A function that is called for each change event.

unsubscribe_to_change_events(self: carb.settings._settings.ISettings, id: carb.settings._settings.SubscriptionId) → None

Unsubscribes from change events.

Parameters

id – The handle returned from subscribe_to_tree_change_events() or subscribe_to_node_change_events().

update(self: carb.settings._settings.ISettings, arg0: str, arg1: carb.dictionary._dictionary.Item, arg2: str, arg3: object) → None

Merges the source dictionary.Item into the settings database.

Destination path need not exist and missing items in the path will be created as ItemType.DICTIONARY.

Parameters

• path – Settings database key path (i.e. “/log/level”). Used as the destination location within the setting database. “/” is considered to be the root.

• dictionary – A dictionary.Item used as the base of the items to merge into the setting database.

• dictionaryPath – A child path of `dictionary` to use as the root for merging. May be None or an empty string in order to use `dictionary` directly as the root.

• updatePolicy – One of dictionary.UpdateAction to use as the policy for updating.