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.

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

System requirements

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