Repository navigation
Put qualname in the objects.inv #4826
Description
Due to type annotations, more and more tools retrieve qualified object names from live objects and expect them to serve as object ID.
However, code like the following fails when the object is reexported, when its canonical location doesn’t fit its qualified name:
from scipy.sparse import spmatrix
qualname = f'{spmatrix.__module__}.{spmatrix.__qualname__}' # 'scipy.sparse.base.spmatrix'
from sphinx.ext.intersphinx import inspect_main
sys.stdout = StringIO()
inspect_main(['https://docs.scipy.org/doc/scipy/reference/objects.inv'])
assert qualname in sys.stdout.getvalue() # nope, only 'scipy.sparse.spmatrix'a fix could either go into the inventory dumping or the python domain (if adding objects goes through a domain API and isn’t just doing env.domains['py'].objects.append(…))
Activity
tk0miya commentedon Apr 10, 2018
Please let me know your goal. The inventory file of intersphinx is generated for cross reference.
Did you mean that you want to reference
spmatrixby qualname (ex.:mod:scipy.sparse.base.spmatrix)?flying-sheep commentedon Apr 19, 2018
Yes, since there is no automatic way of knowing what the “canonical” place for an object is.
flying-sheep commentedon Jul 23, 2018
@tk0miya do you need more information? I’d do a PR, but I don’t know enough about the inner workings here and how to start best.
tk0miya commentedon Aug 26, 2018
Sorry for late response.
I feel a bit strange for your proposal. I think the qualified names are not undocumented. That means it is private members. I don't think it is good way to expose qualified names automatically.
flying-sheep commentedon Aug 27, 2018
You’re right, but I didn’t propose to just add the qualname to the objects.inv. I do want a solution for the case where I know the qualname but not the canonical documentation location.
Each documented object has 1–∞ aliases, one of which is the the canonical documented location (in objects.inv) and one of which is the canonical qualified name (
thing.__module__ + '.' + thing.__(qual)name__). Those to names might be (but aren’t always) the same.I don’t think it’s necessary to support all alias names, just the qualified name as well as the documented one. I can imagine two solutions, but maybe there are more:
:class:`actual.qualified.Name`renders as<a class="py-class" href="...">canonical.Name</a>The latter would be much more practical, because people won’t have to change autodoc templates and so on, also it would be faster and work without having access to and implementing other modules. The former would work without rebuilding every other project’s documentation.
tk0miya commentedon Sep 1, 2018
Most important thing is whether the author of the document want to expose the qualname to readers. I can agree with adding an option for it if they want.
But, as a developer, I feel qualname is a kind of private interface. So I don't want that if I was author.
flying-sheep commentedon Sep 2, 2018
i think you didn’t understand me. the point is that sometimes someone just has the qualname and needs to get a link out of the objects.inv using it.
nobody will ever see the qualname, it’s just for finding a class or function in the docs: using the qualname, you shoud be able to get a link to the documented location. the link should look like if you used the documented location.
this is about an implementation detail and enhanced functionality, not design, so an option would be counter productive, annoying, and have no benefit.
flying-sheep commentedon Nov 8, 2018
so what do you think is the best approach (from my second-to-last comment)? 1 or 2?
tk0miya commentedon Nov 11, 2018
If we'll expose qualname into objects.inv, users can refer objects using qualified name like
:py:class:`scipy.sparse.base.spmatrix`as you said. It means the qualname has appeared in the document. But I think qualname is not promised interface. So it might be fragile. But documents usually alive longer than source code.I'm afraid of that the exposure causes the document network fragile. I can understand it is useful for IDE or tooling, but...
flying-sheep commentedon Nov 11, 2018
Actually this is not a problem. The qualname will only appear
the links that appear in the HTML will point to the documented name. e.g.
.. autodoc:: some_function, wheredef some_function(df: pd.DataFrame): ...:class:`pandas.core.frame.DataFrame`.objects.invcontains an alias linepandas.core.frame.DataFrame → pandas.DataFramegoerz commentedon Dec 18, 2018
A big +1 from me. Without this, the Sphinx documentation for projects that uses type annotations are broken, with no workaround. In fact, this is one reason why I think people should stay away from type annotations for the time being.
tk0miya commentedon Dec 23, 2018
Sorry for late.
@flying-sheep Finally I can understand your goal. Thank you for explanation. I agree to add qualnames to inventory as alias. I think they should be also added into internal indices data; which is origin of inventory file. Because other extension would also be able to refer it by qualname.
flying-sheep commentedon Dec 25, 2018
Great to hear! Merry Christmas!
flying-sheep commentedon Jan 9, 2020
It’s one year later. Merry Christmas and a happy new year again! 😉
Actually scanpydoc.elegant_typehints has a (manual) workaround (check the docs for
qualname_overrides) behind the link.eric-wieser commentedon Mar 27, 2020
Related to #5589 I think
tk0miya commentedon Mar 27, 2021
Now I merged #9026 that generates
:canonical:option for the imported classes. It allows to refer the python objects by its canonical name. It resolves the problempandas.DataFrameandpandas.core.frame.DataFrame!flying-sheep commentedon Mar 27, 2021
Great, thank you so much! This will help in many many cases.
This PR is only a partial solution for autodoc though, as it only touches the class documenter. What about
api.Classhas:canonical: orig.Classset, will referring toorig.Class.methodwork the same as referring toapi.Class.method?Let’s fix up #9039