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.