Coders / Decoders#

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

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 boolean 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

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

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().

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