objects.inv - available?

[mmacy]

After digging around a bit for the object inventory file (objects.inv) for httpx, I'm throwing in the towel and asking outright:

❓ Q: Is the objects.inv for httpx hosted anywhere that dependent documentation projects can reference?

I didn't see it in the gh-pages branch, and I'm aware of the open discussion in #1220, but I haven't yet been able to unearth the inventory if indeed you are generating and propping it somewhere.

If it's around and I'm just missing it somehow, would love to find out where. Thanks!

[lovelydinosaur]

We don't generate an objects.inv file, no.
There might be some useful/interesting things to talk about here, tho I'd like to get a better idea of context first.
Are you able to show an example of what you're aiming for here?

[lovelydinosaur]

from the looks of it, the project doesn't appear to be maintained anymore, with the last commit being 2 years old, so I'm not sure if it's even worth opening this issue there.

It's not maintained. Needs an issue/PR prompting it to move into properly deprecated and pointing at more active alternatives.

Considering the state ot mkautodocs, would you at all be willing to consider switching to mkdocstrings-python?

Yep.

I can't currently achieve that because of the missing objects.inv.

Im somewhat allergic to objects.inv because hyperlinking on the web shouldn't need solutions that are language specific.

[Ravencentric]

Im somewhat allergic to objects.inv because hyperlinking on the web shouldn't need solutions that are language specific.

It's a defacto standard in the python community and unfortunately there's no alternative option here other than just not having httpx references hyperlinked in auto generated API docs

[ItsDrike]

Im somewhat allergic to objects.inv because hyperlinking on the web shouldn't need solutions that are language specific.

Why is that? The alternative solution would have to be hard-coding docs urls for every object manually, which would be super annoying. (Although I do think that it'd be nice if mkdocstrings provided an option to at least do that). I'm not hugely familiar with the format of objects.inv, so it may be fair to say that it sucks, but not having it, at least at current time when there really isn't any other alternative (not even hard-coding) is definitely worse.

What's especially annoying is that the auto-generated docs often only show the type annotation, which is just Client, and it may be hard to infer what kind of client that is, I could enable showing fully qualified names, but that would do so on every type for that function, which isn't ideal, so I have to explain what that parameter is in the docstring, with proper reference there, that wouldn't be necessary.

[lovelydinosaur]

I'm voicing a design sensibility here, rather than a "let's not do that".

In some slightly alternate imagined space we're interlinking across projects using permalinks & redirects...

• https://www.python-httpx.org/glossary/BasicAuth
• https://www.python-httpx.org/glossary/DigestAuth
• https://www.python-httpx.org/glossary/NetRCAuth

Anyways, yep sure let's have an objects.inv (it doesn't suck, it's a useful tool & it's what we've got).

And yes, a switch across to mkdocstrings would make sense.

[samuelcolvin]

Chiming in here, a objects.inv file for HTTPX would be great please @tomchristie.

[lovelydinosaur]

Alrighty... @samuelcolvin helpfully nudged this again via email.

Please can you add objects.inv to HTTPX so we can link to it from pydantic-ai

That sounds interesting. 🧐

It's much easier for me to get a grip on this if there's a real-life example that we can talk about wrt. tooling, rather than just talking abstract. Would anyone be able to point to a couple of examples of projects with publicly accessible objects.inv URLs and show how that helps cross-referencing tools.

(I realise that this might seem onerous/unneccessary to folks fully invested in sphinx-land, tho we're not using that docs tooling over in this part of the ecosystem and I find the file format amusingly inscrutable. Also somewhat musing on @Ravencentric's point.)

[mmacy]

It's not just sphinx-land. In fact, since your docs are already in mkdocs-material, you could use mkdocstrings for your API ref and it'll build and include the objects.inv in your built doc site for you automatically.

[samuelcolvin]

Thanks @tomchristie. To be clear, we reference httpx types lots in the pydantic-ai documentation, e.g. here, I'd love to just change that line to

You can customize the `AnthropicProvider` with a custom [`AsyncClient`][httpx.AsyncClient]:

So it links to httpx's API documentation, this works with lots of other dependencies, since our API docs are generated by mkdocsstrings:

          import:
            - url: https://logfire.pydantic.dev/docs/objects.inv
            - url: https://docs.python.org/3/objects.inv
            - url: https://docs.pydantic.dev/latest/objects.inv
            - url: https://dirty-equals.helpmanual.io/latest/objects.inv
            - url: https://fastapi.tiangolo.com/objects.inv
            - url: https://typing-extensions.readthedocs.io/en/latest/objects.inv
            - url: https://rich.readthedocs.io/en/stable/objects.inv
            # waiting for https://github.com/encode/httpx/discussions/3091#discussioncomment-11205594

See here.

TL;DR - if you generate the API documentation with mkdocstrings you'll get the objects.inv file generated automatically.