Coders / Decoders#

Encode user-friendly values into internal formats used by the application, and decoder the values back into user-friendly values.

General#

Codec#

class mhi.common.codec.Codec#

Codec: Coder / Decoder

Encode from user-friendly values into an internal value format, and decode from the internal format into (ideally) a user-friendly value.

encode(value: Any) Any#

Encode a user-friendly value into an internal format

Parameters:

value – the value to encode

Returns:

the encoded value

decode(value: Any) Any#

Decode an internal format value into a more user-friendly format

Parameters:

value – the value to decode

Returns:

the decoded value

range()#

Returns the range of values that this codec will encode, as in, maybe passed to encode() and will be returned by decode().

Boolean Codec#

class mhi.common.codec.BooleanCodec#

Boolean Coder / Decoder

Convert Python boolean values to/from the strings “true” and “false”, used by MHI application serialization.

encode(value: Any) str#

Encode a boolean into an MHI serialization string

Parameters:

value (bool) – the value to encode

Returns:

the “encoded” string “true” or “false”

Return type:

str

decode(value: str) bool#

Decode a boolean from an MHI serialization string

Parameters:

value (str) – the string “true” or “false”

Returns:

the decoded value

Return type:

bool

range() Set[bool]#

Returns the range of values that this codec will encode, as in, maybe passed to encode() and will be returned by decode().

Returns:

{False, True}

Map Codec#

class mhi.common.codec.MapCodec(code, *, extras=None)#

Map Coder / Decoder

Convert Python values to/from the strings, used by MHI application serialization.

encode(value: Any) str#

Encode a value into an MHI serialization string

Parameters:

value – the value to encode

Returns:

the encoded string

Return type:

str

decode(value: str) Any#

Decode a value from an MHI serialization string

Parameters:

value (str) – the value to decode

Returns:

the decoded value

range() Set[Any]#

Returns the range of values that this codec will encode, as in, maybe passed to encode() and will be returned by decode().

Returns:

value which can be encoded by the codec.

Return type:

frozenset

Keyword Codec#

class mhi.common.codec.KeywordCodec#

Keyword Codec

Encode values for specific keys of a dictionary from user-friendly values into an internal value format, and decode values for those specific keys from the internal format into (ideally) a user-friendly value.

encodes(keyword: str)#

Predicate, indicating whether or not this keyword codec will encode and decode a particular keyword

Parameters:

keyword (str) – keyword to test

Returns:

True if this codec handles the keyword, False otherwise

Return type:

bool

encode_all(kwargs: Dict[str, Any]) Dict[str, Any]#

Encode all values in the given dictionary which are handled by this codec. Values for unrecognized keywords are unchanged.

Parameters:

kwargs (dict) – a dictionary of keyword-value pairs

Returns:

A new dictionary containing encoded values, where supported.

Return type:

dict

decode_all(kwargs: Dict[str, Any]) Dict[str, Any]#

Decode all values in the given dictionary which are handled by this codec. Values for unrecognized keywords are unchanged.

Parameters:

kwargs (dict) – a dictionary of keyword-value pairs

Returns:

A new dictionary containing decoded values, where supported.

Return type:

dict

decode(value: Any) Any#

Decode an internal format value into a more user-friendly format

Parameters:

value – the value to decode

Returns:

the decoded value

encode(value: Any) Any#

Encode a user-friendly value into an internal format

Parameters:

value – the value to encode

Returns:

the encoded value

range()#

Returns the range of values that this codec will encode, as in, maybe passed to encode() and will be returned by decode().

Simple Codec#

class mhi.common.codec.SimpleCodec(code_dict=None, **codes)#

Keyword Codec

Encode values for specific keys of a dictionary from user-friendly values into an internal value format, and decode values for those specific keys from the internal format into (ideally) a user-friendly value.

Parameters:
  • code_dict (dict) – A dictionary used to translate user-friendly values into internal values.

  • **codes – additional keyword-value translation pairs.

Example

A codec which converts fruit names into integers:

>>> codec = SimpleCodec(apple=1, banana=2, pear=3)
>>> codec.keywords('fruit')
>>> codec.encode('apple')
1
>>> codec.decode(2)
'banana'
>>> codec.encode_all({'animal': 'lion', 'fruit': 'pear'})
{'animal': 'lion', 'fruit': 3}
alternates(code_dict, **codes)#

Provide additional encodings aliases for the codec. These additional options must not duplicate any existing user-friendly keywords, and must not introduce any new values to the mapping.

For instance, a codec may defined the mapping ‘EMTPY’ => 0. An alternate mapping ‘BLANK’ => 0 may be provided, allowing either ‘EMPTY’ or ‘BLANK’ to be encoded as 0, but 0 will always be decoded as ‘EMPTY’.

Parameters:
  • code_dict (dict) – A dictionary of additional translation aliases.

  • **codes – additional keyword-value translation alias pairs.

encode(value)#

Encode a user-friendly value into an internal format

Parameters:

value – the value to encode

Returns:

the encoded value

decode(value)#

Decode an internal format value into a more user-friendly format

Parameters:

value – the value to decode

Returns:

the decoded value

keywords(*keywords: str) None#

Add keywords which will be recognized by this codec when encode_all() or decode_all() is called.

Parameters:

*keywords (str) – List of keywords to associate to this codec

encodes(keyword: str) bool#

Predicate, indicating whether or not this keyword codec will encode and decode a particular keyword

Parameters:

keyword (str) – keyword to test

Returns:

True if this codec handles the keyword, False otherwise

Return type:

bool

range() Set[str]#

Returns the range of values that this codec will encode, as in, maybe passed to encode() and will be returned by decode().

decode_all(kwargs: Dict[str, Any]) Dict[str, Any]#

Decode all values in the given dictionary which are handled by this codec. Values for unrecognized keywords are unchanged.

Parameters:

kwargs (dict) – a dictionary of keyword-value pairs

Returns:

A new dictionary containing decoded values, where supported.

Return type:

dict

encode_all(kwargs: Dict[str, Any]) Dict[str, Any]#

Encode all values in the given dictionary which are handled by this codec. Values for unrecognized keywords are unchanged.

Parameters:

kwargs (dict) – a dictionary of keyword-value pairs

Returns:

A new dictionary containing encoded values, where supported.

Return type:

dict

Fuzzy Codec#

class mhi.common.codec.FuzzyCodec(decode_mapping: Dict[str, str])#

A fuzzy-match codec

This codec matches the value given to encode() against the set of expected inputs, and uses the best match from the expected inputs to determine the correct encoded value.

Note

Unlike the MapCodec and SimpleCodec, the “encoded” values are passed as the keys of the mapping dictionary.

Example:

>>> codec = FuzzyCodec({'ABC': 'apple', 'DEF': 'banana', 'GHI': 'cherry'})
>>> codec.encode('Bnana', warn)
'DEF'
>>> codec.decode('DEF')
'banana'
encode(value: str) str#

Encode a value into an MHI serialization string

A warning is generated if the given value is only an approximate match to the values in the encoding map.

Parameters:

value – the value to encode

Returns:

the encoded string

Return type:

str

encode_to(value: str, active: Set[str]) str#

Encode a value into an MHI serialization string using a restricted set of possible output options.

A warning is generated if the given value is only an approximate match to the values in the active set of the encoding map.

Parameters:
  • value – the value to encode

  • active – a set of ‘enabled’ conversion codes

Returns:

the encoded string

Return type:

str

equivalent(code: str, active: Set[str]) str | None#

If a value can encode_to() to multiple codes, distinguished by which codes are in the active set, then a code may be mapped to a different code with a different active set.

decode(value: str) str#

Decode a value from an MHI serialization string

Parameters:

value (str) – the value to decode

Returns:

the decoded value

range() List[str]#

Returns the range of values that this codec will encode, as in, maybe passed to encode() and will be returned by decode().

Returns:

values which can be encoded by the codec.

active_range(active: Set[str]) List[str]#

Returns the range of values that this codec will encode, as in, maybe passed to encode_to() and will be returned by decode().

Parameters:

active – a set of ‘enabled’ output values

Returns:

values which can be encoded by the codec.

Arrows#

This module is used to encode and decode between a set of compass directions {"N", "E", "SW" } and bit encoded values (0b001001001).

Arrow directions#

Direction

Value

N

1

S

2

W

4

E

8

NW

16

NE

32

SW

64

SE

128

class mhi.common.arrow.Arrow#

Coder/Decoder for compass directions into PSCAD integer representation

encodes(keyword: str) bool#

Predicate, indicating whether or not this keyword codec will encode and decode a particular keyword

Parameters:

keyword (str) – keyword to test

Returns:

True if keyword is 'arrows', False otherwise

Return type:

bool

encode(dirs: int | str | Sequence[str]) int#

Encode one or more directions into an bit-encoded integer:

>>> arrow.encode("N S")
3
>>> arrow.encode(["E", "W"])
12
Parameters:

dirs – the directions to encode

Returns:

a bit-encoded direction value

Return type:

int

decode(dirs: str | int) str#

Decode a bit-encoded integer string into a direction string:

>>> arrow.decode("15")
'N S W E'
Parameters:

dirs (str) – the direction value to decode

Returns:

a space-separated list of compass directions

Return type:

str

range() Set[str]#

Returns the range of values that this codec will encode, as in, maybe passed to encode() and will be returned by decode().

decode_all(kwargs: Dict[str, Any]) Dict[str, Any]#

Decode all values in the given dictionary which are handled by this codec. Values for unrecognized keywords are unchanged.

Parameters:

kwargs (dict) – a dictionary of keyword-value pairs

Returns:

A new dictionary containing decoded values, where supported.

Return type:

dict

encode_all(kwargs: Dict[str, Any]) Dict[str, Any]#

Encode all values in the given dictionary which are handled by this codec. Values for unrecognized keywords are unchanged.

Parameters:

kwargs (dict) – a dictionary of keyword-value pairs

Returns:

A new dictionary containing encoded values, where supported.

Return type:

dict

Colours#

This module is used to encode and decode between common colour names and RGB integer values. Standard Windows and CSS colour names are recognized.

class mhi.common.colour.Colour#

Colour Coder / Decoder

classmethod colour_to_argb(clr: str | int | Sequence[int]) str#

Convert a colour to an ARGB string (#ff_RR_GG_BB)

classmethod argb_to_colour(argb: str) str#

Convert an ARGB (#ff_RR_GG_BB) colour to a named colour, if possible.

encodes(keyword: str) bool#

Predicate, indicating whether or not this keyword codec will encode and decode a particular keyword

Parameters:

keyword (str) – keyword to test

Returns:

True if keyword is 'fg_color', 'bg_color', or 'true-color', False otherwise

Return type:

bool

encode(colour: str | int | Sequence[int]) str#

Encode a named colour into an #ARGB value:

>>> colour = Colour()
>>> colour.encode("RED")
#ffff0000
>>> colour.encode((0, 0, 255))
#ff0000ff
>>> colour.encode("#FA8800")
#fffa8800
Parameters:

colour – the colour to encoded

Returns:

the #ARGB value

Return type:

str

decode(colour: str) str#

Decode an ARGB value into a named colour, if possible:

>>> colour = Colour()
>>> colour.decode(str(0xFF_FF_FF))
'white'
>>> colour.decode(str(0x9A_FA_00))
'mediumspringgreen'
>>> colour.decode('#00FA9A'))
'mediumspringgreen'
>>> colour.decode(str(16418816))
'#ff0088fa'
Parameters:

colour (str) – an #ARGB colour value

Returns:

the name of the colour

Return type:

str

range() Set[str]#

Return the set of known colour names

decode_all(kwargs: Dict[str, Any]) Dict[str, Any]#

Decode all values in the given dictionary which are handled by this codec. Values for unrecognized keywords are unchanged.

Parameters:

kwargs (dict) – a dictionary of keyword-value pairs

Returns:

A new dictionary containing decoded values, where supported.

Return type:

dict

encode_all(kwargs: Dict[str, Any]) Dict[str, Any]#

Encode all values in the given dictionary which are handled by this codec. Values for unrecognized keywords are unchanged.

Parameters:

kwargs (dict) – a dictionary of keyword-value pairs

Returns:

A new dictionary containing encoded values, where supported.

Return type:

dict