Skip to content

Commit

Permalink
Update FastAPI integration docs (#6833) (#6850)
Browse files Browse the repository at this point in the history
## Summary

- Fixed the directory structure and commands for the second scenario
#6833
- Added a headline "Migrating an existing FastAPI project" because the
first part looks like a migration scenario, but didn't have its own
section before.
- Added explicit `--app` flags to commands to emphasize that the
commands create an Application project. Although maybe unnecessary
considering that `--app` is now default.
- Added instructions for testing that the dev server and Docker image
work correctly
- Took the liberty of adding a `project` at the root of all directory
structures and appropriate commands.
- With explicitly defined root directory it is easier to differentiate
between the `project` root directory and FastAPI's `app` directory.
- Without it it could be less obvious for developers less familiar with
FastAPI. Had a similar issue when started using Django several years
ago.
- If I left `app` in the command, then after copying the **app
directory** from https://github.com/astral-sh/uv-fastapi-example the
path would be `app/app/...`.
- Cleaned up glyphs in tree sctructures that were copied from FastAPI
docs.

## Caveats

- On project initialization `hello.py` is created. It is not reflected
in directory structure trees in this PR and may be slightly confusing
for developers less familiar with uv.
- I believe it will be soon addressed in #6750 and after that the docs
will reflect actual directory structure.
  • Loading branch information
denkasyanov authored Aug 30, 2024
1 parent 50c5fe9 commit 0ceefb3
Showing 1 changed file with 51 additions and 28 deletions.
79 changes: 51 additions & 28 deletions docs/guides/integration/fastapi.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,32 +8,36 @@ environments, running FastAPI applications, and more.

You can view the source code for this guide in the [uv-fastapi-example](https://github.com/astral-sh/uv-fastapi-example) repository.

## Migrating an existing FastAPI project

As an example, consider the sample application defined in the
[FastAPI documentation](https://fastapi.tiangolo.com/tutorial/bigger-applications/), structured as
follows:

```plaintext
.
── app
├── __init__.py
├── main.py
├── dependencies.py
── routers
│ ├── __init__.py
│ ├── items.py
│ └── users.py
└── internal
├── __init__.py
└── admin.py
project
── app
├── __init__.py
├── main.py
├── dependencies.py
── routers
│ ├── __init__.py
│ ├── items.py
│ └── users.py
└── internal
├── __init__.py
└── admin.py
```

To use uv with this project, add a `pyproject.toml` file to the root directory of the project with
`uv init`:
To use uv with this application, inside the `project` directory run:

```console
$ uv init
$ uv init --app
```

This creates an [Application project](../../concepts/projects.md#applications) with a
`pyproject.toml` file.

Then, add a dependency on FastAPI:

```console
Expand All @@ -43,19 +47,19 @@ $ uv add fastapi --extra standard
You should now have the following structure:

```plaintext
.
project
├── pyproject.toml
── app
├── __init__.py
├── main.py
├── dependencies.py
── routers
│ ├── __init__.py
│ ├── items.py
│ └── users.py
└── internal
├── __init__.py
└── admin.py
── app
├── __init__.py
├── main.py
├── dependencies.py
── routers
│ ├── __init__.py
│ ├── items.py
│ └── users.py
└── internal
├── __init__.py
└── admin.py
```

And the contents of the `pyproject.toml` file should look something like this:
Expand All @@ -82,6 +86,8 @@ $ uv run fastapi dev
alongside the `pyproject.toml`), create a virtual environment, and run the command in that
environment.

Test the app by opening http://127.0.0.1:8000/?token=jessica in a web browser.

## Deployment

To deploy the FastAPI application with Docker, you can use the following `Dockerfile`:
Expand All @@ -103,4 +109,21 @@ RUN uv sync --frozen --no-cache
CMD ["/app/.venv/bin/fastapi", "run", "app/main.py", "--port", "80", "--host", "0.0.0.0"]
```

For more on using uv with Docker, see the [Docker guide](./docker.md).
Build the Docker image with:

```console
$ docker build -t fastapi-app .
```

Run the Docker container locally with:

```console
$ docker run -p 8000:80 fastapi-app
```

Navigate to http://127.0.0.1:8000/?token=jessica in your browser to verify that the app is running
correctly.

!!! tip

For more on using uv with Docker, see the [Docker guide](./docker.md).

0 comments on commit 0ceefb3

Please sign in to comment.