libretro.drivers.options.dict¶

OptionDriver implementation backed by a Mapping of values.

See also

OptionDriver: The protocol this class implements.

__init__(version=2, categories_supported=None, variables=None)[source]¶

Initialize the driver with a chosen interface version and seed values.

Parameters:

version (int) – The core-options interface version to advertise (0, 1, or 2).
categories_supported (bool | None) – Whether to advertise category support. Defaults to True for v2 and False otherwise.
variables (Mapping[str, str] | Mapping[bytes, bytes] | None) – Initial option values, keyed by option key. String keys and values are encoded as UTF-8.

Raises:

ValueError – If version is not 0, 1, or 2.

get_variable(key)[source]¶

Return the current value of a single core option.

Corresponds to RETRO_ENVIRONMENT_GET_VARIABLE.

Parameters:: key (bytes) – The key of the core option to retrieve.
Return type:: bytes | None
Returns:: None if no option with the key given by key exists. Otherwise, the option’s current value if it has a valid one (as determined by the option definitions), or the default value otherwise.

set_variables(variables)[source]¶

Corresponds to RETRO_ENVIRONMENT_SET_VARIABLES.

Parameters:: variables (Collection[retro_variable] | None) – The variables registered by the core, or None to clear the registration.

property variable_updated¶

Whether any core option has been changed since the core last queried it.

Corresponds to RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE. Reading this property is expected to clear the flag.

property version¶

The core options interface version this driver implements.

Corresponds to RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION.

set_options(options)[source]¶

Corresponds to RETRO_ENVIRONMENT_SET_CORE_OPTIONS.

Parameters:: options (Collection[retro_core_option_definition] | None) – The options registered by the core, or None to clear the registration.

set_options_intl(options)[source]¶

Corresponds to RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL.

Parameters:: options (retro_core_options_intl | None) – The options registered by the core, or None to clear the registration.

set_display(key, visible)[source]¶

Show or hide a single core option in the frontend’s UI.

Corresponds to RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY.

Parameters:

key (bytes) – The key of the option to update.
visible (bool) – True to show the option, False to hide it.

set_options_v2(options)[source]¶

Corresponds to RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2.

Parameters:: options (retro_core_options_v2 | None) – The options registered by the core, or None to clear the registration.

set_options_v2_intl(options)[source]¶

Corresponds to RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL.

Parameters:: options (retro_core_options_v2_intl | None) – The options registered by the core, or None to clear the registration.

property update_display_callback¶

The display-update callback registered by the core, if any.

Set via RETRO_ENVIRONMENT_SET_CORE_OPTIONS_UPDATE_DISPLAY_CALLBACK. None if the core has not registered one.

Parameters:: callback – The callback to register, or None to clear it.
Raises:: UnsupportedEnvCall – If this driver does not support the display-update callback.

set_variable(var, value)[source]¶

Set a single core option’s value.

Corresponds to RETRO_ENVIRONMENT_SET_VARIABLE.

Parameters:

var (bytes) – The key of the option to set.
value (bytes) – The new value for the option.

Return type:

bool

Returns:

True if the value was accepted by the driver.

property supports_categories¶: Whether this driver groups core options into categories (v2 feature).

class VariableMapping[source]¶

Bases: MutableMapping[bytes, bytes]

Doesn’t fully implement MutableMapping since the semantics aren’t exactly the same as a normal dict (e.g. setting an invalid value doesn’t actually set it), but core options can be mutated with __setitem__ and __delitem__.

__init__(options)[source]¶

Initialize the mapping with a back-reference to its owning driver.

Parameters:: options (DictOptionDriver) – The DictOptionDriver this mapping reads from and writes to.

self[key][source]¶

Get the value of an option variable by key, or its default value if it hasn’t been set yet.

Parameters:: key (str | bytes) – The key of the variable to get
Return type:: bytes
Returns:: The value of the variable, or its default value if it hasn’t been set.
Raises:: KeyError – If no option with the given key has been registered

self[key] = value[source]¶

Set the value of an option variable by key.

Parameters:

key (str | bytes) – The key of the variable to set
value (str | bytes) – The value to set for the variable. str and bytes are accepted, but the value will always be stored as bytes.

Values that haven’t been registered can be set, but will only be exposed to the core if it registers an option with that key and value later on.

del self[key][source]¶: Delete an option variable by key; future attempts to get this variable will return its default value until it’s set again. If the option isn’t set, this does nothing.

len(self)[source]¶

iter(self)[source]¶

Return type:: Iterator[bytes]

key in self¶

classmethod __new__(*args, **kwargs)¶

clear() → None. Remove all items from D.¶

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair¶: as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D¶

update([E, ]**F) → None. Update D from mapping/iterable E and F.¶: If E present and has a .keys() method, does: for k in E.keys(): D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values¶

property variables¶

A live, mutable mapping of option keys to current values.

Mutating the returned mapping changes the driver’s stored option values and is the primary way to drive option changes from a Python test harness.

class VisibilityMapping[source]¶

Bases: Mapping[bytes, bool]

A read-only Mapping of option key to visibility flag.

Used by DictOptionDriver.visibility to expose per-option visibility decisions to test code.

key in self¶

classmethod __new__(*args, **kwargs)¶

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

values() → an object providing a view on D's values¶

__init__(options)[source]¶

Initialize the mapping with a back-reference to its owning driver.

Parameters:: options (DictOptionDriver) – The DictOptionDriver this mapping reads from.

self[key][source]¶

Return type:: bool

len(self)[source]¶

Return type:: int

iter(self)[source]¶

Return type:: Iterator[bytes]

classmethod __new__(*args, **kwargs)¶

property visibility¶: A mapping of option keys to whether the frontend would show that option.

property categories¶

The v2 option categories registered by the core, indexed by category key.

None if the core has not registered any categories or this driver does not support categories.

property definitions¶

The v2 option definitions registered by the core, indexed by option key.

None if the core has not registered any v2 definitions.