Skip to content

Commit 78e3075

Browse files
tiangolotiangolo
committed
📝 Add docs for pyproject.toml with entrypoint 
1 parent 627c10a commit 78e3075

10 files changed

Lines changed: 159 additions & 54 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -213,7 +213,7 @@ Run the server with:
213213
<div class="termy">
214214

215215
```console
216-
$ fastapi dev main.py
216+
$ fastapi dev
217217

218218
╭────────── FastAPI CLI - Development mode ───────────╮
219219
│ │
@@ -238,9 +238,9 @@ INFO: Application startup complete.
238238
</div>
239239

240240
<details markdown="1">
241-
<summary>About the command <code>fastapi dev main.py</code>...</summary>
241+
<summary>About the command <code>fastapi dev</code>...</summary>
242242

243-
The command `fastapi dev` reads your `main.py` file, detects the **FastAPI** app in it, and starts a server using [Uvicorn](https://www.uvicorn.dev).
243+
The command `fastapi dev` reads your `main.py` file automatically, detects the **FastAPI** app in it, and starts a server using [Uvicorn](https://www.uvicorn.dev).
244244

245245
By default, `fastapi dev` will start with auto-reload enabled for local development.
246246

@@ -459,20 +459,6 @@ You can optionally deploy your FastAPI app to [FastAPI Cloud](https://fastapiclo
459459

460460
If you already have a **FastAPI Cloud** account (we invited you from the waiting list 😉), you can deploy your application with one command.
461461

462-
Before deploying, make sure you are logged in:
463-
464-
<div class="termy">
465-
466-
```console
467-
$ fastapi login
468-
469-
You are logged in to FastAPI Cloud 🚀
470-
```
471-
472-
</div>
473-
474-
Then deploy your app:
475-
476462
<div class="termy">
477463

478464
```console

‎docs/en/docs/advanced/sub-applications.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,12 @@ In this case, it will be mounted at the path `/subapi`:
3030

3131
### Check the automatic API docs { #check-the-automatic-api-docs }
3232

33-
Now, run the `fastapi` command with your file:
33+
Now, run the `fastapi` command:
3434

3535
<div class="termy">
3636

3737
```console
38-
$ fastapi dev main.py
38+
$ fastapi dev
3939

4040
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
4141
```

‎docs/en/docs/advanced/websockets.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -64,12 +64,12 @@ You can receive and send binary, text, and JSON data.
6464

6565
## Try it { #try-it }
6666

67-
If your file is named `main.py`, run your application with:
67+
Put your code in a file `main.py` and then run your application:
6868

6969
<div class="termy">
7070

7171
```console
72-
$ fastapi dev main.py
72+
$ fastapi dev
7373

7474
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
7575
```
@@ -121,12 +121,12 @@ You can use a closing code from the [valid codes defined in the specification](h
121121

122122
### Try the WebSockets with dependencies { #try-the-websockets-with-dependencies }
123123

124-
If your file is named `main.py`, run your application with:
124+
Run your application:
125125

126126
<div class="termy">
127127

128128
```console
129-
$ fastapi dev main.py
129+
$ fastapi dev
130130

131131
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
132132
```

‎docs/en/docs/fastapi-cli.md‎

Lines changed: 60 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
# FastAPI CLI { #fastapi-cli }
22

3-
**FastAPI CLI** is a command line program that you can use to serve your FastAPI app, manage your FastAPI project, and more.
3+
**FastAPI <abbr title="command line interface">CLI</abbr>** is a command line program that you can use to serve your FastAPI app, manage your FastAPI project, and more.
44

5-
When you install FastAPI (e.g. with `pip install "fastapi[standard]"`), it includes a package called `fastapi-cli`, this package provides the `fastapi` command in the terminal.
5+
When you install FastAPI (e.g. with `pip install "fastapi[standard]"`), it comes with a command line program you can run in the terminal.
66

77
To run your FastAPI app for development, you can use the `fastapi dev` command:
88

99
<div class="termy">
1010

1111
```console
12-
$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:solid">main.py</u>
12+
$ <font color="#4E9A06">fastapi</font> dev
1313

1414
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
1515

@@ -46,14 +46,67 @@ $ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:solid
4646

4747
</div>
4848

49-
The command line program called `fastapi` is **FastAPI CLI**.
49+
/// tip
5050

51-
FastAPI CLI takes the path to your Python program (e.g. `main.py`) and automatically detects the `FastAPI` instance (commonly named `app`), determines the correct import process, and then serves it.
51+
For production you would use `fastapi run` instead of `fastapi dev`. 🚀
5252

53-
For production you would use `fastapi run` instead. 🚀
53+
///
5454

5555
Internally, **FastAPI CLI** uses [Uvicorn](https://www.uvicorn.dev), a high-performance, production-ready, ASGI server. 😎
5656

57+
The `fastapi` CLI will try to detect automatically the FastAPI app to run, assuming it's an object called `app` in a file `main.py` (or a couple other variants).
58+
59+
But you can configure explicitly the app to use.
60+
61+
## Configure the app `entrypoint` in `pyproject.toml` { #configure-the-app-entrypoint-in-pyproject-toml }
62+
63+
You can configure where your app is located in a `pyproject.toml` file like:
64+
65+
```toml
66+
[tool.fastapi]
67+
entrypoint = "main:app"
68+
```
69+
70+
That `entrypoint` will tell the `fastapi` command that it should import the app like:
71+
72+
```python
73+
from main import app
74+
```
75+
76+
If your code was structured like:
77+
78+
```
79+
.
80+
├── backend
81+
│   ├── main.py
82+
│   ├── __init__.py
83+
```
84+
85+
Then you would set the `entrypoint` as:
86+
87+
```toml
88+
[tool.fastapi]
89+
entrypoint = "backend.main:app"
90+
```
91+
92+
which would be equivalent to:
93+
94+
```python
95+
from backend.main import app
96+
```
97+
98+
### `fastapi dev` with path { #fastapi-dev-with-path }
99+
100+
You can also pass the file path to the `fastapi dev` command, and it will guess the FastAPI app object to use:
101+
102+
```console
103+
$ fastapi dev main.py
104+
```
105+
106+
But you would have to remember to pass the correct path every time you call the `fastapi` command.
107+
108+
Additionally, other tools might not be able to find it, for example the [VS Code Extension](editor-support.md) or [FastAPI Cloud](https://fastapicloud.com), so it is recommended to use the `entrypoint` in `pyproject.toml`.
109+
57110
## `fastapi dev` { #fastapi-dev }
58111

59112
Running `fastapi dev` initiates development mode.
@@ -62,7 +115,7 @@ By default, **auto-reload** is enabled, automatically reloading the server when
62115

63116
## `fastapi run` { #fastapi-run }
64117

65-
Executing `fastapi run` starts FastAPI in production mode by default.
118+
Executing `fastapi run` starts FastAPI in production mode.
66119

67120
By default, **auto-reload** is disabled. It also listens on the IP address `0.0.0.0`, which means all the available IP addresses, this way it will be publicly accessible to anyone that can communicate with the machine. This is how you would normally run it in production, for example, in a container.
68121

‎docs/en/docs/index.md‎

Lines changed: 3 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,7 @@ Run the server with:
210210
<div class="termy">
211211

212212
```console
213-
$ fastapi dev main.py
213+
$ fastapi dev
214214

215215
╭────────── FastAPI CLI - Development mode ───────────╮
216216
│ │
@@ -235,9 +235,9 @@ INFO: Application startup complete.
235235
</div>
236236

237237
<details markdown="1">
238-
<summary>About the command <code>fastapi dev main.py</code>...</summary>
238+
<summary>About the command <code>fastapi dev</code>...</summary>
239239

240-
The command `fastapi dev` reads your `main.py` file, detects the **FastAPI** app in it, and starts a server using [Uvicorn](https://www.uvicorn.dev).
240+
The command `fastapi dev` reads your `main.py` file automatically, detects the **FastAPI** app in it, and starts a server using [Uvicorn](https://www.uvicorn.dev).
241241

242242
By default, `fastapi dev` will start with auto-reload enabled for local development.
243243

@@ -456,20 +456,6 @@ You can optionally deploy your FastAPI app to [FastAPI Cloud](https://fastapiclo
456456

457457
If you already have a **FastAPI Cloud** account (we invited you from the waiting list 😉), you can deploy your application with one command.
458458

459-
Before deploying, make sure you are logged in:
460-
461-
<div class="termy">
462-
463-
```console
464-
$ fastapi login
465-
466-
You are logged in to FastAPI Cloud 🚀
467-
```
468-
469-
</div>
470-
471-
Then deploy your app:
472-
473459
<div class="termy">
474460

475461
```console

‎docs/en/docs/tutorial/bigger-applications.md‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -465,14 +465,45 @@ As we cannot just isolate them and "mount" them independently of the rest, the *
465465

466466
///
467467

468+
## Configure the `entrypoint` in `pyproject.toml` { #configure-the-entrypoint-in-pyproject-toml }
469+
470+
As your FastAPI `app` object lives in `app/main.py`, you can configure the `entrypoint` in your `pyproject.toml` file like this:
471+
472+
```toml
473+
[tool.fastapi]
474+
entrypoint = "app.main:app"
475+
```
476+
477+
that is equivalent to importing like:
478+
479+
```python
480+
from app.main import app
481+
```
482+
483+
That way the `fastapi` command will know where to find your app.
484+
485+
/// Note
486+
487+
You could also pass the path to the command, like:
488+
489+
```console
490+
$ fastapi dev app/main.py
491+
```
492+
493+
But you would have to remember to pass the correct path every time you call the `fastapi` command.
494+
495+
Additionally, other tools might not be able to find it, for example the [VS Code Extension](../editor-support.md) or [FastAPI Cloud](https://fastapicloud.com), so it is recommended to use the `entrypoint` in `pyproject.toml`.
496+
497+
///
498+
468499
## Check the automatic API docs { #check-the-automatic-api-docs }
469500

470501
Now, run your app:
471502

472503
<div class="termy">
473504

474505
```console
475-
$ fastapi dev app/main.py
506+
$ fastapi dev
476507

477508
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
478509
```

‎docs/en/docs/tutorial/first-steps.md‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Run the live server:
1111
<div class="termy">
1212

1313
```console
14-
$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:solid">main.py</u>
14+
$ <font color="#4E9A06">fastapi</font> dev
1515

1616
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
1717

@@ -143,6 +143,55 @@ And there are dozens of alternatives, all based on OpenAPI. You could easily add
143143

144144
You could also use it to generate code automatically, for clients that communicate with your API. For example, frontend, mobile or IoT applications.
145145

146+
### Configure the app `entrypoint` in `pyproject.toml` { #configure-the-app-entrypoint-in-pyproject-toml }
147+
148+
You can configure where your app is located in a `pyproject.toml` file like:
149+
150+
```toml
151+
[tool.fastapi]
152+
entrypoint = "main:app"
153+
```
154+
155+
That `entrypoint` will tell the `fastapi` command that it should import the app like:
156+
157+
```python
158+
from main import app
159+
```
160+
161+
If your code was structured like:
162+
163+
```
164+
.
165+
├── backend
166+
│   ├── main.py
167+
│   ├── __init__.py
168+
```
169+
170+
Then you would set the `entrypoint` as:
171+
172+
```toml
173+
[tool.fastapi]
174+
entrypoint = "backend.main:app"
175+
```
176+
177+
which would be equivalent to:
178+
179+
```python
180+
from backend.main import app
181+
```
182+
183+
### `fastapi dev` with path { #fastapi-dev-with-path }
184+
185+
You can also pass the file path to the `fastapi dev` command, and it will guess the FastAPI app object to use:
186+
187+
```console
188+
$ fastapi dev main.py
189+
```
190+
191+
But you would have to remember to pass the correct path every time you call the `fastapi` command.
192+
193+
Additionally, other tools might not be able to find it, for example the [VS Code Extension](../editor-support.md) or [FastAPI Cloud](https://fastapicloud.com), so it is recommended to use the `entrypoint` in `pyproject.toml`.
194+
146195
### Deploy your app (optional) { #deploy-your-app-optional }
147196

148197
You can optionally deploy your FastAPI app to [FastAPI Cloud](https://fastapicloud.com), go and join the waiting list if you haven't. 🚀

‎docs/en/docs/tutorial/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,12 @@ It is also built to work as a future reference so you can come back and see exac
1010

1111
All the code blocks can be copied and used directly (they are actually tested Python files).
1212

13-
To run any of the examples, copy the code to a file `main.py`, and start `fastapi dev` with:
13+
To run any of the examples, copy the code to a file `main.py`, and start `fastapi dev`:
1414

1515
<div class="termy">
1616

1717
```console
18-
$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:solid">main.py</u>
18+
$ <font color="#4E9A06">fastapi</font> dev
1919

2020
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
2121

‎docs/en/docs/tutorial/security/first-steps.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ Run the example with:
4545
<div class="termy">
4646

4747
```console
48-
$ fastapi dev main.py
48+
$ fastapi dev
4949

5050
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
5151
```

‎docs/en/docs/tutorial/sql-databases.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ You can run the app:
152152
<div class="termy">
153153

154154
```console
155-
$ fastapi dev main.py
155+
$ fastapi dev
156156

157157
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
158158
```
@@ -337,7 +337,7 @@ You can run the app again:
337337
<div class="termy">
338338

339339
```console
340-
$ fastapi dev main.py
340+
$ fastapi dev
341341

342342
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
343343
```

0 commit comments

Comments
 (0)