You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Thanks for the report @flying-sheep. I think the field name "role" is correct in this context, though the roles passed by the Python handler are mostly incorrect, yes. Lets continue the discussion in mkdocstrings/python#339 since I think mkdocstrings doesn't have to change anything.
OK, to summarize what happened over there: you used the term “role”, then got confused, realized that indeed there’s “roles” and “object types” with a 1:1 mapping that is identity for some of them, and now understand the distinction.
That’s why I filed this issue: The inventory contains “object types”, not “roles”. I think the simplest would be that the Python handler emits object types directly, which directly end up in the inventory.
It’s of course an option to just misname the concept here and talk about “roles” while we’re consistently handling “object types”, but to spare others the confusion, the correct terminology should be used here.
Yes, I think I finally understand it 🙂 I think sphobjinv's docs should be updated to use "object type" too, since that's my go-to reference. Thanks for bringing this to my attention!
I'd love to rename the field from "role" to "object type" in mkdocstrings and handlers, but I'm afraid this would be a breaking change. I'll try to see if I can get some stats on how many projects would be affected. There might be a deprecation path too, to keep backward compatibility.
you could rename it and accept the old role argument with a DeprecationWarning. That way it still works, but it’s clear that it’s not the right thing to do.
OK even though I can't find any real usage of InventoryItem in the wild, I'll take the safe route and avoid any breaking change. The thing is role is currently a positional-or-keyword parameter. That makes it impossible to deprecate with backward compatibility without a very ugly new signature, if at all possible. Since mkdocstrings is in maintenance mode, lets keep it that way. I don't think too many people read mkdocstrings' inventory code to learn about Sphinx's objects.inv anyway. I'll still fix the object types passed from the Python handler.
Activity
pawamoy commentedon Sep 3, 2026
Thanks for the report @flying-sheep. I think the field name "role" is correct in this context, though the roles passed by the Python handler are mostly incorrect, yes. Lets continue the discussion in mkdocstrings/python#339 since I think mkdocstrings doesn't have to change anything.
flying-sheep commentedon Sep 4, 2026
OK, to summarize what happened over there: you used the term “role”, then got confused, realized that indeed there’s “roles” and “object types” with a 1:1 mapping that is identity for some of them, and now understand the distinction.
That’s why I filed this issue: The inventory contains “object types”, not “roles”. I think the simplest would be that the Python handler emits object types directly, which directly end up in the inventory.
It’s of course an option to just misname the concept here and talk about “roles” while we’re consistently handling “object types”, but to spare others the confusion, the correct terminology should be used here.
pawamoy commentedon Sep 4, 2026
Yes, I think I finally understand it 🙂 I think sphobjinv's docs should be updated to use "object type" too, since that's my go-to reference. Thanks for bringing this to my attention!
I'd love to rename the field from "role" to "object type" in mkdocstrings and handlers, but I'm afraid this would be a breaking change. I'll try to see if I can get some stats on how many projects would be affected. There might be a deprecation path too, to keep backward compatibility.
flying-sheep commentedon Sep 4, 2026
you could rename it and accept the old
roleargument with aDeprecationWarning. That way it still works, but it’s clear that it’s not the right thing to do.pawamoy commentedon Sep 4, 2026
OK even though I can't find any real usage of
InventoryItemin the wild, I'll take the safe route and avoid any breaking change. The thing isroleis currently a positional-or-keyword parameter. That makes it impossible to deprecate with backward compatibility without a very ugly new signature, if at all possible. Since mkdocstrings is in maintenance mode, lets keep it that way. I don't think too many people read mkdocstrings' inventory code to learn about Sphinx's objects.inv anyway. I'll still fix the object types passed from the Python handler.