The asyncio package was introduced in the standard library from Python 3.4. The package is still in provisional stage, that is
backward compatibility can be broken with future changes. However, the Python community is pretty excited about it and I know
personally that many people have started using it in production. So, I too decided to try it out. I built a rather simple
micro service using the excellent sanic framework and motor (for accessing mongodb). uvloop is an alternative event loop
implementation written in Cython on top of libuv and can be used as a drop in replacement for asyncio’s event loop. Sanic uses
uvloop behind the scene to go fast.
In this blog post, I would quickly introduce the technologies involved and then walk through some sample code with relevant explanations.
What is Asyncio? Why Should I Care?
In one of my earlier blog post - Async Python: The Different Forms of Concurrency, I have tried to elaborate on the different ways to achieve concurrency in the Python land. In the last part of the post, I have tried to explain what asyncio brings new to the table.
Asyncio allows us to write asynchronous, concurrent programs running on a single thread, using an event loop to schedule tasks and multiplexing I/O over sockets (and other resources). The one line explanation might be a little complex to comprehend at a glance. So I will break it down. In asyncio, everything runs on a single thread. We use coroutines which can be treated as small units of task that we can pause and resume. Then there is I/O multiplexing - when our tasks are busy waiting for I/O, an event loop pauses them and allows other tasks to run. When the paused tasks finish I/O, the event loop resumes them. This way even a single thread can handle / serve a large number of connections / clients by effectively juggling between “active” tasks and tasks that are waiting for some sort of I/O.
In general synchronous style, for example, when we’re using thread based concurrency, each client will occupy a thread and when we have a large number of connections, we will soon run out of threads. Though not all of those threads were active at a given time, some might have been simply waiting for I/O, doing nothing. Asyncio helps us solve this problem and provides an efficient solution to the concurrency problem.
While Twisted, Tornado and many other solutions have existed in the past, NodeJS brought huge attention to this kind of solution. And with Asyncio being in the standard library, I believe it will become the standard way of doing async I/O in the Python world over time.
What about uvloop?
We talked about event loop above. It schedules the tasks and deals with various events. It also manages the I/O multiplexing using
the various options offered by the operating system. In simple words - the event loop is very critical and the central part of the
whole asyncio operations. The asyncio package ships with an event loop by default. But we can also swap it for our custom
implementations if we need/prefer. uvloop is one such event loop that is very very fast. The key to it’s success could be partially
attributed to Cython. Cython allows us to write codes in Python like syntax while the codes perform like C. uvloop was written in
Cython and it uses the famous libuv library (also used by NodeJS).
If you are wondering if uvloop’s performances are good enough reason to swap out the default event loop, you may want to read this
aricle here - uvloop: Blazing fast Python networking or you can just
look at this following chart taken from that blog post:
Yes, it can go faster than NodeJS and catch up to Golang. Convinced yet? Let’s talk about Sanic!
Sanic - Gotta go fast!
Sanic was inspired by the above article I talked about. They used uvloop and httptools too (referenced in the article). The
framework provides a nice, Flask like syntax along with the async / await syntax from Python 3.5.
Please Note: uvloop still doesn’t work on Windows properly. Sanic uses the default asyncio event loop if uvloop
is not available. But this probably doesn’t matter because in most cases we deploy to linux machines anyway. Just in case you
want to try out the performance gains on Windows, I recommend you use a VM to test it inside a Linux machine.
Motor
Motor started off as an async mongodb driver for Tornado. Motor = Mongodb + Tornado. But Motor
now has pretty nice support for asyncio. And of course we can use the async / await syntax too.
I guess we have had brief introductions to the technologies we are going to use. So let’s get started with the actual work.
Setting Up
We need to install sanic and motor using pip.
pip install sanic
pip install motor
Sanic should also install it’s dependencies including uvloop and ujson along with others.
Set uvloop as the event loop
We will swap out the default event loop and use uvloop instead.
import asyncio
import uvloop
asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
Simple as that. We import asyncio and uvloop. We set the event loop policy to uvloop’s event loop policy and we’re done. Now asyncio will use uvloop as the default event loop.
Connecting to Mongodb
We will be using motor to connect to our mongodb. Just like this:
from motor.motor_asyncio import AsyncIOMotorClient
mongo_connection = AsyncIOMotorClient("<mongodb connection string>")
contacts = mongo_connection.mydatabase.contacts
We import the AsyncIOMotorClient and pass our mongodb connection string to it. We also point to our target collection
using a name / variable so that we can easily (and directly) use that collection later. Here mydatabase is the db name
and contacts is the collection name.
Request Handlers
Now we will dive right in and write our request handlers. For our demo application, I will create two routes. One for listing the contacts and one for creating new ones. But first we must instantiate sanic.
from sanic import Sanic
from sanic.response import json
app = Sanic(__name__)
Flask-like, remember? Now that we have the app instance, let’s add routes to it.
@app.route("/")
async def list(request):
data = await contacts.find().to_list(20)
for x in data:
x['id'] = str(x['_id'])
del x['_id']
return json(data)
@app.route("/new")
async def new(request):
contact = request.json
insert = await contacts.insert_one(contact)
return json({"inserted_id": str(insert.inserted_id)})
The routes are simple and for the sake of brevity, I haven’t written any error handling codes. The list function is async.
Inside it we await our contacts to arrive from the database, as a list of 20 entries. In a sync style, we would use the find
method directly but now we await it.
After we have the results, we quickly iterate over the documents and add id key and remove the _id key. The _id key is an
instance of ObjectId which would need us to use the bson package for serialization. To avoid complexity here, we just convert
the id to string and then delete the ObjectId instance. The rest of the document is usual string based key-value pairs (dict).
So it should serialize fine.
In the new function, we grab the incoming json payload and pass it to the insert_one method directly. request.json would
contain the dict representation of the json request. Check out this page
for other request data available to you. Here, we again await the insert_one call. When the response is available, we
take the inserted_id and send a response back.
Running the App
Let’s see the code first:
loop = asyncio.get_event_loop()
app.run(host="0.0.0.0", port=8000, workers=3, debug=True, loop=loop)
Here we get the default event loop and pass it to app.run along with other obvious options. With the workers argument,
we can set how many workers we want to use. This allows us to spin up multiple workers and take advantages of multiple cpu
cores. On a single core machine, we can just set it to 1 or totally skip that one.
The loop is optional as well. If we do not pass the loop, sanic will create a new one and set it as the default loop. But in
our case, we have connected to mongodb using motor before the app.run function could actually run. Motor now already uses the
default event loop. If we don’t pass that same loop to sanic, sanic will initialize a new event loop. Our database access and
sanic server will be on two different event loops and we won’t be able to make database calls. That is why we use the get_event_loop
function to retrieve the current default event loop and pass it to sanic. This is also why we set uvloop as the default event
loop on top of the file. Otherwise we would end up with the default loop (that comes with asyncio) and sanic would also have to
use that. Initializing uvloop at the beginning makes sure everyone uses it.
Final Code
So here’s the final code. We probably should clean up the imports and bring them up on top. But to relate to the different steps, I kept them as is. Also as mentioned earlier, the code has no error handling. We should write proper error handling code in all serious projects.
import asyncio
import uvloop
asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
from motor.motor_asyncio import AsyncIOMotorClient
mongo_connection = AsyncIOMotorClient("<connection string>")
contacts = mongo_connection.mydatabase.contacts
from sanic import Sanic
from sanic.response import json
app = Sanic(__name__)
@app.route("/")
async def list(request):
data = await contacts.find().to_list(20)
for x in data:
x['id'] = str(x['_id'])
del x['_id']
return json(data)
@app.route("/new")
async def new(request):
contact = request.json
insert = await contacts.insert_one(contact)
return json({"inserted_id": str(insert.inserted_id)})
loop = asyncio.get_event_loop()
app.run(host="0.0.0.0", port=8000, workers=3, debug=True, loop=loop)
Now let’s try it out?
Trying Out
I have saved the above code as main.py. So let’s run it.
python main.py
Now we can use curl to try it out. Let’s first add a contact:
curl -X POST -H "Content-Type: application/json" -d '{"name": "masnun"}' "http://localhost:8000/new"
We should see something like:
{"inserted_id":"582ceb772c608731477f5384"}
Let’s verify by checking / -
curl -X GET "http://localhost:8000/"
If everything goes right, we should see something like:
[{"id":"582ceb772c608731477f5384","name":"masnun"}]
I hope it works for you too! :-)
If you have any feedback or suggestions, please feel free to share it in the comments section. I would love to disqus :-)