Skip to content

bug: “type”, not “typealias“ & you’re confusing “role” and “objtype” #339

Closed
Closed
bug: “type”, not “typealias“ & you’re confusing “role” and “objtype”#339
Assignees
pawamoy
Labels
bugSomething isn't working

Description

@flying-sheep
flying-sheep
opened on Sep 3, 2026

Description of the bug

In these two spots, you should pass role="type", “typealias” is neither a role that exists nor a valid objtype

python/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html.jinja

Line 38 in 8125b0d

role="typealias",

python/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html.jinja

Line 86 in 8125b0d

role="typealias",

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 attr refers to objtype “attribute”,

To Reproduce

document this:

type Foo = int

the objects.inv you create will contain broken entries

Full traceback

N/A

Expected behavior

  • type statements create type entries in object.inv (not typealias)
  • attributes create attribute entries in objects.inv (not attr, that’s the role used to refer to them)

Environment information

v2.0.8

Additional context

N/A

Activity

  1. flying-sheep
    assigned
    pawamoy
    on Sep 3, 2026
  2. flying-sheep
    added
    unconfirmedThis bug was not reproduced yet
    on Sep 3, 2026

  3. pawamoy commented on Sep 3, 2026

    @pawamoy
    pawamoy
    on Sep 3, 2026
    Member

    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 the py domain 🙂

    @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 Exception or BaseException
    • obj: maybe we should use that one instead of the unsupported "param" and "typeparam"...

  4. pawamoy commented on Sep 3, 2026

    @pawamoy
    pawamoy
    on Sep 3, 2026
    Member

    Well, no, looks like I got this backwards. So we're mostly good except for attr instead of attribute?

  5. pawamoy commented on Sep 3, 2026

    @pawamoy
    pawamoy
    on Sep 3, 2026
    Member

    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 🙂?

  6. bskinn commented on Sep 3, 2026

    @bskinn
    bskinn
    on Sep 3, 2026

    @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)

  7. bskinn commented on Sep 3, 2026

    @bskinn
    bskinn
    on Sep 3, 2026

    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.

    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.

  8. pawamoy commented on Sep 3, 2026

    @pawamoy
    pawamoy
    on Sep 3, 2026
    Member

    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).

  9. flying-sheep commented on Sep 4, 2026

    @flying-sheep
    flying-sheep
    on Sep 4, 2026
    Author

    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.

  10. flying-sheep commented on Sep 4, 2026

    @flying-sheep
    flying-sheep
    on Sep 4, 2026
    Author

    here are the stats from my projects (inflated by duplicate inventories). Notable:

    • parameter is emitted from docstring parsing, not the AST, so maybe out of scope for a bugfix, but definitely a worthy feature
    • typealias comes 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

  11. pawamoy commented on Sep 4, 2026

    @pawamoy
    pawamoy
    on Sep 4, 2026
    Member

    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: 5

    Invalid 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: 82

    Invalid 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]: 2958

    Looks like some Sphinx projects are taking some liberties with their objects inventory too.

  12. pawamoy commented on Sep 4, 2026

    @pawamoy
    pawamoy
    on Sep 4, 2026
    Member

    @bskinn what do you think of renaming the "role" field to "object type" in sphobjinv's docs, in addition to listing the valid object types (without a runtime dependency on Sphinx)? I can send a PR if you want 🙂

  13. pawamoy commented on Sep 4, 2026

    @pawamoy
    pawamoy
    on Sep 4, 2026
    Member

    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"?

  14. pawamoy
    added
    bugSomething isn't working
    and removed
    unconfirmedThis bug was not reproduced yet
    on Sep 4, 2026

  15. flying-sheep commented on Sep 4, 2026

    @flying-sheep
    flying-sheep
    on Sep 4, 2026
    Author

    Looks like some Sphinx projects are taking some liberties with their objects inventory too.

    Yeah, some extensions:

    • sphinx_toolbox.more_autodoc invents py:enum and py:protocol
    • sphinx-immaterial and sphinx-paramlinks invent py: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

  16. pawamoy commented on Sep 4, 2026

    @pawamoy
    pawamoy
    on Sep 4, 2026
    Member

    Yeah, maybe lets not argue about their naming choices and just stay close to their implementation. It's an "object" inventory after all.

  17. pawamoy commented on Sep 4, 2026

    @pawamoy
    pawamoy
    on Sep 4, 2026
    Member

    Opened a discussion there btw: https://github.com/orgs/sphinx-doc/discussions/14667.

  18. pawamoy
    added a commit that references this issue on Sep 22, 2026

    fix: Improve inventory object types (incorrectly called roles in mkdo…

    d754326

  19. pawamoy commented on Sep 22, 2026

    @pawamoy
    pawamoy
    on Sep 22, 2026
    Member

    I merged #340, mkdocstrings-python will now correctly use attribute instead of attr, and type instead of typealias. We still use non-builtin types such as parameter and typeparameter, because to me it looks like this is a valid use-case: the domain object types are public API in Sphinx.

  20. pawamoy
    closed this as completedon Sep 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions