More informative `Exception`/Error messages in converter

[heinezen]

Required skills: Python

Difficulty: Medium

In AoE2's .dat format most associations and assignments of properties are done by IDs (e.g. unit has ability with ID X). The openage converter uses these IDs to lookup the associated openage API property and then map the values from AoE2's .dat structure to the corresponding API object's member values. In short, every property from AoE2 needs to be manually mapped to an openage API property. As such, most of the runtime errors are actually lookup errors (usually Python's KeyError) that occur when an AoE2 property was not mapped to an openage API property.

The goal of this task is to make these errors more informative by catching the generic KeyError from Python and re-raising it with a better message. For example, we can improve the error message by specifying:

• Context of the property (i.e. the property is: ability, resource, unit, tech, ...)
• Data type that is looked up (function, object, string, other ID, ...)

Example

generic message:

File "openage/convert/processor/conversion/de2/tech_subprocessor.py", line 276, in resource_modify_effect
    upgrade_func = DE2TechSubprocessor.upgrade_resource_funcs[resource_id]
KeyError: 208

better message:

File "openage/convert/processor/conversion/de2/tech_subprocessor.py", line 276, in resource_modify_effect
    upgrade_func = DE2TechSubprocessor.upgrade_resource_funcs[resource_id]
KeyError: No subprocessor function found for handling upgrade of civ resource: 208

Use try-except statement where these lookups could be thrown. Remember to use raise ... from to preserve the stack trace of the initial KeyError.

Further reading:

• Converter code
• Converter architecture
• Converter workflow

[duanqn]

When you say

most of the runtime errors are actually lookup errors

Are those errors code defects, or just because the user does not have the correct AoE2 assets?

[heinezen]

Most of them are code defects or missing implementations, e.g.

• For somehing like tech effects, the converter gets the effect ID and looks up a corresponding handler function in a dict. If the ID is not found, the KeyError should be caught and raise a NotImplementedError.
• KeyErrors when looking up unit ID or tech IDs are almost always the converters fault
• Names for converted nyan objects are provided by the converter and a key error here indicates that the name must be added by us

The correct AoE2 assets should be detected before the conversion starts.