id_translation.transform

User-defined transformations of IDs and translations.

Classes

BitmaskTransformer([joiner, overrides, ...])

Transformations for translating bitmask fields.

class BitmaskTransformer(joiner=' & ', *, overrides=None, force_decomposition=False, force_real_translations=True)

Bases: Transformer[int]

Transformations for translating bitmask fields.

IDs must be integers.

Important

When using TOML config, dict keys must be strings. Use alternative format for overrides:

[transform.'<source>'.BitmaskTransformer]
overrides = [
  { id = 0, override = "override-for-id=0" },
  { id = 1, override = "override-for-id=1" },
]

Key names must match exactly, and IDs may not be repeated. For more information about TOML configuration, see Section: Transformations.

Parameters:

• joiner – A string used to join bitmask flag labels.

• overrides – A dict {id: translation}. Use to add or override the translation source.

• force_decomposition – If True, ignore composite values in the translation source.

• force_real_translations – If True, convert MagicDict instances to plain dict using the MagicDict.real attribute. Results such as '<Failed: id=2> & 4:name-of-4' are possible when False, and will be considered hits by translate(max_fails < 1) calls.

Examples

Basic usage.

>>> btr = BitmaskTransformer(overrides={0b000: "NOT_SET", 0b1000: "OVERFLOW!"})

Create a Translator using bitmask transforms for the ‘bitmasks’ source.

>>> from id_translation import Translator
>>> data = {"id": [1, 4, 8], "name": ["name-of-1", "name-of-4", "0b1000"]}
>>> tra = Translator({"bitmasks": data}, transformers={"bitmasks": btr})

Translate some bitmasks!

>>> tra.translate((0b000, 0b101, 8), names="bitmasks")
('NOT_SET', '1:name-of-1 & 4:name-of-4', 'OVERFLOW!')

Note that 0='NOT_SET' was translated even though it’s not in the data, and that 8='0b1000' was replaced by 'OVERFLOW!', as per the overrides specified for the transformer.

Implication of setting force_real_translations=False.

>>> btr = BitmaskTransformer(force_real_translations=False)
>>> tra = Translator({"bitmasks": data}, transformers={"bitmasks": btr})
>>> tra.translate((5, 6), names="bitmasks", max_fails=0.0)
('1:name-of-1 & 4:name-of-4', '<Failed: id=2> & 4:name-of-4')

The translation “succeeded”, even though max_fails=0.0 and 6 = '<Failed: id=2> & 4:name-of-4' was only a partial success. This would’ve raised an error if force_real_translations was not set. The transformer adds real mappings for all composite IDs, so the Translator won’t detect any issues when using MagicDict.real_contains() to verify the results.

classmethod decompose_bitmask(i, /)

Decompose a bitmask into powers of two.

If i is not decomposable, an empty list is returned.

Parameters:

i – Any integer.

Returns:

A decomposition of i into powers of two.

classmethod is_decomposable(i, /)

Check if i is decomposable into bitmask values.

An integer i is decomposable if and only if i > 2, and i is not a power of two.

Parameters:

i – Any integer.

Returns:

True if i is decomposable into powers of two.

try_add_missing_key(key, /, *, translations)

Join decomposed bitmask values using the joiner string.

classmethod update_ids(ids, /)

Add decomposed bitmask values.

update_translations(translations, /)

Join decomposed bitmask values using the joiner string.

Modules

types

Classes used for ID and translation transformation.