What's the intended purpose of keymap_items.find_from_operator?

This one is probably for @ideasman42 but I would welcome insights anyone else might have as well. And before you reply with “duh, finding a keymap item using its operator!”, hear me out. That’s what I want to use it for but but the more I look into it the less I understand what the intent of the function is. There isn’t really any discussion on the initial commit and the documentation isn’t clear on what it would be used for.

The biggest issue I see is that if you have more than one keymap item that uses a particular operator, find_from_operator apparently only returns the first one it finds rather than a list of all the keymap items using this operator. This probably wouldn’t be that big of a deal if you could also narrow down the search by using properties or specific events, but it’s not granular enough for that. There actually is a ‘properties’ parameter that is undocumented, but it’s not clear to me how it is intended to be used. I would have expected it to be a list of property tuples, but it’s expecting an OperatorProperties type- which confuses me because if I have a reference to the OperatorProperties I likely already have the keymap item itself. Either one of these issues would be something you could work around if not for the other. If find_from_operator returned a list you could manually compare properties. If you could specify properties you could get a single keymap item returned that was exactly what you wanted.

Best I can tell, find_from_operator is only useful if you only have an operator’s idname registered a single time in any given keymap.