Dynamic Docstrings in Sync Client

asonnenschein commented 2 days ago

This MR enables reference documentation for new synchronous client objects implemented in https://github.com/planetlabs/planet-client-python/pull/1049, and uses a decorator to dynamically populate sync client docstrings from their async client counterparts.

stephenhillier commented 2 days ago

Is there a way to get these to display in IDEs (I can't get the decorated ones to display in VSCode or Neovim)?

asonnenschein commented 2 days ago

Is there a way to get these to display in IDEs (I can't get the decorated ones to display in VSCode or Neovim)?

Not that I am aware of. The way I have the docstrings set up in this PR will display them via Python's help() method, and they will build with the docs (not sure why I cannot reply to your comment in a thread @stephenhillier, which is why I am making a separate response comment).

ischneider commented 17 hours ago

I messed around with approaches for this and my findings are that the language servers (used for display in IDE) do not execute code (which makes sense!) so the doc annotation or my metaclass approach don't work.

What does work, and what I'm now advocating for is:

rather than wrap a client, inherit directly from it
for each async function, (re-)declare a sync version w/ the appropriate typing hint
use the super class function (async) and use the call_sync to wait for the coroutine
add a AsyncGenerator -> Generator converter to further reduce boiler plate
migrate tests to use an approach where we build a payload and execute in both a sync and async context to reduce boiler plate and ensure all functions are wrapped

Will iterate on this for the remainder of the day and see what I can do for one of the clients as an example...

planetlabs / planet-client-python

Dynamic Docstrings in Sync Client #1077