# Introduction

Welcome to the Bocadillo documentation!

Here is some general information about Bocadillo you may want to know before getting started.

In a hurry? Skip to Installation.

# About this website

This documentation site is an ongoing community effort. If you've found a typo, use the "Edit" link at the bottom of each page to submit a fix!

# Why Bocadillo?

Bocadillo is a Python asynchronous web framework. It is built on top of asyncio and Starlette, and implements the ASGI standard.

With Bocadillo, you can use asynchronous programming available in Python 3.6+ to build fast, scalable and real-time capable web APIs.

Here's how Bocadillo makes this as fun and approachable as possible:

• Productive

  Bocadillo is an ASGI web framework designed to help you build, test and deploy web APIs as easily as possible. It focuses on modularity, has thorough documentation, and integrates seamlessly with third-party async libraries.

• Real-time capable

  Embrace asynchronous programming and use the built-in WebSocket and SSE support to design real-time, highly-concurrent systems.

• Performant

  Bocadillo makes the most out of Starlette and Uvicorn, the lightning-fast ASGI toolkit and web server.

• Scalable

  As your project grows, features such as routers, providers and plugins help you solve a variety of problems out of simple components.

• Tooling

  Bocadillo ships with testing and development tools that help you build high-quality applications.

• Documented

  We make sure every single feature is documented front to back, and provide optimal editor support with a 100% type-annotated code base.

To learn more about the framework's history, design decisions, or why it's even called Bocadillo in the first place, check out the FAQ.

# What makes Bocadillo an async web framework?

We keep saying that Bocadillo is a Python async web framework — what does it mean?

Historically, web frameworks in the Python ecosystem — Django, Flask, Pyramid, Falcon, etc. — have been built using the WSGI standard. WSGI is a common language that Python web servers (such as gunicorn) and web applications use to communicate.

Yet, WSGI was not designed for concurrency. It can only handle one request at a time. As a result, if processing a request requires running a 10-second long database query, other clients have to wait, period.

This is why, after the introduction of asynchronous programming in Python 3.5 (async/await, asyncio, etc), the community worked towards a new standard. The result of this effort was ASGI - the Asynchronous Server Gateway Interface.

Just like WSGI, ASGI is a common language that enables communication between asynchronous web servers (such as uvicorn) and asynchronous web applications (such as Bocadillo). This is similar to how HTTP makes the communication between web browsers and web servers possible.

In short, Bocadillo is an async web framework because it speaks the ASGI language.

This has a number of benefits. Among others, you can now build highly-concurrent web apps and services, which typically results in higher throughput for applications that spend a lot of time on I/O.

# Do I need to use async?

Yes, you will need to use asynchronous programming to write Bocadillo applications.

We think this decision was totally worth it, because:

• It's why you are here — and why you didn't use a WSGI framework like Flask or Django in the first place.
• It's faster: internally, Bocadillo must deal with async functions anyway (because async is all-in), so supporting synchronous APIs would have reduced performance.
• It's enriching: we believe this is a great opportunity to level-up your Python async skills!

# I'm new to async. Where can I get help?

Although Bocadillo was designed to make working with async as pleasurable as possible, we do know that learning async Python can be overwhelming in the beginning.

If you need help to get the ground running, take a look at the Async crash course.