forked from tiangolo/fastapi
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add Korean Translation for Python-types tiangolo#2017
- Loading branch information
Showing
1 changed file
with
314 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,314 @@ | ||
# 파이썬 타입 소개 | ||
|
||
**Python 3.6+**는 "타입 힌트"를 선택적으로 제공합니다. | ||
|
||
**"타입 힌트"**는 (Python 3.6+)부터 제공하는 새로운 문법으로 변수의 <abbr title="for example: str, int, float, bool">타입</abbr>을 지정할 수 있습니다. | ||
|
||
변수의 타입을 지정하면 에디터와 툴이 더 많은 도움을 줄 수 있게 됩니다. | ||
|
||
이 문서는 파이썬 타입 힌트에 대한 **빠른 튜토리얼 / 내용환기** 수준의 문서입니다. 여기서는 **FastAPI**를 쓰기 위한 최소한의 내용만을 다룹니다. | ||
|
||
**FastAPI**는 타입 힌트에 기반을 두고 있으며, 이는 많은 장점과 이익이 있습니다. | ||
|
||
비록 **FastAPI**를 쓰지 않는다고 하더라도, 조금이라도 알아두면 도움이 될 것입니다. | ||
|
||
!!! note | ||
파이썬에 능숙하셔서 타입 힌트에 대해 모두 아신다면, 다음 챕터로 건너뛰세요. | ||
|
||
## 동기 부여 | ||
|
||
간단한 예시부터 시작해봅시다: | ||
|
||
```Python | ||
{!../../../docs_src/python_types/tutorial001.py!} | ||
``` | ||
|
||
이 프로그램을 실행한 결과값: | ||
|
||
``` | ||
John Doe | ||
``` | ||
|
||
함수는 아래와 같이 실행됩니다: | ||
|
||
* `first_name`과 `last_name`를 받습니다. | ||
* `title()`로 각 첫 문자를 대문자로 변환시킵니다. | ||
* 두 단어를 중간에 공백을 두고 <abbr title="두 개를 하나로 차례차례 이어지게 하다">연결</abbr>합니다. | ||
|
||
```Python hl_lines="2" | ||
{!../../../docs_src/python_types/tutorial001.py!} | ||
``` | ||
|
||
### 코드 수정 | ||
|
||
이건 매우 간단한 프로그램입니다. | ||
|
||
그런데 처음부터 작성한다고 생각을 해봅시다. | ||
|
||
파라미터가 무엇인지 정하고, 함수를 정의할 때가 되었습니다. | ||
|
||
그때 당신은 "첫 글자를 대문자로 바꾸는 함수"를 호출해야 합니다. | ||
|
||
하지만 함수 이름이 무엇이었는지 너무 헷갈리네요. `upper`? `uppercase`? `first_uppercase`? `capitalize`? | ||
|
||
그때 개발자들의 오랜 친구, 에디터 자동완성을 시도해봅니다. | ||
|
||
당신은 `first_name`를 입력한 뒤 점(`.`)을 입력하고 자동완성을 켜기 위해서 `Ctrl+Space`를 눌렀습니다. | ||
|
||
하지만 슬프게도.. 아무런 도움이 되지 않네요: | ||
|
||
<img src="/img/python-types/image01.png"> | ||
|
||
### 타입을 추가하자 | ||
|
||
이전 버전에서 한 줄만 수정해봅시다. | ||
|
||
저희는 이 함수의 파라미터 부분: | ||
|
||
```Python | ||
first_name, last_name | ||
``` | ||
|
||
을 아래와 같이 바꿀 겁니다: | ||
|
||
```Python | ||
first_name: str, last_name: str | ||
``` | ||
|
||
이게 다에요. | ||
|
||
이게 "타입 힌트"입니다. | ||
|
||
```Python hl_lines="1" | ||
{!../../../docs_src/python_types/tutorial002.py!} | ||
``` | ||
|
||
타입힌트는 기본 값을 선언하는 것과는 다릅니다. | ||
|
||
```Python | ||
first_name="john", last_name="doe" | ||
``` | ||
|
||
여러 차이가 있습니다. | ||
|
||
(`=`) 대신 (`:`)을 쓰고, | ||
|
||
일반적으로 타입힌트를 추가한다고 해서 특별하게 어떤 일이 일어나지도 않습니다. | ||
|
||
하지만, 타입 힌트를 사용해서 다시 중간의 코드를 작성한다고 생각해보세요. | ||
|
||
같은 상황에서 `Ctrl+Space`로 자동완성을 작동시키면, | ||
|
||
<img src="/img/python-types/image02.png"> | ||
|
||
아래와 같이 "그렇지!"하는 옵션이 나올때까지 스크롤을 내려서 볼 수 있습니다: | ||
|
||
<img src="/img/python-types/image03.png"> | ||
|
||
## 더 큰 동기부여 | ||
|
||
아래 함수를 보면, 이미 타입 힌트가 적용되어 있는 걸 볼 수 있습니다: | ||
|
||
```Python hl_lines="1" | ||
{!../../../docs_src/python_types/tutorial003.py!} | ||
``` | ||
|
||
에디터는 변수의 타입을 알기 때문에, 자동완성 뿐 아니라 에러 내용도 확인할 수 있습니다: | ||
|
||
<img src="/img/python-types/image04.png"> | ||
|
||
이제 고쳐야하는 걸 알기 때문에, `age`를 `str(age)`과 같이 문자열로 바꾸게 됩니다: | ||
|
||
```Python hl_lines="2" | ||
{!../../../docs_src/python_types/tutorial004.py!} | ||
``` | ||
|
||
## 타입 선언 | ||
|
||
방금 함수의 매개변수로써 타입 힌트를 주로 사용하는 방법을 알아보았습니다. | ||
|
||
이 방법을 **FastAPI**에서도 주로 사용하게 됩니다. | ||
|
||
### Simple 타입 | ||
|
||
`str`뿐 아니라 모든 파이썬 표준 타입을 선언할 수 있습니다. | ||
|
||
예를 들면: | ||
|
||
* `int` | ||
* `float` | ||
* `bool` | ||
* `bytes` | ||
|
||
```Python hl_lines="1" | ||
{!../../../docs_src/python_types/tutorial005.py!} | ||
``` | ||
|
||
### 타입 매개변수를 활용한 Generic(제네릭) 타입 | ||
|
||
`dict`, `list`, `set`, `tuple`과 같은 값을 저장할 수 있는 데이터 구조가 있고, 내부의 값은 각자의 타입을 가질 수도 있습니다. | ||
|
||
타입과 내부 타입을 선언하기 위해서는 파이썬 표준 모듈인 `typing`을 이용해야 합니다. | ||
|
||
구체적으로는 아래 타입 힌트를 지원합니다. | ||
|
||
#### `List` | ||
|
||
예를 들면, `str`의 `list`인 변수를 정의해봅시다. | ||
|
||
`typing`에서 `List`(대문자 `L`)를 import 합니다. | ||
|
||
```Python hl_lines="1" | ||
{!../../../docs_src/python_types/tutorial006.py!} | ||
``` | ||
|
||
콜론(`:`) 문법을 이용하여 변수를 선언합니다. | ||
|
||
타입으로는 `List`를 넣어줍니다. | ||
|
||
이때 배열은 내부 타입을 포함하는 타입이기 때문에 대괄호 안에 넣어줍니다. | ||
|
||
```Python hl_lines="4" | ||
{!../../../docs_src/python_types/tutorial006.py!} | ||
``` | ||
|
||
!!! tip | ||
대괄호 안의 내부 타입은 "타입 매개변수(type paramters)"라고 합니다. | ||
|
||
이번 예제에서는 `str`이 `List`에 들어간 타입 매개변수 입니다. | ||
|
||
이는 "`items`은 `list`인데, 배열에 들어있는 아이템 각각은 `str`이다"라는 뜻입니다. | ||
|
||
이렇게 함으로써, 에디터는 배열에 들어있는 아이템을 처리할때도 도움을 줄 수 있게 됩니다: | ||
|
||
<img src="/img/python-types/image05.png"> | ||
|
||
타입이 없으면 이건 거의 불가능이나 다름 없습니다. | ||
|
||
변수 `item`은 `items`의 개별 요소라는 사실을 알아두세요. | ||
|
||
그리고 에디터는 계속 `str`라는 사실을 알고 도와줍니다. | ||
|
||
#### `Tuple`과 `Set` | ||
|
||
`tuple`과 `set`도 동일하게 선언할 수 있습니다. | ||
|
||
```Python hl_lines="1 4" | ||
{!../../../docs_src/python_types/tutorial007.py!} | ||
``` | ||
|
||
이 뜻은 아래와 같습니다: | ||
|
||
* 변수 `items_t`는, 차례대로 `int`, `int`, `str`인 `tuple`이다. | ||
* 변수 `items_s`는, 각 아이템이 `bytes`인 `set`이다. | ||
|
||
#### `Dict` | ||
|
||
`dict`를 선언하려면 컴마로 구분된 2개의 파라미터가 필요합니다. | ||
|
||
첫 번째 매개변수는 `dict`의 키(key)이고, | ||
|
||
두 번째 매개변수는 `dict`의 값(value)입니다. | ||
|
||
```Python hl_lines="1 4" | ||
{!../../../docs_src/python_types/tutorial008.py!} | ||
``` | ||
|
||
이 뜻은 아래와 같습니다: | ||
|
||
* 변수 `prices`는 `dict`이다: | ||
* `dict`의 키(key)는 `str`타입이다. (각 아이템의 이름(name)) | ||
* `dict`의 값(value)는 `float`타입이다. (각 아이템의 가격(price)) | ||
|
||
#### `Optional` | ||
|
||
`str`과 같이 타입을 선언할 때 `Optional`을 쓸 수도 있는데, "선택적(Optional)"이기때문에 `None`도 될 수 있습니다: | ||
|
||
```Python hl_lines="1 4" | ||
{!../../../docs_src/python_types/tutorial009.py!} | ||
``` | ||
|
||
`Optional[str]`을 `str` 대신 쓰게 되면, 특정 값이 실제로는 `None`이 될 수도 있는데 항상 `str`이라고 가정하는 상황에서 에디터가 에러를 찾게 도와줄 수 있습니다. | ||
|
||
#### Generic(제네릭) 타입 | ||
|
||
이 타입은 대괄호 안에 매개변수를 가지며, 종류는: | ||
|
||
* `List` | ||
* `Tuple` | ||
* `Set` | ||
* `Dict` | ||
* `Optional` | ||
* ...등등 | ||
|
||
위와 같은 타입은 **Generic(제네릭) 타입** 혹은 **Generics(제네릭스)**라고 불립니다. | ||
|
||
### 타입으로써의 클래스 | ||
|
||
변수의 타입으로 클래스를 선언할 수도 있습니다. | ||
|
||
이름(name)을 가진 `Person` 클래스가 있다고 해봅시다. | ||
|
||
```Python hl_lines="1-3" | ||
{!../../../docs_src/python_types/tutorial010.py!} | ||
``` | ||
|
||
그렇게 하면 변수를 `Person`이라고 선언할 수 있게 됩니다. | ||
|
||
```Python hl_lines="6" | ||
{!../../../docs_src/python_types/tutorial010.py!} | ||
``` | ||
|
||
그리고 역시나 모든 에디터 도움을 받게 되겠죠. | ||
|
||
<img src="/img/python-types/image06.png"> | ||
|
||
## Pydantic 모델 | ||
|
||
<a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a>은 데이터 검증(Validation)을 위한 파이썬 라이브러리입니다. | ||
|
||
당신은 속성들을 포함한 클래스 형태로 "모양(shape)"을 선언할 수 있습니다. | ||
|
||
그리고 각 속성은 타입을 가지고 있습니다. | ||
|
||
이 클래스를 활용하여서 값을 가지고 있는 인스턴스를 만들게 되면, 필요한 경우에는 적당한 타입으로 변환까지 시키기도 하여 데이터가 포함된 객체를 반환합니다. | ||
|
||
그리고 결과 객체에 대해서는 에디터의 도움을 받을 수 있게 됩니다. | ||
|
||
Pydantic 공식 문서 예시: | ||
|
||
```Python | ||
{!../../../docs_src/python_types/tutorial011.py!} | ||
``` | ||
|
||
!!! info | ||
Pydantic<에 대해 더 배우고 싶다면 <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">공식 문서</a>를 참고하세요.</a> | ||
|
||
|
||
**FastAPI**는 모두 Pydantic을 기반으로 되어 있습니다. | ||
|
||
[Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}에서 이번 연습보다 더 많은 내용을 볼 수 있습니다. | ||
|
||
## **FastAPI**에서의 타입 힌트 | ||
|
||
**FastAPI**는 여러 부분에서 타입 힌트의 장점을 취하고 있습니다. | ||
|
||
**FastAPI**에서 타입 힌트를 썼을 때 얻는 장점은: | ||
* **에디터 도움**. | ||
* **타입 확인**. | ||
|
||
...그리고 **FastAPI**는 같은 정의를 아래에도 적용합니다: | ||
|
||
* **요구사항 정의**: 리퀘스트 경로 파라미터, 쿼리 파라미터, 헤더, 바디, 의존성 등. | ||
* **데이터 변환**: 리퀘스트에서 요구된 타입으로. | ||
* **데이터 검증**: 각 리퀘스트마다: | ||
* 데이터가 유효하지 않은 경우에는 **자동으로 에러**를 발생합니다. | ||
* OpenAPI를 활용한 **API 문서화**: | ||
* 자동으로 상호작용하는 유저 인터페이스에 쓰이게 됩니다. | ||
|
||
위 내용이 다소 추상적일 수도 있지만, 걱정마세요. [Tutorial - User Guide](tutorial/index.md){.internal-link target=_blank}에서 전부 확인 가능합니다. | ||
|
||
가장 중요한 건, 파이썬 표준 타입을 한 곳에서(클래스를 더하거나, 데코레이터 사용하는 대신) 사용함으로써 **FastAPI**가 당신을 위해 많은 일을 해준다는 사실이죠. | ||
|
||
!!! info | ||
만약 모든 튜토리얼을 다 보았음에도 타입에 대해서 더 보고자 방문한 경우에는 <a href="https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html" class="external-link" target="_blank">`mypy`에서 제공하는 "cheat sheet"</a>이 좋은 자료가 될 겁니다. |