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

[flying-sheep]

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

[pawamoy]

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

[pawamoy]

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

[pawamoy]

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

[bskinn]

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

[bskinn]

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.

[pawamoy]

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

[flying-sheep]

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.

[flying-sheep]

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

[pawamoy]

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.

[pawamoy]

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

[pawamoy]

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