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
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
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
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 thekeyword
,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.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()
ordecode_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 thekeyword
,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 bydecode()
.
- 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
andSimpleCodec
, 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 theactive
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 bydecode()
.- 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 bydecode()
.- 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
).
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
ifkeyword
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 bydecode()
.
- 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
ifkeyword
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