Introduction

Expanse is a modern and elegant web application framework.

At the heart of its design and architecture is and always will be the developer experience. Expanse wants to get out of your way and let you build what matters by giving you intuitive and powerful tools like transparent dependency injection, a powerful database component (powered by SQLAlchemy), queues (Coming soon), authentication (Coming soon), authorization (Coming soon), and more.

(A)synchronous

Expanse is an asynchronous framework at heart but gives you the choice to use either synchronous or asynchronous components. Every native component provided by the framework come in both flavors so you can choose whichever fits your needs on a case by case basis. There is no wrong choice here and if you were to decide to switch you can simply replace the components with their synchronous or asynchronous counterpart.

The core concepts and architecture of the framework do not change from one implementation to the other, so if you follow the conventions outlined in this documentation this should be easy.

The documentation will always provide examples for each implementation where relevant.

That being said, calling blocking code from asynchronous code is strongly discouraged as it will block the event loop and degrade the performance of your application. If you are unsure about what to use, it's usually better to go with the synchronous implementation since Expanse will make sure to run it in a thread pool when called from asynchronous code and keep the performance impact to a minimum.

Creating a new project

Before creating your first project, make sure that you have Python (minimum version: 3.11) installed on your machine along with pipx.

1. Install the official Expanse CLI to create your project:

   pipx install expanse-cli
   
   expanse new my-app
   

   Alternatively to using the official installer, you can simply clone the Git project (https://github.com/python-expanse/app.git) instead.

2. Navigate to the project directory and install the dependencies needed to run the project using your favorite package manager (e.g. poetry or uv):

   cd my-app
   
   poetry sync # or uv sync
   

3. Copy the .env.example file to .env:

   cp .env.example .env
   

4. Create the encryption key for your application:

   poetry run python ./beam encryption key generate
   # or uv run python ./beam encryption key generate
   

5. Execute the database migrations:

   poetry run python ./beam db migrate
   # or uv run python ./beam db migrate
   

6. Finally, you can start the development server via the Beam serve command:

   poetry run python ./beam serve  # or uv run python ./beam serve
   

Your application is now available at http://localhost:8000 and you are ready to start building you project. You can follow the next steps to learn more about Expanse and its concepts

What's next?

Now that you have created your first Expanse project, you can start exploring the framework by learning about its core concepts and components.

Here are some recommended next steps:

• Understand the directory structure of an Expanse project by reading the Project Structure section.
• Learn about creating routes to handle incoming requests.
• Dive into the Database section to learn about working with databases.
• Check out the Security section to understand how to secure your application.

System requirements

Poetry requires Python 3.12+. It is multi-platform and the goal is to make it work equally well on Linux, macOS and Windows.