openage
openage copied to clipboard
SFTtech
More informative `Exception`/Error messages in converter
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:
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?
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
KeyErrorshould be caught and raise aNotImplementedError. - 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.
Hi all! I'm a first time contributor and I am going to try to solve this issue. Very new to open source contributing but hoping I can help here!
