pyplanet.contrib.setting

class pyplanet.contrib.setting.manager.AppSettingManager(instance, app)[source]

The local app setting manager is the one you should use to register settings to inside of your app.

You can use this manager like this:

from pyplanet.contrib.setting import Setting

async def on_start(self):
        await self.context.setting.register(
                Setting('feature_a', 'Enable feature A', Setting.CAT_FEATURES, type=bool, description='Enable feature A'),
                Setting('feature_b', 'Enable feature B', Setting.CAT_FEATURES, type=bool, description='Enable feature B'),
        )

For more information about the settings, categories, types, and all other options. Look at the Settings documentation.

Warning

Don’t initiate this class yourself.

get_all(prefetch_values=True)[source]

Retrieve a list of settings, with prefetched values, so get_value is almost instant (or use ._value, not recommended).

Parameters:prefetch_values – Prefetch the values in this call. Defaults to True.
Returns:List with setting objects.
get_categories()[source]

Get all the categories we have registered. Returns a dict with label as key, and count + name as values.

get_setting(key, prefetch_values=True)[source]

Get setting by key and optionally fetch the value if not yet fetched.

Parameters:
  • key – Key string
  • prefetch_values – Prefetch the values if not yet fetched?
Returns:

Setting instance.

Raise:

SettingException

register(*settings)[source]

Register your setting(s). This will create default values when the setting has not yet been inited before.

Parameters:settings (pyplanet.contrib.setting.setting._Setting) – Setting(s) given.
class pyplanet.contrib.setting.manager.GlobalSettingManager(instance)[source]

Global Setting manager is available at the instance. instance.setting_manager.

Warning

Don’t use the setting_manager for registering app settings! Use the app setting manager instead!

Don’t initiate this class yourself.

create_app_manager(app_config)[source]

Create app setting manager.

Parameters:app_config (pyplanet.apps.config.AppConfig) – App Config instance.
Returns:Setting Manager
Return type:pyplanet.contrib.setting.manager.AppSettingManager
get_all(prefetch_values=True)[source]

Retrieve a list of settings, with prefetched values, so get_value is almost instant (or use ._value, not recommended).

Parameters:prefetch_values – Prefetch the values in this call. Defaults to True.
Returns:List with setting objects.
get_app_manager(app)[source]

Get the app manager for a specified app label or config instance.

Parameters:app – App label in string or the app config instance.
Returns:App manager instance.
Return type:pyplanet.contrib.setting.manager.AppSettingManager
get_apps(prefetch_values=True)[source]

Get all the app label + names for all the settings we can find in our registry. Returns a dict with label as key, and count + name as values.

Parameters:prefetch_values – Prefetch the values in this call. Defaults to True.
Returns:List with setting objects.
get_categories(prefetch_values=True)[source]

Get all the categories we have registered. Returns a dict with label as key, and count + name as values.

Parameters:prefetch_values – Prefetch the values in this call. Defaults to True.
Returns:List with setting objects.
get_setting(app_label, key, prefetch_values=True)[source]

Get setting by key and optionally fetch the value if not yet fetched.

Parameters:
  • app_label – Namespace (mostly app label).
  • key – Key string
  • prefetch_values – Prefetch the values if not yet fetched?
Returns:

Setting instance.

Raise:

SettingException

recursive_settings

Retrieve all settings, of all submanagers.

The setting contrib contains code for managing and providing settings contexts.

class pyplanet.contrib.setting.Setting(key: str, name: str, category: str, type=<class 'str'>, description: str = None, choices=None, default=None, change_target=None)[source]

The setting class is for defining a setting for the end-user. This setting can be changed with /settings and //settings.

With this class you can define or manage your setting that is going to be public for all other apps and end-user.

You can get notified of changes with the change_target in the init of this class. Point this to a method (async or sync) with the following params: old_value and new_value.

Example:

my_setting = Setting(
        'dedimania_code', 'Dedimania Server Code', Setting.CAT_KEYS, type=str,
        description='The secret dedimania code. Get one at $lhttp://dedimania.net/tm2stats/?do=register',
        default=None
)

my_other_setting = Setting(
        'sample_boolean', 'Booleans for the win!', Setting.CAT_BEHAVIOUR, type=bool, description='Example',
)
__init__(key: str, name: str, category: str, type=<class 'str'>, description: str = None, choices=None, default=None, change_target=None)[source]

Create setting with properties.

Parameters:
  • key – Key of setting, this is mainly only used for the backend and for referencing the setting. You should keep this unique in your app!
  • name – Name of the setting that will be displayed as a small label to the player.
  • category – Category from Categories.*. Must be provided!
  • type – Type of value to expect, use python types here. str by default.
  • description – Description to provide help and instructions to the player.
  • choices – List or tuple with choices, only when wanting to restrict values to selected options.
  • default – Default value if not provided from database. This will be returned. Defaults to None.
  • change_target – Target method to call when the setting value has been changed.
__str__()[source]

Return str(self).

__weakref__

list of weak references to the object (if defined)

clear()[source]

Clear the value in the data storage. This will set the value to None, and will return the default value on request of data.

Raise:NotFound / SerializationException
get_model()[source]

Get the model for the setting. This will return the model instance or raise an exception when not found.

Returns:Model instance
Raise:NotFound
get_value(refresh=False)[source]

Get the value or the default value for the setting model.

Parameters:refresh – Force a refresh of the value.
Returns:Value in the desired type and unserialized from database/storage.
Raise:NotFound / SerializationException
initiate_setting()[source]

Initiate database record for setting.

serialize_value(value)[source]

Serialize the python value to the data store value, based on the type of the setting.

Parameters:value – Python Value.
Returns:Database Value
set_value(value)[source]

Set the value, this will serialize and save the setting to the data storage.

Parameters:value – Python value input.
Raise:NotFound / SerializationException
type_name

Get the name of the specified type in string format, suited for displaying to end-user.

Returns:User friendly name of type.
unserialize_value(value)[source]

Unserialize the datastorage value to the python value, based on the type of the setting.

Parameters:value – Value from database.
Returns:Python value.
Raises:pyplanet.contrib.setting.exceptions.SerializationException – SerializationException
class pyplanet.contrib.setting.GlobalSettingManager(instance)[source]

Global Setting manager is available at the instance. instance.setting_manager.

Warning

Don’t use the setting_manager for registering app settings! Use the app setting manager instead!

Don’t initiate this class yourself.

__init__(instance)[source]

Initiate, should only be done from the core instance.

Parameters:instance (pyplanet.core.instance.Instance) – Instance.
create_app_manager(app_config)[source]

Create app setting manager.

Parameters:app_config (pyplanet.apps.config.AppConfig) – App Config instance.
Returns:Setting Manager
Return type:pyplanet.contrib.setting.manager.AppSettingManager
get_all(prefetch_values=True)[source]

Retrieve a list of settings, with prefetched values, so get_value is almost instant (or use ._value, not recommended).

Parameters:prefetch_values – Prefetch the values in this call. Defaults to True.
Returns:List with setting objects.
get_app_manager(app)[source]

Get the app manager for a specified app label or config instance.

Parameters:app – App label in string or the app config instance.
Returns:App manager instance.
Return type:pyplanet.contrib.setting.manager.AppSettingManager
get_apps(prefetch_values=True)[source]

Get all the app label + names for all the settings we can find in our registry. Returns a dict with label as key, and count + name as values.

Parameters:prefetch_values – Prefetch the values in this call. Defaults to True.
Returns:List with setting objects.
get_categories(prefetch_values=True)[source]

Get all the categories we have registered. Returns a dict with label as key, and count + name as values.

Parameters:prefetch_values – Prefetch the values in this call. Defaults to True.
Returns:List with setting objects.
get_setting(app_label, key, prefetch_values=True)[source]

Get setting by key and optionally fetch the value if not yet fetched.

Parameters:
  • app_label – Namespace (mostly app label).
  • key – Key string
  • prefetch_values – Prefetch the values if not yet fetched?
Returns:

Setting instance.

Raise:

SettingException

recursive_settings

Retrieve all settings, of all submanagers.

Exceptions for Setting Manager.

exception pyplanet.contrib.setting.exceptions.SerializationException[source]

Setting value (un)serialization problems

exception pyplanet.contrib.setting.exceptions.SettingException[source]

Abstract setting exception.

exception pyplanet.contrib.setting.exceptions.TypeUnknownException[source]

The type is unknown.