library/docs-fastapi
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync fastapi docs from 50113da1 on 2026-09-11

Browse Source
This commit is contained in:
The Librarian
2026-09-11 04:00:08 +00:00
parent 632909b5f6
commit 818066b271
739 changed files with 4974 additions and 17395 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ko/docs/advanced/additional-responses.md
+2 -2
View File
@@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"}
응답에 정확히 무엇을 포함할 수 있는지 보려면, OpenAPI 사양의 다음 섹션을 확인하세요:
* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object): `Response Object`를 포함합니다.
* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object): `responses` 파라미터 안의 각 응답에 이것의 어떤 항목이든 직접 포함할 수 있습니다. `description`, `headers`, `content`(여기에서 서로 다른 미디어 타입과 JSON Schema를 선언합니다), `links` 등을 포함할 수 있습니다.
* [OpenAPI Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object): `Response Object`를 포함합니다.
* [OpenAPI Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object): `responses` 파라미터 안의 각 응답에 이것의 어떤 항목이든 직접 포함할 수 있습니다. `description`, `headers`, `content`(여기에서 서로 다른 미디어 타입과 JSON Schema를 선언합니다), `links` 등을 포함할 수 있습니다.
docs/ko/docs/advanced/async-tests.md
+1 -1
View File
@@ -45,7 +45,7 @@
<div class="termy">
```console
$ pytest
$ uv run pytest
---> 100%
```
docs/ko/docs/advanced/behind-a-proxy.md
+7 -7
View File
@@ -33,7 +33,7 @@ FastAPI CLI를 *CLI 옵션* `--forwarded-allow-ips`로 실행하고, 전달 헤
<div class="termy">
```console
$ fastapi run --forwarded-allow-ips="*"
$ uv run fastapi run --forwarded-allow-ips="*"
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
@@ -161,7 +161,7 @@ IP `0.0.0.0`은 보통 해당 머신/서버에서 사용 가능한 모든 IP에
}
```
이 예시에서 "Proxy"는 **Traefik** 같은 것이고, 서버는 **Uvicorn**으로 실행되는 FastAPI CLI처럼, FastAPI 애플리케이션을 실행하는 구성일 수 있습니다.
이 예시에서 "Proxy"는 **Traefik** 같은 것이고, 서버는 **Uvicorn**을 사용하는 FastAPI CLI처럼, FastAPI 애플리케이션을 실행하는 구성일 수 있습니다.
### `root_path` 제공하기 { #providing-the-root-path }
@@ -170,7 +170,7 @@ IP `0.0.0.0`은 보통 해당 머신/서버에서 사용 가능한 모든 IP에
<div class="termy">
```console
$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
@@ -200,7 +200,7 @@ ASGI 사양은 이 사용 사례를 위해 `root_path`를 정의합니다.
<div class="termy">
```console
$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
@@ -253,7 +253,7 @@ Uvicorn은 프록시가 `http://127.0.0.1:8000/app`에서 Uvicorn에 접근할
[Traefik](https://docs.traefik.io/)을 사용하면, 경로 접두사가 제거되는 구성을 로컬에서 쉽게 실험할 수 있습니다.
[Traefik 다운로드](https://github.com/containous/traefik/releases)는 단일 바이너리이며, 압축 파일을 풀고 터미널에서 바로 실행할 수 있습니다.
[Traefik 다운로드](https://github.com/traefik/traefik/releases)는 단일 바이너리이며, 압축 파일을 풀고 터미널에서 바로 실행할 수 있습니다.
그 다음 다음 내용을 가진 `traefik.toml` 파일을 생성하세요:
@@ -321,7 +321,7 @@ INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
<div class="termy">
```console
$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
@@ -394,7 +394,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1
기본적으로 **FastAPI**는 OpenAPI 스키마에서 `root_path`의 URL로 `server`를 생성합니다.
하지만 예를 들어 동일한 docs UI가 스테이징과 프로덕션 환경 모두와 상호작용하도록 하려면, 다른 대안 `servers`를 제공할 수도 있습니다.
하지만 예를 들어 *동일한* docs UI가 스테이징과 프로덕션 환경 모두와 상호작용하도록 하려면, 다른 대안 `servers`를 제공할 수도 있습니다.
사용자 정의 `servers` 리스트를 전달했고 `root_path`(API가 프록시 뒤에 있기 때문)가 있다면, **FastAPI**는 리스트의 맨 앞에 이 `root_path`를 가진 "server"를 삽입합니다.
docs/ko/docs/advanced/dataclasses.md
+2 -2
View File
@@ -6,7 +6,7 @@ FastAPI는 **Pydantic** 위에 구축되어 있으며, 지금까지는 Pydantic
{* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *}
이는 **Pydantic** 덕분에 여전히 지원되는데, Pydantic이 [`dataclasses`에 대한 내부 지원](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel)을 제공하기 때문입니다.
이는 **Pydantic** 덕분에 여전히 지원되는데, Pydantic이 [`dataclasses`에 대한 내부 지원](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel)을 제공하기 때문입니다.
따라서 위 코드처럼 Pydantic을 명시적으로 사용하지 않더라도, FastAPI는 Pydantic을 사용해 표준 dataclasses를 Pydantic의 dataclasses 변형으로 변환합니다.
@@ -88,7 +88,7 @@ dataclass는 자동으로 Pydantic dataclass로 변환됩니다.
`dataclasses`를 다른 Pydantic 모델과 조합하거나, 이를 상속하거나, 여러분의 모델에 포함하는 등의 작업도 할 수 있습니다.
자세한 내용은 [dataclasses에 관한 Pydantic 문서](https://docs.pydantic.dev/latest/concepts/dataclasses/)를 참고하세요.
자세한 내용은 [dataclasses에 관한 Pydantic 문서](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/)를 참고하세요.
## 버전 { #version }
docs/ko/docs/advanced/events.md
+1 -1
View File
@@ -154,7 +154,7 @@ async with lifespan(app):
/// note | 참고
Starlette `lifespan` 핸들러에 대해서는 [Starlette의 Lifespan 문서](https://www.starlette.dev/lifespan/)에서 더 읽어볼 수 있습니다.
Starlette `lifespan` 핸들러에 대해서는 [Starlette의 Lifespan 문서](https://starlette.dev/lifespan/)에서 더 읽어볼 수 있습니다.
또한 코드의 다른 영역에서 사용할 수 있는 lifespan 상태를 처리하는 방법도 포함되어 있습니다.
docs/ko/docs/advanced/generate-clients.md
+1 -1
View File
@@ -12,7 +12,7 @@
**TypeScript 클라이언트**의 경우 [Hey API](https://heyapi.dev/)는 TypeScript 생태계에 최적화된 경험을 제공하는 목적에 맞게 설계된 솔루션입니다.
더 많은 SDK 생성기는 [OpenAPI.Tools](https://openapi.tools/#sdk)에서 확인할 수 있습니다.
더 많은 SDK 생성기는 [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators)에서 확인할 수 있습니다.
/// tip | 팁
docs/ko/docs/advanced/middleware.md
+2 -2
View File
@@ -91,7 +91,7 @@ HTTP Host Header 공격을 방어하기 위해, 들어오는 모든 요청에
예를 들어:
* [Uvicorn의 `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py)
* [Uvicorn의 `ProxyHeadersMiddleware`](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py)
* [MessagePack](https://github.com/florimondmanca/msgpack-asgi)
사용 가능한 다른 middleware를 보려면 [Starlette의 Middleware 문서](https://www.starlette.dev/middleware/)와 [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi)를 확인하세요.
사용 가능한 다른 middleware를 보려면 [Starlette의 Middleware 문서](https://starlette.dev/middleware/)와 [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi)를 확인하세요.
docs/ko/docs/advanced/openapi-callbacks.md
+3 -3
View File
@@ -35,7 +35,7 @@
/// tip | 팁
`callback_url` 쿼리 파라미터는 Pydantic의 [Url](https://docs.pydantic.dev/latest/api/networks/) 타입을 사용합니다.
`callback_url` 쿼리 파라미터는 Pydantic의 [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/) 타입을 사용합니다.
///
@@ -106,11 +106,11 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True})
일반적인 *경로 처리*와의 주요 차이점은 2가지입니다:
* 실제 코드를 가질 필요가 없습니다. 여러분의 앱은 이 코드를 절대 호출하지 않기 때문입니다. 이는 *external API*를 문서화하는 데만 사용됩니다. 따라서 함수는 그냥 `pass`만 있어도 됩니다.
* *path*에는 [OpenAPI 3 표현식](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)(자세한 내용은 아래 참고)이 포함될 수 있으며, 이를 통해 *여러분의 API*로 보내진 원래 요청의 파라미터와 일부 값을 변수로 사용할 수 있습니다.
* *path*에는 [OpenAPI 3 표현식](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)(자세한 내용은 아래 참고)이 포함될 수 있으며, 이를 통해 *여러분의 API*로 보내진 원래 요청의 파라미터와 일부 값을 변수로 사용할 수 있습니다.
### 콜백 경로 표현식 { #the-callback-path-expression }
콜백 *path*는 *여러분의 API*로 보내진 원래 요청의 일부를 포함할 수 있는 [OpenAPI 3 표현식](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)을 가질 수 있습니다.
콜백 *path*는 *여러분의 API*로 보내진 원래 요청의 일부를 포함할 수 있는 [OpenAPI 3 표현식](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)을 가질 수 있습니다.
이 경우, 다음 `str`입니다:
docs/ko/docs/advanced/response-cookies.md
+1 -1
View File
@@ -48,4 +48,4 @@
///
사용 가능한 모든 매개변수와 옵션은 [Starlette의 문서](https://www.starlette.dev/responses/#set-cookie)에서 확인할 수 있습니다.
사용 가능한 모든 매개변수와 옵션은 [Starlette의 문서](https://starlette.dev/responses/#set-cookie)에서 확인할 수 있습니다.
docs/ko/docs/advanced/response-headers.md
+1 -2
View File
@@ -1,6 +1,5 @@
# 응답 헤더 { #response-headers }
## `Response` 매개변수 사용하기 { #use-a-response-parameter }
여러분은 *경로 처리 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다 (쿠키와 같이 사용할 수 있습니다).
@@ -39,4 +38,4 @@
커스텀 사설 헤더는 [`X-` 접두어를 사용하여](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) 추가할 수 있다는 점을 기억하세요.
하지만, 여러분이 브라우저에서 클라이언트가 볼 수 있기를 원하는 커스텀 헤더가 있는 경우, CORS 설정에 이를 추가해야 합니다([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)에서 자세히 알아보세요). [Starlette의 CORS 문서](https://www.starlette.dev/middleware/#corsmiddleware)에 문서화된 `expose_headers` 매개변수를 사용하세요.
하지만, 여러분이 브라우저에서 클라이언트가 볼 수 있기를 원하는 커스텀 헤더가 있는 경우, CORS 설정에 이를 추가해야 합니다([CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)에서 자세히 알아보세요). [Starlette의 CORS 문서](https://starlette.dev/middleware/#corsmiddleware)에 문서화된 `expose_headers` 매개변수를 사용하세요.
docs/ko/docs/advanced/settings.md
+34 -11
View File
@@ -1,15 +1,18 @@
# 설정과 환경 변수 { #settings-and-environment-variables }
많은 경우 애플리케이션에는 외부 설정이나 구성(예: secret key, 데이터베이스 자격 증명, 이메일 서비스 자격 증명 등)이 필요할 수 있습니다.
이러한 설정 대부분은 데이터베이스 URL처럼 변동 가능(변경될 수 있음)합니다. 그리고 많은 설정은 secret처럼 민감할 수 있습니다.
이 때문에 보통 애플리케이션이 읽어들이는 환경 변수로 이를 제공하는 것이 일반적입니다.
**환경 변수**(**env var**라고도 함)는 Python 코드 외부, 운영체제에 존재하는 값이며, 애플리케이션과 다른 프로그램에서 읽을 수 있습니다.
명령어를 실행할 때 해당 명령어를 위한 환경 변수를 만들 수 있습니다. 아래에서 플랫폼별 명령어를 볼 수 있습니다.
/// tip | 팁
환경 변수를 이해하려면 [환경 변수](../environment-variables.md)를 읽어보세요.
환경 변수가 어떻게 동작하는지 자세히 설명한 [환경 변수 가이드](https://tiangolo.com/guides/environment-variables/)를 읽어보세요.
///
@@ -21,16 +24,16 @@
## Pydantic `Settings` { #pydantic-settings }
다행히 Pydantic은 환경 변수에서 오는 이러한 설정을 처리할 수 있는 훌륭한 유틸리티를 [Pydantic: Settings 관리](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)로 제공합니다.
다행히 Pydantic은 환경 변수에서 오는 이러한 설정을 처리할 수 있는 훌륭한 유틸리티를 [Pydantic: Settings 관리](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/)로 제공합니다.
### `pydantic-settings` 설치하기 { #install-pydantic-settings }
먼저 [가상 환경](../virtual-environments.md)을 만들고 활성화한 다음, `pydantic-settings` 패키지를 설치하세요:
프로젝트에 `pydantic-settings` 패키지를 추가하세요:
<div class="termy">
```console
$ pip install pydantic-settings
$ uv add pydantic-settings
---> 100%
```
@@ -41,7 +44,7 @@ $ pip install pydantic-settings
<div class="termy">
```console
$ pip install "fastapi[all]"
$ uv add "fastapi[all]"
---> 100%
```
@@ -77,19 +80,39 @@ Pydantic 모델과 같은 방식으로, 타입 어노테이션(그리고 필요
다음으로 환경 변수를 통해 구성을 전달하면서 서버를 실행합니다. 예를 들어 다음처럼 `ADMIN_EMAIL`과 `APP_NAME`을 설정할 수 있습니다:
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py
$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ $Env:ADMIN_EMAIL = "deadpool@example.com"
$ $Env:APP_NAME = "ChimichangApp"
$ uv run fastapi run main.py
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
</div>
////
/// tip | 팁
하나의 명령에 여러 env var를 설정하려면 공백으로 구분하고, 모두 명령 앞에 두세요.
Bash에서 하나의 명령에 여러 env var를 설정하려면 공백으로 구분하고, 모두 명령 앞에 두세요.
///
@@ -173,11 +196,11 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p
///
Pydantic은 외부 라이브러리를 사용해 이런 유형의 파일에서 읽는 기능을 지원합니다. 자세한 내용은 [Pydantic Settings: Dotenv (.env) 지원](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support)을 참고하세요.
Pydantic은 외부 라이브러리를 사용해 이런 유형의 파일에서 읽는 기능을 지원합니다. 자세한 내용은 [Pydantic Settings: Dotenv (.env) 지원](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support)을 참고하세요.
/// tip | 팁
이를 사용하려면 `pip install python-dotenv`가 필요합니다.
이를 사용하려면 `uv add python-dotenv`로 프로젝트에 `python-dotenv`를 추가하세요.
///
@@ -198,7 +221,7 @@ APP_NAME="ChimichangApp"
/// tip | 팁
`model_config` 속성은 Pydantic 설정을 위한 것입니다. 자세한 내용은 [Pydantic: 개념: 구성](https://docs.pydantic.dev/latest/concepts/config/)을 참고하세요.
`model_config` 속성은 Pydantic 설정을 위한 것입니다. 자세한 내용은 [Pydantic: 개념: 구성](https://pydantic.dev/docs/validation/latest/concepts/config/)을 참고하세요.
///
docs/ko/docs/advanced/sub-applications.md
+5 -5
View File
@@ -1,6 +1,6 @@
# 하위 애플리케이션 - 마운트 { #sub-applications-mounts }
각각의 독립적인 OpenAPI와 문서 UI를 갖는 두 개의 독립적인 FastAPI 애플리케이션이 필요하다면, 메인 앱을 두고 하나(또는 그 이상)의 하위 애플리케이션을 "마운트"할 수 있습니다.
각각의 독립적인 OpenAPI와 문서 UI를 갖는 두 개의 독립적인 FastAPI 애플리케이션이 필요하다면, 메인 애플리케이션을 두고 하나(또는 그 이상)의 하위 애플리케이션을 "마운트"할 수 있습니다.
## **FastAPI** 애플리케이션 마운트 { #mounting-a-fastapi-application }
@@ -35,7 +35,7 @@
<div class="termy">
```console
$ fastapi dev
$ uv run fastapi dev
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
@@ -44,7 +44,7 @@ $ fastapi dev
그리고 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)에서 문서를 여세요.
메인 앱의 자동 API 문서를 보게 될 것이며, 메인 앱 자체의 _경로 처리_만 포함됩니다:
메인 애플리케이션의 자동 API 문서를 보게 될 것이며, 메인 애플리케이션 자체의 _경로 처리_만 포함됩니다:
<img src="/img/tutorial/sub-applications/image01.png">
@@ -54,7 +54,7 @@ $ fastapi dev
<img src="/img/tutorial/sub-applications/image02.png">
두 사용자 인터페이스 중 어느 것과 상호작용을 시도하더라도 올바르게 동작할 것입니다. 브라우저가 각 특정 앱 또는 하위 앱과 통신할 수 있기 때문입니다.
두 사용자 인터페이스 중 어느 것과 상호작용을 시도하더라도 올바르게 동작할 것입니다. 브라우저가 각 특정 애플리케이션 또는 하위 애플리케이션과 통신할 수 있기 때문입니다.
### 기술적 세부사항: `root_path` { #technical-details-root-path }
@@ -62,6 +62,6 @@ $ fastapi dev
이렇게 하면 하위 애플리케이션은 문서 UI를 위해 해당 경로 접두사를 사용해야 한다는 것을 알게 됩니다.
또한 하위 애플리케이션도 자체적으로 하위 앱을 마운트할 수 있으며, FastAPI가 이 모든 `root_path`를 자동으로 처리하기 때문에 모든 것이 올바르게 동작합니다.
또한 하위 애플리케이션도 자체적으로 하위 애플리케이션을 마운트할 수 있으며, FastAPI가 이 모든 `root_path`를 자동으로 처리하기 때문에 모든 것이 올바르게 동작합니다.
`root_path`와 이를 명시적으로 사용하는 방법에 대해서는 [프록시 뒤](behind-a-proxy.md) 섹션에서 더 알아볼 수 있습니다.
docs/ko/docs/advanced/templates.md
+3 -3
View File
@@ -8,12 +8,12 @@
## 의존성 설치 { #install-dependencies }
[가상 환경](../virtual-environments.md)을 생성하고, 활성화한 후 `jinja2`를 설치해야 합니다:
프로젝트에 `jinja2`를 추가합니다:
<div class="termy">
```console
$ pip install jinja2
$ uv add jinja2
---> 100%
```
@@ -123,4 +123,4 @@ Item ID: 42
## 더 많은 세부 사항 { #more-details }
템플릿 테스트를 포함한 더 많은 세부 사항은 [Starlette의 템플릿 문서](https://www.starlette.dev/templates/)를 확인하세요.
템플릿 테스트를 포함한 더 많은 세부 사항은 [Starlette의 템플릿 문서](https://starlette.dev/templates/)를 확인하세요.
docs/ko/docs/advanced/testing-events.md
+1 -1
View File
@@ -5,7 +5,7 @@
{* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *}
["공식 Starlette 문서 사이트에서 테스트에서 라이프스팬 실행하기."](https://www.starlette.dev/lifespan/#running-lifespan-in-tests)에 대한 자세한 내용을 더 읽을 수 있습니다.
["공식 Starlette 문서 사이트에서 테스트에서 라이프스팬 실행하기."](https://starlette.dev/lifespan/#running-lifespan-in-tests)에 대한 자세한 내용을 더 읽을 수 있습니다.
더 이상 권장되지 않는 `startup` 및 `shutdown` 이벤트의 경우, 다음과 같이 `TestClient`를 사용할 수 있습니다:
docs/ko/docs/advanced/testing-websockets.md
+2 -2
View File
@@ -6,8 +6,8 @@
{* ../../docs_src/app_testing/tutorial002_py310.py hl[27:31] *}
/// note
/// note | 참고
자세한 내용은 Starlette의 [WebSocket 테스트](https://www.starlette.dev/testclient/#testing-websocket-sessions) 문서를 확인하세요.
자세한 내용은 Starlette의 [WebSocket 테스트](https://starlette.dev/testclient/#testing-websocket-sessions) 문서를 확인하세요.
///
docs/ko/docs/advanced/using-request-directly.md
+2 -2
View File
@@ -15,7 +15,7 @@
## `Request` 객체에 대한 세부 사항 { #details-about-the-request-object }
**FastAPI**는 실제로 내부에 **Starlette**을 사용하며, 그 위에 여러 도구를 덧붙인 구조입니다. 따라서 여러분이 필요할 때 Starlette의 [`Request`](https://www.starlette.dev/requests/) 객체를 직접 사용할 수 있습니다.
**FastAPI**는 실제로 내부에 **Starlette**을 사용하며, 그 위에 여러 도구를 덧붙인 구조입니다. 따라서 여러분이 필요할 때 Starlette의 [`Request`](https://starlette.dev/requests/) 객체를 직접 사용할 수 있습니다.
또한 이는 `Request` 객체에서 데이터를 직접 가져오는 경우(예: 본문을 읽기) FastAPI가 해당 데이터를 검증하거나 변환하지 않으며, 문서화(OpenAPI를 통한 자동 API 사용자 인터페이스용)도 되지 않는다는 의미이기도 합니다.
@@ -45,7 +45,7 @@
## `Request` 설명서 { #request-documentation }
여러분은 [`Request` 객체에 대한 공식 Starlette 설명서 사이트](https://www.starlette.dev/requests/)에 대한 더 자세한 내용을 읽어볼 수 있습니다.
여러분은 [`Request` 객체에 대한 공식 Starlette 설명서 사이트](https://starlette.dev/requests/)에 대한 더 자세한 내용을 읽어볼 수 있습니다.
/// note | 기술 세부사항
docs/ko/docs/advanced/websockets.md
+6 -6
View File
@@ -4,12 +4,12 @@
## `websockets` 설치 { #install-websockets }
[가상 환경](../virtual-environments.md)을 생성하고 활성화한 다음, `websockets`("WebSocket" 프로토콜을 쉽게 사용할 수 있게 해주는 Python 라이브러리)를 설치하세요:
프로젝트에 `websockets`("WebSocket" 프로토콜을 쉽게 사용할 수 있게 해주는 Python 라이브러리)를 추가하세요:
<div class="termy">
```console
$ pip install websockets
$ uv add websockets
---> 100%
```
@@ -69,7 +69,7 @@ WebSocket 경로에서 메시지를 대기(`await`)하고 전송할 수 있습
<div class="termy">
```console
$ fastapi dev
$ uv run fastapi dev
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
@@ -126,7 +126,7 @@ WebSocket이기 때문에 `HTTPException`을 발생시키는 것은 적절하지
<div class="termy">
```console
$ fastapi dev
$ uv run fastapi dev
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
@@ -182,5 +182,5 @@ FastAPI와 쉽게 통합할 수 있으면서 더 견고하고 Redis, PostgreSQL
다음 옵션에 대해 더 알아보려면 Starlette의 문서를 확인하세요:
* [`WebSocket` 클래스](https://www.starlette.dev/websockets/).
* [클래스 기반 WebSocket 처리](https://www.starlette.dev/endpoints/#websocketendpoint).
* [`WebSocket` 클래스](https://starlette.dev/websockets/).
* [클래스 기반 WebSocket 처리](https://starlette.dev/endpoints/#websocketendpoint).
docs/ko/docs/advanced/wsgi.md
+1 -1
View File
@@ -8,7 +8,7 @@
/// note | 참고
이를 사용하려면 `a2wsgi`를 설치해야 합니다. 예: `pip install a2wsgi`
이를 사용하려면 프로젝트에 `a2wsgi`를 추가해야 합니다. 예: `uv add a2wsgi`
///
docs/ko/docs/alternatives.md
+6 -6
View File
@@ -125,7 +125,7 @@ def read_url():
또한 표준 기반의 사용자 인터페이스 도구를 통합하기:
* [Swagger UI](https://github.com/swagger-api/swagger-ui)
* [ReDoc](https://github.com/Rebilly/ReDoc)
* [ReDoc](https://github.com/Redocly/redoc)
이 두 가지는 꽤 대중적이고 안정적이기 때문에 선택되었습니다. 하지만 간단히 검색해보면 OpenAPI를 위한 대안 UI가 수십 가지나 있다는 것을 알 수 있습니다(**FastAPI**와 함께 사용할 수 있습니다).
@@ -237,7 +237,7 @@ serialization과 validation을 정의하는 동일한 코드로부터 OpenAPI sc
///
### [NestJS](https://nestjs.com/) (그리고 [Angular](https://angular.io/)) { #nestjs-and-angular }
### [NestJS](https://nestjs.com/) (그리고 [Angular](https://angular.dev/)) { #nestjs-and-angular }
이건 Python도 아닙니다. NestJS는 Angular에서 영감을 받은 JavaScript(TypeScript) NodeJS framework입니다.
@@ -337,7 +337,7 @@ OpenAPI나 JSON Schema 같은 표준을 기반으로 하지 않았기 때문에
/// note | 참고
Hug는 Timothy Crosley가 만들었습니다. Python 파일에서 import를 자동으로 정렬하는 훌륭한 도구인 [`isort`](https://github.com/timothycrosley/isort)의 제작자이기도 합니다.
Hug는 Timothy Crosley가 만들었습니다. Python 파일에서 import를 자동으로 정렬하는 훌륭한 도구인 [`isort`](https://github.com/PyCQA/isort)의 제작자이기도 합니다.
///
@@ -401,7 +401,7 @@ APIStar는 Tom Christie가 만들었습니다. 다음을 만든 사람과 동일
## **FastAPI**가 사용하는 것 { #used-by-fastapi }
### [Pydantic](https://docs.pydantic.dev/) { #pydantic }
### [Pydantic](https://pydantic.dev/docs/) { #pydantic }
Pydantic은 Python type hints를 기반으로 데이터 검증, serialization, 문서화(JSON Schema 사용)를 정의하는 라이브러리입니다.
@@ -417,7 +417,7 @@ Marshmallow와 비교할 수 있습니다. 다만 benchmark에서 Marshmallow보
///
### [Starlette](https://www.starlette.dev/) { #starlette }
### [Starlette](https://starlette.dev/) { #starlette }
Starlette는 경량 <dfn title="비동기 Python 웹 애플리케이션을 구축하기 위한 새로운 표준">ASGI</dfn> framework/toolkit으로, 고성능 asyncio 서비스를 만들기에 이상적입니다.
@@ -462,7 +462,7 @@ ASGI는 Django 코어 팀 멤버들이 개발 중인 새로운 "표준"입니다
///
### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn }
### [Uvicorn](https://uvicorn.dev) { #uvicorn }
Uvicorn은 uvloop과 httptools로 구축된 초고속 ASGI 서버입니다.
docs/ko/docs/deployment/docker.md
+15 -19
View File
@@ -105,36 +105,32 @@ Docker나 Kubernetes 같은 모든 컨테이너 관리 시스템에는 이러한
### 패키지 요구사항 { #package-requirements }
보통 애플리케이션의 **패키지 요구사항**을 어떤 파일에 적어 둡니다.
`uv`로 프로젝트를 관리할 때는 직접 의존성이 `pyproject.toml`에 선언되고, 정확히 해결된 버전은 `uv.lock`에 저장됩니다.
이는 주로 그 요구사항을 **설치**하는 데 사용하는 도구에 따라 달라집니다.
가장 일반적인 방법은 패키지 이름과 버전을 한 줄에 하나씩 적어 둔 `requirements.txt` 파일을 사용하는 것입니다.
버전 범위를 설정할 때는 [FastAPI 버전들에 대하여](versions.md)에서 읽은 것과 같은 아이디어를 사용하면 됩니다.
예를 들어 `requirements.txt`는 다음과 같을 수 있습니다:
```
fastapi[standard]>=0.113.0,<0.114.0
pydantic>=2.7.0,<3.0.0
```
그리고 보통 `pip`로 패키지 의존성을 설치합니다. 예를 들면:
애플리케이션에 필요한 패키지를 다음으로 추가할 수 있습니다:
<div class="termy">
```console
$ pip install -r requirements.txt
$ uv add "fastapi[standard]" pydantic
---> 100%
Successfully installed fastapi pydantic
```
</div>
/// note | 참고
패키지 의존성을 정의하고 설치하는 다른 형식과 도구도 있습니다.
아래 Dockerfile은 컨테이너 내부에서 `pip`를 사용합니다. uv 프로젝트에서 잠긴 의존성을 Dockerfile이 기대하는 `requirements.txt` 형식으로 내보낼 수 있습니다:
<div class="termy">
```console
$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt
```
</div>
생성된 `requirements.txt`는 컨테이너 빌드를 위한 내보내기 결과입니다. 의존성 관리는 계속 `uv add`로 하고, `uv.lock`이 변경될 때 다시 생성하세요.
///
@@ -372,7 +368,7 @@ Docker 컨테이너의 URL에서 확인할 수 있어야 합니다. 예를 들
또한 [http://192.168.99.100/redoc](http://192.168.99.100/redoc) 또는 [http://127.0.0.1/redoc](http://127.0.0.1/redoc)(또는 Docker 호스트를 사용해 동등하게 접근)로 이동할 수도 있습니다.
대안 자동 문서([ReDoc](https://github.com/Rebilly/ReDoc) 제공)를 볼 수 있습니다:
대안 자동 문서([ReDoc](https://github.com/Redocly/redoc) 제공)를 볼 수 있습니다:
![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)
docs/ko/docs/deployment/fastapicloud.md
+8 -8
View File
@@ -1,11 +1,11 @@
# FastAPI Cloud { #fastapi-cloud }
**한 번의 명령**으로 FastAPI 앱을 [FastAPI Cloud](https://fastapicloud.com)에 배포할 수 있습니다. 🚀
**한 번의 명령어**만으로 FastAPI 애플리케이션을 [FastAPI Cloud](https://fastapicloud.com)에 배포할 수 있습니다. 🚀
<div class="termy">
```console
$ fastapi deploy
$ uv run fastapi deploy
Deploying to FastAPI Cloud...
@@ -18,7 +18,7 @@ Deploying to FastAPI Cloud...
CLI가 FastAPI 애플리케이션을 자동으로 감지하여 클라우드에 배포합니다. 로그인되어 있지 않다면, 인증을 완료할 수 있도록 브라우저가 자동으로 열립니다.
이게 전부입니다! 이제 해당 URL에서 앱에 접근할 수 있습니다. ✨
이게 전부입니다! 이제 해당 URL에서 애플리케이션에 접근할 수 있습니다. ✨
## FastAPI Cloud 소개 { #about-fastapi-cloud }
@@ -26,9 +26,9 @@ CLI가 FastAPI 애플리케이션을 자동으로 감지하여 클라우드에
최소한의 노력으로 API를 **구축**, **배포**, **접근**하는 과정을 간소화합니다.
FastAPI로 앱을 만들 때의 동일한 **개발자 경험**을, 클라우드에 **배포**할 때도 제공합니다. 🎉
FastAPI로 애플리케이션을 만들 때의 동일한 **개발자 경험**을, 클라우드에 **배포**할 때도 제공합니다. 🎉
또한 앱을 배포할 때 보통 필요한 대부분의 것들도 처리해 줍니다. 예를 들면:
또한 애플리케이션을 배포할 때 보통 필요한 대부분의 것들도 처리해 줍니다. 예를 들면:
* HTTPS
* 요청을 기반으로 자동 스케일링하는 복제(Replication)
@@ -38,10 +38,10 @@ FastAPI Cloud는 *FastAPI and friends* 오픈 소스 프로젝트의 주요 스
## 다른 클라우드 제공업체에 배포하기 { #deploy-to-other-cloud-providers }
FastAPI는 오픈 소스이며 표준을 기반으로 합니다. 원하는 어떤 클라우드 제공업체에도 FastAPI 앱을 배포할 수 있습니다.
FastAPI는 오픈 소스이며 표준을 기반으로 합니다. 원하는 어떤 클라우드 제공업체에도 FastAPI 애플리케이션을 배포할 수 있습니다.
해당 클라우드 제공업체의 가이드를 따라 FastAPI 앱을 배포하세요. 🤓
해당 클라우드 제공업체의 가이드를 따라 FastAPI 애플리케이션을 배포하세요. 🤓
## 자체 서버에 배포하기 { #deploy-your-own-server }
또한 이 **Deployment** 가이드에서 이후에 모든 세부사항을 알려드릴 거예요. 그래서 무슨 일이 일어나고 있는지, 무엇이 필요하며, 본인의 서버를 포함해 직접 FastAPI 앱을 어떻게 배포하는지까지 이해할 수 있게 될 것입니다. 🤓
또한 이 **Deployment** 가이드에서 이후에 모든 세부사항을 알려드릴 거예요. 그래서 무슨 일이 일어나고 있는지, 무엇이 필요하며, 본인의 서버를 포함해 직접 FastAPI 애플리케이션을 어떻게 배포하는지까지 이해할 수 있게 될 것입니다. 🤓
docs/ko/docs/deployment/manually.md
+5 -5
View File
@@ -52,7 +52,7 @@ FastAPI는 <abbr title="Asynchronous Server Gateway Interface - 비동기 서버
다음을 포함해 여러 대안이 있습니다:
* [Uvicorn](https://www.uvicorn.dev/): 고성능 ASGI 서버.
* [Uvicorn](https://uvicorn.dev): 고성능 ASGI 서버.
* [Hypercorn](https://hypercorn.readthedocs.io/): HTTP/2 및 Trio 등 여러 기능과 호환되는 ASGI 서버.
* [Daphne](https://github.com/django/daphne): Django Channels를 위해 만들어진 ASGI 서버.
* [Granian](https://github.com/emmett-framework/granian): Python 애플리케이션을 위한 Rust HTTP 서버.
@@ -73,14 +73,14 @@ FastAPI를 설치하면 프로덕션 서버인 Uvicorn이 함께 설치되며, `
하지만 ASGI 서버를 수동으로 설치할 수도 있습니다.
[가상 환경](../virtual-environments.md)을 만들고 활성화한 다음, 서버 애플리케이션을 설치하세요.
프로젝트에 서버 애플리케이션을 추가하세요.
예를 들어 Uvicorn을 설치하려면:
<div class="termy">
```console
$ pip install "uvicorn[standard]"
$ uv add "uvicorn[standard]"
---> 100%
```
@@ -95,7 +95,7 @@ $ pip install "uvicorn[standard]"
여기에는 `uvloop`가 포함되며, 이는 `asyncio`를 고성능으로 대체할 수 있는 드롭인 대체재로, 큰 동시성 성능 향상을 제공합니다.
`pip install "fastapi[standard]"` 같은 방식으로 FastAPI를 설치하면 `uvicorn[standard]`도 함께 설치됩니다.
`uv add "fastapi[standard]"` 같은 방식으로 FastAPI를 추가하면 `uvicorn[standard]`도 함께 설치됩니다.
///
@@ -106,7 +106,7 @@ ASGI 서버를 수동으로 설치했다면, 보통 FastAPI 애플리케이션
<div class="termy">
```console
$ uvicorn main:app --host 0.0.0.0 --port 80
$ uv run uvicorn main:app --host 0.0.0.0 --port 80
<span style="color: green;">INFO</span>: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
```
docs/ko/docs/deployment/server-workers.md
+1 -1
View File
@@ -86,7 +86,7 @@ $ <font color="#4E9A06">fastapi</font> run --workers 4 <u style="text-decoration
<div class="termy">
```console
$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
<font color="#A6E22E">INFO</font>: Uvicorn running on <b>http://0.0.0.0:8080</b> (Press CTRL+C to quit)
<font color="#A6E22E">INFO</font>: Started parent process [<font color="#A1EFE4"><b>27365</b></font>]
<font color="#A6E22E">INFO</font>: Started server process [<font color="#A1EFE4">27368</font>]
docs/ko/docs/environment-variables.md
+5 -293
View File
@@ -1,299 +1,11 @@
# 환경 변수 { #environment-variables }
**환경 변수**(또는 **env var**라고도 합니다)는 파이썬 코드의 바깥인 운영 체제에 존재하는 값이며, 애플리케이션과 다른 프로그램에서 읽을 수 있습니다.
/// tip | 팁
FastAPI 애플리케이션은 데이터베이스 URL, 이메일 자격 증명, 비밀 키와 같은 설정에 환경 변수를 흔히 사용합니다.
만약 "환경 변수"가 무엇이고, 어떻게 사용하는지 알고 계시다면, 이 챕터를 스킵하셔도 좋습니다.
[설정 및 환경 변수](advanced/settings.md)에서 애플리케이션 설정에 환경 변수를 사용하는 방법을 배우게 됩니다.
///
## 더 알아보기 { #learn-more }
환경 변수(또는 "**env var**"라고도 합니다)는 파이썬 코드의 **바깥**인, **운영 체제**에 존재하는 변수이며, 파이썬 코드(또는 다른 프로그램에서도)에서 읽을 수 있습니다.
환경 변수는 애플리케이션 **설정**을 처리하거나, 파이썬의 **설치** 과정의 일부로 유용할 수 있습니다.
## 환경 변수를 만들고 사용하기 { #create-and-use-env-vars }
파이썬 없이도, **셸 (터미널)** 에서 환경 변수를 **생성** 하고 사용할 수 있습니다.
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
// 환경 변수 MY_NAME을 다음과 같이 생성할 수 있습니다
$ export MY_NAME="Wade Wilson"
// 그런 다음 다른 프로그램과 함께 사용할 수 있습니다. 예:
$ echo "Hello $MY_NAME"
Hello Wade Wilson
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
// 환경 변수 MY_NAME 생성
$ $Env:MY_NAME = "Wade Wilson"
// 다른 프로그램과 함께 사용하기. 예:
$ echo "Hello $Env:MY_NAME"
Hello Wade Wilson
```
</div>
////
## 파이썬에서 env var 읽기 { #read-env-vars-in-python }
파이썬 **바깥**인 터미널에서(또는 다른 어떤 방법으로든) 환경 변수를 만들고, 그런 다음 **파이썬에서 읽을 수 있습니다**.
예를 들어 다음과 같은 `main.py` 파일이 있다고 합시다:
```Python hl_lines="3"
import os
name = os.getenv("MY_NAME", "World")
print(f"Hello {name} from Python")
```
/// tip | 팁
[`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) 의 두 번째 인자는 반환할 기본값입니다.
제공하지 않으면 기본값은 `None`이며, 여기서는 사용할 기본값으로 `"World"`를 제공합니다.
///
그러면 해당 파이썬 프로그램을 다음과 같이 호출할 수 있습니다:
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
// 여기서는 아직 환경 변수를 설정하지 않습니다
$ python main.py
// 환경 변수를 설정하지 않았으므로 기본값이 사용됩니다
Hello World from Python
// 하지만 먼저 환경 변수를 생성하면
$ export MY_NAME="Wade Wilson"
// 그리고 프로그램을 다시 실행하면
$ python main.py
// 이제 환경 변수를 읽을 수 있습니다
Hello Wade Wilson from Python
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
// 여기서는 아직 환경 변수를 설정하지 않습니다
$ python main.py
// 환경 변수를 설정하지 않았으므로 기본값이 사용됩니다
Hello World from Python
// 하지만 먼저 환경 변수를 생성하면
$ $Env:MY_NAME = "Wade Wilson"
// 그리고 프로그램을 다시 실행하면
$ python main.py
// 이제 환경 변수를 읽을 수 있습니다
Hello Wade Wilson from Python
```
</div>
////
환경변수는 코드 바깥에서 설정될 수 있지만, 코드에서 읽을 수 있고, 나머지 파일과 함께 저장(`git`에 커밋)할 필요가 없으므로, 구성이나 **설정** 에 사용하는 것이 일반적입니다.
또한 **특정 프로그램 호출**에 대해서만 사용할 수 있는 환경 변수를 만들 수도 있는데, 해당 프로그램에서만 사용할 수 있고, 해당 프로그램이 실행되는 동안만 사용할 수 있습니다.
그렇게 하려면 프로그램 바로 앞, 같은 줄에 환경 변수를 만들어야 합니다:
<div class="termy">
```console
// 이 프로그램 호출을 위해 같은 줄에서 환경 변수 MY_NAME 생성
$ MY_NAME="Wade Wilson" python main.py
// 이제 환경 변수를 읽을 수 있습니다
Hello Wade Wilson from Python
// 이후에는 해당 환경 변수가 존재하지 않습니다
$ python main.py
Hello World from Python
```
</div>
/// tip | 팁
[The Twelve-Factor App: Config](https://12factor.net/config) 에서 좀 더 자세히 알아볼 수 있습니다.
///
## 타입과 검증 { #types-and-validation }
이 환경변수들은 오직 **텍스트 문자열**로만 처리할 수 있습니다. 텍스트 문자열은 파이썬 외부에 있으며 다른 프로그램 및 나머지 시스템(그리고 Linux, Windows, macOS 같은 서로 다른 운영 체제에서도)과 호환되어야 합니다.
즉, 파이썬에서 환경 변수로부터 읽은 **모든 값**은 **`str`**이 되고, 다른 타입으로의 변환이나 검증은 코드에서 수행해야 합니다.
**애플리케이션 설정**을 처리하기 위한 환경 변수 사용에 대한 자세한 내용은 [고급 사용자 가이드 - 설정 및 환경 변수](./advanced/settings.md) 에서 확인할 수 있습니다.
## `PATH` 환경 변수 { #path-environment-variable }
**`PATH`**라고 불리는, **특별한** 환경변수가 있습니다. 운영체제(Linux, macOS, Windows)에서 실행할 프로그램을 찾기위해 사용됩니다.
변수 `PATH`의 값은 Linux와 macOS에서는 콜론 `:`, Windows에서는 세미콜론 `;`으로 구분된 디렉토리로 구성된 긴 문자열입니다.
예를 들어, `PATH` 환경 변수는 다음과 같습니다:
//// tab | Linux, macOS
```plaintext
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
```
이는 시스템이 다음 디렉토리에서 프로그램을 찾아야 함을 의미합니다:
* `/usr/local/bin`
* `/usr/bin`
* `/bin`
* `/usr/sbin`
* `/sbin`
////
//// tab | Windows
```plaintext
C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32
```
이는 시스템이 다음 디렉토리에서 프로그램을 찾아야 함을 의미합니다:
* `C:\Program Files\Python312\Scripts`
* `C:\Program Files\Python312`
* `C:\Windows\System32`
////
터미널에 **명령어**를 입력하면 운영 체제는 `PATH` 환경 변수에 나열된 **각 디렉토리**에서 프로그램을 **찾습니다.**
예를 들어 터미널에 `python`을 입력하면 운영 체제는 해당 목록의 **첫 번째 디렉토리**에서 `python`이라는 프로그램을 찾습니다.
찾으면 **사용합니다**. 그렇지 않으면 **다른 디렉토리**에서 계속 찾습니다.
### 파이썬 설치와 `PATH` 업데이트 { #installing-python-and-updating-the-path }
파이썬을 설치할 때, 아마 `PATH` 환경 변수를 업데이트 할 것이냐고 물어봤을 겁니다.
//// tab | Linux, macOS
파이썬을 설치하고 그것이 `/opt/custompython/bin` 디렉토리에 있다고 가정해 보겠습니다.
`PATH` 환경 변수를 업데이트하도록 "예"라고 하면 설치 관리자가 `/opt/custompython/bin`을 `PATH` 환경 변수에 추가합니다.
다음과 같이 보일 수 있습니다:
```plaintext
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin
```
이렇게 하면 터미널에 `python`을 입력할 때, 시스템이 `/opt/custompython/bin`(마지막 디렉토리)에서 파이썬 프로그램을 찾아 사용합니다.
////
//// tab | Windows
파이썬을 설치하고 그것이 `C:\opt\custompython\bin` 디렉토리에 있다고 가정해 보겠습니다.
`PATH` 환경 변수를 업데이트하도록 "예"라고 하면 설치 관리자가 `C:\opt\custompython\bin`을 `PATH` 환경 변수에 추가합니다.
```plaintext
C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin
```
이렇게 하면 터미널에 `python`을 입력할 때, 시스템이 `C:\opt\custompython\bin`(마지막 디렉토리)에서 파이썬 프로그램을 찾아 사용합니다.
////
그래서, 다음과 같이 입력한다면:
<div class="termy">
```console
$ python
```
</div>
//// tab | Linux, macOS
시스템은 `/opt/custompython/bin`에서 `python` 프로그램을 **찾아** 실행합니다.
다음과 같이 입력하는 것과 거의 같습니다:
<div class="termy">
```console
$ /opt/custompython/bin/python
```
</div>
////
//// tab | Windows
시스템은 `C:\opt\custompython\bin\python`에서 `python` 프로그램을 **찾아** 실행합니다.
다음과 같이 입력하는 것과 거의 같습니다:
<div class="termy">
```console
$ C:\opt\custompython\bin\python
```
</div>
////
이 정보는 [가상 환경](virtual-environments.md) 에 대해 알아볼 때 유용할 것입니다.
## 결론 { #conclusion }
이 문서를 통해 **환경 변수**가 무엇이고 파이썬에서 어떻게 사용하는지 기본적으로 이해하셨을 겁니다.
또한 [환경 변수에 대한 위키피디아](https://en.wikipedia.org/wiki/Environment_variable)에서 이에 대해 자세히 알아볼 수 있습니다.
많은 경우에서, 환경 변수가 어떻게 유용하고 적용 가능한지 바로 명확하게 알 수는 없습니다. 하지만 개발할 때 다양한 시나리오에서 계속 나타나므로 이에 대해 아는 것이 좋습니다.
예를 들어, 다음 섹션인 [가상 환경](virtual-environments.md)에서 이 정보가 필요합니다.
환경 변수를 만들고 읽는 방법과 `PATH` 환경 변수가 어떻게 동작하는지까지 포함한 자세한 크로스 플랫폼 설명은 [환경 변수 가이드](https://tiangolo.com/guides/environment-variables/)를 읽어보세요.
docs/ko/docs/fastapi-cli.md
+8 -4
View File
@@ -2,7 +2,7 @@
**FastAPI <abbr title="command line interface - 명령줄 인터페이스">CLI</abbr>**는 FastAPI 애플리케이션을 서빙하고, FastAPI 프로젝트를 관리하는 등 다양한 작업에 사용할 수 있는 커맨드 라인 프로그램입니다.
FastAPI를 설치하면(예: `pip install "fastapi[standard]"`) 터미널에서 실행할 수 있는 커맨드 라인 프로그램이 함께 제공됩니다.
프로젝트에 FastAPI를 추가하면(예: `uv add "fastapi[standard]"`) 터미널에서 실행할 수 있는 명령줄 프로그램이 함께 제공됩니다.
개발용으로 FastAPI 애플리케이션을 실행하려면 `fastapi dev` 명령어를 사용할 수 있습니다:
@@ -52,7 +52,7 @@ $ <font color="#4E9A06">fastapi</font> dev
///
내부적으로 **FastAPI CLI**는 고성능의, 프로덕션에 적합한 ASGI 서버인 [Uvicorn](https://www.uvicorn.dev)을 사용합니다. 😎
내부적으로 **FastAPI CLI**는 고성능의, 프로덕션에 적합한 ASGI 서버인 [Uvicorn](https://uvicorn.dev)을 사용합니다. 😎
`fastapi` CLI는 기본적으로 실행할 FastAPI 앱을 자동으로 감지하려고 시도합니다. `main.py` 파일 안의 `app`이라는 객체(또는 몇 가지 변형)가 있다고 가정합니다.
@@ -100,13 +100,13 @@ from backend.main import app
`fastapi dev` 명령어에 파일 경로를 전달할 수도 있으며, 그러면 사용할 FastAPI 앱 객체를 추정합니다:
```console
$ fastapi dev main.py
$ uv run fastapi dev main.py
```
또는, `fastapi dev` 명령어에 `--entrypoint` 옵션을 전달할 수도 있습니다:
```console
$ fastapi dev --entrypoint main:app
$ uv run fastapi dev --entrypoint main:app
```
하지만 매번 `fastapi` 명령어를 호출할 때 올바른 경로\entrypoint를 전달하는 것을 기억해야 합니다.
@@ -119,6 +119,10 @@ $ fastapi dev --entrypoint main:app
기본적으로 **auto-reload**가 활성화되어 코드에 변경이 생기면 서버를 자동으로 다시 로드합니다. 이는 리소스를 많이 사용하며, 비활성화했을 때보다 안정성이 떨어질 수 있습니다. 개발 환경에서만 사용해야 합니다. 또한 컴퓨터가 자신과만 통신하기 위한(`localhost`) IP인 `127.0.0.1`에서 연결을 대기합니다.
앱을 임포트하기 전에 `fastapi dev`는 `FASTAPI_ENV` 환경 변수를 `development`로 설정합니다. `FASTAPI_ENV`가 이미 설정되어 있다면 기존 값이 유지됩니다. 이를 통해 앱 시작 코드는 개발에 친화적인 동작을 선택할 수 있으며, 동시에 `staging` 같은 앱별 환경을 제공할 수 있습니다.
일반적인 `FASTAPI_ENV` 값은 `development`와 `production`입니다. 현재 `fastapi run`은 `FASTAPI_ENV`를 변경하지 않으므로, 앱에서 프로덕션 모드를 감지해야 한다면 명시적으로 설정하세요.
## `fastapi run` { #fastapi-run }
`fastapi run`을 실행하면 프로덕션 모드로 FastAPI가 시작됩니다.
docs/ko/docs/help-fastapi.md
+7 -15
View File
@@ -46,20 +46,6 @@ FastAPI와 friends에 대한 소식을 공유할 때 알림을 받으려면, 개
* [**Bluesky**의 @tiangolo.com](https://bsky.app/profile/tiangolo.com)
* [**LinkedIn**의 @tiangolo](https://www.linkedin.com/in/tiangolo/).
## GitHub에서 질문으로 다른 사람 돕기 { #help-others-with-questions-in-github }
[GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered)에서 다른 사람들의 질문에 도움을 줄 수 있습니다.
많은 경우, 이미 그 질문에 대한 답을 알고 있을 수 있습니다. 🤓
많은 사람들의 질문을 도와주면, 공식 [FastAPI 전문가](fastapi-people.md#fastapi-experts)가 됩니다. 🎉
가장 중요한 점은: 친절하려고 노력하는 것입니다. 🤗
### 도움 주는 방법 { #how-to-help }
여기 있는 [도움 주는 방법 가이드](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github)를 따라 주세요.
## 질문하기 { #ask-questions }
GitHub 저장소에서 [새 질문을 생성](https://github.com/fastapi/fastapi/discussions/new?category=questions)할 수 있습니다. 예를 들면:
@@ -69,7 +55,7 @@ GitHub 저장소에서 [새 질문을 생성](https://github.com/fastapi/fastapi
## 채팅에 참여하기 { #join-the-chat }
👥 [Discord 채팅 서버](https://discord.gg/VQjSZaeJmf) 👥 에 참여해서 FastAPI 커뮤니티의 다른 사람들과 어울리세요.
👥 [Discord 채팅 서버](https://discord.com/invite/VQjSZaeJmf) 👥 에 참여해서 FastAPI 커뮤니티의 다른 사람들과 어울리세요.
/// tip | 팁
@@ -86,3 +72,9 @@ GitHub 저장소에서 [새 질문을 생성](https://github.com/fastapi/fastapi
GitHub에서는 템플릿이 올바른 질문을 작성하도록 안내하여, 더 쉽게 좋은 답변을 받거나 심지어 질문하기 전에 스스로 문제를 해결할 수 있습니다.
또한 채팅 시스템의 대화는 GitHub만큼 검색이 쉽지 않아, 대화 속에 묻히곤 합니다.
## FastAPI Cloud 사용해 보기 { #try-fastapi-cloud }
FastAPI와 friends의 주요 자금은 FastAPI 애플리케이션을 간단하고 빠르게, 단일 명령어 `fastapi deploy`로 배포할 수 있는 플랫폼인 [**FastAPI Cloud**](https://fastapicloud.com)에서 나옵니다.
FastAPI Cloud는 FastAPI를 만든 같은 팀이 구축했습니다. 사용해 보고 여러분의 프로젝트에 고려해 볼 수 있습니다.
docs/ko/docs/how-to/custom-request-and-route.md
+1 -2
View File
@@ -1,6 +1,5 @@
# 커스텀 Request 및 APIRoute 클래스 { #custom-request-and-apiroute-class }
일부 경우에는 `Request`와 `APIRoute` 클래스에서 사용되는 로직을 오버라이드하고 싶을 수 있습니다.
특히, 이는 middleware에 있는 로직의 좋은 대안이 될 수 있습니다.
@@ -67,7 +66,7 @@
그리고 이 두 가지, `scope`와 `receive`가 새로운 `Request` 인스턴스를 만드는 데 필요한 것들입니다.
`Request`에 대해 더 알아보려면 [Starlette의 Requests 문서](https://www.starlette.dev/requests/)를 확인하세요.
`Request`에 대해 더 알아보려면 [Starlette의 Requests 문서](https://starlette.dev/requests/)를 확인하세요.
///
docs/ko/docs/how-to/extending-openapi.md
+1 -1
View File
@@ -45,7 +45,7 @@
위 정보를 바탕으로, 동일한 유틸리티 함수를 사용해 OpenAPI 스키마를 생성하고 필요한 각 부분을 덮어쓸 수 있습니다.
예를 들어, [커스텀 로고를 포함하기 위한 ReDoc의 OpenAPI 확장](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo)을 추가해 보겠습니다.
예를 들어, [커스텀 로고를 포함하기 위한 ReDoc의 OpenAPI 확장](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo)을 추가해 보겠습니다.
### 일반적인 **FastAPI** { #normal-fastapi }
docs/ko/docs/how-to/graphql.md
+1 -1
View File
@@ -21,7 +21,7 @@
* [Strawberry](https://strawberry.rocks/) 🍓
* [FastAPI용 문서](https://strawberry.rocks/docs/integrations/fastapi) 제공
* [Ariadne](https://ariadnegraphql.org/)
* [FastAPI용 문서](https://ariadnegraphql.org/docs/fastapi-integration) 제공
* [FastAPI용 문서](https://ariadnegraphql.org/server/Integrations/fastapi-integration) 제공
* [Tartiflette](https://tartiflette.io/)
* ASGI 통합을 제공하기 위해 [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) 사용
* [Graphene](https://graphene-python.org/)
docs/ko/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md
+1 -1
View File
@@ -24,7 +24,7 @@ Pydantic v1을 사용하는 오래된 FastAPI 앱이 있다면, 여기서는 이
## 공식 가이드 { #official-guide }
Pydantic에는 v1에서 v2로의 공식 [마이그레이션 가이드](https://docs.pydantic.dev/latest/migration/)가 있습니다.
Pydantic에는 v1에서 v2로의 공식 [마이그레이션 가이드](https://pydantic.dev/docs/validation/latest/get-started/migration/)가 있습니다.
여기에는 무엇이 바뀌었는지, 검증이 이제 어떻게 더 정확하고 엄격해졌는지, 가능한 주의사항 등도 포함되어 있습니다.
docs/ko/docs/index.md
+19 -23
View File
@@ -110,7 +110,7 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트
</div>
<div class="fastapi-opinions__panel" id="fo-panel-uber" role="tabpanel" aria-labelledby="fo-tab-uber" tabindex="0" hidden>
<blockquote class="fastapi-opinions__quote">"우리는 <strong>FastAPI</strong> 라이브러리를 채택해 <strong>예측</strong>을 얻기 위해 쿼리할 수 있는 <strong>REST</strong> 서버를 생성했습니다." <em>[Ludwig을 위해]</em></blockquote>
<div class="fastapi-opinions__attr">— Piero Molino, Yaroslav Dudin, Sai Sumanth Miryala, <strong>Uber</strong> <a href="https://eng.uber.com/ludwig-v0-2/">(ref)</a></div>
<div class="fastapi-opinions__attr">— Piero Molino, Yaroslav Dudin, Sai Sumanth Miryala, <strong>Uber</strong> <a href="https://www.uber.com/us/en/blog/ludwig-v0-2/">(ref)</a></div>
</div>
<div class="fastapi-opinions__panel" id="fo-panel-netflix" role="tabpanel" aria-labelledby="fo-tab-netflix" tabindex="0" hidden>
<blockquote class="fastapi-opinions__quote">"<strong>Netflix</strong>는 우리의 <strong>위기 관리</strong> 오케스트레이션 프레임워크인 <strong>Dispatch</strong>의 오픈 소스 공개를 발표하게 되어 기쁩니다!" <em>[FastAPI로 빌드]</em></blockquote>
@@ -133,7 +133,7 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트
"_**FastAPI** 라이브러리를 채택하여 **예측**을 얻기 위해 쿼리를 실행할 수 있는 **REST** 서버를 생성했습니다. [Ludwig을 위해]_"
<div style="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - <strong>Uber</strong> <a href="https://eng.uber.com/ludwig-v0-2/"><small>(ref)</small></a></div>
<div style="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - <strong>Uber</strong> <a href="https://www.uber.com/us/en/blog/ludwig-v0-2/"><small>(ref)</small></a></div>
---
@@ -151,12 +151,6 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트
</div>
## FastAPI Conf { #fastapi-conf }
[**FastAPI Conf '26**](https://fastapiconf.com)은 **2026년 10월 28일**, **네덜란드 암스테르담**에서 열립니다. FastAPI에 관한 모든 것, 바로 출처에서. 🎤
<a class="fastapi-feature-banner" href="https://fastapiconf.com"><img src="https://fastapi.tiangolo.com/img/fastapi-conf.jpeg" alt="FastAPI Conf '26 - October 28, 2026 - Amsterdam, NL"></a>
## FastAPI 미니 다큐멘터리 { #fastapi-mini-documentary }
2025년 말에 공개된 [FastAPI 미니 다큐멘터리](https://www.youtube.com/watch?v=mpR8ngthqiE)가 있습니다. 온라인에서 시청할 수 있습니다:
@@ -175,17 +169,17 @@ FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트
FastAPI는 거인들의 어깨 위에 서 있습니다:
* [Starlette](https://www.starlette.dev/) — 웹 부분을 담당합니다.
* [Pydantic](https://docs.pydantic.dev/) — 데이터 부분을 담당합니다.
* [Starlette](https://starlette.dev/) — 웹 부분을 담당합니다.
* [Pydantic](https://pydantic.dev/docs/) — 데이터 부분을 담당합니다.
## 설치 { #installation }
[가상 환경](https://fastapi.tiangolo.com/ko/virtual-environments/)을 생성하고 활성화한 다음 FastAPI를 설치하세요:
먼저, [`uv`를 설치](https://docs.astral.sh/uv/getting-started/installation/)한 다음 프로젝트에 FastAPI를 추가하세요:
<div class="termy">
```console
$ pip install "fastapi[standard]"
$ uv add "fastapi[standard]"
---> 100%
```
@@ -194,6 +188,8 @@ $ pip install "fastapi[standard]"
**참고**: 모든 터미널에서 동작하도록 `"fastapi[standard]"`를 따옴표로 감싸 넣었는지 확인하세요.
`pip`를 사용하는 것을 선호한다면, 가상 환경 안에 `fastapi[standard]`를 설치하세요. 대안 단계는 [설치 가이드](tutorial/#install-fastapi)를 참고하세요.
## 예제 { #example }
### 만들기 { #create-it }
@@ -250,7 +246,7 @@ async def read_item(item_id: int, q: str | None = None):
<div class="termy">
```console
$ fastapi dev
$ uv run fastapi dev
╭────────── FastAPI CLI - Development mode ───────────╮
│ │
@@ -277,7 +273,7 @@ INFO: Application startup complete.
<details markdown="1">
<summary><code>fastapi dev</code> 명령에 관하여...</summary>
`fastapi dev` 명령은 여러분의 `main.py` 파일을 자동으로 읽고, 그 안의 **FastAPI** 앱을 감지한 다음, [Uvicorn](https://www.uvicorn.dev)을 사용해 서버를 시작합니다.
`fastapi dev` 명령은 여러분의 `main.py` 파일을 자동으로 읽고, 그 안의 **FastAPI** 앱을 감지한 다음, [Uvicorn](https://uvicorn.dev)을 사용해 서버를 시작합니다.
기본적으로 `fastapi dev`는 로컬 개발을 위해 auto-reload가 활성화된 상태로 시작됩니다.
@@ -314,7 +310,7 @@ INFO: Application startup complete.
그리고 이제 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)로 가봅시다.
다른 자동 문서를 볼 수 있습니다([ReDoc](https://github.com/Rebilly/ReDoc) 제공):
다른 자동 문서를 볼 수 있습니다([ReDoc](https://github.com/Redocly/redoc) 제공):
![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)
@@ -497,7 +493,7 @@ item: Item
<div class="termy">
```console
$ fastapi deploy
$ uv run fastapi deploy
Deploying to FastAPI Cloud...
@@ -540,7 +536,7 @@ FastAPI는 Pydantic과 Starlette에 의존합니다.
### `standard` 의존성 { #standard-dependencies }
`pip install "fastapi[standard]"`로 FastAPI를 설치하면 `standard` 그룹의 선택적 의존성이 함께 설치됩니다.
`uv add "fastapi[standard]"`로 FastAPI를 설치하면 `standard` 그룹의 선택적 의존성이 함께 설치됩니다.
Pydantic이 사용하는:
@@ -554,17 +550,17 @@ Starlette이 사용하는:
FastAPI가 사용하는:
* [`uvicorn`](https://www.uvicorn.dev) - 애플리케이션을 로드하고 제공하는 서버를 위한 것입니다. 여기에는 고성능 서빙에 필요한 일부 의존성(예: `uvloop`)이 포함된 `uvicorn[standard]`가 포함됩니다.
* [`uvicorn`](https://uvicorn.dev) - 애플리케이션을 로드하고 제공하는 서버를 위한 것입니다. 여기에는 고성능 서빙에 필요한 일부 의존성(예: `uvloop`)이 포함된 `uvicorn[standard]`가 포함됩니다.
* `fastapi-cli[standard]` - `fastapi` 명령을 제공하기 위한 것입니다.
* 여기에는 [FastAPI Cloud](https://fastapicloud.com)에 FastAPI 애플리케이션을 배포할 수 있게 해주는 `fastapi-cloud-cli`가 포함됩니다.
### `standard` 의존성 없이 { #without-standard-dependencies }
`standard` 선택적 의존성을 포함하고 싶지 않다면, `pip install "fastapi[standard]"` 대신 `pip install fastapi`로 설치할 수 있습니다.
`standard` 선택적 의존성을 포함하고 싶지 않다면, `uv add "fastapi[standard]"` 대신 `uv add fastapi`로 설치할 수 있습니다.
### `fastapi-cloud-cli` 없이 { #without-fastapi-cloud-cli }
표준 의존성과 함께 FastAPI를 설치하되 `fastapi-cloud-cli` 없이 설치하고 싶다면, `pip install "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다.
표준 의존성과 함께 FastAPI를 설치하되 `fastapi-cloud-cli` 없이 설치하고 싶다면, `uv add "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다.
### 추가 선택적 의존성 { #additional-optional-dependencies }
@@ -572,13 +568,13 @@ FastAPI가 사용하는:
추가 선택적 Pydantic 의존성:
* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - 설정 관리를 위한 것입니다.
* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - Pydantic에서 사용할 추가 타입을 위한 것입니다.
* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - 설정 관리를 위한 것입니다.
* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - Pydantic에서 사용할 추가 타입을 위한 것입니다.
추가 선택적 FastAPI 의존성:
* [`orjson`](https://github.com/ijl/orjson) - `ORJSONResponse`를 사용하려면 필요.
* [`ujson`](https://github.com/esnme/ultrajson) - `UJSONResponse`를 사용하려면 필요.
* [`ujson`](https://github.com/ultrajson/ultrajson) - `UJSONResponse`를 사용하려면 필요.
## 라이센스 { #license }
docs/ko/docs/project-generation.md
+9 -10
View File
@@ -1,24 +1,23 @@
# Full Stack FastAPI 템플릿 { #full-stack-fastapi-template }
템플릿은 일반적으로 특정 설정과 함께 제공되지만, 유연하고 커스터마이징이 가능하게 디자인 되었습니다. 이 특성들은 여러분이 프로젝트의 요구사항에 맞춰 수정, 적용을 할 수 있게 해주고, 템플릿이 완벽한 시작점이 되게 해줍니다. 🏁
많은 초기 설정, 보안, 데이터베이스 및 일부 API 엔드포인트가 이미 준비되어 있으므로, 여러분은 이 템플릿을 시작하는 데 사용할 수 있습니다.
GitHub 저장소: [Full Stack FastAPI 템플릿](https://github.com/tiangolo/full-stack-fastapi-template)
GitHub 저장소: [Full Stack FastAPI 템플릿](https://github.com/fastapi/full-stack-fastapi-template)
## Full Stack FastAPI 템플릿 - 기술 스택과 기능들 { #full-stack-fastapi-template-technology-stack-and-features }
- ⚡ Python 백엔드 API를 위한 [**FastAPI**](https://fastapi.tiangolo.com/ko).
- 🧰 Python SQL 데이터베이스 상호작용을 위한 [SQLModel](https://sqlmodel.tiangolo.com) (ORM).
- 🔍 FastAPI에 의해 사용되는, 데이터 검증과 설정 관리를 위한 [Pydantic](https://docs.pydantic.dev).
- 💾 SQL 데이터베이스로서의 [PostgreSQL](https://www.postgresql.org).
- 🧰 Python SQL 데이터베이스 상호작용을 위한 [SQLModel](https://sqlmodel.tiangolo.com) (ORM).
- 🔍 FastAPI에 의해 사용되는, 데이터 검증과 설정 관리를 위한 [Pydantic](https://pydantic.dev/docs/).
- 💾 SQL 데이터베이스로서의 [PostgreSQL](https://www.postgresql.org).
- 🚀 프론트엔드를 위한 [React](https://react.dev).
- 💃 TypeScript, hooks, Vite 및 기타 현대적인 프론트엔드 스택을 사용.
- 🎨 프론트엔드 컴포넌트를 위한 [Tailwind CSS](https://tailwindcss.com) 및 [shadcn/ui](https://ui.shadcn.com).
- 🤖 자동으로 생성된 프론트엔드 클라이언트.
- 🧪 End-to-End 테스트를 위한 [Playwright](https://playwright.dev).
- 🦇 다크 모드 지원.
- 💃 TypeScript, hooks, Vite 및 기타 현대적인 프론트엔드 스택을 사용.
- 🎨 프론트엔드 컴포넌트를 위한 [Tailwind CSS](https://tailwindcss.com) 및 [shadcn/ui](https://ui.shadcn.com).
- 🤖 자동으로 생성된 프론트엔드 클라이언트.
- 🧪 End-to-End 테스트를 위한 [Playwright](https://playwright.dev).
- 🦇 다크 모드 지원.
- 🐋 개발 환경과 프로덕션(운영)을 위한 [Docker Compose](https://www.docker.com).
- 🔒 기본으로 지원되는 안전한 비밀번호 해싱.
- 🔑 JWT (JSON Web Token) 인증.
docs/ko/docs/python-types.md
+2 -2
View File
@@ -271,7 +271,7 @@ def some_function(data: Any):
## Pydantic 모델 { #pydantic-models }
[Pydantic](https://docs.pydantic.dev/)은 데이터 검증을 수행하는 파이썬 라이브러리입니다.
[Pydantic](https://pydantic.dev/docs/)은 데이터 검증을 수행하는 파이썬 라이브러리입니다.
속성을 가진 클래스 형태로 데이터의 "모양(shape)"을 선언합니다.
@@ -287,7 +287,7 @@ Pydantic 공식 문서의 예시:
/// note | 참고
더 알아보려면 [Pydantic 문서를 확인하세요](https://docs.pydantic.dev/).
더 알아보려면 [Pydantic 문서를 확인하세요](https://pydantic.dev/docs/).
///
docs/ko/docs/tutorial/background-tasks.md
+3 -3
View File
@@ -1,6 +1,6 @@
# 백그라운드 작업 { #background-tasks }
FastAPI에서는 응답을 반환한 *후에* 실행할 백그라운드 작업을 정의할 수 있습니다.
응답을 반환한 *후에* 실행할 백그라운드 작업을 정의할 수 있습니다.
백그라운드 작업은 요청 후에 발생해야 하지만, 클라이언트가 응답을 받기 전에 작업이 완료될 때까지 기다릴 필요가 없는 작업에 유용합니다.
@@ -63,7 +63,7 @@ FastAPI에서는 응답을 반환한 *후에* 실행할 백그라운드 작업
## 기술적 세부사항 { #technical-details }
`BackgroundTasks` 클래스는 [`starlette.background`](https://www.starlette.dev/background/)에서 직접 가져옵니다.
`BackgroundTasks` 클래스는 [`starlette.background`](https://starlette.dev/background/)에서 직접 가져옵니다.
FastAPI에 직접 임포트/포함되어 있으므로 `fastapi`에서 임포트할 수 있고, 실수로 `starlette.background`에서 대안인 `BackgroundTask`(끝에 `s`가 없음)를 임포트하는 것을 피할 수 있습니다.
@@ -71,7 +71,7 @@ FastAPI에 직접 임포트/포함되어 있으므로 `fastapi`에서 임포트
FastAPI에서 `BackgroundTask`만 단독으로 사용하는 것도 가능하지만, 코드에서 객체를 생성하고 이를 포함하는 Starlette `Response`를 반환해야 합니다.
더 자세한 내용은 [Starlette의 Background Tasks 공식 문서](https://www.starlette.dev/background/)에서 확인할 수 있습니다.
더 자세한 내용은 [Starlette의 Background Tasks 공식 문서](https://starlette.dev/background/)에서 확인할 수 있습니다.
## 주의사항 { #caveat }
docs/ko/docs/tutorial/bigger-applications.md
+13 -13
View File
@@ -58,17 +58,17 @@ from app.routers import items
```bash
.
├── app # 'app'은 Python 패키지입니다
│   ├── __init__.py # 이 파일로 'app'이 'Python 패키지'가 됩니다
│   ├── main.py # 'main' 모듈, 예: import app.main
│   ├── dependencies.py # 'dependencies' 모듈, 예: import app.dependencies
│   └── routers # 'routers'는 'Python 하위 패키지'입니다
│   │ ├── __init__.py # 이 파일로 'routers'가 'Python 하위 패키지'가 됩니다
│   │ ├── items.py # 'items' 서브모듈, 예: import app.routers.items
│   │ └── users.py # 'users' 서브모듈, 예: import app.routers.users
│   └── internal # 'internal'은 'Python 하위 패키지'입니다
│   ├── __init__.py # 이 파일로 'internal'이 'Python 하위 패키지'가 됩니다
│   └── admin.py # 'admin' 서브모듈, 예: import app.internal.admin
├── app # "app"은 Python 패키지입니다
│   ├── __init__.py # 이 파일로 "app"이 "Python 패키지"가 됩니다
│   ├── main.py # "main" 모듈, 예: import app.main
│   ├── dependencies.py # "dependencies" 모듈, 예: import app.dependencies
│   └── routers # "routers"는 "Python 하위 패키지"입니다
│   │ ├── __init__.py # 이 파일로 "routers"가 "Python 하위 패키지"가 됩니다
│   │ ├── items.py # "items" 서브모듈, 예: import app.routers.items
│   │ └── users.py # "users" 서브모듈, 예: import app.routers.users
│   └── internal # "internal"은 "Python 하위 패키지"입니다
│   ├── __init__.py # 이 파일로 "internal"이 "Python 하위 패키지"가 됩니다
│   └── admin.py # "admin" 서브모듈, 예: import app.internal.admin
```
## `APIRouter` { #apirouter }
@@ -487,7 +487,7 @@ from app.main import app
명령어에 경로를 직접 전달할 수도 있습니다:
```console
$ fastapi dev app/main.py
$ uv run fastapi dev app/main.py
```
하지만 `fastapi` 명령어를 실행할 때마다 올바른 경로를 기억해 전달해야 합니다.
@@ -503,7 +503,7 @@ $ fastapi dev app/main.py
<div class="termy">
```console
$ fastapi dev
$ uv run fastapi dev
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
docs/ko/docs/tutorial/body-nested-models.md
+1 -1
View File
@@ -96,7 +96,7 @@ Pydantic 모델의 각 어트리뷰트는 타입을 갖습니다.
`str`, `int`, `float` 등과 같은 일반적인 단일 타입과는 별개로, `str`을 상속하는 더 복잡한 단일 타입을 사용할 수 있습니다.
사용할 수 있는 모든 옵션을 보려면 [Pydantic의 Type Overview](https://docs.pydantic.dev/latest/concepts/types/)를 확인하세요. 다음 장에서 몇 가지 예제를 볼 수 있습니다.
사용할 수 있는 모든 옵션을 보려면 [Pydantic의 Type Overview](https://pydantic.dev/docs/validation/latest/concepts/types/)를 확인하세요. 다음 장에서 몇 가지 예제를 볼 수 있습니다.
예를 들어 `Image` 모델에는 `url` 필드가 있으므로, 이를 `str` 대신 Pydantic의 `HttpUrl` 인스턴스로 선언할 수 있습니다:
docs/ko/docs/tutorial/body.md
+1 -1
View File
@@ -6,7 +6,7 @@
여러분의 API는 대부분의 경우 **응답** 본문을 보내야 합니다. 하지만 클라이언트는 항상 **요청 본문**을 보낼 필요는 없고, 때로는 (쿼리 매개변수와 함께) 어떤 경로만 요청하고 본문은 보내지 않을 수도 있습니다.
**요청** 본문을 선언하기 위해서 모든 강력함과 이점을 갖춘 [Pydantic](https://docs.pydantic.dev/) 모델을 사용합니다.
**요청** 본문을 선언하기 위해서 모든 강력함과 이점을 갖춘 [Pydantic](https://pydantic.dev/docs/) 모델을 사용합니다.
/// note | 참고
docs/ko/docs/tutorial/debugging.md
+2 -2
View File
@@ -15,7 +15,7 @@ FastAPI 애플리케이션에서 `uvicorn`을 직접 임포트하여 실행합
<div class="termy">
```console
$ python myapp.py
$ uv run python myapp.py
```
</div>
@@ -35,7 +35,7 @@ from myapp import app
<div class="termy">
```console
$ python myapp.py
$ uv run python myapp.py
```
</div>
docs/ko/docs/tutorial/extra-data-types.md
+2 -3
View File
@@ -1,6 +1,5 @@
# 추가 데이터 자료형 { #extra-data-types }
지금까지 일반적인 데이터 자료형을 사용했습니다. 예를 들면 다음과 같습니다:
* `int`
@@ -37,7 +36,7 @@
* `datetime.timedelta`:
* 파이썬의 `datetime.timedelta`.
* 요청과 응답에서 전체 초(seconds)의 `float`로 표현됩니다.
* Pydantic은 "ISO 8601 time diff encoding"으로 표현하는 것 또한 허용합니다. [더 많은 정보는 문서를 확인하세요](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers).
* Pydantic은 "ISO 8601 time diff encoding"으로 표현하는 것 또한 허용합니다. [더 많은 정보는 문서를 확인하세요](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers).
* `frozenset`:
* 요청과 응답에서 `set`와 동일하게 취급됩니다:
* 요청 시, 리스트를 읽어 중복을 제거하고 `set`로 변환합니다.
@@ -50,7 +49,7 @@
* `Decimal`:
* 표준 파이썬의 `Decimal`.
* 요청과 응답에서 `float`와 동일하게 다뤄집니다.
* 여기에서 모든 유효한 Pydantic 데이터 자료형을 확인할 수 있습니다: [Pydantic 데이터 자료형](https://docs.pydantic.dev/latest/usage/types/types/).
* 여기에서 모든 유효한 Pydantic 데이터 자료형을 확인할 수 있습니다: [Pydantic 데이터 자료형](https://pydantic.dev/docs/validation/latest/concepts/types/).
## 예시 { #example }
docs/ko/docs/tutorial/extra-models.md
+1 -1
View File
@@ -166,7 +166,7 @@ OpenAPI에서는 이를 `anyOf`로 정의합니다.
/// note | 참고
[`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions)을 정의할 때는 더 구체적인 타입을 먼저 포함하고, 덜 구체적인 타입을 그 뒤에 나열해야 합니다. 아래 예제에서는 `Union[PlaneItem, CarItem]`에서 더 구체적인 `PlaneItem`이 `CarItem`보다 앞에 위치합니다.
[`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/)을 정의할 때는 더 구체적인 타입을 먼저 포함하고, 덜 구체적인 타입을 그 뒤에 나열해야 합니다. 아래 예제에서는 `Union[PlaneItem, CarItem]`에서 더 구체적인 `PlaneItem`이 `CarItem`보다 앞에 위치합니다.
///
docs/ko/docs/tutorial/first-steps.md
+12 -6
View File
@@ -6,12 +6,18 @@
위 코드를 `main.py`에 복사합니다.
/// tip | 팁
FastAPI에는 VS Code(및 Cursor)를 위한 [공식 확장](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)이 있으며, 에디터에서 바로 경로 처리 탐색기, 경로 처리 검색, 테스트에서의 CodeLens 탐색(테스트에서 정의로 이동), FastAPI Cloud 배포와 로그를 포함한 많은 기능을 제공합니다.
///
라이브 서버를 실행합니다:
<div class="termy">
```console
$ <font color="#4E9A06">fastapi</font> dev
$ <font color="#4E9A06">uv run fastapi</font> dev
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
@@ -78,7 +84,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
그리고 이제, [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)로 가봅니다.
대안 자동 문서를 볼 수 있습니다 ([ReDoc](https://github.com/Rebilly/ReDoc) 제공):
대안 자동 문서를 볼 수 있습니다 ([ReDoc](https://github.com/Redocly/redoc) 제공):
![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)
@@ -185,13 +191,13 @@ from backend.main import app
`fastapi dev` 명령어에 파일 경로를 전달할 수도 있으며, 그러면 사용할 FastAPI 애플리케이션 객체를 추정합니다:
```console
$ fastapi dev main.py
$ uv run fastapi dev main.py
```
또는 `fastapi dev` 명령어에 `--entrypoint` 옵션을 전달할 수도 있습니다:
```console
$ fastapi dev --entrypoint main:app
$ uv run fastapi dev --entrypoint main:app
```
하지만 매번 `fastapi` 명령어를 호출할 때마다 올바른 path\entrypoint를 전달해야 합니다.
@@ -205,7 +211,7 @@ $ fastapi dev --entrypoint main:app
<div class="termy">
```console
$ fastapi deploy
$ uv run fastapi deploy
Deploying to FastAPI Cloud...
@@ -232,7 +238,7 @@ CLI가 여러분의 FastAPI 애플리케이션을 자동으로 감지하고 클
`FastAPI`는 `Starlette`를 직접 상속하는 클래스입니다.
`FastAPI`로 [Starlette](https://www.starlette.dev/)의 모든 기능을 사용할 수 있습니다.
`FastAPI`로 [Starlette](https://starlette.dev/)의 모든 기능을 사용할 수 있습니다.
///
docs/ko/docs/tutorial/frontend.md
+9 -3
View File
@@ -52,7 +52,7 @@ npm run build
{* ../../docs_src/frontend/tutorial002_py310.py hl[5] *}
**FastAPI**는 브라우저 탐색처럼 보이는 `GET` 및 `HEAD` 요청에만 이 fallback을 사용합니다. JavaScript, CSS, 이미지처럼 누락된 파일은 여전히 `404`를 반환합니다.
**FastAPI**는 브라우저 탐색 요청이 보통 그러하듯 `Accept: text/html` 또는 `Accept: application/xhtml+xml`로 HTML을 명시적으로 허용하는 `GET` 및 `HEAD` 요청에만 이 fallback을 사용합니다. JavaScript, CSS, 이미지처럼 누락된 파일은 여전히 `404`를 반환합니다.
`POST`나 `PUT` 같은 다른 메서드의 요청이 프론트엔드 fallback에만 매칭되는 경로로 들어와도 `404`를 반환합니다. 일반 **FastAPI** *경로 처리*는 여전히 프론트엔드 라우트보다 높은 우선순위를 가집니다.
@@ -106,9 +106,13 @@ npm run build
## 디렉터리 확인하기 { #check-directory }
기본적으로 `app.frontend()`는 애플리케이션이 생성될 때 디렉터리가 존재하는지 확인합니다.
기본적으로 `app.frontend()`는 `check_dir="auto"`를 사용합니다.
이는 설정 오류를 일찍 발견하는 데 도움이 됩니다. 예를 들어 프론트엔드 빌드 출력 디렉터리가 없다면 **FastAPI**는 시작 시 오류를 발생시킵니다.
`FASTAPI_ENV` 환경 변수가 `development`로 설정되어 있으면, 프론트엔드 빌드 출력 디렉터리가 없을 때 **FastAPI**는 경고만 표시합니다. [`fastapi dev` 명령어](https://github.com/fastapi/fastapi-cli#fastapi-dev)는 이 환경 변수가 아직 설정되어 있지 않다면 대신 설정해 줍니다. 이를 통해 개발 중에 프론트엔드를 빌드하거나 시작하기 전에 백엔드를 시작할 수 있습니다.
다른 모든 환경에서는 애플리케이션이 생성될 때 **FastAPI**가 오류를 발생시킵니다. 이는 프론트엔드 파일 없이 애플리케이션을 배포하기 전에 설정 오류를 일찍 발견하는 데 도움이 됩니다.
애플리케이션이 생성될 때 항상 디렉터리를 확인하도록 `check_dir=True`를 설정할 수도 있습니다.
프론트엔드 파일이 나중에 생성된다면, 예를 들어 애플리케이션 객체가 생성된 후 별도의 빌드 단계에서 생성된다면, `check_dir=False`를 설정합니다:
@@ -132,6 +136,8 @@ npm run build
애플리케이션, `APIRouter`, `include_router()`의 의존성도 프론트엔드 응답에 적용됩니다. 이는 쿠키 인증 등으로 프론트엔드를 보호하는 데 유용할 수 있습니다.
의존성은 일반 *경로 처리*에서처럼 응답 헤더를 수정하고 백그라운드 작업을 추가할 수도 있습니다.
## 정적 빌드 출력만 사용하기 { #static-build-output-only }
`app.frontend()`는 프론트엔드 빌드에서 이미 생성된 파일을 제공합니다.
docs/ko/docs/tutorial/handling-errors.md
+1 -1
View File
@@ -82,7 +82,7 @@ HTTP 오류에 커스텀 헤더를 추가할 수 있으면 유용한 상황이
## 커스텀 예외 핸들러 설치하기 { #install-custom-exception-handlers }
[Starlette의 동일한 예외 유틸리티](https://www.starlette.dev/exceptions/)를 사용해 커스텀 예외 핸들러를 추가할 수 있습니다.
[Starlette의 동일한 예외 유틸리티](https://starlette.dev/exceptions/)를 사용해 커스텀 예외 핸들러를 추가할 수 있습니다.
여러분(또는 사용하는 라이브러리)이 `raise`할 수 있는 커스텀 예외 `UnicornException`이 있다고 가정해 봅시다.
docs/ko/docs/tutorial/index.md
+55 -16
View File
@@ -1,6 +1,5 @@
# 자습서 - 사용자 안내서 { #tutorial-user-guide }
이 자습서는 **FastAPI**의 대부분의 기능을 단계별로 사용하는 방법을 보여줍니다.
각 섹션은 이전 섹션을 바탕으로 점진적으로 구성되지만, 주제를 분리한 구조로 되어 있어 특정 API 요구사항을 해결하기 위해 원하는 섹션으로 바로 이동할 수 있습니다.
@@ -11,12 +10,12 @@
모든 코드 블록은 복사해서 바로 사용할 수 있습니다(실제로 테스트된 Python 파일입니다).
예제 중 어떤 것이든 실행하려면, 코드를 `main.py` 파일에 복사하고 다음으로 `fastapi dev`를 시작하세요:
예제 중 어떤 것이든 실행하려면, 코드를 `main.py` 파일에 복사하고 `uv run`으로 `fastapi dev`를 시작하세요:
<div class="termy">
```console
$ <font color="#4E9A06">fastapi</font> dev
$ <font color="#4E9A06">uv run fastapi</font> dev
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
@@ -61,35 +60,75 @@ $ <font color="#4E9A06">fastapi</font> dev
## FastAPI 설치 { #install-fastapi }
첫 단계는 FastAPI를 설치하는 것입니다.
첫 단계는 프로젝트를 설정하고 FastAPI를 추가하는 것입니다.
[가상 환경](../virtual-environments.md)을 생성하고 활성화한 다음, **FastAPI를 설치**하세요:
[`uv`](https://docs.astral.sh/uv/getting-started/installation/)를 설치한 다음, 프로젝트를 생성하고 FastAPI를 추가하세요:
<div class="termy">
```console
$ pip install "fastapi[standard]"
$ uv init awesome-project --bare
$ cd awesome-project
$ uv add "fastapi[standard]"
---> 100%
```
</div>
`uv add`는 프로젝트의 가상 환경을 `.venv`에 생성하고, FastAPI를 `pyproject.toml`에 추가하며, 나중에 동일한 패키지 버전을 설치할 수 있도록 `uv.lock`을 생성합니다.
/// details | 이 명령어들이 하는 일
* `uv init`: 새 Python 프로젝트를 생성합니다.
* `awesome-project`: 이 이름의 새 디렉터리에 프로젝트를 생성합니다.
* `--bare`: 샘플 `main.py`, `README.md` 또는 다른 파일을 생성하지 않고, 최소한의 `pyproject.toml` 파일만 생성합니다. 이 자습서의 다음 단계에서 애플리케이션 파일을 직접 생성하게 됩니다.
그런 다음 `cd awesome-project`는 FastAPI를 추가하기 전에 새 프로젝트 디렉터리로 들어갑니다.
`uv`는 시스템에 이미 설치된 호환되는 Python 버전을 사용하거나, 필요한 경우 다운로드합니다.
`uv add`를 실행하면 FastAPI와 FastAPI가 의존하는 모든 패키지의 호환되는 버전을 선택합니다. 정확한 버전을 `uv.lock`에 기록하여, 나중에 다른 컴퓨터에서나 애플리케이션을 배포할 때 동일한 패키지 버전을 설치할 수 있게 합니다.
이 파일을 생성하거나 업데이트하는 것을 프로젝트 의존성 [**locking**](https://docs.astral.sh/uv/concepts/projects/sync/)이라고 합니다. `uv`는 패키지를 추가할 때 이 작업을 자동으로 수행합니다.
///
/// details | FastAPI 설치 옵션
`uv add "fastapi[standard]"`로 설치하면 `fastapi-cloud-cli`를 포함한 몇 가지 기본 선택적 standard 의존성이 함께 설치되며, 이를 사용해 [FastAPI Cloud](https://fastapicloud.com)에 배포할 수 있습니다.
이러한 선택적 의존성이 필요 없다면 `uv add fastapi`로 대신 설치할 수 있습니다.
standard 의존성은 설치하되 `fastapi-cloud-cli` 없이 설치하려면 `uv add "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다.
///
/// details | 대신 `pip` 사용하기
가상 환경과 패키지를 수동으로 관리하는 것을 선호한다면, 가상 환경을 생성하고 활성화한 다음 `pip install "fastapi[standard]"`로 FastAPI를 설치하세요.
자세한 단계는 [가상 환경 안내서](https://tiangolo.com/guides/virtual-environments/)를 읽어보세요.
///
## AI Agent Skills { #ai-agent-skills }
FastAPI에는 AI coding agent를 위한 공식 skill이 포함되어 있습니다. 패키지에 함께 포함되어 있으므로, 그 안내는 프로젝트에 설치된 FastAPI 버전과 계속 일치하며 FastAPI를 업데이트할 때 함께 업데이트됩니다.
프로젝트에 FastAPI를 설치한 뒤에는 <a href="https://library-skills.io">Library Skills</a>로 skill을 설치할 수 있습니다:
```bash
uvx library-skills
```
/// note | 참고
`pip install "fastapi[standard]"`로 설치하면 `fastapi-cloud-cli`를 포함한 몇 가지 기본 선택적 standard 의존성이 함께 설치되며, 이를 사용해 [FastAPI Cloud](https://fastapicloud.com)에 배포할 수 있습니다.
이러한 선택적 의존성이 필요 없다면 `pip install fastapi`로 대신 설치할 수 있습니다.
standard 의존성은 설치하되 `fastapi-cloud-cli` 없이 설치하려면 `pip install "fastapi[standard-no-fastapi-cloud-cli]"`로 설치할 수 있습니다.
`uvx`는 `uv tool run`의 alias입니다. Library Skills가 프로젝트에 설치된 패키지를 스캔하는 동안, 임시로 격리된 환경에서 Library Skills를 실행합니다.
///
/// tip | 팁
FastAPI는 VS Code(및 Cursor)용 [공식 확장 프로그램](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)이 있습니다. 경로 처리 탐색기, 경로 처리 검색, 테스트에서의 CodeLens 탐색(테스트에서 정의로 바로 이동), FastAPI Cloud 배포와 로그 등 많은 기능을 에디터에서 바로 제공합니다.
///
이 skill은 Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Pi, OpenCode 및 대부분의 다른 coding agent와 호환됩니다. Claude Code의 경우 skill을 설치할 위치를 묻는 메시지가 표시되면 `.claude/skills`를 선택하세요.
## 고급 사용자 안내서 { #advanced-user-guide }
docs/ko/docs/tutorial/middleware.md
+1 -1
View File
@@ -37,7 +37,7 @@
사용자 정의 독점 헤더는 [`X-` 접두사를 사용](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)하여 추가할 수 있다는 점을 기억하세요.
하지만 브라우저에서 클라이언트가 볼 수 있게 하려는 사용자 정의 헤더가 있다면, [CORS (Cross-Origin Resource Sharing)](cors.md) 설정에 [Starlette의 CORS 문서](https://www.starlette.dev/middleware/#corsmiddleware)에 문서화된 `expose_headers` 매개변수를 사용해 추가해야 합니다.
하지만 브라우저에서 클라이언트가 볼 수 있게 하려는 사용자 정의 헤더가 있다면, [CORS (Cross-Origin Resource Sharing)](cors.md) 설정에 [Starlette의 CORS 문서](https://starlette.dev/middleware/#corsmiddleware)에 문서화된 `expose_headers` 매개변수를 사용해 추가해야 합니다.
///
docs/ko/docs/tutorial/path-params.md
+2 -2
View File
@@ -92,7 +92,7 @@
## 표준 기반의 이점, 대체 문서 { #standards-based-benefits-alternative-documentation }
그리고 생성된 스키마는 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) 표준에서 나온 것이기 때문에 호환되는 도구가 많이 있습니다.
그리고 생성된 스키마는 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) 표준에서 나온 것이기 때문에 호환되는 도구가 많이 있습니다.
이 덕분에 **FastAPI** 자체에서 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)로 접속할 수 있는 (ReDoc을 사용하는) 대체 API 문서를 제공합니다:
@@ -102,7 +102,7 @@
## Pydantic { #pydantic }
모든 데이터 검증은 [Pydantic](https://docs.pydantic.dev/)에 의해 내부적으로 수행되므로 이로 인한 이점을 모두 얻을 수 있습니다. 여러분은 관리를 잘 받고 있음을 느낄 수 있습니다.
모든 데이터 검증은 [Pydantic](https://pydantic.dev/docs/)에 의해 내부적으로 수행되므로 이로 인한 이점을 모두 얻을 수 있습니다. 여러분은 관리를 잘 받고 있음을 느낄 수 있습니다.
`str`, `float`, `bool`, 그리고 다른 여러 복잡한 데이터 타입 선언을 할 수 있습니다.
docs/ko/docs/tutorial/query-params-str-validations.md
+2 -2
View File
@@ -370,11 +370,11 @@ http://127.0.0.1:8000/items/?item-query=foobaritems
그런 경우에는 일반적인 검증(예: 값이 `str`인지 검증한 뒤) 이후에 적용되는 **커스텀 검증 함수**를 사용할 수 있습니다.
`Annotated` 안에서 [Pydantic의 `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator)를 사용하면 이를 구현할 수 있습니다.
`Annotated` 안에서 [Pydantic의 `AfterValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator)를 사용하면 이를 구현할 수 있습니다.
/// tip | 팁
Pydantic에는 [BeforeValidator](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator)와 같은 다른 것들도 있습니다. 🤓
Pydantic에는 [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator)와 같은 다른 것들도 있습니다. 🤓
///
docs/ko/docs/tutorial/request-files.md
+2 -2
View File
@@ -6,10 +6,10 @@
업로드된 파일을 전달받기 위해 먼저 [`python-multipart`](https://github.com/Kludex/python-multipart)를 설치해야합니다.
[가상 환경](../virtual-environments.md)을 생성하고, 활성화한 다음, 예를 들어 다음과 같이 설치하세요:
프로젝트에 추가하세요:
```console
$ pip install python-multipart
$ uv add python-multipart
```
업로드된 파일들은 "폼 데이터"의 형태로 전송되기 때문에 이 작업이 필요합니다.
docs/ko/docs/tutorial/request-form-models.md
+2 -2
View File
@@ -6,10 +6,10 @@ FastAPI에서 **Pydantic 모델**을 이용하여 **폼 필드**를 선언할
폼을 사용하려면, 먼저 [`python-multipart`](https://github.com/Kludex/python-multipart)를 설치하세요.
[가상 환경](../virtual-environments.md)을 생성하고 활성화한 다음, 예를 들어 아래와 같이 설치하세요:
프로젝트에 추가하세요:
```console
$ pip install python-multipart
$ uv add python-multipart
```
///
docs/ko/docs/tutorial/request-forms-and-files.md
+4 -4
View File
@@ -2,14 +2,14 @@
`File` 과 `Form` 을 사용하여 파일과 폼 필드를 동시에 정의할 수 있습니다.
/// note
/// note | 참고
업로드된 파일 및/또는 폼 데이터를 받으려면 먼저 [`python-multipart`](https://github.com/Kludex/python-multipart)를 설치해야 합니다.
[가상 환경](../virtual-environments.md)을 생성하고, 활성화한 다음 설치해야 합니다. 예:
프로젝트에 추가하세요:
```console
$ pip install python-multipart
$ uv add python-multipart
```
///
@@ -28,7 +28,7 @@ $ pip install python-multipart
또한 일부 파일은 `bytes`로, 일부 파일은 `UploadFile`로 선언할 수 있습니다.
/// warning
/// warning | 경고
다수의 `File`과 `Form` 매개변수를 한 *경로 처리*에 선언하는 것이 가능하지만, 요청의 본문이 `application/json`가 아닌 `multipart/form-data`로 인코딩되기 때문에 JSON으로 받기를 기대하는 `Body` 필드를 함께 선언할 수는 없습니다.
docs/ko/docs/tutorial/request-forms.md
+2 -2
View File
@@ -7,10 +7,10 @@ JSON 대신 폼 필드를 받아야 하는 경우 `Form`을 사용할 수 있습
폼을 사용하려면, 먼저 [`python-multipart`](https://github.com/Kludex/python-multipart)를 설치하세요.
[가상 환경](../virtual-environments.md)을 생성하고 활성화한 다음, 예를 들어 다음과 같이 설치하세요:
프로젝트에 추가하세요:
```console
$ pip install python-multipart
$ uv add python-multipart
```
///
docs/ko/docs/tutorial/response-model.md
+4 -4
View File
@@ -76,16 +76,16 @@ FastAPI는 이 `response_model`을 사용해 데이터 문서화, 검증 등을
`EmailStr`을 사용하려면 먼저 [`email-validator`](https://github.com/JoshData/python-email-validator)를 설치하세요.
[가상 환경](../virtual-environments.md)을 생성하고, 활성화한 다음 설치해야 합니다. 예를 들어:
프로젝트에 추가하세요:
```console
$ pip install email-validator
$ uv add email-validator
```
또는 다음과 같이:
```console
$ pip install "pydantic[email]"
$ uv add "pydantic[email]"
```
///
@@ -258,7 +258,7 @@ FastAPI는 Pydantic을 내부적으로 여러 방식으로 사용하여, 클래
* `response_model_exclude_defaults=True`
* `response_model_exclude_none=True`
`exclude_defaults` 및 `exclude_none`에 대해 [Pydantic 문서](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict)에 설명된 대로 사용할 수 있습니다.
`exclude_defaults` 및 `exclude_none`에 대해 [Pydantic 문서](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value)에 설명된 대로 사용할 수 있습니다.
///
docs/ko/docs/tutorial/schema-extra-example.md
+1 -1
View File
@@ -12,7 +12,7 @@
추가 정보는 있는 그대로 해당 모델의 **JSON 스키마** 결과에 추가되고, API 문서에서 사용합니다.
[Pydantic 문서: Configuration](https://docs.pydantic.dev/latest/api/config/)에 설명된 것처럼 `dict`를 받는 `model_config` 어트리뷰트를 사용할 수 있습니다.
[Pydantic 문서: Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/)에 설명된 것처럼 `dict`를 받는 `model_config` 어트리뷰트를 사용할 수 있습니다.
`"json_schema_extra"`를 생성된 JSON 스키마에서 보여주고 싶은 별도의 데이터와 `examples`를 포함하는 `dict`으로 설정할 수 있습니다.
docs/ko/docs/tutorial/security/first-steps.md
+5 -5
View File
@@ -27,14 +27,14 @@
/// note | 참고
[`python-multipart`](https://github.com/Kludex/python-multipart) 패키지는 `pip install "fastapi[standard]"` 명령을 실행하면 **FastAPI**와 함께 자동으로 설치됩니다.
[`python-multipart`](https://github.com/Kludex/python-multipart) 패키지는 `uv add "fastapi[standard]"` 명령을 실행하면 **FastAPI**와 함께 자동으로 설치됩니다.
하지만 `pip install fastapi` 명령을 사용하면 `python-multipart` 패키지가 기본으로 포함되지 않습니다.
하지만 `uv add fastapi` 명령을 사용하면 `python-multipart` 패키지가 기본으로 포함되지 않습니다.
수동으로 설치하려면, [가상 환경](../../virtual-environments.md)을 만들고 활성화한 다음, 아래로 설치하세요:
수동으로 설치하려면, 프로젝트에 아래로 추가하세요:
```console
$ pip install python-multipart
$ uv add python-multipart
```
이는 **OAuth2**가 `username`과 `password`를 보내기 위해 "form data"를 사용하기 때문입니다.
@@ -46,7 +46,7 @@ $ pip install python-multipart
<div class="termy">
```console
$ fastapi dev
$ uv run fastapi dev
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
docs/ko/docs/tutorial/security/oauth2-jwt.md
+5 -5
View File
@@ -31,12 +31,12 @@ JWT 토큰을 직접 다뤄보고 동작 방식을 확인해보고 싶다면 [ht
Python에서 JWT 토큰을 생성하고 검증하려면 `PyJWT`를 설치해야 합니다.
[가상환경](../../virtual-environments.md)을 만들고 활성화한 다음 `pyjwt`를 설치하십시오:
프로젝트에 `pyjwt`를 추가하십시오:
<div class="termy">
```console
$ pip install pyjwt
$ uv add pyjwt
---> 100%
```
@@ -73,12 +73,12 @@ pwdlib는 패스워드 해시를 다루기 위한 훌륭한 Python 패키지입
추천 알고리즘은 "Argon2"입니다.
[가상환경](../../virtual-environments.md)을 만들고 활성화한 다음 Argon2와 함께 pwdlib를 설치하십시오:
프로젝트에 Argon2와 함께 `pwdlib`를 추가하십시오:
<div class="termy">
```console
$ pip install "pwdlib[argon2]"
$ uv add "pwdlib[argon2]"
---> 100%
```
@@ -135,7 +135,7 @@ pwdlib는 bcrypt 해싱 알고리즘도 지원하지만 레거시 알고리즘
JWT 토큰을 서명하는 데 사용할 임의의 비밀 키를 생성합니다.
안전한 임의의 비밀 키를 생성하려면 다음 명령을 사용하십시오:
안전한 임의의 비밀 키를 생성하려면 다음 명령어를 사용하십시오:
<div class="termy">
docs/ko/docs/tutorial/sql-databases.md
+4 -4
View File
@@ -35,12 +35,12 @@ SQLModel은 SQLAlchemy를 기반으로 하므로, SQLAlchemy에서 **지원하
## `SQLModel` 설치하기 { #install-sqlmodel }
먼저, [가상 환경](../virtual-environments.md)을 생성하고 활성화한 다음, `sqlmodel`을 설치하세요:
프로젝트에 `sqlmodel`을 추가하세요:
<div class="termy">
```console
$ pip install sqlmodel
$ uv add sqlmodel
---> 100%
```
@@ -153,7 +153,7 @@ SQLModel은 Alembic을 감싸는 마이그레이션 유틸리티를 제공할
<div class="termy">
```console
$ fastapi dev
$ uv run fastapi dev
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
@@ -338,7 +338,7 @@ hero **삭제**는 이전과 거의 동일합니다.
<div class="termy">
```console
$ fastapi dev
$ uv run fastapi dev
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
docs/ko/docs/tutorial/static-files.md
+1 -1
View File
@@ -45,4 +45,4 @@
## 추가 정보 { #more-info }
자세한 내용과 옵션은 [Starlette의 정적 파일 문서](https://www.starlette.dev/staticfiles/)를 확인하세요.
자세한 내용과 옵션은 [Starlette의 정적 파일 문서](https://starlette.dev/staticfiles/)를 확인하세요.
docs/ko/docs/tutorial/testing.md
+6 -6
View File
@@ -1,6 +1,6 @@
# 테스팅 { #testing }
[Starlette](https://www.starlette.dev/testclient/) 덕분에 **FastAPI** 애플리케이션을 테스트하는 일은 쉽고 즐거운 일이 되었습니다.
[Starlette](https://starlette.dev/testclient/) 덕분에 **FastAPI** 애플리케이션을 테스트하는 일은 쉽고 즐거운 일이 되었습니다.
이는 [HTTPX](https://www.python-httpx.org)를 기반으로 하며, 이는 Requests를 기반으로 설계되었기 때문에 매우 친숙하고 직관적입니다.
@@ -12,10 +12,10 @@
`TestClient` 사용하려면, 우선 [`httpx`](https://www.python-httpx.org)를 설치해야 합니다.
[가상 환경](../virtual-environments.md)을 만들고, 활성화한 뒤 설치하세요. 예시:
프로젝트에 추가하세요:
```console
$ pip install httpx
$ uv add httpx
```
///
@@ -156,12 +156,12 @@ FastAPI 애플리케이션에 요청을 보내는 것 외에도 테스트에서
그 후에는 `pytest`를 설치하기만 하면 됩니다.
[가상 환경](../virtual-environments.md)을 만들고, 활성화 시킨 뒤에 설치하세요. 예시:
프로젝트에 추가하세요:
<div class="termy">
```console
$ pip install pytest
$ uv add pytest
---> 100%
```
@@ -175,7 +175,7 @@ $ pip install pytest
<div class="termy">
```console
$ pytest
$ uv run pytest
================ test session starts ================
platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1
docs/ko/docs/virtual-environments.md
+10 -840
View File
@@ -1,865 +1,35 @@
# 가상 환경 { #virtual-environments }
Python 프로젝트를 작업할 때는 각 프로젝트마다 설치하는 패키지를 분리하기 위해 **가상 환경**을 사용해야 합니다.
Python 프로젝트를 작업할 때는 **가상 환경**(또는 이와 유사한 메커니즘)을 사용해 각 프로젝트마다 설치하는 패키지를 분리하는 것이 좋습니다.
/// note | 참고
이미 가상 환경에 대해 알고 있고, 어떻게 생성하고 사용하는지도 알고 있다면, 이 섹션은 건너뛰어도 괜찮습니다. 🤓
///
/// tip | 팁
**가상 환경**은 **환경 변수**와 다릅니다.
**환경 변수**는 시스템에 존재하며, 프로그램이 사용할 수 있는 변수입니다.
**가상 환경**은 몇몇 파일로 구성된 하나의 디렉터리입니다.
///
/// note | 참고
이 페이지에서는 **가상 환경**을 사용하는 방법과 작동 방식을 알려드립니다.
Python 설치까지 포함해 **모든 것을 관리해주는 도구**를 도입할 준비가 되었다면 [uv](https://github.com/astral-sh/uv)를 사용해 보세요.
///
FastAPI 프로젝트에서는 [uv](https://docs.astral.sh/uv/)를 사용해 프로젝트, 의존성, 가상 환경을 관리하는 것을 권장합니다.
## 프로젝트 생성 { #create-a-project }
먼저, 프로젝트를 위한 디렉터리를 하나 생성합니다.
제가 보통 하는 방법은 사용자 홈/유저 디렉터리 안에 `code`라는 디렉터리를 만드는 것입니다.
그리고 그 안에 프로젝트마다 디렉터리를 하나씩 만듭니다.
[공식 설치 가이드](https://docs.astral.sh/uv/getting-started/installation/)를 사용해 `uv`를 설치한 다음, 프로젝트를 생성하세요:
<div class="termy">
```console
// 홈 디렉터리로 이동
$ cd
// 모든 코드 프로젝트를 위한 디렉터리 생성
$ mkdir code
// 그 code 디렉터리로 이동
$ cd code
// 이 프로젝트를 위한 디렉터리 생성
$ mkdir awesome-project
// 그 프로젝트 디렉터리로 이동
$ uv init awesome-project --bare
$ cd awesome-project
$ uv add "fastapi[standard]"
```
</div>
## 가상 환경 생성 { #create-a-virtual-environment }
`uv`는 프로젝트를 위한 가상 환경을 자동으로 생성합니다. 직접 만들거나 활성화할 필요가 없습니다.
Python 프로젝트를 **처음 시작할 때**, 가상 환경을 **<dfn title="다른 옵션도 있지만, 이것은 간단한 가이드라인입니다">프로젝트 내부</dfn>**에 생성하세요.
/// tip | 팁
이 작업은 **프로젝트당 한 번만** 하면 되며, 작업할 때마다 할 필요는 없습니다.
///
//// tab | `venv`
가상 환경을 만들려면 Python에 포함된 `venv` 모듈을 사용할 수 있습니다.
프로젝트 환경 안에서 명령어를 실행하려면 `uv run`을 사용하세요. 예를 들면:
<div class="termy">
```console
$ python -m venv .venv
$ uv run fastapi dev
```
</div>
/// details | 명령어 의미
## 더 알아보기 { #learn-more }
* `python`: `python`이라는 프로그램을 사용합니다
* `-m`: 모듈을 스크립트로 호출합니다. 다음에 어떤 모듈인지 지정합니다
* `venv`: 보통 Python에 기본으로 설치되어 있는 `venv` 모듈을 사용합니다
* `.venv`: 새 디렉터리인 `.venv`에 가상 환경을 생성합니다
///
////
//// tab | `uv`
[`uv`](https://github.com/astral-sh/uv)가 설치되어 있다면, 이를 사용해 가상 환경을 생성할 수 있습니다.
<div class="termy">
```console
$ uv venv
```
</div>
/// tip | 팁
기본적으로 `uv`는 `.venv`라는 디렉터리에 가상 환경을 생성합니다.
하지만 디렉터리 이름을 추가 인자로 전달해 이를 커스터마이즈할 수 있습니다.
///
////
해당 명령어는 `.venv`라는 디렉터리에 새로운 가상 환경을 생성합니다.
/// details | `.venv` 또는 다른 이름
가상 환경을 다른 디렉터리에 생성할 수도 있지만, 관례적으로 `.venv`라는 이름을 사용합니다.
///
## 가상 환경 활성화 { #activate-the-virtual-environment }
이후 실행하는 Python 명령어와 설치하는 패키지가 새 가상 환경을 사용하도록, 새 가상 환경을 활성화하세요.
/// tip | 팁
프로젝트 작업을 위해 **새 터미널 세션**을 시작할 때마다 **매번** 이 작업을 하세요.
///
//// tab | Linux, macOS
<div class="termy">
```console
$ source .venv/bin/activate
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ .venv\Scripts\Activate.ps1
```
</div>
////
//// tab | Windows Bash
또는 Windows에서 Bash(예: [Git Bash](https://gitforwindows.org/))를 사용하는 경우:
<div class="termy">
```console
$ source .venv/Scripts/activate
```
</div>
////
/// tip | 팁
해당 환경에 **새 패키지**를 설치할 때마다, 환경을 다시 **활성화**하세요.
이렇게 하면 해당 패키지가 설치한 **터미널(<abbr title="command line interface - 명령줄 인터페이스">CLI</abbr>) 프로그램**을 사용할 때, 전역으로 설치되어 있을 수도 있는(아마 필요한 버전과는 다른 버전인) 다른 프로그램이 아니라 가상 환경에 있는 것을 사용하게 됩니다.
///
## 가상 환경 활성화 여부 확인 { #check-the-virtual-environment-is-active }
가상 환경이 활성화되어 있는지(이전 명령어가 작동했는지) 확인합니다.
/// tip | 팁
이 단계는 **선택 사항**이지만, 모든 것이 예상대로 작동하고 있는지, 그리고 의도한 가상 환경을 사용하고 있는지 **확인**하는 좋은 방법입니다.
///
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
$ which python
/home/user/code/awesome-project/.venv/bin/python
```
</div>
프로젝트 내부(이 경우 `awesome-project`)의 `.venv/bin/python`에 있는 `python` 바이너리가 표시된다면, 정상적으로 작동한 것입니다. 🎉
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ Get-Command python
C:\Users\user\code\awesome-project\.venv\Scripts\python
```
</div>
프로젝트 내부(이 경우 `awesome-project`)의 `.venv\Scripts\python`에 있는 `python` 바이너리가 표시된다면, 정상적으로 작동한 것입니다. 🎉
////
## `pip` 업그레이드 { #upgrade-pip }
/// tip | 팁
[`uv`](https://github.com/astral-sh/uv)를 사용한다면, `pip` 대신 `uv`로 설치하게 되므로 `pip`을 업그레이드할 필요가 없습니다. 😎
///
`pip`로 패키지를 설치한다면(Python에 기본으로 포함되어 있습니다) 최신 버전으로 **업그레이드**하는 것이 좋습니다.
패키지 설치 중 발생하는 다양한 특이한 오류는 먼저 `pip`를 업그레이드하는 것만으로 해결되는 경우가 많습니다.
/// tip | 팁
보통 이 작업은 가상 환경을 만든 직후 **한 번만** 하면 됩니다.
///
가상 환경이 활성화된 상태인지 확인한 다음(위의 명령어 사용) 아래를 실행하세요:
<div class="termy">
```console
$ python -m pip install --upgrade pip
---> 100%
```
</div>
/// tip | 팁
때로는 pip를 업그레이드하려고 할 때 **`No module named pip`** 오류가 발생할 수 있습니다.
이 경우 아래 명령어로 pip를 설치하고 업그레이드하세요:
<div class="termy">
```console
$ python -m ensurepip --upgrade
---> 100%
```
</div>
이 명령어는 pip가 아직 설치되어 있지 않다면 설치하며, 설치된 pip 버전이 `ensurepip`에서 제공 가능한 버전만큼 최신임을 보장합니다.
///
## `.gitignore` 추가하기 { #add-gitignore }
**Git**을 사용하고 있다면(사용하는 것이 좋습니다), `.venv`의 모든 내용을 Git에서 제외하도록 `.gitignore` 파일을 추가하세요.
/// tip | 팁
[`uv`](https://github.com/astral-sh/uv)로 가상 환경을 만들었다면, 이미 자동으로 처리되어 있으므로 이 단계는 건너뛰어도 됩니다. 😎
///
/// tip | 팁
가상 환경을 만든 직후 **한 번만** 하면 됩니다.
///
<div class="termy">
```console
$ echo "*" > .venv/.gitignore
```
</div>
/// details | 명령어 의미
* `echo "*"`: 터미널에 `*` 텍스트를 "출력"합니다(다음 부분이 이를 약간 변경합니다)
* `>`: `>` 왼쪽 명령어가 터미널에 출력한 내용을 터미널에 출력하지 않고, `>` 오른쪽에 있는 파일에 기록하라는 의미입니다
* `.gitignore`: 텍스트가 기록될 파일 이름입니다
그리고 Git에서 `*`는 "모든 것"을 의미합니다. 따라서 `.venv` 디렉터리 안의 모든 것을 무시합니다.
이 명령어는 다음 내용을 가진 `.gitignore` 파일을 생성합니다:
```gitignore
*
```
///
## 패키지 설치 { #install-packages }
환경을 활성화한 뒤, 그 안에 패키지를 설치할 수 있습니다.
/// tip | 팁
프로젝트에 필요한 패키지를 설치하거나 업그레이드할 때는 **한 번**만 하면 됩니다.
버전을 업그레이드하거나 새 패키지를 추가해야 한다면 **다시 이 작업을** 하게 됩니다.
///
### 패키지 직접 설치 { #install-packages-directly }
급하게 작업 중이고 프로젝트의 패키지 요구사항을 선언하는 파일을 사용하고 싶지 않다면, 패키지를 직접 설치할 수 있습니다.
/// tip | 팁
프로그램에 필요한 패키지와 버전을 파일(예: `requirements.txt` 또는 `pyproject.toml`)에 적어두는 것은 (매우) 좋은 생각입니다.
///
//// tab | `pip`
<div class="termy">
```console
$ pip install "fastapi[standard]"
---> 100%
```
</div>
////
//// tab | `uv`
[`uv`](https://github.com/astral-sh/uv)가 있다면:
<div class="termy">
```console
$ uv pip install "fastapi[standard]"
---> 100%
```
</div>
////
### `requirements.txt`에서 설치 { #install-from-requirements-txt }
`requirements.txt`가 있다면, 이제 이를 사용해 그 안의 패키지를 설치할 수 있습니다.
//// tab | `pip`
<div class="termy">
```console
$ pip install -r requirements.txt
---> 100%
```
</div>
////
//// tab | `uv`
[`uv`](https://github.com/astral-sh/uv)가 있다면:
<div class="termy">
```console
$ uv pip install -r requirements.txt
---> 100%
```
</div>
////
/// details | `requirements.txt`
일부 패키지가 있는 `requirements.txt`는 다음과 같이 생겼을 수 있습니다:
```requirements.txt
fastapi[standard]==0.113.0
pydantic==2.8.0
```
///
## 프로그램 실행 { #run-your-program }
가상 환경을 활성화한 뒤에는 프로그램을 실행할 수 있으며, 설치한 패키지가 들어있는 가상 환경 내부의 Python을 사용하게 됩니다.
<div class="termy">
```console
$ python main.py
Hello World
```
</div>
## 에디터 설정 { #configure-your-editor }
아마 에디터를 사용할 텐데, 자동 완성과 인라인 오류 표시를 받을 수 있도록 생성한 가상 환경을 사용하도록 설정하세요(대부분 자동 감지합니다).
예를 들면:
* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment)
* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html)
/// tip | 팁
보통 이 설정은 가상 환경을 만들 때 **한 번만** 하면 됩니다.
///
## 가상 환경 비활성화 { #deactivate-the-virtual-environment }
프로젝트 작업을 마쳤다면 가상 환경을 **비활성화**할 수 있습니다.
<div class="termy">
```console
$ deactivate
```
</div>
이렇게 하면 `python`을 실행할 때, 해당 가상 환경과 그 안에 설치된 패키지에서 실행하려고 하지 않습니다.
## 작업할 준비 완료 { #ready-to-work }
이제 프로젝트 작업을 시작할 준비가 되었습니다.
/// tip | 팁
위의 내용이 무엇인지 더 이해하고 싶으신가요?
계속 읽어보세요. 👇🤓
///
## 가상 환경을 왜 사용하나요 { #why-virtual-environments }
FastAPI로 작업하려면 [Python](https://www.python.org/)을 설치해야 합니다.
그 다음 FastAPI와 사용하려는 다른 **패키지**를 **설치**해야 합니다.
패키지를 설치할 때는 보통 Python에 포함된 `pip` 명령어(또는 유사한 대안)를 사용합니다.
하지만 `pip`를 그대로 직접 사용하면, 패키지는 **전역 Python 환경**(전역 Python 설치)에 설치됩니다.
### 문제점 { #the-problem }
그렇다면, 전역 Python 환경에 패키지를 설치하면 어떤 문제가 있을까요?
어느 시점이 되면 **서로 다른 패키지**에 의존하는 다양한 프로그램을 작성하게 될 것입니다. 그리고 작업하는 프로젝트 중 일부는 같은 패키지의 **서로 다른 버전**에 의존할 수도 있습니다. 😱
예를 들어 `philosophers-stone`이라는 프로젝트를 만들 수 있습니다. 이 프로그램은 **`harry`라는 다른 패키지의 버전 `1`**에 의존합니다. 그래서 `harry`를 설치해야 합니다.
```mermaid
flowchart LR
stone(philosophers-stone) -->|requires| harry-1[harry v1]
```
그다음, 나중에 `prisoner-of-azkaban`이라는 또 다른 프로젝트를 만들고, 이 프로젝트도 `harry`에 의존하지만, 이 프로젝트는 **`harry` 버전 `3`**이 필요합니다.
```mermaid
flowchart LR
azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]
```
하지만 이제 문제가 생깁니다. 로컬 **가상 환경**이 아니라 전역(전역 환경)에 패키지를 설치한다면, 어떤 버전의 `harry`를 설치할지 선택해야 합니다.
`philosophers-stone`을 실행하고 싶다면, 먼저 `harry` 버전 `1`을 다음과 같이 설치해야 합니다:
<div class="termy">
```console
$ pip install "harry==1"
```
</div>
그리고 전역 Python 환경에 `harry` 버전 `1`이 설치된 상태가 됩니다.
```mermaid
flowchart LR
subgraph global[global env]
harry-1[harry v1]
end
subgraph stone-project[philosophers-stone project]
stone(philosophers-stone) -->|requires| harry-1
end
```
하지만 `prisoner-of-azkaban`을 실행하려면 `harry` 버전 `1`을 제거하고 `harry` 버전 `3`을 설치해야 합니다(또는 버전 `3`을 설치하기만 해도 버전 `1`이 자동으로 제거됩니다).
<div class="termy">
```console
$ pip install "harry==3"
```
</div>
그러면 전역 Python 환경에 `harry` 버전 `3`이 설치된 상태가 됩니다.
그리고 `philosophers-stone`을 다시 실행하려고 하면, `harry` 버전 `1`이 필요하기 때문에 **작동하지 않을** 가능성이 있습니다.
```mermaid
flowchart LR
subgraph global[global env]
harry-1[<strike>harry v1</strike>]
style harry-1 fill:#ccc,stroke-dasharray: 5 5
harry-3[harry v3]
end
subgraph stone-project[philosophers-stone project]
stone(philosophers-stone) -.-x|⛔️| harry-1
end
subgraph azkaban-project[prisoner-of-azkaban project]
azkaban(prisoner-of-azkaban) --> |requires| harry-3
end
```
/// tip | 팁
Python 패키지에서는 **새 버전**에서 **호환성을 깨뜨리는 변경(breaking changes)**을 **피하려고** 최선을 다하는 것이 매우 일반적이지만, 안전을 위해 더 최신 버전은 의도적으로 설치하고, 테스트를 실행해 모든 것이 올바르게 작동하는지 확인할 수 있을 때 설치하는 것이 좋습니다.
///
이제 이런 일이 여러분의 **모든 프로젝트가 의존하는** **많은** 다른 **패키지**에서도 일어난다고 상상해 보세요. 이는 관리하기가 매우 어렵습니다. 그리고 결국 일부 프로젝트는 패키지의 **호환되지 않는 버전**으로 실행하게 될 가능성이 높으며, 왜 무언가가 작동하지 않는지 알지 못하게 될 수 있습니다.
또한 운영체제(Linux, Windows, macOS 등)에 따라 Python이 이미 설치되어 있을 수도 있습니다. 그런 경우에는 시스템에 **필요한 특정 버전**의 패키지가 일부 미리 설치되어 있을 가능성이 큽니다. 전역 Python 환경에 패키지를 설치하면, 운영체제에 포함된 프로그램 일부가 **깨질** 수 있습니다.
## 패키지는 어디에 설치되나요 { #where-are-packages-installed }
Python을 설치하면 컴퓨터에 몇몇 파일이 들어 있는 디렉터리가 생성됩니다.
이 디렉터리 중 일부는 설치한 모든 패키지를 담는 역할을 합니다.
다음을 실행하면:
<div class="termy">
```console
// 지금은 실행하지 마세요, 예시일 뿐입니다 🤓
$ pip install "fastapi[standard]"
---> 100%
```
</div>
FastAPI 코드를 담은 압축 파일을 다운로드합니다. 보통 [PyPI](https://pypi.org/project/fastapi/)에서 받습니다.
또한 FastAPI가 의존하는 다른 패키지들의 파일도 **다운로드**합니다.
그 다음 모든 파일을 **압축 해제**하고 컴퓨터의 한 디렉터리에 넣습니다.
기본적으로, 다운로드하고 압축 해제한 파일들은 Python 설치와 함께 제공되는 디렉터리, 즉 **전역 환경**에 저장됩니다.
## 가상 환경이란 무엇인가요 { #what-are-virtual-environments }
전역 환경에 모든 패키지를 두는 문제에 대한 해결책은 작업하는 **각 프로젝트마다 가상 환경**을 사용하는 것입니다.
가상 환경은 전역 환경과 매우 유사한 하나의 **디렉터리**이며, 프로젝트의 패키지를 설치할 수 있습니다.
이렇게 하면 각 프로젝트는 자체 가상 환경(`.venv` 디렉터리)과 자체 패키지를 갖게 됩니다.
```mermaid
flowchart TB
subgraph stone-project[philosophers-stone project]
stone(philosophers-stone) --->|requires| harry-1
subgraph venv1[.venv]
harry-1[harry v1]
end
end
subgraph azkaban-project[prisoner-of-azkaban project]
azkaban(prisoner-of-azkaban) --->|requires| harry-3
subgraph venv2[.venv]
harry-3[harry v3]
end
end
stone-project ~~~ azkaban-project
```
## 가상 환경을 활성화한다는 것은 무엇을 의미하나요 { #what-does-activating-a-virtual-environment-mean }
가상 환경을 활성화한다는 것은, 예를 들어 다음과 같은 명령어로:
//// tab | Linux, macOS
<div class="termy">
```console
$ source .venv/bin/activate
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ .venv\Scripts\Activate.ps1
```
</div>
////
//// tab | Windows Bash
또는 Windows에서 Bash(예: [Git Bash](https://gitforwindows.org/))를 사용하는 경우:
<div class="termy">
```console
$ source .venv/Scripts/activate
```
</div>
////
다음 명령어들에서 사용할 수 있는 몇몇 [환경 변수](environment-variables.md)를 생성하거나 수정하는 것을 의미합니다.
그 변수 중 하나가 `PATH` 변수입니다.
/// tip | 팁
`PATH` 환경 변수에 대해 더 알아보려면 [환경 변수](environment-variables.md#path-environment-variable) 섹션을 참고하세요.
///
가상 환경을 활성화하면 가상 환경의 경로인 `.venv/bin`(Linux와 macOS) 또는 `.venv\Scripts`(Windows)를 `PATH` 환경 변수에 추가합니다.
가령 환경을 활성화하기 전에는 `PATH` 변수가 다음과 같았다고 해보겠습니다:
//// tab | Linux, macOS
```plaintext
/usr/bin:/bin:/usr/sbin:/sbin
```
이는 시스템이 다음 위치에서 프로그램을 찾는다는 뜻입니다:
* `/usr/bin`
* `/bin`
* `/usr/sbin`
* `/sbin`
////
//// tab | Windows
```plaintext
C:\Windows\System32
```
이는 시스템이 다음 위치에서 프로그램을 찾는다는 뜻입니다:
* `C:\Windows\System32`
////
가상 환경을 활성화한 뒤에는 `PATH` 변수가 다음과 같이 보일 수 있습니다:
//// tab | Linux, macOS
```plaintext
/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin
```
이는 시스템이 이제 다음 위치에서 프로그램을 가장 먼저 찾기 시작한다는 뜻입니다:
```plaintext
/home/user/code/awesome-project/.venv/bin
```
그리고 나서 다른 디렉터리들을 탐색합니다.
따라서 터미널에 `python`을 입력하면, 시스템은 다음 위치에서 Python 프로그램을 찾고:
```plaintext
/home/user/code/awesome-project/.venv/bin/python
```
그것을 사용하게 됩니다.
////
//// tab | Windows
```plaintext
C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32
```
이는 시스템이 이제 다음 위치에서 프로그램을 가장 먼저 찾기 시작한다는 뜻입니다:
```plaintext
C:\Users\user\code\awesome-project\.venv\Scripts
```
그리고 나서 다른 디렉터리들을 탐색합니다.
따라서 터미널에 `python`을 입력하면, 시스템은 다음 위치에서 Python 프로그램을 찾고:
```plaintext
C:\Users\user\code\awesome-project\.venv\Scripts\python
```
그것을 사용하게 됩니다.
////
중요한 세부 사항은 가상 환경 경로가 `PATH` 변수의 **맨 앞**에 들어간다는 점입니다. 시스템은 다른 어떤 Python보다도 **먼저** 이를 찾게 됩니다. 이렇게 하면 `python`을 실행할 때, 다른 어떤 `python`(예: 전역 환경의 `python`)이 아니라 **가상 환경의 Python**을 사용하게 됩니다.
가상 환경을 활성화하면 다른 몇 가지도 변경되지만, 이것이 그중 가장 중요한 것 중 하나입니다.
## 가상 환경 확인하기 { #checking-a-virtual-environment }
가상 환경이 활성화되어 있는지 확인할 때는, 예를 들어 다음을 사용합니다:
//// tab | Linux, macOS, Windows Bash
<div class="termy">
```console
$ which python
/home/user/code/awesome-project/.venv/bin/python
```
</div>
////
//// tab | Windows PowerShell
<div class="termy">
```console
$ Get-Command python
C:\Users\user\code\awesome-project\.venv\Scripts\python
```
</div>
////
이는 사용될 `python` 프로그램이 **가상 환경 내부에 있는 것**이라는 뜻입니다.
Linux와 macOS에서는 `which`, Windows PowerShell에서는 `Get-Command`를 사용합니다.
이 명령어는 `PATH` 환경 변수에 있는 경로를 **순서대로** 확인하면서 `python`이라는 프로그램을 찾습니다. 찾는 즉시, 그 프로그램의 **경로를 보여줍니다**.
가장 중요한 부분은 `python`을 호출했을 때, 실행될 정확한 "`python`"이 무엇인지 알 수 있다는 점입니다.
따라서 올바른 가상 환경에 있는지 확인할 수 있습니다.
/// tip | 팁
가상 환경을 하나 활성화해서 Python을 사용한 다음, **다른 프로젝트로 이동**하기 쉽습니다.
그리고 두 번째 프로젝트는 다른 프로젝트의 가상 환경에서 온 **잘못된 Python**을 사용하고 있기 때문에 **작동하지 않을** 수 있습니다.
어떤 `python`이 사용되고 있는지 확인할 수 있으면 유용합니다. 🤓
///
## 가상 환경을 왜 비활성화하나요 { #why-deactivate-a-virtual-environment }
예를 들어 `philosophers-stone` 프로젝트에서 작업하면서, **그 가상 환경을 활성화**하고, 패키지를 설치하고, 그 환경으로 작업하고 있다고 해보겠습니다.
그런데 이제 **다른 프로젝트**인 `prisoner-of-azkaban`에서 작업하고 싶습니다.
해당 프로젝트로 이동합니다:
<div class="termy">
```console
$ cd ~/code/prisoner-of-azkaban
```
</div>
`philosophers-stone`의 가상 환경을 비활성화하지 않으면, 터미널에서 `python`을 실행할 때 `philosophers-stone`의 Python을 사용하려고 할 것입니다.
<div class="termy">
```console
$ cd ~/code/prisoner-of-azkaban
$ python main.py
// sirius 임포트 오류, 설치되어 있지 않습니다 😱
Traceback (most recent call last):
File "main.py", line 1, in <module>
import sirius
```
</div>
하지만 가상 환경을 비활성화하고 `prisoner-of-azkaban`에 대한 새 가상 환경을 활성화하면, `python`을 실행할 때 `prisoner-of-azkaban`의 가상 환경에 있는 Python을 사용하게 됩니다.
<div class="termy">
```console
$ cd ~/code/prisoner-of-azkaban
// 비활성화를 위해 이전 디렉터리에 있을 필요는 없습니다. 어디서든, 다른 프로젝트로 이동한 뒤에도 할 수 있습니다 😎
$ deactivate
// prisoner-of-azkaban/.venv의 가상 환경을 활성화하세요 🚀
$ source .venv/bin/activate
// 이제 python을 실행하면, 이 가상 환경에 설치된 sirius 패키지를 찾습니다 ✨
$ python main.py
I solemnly swear 🐺
```
</div>
## 대안들 { #alternatives }
이 문서는 시작을 돕고, 내부에서 모든 것이 어떻게 작동하는지 알려주는 간단한 가이드입니다.
가상 환경, 패키지 의존성(requirements), 프로젝트를 관리하는 방법에는 많은 **대안**이 있습니다.
준비가 되었고 **프로젝트 전체**, 패키지 의존성, 가상 환경 등을 **관리**하는 도구를 사용하고 싶다면 [uv](https://github.com/astral-sh/uv)를 사용해 보시길 권합니다.
`uv`는 많은 일을 할 수 있습니다. 예를 들어:
* 여러 버전을 포함해 **Python을 설치**
* 프로젝트의 **가상 환경** 관리
* **패키지** 설치
* 프로젝트의 패키지 **의존성과 버전** 관리
* 의존성을 포함해 설치할 패키지와 버전의 **정확한** 세트를 보장하여, 개발 중인 컴퓨터와 동일하게 프로덕션에서 실행할 수 있도록 합니다. 이를 **locking**이라고 합니다
* 그 외에도 많은 기능이 있습니다
## 결론 { #conclusion }
여기까지 모두 읽고 이해했다면, 이제 많은 개발자들보다 가상 환경에 대해 **훨씬 더 많이** 알게 된 것입니다. 🤓
이 세부 사항을 알고 있으면, 나중에 복잡해 보이는 무언가를 디버깅할 때 아마도 도움이 될 것입니다. **내부에서 어떻게 작동하는지** 알고 있기 때문입니다. 😎
가상 환경이 내부에서 어떻게 작동하는지, 활성화와 대안인 `python -m venv` 및 `pip` 워크플로를 포함해 알아보려면 [가상 환경 가이드](https://tiangolo.com/guides/virtual-environments/)를 읽어보세요.