Repository navigation
bug: “type”, not “typealias“ & you’re confusing “role” and “objtype” #339
Description
Activity
Thanks for the report @flying-sheep. Can you link to Sphinx's documentation about this? I find their docs extremely poor on the subject.
From what I was able to gather, here's the complete list of roles we can use in objects.inv:
- mod
- func
- deco
- data
- const
- class
- meth
- attr
- type
- exc
- obj
Here's what we're writing from mkdocstrings-python:
- module (wrong, should be mod)
- function (wrong, should func/deco/meth)
- data (right)
- class (right)
- attr (right)
- typealias (wrong, should be type)
- param (no equivalent)
- typeparam (no equivalent)
@bskinn you might find this interesting. Could be nice if sphobjinv would explicitly list those roles, at least for thepydomain 🙂
@flying-sheep as you can see Sphinx doesn't even allow registering entries for parameters (or type parameters) so I had to take some liberties there... 😅
What we never write from mkdocstrings-python:
- const: hard to distinguish from data/attr when iterating on extracted API data
- exc: could be relatively easy to use it on classes that inherit from
ExceptionorBaseException - obj: maybe we should use that one instead of the unsupported "param" and "typeparam"...
Well, no, looks like I got this backwards. So we're mostly good except for
attrinstead ofattribute?So, valid object types (or "roles" as defined by sphobjinv):
object type python handler function function ✅️ data data ✅️ class class ✅️ exception class ❌️ (can easily fix) method function ❌️ (can easily fix) classmethod function ❌️ (can easily fix, not sure it's worth) staticmethod function ❌️ (can easily fix, not sure it's worth) attribute attr ❌️ (can easily fix) property attr ❌️ (can easily fix) type typealias ❌️ (can easily fix) module module ✅️ / param ❌️ (might use obj for correctness) / typeparam ❌️ (might use obj for correctness) WDYT @flying-sheep 🙂?
Reacted by Philipp A.@pawamoy There has been some discussion along these lines in bskinn/sphobjinv#234, though with a different focus. OP there already did some forensics that might be helpful; e.g., at bskinn/sphobjinv#234 (comment)
The catch with surfacing these in
sphobjinvruntime use is that, as best I recall, it would require including Sphinx as a full dependency, which I would prefer not to do (at least, not in the core dependencies) given its size.It might work to place this sort of functionality behind an extra/optional-dependency, though ... that way, an end-user would have the choice to install a heavier dependency set if they want the functionality.
The catch with surfacing these in sphobjinv runtime use is that, as best I recall, it would require including Sphinx as a full dependency, which I would prefer not to do (at least, not in the core dependencies) given its size.
Understandable. As mentioned in https://github.com/orgs/sphinx-doc/discussions/12204 though, the object types haven't changed for a long time, so maybe a static table (no need to depend on Sphinx) in sphobjinv's docs with a little warning about it possibly going stale could still be valuable, to make it clear what object types are valid in the inventory (no need to document roles/directives equivalents).
New object types get added at the frequency that Python adds them, so very slowly. I think it’s very feasible to hardcode them all (with a comment that the source of truth is intersphinx, and sphobjinv is a useful 3rd party resource dealing with the same problem)
classmethod, staticmethod (can easily fix, not sure it's worth)
Hmm, I don’t think I’ve ever seen these. Worth double checking if these get emitted.
here are the stats from my projects (inflated by duplicate inventories). Notable:
parameteris emitted from docstring parsing, not the AST, so maybe out of scope for a bugfix, but definitely a worthy featuretypealiascomes from you of course, this is what this issue is about
count type 144260 py:method 72370 py:function 44346 py:attribute 35060 py:data 32440 py:class 15091 py:parameter 10358 py:property 8093 py:module 5085 py:exception 2680 py:attr 539 py:type 20 py:typealias Yes, good idea, I started vibe-coding a script yesterday to analyze the top N Python packages to see some stats. Here they are for the top 500 packages (for those we could find an inventory for).
Object types by inventory count (number of projects, not occurrences):
py:attr [INVALID]: 14 py:attribute: 140 py:class: 194 py:classmethod: 4 (datadog, python-docx, python-pptx, requests-toolbelt) py:data: 97 py:enum [INVALID]: 1 (pyzmq) py:exception: 95 py:function: 185 py:interface [INVALID]: 1 (zope-interface) py:method: 174 py:module: 170 py:param [INVALID]: 1 (python-multipart) py:parameter [INVALID]: 5 py:property: 96 py:staticmethod: 1 (datadog) py:type: 5Invalid object types by builder:
astro (5): (none) mkdocs (12): attr [INVALID] (7), param [INVALID] (1), parameter [INVALID] (1) sphinx (198): enum [INVALID] (1), interface [INVALID] (1), parameter [INVALID] (4) zensical (8): attr [INVALID] (7)Valid object types by total occurrence count:
py:attribute: 55732 py:class: 41846 py:classmethod: 76 py:data: 3883 py:exception: 1220 py:function: 19530 py:method: 135325 py:module: 4974 py:obj: 0 py:property: 5526 py:staticmethod: 1 py:type: 82Invalid object types by total occurrence count:
py:attr [INVALID]: 5266 py:enum [INVALID]: 26 py:interface [INVALID]: 22 py:param [INVALID]: 16 py:parameter [INVALID]: 2958Looks like some Sphinx projects are taking some liberties with their objects inventory too.
Thinking about it, "object type" is not exactly the most generic field name. Works for Python, but might not work for many other domains that aren't about programming languages. Even for Python, if Sphinx ever adds support for parameters, "object" doesn't fit a parameter. Even "symbol" wouldn't fit 🤔 So maybe just "type"?
Looks like some Sphinx projects are taking some liberties with their objects inventory too.
Yeah, some extensions:
sphinx_toolbox.more_autodocinventspy:enumandpy:protocolsphinx-immaterialandsphinx-paramlinksinventpy:parameter
"object" doesn't fit a parameter.
Sphinx already has documents and sections in the inventory, and all of these have “objtypes”: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/intersphinx/_resolve.py#L144
Yeah, maybe lets not argue about their naming choices and just stay close to their implementation. It's an "object" inventory after all.
Opened a discussion there btw: https://github.com/orgs/sphinx-doc/discussions/14667.
Reacted by Philipp A.- added a commit that references this issue
on Sep 22, 2026 I merged #340, mkdocstrings-python will now correctly use
attributeinstead ofattr, andtypeinstead oftypealias. We still use non-builtin types such asparameterandtypeparameter, because to me it looks like this is a valid use-case: the domain object types are public API in Sphinx.Reacted by Philipp A.
Description of the bug
In these two spots, you should pass
role="type", “typealias” is neither a role that exists nor a valid objtypepython/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html.jinja
Line 38 in 8125b0d
python/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html.jinja
Line 86 in 8125b0d
There’s also a bigger bug in
mkdocstrings(mkdocstrings/mkdocstrings#826), and probably zensical:role!=objtype:https://github.com/mkdocstrings/mkdocstrings/blob/9a11dcb8e9b39ff6e1a22abdd362350de4e68e9f/src/mkdocstrings/_internal/inventory.py#L64
e.g. the role
attrrefers to objtype “attribute”,To Reproduce
document this:
the objects.inv you create will contain broken entries
Full traceback
N/A
Expected behavior
typestatements createtypeentries inobject.inv(nottypealias)attributeentries inobjects.inv(notattr, that’s the role used to refer to them)Environment information
v2.0.8
Additional context
N/A