Making run method non-blocking

[lukaskremla]

I am working with Microdot on an ESP32 S2. I am building a web server for a control unit, which will be running multiple tasks asynchronously. In order to make this possible I have to run the web server code through an async start coroutine at the end of which I call the run method. Then in the main file I have to run start with asyncio.create_task, which is something PyCharm is apparently not too happy about because the coroutine is not awaited.

Now this is in no way a big deal preventing me from doing something, it works like this and I can use the # noinspection PyAsyncCall to suppress the warning and I can hide the create_task in another method to keep the main file clean.

But I want to ask. Is there any specific reason for letting the run method be blocking by using asyncio.run instead of asyncio.create_task in microdot.py?

I understand that having the code be blocking makes things simpler, possibly reducing the possibility of someone miss-managing the asynchronous aspect, and it also keeps in line with the behavior of other web frameworks like Flask. But given Microdot is tailored to to be lightweight and MicroPython friendly, perhaps adding an option to run the code in a non-blocking way could be beneficial?

Maybe adding a parameter to the run method or defining another method, something like run_non_blocking. Which would keep the current blocking run behavior as the default or preferred way to run the server, but it would also make it a bit easier to integrate Microdot into big asynchronous applications.

It's just an idea, something that makes sense for me in my use cases, wanted to ask your opinion on adding something like this to Microdot.

[miguelgrinberg]

Without seeing the code that you wrote I don't fully understand what you are doing. The run() method is a blocking function, it cannot be used inside a coroutine. But there is a coroutine version of run that you can use called start_server.

Examples:

Using await:

            async def main():
                await app.start_server()  # blocks

            asyncio.run(main())

Using create_task():

            async def main():
                task = asyncio.create_task(app.start_server())  # doesn't block
                # do other stuff here

            asyncio.run(main())

See the documentation for the arguments you can pass.

[lukaskremla]

webserver.py

server = Microdot()

# Route definitions...

async def start():
    server.run

main.py

async def main():
    # Run my method for setting up the wifi
    
    # noinspection PyAsyncCall (PyCharm shows a warning about create_task not being awaited)
    asyncio.create_task(webserver.start())
    
    # Other code that needs to run alongside the server
    
asyncio.run(main())

Now what I was proposing is to make the server.run method accept a parameter like server.run(non_blocking=True). Which microdot.py could handle like this for example:

    def run(self, host='0.0.0.0', port=5000, debug=False, ssl=None, non_blocking=False):
        if non_blocking:
            # noinspection PyAsyncCall
            asyncio.create_task(self.start_server(host=host, port=port, debug=debug,
                                          ssl=ssl))  # pragma: no cover
        else:
            asyncio.run(self.start_server(host=host, port=port, debug=debug,
                                          ssl=ssl))  # pragma: no cover

This would allow me to change my code like this:

webserver.py

server = Microdot()

# Route definitions...

def start():
    server.run(non_blocking=True)

main.py

async def main():
    # Run my method for setting up the wifi
    
    webserver.start()
    
    # Other code that needs to run alongside the server
    
asyncio.run(main())

Now as I was saying this is not biggie, if I really want to make the code in main.py as clean as I shown above I could do something like this workaround:

webserver.py

server = Microdot()

# Route definitions...

async def run_non_blocking():
    server.run
    
def start()
    # noinspection PyAsyncCall
    asyncio.create_task(run_non_blocking()):

And my main.py could look the same as it would with the proposed Microdot change.

I could also do this, which would be be better:

webserver.py

server = Microdot()

# Route definitions...

def start()
    # noinspection PyAsyncCall
    asyncio.create_task(server.start_server()):

This would also make my main.py look the same as with the proposed Microdot change.

The point is, I feel that adding a parameter to the run method would make all of this a bit cleaner and easier to read. It is less "workaroundy" than the last two options I proposed and it is easier to read than the first method of how I have to do it right now. To me it feels more self descriptive and it also moves the IDE warning away from my code, which could be preferred by other Microdot users, beginners would also have one less warning to worry about.

Technically I could also do task = asyncio.create_task(webserver.start()) in the original code. This would hide the warning of the task not being awaited, but now I have an unused variable, which adds a soft warning.

Adding a parameter like this would not break or change anything for the existing Microdot applications either.

[miguelgrinberg]

I'm not sure you realize this, but PyCharm's static analyzer is wrong. It is perfectly fine to call create_task() and not await the result. This is how you create a task that runs in the background. If you want to try something that might work, assign the result of create_task to a variable, say task, then add await task at the end of your function.

In any case, as I said above, you cannot use run() inside a coroutine. I'm not sure what you expect this to do, but it is not going to work:

async def start():
    server.run

What you are proposing is really not at all different to what I suggested. Here is your suggestion again:

    def run(self, host='0.0.0.0', port=5000, debug=False, ssl=None, non_blocking=False):
        if non_blocking:
            # noinspection PyAsyncCall
            asyncio.create_task(self.start_server(host=host, port=port, debug=debug,
                                          ssl=ssl))  # pragma: no cover
        else:
            asyncio.run(self.start_server(host=host, port=port, debug=debug,
                                          ssl=ssl))  # pragma: no cover

The only difference that I can see is that you are suggesting to move the code that PyCharm does not like inside this package instead of being in your own application.

Calling create_task in a function that is not asynchronous is not something I would do as it is not what most people would expect given that create_task is used in an asynchronous context. Mixing asynchronous and synchronous functions is also not a practice I would recommend, and for that reason I provide run for sync use and start_server for async use. Explicit is better than implicit, in my opinion.

[lukaskremla]

I do realize that PyCharm is wrong and that is why I am suppressing the warning without worrying about it.

As far as running asynchronous functions from a synchronous context, let me try to explain why I think that can be a valid approach.

I am working in a team, there is several of us writing code for the application we are developing. Each one of us is responsible for a different part of the code. We write everything in classes and we have a conventions for methods of these classes. Pretty much everything where we start some process has a .start method.

The person putting things together in the controller of the app does not need to know what the web server I make does in the background, he does not need to understand it. For him it is enough to know that .start will start the web server. It is up to me to handle the logic of how to start the web server. It shields this person writing the code from making a pointless mistake this way. I think that something like webserver.start is more concise and easy to read than asyncio.create_task(webserver.start) even if it means that the webserver method .start starts an asynchronous task in a synchronous method.

And given Microdot is meant to be a lightweight framework and (correct me if I got this impression wrong) is more intended for MicroPython, it doesn't make much sense to me to make the run method blocking.

Microdot is an amazing framework, it is the best webserver for MicroPython I have been able to find, but finding out that the main way that is presented in the documentation to run the server is blocking was very surprising.

I understand your point about explicit being better than implicit, but in this case coming to Microdot with the expectation that it is "an asynchronous framework" that can run on micro controllers after reading the documentation, I would assume that it is fully asynchronous from the get go. That I just run the server and it works asynchronously right away allowing me to get the most out of the limited processing power I have in the micro controller.

Maybe it is just a question of taste and preference. But reading the documentation and seeing Microdot is an "asynchronous framework..." and then seeing "The run method starts... This method blocks while it waits for connections from clients." in the next paragraph was odd.

Finally, please don't take what I say in a negative way. I do not mean to insult your work or waste your time arguing about something in your open source work not being to my taste. As I have said already, Microdot is an amazing feature rich web framework and I am truly grateful to you for making it an open source framework that all of us can use. I have been yet to find a MicroPython open source documentation for a framework that would be as well written as yours is.

My reason for starting this discussion was that I truly believe it would be of benefit to the users if they would be able to run Microdot asynchronously by default, or at least making it a bit easier to do so by making the .run method accept an argument to make it run the server asynchronously.

I understand Microdot may have been written at a time when asyncio wasn't available on MicroPython and that the synchronous method might be for compatibility or consistence. But I still believe that adding a parameter to the run method to allow Microdot to be ran asynchronously directly and be non-blocking would make it easier to make the most of asyncio while using Microdot.

All I ask is for you to consider my suggestion. Is it really the better way to make the default server starting method of this server be blocking if Microdot is pretty much the only reasonable MicroPython web server option?

[miguelgrinberg]

First of all I do not understand why you think this behavior needs to be in run. If you want to have a synchronous start function, then you can do this in your webserver.py:

server = Microdot()

# Route definitions...

def start():
    asyncio.create_task(server.start_server())

Isn't this exactly what you want?

If you and your team like to do things this way, then I'm not going to get in the way. But if you want my opinion, this isn't great.

The person putting things together in the controller of the app does not need to know what the web server I make does in the background, he does not need to understand it.

You are correct. Your teammates do not need to understand what your webserver does. They do, however, need to know it is an asynchronous web server, because your choice of using an asynchronous pattern for the server forces them to also implement their modules in an asynchronous way. If you don't understand why this is the case then you are going to find out sooner than later. As I said above, you are mixing synchronous and asynchronous functions, and that is not a good pattern because your entire application needs to be asynchronous for things to work.

I think that something like webserver.start is more concise and easy to read than asyncio.create_task(webserver.start) even if it means that the webserver method .start starts an asynchronous task in a synchronous method.

Use the code above in this reply to get this solution implemented without any changes to Microdot.

it doesn't make much sense to me to make the run method blocking.

Yes. The run method is intended to be used in applications that only need a web server. It is not appropriate to your use case. You should use start_server as demonstrated above.

I would assume that it is fully asynchronous from the get go.

And it is. I'm not really sure why you think run makes the framework not fully asynchronous. All asynchronous applications start from a synchronous function. The asyncio.run function is synchronous and blocking too.

but finding out that the main way that is presented in the documentation to run the server is blocking was very surprising.

On this I accept your criticism. I will add an example of how to start the server with start_server as well because it is harder to find this method without being featured in an example.

I understand Microdot may have been written at a time when asyncio wasn't available on MicroPython and that the synchronous method might be for compatibility or consistence. But I still believe that adding a parameter to the run method to allow Microdot to be ran asynchronously directly and be non-blocking would make it easier to make the most of asyncio while using Microdot.

I'm really failing to understand why this has to be done in run. The standard way to start a server without blocking in asyncio is with an asynchronous method called start_server. Here is an example from CPython does it: https://docs.python.org/3/library/asyncio-stream.html#asyncio.start_server. Here is documentation from MicroPython on this topic: https://docs.micropython.org/en/latest/library/asyncio.html#asyncio.start_server.

If you prefer a sync function, then wrap the standard start_server in your own function as I show above in this comment. That gives you exactly what you are asking for, and leaves this framework working in the way most Python developers are used to.

Is it really the better way to make the default server starting method of this server be blocking if Microdot is pretty much the only reasonable MicroPython web server option?

There's two ways to start the server, depending on your needs. Neither one is default, you are supposed to use the one that matches your needs better. I'll add an example of start_server so that you don't feel it is not supposed to be used.

[miguelgrinberg]

As promised above: https://microdot.readthedocs.io/en/latest/intro.html#a-simple-microdot-web-server

[lukaskremla]

Thank you for your patience with me. I'm a student working part time. I'm working on the web server component of a new control unit and I'm trying to understand what I work with as best as I can.

If the run method is working in a way that is, or could be deemed, a convention amongst Python developers. Then I admit I was at fault thinking it needs to be modified.

Thank you for adding the start_server example to Microdot documentation. Having the options for starting the web server as clearly documented as this leaves no space for my previous confusion about a blocking start method. I have no more remarks to this.

To address your suggestion about not running async methods from synchronous methods like I currently do. Could I please ask about why running the asynchronous start_server method in this way is not ideal?

For context, given the ESP32 S2 we're working with being single-threaded we're all aware that to achieve what our app needs to achieve, we must use asyncio.

Our main function is asynchronous and runs in an infinite loop in which we control peripherals, check for alarm conditions etc. We're running multiple asynchronous processes, like the web server or alarm state machine alongside this. We're all aware that things which could block have to be asynchronous, including the web server.

In this context, I'm under the impression that having a synchronous method such as webserver.start create a task for the web server is acceptable given the whole application is written asynchronously. Am I mistaken?

[miguelgrinberg]

As I said before, if you are happy using start functions, then do so. It is not a good pattern because of the separation of concerns principle. The web server doesn't need to know how tasks are scheduled, all it needs to care about is create its own background task. The top-most layer of your application should get all the tasks and decide what to do with them, and which need to run in the background and which should be awaited in the foreground.

In case you want to see another implementation, the Uvicorn web server (most used async web server in CPython) uses a similar pattern to Microdot, where server.run() is blocking and server.serve() is a coroutine. See for yourself: https://www.uvicorn.org/#config-and-server-instances.