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.pscad.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

Boolean Codec¶

class mhi.pscad.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

static range() → Tuple[bool, 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
Return type: Tuple[Bool, Bool]

Map Codec¶

class mhi.pscad.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() → FrozenSet[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.pscad.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

Simple Codec¶

class mhi.pscad.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

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

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

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.pscad.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: Union[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: Union[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

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.pscad.common.colour.Colour¶

Colour Coder / Decoder

classmethod colour_to_argb(clr: Union[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: Union[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(0xFFFFFF))
'white'
>>> colour.decode(str(0x9AFA00))
'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

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

Coders / Decoders¶

Codec¶

Boolean Codec¶

Map Codec¶

Keyword Codec¶

Simple Codec¶

Arrows¶

Colours¶

Table of Contents

Previous topic

Next topic

This Page