DEV Community: Sebastián Ramírez

The Future of Education and Art

Sebastián Ramírez — Wed, 17 Aug 2022 10:58:00 +0000

This article lives in:

Intro

The current traditional education system is somewhat broken.

The jobs and requirements based on this system are also somewhat broken. Even more when combined with other arbitrary rules like fixed years of experience.

Our societies are at risk. If we don't change those things, if we don't do it fast enough, an increasing wave of poverty with more power and economic imbalances could come and do a lot of damage.

We can fix it.

And the future of education and art go together, at least I think they should.

I normally don't think that whatever I have to say could be important. But people keep asking me for my opinions on random things and making me feel like my ideas are sometimes useful.

This is one of those opinions I have, normally not so public, and probably controversial. But maybe others could find it useful too, so I'm writing this.

This is just my point of view. It doesn't represent anyone. And I can also change, adjust, and clarify my own point of view later. But maybe some of these ideas can be useful to others.

The Traditional Education System

The traditional education system seems designed to train people to adapt and work in the industrial revolution, in factories and such. That was a long time ago. Go early, dress the same, sit at a table, have a supervisor (teacher) in front of many people, do the same things as others do, etc.

People are given lots and lots of information, in most cases, without much purpose. I think most things learned and taught should have some purpose, otherwise, it's very difficult to learn them, and even more to apply that knowledge. But anyway, that could be a longer post.

Good institutions normally can afford very good teachers.

But these institutions and those teachers are located at a specific point on earth.

Only the people around that point or the ones that can afford to go there can apply to study there. And not many are received because the space, teachers, and resources are limited.

This ends up being some intrinsic gatekeeping. It's unavoidable, you just can't fit more people in that room of the building.

But it's not because the knowledge, the teacher's style, or resources should be limited to some people. It's just because the structure doesn't allow more people to access it.

And then, in that same structure, the teacher has to teach the same class year after year. Even if it's the same information, even if nothing new is added or changed, there's a lot of repetition there.

Many institutions around the world teach the same concepts and ideas. But they end up coming up with different ways to do it. Some can afford to make better materials, methods, or ways of teaching, but that's kept for only that institution. Other institutions keep teaching with the same old resources as before, even if that was improved somewhere else.

And in some cases, well regarded institutions teach old or somewhat obsolete concepts, or even privative tools that students will never be able to use again (e.g. a programming language), maybe just because the institution had a partnership with the provider of that tool. And when they go out and start working, they end up having to use a completely different tool, and learn it on the job either way.

But still, people end up wanting to move to some city to be able to attend some school, but the information or learnings are not necessarily tied to that particular place, it's just a coincidence.

Of course, some professions need hands-on physical experience, like doctors. But many professions are not tightly coupled to space, even more in technology and digital professions.

Education Systems Change Lives

I'm not against education, and I know from very close people that these same education systems can and do change lives.

When people have the choice of studying there or nothing, the difference of education is massive.

And many have the fortune of having amazing teachers that guide them and help them a lot. But that's not always the case.

And in some cases, some teachers that want and try to be better, to give practical materials and learnings, are stopped by the mechanics of what is expected in the system, maybe even just because it's easier for the administration to keep things unchanged.

And also, some education institutions are doing a big job to evolve and adapt to these new changes, which is amazing.

I'm not against any of that. I only think education systems need to evolve faster, we need to evolve faster, and find ways to teach faster, better, in more accessible ways, more dynamically. Because technology and advancements are not gonna wait for us.

Technology and Job Displacement

Technology has displaced jobs for a long time. Old jobs disappear, slowly or quickly, and new jobs appear. Old jobs are replaced by new ones.

The education systems have to (at least should) adapt to this and teach the new jobs and skills.

But technology moves fast, and maybe gets faster every time. And the speed at which technology can alter jobs is higher than the speed at which traditional education systems evolve.

Traditional education systems tend to expect very long periods dedicated only to absorbing new knowledge, in many cases without much purpose or practice, and then they expect that the next periods will be dedicated to applying that information, without acquiring new information.

But jobs related to or altered by technology make that idea of one long period studying and one long period applying less practical.

Technology changes fast. If you start studying something expecting it to take as long as traditional education systems would, by the time you finish, there might be some better alternative. But if you expect not to study again, you will not learn that new better alternative.

I think it would make more sense to start studying and start applying as soon as possible. And continue studying and applying forever.

Arguments against technology (e.g. against artificial intelligence) tend to include job displacement. Because for people that have been doing the same thing for a long time and don't have a way to change, update, and adapt, getting their job displaced would be very, very bad.

It's common to hear "artificial intelligence will replace us" and alarming things like that. But it's not a new problem, artificial intelligence is just technology, and technology has been changing jobs forever.

Technology, artificial intelligence, automation, are all just tools.

It's like a knife. The first knife used to cut meat was probably very useful, it was probably a great invention, and it surely helped people a lot then. But then a knife could also be used to kill someone. That doesn't necessarily make the knife itself a bad thing that should be avoided, but people should be taught to use it so that more people use it to improve lives than to damage them.

With technology we could have the power to reduce the need for many hazardous jobs, repetitive and sometimes numbing jobs, increase efficiency for everyone. We could have the power to increase the food production, reduce waste, reduce energy consumption. We could solve a lot of the problems in our society and our planet.

But then, we come again to the current traditional education systems. If people can't access the information easily, if it's not made to be easy to understand and apply, if it doesn't have a clear purpose, then we don't have a way to help people overcome the challenges from fast-moving technology, to get new jobs, to take advantage of those improvements in technology.

And powers or billionaires with more control of technology would just get more power, money and control of technology, while the rest gets less, and the imbalance would just get worse.

It could go really bad, or we could make it go well for everyone.

Job Requirements

The next problem is the traditional system of how to hire people.

The process of hiring people tends to be based on very old practices and assumptions that look more and more absurd every day.

If a job requires someone to have a specific degree from the traditional education system, that is gatekeeping and discarding anyone that could have learned the same things or more with alternative methods (it would certainly discard me, I was homeschooled all my life 😅).

And knowing that traditional education systems are not being able to evolve and adapt as fast as technology, why require someone to have a specific degree when that is not really what they are gonna need in the job that is evolving at the pace of technology?

A possible answer is that "they will have the foundational concepts of some topic". But then, the requirement tends to be "a degree on X". But they never examine the topics taught in that "X" career at that particular institution to see if the person knows what is needed. So, why such a strong emphasis in a particular degree when there's really no emphasis in the actual knowledge or skills?

Years of Experience

The same goes for years of experience. It's just a proxy indicator for the skill level, but it's quite a bad proxy.

One person could have 5 or 10 years working with the same technology, doing the same thing day after day. They are not learning something new. And the skills they can get in all that time are not that much.

And another person could work at a startup where they have to learn new skills very fast, take new challenges, even lead colleagues, and acquire the equivalent of "10 years of experience" in 2 years.

Companies and job requirements have to be updated as well, to check for actual skills, or at least better indicators of those skills, but less focus on particular degrees and years of experience.

Governments

Of course, governments could be greatly improved as well. They tend to be the slowest of them all. And many things in governments are still very tightly coupled to traditional and old structures, like traditional education system degrees.

But they are probably the most difficult to change, and they will slowly evolve and will have to adapt by force at some point.

That's a much harder battle, we can focus on the things we can have an impact on right now, because we need changes to start right now.

New Education Systems

Coming back to education systems, there are new ones. I'm not inventing anything new here.

The internet with articles, documentation, videos, massive online courses (in many cases free), provide a way for people around the world to access the same content.

Grading can be done by software online. It's not great, but it's not much worse than tests in traditional education systems, and can be scaled much better. The topic of how to test knowledge and the emphasis on those standard educational tests can also be greatly improved, but that's also another longer post.

Having these resources available online helps a lot with the limit and gatekeeping of physical locations on the planet. It also helps with the problem of the limited seats in a given room in a building, the internet doesn't have limited seats.

Even if the classes are done by the same teachers in person, accessing and using the best materials available online can help a lot.

But one of the best parts of all this is that the best teachers in the world can give their best classes once, record them, and everyone else could access them. No need for the teachers to work a lot more, at least it's not proportional to the people that can access the information.

And the content can be improved and refined by them or even others through time. And the best ways to teach something can emerge and improve. So that people can learn things easily and fast, with less effort every time, so more people can learn those things instead of having knowledge reserved only for the most brilliant ones that were able to disentangle a concept from a dry explanation.

Someone that I admire highly seems to have realized all this, several years ago. Andrew Ng was pioneering work on artificial intelligence, he probably realized all the job displacement it could produce, and that the next problem to solve for society would be education and access to it. And he went and founded Coursera, an online education platform. I think something similar happened with Sebastian Thrun and Udacity. And probably the same with edX and others too.

How New Education Systems Affected Me

I'm from Colombia, in Latin America, I was homeschooled all my life, I didn't go to the university (actually, not even to elementary school).

But I had access (sometimes) to the internet. I was able to download pages to read them offline and learn about web technologies and Wikipedia articles.

And then when these online course platforms appeared (and I had stable internet), I was able to take the same classes from well regarded institutions that people in those places could, otherwise I wouldn't have been able to.

Here's an interesting detail. I'm not against education institutions, not even traditional ones. The courses I studied were mostly from those same institutions. I'm against the system that enforces limiting information to only a few people based on arbitrary coincidences (location) and rules, and implicitly gatekeeping that knowledge, when making it more accessible doesn't cost more and can help much more people.

In those courses, I was taught very complex concepts in ways that seemed easy to understand, at times, I even felt smart. I studied the same concepts in different courses, through time, I also saw other people studying and struggling with the same concepts. And that let me see that some ways of teaching something were better than others.

In some cases the same concept could look much more complex than when it was explained differently. The way something is explained makes a huge difference. It makes a difference in the effort needed to learn, the speed at which something can be learned, the ability to apply the concept afterwards, etc.

Art for Education

At this point is where art comes in.

A possible definition of art would be the use of aesthetics and imagination to communicate something.

It doesn't have to be jolly, you could have a very sad and powerful piece of art, a song, a painting. But it uses aesthetics, sensation, imagination, to communicate that sadness, in a powerful way.

And education could be thought of as the communication of useful information that can be applied.

Now, art would be one of the most powerful ways to communicate in general (if not just the most). And education is also just about communicating things well.

I think art could and should be used for education, to teach things.

How many things are taught to kids via songs? Have you heard the saying that "an image is worth a thousand words"?

Art can accelerate the process of learning, teaching, and education in general.

And now that each piece of content, each resource that is made, can be available online to millions of people around the world, making art to explain a concept is worth it.

Before, making a piece of art, only for one class, given to a handful of people, might not have been worth the effort, time, money. But if you can teach millions, then all that investment is paid through time and people learning.

There's also the strange coincidence that artists tend to have a difficult life, it's not easy to succeed, at least economically, via arts. It tends to work for only a handful that takes all the fame and money, but it doesn't work well for the great majority.

But if art is not dedicated only to entertainment, but also to education, there are a lot of artists that can help, that resource is already there, and doing that would of course help them. Some hundreds or thousands of dollars for some work that can then be replicated for a long time with many people can be very fruitful for the thing that is being taught.

I imagine courses (mostly online, because those are the ones I've taken the most), where from time to time, they hire a new illustrator, or 3D artist, that makes a new animation that explains the concept that otherwise you would have to just imagine. Or musicians making short songs to teach ideas or things that need to be memorized, etc.

As part of that, there are also many things that improve how something is taught that I would consider art, or somewhat art at least. Like cues that bring the attention to some content (e.g. some piece of code), diagrams, tools to show and order the information in a beautiful way, etc. Making sure that something is amenable, that it's easy to communicate, is what ensures that it will have the intended effect, that it will be useful.

A Small Example Using Art for Education

I have been playing with this idea for a while. Some years ago I took an online course on edX from Berkeley about artificial intelligence. It was full of illustrations, and it was clear that the illustrator knew the concepts, because the illustrations were clear, easy to understand, and accurate. I didn't even think the course was "easy", but it was so enjoyable! And the concepts were much easier and fast to understand. I studied some of the same concepts in several other courses, and the difference between having clear illustrations and art and having only dense descriptions was really big.

I wanted to have illustrations for FastAPI too. So I recently hired Ketrina, the same illustrator from that edX course, and asked her to make some illustrations for the documentation explaining concurrency and parallelism in FastAPI.

I would hope that would help explain the concepts better and more easily.

I would hope others could also start using art to explain things better, more easily, and faster, and hopefully, making education more accessible to everyone.

About me

Hey! 👋 I'm Sebastián Ramírez (tiangolo).

You can follow me, contact me, see what I do, or use my open source code:

HTTPS for Developers

Sebastián Ramírez — Tue, 28 Sep 2021 08:27:34 +0000

This article lives in:

Intro

Here's a brief introduction to HTTPS for developers. 🔒

This article is extracted from the FastAPI docs about HTTPS.

I just upgraded those docs with several explanations and diagrams, and I thought the end result is generic and useful enough for many other developers (even in other languages and frameworks) to also publish it as a post, so here it is. 🤓

Who Is This For

If you are a user, your only interaction with HTTPS is with the browser opening URLs, then you are better off just reading How HTTPS Works.

If you are a cryptography researcher, you are better off studying the cryptographic primitives and then reading the standards (RFCs).

But if you are a developer (programmer, coder) and want to know enough technical details to understand how it works and how to use HTTPS in your applications without going into the depths of cryptography and web standards, then this is for you! 🎉👇

About HTTPS

It is easy to assume that HTTPS is something that is just "enabled" or not.

But it is way more complex than that.

To learn the basics of HTTPS, from a consumer perspective, check https://howhttps.works/.

Now, from a developer's perspective, here are several things to have in mind while thinking about HTTPS:

For HTTPS, the server needs to have "certificates" generated by a third party.
- Those certificates are actually acquired from the third party, not "generated".
Certificates have a lifetime.
- They expire.
- And then they need to be renewed, acquired again from the third party.
The encryption of the connection happens at the TCP level.
- That's one layer below HTTP.
- So, the certificate and encryption handling is done before HTTP.
TCP doesn't know about "domains". Only about IP addresses.
- The information about the specific domain requested goes in the HTTP data.
The HTTPS certificates "certify" a certain domain, but the protocol and encryption happen at the TCP level, before knowing which domain is being dealt with.
By default, that would mean that you can only have one HTTPS certificate per IP address.
- No matter how big your server is or how small each application you have on it might be.
- There is a solution to this, however.
There's an extension to the TLS protocol (the one handling the encryption at the TCP level, before HTTP) called SNI.
- This SNI extension allows one single server (with a single IP address) to have several HTTPS certificates and serve multiple HTTPS domains/applications.
- For this to work, a single component (program) running on the server, listening on the public IP address, must have all the HTTPS certificates in the server.
After obtaining a secure connection, the communication protocol is still HTTP.
- The contents are encrypted, even though they are being sent with the HTTP protocol.

It is a common practice to have one program/HTTP server running on the server (the machine, host, etc.) and managing all the HTTPS parts: receiving the encrypted HTTPS requests, sending the decrypted HTTP requests to the actual HTTP application running in the same server (the FastAPI application, in this case), take the HTTP response from the application, encrypt it using the appropriate HTTPS certificate and sending it back to the client using HTTPS. This server is often called a TLS Termination Proxy.

Some of the options you could use as a TLS Termination Proxy are:

Traefik (that can also handle certificate renewals)
Caddy (that can also handle certificate renewals)
Nginx
HAProxy

Let's Encrypt

Before Let's Encrypt, these HTTPS certificates were sold by trusted third parties.

The process to acquire one of these certificates used to be cumbersome, require quite some paperwork and the certificates were quite expensive.

But then Let's Encrypt was created.

It is a project from the Linux Foundation. It provides HTTPS certificates for free, in an automated way. These certificates use all the standard cryptographic security, and are short-lived (about 3 months), so the security is actually better because of their reduced lifespan.

The domains are securely verified and the certificates are generated automatically. This also allows automating the renewal of these certificates.

The idea is to automate the acquisition and renewal of these certificates so that you can have secure HTTPS, for free, forever.

HTTPS for Developers by Example

Here's an example of how an HTTPS API could look like, step by step, paying attention mainly to the ideas important for developers.

Domain Name

It would probably all start by you acquiring some domain name. Then, you would configure it in a DNS server (possibly your same cloud provider).

You would probably get a cloud server (a virtual machine) or something similar, and it would have a fixed public IP address.

In the DNS server(s) you would configure a record (an "A record") to point your domain to the public IP address of your server.

You would probably do this just once, the first time, when setting everything up.

Tip: This Domain Name part is way before HTTPS, but as everything depends on the domain and the IP address, it's worth mentioning it here.

DNS

Now let's focus on all the actual HTTPS parts.

First, the browser would check with the DNS servers what is the IP for the domain, in this case, someapp.example.com.

The DNS servers would tell the browser to use some specific IP address. That would be the public IP address used by your server, that you configured in the DNS servers.

TLS Handshake Start

The browser would then communicate with that IP address on port 443 (the HTTPS port).

The first part of the communication is just to establish the connection between the client and the server and to decide the cryptographic keys they will use, etc.

This interaction between the client and the server to establish the TLS connection is called the TLS handshake.

TLS with SNI Extension

Only one process in the server can be listening on a specific port in a specific IP address. There could be other processes listening on other ports in the same IP address, but only one for each combination of IP address and port.

TLS (HTTPS) uses the specific port 443 by default. So that's the port we would need.

As only one process can be listening on this port, the process that would do it would be the TLS Termination Proxy.

The TLS Termination Proxy would have access to one or more TLS certificates (HTTPS certificates).

Using the SNI extension discussed above, the TLS Termination Proxy would check which of the TLS (HTTPS) certificates available it should use for this connection, using the one that matches the domain expected by the client.

In this case, it would use the certificate for someapp.example.com.

The client already trusts the entity that generated that TLS certificate (in this case Let's Encrypt, but we'll see about that later), so it can verify that the certificate is valid.

Then, using the certificate, the client and the TLS Termination Proxy decide how to encrypt the rest of the TCP communication. This completes the TLS Handshake part.

After this, the client and the server have an encrypted TCP connection, this is what TLS provides. And then they can use that connection to start the actual HTTP communication.

And that's what HTTPS is, it's just plain HTTP inside a secure TLS connection instead of a pure (unencrypted) TCP connection.

Tip: Notice that the encryption of the communication happens at the TCP level, not at the HTTP level.

HTTPS Request

Now that the client and server (specifically the browser and the TLS Termination Proxy) have an encrypted TCP connection, they can start the HTTP communication.

So, the client sends an HTTPS request. This is just an HTTP request through an encrypted TLS connection.

Decrypt the Request

The TLS Termination Proxy would use the encryption agreed to decrypt the request, and would transmit the plain (decrypted) HTTP request to the process running the application (for example a process with Uvicorn running the FastAPI application).

HTTP Response

The application would process the request and send a plain (unencrypted) HTTP response to the TLS Termination Proxy.

HTTPS Response

The TLS Termination Proxy would then encrypt the response using the cryptography agreed before (that started with the certificate for someapp.example.com), and send it back to the browser.

Next, the browser would verify that the response is valid and encrypted with the right cryptographic key, etc. It would then decrypt the response and process it.

The client (browser) will know that the response comes from the correct server because it is using the cryptography they agreed using the HTTPS certificate before.

Multiple Applications

In the same server (or servers), there could be multiple applications, for example, other API programs or a database.

Only one process can be handling the specific IP and port (the TLS Termination Proxy in our example) but the other applications/processes can be running on the server(s) too, as long as they don't try to use the same combination of public IP and port.

That way, the TLS Termination Proxy could handle HTTPS and certificates for multiple domains, for multiple applications, and then transmit the requests to the right application in each case.

Certificate Renewal

At some point in the future, each certificate would expire (about 3 months after acquiring it).

And then, there would be another program (in some cases it's another program, in some cases it could be the same TLS Termination Proxy) that would talk to Let's Encrypt, and renew the certificate(s).

The TLS certificates are associated with a domain name, not with an IP address.

So, to renew the certificates, the renewal program needs to prove to the authority (Let's Encrypt) that it indeed "owns" and controls that domain.

To do that, and to accommodate different application needs, there are several ways it can do it. Some popular ways are:

Modify some DNS records.
- For this, the renewal program needs to support the APIs of the DNS provider, so, depending on the DNS provider you are using, this might or might not be an option.
Run as a server (at least during the certificate acquisition process) on the public IP address associated with the domain.
- As we said above, only one process can be listening on a specific IP and port.
- This is one of the reasons why it's very useful when the same TLS Termination Proxy also takes care of the certificate renewal process.
- Otherwise, you might have to stop the TLS Termination Proxy momentarily, start the renewal program to acquire the certificates, then configure them with the TLS Termination Proxy, and then restart the TLS Termination Proxy. This is not ideal, as your app(s) will not be available during the time that the TLS Termination Proxy is off.

All this renewal process, while still serving the app, is one of the main reasons why you would want to have a separate system to handle HTTPS with a TLS Termination Proxy instead of just using the TLS certificates with the application server directly (e.g. Uvicorn).

Recap

Having HTTPS is very important, and quite critical in most cases. Most of the effort you as a developer have to put around HTTPS is just about understanding these concepts and how they work.

But once you know the basic information of HTTPS for developers you can easily combine and configure different tools to help you manage everything in a simple way.

Learn More

This article is extracted from the FastAPI documentation about deployments and HTTPS.

If you want to learn concrete examples of some tools you can use and how to configure them to deploy a FastAPI application, check out the next chapters in the FastAPI documentation.

About me

Hey! 👋 I'm Sebastián Ramírez (tiangolo).

You can follow me, contact me, see what I do, or use my open source code:

The Future of FastAPI and Pydantic is Bright

Sebastián Ramírez — Sat, 19 Jun 2021 14:19:37 +0000

This article lives in:

In very short

The future of FastAPI and Pydantic is bright. ✨

This is because we all, as the Python community, define their future. To help us and to help others. From the Core Developers making Python itself to the new developers that started learning Python this month.

And as long as these tools are helping us all solve problems, help ourselves, help others, and be more efficient and productive, we all will keep them working and improving.

And that's what we are all doing. 🤓🚀

Intro

You might have heard not long ago about PEP 563, PEP 649, and some changes that could affect Pydantic and FastAPI in the future.

If you read about it, I wouldn't expect you to understand what all that meant. I didn't fully understand it until I spent hours reading all the related content and doing multiple experiments.

It might have worried you and maybe confuse you a bit.

Now there's nothing to be worried about. But still, here I want to help clarify all that and give you a bit more context.

Brace yourself, you are about to learn a bit more about how Python works, how FastAPI and Pydantic work, how type annotations work, and more. 👇

Details

Start with a basic FastAPI app

FastAPI is based on Pydantic. Let's see a simple example using them both.

Imagine that we have a file ./main.py with the following code:

from typing import Optional

import uvicorn
from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float


app = FastAPI()

@app.post("/items/")
def create_item(item: Item):
    return item


if __name__ == "__main__":
    uvicorn.run(app)

You could run this example and start the API application with:

$ python ./main.py

INFO:     Started server process [4418]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Then you could open your browser and interact with the API docs at http://127.0.0.1:8000/docs, etc.

But here we want to focus on what happens behind the scenes.

Note: Instead of using the last two lines, you could have used the uvicorn command, and that's what you would normally do. But for this example, it will be useful to see everything from the point of view of the python command.

How Python works

By running that command above, you are asking your system to start the program called python. And to give it the file main.py as a parameter.

Note: In Windows, the program might be called python.exe instead of just python.

That program called python (or python.exe) is written in another programming language called "C". Maybe you knew that.

And what that program python does is read the file main.py, interpret the code that we wrote in it using the Python Programming Language, and execute it step by step.

So, we have two things with more or less the same name "python" that represent something slightly different:

python: the program that runs our code (which is actually written in the C programming language)
"Python": the name of the programming language we use to write our code

So, you could say that python (the program) can read Python (the programming language).

What is Runtime

Now, when that program python is executing our code written in the Python programming language, we call that "runtime".

It's just the period of time when it is executing our code.

When our code is not being executed, for example, when we are editing the file ./main.py, it is not running, so we are not at runtime.

The way that program works is that, at runtime (when our code is being executed), Pydantic and FastAPI read those type annotations (or type hints) to extract their data and do things with it.

So, for example, in the Item class above, we have:

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float

At runtime, Pydantic and FastAPI will see that name is a str and price is a float. And if we send a JSON request with a price that is not a float, they will be able to validate the data for us.

FastAPI and Pydantic are written in pure Python. How can these tools do that? Python is so powerful that it has features to allow exactly that, to read type annotations at runtime from the same Python code. And Pydantic and FastAPI take advantage of those features.

Another term commonly used to refer to doing things at runtime is to do things dynamically.

What is Static Analysis

The counterpart of runtime would be static. It just means that the code is not being executed. It's treated just as a text file containing code.

In many cases, "static" is used when saying Static Analysis, Static Checking, Static Type Checking, etc. It refers to tools that understand the rules of the Python Programming Language and that can analyze the code, but that doesn't execute the code itself.

These tools for static analysis can check if the code is following the rules correctly, checking that the code is valid, providing autocompletion, and other features. When you are editing code and your editor shows a squiggly red line with an error somewhere, that is static analysis.

In some cases, the code could be valid, but it would still be incorrect. For example, if you try to add a str and a float together:

name = "Rick"
price = 1.99

total = name + price

In terms of the rules of the language itself, the code is valid, all the quotes are where they should be, the equal signs are correctly placed, etc. But this code is still incorrect and will not work because you can't add a str with a float.

Many editors will be able to show you a very valuable squiggly red line with the error message under name + price that might save you hours debugging. That is also static analysis.

Some tools that do static analysis and that you might have heard of are:

mypy, the official and main Static Type Checker
flake8, checks for style and correctness
black, autoformats the code in a consistent way that improves efficiency
PyCharm, one of the most popular Python editors, has internal components that do static analysis to check for errors, provide autocompletion, etc.
VS Code, the other of the most popular Python editors, using Pylance, also has internal tools to do static analysis to check for errors, provide autocompletion, etc.

These tools have saved tons of development hours by detecting many bugs earlier in the development process and in the exact place where those errors happened. I bet that in many cases you might have seen the red line, realize what the error is, think "ah, yeah, right", fix it, and not even consider that there was a bug in your code, even for some seconds. If I counted all the times these tools have saved me from these bugs, I would get overwhelmed quickly. 😅

And if you have ever added type annotations to a code base that didn't have them before, you probably would have seen lots of broken sections in the code base and broken corner cases, that were suddenly obvious and you could then fix them. I surely have.

Type Annotations in Python

The Type Annotations (also called Type Hints) that we have available in all the supported modern Python versions (Python 3.6 and above) were designed to improve all that static analysis.

The original intention was to allow mypy and others to help developers while writing the code. And that was the main focus for a while.

But then tools like dataclasses (from the standard library) and Samuel Colvin's Pydantic started using these type annotations to do more than only static analysis, and to use these same type annotations at runtime. In the case of Pydantic, to extract that information to do data conversion, validation, and documentation.

Type Annotations with Forward References

Now, imagine we have a class (it could be a Pydantic model) like this:

from typing import Optional

from pydantic import BaseModel


class Person(BaseModel):
    name: str
    child: Optional[Person] = None

Here we have a Person that could have a child, that would also be a Person. It all looks fine, right?

But now when we run the code (or with the help of some static analysis in editors) we will see that we declared child: Optional[Person] inside the body of the class Person. So, when that part of the code is run by python, the Person inside of name: Optional[Person] doesn't exist yet (that class is still being created).

This is called a Forward Reference. And it would make the code break.

And again, the main purpose of these type annotations was to help with static analysis. Using them at runtime was not yet an important use case.

And having the code break just because we are trying to improve static analysis would be very annoying.

To overcome that problem, it's also valid to declare that internal Person as a literal string, like this:

from typing import Optional

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    child: Optional["Person"] = None

That looked weird to me when I discovered it. It's the name of a class just put there inside a string. But it's valid.

When python is running, it will see that as a literal string, so it will not break.

And most static analysis tools know this is valid and will read the literal string and understand that it actually refers to the Person class.

By knowing that the Optional["Person"] actually refers to the Person class, static analysis tools can, for example, detect that this would be an error:

parent = Person(name="Beth")

parent.child = 3

A smart editor will use its static analysis tools to detect that parent.child = 3 is an error because it expects a Person.

This solves the problem of the forward reference in the code and allows us to still use static analysis tools.

...we are not talking about using these type annotations at runtime yet, but we'll get there later.

PEPs in Python

PEP stands for Python Enhancement Proposal. A PEP is a technical document describing changes to Python, additions to the standard library (for example, adding dataclasses), and other types of changes. Or in some cases, they just provide information and establish conventions.

The name says Proposal, but when they are finally accepted they become a standard.

PEP 563 - Postponed Evaluation of Annotations

Knowing what's a PEP, let's go back to the code example above.

If you hadn't seen something like the Optional["Person"] part before, you might have cringed a bit. I did the first time I discovered that was valid, but it was understandable as it would solve the problem.

Then Łukasz Langa had a smart idea and wrote PEP 563.

If the way type annotations were interpreted changed, and if they were implicitly understood by Python as if they were all just strings, then we would not have to put all those classes inside strings in strange places in our code.

So, we would write our code like:

from typing import Optional

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    child: Optional[Person] = None

And then whenever python read our file ./main.py it would see it as if it was written like this:

from typing import Optional

from pydantic import BaseModel

class Person(BaseModel):
    name: "str"
    child: "Optional[Person]" = None

So, python would run our code happily and without breaking.

And we, the developers would be much happier not having to remember where to put things inside strings and where not.

And we would be able to keep using autocompletion and type checks even in these type annotations with forward references. For example, triggering autocompletion inside a string, with the previous technique, might not always work, but with this change that wouldn't be a problem anymore.

And in the case that some tool ended up using these type annotations at runtime for other reasons, there were still ways to get the information at runtime, with some small caveats, but it was still possible.

Spoiler Alert: These small caveats are what later would become a cumbersome problem for Pydantic, but we'll get there.

Note: Have in mind that this was done several years ago, in fact, the same year Pydantic was released for the first time. Using type annotations at runtime for other purposes than static analysis was not a common use case if at all. It's remarkable that it was even accounted for.

Now, as this would change the behavior of Python internally in a more or less drastic way, it would not be enforced by default yet. Instead, it was made available using a special import, from __future__ import annotations:

from __future__ import annotations
from typing import Optional

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    child: Optional[Person] = None

And as now these type annotations were treated as just strings, it allowed some interesting tricks when using them only for static analysis, like using typing features from future versions of Python in previous versions.

For example, declaring Person | None instead of Optional[Person], avoiding the extra Optional and the extra import, even in Python 3.7 (that feature is available in Python 3.10 but not in Python 3.7):

from __future__ import annotations

class Person:
    name: str
    child: Person | None = None

Note: Have in mind that this would only work for static analysis tools, your editor could understand that even in Python 3.7, but Pydantic wouldn't be able to use it and wouldn't work correctly.

This has been there, available since Python 3.7. And that behavior was planned to be the default for Python 3.10 onwards (not now, but keep reading).

Pydantic and PEP 563

Now, forward to the present, a couple of months ago.

Pydantic already has some support for using from __future__ import annotations in the code as made possible by PEP 563. And in many cases, it works fine. For example, this works:

from __future__ import annotations
from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel


# ✅ Pydantic models outside of functions will always work
class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float


app = FastAPI()


@app.post("/items/")
def create_item(item: Item):
    return item

But there are some caveats that wouldn't work. For example, this doesn't work:

from __future__ import annotations
from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel


def create_app():
    # 🚨 Pydantic models INSIDE of functions would not work
    class Item(BaseModel):
        name: str
        description: Optional[str] = None
        price: float


    app = FastAPI()


    @app.post("/items/")
    def create_item(item: Item):
        return item
    return app


app = create_app()

If you run that code, you would get a disconcerting error:

NameError: name 'Item' is not defined

To solve it in this case, you could move the Item class outside of the function. And there are some other similar corner cases.

These types of disconcerting problems would be especially inconvenient for newcomers to Python (and probably to many experienced Python developers as well), as the problem is not obvious at all for someone that doesn't know the internals (it wasn't obvious to me, and I built FastAPI and Typer 😅).

Python is an example of a very inclusive global tech community, welcoming newcomers from all around the world, from many disciplines. It is being used to solve the most complex problems, including taking pictures of black holes, running drones on Mars, and building the most sophisticated artificial intelligence systems. But at the same time, it's many people's first programing language for its ease of use and its simplicity. And many Python developers don't even consider themselves "developers", even while they use it to solve problems.

So, having an inconvenience like this by default would not be ideal. There are other caveats but I don't want to go deeper into the technical details than I already have. You can read more about them on the Pydantic issue, the mailing list thread, and Łukasz's detailed explanation.

PEP 649 - Deferred Evaluation Of Annotations Using Descriptors

Recently, Larry Hastings that had been working on an alternative to PEP 563, PEP 649, contacted Samuel Colvin (Pydantic's author) and me (author of FastAPI and Typer), as suggested by Brett Cannon (from the Python Steering Council), to see if and how those changes would affect us.

We realized that the changes from PEP 563 (the other one) would be permanently added to Python 3.10 (not requiring the from __future__ import annotations), and the caveats and problems still didn't have a solution.

Suddenly it was also clear that these use cases of using type annotations at runtime instead of only for static analysis were not an obvious use case for everyone involved, including the same Larry Hastings who was working on what would be a potential solution for these use cases.

Asking for Reconsideration

Sadly, we realized all this very late, only weeks before these changes would be set in stone in Python 3.10 (in the end they weren't). Nevertheless, we showed our concerns.

If you read about all this before, that's probably why. It was shared a lot, and it got a bit out of hand.

And sadly, there were some radical comments attacking several of the parts involved (the Python Steering Council, us, etc), as if it was a fight between different groups. 😕

In reality, we are just one big group, the Python Community, and we are all trying to do the best for all of us.

Sadly, all this sudden friction brought a lot of increased stress to all the parties involved. To the Python Steering Council, Core Python Developers, and us, library authors.

Fortunately, everything came out well in the end.

Here's a big shoutout to Carol Willing that, despite the added stress generated for her and everyone else involved, she helped a lot reconciling different points of view, reducing the friction, and calming down all the situation. That capacity of acknowledging and adopting other's points of view is priceless. We need more Carol Willings in the world. 🤓

Python Steering Council decision

In case you didn't know, the decision of what goes into Python and what doesn't is done by the Python Steering Council.

It is currently formed by:

Barry Warsaw
Brett Cannon
Carol Willing
Pablo Galindo Salgado
Thomas Wouters

Now, back to the story, after a couple of days of that previous discussion, during the next Python Steering Council meeting, they unanimously decided to roll back the decision of making these type annotations as strings (as described in PEP 563) being the default behavior.

Having those string type annotations by default in Python 3.10 had been decided some time ago, and rolling that change back only weeks before the "feature freeze" (the moment where no more changes are accepted into the next version) was a big decision, involving a lot of extra stress and effort.

Nevertheless, they took the decision in order to support the community of users of FastAPI, Pydantic, and other libraries using these features:

We can’t risk breaking even a small subset of the FastAPI/pydantic users, not to mention other uses of evaluated type annotations that we’re not aware of yet.

This, again, shows the strong commitment of the Python community, starting from the Steering Council, to be inclusive, and supportive of all users, with different use cases.

Here's another big shoutout to Pablo Galindo, who took all the extra work to perform all the last-minute changes, and even voted in favor of them.

What's Next

The decision was to keep the current behavior, of allowing from __future__ import annotations in the code, as defined by PEP 563, but not as the default behavior.

This will provide enough time to find a solution or an alternative that works for all the use cases, including Pydantic, FastAPI, and also the use cases that are interested exclusively in static analysis.

This is the best possible outcome for everyone. 🎉

It gives enough time to find an alternate solution and it avoids hurried decisions with little time that could have unknown negative effects.

Who cares about FastAPI and Pydantic

Now, in general, how does the future of FastAPI and Pydantic look like? Who cares about them?

FastAPI, using Pydantic, was included for the first time in the last Python Developer Survey, and despite being the first year in it, it was already ranked as the third most popular web framework, after Flask and Django. This shows that it's being useful for many people.

It was also included in the latest ThoughtWorks Technology Radar, as one of the technologies that enterprises should start trying out.

FastAPI and Pydantic are currently being used by many products and organizations, from the biggest ones you've heard of, to the smallest teams, including solo developers.

Several popular and widely used cloud providers, SaaS tools, databases, etc. are adding documentation, tutorials, and even improving their offers to better serve the FastAPI users.

The most popular code editors for Python, PyCharm and Visual Studio Code, have been working on improving their support for FastAPI and Pydantic. I have even talked to both teams directly. 🤓

This is particularly interesting because FastAPI was designed to have the best support from editors, to provide the best developer experience possible. FastAPI and Pydantic use almost exclusively standard features of the language. When editors improve their support (even more) for these tools, they are actually improving their support for the features of the language itself. And this benefits many other use cases apart from FastAPI and Pydantic.

Conclusion

Python is a great community.

We are all trying to make it better for all of us, from the Steering Council and Core Developers to library authors and even those who help others using these libraries.

FastAPI and Pydantic are part of this community that includes and supports everyone, with all their use cases.

And that's the main reason why the future of FastAPI and Pydantic is so bright. Because the future of Python is bright. We all make this future. ✨

Thanks

Thanks to everyone involved in finding a solution and improving the Python community. 🙇

And special thanks to:

for their review and feedback on this article before publishing.

About me

Hey! 👋 I'm Sebastián Ramírez (tiangolo).

You can follow me, contact me, see what I do, or use my open source code:

Deploying FastAPI (and other) apps with HTTPS powered by Traefik

Sebastián Ramírez — Sat, 06 Mar 2021 19:13:19 +0000

This article lives in:

Intro

Let's say you have a FastAPI application... or actually, any other type of web application, including a Panel dashboard with Pandas DataFrames and Bokeh visualizations, or a Streamlit application. These are, in the end, web applications. You could think of many other examples.

Now let's say it all works well locally, on your machine.

But in most cases, the purpose of these web apps is to be available on the real web (not only on your machine), so that others can actually access them.

So you need to "deploy" them somewhere, on a remote server.

And then you would want to have secure communication between your app clients (web browsers, mobile apps, etc.) and your server web application.

So, you should have HTTPS. 🔒

But although it might sound like a simple "option" to enable, it's quite more complex than that... and Traefik can help you a lot.

I have been a long-time fan of Traefik, even before creating FastAPI.

And recently I had the chance to make an event/webinar with them. 🎉

You can watch the recording of the video here on the Traefik resources' website.

About HTTPS

HTTPS is quite more complex than "enabling an option".

The protocol any of your applications will need to "talk" is actually the same HTTP, so you don't have to change anything in your web apps to change from HTTP to HTTPS.

But that HTTP communication has to go through a secure connection (TLS/SSL), that's where the "S" in HTTPS comes from, "HTTP Secure".

There's a whole process required, including acquiring HTTPS (TLS/SSL) certificates. But fortunately, Let's Encrypt provides them for free... you just have to set everything up.

But then, "setting everything up" including acquiring the certificates, installing them where appropriate, renewing them every three months, etc. It's all a relatively complex process. But Traefik can do all that for you.

To quickly learn how HTTPS works from the consumer's perspective, I highly encourage you to go and check HowHTTPS.works.

Then you can go and read the short summary of what you need to know as a developer in the FastAPI docs: About HTTPS.

Domain name

HTTPS is tied to a domain name because the TLS certificate is for that specific domain name.

So, you need to have one or buy one.

I buy my domains at Name.com, it's quite cheap and it has worked quite well for me.

Remote server

You will also need a "cloud" or remote server.

It's frequently called a "VPS" for "virtual private server". It's a "private server" because you get a full Linux system with full control of it (contrary to a "shared hosting"). And it's "virtual" because what providers do is create a virtual machine and make it available for you, instead of installing a real physical server, that's why they are affordable.

For simplicity, I would suggest these providers:

I personally have things in each one of those. They all work great, they have a simple and nice user experience, and are quite cheap.

Even $5 or $10 USD a month is enough to have one of the small servers up and running.

You can also go and use one of the giant cloud infrastructure providers if you want, learn all their terminology and components, set up all the accounts, permissions, etc. And then use them. But for this example, I would suggest one of the three above as it will be a lot simpler.

DNS records

When you create a remote server, it will have a public IP.

But now you need to configure your domain to point to that IP, so that when your users go to your domain, they end up talking to your remote server in its IP.

There's a set of "records" that do that, they are called "DNS records" (DNS for "Domain Name System").

Those records are stored in "Name Servers". All of these cloud providers above have free Name Servers, so you can use them to store that information about pointing domains to IPs.

Tip: those same DNS records are also used for configuring email, and other related small things.

Note: all these Name Server and DNS changes are automatically copied and replicated through the web so that everyone in the world knows where to access the information about your domain, and then, with that, they will know to which IP they should talk to when interacting with your domain. Because that replication takes some time, after you save some of these changes, they can take from minutes to hours to be ready.

Name Servers

The first step is in your "registrar" (the entity that sold you the domain, e.g. Name.com). In there, you define what are the Name Servers for your domain.

You will probably first want to remove the default Name Servers. After buying a domain, the default Name Servers are normally the ones for the same registrar (e.g. Name.com), and normally all they do is have DNS records to point the domain to a placeholder page full of ads, but they normally don't allow you to create DNS records (like pointing the domain to an IP address).

So, you will probably want to remove those default Name Servers and add the ones for your VPS provider.

E.g. you could add the Name Servers for DigitalOcean:

ns1.digitalocean.com
ns2.digitalocean.com
ns3.digitalocean.com

DNS Records

After you configure the Name Servers for your domain to be the ones for your cloud provider, you can now go to that cloud provider and set up the DNS Records.

Depending on your cloud provider, they will have some section to configure "domains", "domain zones", or "networks", in the end, they all refer to the same configurations for DNS records for a specific domain.

So, the next step is to create a configuration there for your specific domain (sometimes called a "domain zone").

Then, inside of that domain configuration, you need to add a DNS record to point any web communication to your cloud server.

There are several types of DNS records, the one we need is an A record, when you are creating a DNS record, those are normally the default type as they are the most important one.

An A record has an IP and a hostname.

The IP would be the one for your remote server. You might need to go to the section in the dashboard where your server is located to copy that IP.

The hostname would be your domain or any sub-domain. So, if you bought example.com, you can set the record to example.com, or to somesubdomain.example.com or also a.long.sub.domain.example.com. In most cases, you can even use *.example.com, which will match any sub-domain and point it to the IP you specify.

You can create multiple A records, one for each domain or sub-domain. And each of them can point to different IPs. That's also why you see some applications that use several domains, like dashboard.example.com and api.example.com, to handle different parts of the same system in different servers.

Note: depending on the provider, you might need to use the symbol @ in the hostname to mean "the same domain I'm configuring", so, for the domain configurations for example.com, creating an A record with some IP and the hostname @ would mean "point the same domain example.com to that IP address".

Wait

You might have to wait sometime for these DNS changes to replicate.

You can test if your computer already has access to the most recent version of your records with the tool ping from the command line. For example, checking for the domain tiangolo.com:

$ ping tiangolo.com                               
PING tiangolo.com (104.198.14.52) 56(84) bytes of data.
64 bytes from 52.14.198.104.bc.googleusercontent.com (104.198.14.52): icmp_seq=1 ttl=103 time=204 ms
64 bytes from 52.14.198.104.bc.googleusercontent.com (104.198.14.52): icmp_seq=2 ttl=103 time=226 ms

you can see the IP address is 104.198.14.52. If that's what you just configured, congrats!

The DNS records are ready. 🎉

Check the video

From this point, you should be able to follow the video recording with all the explanations.

So I'll keep the rest of this post as simple as possible, mainly showing you the config files so you can copy all the examples.

Simple FastAPI app

Let's start with a basic FastAPI app.

I'm assuming that you know a bit about FastAPI, if you don't, feel free to check the documentation, it is written as a tutorial.

If you want to see the explanation step by step, feel free to check the video.

The basic app we will use is in a file at ./app/main.py, with:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_main():
    return {"message": "Hello World of FastAPI with Traefik"}

Dockerfile

We will use Docker to deploy everything.

So, make sure you install it.

Then we need a file at ./app/Dockerfile with:

FROM tiangolo/uvicorn-gunicorn-fastapi:python3.8

COPY ./app /app/

Notice that we are using the official FastAPI Docker image: tiangolo/uvicorn-gunicorn-fastapi:python3.8.

The official base Docker image does most of the work for us, so we just have to copy the code inside.

Make sure you have Docker installed on your local computer and in the remote server.

Prepare your cloud server

Connect to your remote server from your terminal with SSH, it could be something like:

ssh root@fastapi-with-traefik.example.com

Update the list of package versions available:

apt update

Upgrade the packages to the latest version:

apt upgrade

Docker Compose

We are using Docker Compose to manage all the configurations. So make you install Docker Compose locally and on the remote server.

To prevent Docker Compose from hanging, install haveged:

apt install haveged

Technical Details: Docker Compose uses the internal pseudo-random number generators of the machine. But in a freshly installed/created cloud server, it might not have enough of that "randomness". And that could make the Docker Compose commands hang forever waiting for enough "randomness" to use. haveged prevents/fixes that issue.

After that, you can check that Docker Compose works correctly.

Docker Compose files

For all the detailed explanations of the Docker Compose files, check the video recording.

Make sure you update the domains from example.com to use yours, and the email to register with Let's Encrypt, you will receive notifications about your expiring certificates in that email.

Also, make sure you add the right DNS records for your main application, and for the Traefik dashboard, and update them in the Docker Compose files accordingly.

Here are the Docker Compose files if you want to easily copy them.

docker-compose.traefik.yml:

services:

  traefik:
    # Use the latest v2.3.x Traefik image available
    image: traefik:v2.3
    ports:
      # Listen on port 80, default for HTTP, necessary to redirect to HTTPS
      - 80:80
      # Listen on port 443, default for HTTPS
      - 443:443
    restart: always
    labels:
      # Enable Traefik for this service, to make it available in the public network
      - traefik.enable=true
      # Define the port inside of the Docker service to use
      - traefik.http.services.traefik-dashboard.loadbalancer.server.port=8080
      # Make Traefik use this domain in HTTP
      - traefik.http.routers.traefik-dashboard-http.entrypoints=http
      - traefik.http.routers.traefik-dashboard-http.rule=Host(`traefik.fastapi-with-traefik.example.com`)
      # Use the traefik-public network (declared below)
      - traefik.docker.network=traefik-public
      # traefik-https the actual router using HTTPS
      - traefik.http.routers.traefik-dashboard-https.entrypoints=https
      - traefik.http.routers.traefik-dashboard-https.rule=Host(`traefik.fastapi-with-traefik.example.com`)
      - traefik.http.routers.traefik-dashboard-https.tls=true
      # Use the "le" (Let's Encrypt) resolver created below
      - traefik.http.routers.traefik-dashboard-https.tls.certresolver=le
      # Use the special Traefik service api@internal with the web UI/Dashboard
      - traefik.http.routers.traefik-dashboard-https.service=api@internal
      # https-redirect middleware to redirect HTTP to HTTPS
      - traefik.http.middlewares.https-redirect.redirectscheme.scheme=https
      - traefik.http.middlewares.https-redirect.redirectscheme.permanent=true
      # traefik-http set up only to use the middleware to redirect to https
      - traefik.http.routers.traefik-dashboard-http.middlewares=https-redirect
      # admin-auth middleware with HTTP Basic auth
      # Using the environment variables USERNAME and HASHED_PASSWORD
      - traefik.http.middlewares.admin-auth.basicauth.users=${USERNAME?Variable not set}:${HASHED_PASSWORD?Variable not set}
      # Enable HTTP Basic auth, using the middleware created above
      - traefik.http.routers.traefik-dashboard-https.middlewares=admin-auth
    volumes:
      # Add Docker as a mounted volume, so that Traefik can read the labels of other services
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # Mount the volume to store the certificates
      - traefik-public-certificates:/certificates
    command:
      # Enable Docker in Traefik, so that it reads labels from Docker services
      - --providers.docker
      # Do not expose all Docker services, only the ones explicitly exposed
      - --providers.docker.exposedbydefault=false
      # Create an entrypoint "http" listening on port 80
      - --entrypoints.http.address=:80
      # Create an entrypoint "https" listening on port 443
      - --entrypoints.https.address=:443
      # Create the certificate resolver "le" for Let's Encrypt, uses the environment variable EMAIL
      - --certificatesresolvers.le.acme.email=admin@example.com
      # Store the Let's Encrypt certificates in the mounted volume
      - --certificatesresolvers.le.acme.storage=/certificates/acme.json
      # Use the TLS Challenge for Let's Encrypt
      - --certificatesresolvers.le.acme.tlschallenge=true
      # Enable the access log, with HTTP requests
      - --accesslog
      # Enable the Traefik log, for configurations and errors
      - --log
      # Enable the Dashboard and API
      - --api
    networks:
      # Use the public network created to be shared between Traefik and
      # any other service that needs to be publicly available with HTTPS
      - traefik-public

volumes:
  # Create a volume to store the certificates, there is a constraint to make sure
  # Traefik is always deployed to the same Docker node with the same volume containing
  # the HTTPS certificates
  traefik-public-certificates:

networks:
  # Use the previously created public network "traefik-public", shared with other
  # services that need to be publicly available via this Traefik
  traefik-public:
    external: true

docker-compose.yml:

services:

  backend:
    build: ./
    restart: always
    labels:
      # Enable Traefik for this specific "backend" service
      - traefik.enable=true
      # Define the port inside of the Docker service to use
      - traefik.http.services.app.loadbalancer.server.port=80
      # Make Traefik use this domain in HTTP
      - traefik.http.routers.app-http.entrypoints=http
      - traefik.http.routers.app-http.rule=Host(`fastapi-with-traefik.example.com`)
      # Use the traefik-public network (declared below)
      - traefik.docker.network=traefik-public
      # Make Traefik use this domain in HTTPS
      - traefik.http.routers.app-https.entrypoints=https
      - traefik.http.routers.app-https.rule=Host(`fastapi-with-traefik.example.com`)
      - traefik.http.routers.app-https.tls=true
      # Use the "le" (Let's Encrypt) resolver
      - traefik.http.routers.app-https.tls.certresolver=le
      # https-redirect middleware to redirect HTTP to HTTPS
      - traefik.http.middlewares.https-redirect.redirectscheme.scheme=https
      - traefik.http.middlewares.https-redirect.redirectscheme.permanent=true
      # Middleware to redirect HTTP to HTTPS
      - traefik.http.routers.app-http.middlewares=https-redirect
      - traefik.http.routers.app-https.middlewares=admin-auth
    networks:
      # Use the public network created to be shared between Traefik and
      # any other service that needs to be publicly available with HTTPS
      - traefik-public

networks:
  traefik-public:
    external: true

docker-compose.override.yml:

services:

  backend:
    ports:
      - 80:80

networks:
  traefik-public:
    external: false

Start the stacks

There are many approaches for putting your code and Docker images on your server.

You could have a very sophisticated Continuous Integration system. But for this example using a simple rsync would be enough.

For example:

rsync -a ./* root@fastapi-with-traefik.example.com:/root/code/fastapi-with-traefik/

Then, inside of your server, make sure you create the Docker network:

docker network create traefik-public

Next, create the environment variables for HTTP Basic Auth.

Create the username, e.g.:

export USERNAME=admin

Create an environment variable with the password, e.g.:

export PASSWORD=changethis

Use openssl to generate the "hashed" version of the password and store it in an environment variable:

export HASHED_PASSWORD=$(openssl passwd -apr1 $PASSWORD)

And now you can start the Traefik Docker Compose stack:

docker-compose -f docker-compose.traefik.yml up

Next, start the main Docker Compose stack:

docker-compose -f docker-compose.yml up -d

Check your app

After that, if everything worked correctly (and probably it didn't work correctly the first time 😅), you should be able to check your new application live at your domain, something like:

https://fastapi-with-traefik.example.com

And the Traefik dashboard at:

https://traefik.fastapi-with-traefik.example.com

And the Traefik dashboard would be protected by HTTP Basic Auth, so no one can go and tamper with your Traefik.

Celebrate 🎉

Congrats! That's a very stable way to have a production application deployed.

You can probably improve that a lot, add Continuous Integration, monitoring, logging, use a complete cluster of machines instead of a single one (e.g. use Kubernetes instead of Docker Compose), etc. There's no limit to adding more stuff and improving it all...

But with this, you already have the minimum to serve your users a secure application.

And as your deployment is based on Docker, and can be replicated easily and quickly, you could destroy that server, create a new one from scratch, and be live again in minutes. Because it doesn't depend on that specific server.

All the important configurations and setup are in your Docker Compose files.

And all the important logic and setup of the actual app are in the Docker image (with the Dockerfile).

And Docker itself is taking care of having your application running, restarting it after failures or reboots, etc.

Dessert 🍰

Do you want a bit more?

Check the source code for this blog post, including the latest version of the app and config files, including a basic example with Panel, and one with Streamlit. ✨

Learn More

Here are some extra resources:

I hope that was useful! 🚀

About me

Hey! 👋 I'm Sebastián Ramírez (tiangolo).

You can follow me, contact me, see what I do, or use my open source code:

FastAPI top-level dependencies

Sebastián Ramírez — Sun, 03 Jan 2021 11:16:26 +0000

This article lives in:

Intro

FastAPI version 0.62.0 comes with global dependencies that you can apply to a whole application.

As well as top-level dependencies, tags, and other parameters for APIRouters, that before were available only on app.include_router().

This makes it easier to put configurations and dependencies (e.g. for authentication) related to a group of path operations more closely together. 🔒

Let's start by checking APIRouter...

Include a router

Imagine you had a file users.py with:

from fastapi import APIRouter

router = APIRouter()


@router.get("/users/")
def read_users():
    return ["rick", "morty"]

And now let's say you want to include it in the main.py file with:

from fastapi import FastAPI, Depends
from . import users
from .dependencies import get_query_token

app = FastAPI()

app.include_router(
    users.router,
    tags=["users"],
    dependencies=[Depends(get_query_token)]
)


@app.get("/")
def main():
    return {"message": "Hello World"}

In this example, you are applying the tag users to all the path operations in users.py. And you are also applying the dependency get_query_token to all of them.

This works, and it was the only/main way to do it up to version 0.62.0.

But what is not so great about it is that the tag and the dependency are mainly related to users.py, not to main.py. But that code had to live in main.py, instead of being closer to what it is related to.

`APIRouter` top-level dependencies and tags

Now, with FastAPI version 0.62.0, you can declare top-level dependencies, tags, and others in the APIRouter directly.

So, the new router.py can now look like:

from fastapi import APIRouter, Depends
from .dependencies import get_query_token

router = APIRouter(
    tags=["users"],
    dependencies=[Depends(get_query_token)]
)


@router.get("/users/")
def read_users():
    return ["rick", "morty"]

...notice the tags and dependencies in the APIRouter, they can now live closer to their related code! 🎉

And the main.py would be simply:

from fastapi import FastAPI
from . import users

app = FastAPI()

app.include_router(
    users.router,
)


@app.get("/")
def main():
    return {"message": "Hello World"}

Global dependencies

In the same way, you can now also declare dependencies that apply to all the path operations in the FastAPI application:

from fastapi import FastAPI, Depends
from .dependencies import get_query_token

app = FastAPI(
    dependencies=[Depends(get_query_token)]
)

@app.get("/")
def main():
    return {"message": "Hello World"}

Tips

Some tips to adopt a convention:

By default, set all those configs in APIRouter().
Try to only set them in app.include_router() when you want to override some defaults that can't (or shouldn't) be set in APIRouter directly.
Set them in FastAPI() only when you want them to apply to everything, e.g. some default authentication for a simple app.

Learn More

You can read more about global dependencies.

And about APIRouter top-level dependencies, tags, and others.

If you don't want to miss other news, you can subscribe to the FastAPI and friends official newsletter. 🎉

About me

Hey! 👋 I'm tiangolo (Sebastián Ramírez).

You can follow me, contact me, see what I do, or use my open source code:

Concurrent Burgers - Understand async / await

Sebastián Ramírez — Sun, 17 May 2020 06:57:46 +0000

This article lives in:

Dev.to
Medium
GitHub
FastAPI's docs (including translations to other languages)

Intro

Modern versions of Python (and other languages) have support for "asynchronous code" using something called "coroutines", with async and await syntax.

Here's a friendly and not very technical explanation to give some intuition about all that, including asynchronous code, concurrency, and parallelism.

This is taken from the docs for FastAPI, a modern framework for building APIs in Python.

Although this was written for Python and FastAPI, all the story and information is relevant for other languages that also have async and await, like JavaScript and Rust.

Now, let's see that phrase by parts in the sections below:

Asynchronous Code
async and await
Coroutines

Asynchronous Code

Asynchronous code just means that the language 💬 has a way to tell the computer / program 🤖 that at some point in the code, it 🤖 will have to wait for something else to finish somewhere else. Let's say that something else is called "slow-file" 📝.

So, during that time, the computer can go and do some other work, while "slow-file" 📝 finishes.

Then the computer / program 🤖 will come back every time it has a chance because it's waiting again, or whenever it 🤖 finished all the work it had at that point. And it 🤖 will see if any of the tasks it was waiting for have already finished, doing whatever it had to do.

Next, it 🤖 takes the first task to finish (let's say, our "slow-file" 📝) and continues whatever it had to do with it.

That "wait for something else" normally refers to I/O operations that are relatively "slow" (compared to the speed of the processor and the RAM memory), like waiting for:

the data from the client to be sent through the network
the data sent by your program to be received by the client through the network
the contents of a file in the disk to be read by the system and given to your program
the contents your program gave to the system to be written to disk
a remote API operation
a database operation to finish
a database query to return the results
etc.

As the execution time is consumed mostly by waiting for I/O operations, they call them "I/O bound" operations.

It's called "asynchronous" because the computer / program doesn't have to be "synchronized" with the slow task, waiting for the exact moment that the task finishes, while doing nothing, to be able to take the task result and continue the work.

Instead of that, by being an "asynchronous" system, once finished, the task can wait in line a little bit (some microseconds) for the computer / program to finish whatever it went to do, and then come back to take the results and continue working with them.

For "synchronous" (contrary to "asynchronous") they commonly also use the term "sequential", because the computer / program follows all the steps in sequence before switching to a different task, even if those steps involve waiting.

Concurrency and Burgers

This idea of asynchronous code described above is also sometimes called "concurrency". It is different from "parallelism".

Concurrency and parallelism both relate to "different things happening more or less at the same time".

But the details between concurrency and parallelism are quite different.

To see the difference, imagine the following story about burgers:

Concurrent Burgers

You go with your crush 😍 to get fast food 🍔, you stand in line while the cashier 💁 takes the orders from the people in front of you.

Then it's your turn, you place your order of 2 very fancy burgers 🍔 for your crush 😍 and you.

You pay 💸.

The cashier 💁 says something to the guy in the kitchen 👨‍🍳 so he knows he has to prepare your burgers 🍔 (even though he is currently preparing the ones for the previous clients).

The cashier 💁 gives you the number of your turn.

While you are waiting, you go with your crush 😍 and pick a table, you sit and talk with your crush 😍 for a long time (as your burgers are very fancy and take some time to prepare ✨🍔✨).

As you are sitting on the table with your crush 😍, while you wait for the burgers 🍔, you can spend that time admiring how awesome, cute and smart your crush is ✨😍✨.

While waiting and talking to your crush 😍, from time to time, you check the number displayed on the counter to see if it's your turn already.

Then at some point, it finally is your turn. You go to the counter, get your burgers 🍔 and come back to the table.

You and your crush 😍 eat the burgers 🍔 and have a nice time ✨.

Imagine you are the computer / program 🤖 in that story.

While you are at the line, you are just idle 😴, waiting for your turn, not doing anything very "productive". But the line is fast because the cashier 💁 is only taking the orders (not preparing them), so that's fine.

Then, when it's your turn, you do actual "productive" work 🤓, you process the menu, decide what you want, get your crush's 😍 choice, pay 💸, check that you give the correct bill or card, check that you are charged correctly, check that the order has the correct items, etc.

But then, even though you still don't have your burgers 🍔, your work with the cashier 💁 is "on pause" ⏸, because you have to wait 🕙 for your burgers to be ready.

But as you go away from the counter and sit on the table with a number for your turn, you can switch 🔀 your attention to your crush 😍, and "work" ⏯ 🤓 on that. Then you are again doing something very "productive" 🤓, as is flirting with your crush 😍.

Then the cashier 💁 says "I'm finished with doing the burgers" 🍔 by putting your number on the counter's display, but you don't jump like crazy immediately when the displayed number changes to your turn number. You know no one will steal your burgers 🍔 because you have the number of your turn, and they have theirs.

So you wait for your crush 😍 to finish the story (finish the current work ⏯ / task being processed 🤓), smile gently and say that you are going for the burgers ⏸.

Then you go to the counter 🔀, to the initial task that is now finished ⏯, pick the burgers 🍔, say thanks and take them to the table. That finishes that step / task of interaction with the counter ⏹. That in turn, creates a new task, of "eating burgers" 🔀 ⏯, but the previous one of "getting burgers" is finished ⏹.

Parallel Burgers

Now let's imagine these aren't "Concurrent Burgers", but "Parallel Burgers".

You go with your crush 😍 to get parallel fast food 🍔.

You stand in line while several (let's say 8) cashiers that at the same time are cooks 👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳 take the orders from the people in front of you.

Everyone before you is waiting 🕙 for their burgers 🍔 to be ready before leaving the counter because each of the 8 cashiers goes himself and prepares the burger right away before getting the next order.

Then it's finally your turn, you place your order of 2 very fancy burgers 🍔 for your crush 😍 and you.

You pay 💸.

The cashier goes to the kitchen 👨‍🍳.

You wait, standing in front of the counter 🕙, so that no one else takes your burgers 🍔 before you do, as there are no numbers for turns.

As you and your crush 😍 are busy not letting anyone get in front of you and take your burgers whenever they arrive 🕙, you cannot pay attention to your crush 😞.

This is "synchronous" work, you are "synchronized" with the cashier/cook 👨‍🍳. You have to wait 🕙 and be there at the exact moment that the cashier/cook 👨‍🍳 finishes the burgers 🍔 and gives them to you, or otherwise, someone else might take them.

Then your cashier/cook 👨‍🍳 finally comes back with your burgers 🍔, after a long time waiting 🕙 there in front of the counter.

You take your burgers 🍔 and go to the table with your crush 😍.

You just eat them, and you are done 🍔 ⏹.

There was not much talk or flirting as most of the time was spent waiting 🕙 in front of the counter 😞.

In this scenario of the parallel burgers, you are a computer / program 🤖 with two processors (you and your crush 😍), both waiting 🕙 and dedicating their attention ⏯ to be "waiting on the counter" 🕙 for a long time.

The fast food store has 8 processors (cashiers/cooks) 👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳. While the concurrent burgers store might have had only 2 (one cashier and one cook) 💁 👨‍🍳.

But still, the final experience is not the best 😞.

This would be the parallel equivalent story for burgers 🍔.

For a more "real life" example of this, imagine a bank.

Up to recently, most of the banks had multiple cashiers 👨‍💼👨‍💼👨‍💼👨‍💼 and a big line 🕙🕙🕙🕙🕙🕙🕙🕙.

All of the cashiers doing all the work with one client after the other 👨‍💼⏯.

And you have to wait 🕙 in the line for a long time or you lose your turn.

You probably wouldn't want to take your crush 😍 with you to do errands at the bank 🏦.

Burger Conclusion

In this scenario of "fast food burgers with your crush", as there is a lot of waiting 🕙, it makes a lot more sense to have a concurrent system ⏸🔀⏯.

This is the case for most of the web applications.

Many, many users, but your server is waiting 🕙 for their not-so-good connection to send their requests.

And then waiting 🕙 again for the responses to come back.

This "waiting" 🕙 is measured in microseconds, but still, summing it all, it's a lot of waiting in the end.

That's why it makes a lot of sense to use asynchronous ⏸🔀⏯ code for web APIs.

Most of the existing popular Python frameworks (including Flask and Django) were created before the new asynchronous features in Python existed. So, the ways they can be deployed support parallel execution and an older form of asynchronous execution that is not as powerful as the new capabilities.

Even though the main specification for asynchronous web Python (ASGI) was developed at Django, to add support for WebSockets.

That kind of asynchronicity is what made NodeJS popular (even though NodeJS is not parallel) and that's the strength of Go as a programing language.

And that's the same level of performance you get with FastAPI.

And as you can have parallelism and asynchronicity at the same time, you get higher performance than most of the tested NodeJS frameworks and on par with Go, which is a compiled language closer to C (all thanks to Starlette).

Is concurrency better than parallelism?

Nope! That's not the moral of the story.

Concurrency is different than parallelism. And it is better on specific scenarios that involve a lot of waiting. Because of that, it generally is a lot better than parallelism for web application development. But not for everything.

So, to balance that out, imagine the following short story:

You have to clean a big, dirty house.

Yep, that's the whole story.

There's no waiting 🕙 anywhere, just a lot of work to be done, on multiple places of the house.

You could have turns as in the burgers example, first the living room, then the kitchen, but as you are not waiting 🕙 for anything, just cleaning and cleaning, the turns wouldn't affect anything.

It would take the same amount of time to finish with or without turns (concurrency) and you would have done the same amount of work.

But in this case, if you could bring the 8 ex-cashier/cooks/now-cleaners 👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳👨‍🍳, and each one of them (plus you) could take a zone of the house to clean it, you could do all the work in parallel, with the extra help, and finish much sooner.

In this scenario, each one of the cleaners (including you) would be a processor, doing their part of the job.

And as most of the execution time is taken by actual work (instead of waiting), and the work in a computer is done by a CPU, they call these problems "CPU bound".

Common examples of CPU bound operations are things that require complex math processing.

For example:

Audio or image processing.
Computer vision: an image is composed of millions of pixels, each pixel has 3 values / colors, processing that normally requires computing something on those pixels, all at the same time.
Machine Learning: it normally requires lots of "matrix" and "vector" multiplications. Think of a huge spreadsheet with numbers and multiplying all of them together at the same time.
Deep Learning: this is a sub-field of Machine Learning, so, the same applies. It's just that there is not a single spreadsheet of numbers to multiply, but a huge set of them, and in many cases, you use a special processor to build and / or use those models.

Concurrency + Parallelism: Web + Machine Learning

With FastAPI you can take the advantage of concurrency that is very common for web development (the same main attractive of NodeJS).

But you can also exploit the benefits of parallelism and multiprocessing (having multiple processes running in parallel) for CPU bound workloads like those in Machine Learning systems.

That, plus the simple fact that Python is the main language for Data Science, Machine Learning and especially Deep Learning, make FastAPI a very good match for Data Science / Machine Learning web APIs and applications (among many others).

To see how to achieve this parallelism in production see the FastAPI docs for Deployment.

`async` and `await`

Modern versions of Python have a very intuitive way to define asynchronous code. This makes it look just like normal "sequential" code and do the "awaiting" for you at the right moments.

When there is an operation that will require waiting before giving the results and has support for these new Python features, you can code it like:

burgers = await get_burgers(2)

The key here is the await. It tells Python that it has to wait ⏸ for get_burgers(2) to finish doing its thing 🕙 before storing the results in burgers. With that, Python will know that it can go and do something else 🔀 ⏯ in the meanwhile (like receiving another request).

For await to work, it has to be inside a function that supports this asynchronicity. To do that, you just declare it with async def:

async def get_burgers(number: int):
    # Do some asynchronous stuff to create the burgers
    return burgers

...instead of def:

# This is not asynchronous
def get_sequential_burgers(number: int):
    # Do some sequential stuff to create the burgers
    return burgers

With async def, Python knows that, inside that function, it has to be aware of await expressions, and that it can "pause" ⏸ the execution of that function and go do something else 🔀 before coming back.

When you want to call an async def function, you have to "await" it. So, this won't work:

# This won't work, because get_burgers was defined with: async def
burgers = get_burgers(2)

Other forms of asynchronous code

This style of using async and await is relatively new in the language.

But it makes working with asynchronous code a lot easier.

This same syntax (or almost identical) was also included recently in modern versions of JavaScript (in Browser and NodeJS).

But before that, handling asynchronous code was quite more complex and difficult.

In previous versions of Python, you could have used threads or Gevent. But the code is way more complex to understand, debug, and think about.

In previous versions of NodeJS / Browser JavaScript, you would have used "callbacks". Which leads to callback hell.

Coroutines

Coroutine is just the very fancy term for the thing returned by an async def function. Python knows that it is something like a function that it can start and that it will end at some point, but that it might be paused ⏸ internally too, whenever there is an await inside of it.

But all this functionality of using asynchronous code with async and await is many times summarized as using "coroutines". It is comparable to the main key feature of Go, the "Goroutines".

Conclusion

Let's see the same phrase from above:

Modern versions of Python have support for "asynchronous code" using something called "coroutines", with async and await syntax.

That should make more sense now. ✨

All that is what powers FastAPI (through Starlette) and what makes it have such an impressive performance.

Learn More

This version has some of the details that are very specific to FastAPI trimmed out. If you want to learn those, including how to get asynchronous performance benefits while still writing standard def functions and using standard libraries, check the FastAPI docs.

If you want a deeper and much more technical explanation of all this, check this video series from EdgeDB by Łukasz Langa.

About me

Hey! 👋 I'm Sebastián Ramírez (tiangolo).

You can follow me, contact me, ask questions, see what I do, or use my open source code:

Build a web API from scratch with FastAPI - the workshop

Sebastián Ramírez — Thu, 27 Feb 2020 21:08:18 +0000

This article lives in:

The first FastAPI workshop at PyCon Belarus

Last weekend I had the chance to go to PyCon Belarus, I had a great time and met a lot of great people.

I gave a talk there:

Liquid error: internal

And a workshop with about 60 people:

Liquid error: internal

Creating the workshop

When creating the workshop I got a bit excited and created too much content for the time I had available.

The final app ended up having basic OAuth2 authentication, authorization handling with dependencies, tests with full coverage, etc.

I "gave" a test trial of the full workshop to Camila and the total time was about 9 hours, it wasn't really possible to give it all in 3 hours.

But as it was made in incremental steps, completing a full new version of the app at every step (or every 2 steps), we could start it and go through it, step by step, and advance as much as possible. And wherever we ended up by the end would still be a valid version of the app.

The first version of the workshop

The speed of a workshop like this has a constant tradeoff, as there's always people that finish some part faster than others, so, at some points some people will be "bored" while others will be stressed finishing some part before the next comes.

But nevertheless, at the workshop in PyCon Belarus developers were quite fast, and we were able to go up to version 8 of the app, while I was expecting to get only up to about version 5.

But there were 15 versions. So, for those that wanted to see the final version, here it is.

Source code for the final version

I don't have an easy way to provide it step by step with all the explanations here, but if you are curious you can still check here the last version of the code.

It was all based on the same FastAPI documentation, so, if you want to understand it all you can just follow the full FastAPI Tutorial - User Guide.

Below are the initial setup instructions and then the link to the full code of the last version.

Create a project directory

Create a directory for the project.

For example ./apiapp/:

$ mkdir apiapp
$ cd ./apiapp/

Create a Python environment

In the ./apiapp/ directory, create a new Python environment.

You could be using Poetry, Pipenv, or other tools.

To make it simple we are going to use pure Python with the venv module.

Make sure you have a Python version > 3.6:

$ python --version

# OR

$ python3.6 --version

# OR

$ python3.7 --version

Then use that Python 3.6+ to create a new environment for your project.

python -m venv env

That will create a directory ./env/ that will contain a full Python environment, with its own packages, etc.

And in that environment is that we are going to install packages and everything.

Initialize git

$ git init

Ignore that environment in git

Inside of that ./env/ directory, create a file .gitignore with the contents:

(that's a single * in the file).

That will tell git that we want to ignore everything inside that directory.

Activate the environment

Now we need to "activate" the environment.

This will tell your terminal that when you try to run python it should use the new Python you just installed in that ./env/ directory and not the global one.

Activate the environment:

$ source ./env/bin/activate

To make sure that it worked, check which Python binary is used by your terminal.

$ which python

It should show the path of the new Python, something like:

/home/user/code/apiapp/env/bin/python

Activate in Windows

If you are in Windows, in Git Bash, activate with:

$ source ./env/Scripts/activate

If you are using PowerShell, activate with:

$ .\env\Scripts\Activate.ps1

To confirm which Python you have in PowerShell use:

$ Get-Command python

Deactivate an environment

We don't need to deactivate the environment because we are going to use it. But if you need to deactivate it later, just run:

$ deactivate

Open your editor

Open your editor and select that environment.

Visual Studio Code

If you have Visual Studio Code and a shell like Bash, you can just run:

$ code ./

In any case, make sure you select the environment you just created for your editor.

If you use Visual Studio Code, make sure you have the Python Extension.

You can then create a dummy file dummy.py and open it. That will make VS Code load the extension and show the Python environment used.

In the lower left corner you will see the Python version used, if you click it, you can select a different one.

After this, you can delete the dummy.py file.

PyCharm

If you use PyCharm as your editor, open it.

Select your project directory ./apiapp/ as the workspace.

Then Configure a Python interpreter for your project, and select the interpreter inside of the environment you just created.

Using the correct environment

Using the correct environment in your editor as we described here and opening it exactly in your project directory will make your editor know the installed packages and will let it provide autocompletion, type checks, relative imports, etc.

If you didn't configure the environment correctly or if you didn't open it exactly in your project directory (for example, you open one directory above), your editor won't be able to give you all those features.

Create files

Now, in your editor, create a directory app. It will store all your actual code.

Inside of that app directory, create 2 empty files main.py and __init__.py.

And inside of your project directory, right next to the app directory, create an empty requirements.txt file.

Your file structure should look like:

apiapp
├── app
│   ├── __init__.py
│   └── main.py
├── requirements.txt
└── env
    └── ...

Requirements

Edit your requirements.txt to have the following contents:

fastapi
uvicorn
sqlalchemy
async-exit-stack
async-generator
passlib[bcrypt]
python-jose[cryptography]
python-multipart
python-dotenv

Install requirements

Now install the requirements from that requirements.txt file in the terminal with:

$ pip install -r requirements.txt

Dev requirements

Now, to facilitate development, we'll also add extra packages that will help us during development.

Create a file dev-requirements.txt with:

black
mypy
flake8
requests
pytest
pytest-cov
isort
autoflake

Install dev requirements

And now install the development requirements in the same way:

$ pip install -r dev-requirements.txt

In VS Code

Enable Language Server, mypy, black in the settings.

Reload editor

You might need to reload your editor for it to be able to detect the newly installed packages.

Reload environment

Right after installing new Python packages in your environment, you should activate the environment again:

$ source ./env/bin/activate

Note: If you are on Windows use the equivalent command.

This will ensure that packages that have a command, like uvicorn will be available in your terminal.

Make sure that uvicorn is available and is the correct version after installing and re-activating the environment:

$ which uvicorn

It should show the uvicorn from your environment.

Note: Other package managers

If you used a different environment and package manager like Poetry or Pipenv, the requirements.txt file would be a different file and it would be managed differently, but here we are using the simplest version with the pure/standard Python packages (venv, pip, etc).

The app - version 1

Now we are going to create the first version of our app.

Edit - v1

Edit the file main.py...

Run - v1

Run it:

$ uvicorn app.main:app --reload

Edit main.py again, Uvicorn auto-reloads.

Final Version

The final version of the source code is here: https://github.com/tiangolo/blog-posts/tree/master/pyconby-web-api-from-scratch-with-fastapi/apiapp

Additional scripts

There's a script to run the tests and report coverage in HTML so that you can explore it in your browser:

$ bash test.sh

And there is a script to format all the code automatically:

$ bash format.sh

About me

You can follow me, contact me, ask questions, see what I do, or use my open source code:

How to start contributing to open source

Sebastián Ramírez — Mon, 23 Dec 2019 07:01:39 +0000

Here's a tip to help you get started contributing to open source (if you haven't started yet).

This article lives in:

TL;DR

(too long, didn't read)

Newbies are great at docs, better than maintainers. Start with that.

Find a problem

First, find a problem that you want to solve, something that you care about.

If you see you can solve it easily without technology, cool, go and do that. And come back with a new problem ;)

Then find how technology could help to solve it, what kind of app or system would help.

Find a project

Then find an open source project that would help to solve that problem.

If there's a tool that solves the whole problem, that's great. But it's more probable that you will have to divide the problem into smaller parts, and then find an open source tool that would help with some part of the problem.

Study it

Study that open source tool.

Read its documentation, try the examples, learn how to use it.

If it's solving a problem you care about (or part of it) it will be useful, it will be interesting to study. And having a real-world objective for that tool helps you put the focus where it should be.

Documentation

While you study that tool, there are high chances that the documentation has obsolete parts, needs updates, clarifications, etc.

Or simply, it could have been explained better.

Now, that you are just starting and have a fresh point of view with that tool, it's the perfect moment to improve documentation.

You need some steps first:

Learn how to make a pull request with change suggestions.
Learn about the docs for that project. How they are created. It's normally some text files in a directory in the same project, or in a sibling project. But you normally can just edit the small part that you found without having to learn everything about that project's docs system.
Fork that project to get your own version to change and propose changes to the original.

Update the docs

Now add documentation for that project.

Add the examples that would have helped you get started, with a focus on a simple real-life problem (like yours) that this tool would help solve.

Add the text that would have explained to you the same concepts more easily.

Add the definitions of the words the maintainer assumed were obvious but were required to know to be able to do the first steps.

Add documentation for the things that aren't documented yet.

Update the things that seem complex or difficult. Once you understand them, think how someone could have explained them better to you, and write that.

Fix typos. There are always typos.

Any of those changes would probably be an independent pull request. Keep them separated, with the minimum changes, with a very clear scope. That helps maintainers accept just the things they are fine with.

After that, you will already have a bunch of contributions to open source. From there on it's a lot easier.

But that's a good way to get started.

The newbie advantage

If you are a "newbie" with that open source tool, if you are just getting started with it, you have a great advantage over the maintainers or any other more experienced developer that uses that tool. And it's exactly that. That you are a newbie... you know nothing about that tool.

That means that you have a completely fresh point of view. You don't take anything for granted with that tool. You don't assume as obvious some basic concepts of the tool because you weren't the same person developing it for months, knowing all its internal workings.

Also, you are actually reading the docs. And you are reading them in order. So, you can more easily spot things that could have been explained before or better. You can find inconsistencies in different parts.

And you won't be reading it "like you know it", it won't be the 30th time you read those same docs, it will be the first. So, you will more easily be able to detect incorrect things, typos, etc.

A maintainer, an experienced user, or a contributor won't normally spend much time reading the docs again and again, so, those "small" errors accumulate.

And a maintainer or the project creator will never have a fresh point of view, without all the background of having built the whole tool.

A newbie has a fresh point of view. And that's an advantage.

Start with docs!

About me

You can follow me, contact me, ask questions, see what I do, or use my open source code:

DEV Community: Sebastián Ramírez

The Future of Education and Art

Intro

The Traditional Education System

Education Systems Change Lives

Technology and Job Displacement

Job Requirements

Years of Experience

Governments

New Education Systems

How New Education Systems Affected Me

Art for Education

A Small Example Using Art for Education

About me

HTTPS for Developers

Intro

Who Is This For

About HTTPS

Let's Encrypt

HTTPS for Developers by Example

Domain Name

DNS

TLS Handshake Start

TLS with SNI Extension

HTTPS Request

Decrypt the Request

HTTP Response

HTTPS Response

Multiple Applications

Certificate Renewal

Recap

Learn More

About me

The Future of FastAPI and Pydantic is Bright

In very short

Intro

Details

Start with a basic FastAPI app

How Python works

What is Runtime

What is Static Analysis

Type Annotations in Python

Type Annotations with Forward References

PEPs in Python

PEP 563 - Postponed Evaluation of Annotations

Pydantic and PEP 563

PEP 649 - Deferred Evaluation Of Annotations Using Descriptors

Asking for Reconsideration

Python Steering Council decision

What's Next

Who cares about FastAPI and Pydantic

Conclusion

Thanks

About me

Deploying FastAPI (and other) apps with HTTPS powered by Traefik

Intro

About HTTPS

Domain name

Remote server

DNS records

Name Servers

DNS Records

Wait

Check the video

Simple FastAPI app

Dockerfile

Prepare your cloud server

Docker Compose

Docker Compose files

Start the stacks

Check your app

Celebrate 🎉

Dessert 🍰

Learn More

About me

FastAPI top-level dependencies

Intro

Include a router

APIRouter top-level dependencies and tags

Global dependencies

`APIRouter` top-level dependencies and tags

`async` and `await`