Setting Types

class SettingType(...)[source]: Abstract base class for all setting types.

Note

Coercions

If the value received from the the server is of a type incompatible with the local declaration type, the setting may attempt to coerce the value to the local type instead of raising error. Each type may attempt to coerce the value in a different way. In all cases, if a coercion occurs, it will be logged. A setting may customize its coercion behavior by setting the Setting.on_coerce attribute.

setting_type(arg) → SettingType[source]

Factory function for creating setting types. Arg can be one of following types:

A SettingType, in which case it is returned as is.
A primitive type (str, int, float, bool), in which case a setting type for that primitive is returned.
An Enum class, IntFlag, or a generic type alias (see Setting Types with Types and Generic Aliases). Discouraged.

class HeksherEnum(enum_type: Type[Enum])[source]

A setting type for Enum types.

Parameters:: enum_type – The Enum type to use. All the type’s members must be primitives.

class HeksherFlags(flags_type: Type[IntFlag])[source]

A setting type for IntFlag types.

Parameters:: flags_type – The IntFlag type to use.

Note

The resulting heksher type will be a flag type whose options are the IntFlag’s member names.

class MyFlags(IntFlag):
    A = 1
    B = 2
    C = 4

MyFlagsSetting = HeksherFlags(MyFlags)
assert MyFlagsSetting.heksher_string == 'Flags["A","B","C"]'

Note

coercions

If any element of the flags value is not recognized by the IntFlag, that element will be ignored. For example, if the IntFlag has only two members, “green” and “blue”, the server indicates value [“blue”, “red”]. Heksher-py will coerce it to the value [“blue”].

class HeksherSequence(inner: SettingType[T])[source]

A setting type for sequences.

Parameters:: inner – The type of each element in the sequence. Can also be an input to setting_type().

Note

coercions

In addition to any coercions made by the inner type, if any element of the list fails conversion, only that element will be discarded.

class HeksherMapping(inner: SettingType[T])[source]

A setting type for maps.

Parameters:: inner – The type of each value in the map. Can also be an input to setting_type().

Note

coercions

In addition to any coercions made by the inner type, if any value of the dictionary fails conversion, only that key-value pair will be discarded.

Setting Types with Types and Generic Aliases

In older versions, setting types would be created using types and generic aliases. This behaviour is now discouraged, but still supported.

an Enum subclass for an Enum Heksher type.

class Color(Enum):
    blue = "blue"
    green = "green"
    red = "red"

assert setting_type(Color) == HeksherEnum(Color)

an IntFlag subclass for a Flags Heksher type.

class AccessibilityFlags(IntFlag):
    color_blindness = auto()
    large_text = auto()
    text_to_speech = auto()


assert setting_type(AccessibilityFlags) == HeksherFlags(AccessibilityFlags)

a generic specialization of Sequence for a sequence Heksher type, with the inner argument as the generic type.
```
assert setting_type(Sequence[int]) == HeksherSequence(int)
```
a generic specialization of Mapping for a mapping Heksher type, with the value argument as the generic type. The key argument must be str
```
assert setting_type(Mapping[str, int]) == HeksherMapping(int)
```