Undocumented behaviour / incorrect type hints

[mheguy]

There is no documentation indicating that ngrok.forward can return an _asyncio.Task.

Running this code:

import asyncio
import ngrok
NGROK_TOKEN = ""

def sync():
    listener = ngrok.forward(80, authtoken=NGROK_TOKEN)
    print("sync")
    print(type(listener))

async def async_():
    listener = ngrok.forward(80, authtoken=NGROK_TOKEN)
    print("async")
    print(type(listener))

    print("async calling sync..")
    sync()

sync()
asyncio.run(async_())

Gives this output:

sync
<class 'builtins.Listener'>
async
<class '_asyncio.Task'>
async calling sync..
sync
<class '_asyncio.Task'>

After a bit more exploring, all methods belonging directly to the ngrok module have the same behaviour.

Either:

• the type hints should be updated to reflect the true return types
• explicit async methods should be implemented (ex. forward_async)

The second option is a better solution. As my example hints at: the sync function calls forward and gets back an awaitable. This is problematic because the sync method cannot await the listener. This means that it has to be refactored into an async function. It also means that the caller of sync either needs to be async itself, or run the function explicitly with asyncio.run() (or similar).

Edit: On reflecting on this, it might be a bug in how the code is detecting whether it should return an awaitable or not. That isn't a question I can speak to intelligently.

[kbolashev]

+1 to this issue This is actually an issue for writing libraries that are integrating with ngrok. We hit this issue in our libraries, if you have a function that does something like:

def do_things_with_forwarding():
    listener = ngrok.forward(80, authtoken=NGROK_TOKEN)
    ... # do some code

The function is forced to be a de-facto async function, because you can't control the environment in which it's being run. You can even just call it an a Google Colab and you will get back a Task, despite there being no async code as far as the user is concerned, since Jupyter ends up running an async loop: https://colab.research.google.com/drive/1BiyzZKqMM9LFlNdj7Oq1eis_hBiCmyXb?usp=sharing

It would be nice to at least have a function that is guaranteed to return a synchronous client, no matter if there is a coroutine in the callstack or not.