Irfanuddin Shafi Ahmed
1 year ago
committed by
GitHub
GitHub
95 changed files with 4130 additions and 462 deletions
@ -0,0 +1,4 @@ |
|||
PyGithub |
|||
pydantic>=2.5.3,<3.0.0 |
|||
pydantic-settings>=2.1.0,<3.0.0 |
|||
httpx |
|||
@ -0,0 +1,464 @@ |
|||
<p align="center"> |
|||
<a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" alt="FastAPI"></a> |
|||
</p> |
|||
<p align="center"> |
|||
<em>FastAPI উচ্চক্ষমতা সম্পন্ন, সহজে শেখার এবং দ্রুত কোড করে প্রোডাকশনের জন্য ফ্রামওয়ার্ক।</em> |
|||
</p> |
|||
<p align="center"> |
|||
<a href="https://github.com/tiangolo/fastapi/actions?query=workflow%3ATest" target="_blank"> |
|||
<img src="https://github.com/tiangolo/fastapi/workflows/Test/badge.svg" alt="Test"> |
|||
</a> |
|||
<a href="https://codecov.io/gh/tiangolo/fastapi" target="_blank"> |
|||
<img src="https://img.shields.io/codecov/c/github/tiangolo/fastapi?color=%2334D058" alt="Coverage"> |
|||
</a> |
|||
<a href="https://pypi.org/project/fastapi" target="_blank"> |
|||
<img src="https://img.shields.io/pypi/v/fastapi?color=%2334D058&label=pypi%20package" alt="Package version"> |
|||
</a> |
|||
</p> |
|||
|
|||
--- |
|||
|
|||
**নির্দেশিকা নথি**: <a href="https://fastapi.tiangolo.com" target="_blank">https://fastapi.tiangolo.com</a> |
|||
|
|||
**সোর্স কোড**: <a href="https://github.com/tiangolo/fastapi" target="_blank">https://github.com/tiangolo/fastapi</a> |
|||
|
|||
--- |
|||
|
|||
FastAPI একটি আধুনিক, দ্রুত ( বেশি ক্ষমতা ) সম্পন্ন, Python 3.6+ দিয়ে API তৈরির জন্য স্ট্যান্ডার্ড পাইথন টাইপ ইঙ্গিত ভিত্তিক ওয়েব ফ্রেমওয়ার্ক। |
|||
|
|||
এর মূল বৈশিষ্ট্য গুলো হলঃ |
|||
|
|||
- **গতি**: এটি **NodeJS** এবং **Go** এর মত কার্যক্ষমতা সম্পন্ন (Starlette এবং Pydantic এর সাহায্যে)। [পাইথন এর দ্রুততম ফ্রেমওয়ার্ক গুলোর মধ্যে এটি একটি](#_11)। |
|||
- **দ্রুত কোড করা**:বৈশিষ্ট্য তৈরির গতি ২০০% থেকে ৩০০% বৃদ্ধি করে৷ \* |
|||
- **স্বল্প bugs**: মানুব (ডেভেলপার) সৃষ্ট ত্রুটির প্রায় ৪০% হ্রাস করে। \* |
|||
- **স্বজ্ঞাত**: দুর্দান্ত এডিটর সাহায্য <abbr title="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> নামেও পরিচিত। দ্রুত ডিবাগ করা যায়। |
|||
|
|||
- **সহজ**: এটি এমন ভাবে সজানো হয়েছে যেন নির্দেশিকা নথি পড়ে সহজে শেখা এবং ব্যবহার করা যায়। |
|||
- **সংক্ষিপ্ত**: কোড পুনরাবৃত্তি কমানোর পাশাপাশি, bug কমায় এবং প্রতিটি প্যারামিটার ঘোষণা থেকে একাধিক ফিচার পাওয়া যায় । |
|||
- **জোরালো**: স্বয়ংক্রিয় ভাবে তৈরি ক্রিয়াশীল নির্দেশনা নথি (documentation) সহ উৎপাদন উপযোগি (Production-ready) কোড পাওয়া যায়। |
|||
- **মান-ভিত্তিক**: এর ভিত্তি <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> (যা পুর্বে Swagger নামে পরিচিত ছিল) এবং <a href="https://json-schema.org/" class="external-link" target="_blank">JSON Schema</a> এর আদর্শের মানের ওপর |
|||
|
|||
<small>\* উৎপাদনমুখি এপ্লিকেশন বানানোর এক দল ডেভেলপার এর মতামত ভিত্তিক ফলাফল।</small> |
|||
|
|||
## স্পনসর গণ |
|||
|
|||
<!-- sponsors --> |
|||
|
|||
{% if sponsors %} |
|||
{% for sponsor in sponsors.gold -%} |
|||
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a> |
|||
{% endfor -%} |
|||
{%- for sponsor in sponsors.silver -%} |
|||
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a> |
|||
{% endfor %} |
|||
{% endif %} |
|||
|
|||
<!-- /sponsors --> |
|||
|
|||
<a href="https://fastapi.tiangolo.com/fastapi-people/#sponsors" class="external-link" target="_blank">অন্যান্য স্পনসর গণ</a> |
|||
|
|||
## মতামত সমূহ |
|||
|
|||
"_আমি আজকাল **FastAPI** ব্যবহার করছি। [...] আমরা ভাবছি মাইক্রোসফ্টে **ML সার্ভিস** এ সকল দলের জন্য এটি ব্যবহার করব। যার মধ্যে কিছু পণ্য **Windows** এ সংযোযন হয় এবং কিছু **Office** এর সাথে সংযোযন হচ্ছে।_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">কবির খান - <strong>মাইক্রোসফ্টে</strong> <a href="https://github.com/tiangolo/fastapi/pull/26" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_আমরা **FastAPI** লাইব্রেরি গ্রহণ করেছি একটি **REST** সার্ভার তৈরি করতে, যা **ভবিষ্যদ্বাণী** পাওয়ার জন্য কুয়েরি করা যেতে পারে। [লুডউইগের জন্য]_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">পিয়েরো মোলিনো, ইয়ারোস্লাভ দুদিন, এবং সাই সুমন্থ মিরিয়ালা - <strong>উবার</strong> <a href="https://eng.uber.com/ludwig-v0-2/" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_**Netflix** আমাদের **ক্রাইসিস ম্যানেজমেন্ট** অর্কেস্ট্রেশন ফ্রেমওয়ার্ক: **ডিসপ্যাচ** এর ওপেন সোর্স রিলিজ ঘোষণা করতে পেরে আনন্দিত! [যাকিনা **FastAPI** দিয়ে নির্মিত]_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">কেভিন গ্লিসন, মার্ক ভিলানোভা, ফরেস্ট মনসেন - <strong>নেটফ্লিক্স</strong> <a href="https://netflixtechblog.com/introducing-dispatch-da4b8a2a8072" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_আমি **FastAPI** নিয়ে চাঁদের সমান উৎসাহিত। এটি খুবই মজার!_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">ব্রায়ান ওকেন - <strong><a href="https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855" target="_blank">পাইথন বাইটস</a> পডকাস্ট হোস্ট</strong> <a href="https://twitter.com/brianokken/status/1112220079972728832" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"\_সত্যিই, আপনি যা তৈরি করেছেন তা খুব মজবুত এবং পরিপূর্ন৷ অনেক উপায়ে, আমি যা **Hug** এ করতে চেয়েছিলাম - তা কাউকে তৈরি করতে দেখে আমি সত্যিই অনুপ্রানিত৷\_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">টিমোথি ক্রসলে - <strong><a href="https://www.hug.rest/" target="_blank">Hug</a> স্রষ্টা</strong> <a href="https://news.ycombinator.com/item?id=19455465" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"আপনি যদি REST API তৈরির জন্য একটি **আধুনিক ফ্রেমওয়ার্ক** শিখতে চান, তাহলে **FastAPI** দেখুন [...] এটি দ্রুত, ব্যবহার করা সহজ এবং শিখতেও সহজ [...]\_" |
|||
|
|||
"_আমরা আমাদের **APIs** [...] এর জন্য **FastAPI**- তে এসেছি [...] আমি মনে করি আপনিও এটি পছন্দ করবেন [...]_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">ইনেস মন্টানি - ম্যাথিউ হোনিবাল - <strong><a href="https://explosion.ai" target="_blank">Explosion AI</a> প্রতিষ্ঠাতা - <a href="https://spacy.io" target="_blank">spaCy</a> স্রষ্টা</strong> <a href="https://twitter.com/_inesmontani/status/1144173225322143744" target="_blank"><small>(ref)</small></a> - <a href="https://twitter.com/honnibal/status/1144031421859655680" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
## **Typer**, CLI এর জন্য FastAPI |
|||
|
|||
<a href="https://typer.tiangolo.com" target="_blank"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" style="width: 20%;"></a> |
|||
|
|||
আপনি যদি <abbr title="Command Line Interface">CLI</abbr> অ্যাপ বানাতে চান, যা কিনা ওয়েব API এর পরিবর্তে টার্মিনালে ব্যবহার হবে, তাহলে দেখুন<a href="https://typer.tiangolo.com/" class="external-link" target="_blank">**Typer**</a>. |
|||
|
|||
**টাইপার** হল FastAPI এর ছোট ভাইয়ের মত। এবং এটির উদ্দেশ্য ছিল **CLIs এর FastAPI** হওয়া। ⌨️ 🚀 |
|||
|
|||
## প্রয়োজনীয়তা গুলো |
|||
|
|||
Python 3.7+ |
|||
|
|||
FastAPI কিছু দানবেদের কাঁধে দাঁড়িয়ে আছে: |
|||
|
|||
- <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> ওয়েব অংশের জন্য. |
|||
- <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a> ডেটা অংশগুলির জন্য. |
|||
|
|||
## ইনস্টলেশন প্রক্রিয়া |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install fastapi |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
আপনার একটি ASGI সার্ভারেরও প্রয়োজন হবে, প্রোডাকশনের জন্য <a href="https://www.uvicorn.org" class="external-link" target="_blank">Uvicorn</a> অথবা <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>. |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "uvicorn[standard]" |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
## উদাহরণ |
|||
|
|||
### তৈরি |
|||
|
|||
- `main.py` নামে একটি ফাইল তৈরি করুন: |
|||
|
|||
```Python |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.get("/") |
|||
def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
``` |
|||
|
|||
<details markdown="1"> |
|||
<summary>অথবা ব্যবহার করুন <code>async def</code>...</summary> |
|||
|
|||
যদি আপনার কোড `async` / `await`, ব্যবহার করে তাহলে `async def` ব্যবহার করুন: |
|||
|
|||
```Python hl_lines="9 14" |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.get("/") |
|||
async def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
async def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
``` |
|||
|
|||
**টীকা**: |
|||
|
|||
আপনি যদি না জানেন, _"তাড়াহুড়ো?"_ বিভাগটি দেখুন <a href="https://fastapi.tiangolo.com/async/#in-a-hurry" target="_blank">`async` এবং `await` নথির মধ্যে দেখুন </a>. |
|||
|
|||
</details> |
|||
|
|||
### এটি চালান |
|||
|
|||
সার্ভার চালু করুন: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
INFO: Started reloader process [28720] |
|||
INFO: Started server process [28722] |
|||
INFO: Waiting for application startup. |
|||
INFO: Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
<details markdown="1"> |
|||
<summary>নির্দেশনা সম্পর্কে <code>uvicorn main:app --reload</code>...</summary> |
|||
|
|||
`uvicorn main:app` নির্দেশনাটি দ্বারা বোঝায়: |
|||
|
|||
- `main`: ফাইল `main.py` (পাইথন "মডিউল")। |
|||
- `app`: `app = FastAPI()` লাইন দিয়ে `main.py` এর ভিতরে তৈরি করা অবজেক্ট। |
|||
- `--reload`: কোড পরিবর্তনের পরে সার্ভার পুনরায় চালু করুন। এটি শুধুমাত্র ডেভেলপমেন্ট এর সময় ব্যবহার করুন। |
|||
|
|||
</details> |
|||
|
|||
### এটা চেক করুন |
|||
|
|||
আপনার ব্রাউজার খুলুন <a href="http://127.0.0.1:8000/items/5?q=somequery" class="external-link" target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a> এ। |
|||
|
|||
আপনি JSON রেসপন্স দেখতে পাবেন: |
|||
|
|||
```JSON |
|||
{"item_id": 5, "q": "somequery"} |
|||
``` |
|||
|
|||
আপনি ইতিমধ্যে একটি API তৈরি করেছেন যা: |
|||
|
|||
- `/` এবং `/items/{item_id}` _paths_ এ HTTP অনুরোধ গ্রহণ করে। |
|||
- উভয় *path*ই `GET` <em>অপারেশন</em> নেয় ( যা HTTP _methods_ নামেও পরিচিত)। |
|||
- _path_ `/items/{item_id}`-এ একটি _path প্যারামিটার_ `item_id` আছে যা কিনা `int` হতে হবে। |
|||
- _path_ `/items/{item_id}`-এর একটি ঐচ্ছিক `str` _query প্যারামিটার_ `q` আছে। |
|||
|
|||
### ক্রিয়াশীল API নির্দেশিকা নথি |
|||
|
|||
এখন যান <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
|||
|
|||
আপনি স্বয়ংক্রিয় ভাবে প্রস্তুত ক্রিয়াশীল API নির্দেশিকা নথি দেখতে পাবেন (<a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a> প্রদত্ত): |
|||
|
|||
 |
|||
|
|||
### বিকল্প API নির্দেশিকা নথি |
|||
|
|||
এবং এখন <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a> এ যান. |
|||
|
|||
আপনি স্বয়ংক্রিয় ভাবে প্রস্তুত বিকল্প নির্দেশিকা নথি দেখতে পাবেন (<a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a> প্রদত্ত): |
|||
|
|||
 |
|||
|
|||
## উদাহরণস্বরূপ আপগ্রেড |
|||
|
|||
এখন `main.py` ফাইলটি পরিবর্তন করুন যেন এটি `PUT` রিকুয়েস্ট থেকে বডি পেতে পারে। |
|||
|
|||
Python স্ট্যান্ডার্ড লাইব্রেরি, Pydantic এর সাহায্যে বডি ঘোষণা করুন। |
|||
|
|||
```Python hl_lines="4 9-12 25-27" |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
price: float |
|||
is_offer: Union[bool, None] = None |
|||
|
|||
|
|||
@app.get("/") |
|||
def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
|
|||
|
|||
@app.put("/items/{item_id}") |
|||
def update_item(item_id: int, item: Item): |
|||
return {"item_name": item.name, "item_id": item_id} |
|||
``` |
|||
|
|||
সার্ভারটি স্বয়ংক্রিয়ভাবে পুনরায় লোড হওয়া উচিত (কারণ আপনি উপরের `uvicorn` কমান্ডে `--reload` যোগ করেছেন)। |
|||
|
|||
### ক্রিয়াশীল API নির্দেশিকা নথি উন্নীতকরণ |
|||
|
|||
এখন <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a> এডড্রেসে যান. |
|||
|
|||
- ক্রিয়াশীল API নির্দেশিকা নথিটি স্বয়ংক্রিয়ভাবে উন্নীত হযে যাবে, নতুন বডি সহ: |
|||
|
|||
 |
|||
|
|||
- "Try it out" বাটনে চাপুন, এটি আপনাকে পেরামিটারগুলো পূরণ করতে এবং API এর সাথে সরাসরি ক্রিয়া-কলাপ করতে দিবে: |
|||
|
|||
 |
|||
|
|||
- তারপরে "Execute" বাটনে চাপুন, ব্যবহারকারীর ইন্টারফেস আপনার API এর সাথে যোগাযোগ করবে, পেরামিটার পাঠাবে, ফলাফলগুলি পাবে এবং সেগুলি পর্রদায় দেখাবে: |
|||
|
|||
 |
|||
|
|||
### বিকল্প API নির্দেশিকা নথি আপগ্রেড |
|||
|
|||
এবং এখন <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a> এ যান। |
|||
|
|||
- বিকল্প নির্দেশিকা নথিতেও নতুন কুয়েরি প্যারামিটার এবং বডি প্রতিফলিত হবে: |
|||
|
|||
 |
|||
|
|||
### সংক্ষিপ্তকরণ |
|||
|
|||
সংক্ষেপে, আপনি **শুধু একবার** প্যারামিটারের ধরন, বডি ইত্যাদি ফাংশন প্যারামিটার হিসেবে ঘোষণা করেন। |
|||
|
|||
আপনি সেটি আধুনিক পাইথনের সাথে করেন। |
|||
|
|||
আপনাকে নতুন করে নির্দিষ্ট কোন লাইব্রেরির বাক্য গঠন, ফাংশন বা ক্লাস কিছুই শিখতে হচ্ছে না। |
|||
|
|||
শুধুই আধুনিক **Python 3.6+** |
|||
|
|||
উদাহরণস্বরূপ, `int` এর জন্য: |
|||
|
|||
```Python |
|||
item_id: int |
|||
``` |
|||
|
|||
অথবা আরও জটিল `Item` মডেলের জন্য: |
|||
|
|||
```Python |
|||
item: Item |
|||
``` |
|||
|
|||
...এবং সেই একই ঘোষণার সাথে আপনি পাবেন: |
|||
|
|||
- এডিটর সাহায্য, যেমন |
|||
- সমাপ্তি। |
|||
- ধরণ যাচাই |
|||
- তথ্য যাচাইকরণ: |
|||
- ডেটা অবৈধ হলে স্বয়ংক্রিয় এবং পরিষ্কার ত্রুটির নির্দেশনা। |
|||
- এমনকি গভীরভাবে নেস্ট করা JSON অবজেক্টের জন্য বৈধতা। |
|||
- প্রেরিত তথ্য <abbr title="যা পরিচিত: serialization, parsing, marshalling">রূপান্তর</abbr>: যা নেটওয়ার্ক থেকে পাইথনের তথ্য এবং ধরনে আসে, এবং সেখান থেকে পড়া: |
|||
|
|||
- JSON। |
|||
- পাথ প্যারামিটার। |
|||
- কুয়েরি প্যারামিটার। |
|||
- কুকিজ |
|||
- হেডার |
|||
- ফর্ম |
|||
- ফাইল |
|||
|
|||
- আউটপুট ডেটার <abbr title="যা পরিচিত: serialization, parsing, marshalling">রূপান্তর</abbr>: পাইথন ডেটা এবং টাইপ থেকে নেটওয়ার্ক ডেটাতে রূপান্তর করা (JSON হিসাবে): |
|||
-পাইথন টাইপে রূপান্তর করুন (`str`, `int`, `float`, `bool`, `list`, ইত্যাদি)। |
|||
- `datetime` অবজেক্ট। |
|||
- `UUID` objeঅবজেক্টcts। |
|||
- ডাটাবেস মডেল। |
|||
- ...এবং আরো অনেক। |
|||
- স্বয়ংক্রিয় ক্রিয়াশীল API নির্দেশিকা নথি, 2টি বিকল্প ব্যবহারকারীর ইন্টারফেস সহ: |
|||
- সোয়াগার ইউ আই (Swagger UI)। |
|||
- রিডক (ReDoc)। |
|||
|
|||
--- |
|||
|
|||
পূর্ববর্তী কোড উদাহরণে ফিরে আসা যাক, **FastAPI** যা করবে: |
|||
|
|||
- `GET` এবং `PUT` অনুরোধের জন্য পথে `item_id` আছে কিনা তা যাচাই করবে। |
|||
- `GET` এবং `PUT` অনুরোধের জন্য `item_id` টাইপ `int` এর হতে হবে তা যাচাই করবে। |
|||
- যদি না হয় তবে ক্লায়েন্ট একটি উপযুক্ত, পরিষ্কার ত্রুটি দেখতে পাবেন। |
|||
- `GET` অনুরোধের জন্য একটি ঐচ্ছিক ক্যুয়েরি প্যারামিটার নামক `q` (যেমন `http://127.0.0.1:8000/items/foo?q=somequery`) আছে কি তা চেক করবে। |
|||
- যেহেতু `q` প্যারামিটারটি `= None` দিয়ে ঘোষণা করা হয়েছে, তাই এটি ঐচ্ছিক। |
|||
- `None` ছাড়া এটি প্রয়োজনীয় হতো (যেমন `PUT` এর ক্ষেত্রে হয়েছে)। |
|||
- `/items/{item_id}` এর জন্য `PUT` অনুরোধের বডি JSON হিসাবে পড়ুন: |
|||
- লক্ষ করুন, `name` একটি প্রয়োজনীয় অ্যাট্রিবিউট হিসাবে বিবেচনা করেছে এবং এটি `str` হতে হবে। |
|||
- লক্ষ করুন এখানে, `price` অ্যাট্রিবিউটটি আবশ্যক এবং এটি `float` হতে হবে। |
|||
- লক্ষ করুন `is_offer` একটি ঐচ্ছিক অ্যাট্রিবিউট এবং এটি `bool` হতে হবে যদি উপস্থিত থাকে। |
|||
- এই সবটি গভীরভাবে অবস্থানরত JSON অবজেক্টগুলিতেও কাজ করবে। |
|||
- স্বয়ংক্রিয়ভাবে JSON হতে এবং JSON থেকে কনভার্ট করুন। |
|||
- OpenAPI দিয়ে সবকিছু ডকুমেন্ট করুন, যা ব্যবহার করা যেতে পারে: |
|||
- ক্রিয়াশীল নির্দেশিকা নথি। |
|||
- অনেক ভাষার জন্য স্বয়ংক্রিয় ক্লায়েন্ট কোড তৈরির ব্যবস্থা। |
|||
- সরাসরি 2টি ক্রিয়াশীল নির্দেশিকা নথি ওয়েব পৃষ্ঠ প্রদান করা হয়েছে। |
|||
|
|||
--- |
|||
|
|||
আমরা এতক্ষন শুধু এর পৃষ্ঠ তৈরি করেছি, কিন্তু আপনি ইতমধ্যেই এটি কিভাবে কাজ করে তার ধারণাও পেয়ে গিয়েছেন। |
|||
|
|||
নিম্নোক্ত লাইন গুলো পরিবর্তন করার চেষ্টা করুন: |
|||
|
|||
```Python |
|||
return {"item_name": item.name, "item_id": item_id} |
|||
``` |
|||
|
|||
...পুর্বে: |
|||
|
|||
```Python |
|||
... "item_name": item.name ... |
|||
``` |
|||
|
|||
...পরবর্তীতে: |
|||
|
|||
```Python |
|||
... "item_price": item.price ... |
|||
``` |
|||
|
|||
...এবং দেখুন কিভাবে আপনার এডিটর উপাদানগুলোকে সয়ংক্রিয়ভাবে-সম্পন্ন করবে এবং তাদের ধরন জানতে পারবে: |
|||
|
|||
 |
|||
|
|||
আরও বৈশিষ্ট্য সম্পন্ন উদাহরণের জন্য, দেখুন <a href="https://fastapi.tiangolo.com/tutorial/">টিউটোরিয়াল - ব্যবহারকারীর গাইড</a>. |
|||
|
|||
**স্পয়লার সতর্কতা**: টিউটোরিয়াল - ব্যবহারকারীর গাইড নিম্নোক্ত বিষয়গুলি অন্তর্ভুক্ত করে: |
|||
|
|||
- **হেডার**, **কুকিজ**, **ফর্ম ফিল্ড** এবং **ফাইলগুলি** এমন অন্যান্য জায়গা থেকে প্যারামিটার ঘোষণা করা। |
|||
- `maximum_length` বা `regex` এর মতো **যাচাইকরণ বাধামুক্তি** সেট করা হয় কিভাবে, তা নিয়ে আলোচনা করা হবে। |
|||
- একটি খুব শক্তিশালী এবং ব্যবহার করা সহজ <abbr title="also known as components, resources, providers, services, injectables">ডিপেন্ডেন্সি ইনজেকশন</abbr> পদ্ধতি |
|||
- **OAuth2** এবং **JWT টোকেন** এবং **HTTP Basic** auth সহ নিরাপত্তা এবং অনুমোদনপ্রাপ্তি সম্পর্কিত বিষয়সমূহের উপর। |
|||
- **গভীরভাবে অবস্থানরত JSON মডেল** ঘোষণা করার জন্য আরও উন্নত (কিন্তু সমান সহজ) কৌশল (Pydantic কে ধন্যবাদ)। |
|||
- আরো অতিরিক্ত বৈশিষ্ট্য (স্টারলেটকে ধন্যবাদ) হিসাবে: |
|||
- **WebSockets** |
|||
- **GraphQL** |
|||
- HTTPX এবং `pytest` ভিত্তিক অত্যন্ত সহজ পরীক্ষা |
|||
- **CORS** |
|||
- **Cookie Sessions** |
|||
- ...এবং আরো। |
|||
|
|||
## কর্মক্ষমতা |
|||
|
|||
স্বাধীন TechEmpower Benchmarks দেখায় যে **FastAPI** অ্যাপ্লিকেশনগুলি Uvicorn-এর অধীনে চলমান দ্রুততম<a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">পাইথন ফ্রেমওয়ার্কগুলির মধ্যে একটি,</a> শুধুমাত্র Starlette এবং Uvicorn-এর পর (FastAPI দ্বারা অভ্যন্তরীণভাবে ব্যবহৃত)। (\*) |
|||
|
|||
এটি সম্পর্কে আরও বুঝতে, দেখুন <a href="https://fastapi.tiangolo.com/benchmarks/" class="internal-link" target="_blank">Benchmarks</a>. |
|||
|
|||
## ঐচ্ছিক নির্ভরশীলতা |
|||
|
|||
Pydantic দ্বারা ব্যবহৃত: |
|||
|
|||
- <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - দ্রুত JSON এর জন্য <abbr title="converting the string that comes from an HTTP request into Python data">"parsing"</abbr>. |
|||
- <a href="https://github.com/JoshData/python-email-validator" target="_blank"><code>email_validator</code></a> - ইমেল যাচাইকরণের জন্য। |
|||
|
|||
স্টারলেট দ্বারা ব্যবহৃত: |
|||
|
|||
- <a href="https://www.python-httpx.org" target="_blank"><code>httpx</code></a> - আপনি যদি `TestClient` ব্যবহার করতে চান তাহলে আবশ্যক। |
|||
- <a href="https://jinja.palletsprojects.com" target="_blank"><code>jinja2</code></a> - আপনি যদি প্রদত্ত টেমপ্লেট রূপরেখা ব্যবহার করতে চান তাহলে প্রয়োজন। |
|||
- <a href="https://andrew-d.github.io/python-multipart/" target="_blank"><code>python-multipart</code></a> - আপনি যদি ফর্ম সহায়তা করতে চান তাহলে প্রয়োজন <abbr title="converting the string that comes from an HTTP request into Python data">"parsing"</abbr>, `request.form()` সহ। |
|||
- <a href="https://pythonhosted.org/itsdangerous/" target="_blank"><code>itsdangerous</code></a> - `SessionMiddleware` সহায়তার জন্য প্রয়োজন। |
|||
- <a href="https://pyyaml.org/wiki/PyYAMLDocumentation" target="_blank"><code>pyyaml</code></a> - স্টারলেটের SchemaGenerator সাপোর্ট এর জন্য প্রয়োজন (আপনার সম্ভাবত FastAPI প্রয়োজন নেই)। |
|||
- <a href="https://graphene-python.org/" target="_blank"><code>graphene</code></a> - `GraphQLApp` সহায়তার জন্য প্রয়োজন। |
|||
- <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - আপনি `UJSONResponse` ব্যবহার করতে চাইলে প্রয়োজন। |
|||
|
|||
FastAPI / Starlette দ্বারা ব্যবহৃত: |
|||
|
|||
- <a href="https://www.uvicorn.org" target="_blank"><code>uvicorn</code></a> - সার্ভারের জন্য যা আপনার অ্যাপ্লিকেশন লোড করে এবং পরিবেশন করে। |
|||
- <a href="https://github.com/ijl/orjson" target="_blank"><code>orjson</code></a> - আপনি `ORJSONResponse` ব্যবহার করতে চাইলে প্রয়োজন। |
|||
|
|||
আপনি এই সব ইনস্টল করতে পারেন `pip install fastapi[all]` দিয়ে. |
|||
|
|||
## লাইসেন্স |
|||
|
|||
এই প্রজেক্ট MIT লাইসেন্স নীতিমালার অধীনে শর্তায়িত। |
|||
@ -0,0 +1 @@ |
|||
INHERIT: ../en/mkdocs.yml |
|||
@ -0,0 +1,333 @@ |
|||
# Erste Schritte |
|||
|
|||
Die einfachste FastAPI-Datei könnte wie folgt aussehen: |
|||
|
|||
```Python |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
Kopieren Sie dies in eine Datei `main.py`. |
|||
|
|||
Starten Sie den Live-Server: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
<span style="color: green;">INFO</span>: Started reloader process [28720] |
|||
<span style="color: green;">INFO</span>: Started server process [28722] |
|||
<span style="color: green;">INFO</span>: Waiting for application startup. |
|||
<span style="color: green;">INFO</span>: Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
!!! note "Hinweis" |
|||
Der Befehl `uvicorn main:app` bezieht sich auf: |
|||
|
|||
* `main`: die Datei `main.py` (das sogenannte Python-„Modul“). |
|||
* `app`: das Objekt, welches in der Datei `main.py` mit der Zeile `app = FastAPI()` erzeugt wurde. |
|||
* `--reload`: lässt den Server nach Codeänderungen neu starten. Verwenden Sie das nur während der Entwicklung. |
|||
|
|||
In der Konsolenausgabe sollte es eine Zeile geben, die ungefähr so aussieht: |
|||
|
|||
```hl_lines="4" |
|||
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
Diese Zeile zeigt die URL, unter der Ihre Anwendung auf Ihrem lokalen Computer bereitgestellt wird. |
|||
|
|||
### Testen Sie es |
|||
|
|||
Öffnen Sie Ihren Browser unter <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000.</a> |
|||
|
|||
Sie werden folgende JSON-Antwort sehen: |
|||
|
|||
```JSON |
|||
{"message": "Hello World"} |
|||
``` |
|||
|
|||
### Interaktive API-Dokumentation |
|||
|
|||
Gehen Sie als Nächstes auf <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs </a>. |
|||
|
|||
Sie werden die automatisch erzeugte, interaktive API-Dokumentation sehen (bereitgestellt durch <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>): |
|||
|
|||
 |
|||
|
|||
### Alternative API-Dokumentation |
|||
|
|||
Gehen Sie nun auf <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>. |
|||
|
|||
Dort sehen Sie die alternative, automatische Dokumentation (bereitgestellt durch <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>): |
|||
|
|||
 |
|||
|
|||
### OpenAPI |
|||
|
|||
**FastAPI** generiert ein „Schema“ mit all Ihren APIs unter Verwendung des **OpenAPI**-Standards zur Definition von APIs. |
|||
|
|||
#### „Schema“ |
|||
|
|||
Ein „Schema“ ist eine Definition oder Beschreibung von etwas. Nicht der eigentliche Code, der es implementiert, sondern lediglich eine abstrakte Beschreibung. |
|||
|
|||
#### API-„Schema“ |
|||
|
|||
In diesem Fall ist <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> eine Spezifikation, die vorschreibt, wie ein Schema für Ihre API zu definieren ist. |
|||
|
|||
Diese Schemadefinition enthält Ihre API-Pfade, die möglichen Parameter, welche diese entgegennehmen, usw. |
|||
|
|||
#### Daten-„Schema“ |
|||
|
|||
Der Begriff „Schema“ kann sich auch auf die Form von Daten beziehen, wie z.B. einen JSON-Inhalt. |
|||
|
|||
In diesem Fall sind die JSON-Attribute und deren Datentypen, usw. gemeint. |
|||
|
|||
#### OpenAPI und JSON Schema |
|||
|
|||
OpenAPI definiert ein API-Schema für Ihre API. Dieses Schema enthält Definitionen (oder „Schemas“) der Daten, die von Ihrer API unter Verwendung von **JSON Schema**, dem Standard für JSON-Datenschemata, gesendet und empfangen werden. |
|||
|
|||
#### Überprüfen Sie die `openapi.json` |
|||
|
|||
Falls Sie wissen möchten, wie das rohe OpenAPI-Schema aussieht: FastAPI generiert automatisch ein JSON (Schema) mit den Beschreibungen Ihrer gesamten API. |
|||
|
|||
Sie können es direkt einsehen unter: <a href="http://127.0.0.1:8000/openapi.json" class="external-link" target="_blank">http://127.0.0.1:8000/openapi.json</a>. |
|||
|
|||
Es wird ein JSON angezeigt, welches ungefähr so aussieht: |
|||
|
|||
```JSON |
|||
{ |
|||
"openapi": "3.1.0", |
|||
"info": { |
|||
"title": "FastAPI", |
|||
"version": "0.1.0" |
|||
}, |
|||
"paths": { |
|||
"/items/": { |
|||
"get": { |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
|
|||
|
|||
|
|||
... |
|||
``` |
|||
|
|||
#### Wofür OpenAPI gedacht ist |
|||
|
|||
Das OpenAPI-Schema ist die Grundlage für die beiden enthaltenen interaktiven Dokumentationssysteme. |
|||
|
|||
Es gibt dutzende Alternativen, die alle auf OpenAPI basieren. Sie können jede dieser Alternativen problemlos zu Ihrer mit **FastAPI** erstellten Anwendung hinzufügen. |
|||
|
|||
Ebenfalls können Sie es verwenden, um automatisch Code für Clients zu generieren, die mit Ihrer API kommunizieren. Zum Beispiel für Frontend-, Mobile- oder IoT-Anwendungen. |
|||
|
|||
## Rückblick, Schritt für Schritt |
|||
|
|||
### Schritt 1: Importieren von `FastAPI` |
|||
|
|||
```Python hl_lines="1" |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
`FastAPI` ist eine Python-Klasse, die die gesamte Funktionalität für Ihre API bereitstellt. |
|||
|
|||
!!! note "Technische Details" |
|||
`FastAPI` ist eine Klasse, die direkt von `Starlette` erbt. |
|||
|
|||
Sie können alle <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a>-Funktionalitäten auch mit `FastAPI` nutzen. |
|||
|
|||
### Schritt 2: Erzeugen einer `FastAPI`-„Instanz“ |
|||
|
|||
```Python hl_lines="3" |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
In diesem Beispiel ist die Variable `app` eine „Instanz“ der Klasse `FastAPI`. |
|||
|
|||
Dies wird der Hauptinteraktionspunkt für die Erstellung all Ihrer APIs sein. |
|||
|
|||
Die Variable `app` ist dieselbe, auf die sich der Befehl `uvicorn` bezieht: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
Wenn Sie Ihre Anwendung wie folgt erstellen: |
|||
|
|||
```Python hl_lines="3" |
|||
{!../../../docs_src/first_steps/tutorial002.py!} |
|||
``` |
|||
|
|||
Und in eine Datei `main.py` einfügen, dann würden Sie `uvicorn` wie folgt aufrufen: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:my_awesome_api --reload |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
### Schritt 3: Erstellen einer *Pfadoperation* |
|||
|
|||
#### Pfad |
|||
|
|||
„Pfad“ bezieht sich hier auf den letzten Teil der URL, beginnend mit dem ersten `/`. |
|||
|
|||
In einer URL wie: |
|||
|
|||
``` |
|||
https://example.com/items/foo |
|||
``` |
|||
|
|||
... wäre der Pfad folglich: |
|||
|
|||
``` |
|||
/items/foo |
|||
``` |
|||
|
|||
!!! info |
|||
Ein „Pfad“ wird häufig auch als „Endpunkt“ oder „Route“ bezeichnet. |
|||
|
|||
Bei der Erstellung einer API ist der „Pfad“ die wichtigste Möglichkeit zur Trennung von „Anliegen“ und „Ressourcen“. |
|||
|
|||
#### Operation |
|||
|
|||
„Operation“ bezieht sich hier auf eine der HTTP-„Methoden“. |
|||
|
|||
Eine von diesen: |
|||
|
|||
* `POST` |
|||
* `GET` |
|||
* `PUT` |
|||
* `DELETE` |
|||
|
|||
... und die etwas Exotischeren: |
|||
|
|||
* `OPTIONS` |
|||
* `HEAD` |
|||
* `PATCH` |
|||
* `TRACE` |
|||
|
|||
Im HTTP-Protokoll können Sie mit jedem Pfad über eine (oder mehrere) dieser „Methoden“ kommunizieren. |
|||
|
|||
--- |
|||
|
|||
Bei der Erstellung von APIs verwenden Sie normalerweise diese spezifischen HTTP-Methoden, um eine bestimmte Aktion durchzuführen. |
|||
|
|||
Normalerweise verwenden Sie: |
|||
|
|||
* `POST`: um Daten zu erzeugen (create). |
|||
* `GET`: um Daten zu lesen (read). |
|||
* `PUT`: um Daten zu aktualisieren (update). |
|||
* `DELETE`: um Daten zu löschen (delete). |
|||
|
|||
In OpenAPI wird folglich jede dieser HTTP-Methoden als „Operation“ bezeichnet. |
|||
|
|||
Wir werden sie auch „**Operationen**“ nennen. |
|||
|
|||
#### Definieren eines *Pfadoperation-Dekorators* |
|||
|
|||
```Python hl_lines="6" |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
Das `@app.get("/")` sagt **FastAPI**, dass die Funktion direkt darunter für die Bearbeitung von Anfragen zuständig ist, die an: |
|||
|
|||
* den Pfad `/` |
|||
* unter der Verwendung der <abbr title="eine HTTP GET Methode"><code>get</code>-Operation</abbr> gehen |
|||
|
|||
!!! info "`@decorator` Information" |
|||
Diese `@something`-Syntax wird in Python „Dekorator“ genannt. |
|||
|
|||
Sie platzieren ihn über einer Funktion. Wie ein hübscher, dekorativer Hut (daher kommt wohl der Begriff). |
|||
|
|||
Ein „Dekorator“ nimmt die darunter stehende Funktion und macht etwas damit. |
|||
|
|||
In unserem Fall teilt dieser Dekorator **FastAPI** mit, dass die folgende Funktion mit dem **Pfad** `/` und der **Operation** `get` zusammenhängt. |
|||
|
|||
Dies ist der „**Pfadoperation-Dekorator**“. |
|||
|
|||
Sie können auch die anderen Operationen verwenden: |
|||
|
|||
* `@app.post()` |
|||
* `@app.put()` |
|||
* `@app.delete()` |
|||
|
|||
Oder die exotischeren: |
|||
|
|||
* `@app.options()` |
|||
* `@app.head()` |
|||
* `@app.patch()` |
|||
* `@app.trace()` |
|||
|
|||
!!! tip "Tipp" |
|||
Es steht Ihnen frei, jede Operation (HTTP-Methode) so zu verwenden, wie Sie es möchten. |
|||
|
|||
**FastAPI** erzwingt keine bestimmte Bedeutung. |
|||
|
|||
Die hier aufgeführten Informationen dienen als Leitfaden und sind nicht verbindlich. |
|||
|
|||
Wenn Sie beispielsweise GraphQL verwenden, führen Sie normalerweise alle Aktionen nur mit „POST“-Operationen durch. |
|||
|
|||
### Schritt 4: Definieren der **Pfadoperation-Funktion** |
|||
|
|||
Das ist unsere „**Pfadoperation-Funktion**“: |
|||
|
|||
* **Pfad**: ist `/`. |
|||
* **Operation**: ist `get`. |
|||
* **Funktion**: ist die Funktion direkt unter dem „Dekorator“ (unter `@app.get("/")`). |
|||
|
|||
```Python hl_lines="7" |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
Dies ist eine Python-Funktion. |
|||
|
|||
Sie wird von **FastAPI** immer dann aufgerufen, wenn sie eine Anfrage an die URL "`/`" mittels einer `GET`-Operation erhält. |
|||
|
|||
In diesem Fall handelt es sich um eine `async`-Funktion. |
|||
|
|||
--- |
|||
|
|||
Sie könnten sie auch als normale Funktion anstelle von `async def` definieren: |
|||
|
|||
```Python hl_lines="7" |
|||
{!../../../docs_src/first_steps/tutorial003.py!} |
|||
``` |
|||
|
|||
!!! note "Hinweis" |
|||
Wenn Sie den Unterschied nicht kennen, lesen Sie [Async: *„In Eile?“*](../async.md#in-eile){.internal-link target=_blank}. |
|||
|
|||
### Schritt 5: den Inhalt zurückgeben |
|||
|
|||
```Python hl_lines="8" |
|||
{!../../../docs_src/first_steps/tutorial001.py!} |
|||
``` |
|||
|
|||
Sie können ein `dict`, eine `list`, einzelne Werte wie `str`, `int`, usw. zurückgeben. |
|||
|
|||
Sie können auch Pydantic-Modelle zurückgeben (dazu später mehr). |
|||
|
|||
Es gibt viele andere Objekte und Modelle, die automatisch zu JSON konvertiert werden (einschließlich ORMs usw.). Versuchen Sie, Ihre Lieblingsobjekte zu verwenden. Es ist sehr wahrscheinlich, dass sie bereits unterstützt werden. |
|||
|
|||
## Zusammenfassung |
|||
|
|||
* Importieren Sie `FastAPI`. |
|||
* Erstellen Sie eine `app` Instanz. |
|||
* Schreiben Sie einen **Pfadoperation-Dekorator** (wie z.B. `@app.get("/")`). |
|||
* Schreiben Sie eine **Pfadoperation-Funktion** (wie z.B. oben `def root(): ...`). |
|||
* Starten Sie den Entwicklungsserver (z.B. `uvicorn main:app --reload`). |
|||
@ -0,0 +1,3 @@ |
|||
# Acerca de |
|||
|
|||
Acerca de FastAPI, su diseño, inspiración y más. 🤓 |
|||
@ -0,0 +1,3 @@ |
|||
# Ayuda |
|||
|
|||
Ayuda y recibe ayuda, contribuye, involúcrate. 🤝 |
|||
@ -0,0 +1,5 @@ |
|||
# Aprender |
|||
|
|||
Aquí están las secciones introductorias y los tutoriales para aprender **FastAPI**. |
|||
|
|||
Podrías considerar esto como un **libro**, un **curso**, la forma **oficial** y recomendada de aprender FastAPI. 😎 |
|||
@ -0,0 +1,3 @@ |
|||
# Recursos |
|||
|
|||
Recursos adicionales, enlaces externos, artículos y más. ✈️ |
|||
@ -0,0 +1,206 @@ |
|||
# ویژگی ها |
|||
|
|||
## ویژگی های FastAPI |
|||
|
|||
**FastAPI** موارد زیر را به شما ارائه میدهد: |
|||
|
|||
### برپایه استاندارد های باز |
|||
|
|||
* <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank"><strong>OpenAPI</strong></a> برای ساخت API, شامل مشخص سازی <abbr title="که علاوه بر path, به عنوان endpoint و route نیز شناخته میشود">path</abbr> <abbr title="که به عنوان متودهای HTTP یعنی POST,GET,PUT,DELETE و ... شناخته میشوند">operation</abbr> ها, <abbr title="parameters">پارامترها</abbr>, body request ها, امنیت و غیره. |
|||
* مستندسازی خودکار data model با <a href="https://json-schema.org/" class="external-link" target="_blank"><strong>JSON Schema</strong></a> (همانطور که OpenAPI خود نیز مبتنی بر JSON Schema است). |
|||
* طراحی شده بر اساس استاندارد هایی که پس از یک مطالعه دقیق بدست آمده اند بجای طرحی ناپخته و بدون فکر. |
|||
* همچنین به شما اجازه میدهد تا از تولید خودکار client code در بسیاری از زبان ها استفاده کنید. |
|||
|
|||
### مستندات خودکار |
|||
|
|||
مستندات API تعاملی و ایجاد رابط کاربری وب. از آنجایی که این فریم ورک برپایه OpenAPI میباشد، آپشن های متعددی وجود دارد که ۲ مورد بصورت پیش فرض گنجانده شده اند. |
|||
|
|||
* <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank"><strong>Swagger UI</strong></a>، با <abbr title="interactive exploration">کاوش تعاملی</abbr>، API خود را مستقیما از طریق مرورگر صدازده و تست کنید. |
|||
|
|||
 |
|||
|
|||
* مستندات API جایگزین با <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank"><strong>ReDoc</strong></a>. |
|||
|
|||
 |
|||
|
|||
### فقط پایتون مدرن |
|||
|
|||
همه اینها برپایه type declaration های **پایتون ۳.۶** استاندارد (به لطف Pydantic) میباشند. سینتکس جدیدی درکار نیست. تنها پایتون مدرن استاندارد. |
|||
|
|||
اگر به یک یادآوری ۲ دقیقه ای در مورد نحوه استفاده از تایپ های پایتون دارید (حتی اگر از FastAPI استفاده نمیکنید) این آموزش کوتاه را بررسی کنید: [Python Types](python-types.md){.internal-link target=\_blank}. |
|||
|
|||
شما پایتون استاندارد را با استفاده از تایپ ها مینویسید: |
|||
|
|||
```Python |
|||
from datetime import date |
|||
|
|||
from pydantic import BaseModel |
|||
|
|||
# Declare a variable as a str |
|||
# and get editor support inside the function |
|||
def main(user_id: str): |
|||
return user_id |
|||
|
|||
|
|||
# A Pydantic model |
|||
class User(BaseModel): |
|||
id: int |
|||
name: str |
|||
joined: date |
|||
``` |
|||
|
|||
که سپس میتوان به این شکل از آن استفاده کرد: |
|||
|
|||
```Python |
|||
my_user: User = User(id=3, name="John Doe", joined="2018-07-19") |
|||
|
|||
second_user_data = { |
|||
"id": 4, |
|||
"name": "Mary", |
|||
"joined": "2018-11-30", |
|||
} |
|||
|
|||
my_second_user: User = User(**second_user_data) |
|||
``` |
|||
|
|||
!!! info |
|||
`**second_user_data` یعنی: |
|||
|
|||
کلید ها و مقادیر دیکشنری `second_user_data` را مستقیما به عنوان ارگومان های key-value بفرست، که معادل است با : `User(id=4, name="Mary", joined="2018-11-30")` |
|||
|
|||
### پشتیبانی ویرایشگر |
|||
|
|||
تمام فریم ورک به گونه ای طراحی شده که استفاده از آن آسان و شهودی باشد، تمام تصمیمات حتی قبل از شروع توسعه بر روی چندین ویرایشگر آزمایش شده اند، تا از بهترین تجربه توسعه اطمینان حاصل شود. |
|||
|
|||
در آخرین نظرسنجی توسعه دهندگان پایتون کاملا مشخص بود که <a href="https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features" class="external-link" target="_blank">بیشترین ویژگی مورد استفاده از "<abbr title="autocompletion">تکمیل خودکار</abbr>" است</a>. |
|||
|
|||
تمام فریم ورک **FastAPI** برپایه ای برای براورده کردن این نیاز نیز ایجاد گشته است. تکمیل خودکار در همه جا کار میکند. |
|||
|
|||
شما به ندرت نیاز به بازگشت به مستندات را خواهید داشت. |
|||
|
|||
ببینید که چگونه ویرایشگر شما ممکن است به شما کمک کند: |
|||
|
|||
* در <a href="https://code.visualstudio.com/" class="external-link" target="_blank">Visual Studio Code</a>: |
|||
|
|||
 |
|||
|
|||
* در <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a>: |
|||
|
|||
 |
|||
|
|||
شما پیشنهاد های تکمیل خودکاری را خواهید گرفت که حتی ممکن است قبلا آن را غیرممکن تصور میکردید. به عنوان مثال کلید `price` در داخل بدنه JSON (که میتوانست تودرتو نیز باشد) که از یک درخواست آمده است. |
|||
|
|||
دیگر خبری از تایپ کلید اشتباهی، برگشتن به مستندات یا پایین بالا رفتن برای فهمیدن اینکه شما از `username` یا `user_name` استفاده کرده اید نیست. |
|||
|
|||
### مختصر |
|||
|
|||
FastAPI **پیش فرض** های معقولی برای همه چیز دارد، با قابلیت تنظیمات اختیاری در همه جا. تمام پارامترها را میتوانید برای انجام انچه نیاز دارید و برای تعریف API مورد نیاز خود به خوبی تنظیم کنید. |
|||
|
|||
اما به طور پیش فرض، همه چیز **کار میکند**. |
|||
|
|||
### اعتبارسنجی |
|||
|
|||
* اعتبارسنجی برای بیشتر (یا همه؟) **data type** های پایتون، شامل: |
|||
|
|||
* JSON objects (`dict`) |
|||
* آرایه های (`list`) JSON با قابلیت مشخص سازی تایپ ایتم های درون لیست. |
|||
* فیلد های رشته (`str`)، به همراه مشخص سازی حداقل و حداکثر طول رشته. |
|||
* اعداد (`int`,`float`) با حداقل و حداکثر مقدار و غیره. |
|||
|
|||
* اعتبارسنجی برای تایپ های عجیب تر، مثل: |
|||
* URL. |
|||
* Email. |
|||
* UUID. |
|||
* و غیره. |
|||
|
|||
تمام اعتبارسنجی ها توسط کتابخانه اثبات شده و قدرتمند **Pydantic** انجام میشود. |
|||
|
|||
### <abbr title="Security and authentication">امنیت و احراز هویت</abbr> |
|||
|
|||
امنیت و احرازهویت بدون هیچگونه ارتباط و مصالحه ای با پایگاه های داده یا مدل های داده ایجاد شده اند. |
|||
|
|||
تمام طرح های امنیتی در OpenAPI تعریف شده اند، از جمله: |
|||
|
|||
* . |
|||
* **OAuth2** (همچنین با **JWT tokens**). آموزش را در [OAuth2 with JWT](tutorial/security/oauth2-jwt.md){.internal-link target=\_blank} مشاهده کنید. |
|||
* کلید های API: |
|||
* <abbr title="سرصفحه ها">Headers</abbr> |
|||
* <abbr title="پارامترهای پرسمان">Query parameters</abbr> |
|||
* <abbr title="کوکی ها">Cookies</abbr>، و غیره. |
|||
|
|||
به علاوه تمام ویژگی های امنیتی از **Statlette** (شامل **<abbr title="کوکی های جلسه">session cookies</abbr>**) |
|||
|
|||
همه اینها به عنوان ابزارها و اجزای قابل استفاده ای ساخته شده اند که به راحتی با سیستم های شما، مخازن داده، پایگاه های داده رابطه ای و NoSQL و غیره ادغام میشوند. |
|||
|
|||
### <abbr title="تزریق وابستگی">Dependency Injection</abbr> |
|||
|
|||
FastAPI شامل یک سیستم <abbr title='همچنین به عنوان "components", "resources", "services" و "providers" شناخته میشود'><strong>Dependency Injection</strong></abbr> بسیار آسان اما بسیار قدرتمند است. |
|||
|
|||
* حتی وابستگی ها نیز میتوانند وابستگی هایی داشته باشند و یک سلسله مراتب یا **"گرافی" از وابستگی ها** ایجاد کنند. |
|||
|
|||
* همه چیز توسط فریم ورک **به طور خودکار اداره میشود** |
|||
|
|||
* همه وابستگی ها میتوانند به داده های request ها نیاز داشته باشند و مستندات خودکار و محدودیت های <abbr title="عملیات مسیر">path operation</abbr> را **افزایش** دهند. |
|||
|
|||
* با قابلیت **اعتبارسنجی خودکار** حتی برای path operation parameter های تعریف شده در وابستگی ها. |
|||
|
|||
* پشتیبانی از سیستم های پیچیده احرازهویت کاربر، **اتصالات پایگاه داده** و غیره. |
|||
|
|||
* بدون هیچ ارتباطی با دیتابیس ها، فرانت اند و غیره. اما ادغام آسان و راحت با همه آنها. |
|||
|
|||
### پلاگین های نامحدود |
|||
|
|||
یا به عبارت دیگر، هیچ نیازی به آنها نیست، کد موردنیاز خود را وارد و استفاده کنید. |
|||
|
|||
هر یکپارچه سازی به گونه ای طراحی شده است که استفاده از آن بسیار ساده باشد (با وابستگی ها) که میتوانید با استفاده از همان ساختار و روشی که برای _path operation_ های خود استفاده کرده اید تنها در ۲ خط کد "پلاگین" برنامه خودتان را ایجاد کنید. |
|||
|
|||
### تست شده |
|||
|
|||
* 100% <abbr title="مقدار کدی که به طور خودکار تست شده است">پوشش تست</abbr>. |
|||
|
|||
* 100% کد بر اساس <abbr title="حاشیه نویسی تایپ های پایتون (Python type annotations)، با استفاده از آن ویرایشگر و ابزارهای خارجی شما می توانند پشتیبانی بهتری از شما ارائه دهند">type annotate ها</abbr>. |
|||
|
|||
* استفاده شده در اپلیکیشن های تولید |
|||
|
|||
## ویژگی های Starlette |
|||
|
|||
**FastAPI** کاملا (و براساس) با <a href="https://www.starlette.io/" class="external-link" target="_blank"><strong>Starlette</strong></a> سازگار است. بنابراین، هرکد اضافی Starlette که دارید، نیز کار خواهد کرد. |
|||
|
|||
`FastAPI` در واقع یک زیرکلاس از `Starlette` است. بنابراین اگر از قبل Starlette را میشناسید یا با آن کار کرده اید، بیشتر قابلیت ها به همین روش کار خواهد کرد. |
|||
|
|||
با **FastAPI** شما تمام ویژگی های **Starlette** را خواهید داشت (زیرا FastAPI یک نسخه و نمونه به تمام معنا از Starlette است): |
|||
|
|||
* عملکرد به طورجدی چشمگیر. <a href="https://github.com/encode/starlette#performance" class="external-link" target="_blank">این یکی از سریعترین فریم ورک های موجود در پایتون است که همتراز با **نود جی اس** و **گو**</a> است. |
|||
* پشتیبانی از **WebSocket**. |
|||
* <abbr title="In-process background tasks">تسک های درجریان در پس زمینه</abbr>. |
|||
* <abbr title="Startup and shutdown events">رویداد های راه اندازی و متوفق شدن<abbr>. |
|||
* تست کلاینت ساخته شده به روی HTTPX. |
|||
* **CORS**, GZip, فایل های استاتیک, <abbr title="Streaming responses">پاسخ های جریانی</abbr>. |
|||
* پشتیبانی از **نشست ها و کوکی ها**. |
|||
* 100% پوشش با تست. |
|||
* 100% کد براساس type annotate ها. |
|||
|
|||
## ویژگی های Pydantic |
|||
|
|||
**FastAPI** کاملا (و براساس) با <a href="https://pydantic-docs.helpmanual.io" class="external-link" target="_blank"><strong>Pydantic</strong></a> سازگار است. بنابراین هرکد Pydantic اضافی که داشته باشید، نیز کار خواهد کرد. |
|||
|
|||
از جمله کتابخانه های خارجی نیز مبتنی بر Pydantic میتوان به <abbr title="Object-Relational Mapper">ORM</abbr> و <abbr title="Object-Document Mapper">ODM</abbr> ها برای دیتابیس ها اشاره کرد. |
|||
|
|||
این همچنین به این معناست که در خیلی از موارد میتوانید همان ابجکتی که از request میگیرید را **مستقیما به دیتابیس** بفرستید زیرا همه چیز به طور خودکار تأیید میشود. |
|||
|
|||
همین امر برعکس نیز صدق میکند، در بسیاری از موارد شما میتوانید ابجکتی را که از پایگاه داده دریافت میکنید را **مستقیماً به کاربر** ارسال کنید. |
|||
|
|||
با FastAPI شما تمام ویژگی های Pydantic را دراختیار دارید (زیرا FastAPI برای تمام بخش مدیریت دیتا بر اساس Pydantic عمل میکند): |
|||
|
|||
* **خبری از گیج شدن نیست**: |
|||
* هیچ <abbr title="micro-language">زبان خردی</abbr> برای یادگیری تعریف طرحواره های جدید وجود ندارد. |
|||
* اگر تایپ های پایتون را میشناسید، نحوه استفاده از Pydantic را نیز میدانید. |
|||
* به خوبی با **<abbr title="همان Integrated Development Environment, شبیه به ویرایشگر کد">IDE</abbr>/<abbr title="برنامه ای که خطاهای کد را بررسی می کند">linter</abbr>/مغز** شما عمل میکند: |
|||
* به این دلیل که ساختار داده Pydantic فقط نمونه هایی از کلاس هایی هستند که شما تعریف میکنید، تکمیل خودکار، mypy، linting و مشاهده شما باید به درستی با داده های معتبر شما کار کنند. |
|||
* اعتبار سنجی **ساختارهای پیچیده**: |
|||
* استفاده از مدل های سلسله مراتبی Pydantic, `List` و `Dict` کتابخانه `typing` پایتون و غیره. |
|||
* و اعتبارسنج ها اجازه میدهند که طرحواره های داده پیچیده به طور واضح و آسان تعریف، بررسی و بر پایه JSON مستند شوند. |
|||
* شما میتوانید ابجکت های عمیقا تودرتو JSON را که همگی تایید شده و annotated شده اند را داشته باشید. |
|||
* **قابل توسعه**: |
|||
* Pydantic اجازه میدهد تا data type های سفارشی تعریف شوند یا میتوانید اعتبارسنجی را با روش هایی به روی مدل ها با <abbr title="دکوریتور های اعتبارسنج">validator decorator</abbr> گسترش دهید. |
|||
* 100% پوشش با تست. |
|||
@ -0,0 +1,469 @@ |
|||
<p align="center"> |
|||
<a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" alt="FastAPI"></a> |
|||
</p> |
|||
<p align="center"> |
|||
<em>FastAPI keretrendszer, nagy teljesítmény, könnyen tanulható, gyorsan kódolható, productionre kész</em> |
|||
</p> |
|||
<p align="center"> |
|||
<a href="https://github.com/tiangolo/fastapi/actions?query=workflow%3ATest+event%3Apush+branch%3Amaster" target="_blank"> |
|||
<img src="https://github.com/tiangolo/fastapi/workflows/Test/badge.svg?event=push&branch=master" alt="Test"> |
|||
</a> |
|||
<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/tiangolo/fastapi" target="_blank"> |
|||
<img src="https://coverage-badge.samuelcolvin.workers.dev/tiangolo/fastapi.svg" alt="Coverage"> |
|||
</a> |
|||
<a href="https://pypi.org/project/fastapi" target="_blank"> |
|||
<img src="https://img.shields.io/pypi/v/fastapi?color=%2334D058&label=pypi%20package" alt="Package version"> |
|||
</a> |
|||
<a href="https://pypi.org/project/fastapi" target="_blank"> |
|||
<img src="https://img.shields.io/pypi/pyversions/fastapi.svg?color=%2334D058" alt="Supported Python versions"> |
|||
</a> |
|||
</p> |
|||
|
|||
--- |
|||
|
|||
**Dokumentáció**: <a href="https://fastapi.tiangolo.com" target="_blank">https://fastapi.tiangolo.com</a> |
|||
|
|||
**Forrás kód**: <a href="https://github.com/tiangolo/fastapi" target="_blank">https://github.com/tiangolo/fastapi</a> |
|||
|
|||
--- |
|||
A FastAPI egy modern, gyors (nagy teljesítményű), webes keretrendszer API-ok építéséhez Python 3.8+-al, a Python szabványos típusjelöléseire építve. |
|||
|
|||
|
|||
Kulcs funkciók: |
|||
|
|||
* **Gyors**: Nagyon nagy teljesítmény, a **NodeJS**-el és a **Go**-val egyenrangú (a Starlettenek és a Pydantic-nek köszönhetően). [Az egyik leggyorsabb Python keretrendszer](#performance). |
|||
* **Gyorsan kódolható**: A funkciók fejlesztési sebességét 200-300 százalékkal megnöveli. * |
|||
* **Kevesebb hiba**: Körülbelül 40%-al csökkenti az emberi (fejlesztői) hibák számát. * |
|||
* **Intuitív**: Kiváló szerkesztő támogatás. <abbr title="más néven auto-complete, autocompletion, IntelliSense">Kiegészítés</abbr> mindenhol. Kevesebb hibakereséssel töltött idő. |
|||
* **Egyszerű**: Egyszerű tanulásra és használatra tervezve. Kevesebb dokumentáció olvasással töltött idő. |
|||
* **Rövid**: Kód duplikáció minimalizálása. Több funkció minden paraméter deklarálásával. Kevesebb hiba. |
|||
* **Robosztus**: Production ready kód. Automatikus interaktív dokumentáció val. |
|||
* **Szabvány alapú**: Az API-ok nyílt szabványaira alapuló (és azokkal teljesen kompatibilis): <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> (korábban Swagger néven ismert) és a <a href="https://json-schema.org/" class="external-link" target="_blank">JSON Schema</a>. |
|||
|
|||
<small>* Egy production alkalmazásokat építő belső fejlesztői csapat tesztjein alapuló becslés. </small> |
|||
|
|||
## Szponzorok |
|||
|
|||
<!-- sponsors --> |
|||
|
|||
{% if sponsors %} |
|||
{% for sponsor in sponsors.gold -%} |
|||
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a> |
|||
{% endfor -%} |
|||
{%- for sponsor in sponsors.silver -%} |
|||
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a> |
|||
{% endfor %} |
|||
{% endif %} |
|||
|
|||
<!-- /sponsors --> |
|||
|
|||
<a href="https://fastapi.tiangolo.com/fastapi-people/#sponsors" class="external-link" target="_blank">További szponzorok</a> |
|||
|
|||
## Vélemények |
|||
|
|||
"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Kabir Khan - <strong>Microsoft</strong> <a href="https://github.com/tiangolo/fastapi/pull/26" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_We adopted the **FastAPI** library to spawn a **REST** server that can be queried to obtain **predictions**. [for 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/" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_**Netflix** is pleased to announce the open-source release of our **crisis management** orchestration framework: **Dispatch**! [built with **FastAPI**]_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Kevin Glisson, Marc Vilanova, Forest Monsen - <strong>Netflix</strong> <a href="https://netflixtechblog.com/introducing-dispatch-da4b8a2a8072" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_I’m over the moon excited about **FastAPI**. It’s so fun!_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Brian Okken - <strong><a href="https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855" target="_blank">Python Bytes</a> podcast host</strong> <a href="https://twitter.com/brianokken/status/1112220079972728832" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Timothy Crosley - <strong><a href="https://www.hug.rest/" target="_blank">Hug</a> creator</strong> <a href="https://news.ycombinator.com/item?id=19455465" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_If you're looking to learn one **modern framework** for building REST APIs, check out **FastAPI** [...] It's fast, easy to use and easy to learn [...]_" |
|||
|
|||
"_We've switched over to **FastAPI** for our **APIs** [...] I think you'll like it [...]_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Ines Montani - Matthew Honnibal - <strong><a href="https://explosion.ai" target="_blank">Explosion AI</a> founders - <a href="https://spacy.io" target="_blank">spaCy</a> creators</strong> <a href="https://twitter.com/_inesmontani/status/1144173225322143744" target="_blank"><small>(ref)</small></a> - <a href="https://twitter.com/honnibal/status/1144031421859655680" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_If anyone is looking to build a production Python API, I would highly recommend **FastAPI**. It is **beautifully designed**, **simple to use** and **highly scalable**, it has become a **key component** in our API first development strategy and is driving many automations and services such as our Virtual TAC Engineer._" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Deon Pillsbury - <strong>Cisco</strong> <a href="https://www.linkedin.com/posts/deonpillsbury_cisco-cx-python-activity-6963242628536487936-trAp/" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
## **Typer**, a CLI-ok FastAPI-ja |
|||
|
|||
<a href="https://typer.tiangolo.com" target="_blank"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" style="width: 20%;"></a> |
|||
|
|||
Ha egy olyan CLI alkalmazást fejlesztesz amit a parancssorban kell használni webes API helyett, tekintsd meg: <a href="https://typer.tiangolo.com/" class="external-link" target="_blank">**Typer**</a>. |
|||
|
|||
**Typer** a FastAPI kistestvére. A **CLI-k FastAPI-ja**. ⌨️ 🚀 |
|||
|
|||
## Követelmények |
|||
|
|||
Python 3.8+ |
|||
|
|||
A FastAPI óriások vállán áll: |
|||
|
|||
* <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> a webes részekhez. |
|||
* <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a> az adat részekhez. |
|||
|
|||
## Telepítés |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install fastapi |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
A production-höz egy ASGI szerverre is szükség lesz, mint például az <a href="https://www.uvicorn.org" class="external-link" target="_blank">Uvicorn</a> vagy a <a href="https://github.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>. |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "uvicorn[standard]" |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
## Példa |
|||
|
|||
### Hozd létre |
|||
|
|||
* Hozz létre a `main.py` fájlt a következő tartalommal: |
|||
|
|||
```Python |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.get("/") |
|||
def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
``` |
|||
|
|||
<details markdown="1"> |
|||
<summary>Vagy használd az <code>async def</code>-et...</summary> |
|||
|
|||
Ha a kódod `async` / `await`-et, használ `async def`: |
|||
|
|||
```Python hl_lines="9 14" |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.get("/") |
|||
async def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
async def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
``` |
|||
|
|||
**Megjegyzés**: |
|||
|
|||
Ha nem tudod, tekintsd meg a _"Sietsz?"_ szekciót <a href="https://fastapi.tiangolo.com/async/#in-a-hurry" target="_blank">`async` és `await`-ről dokumentációba</a>. |
|||
|
|||
</details> |
|||
|
|||
### Futtasd le |
|||
|
|||
Indítsd el a szervert a következő paranccsal: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
INFO: Started reloader process [28720] |
|||
INFO: Started server process [28722] |
|||
INFO: Waiting for application startup. |
|||
INFO: Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
<details markdown="1"> |
|||
<summary>A parancsról <code>uvicorn main:app --reload</code>...</summary> |
|||
|
|||
A `uvicorn main:app` parancs a következőre utal: |
|||
|
|||
* `main`: fájl `main.py` (a Python "modul"). |
|||
* `app`: a `main.py`-ban a `app = FastAPI()` sorral létrehozott objektum. |
|||
* `--reload`: kód változtatás esetén újra indítja a szervert. Csak fejlesztés közben használandó. |
|||
|
|||
</details> |
|||
|
|||
### Ellenőrizd |
|||
|
|||
Nyisd meg a böngésződ a következő címen: <a href="http://127.0.0.1:8000/items/5?q=somequery" class="external-link" target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a>. |
|||
|
|||
A következő JSON választ fogod látni: |
|||
|
|||
```JSON |
|||
{"item_id": 5, "q": "somequery"} |
|||
``` |
|||
|
|||
Máris létrehoztál egy API-t ami: |
|||
|
|||
* HTTP kéréseket fogad a `/` és `/items/{item_id}` _útvonalakon_. |
|||
* Mindkét _útvonal_ a `GET` <em>műveletet</em> használja (másik elnevezés: HTTP _metódus_). |
|||
* A `/items/{item_id}` _útvonalnak_ van egy _path paramétere_, az `item_id`, aminek `int` típusúnak kell lennie. |
|||
* A `/items/{item_id}` _útvonalnak_ még van egy opcionális, `str` típusú _query paramétere_ is, a `q`. |
|||
|
|||
### Interaktív API dokumentáció |
|||
|
|||
Most nyisd meg a <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a> címet. |
|||
|
|||
Az automatikus interaktív API dokumentációt fogod látni (amit a <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>-al hozunk létre): |
|||
|
|||
 |
|||
|
|||
### Alternatív API dokumentáció |
|||
|
|||
És most menj el a <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a> címre. |
|||
|
|||
Az alternatív automatikus dokumentációt fogod látni. (lásd <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>): |
|||
|
|||
 |
|||
|
|||
## Példa frissítése |
|||
|
|||
Módosítsuk a `main.py` fájlt, hogy `PUT` kérések esetén tudjon body-t fogadni. |
|||
|
|||
Deklaráld a body-t standard Python típusokkal, a Pydantic-nak köszönhetően. |
|||
|
|||
```Python hl_lines="4 9-12 25-27" |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
price: float |
|||
is_offer: Union[bool, None] = None |
|||
|
|||
|
|||
@app.get("/") |
|||
def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
|
|||
|
|||
@app.put("/items/{item_id}") |
|||
def update_item(item_id: int, item: Item): |
|||
return {"item_name": item.name, "item_id": item_id} |
|||
``` |
|||
|
|||
A szerver automatikusan újraindul (mert hozzáadtuk a --reload paramétert a fenti `uvicorn` parancshoz). |
|||
|
|||
### Interaktív API dokumentáció frissítése |
|||
|
|||
Most menj el a <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a> címre. |
|||
|
|||
* Az interaktív API dokumentáció automatikusan frissült így már benne van az új body. |
|||
|
|||
 |
|||
|
|||
* Kattints rá a "Try it out" gombra, ennek segítségével kitöltheted a paramétereket és közvetlen használhatod az API-t: |
|||
|
|||
 |
|||
|
|||
* Ezután kattints az "Execute" gompra, a felhasználói felület kommunikálni fog az API-oddal. Elküldi a paramétereket és a visszakapott választ megmutatja a képernyődön. |
|||
|
|||
 |
|||
|
|||
### Alternatív API dokumentáció frissítés |
|||
|
|||
Most menj el a <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a> címre. |
|||
|
|||
* Az alternatív dokumentáció szintúgy tükrözni fogja az új kérési paraméter és body-t. |
|||
|
|||
 |
|||
|
|||
### Összefoglalás |
|||
|
|||
Összegzésül, deklarálod **egyszer** a paraméterek, body, stb típusát funkciós paraméterekként. |
|||
|
|||
Ezt standard modern Python típusokkal csinálod. |
|||
|
|||
Nem kell új szintaxist, vagy specifikus könyvtár mert metódósait, stb. megtanulnod. |
|||
|
|||
Csak standard **Python 3.8+**. |
|||
|
|||
Például egy `int`-nek: |
|||
|
|||
```Python |
|||
item_id: int |
|||
``` |
|||
|
|||
Egy komplexebb `Item` modellnek: |
|||
|
|||
```Python |
|||
item: Item |
|||
``` |
|||
|
|||
... És csupán egy deklarációval megkapod a: |
|||
|
|||
* Szerkesztő támogatást, beleértve: |
|||
* Szövegkiegészítés. |
|||
* Típus ellenőrzés. |
|||
* Adatok validációja: |
|||
* Automatikus és érthető hibák amikor az adatok hibásak. |
|||
* Validáció mélyen ágyazott objektumok esetén is. |
|||
* Bemeneti adatok<abbr title="also known as: serialization, parsing, marshalling"> átváltása</abbr> : a hálózatról érkező Python adatokká és típusokká. Adatok olvasása következő forrásokból: |
|||
* JSON. |
|||
* Cím paraméterek. |
|||
* Query paraméterek. |
|||
* Cookie-k. |
|||
* Header-ök. |
|||
* Formok. |
|||
* Fájlok. |
|||
* Kimeneti adatok <abbr title=" más néven: serialization, parsing, marshalling">átváltása</abbr>: Python adatok is típusokról hálózati adatokká: |
|||
* válts át Python típusokat (`str`, `int`, `float`, `bool`, `list`, etc). |
|||
* `datetime` csak objektumokat. |
|||
* `UUID` objektumokat. |
|||
* Adatbázis modelleket. |
|||
* ...És sok mást. |
|||
* Automatikus interaktív dokumentáció, beleértve két alternatív dokumentációt is: |
|||
* Swagger UI. |
|||
* ReDoc. |
|||
|
|||
--- |
|||
|
|||
Visszatérve az előző kód példához. A **FastAPI**: |
|||
|
|||
* Validálja hogy van egy `item_id` mező a `GET` és `PUT` kérésekben. |
|||
* Validálja hogy az `item_id` `int` típusú a `GET` és `PUT` kérésekben. |
|||
* Ha nem akkor látni fogunk egy tiszta hibát ezzel kapcsolatban. |
|||
* ellenőrzi hogyha van egy opcionális query paraméter `q` névvel (azaz `http://127.0.0.1:8000/items/foo?q=somequery`) `GET` kérések esetén. |
|||
* Mivel a `q` paraméter `= None`-al van deklarálva, ezért opcionális. |
|||
* `None` nélkül ez a mező kötelező lenne (mint például a body `PUT` kérések esetén). |
|||
* a `/items/{item_id}` címre érkező `PUT` kérések esetén, a JSON-t a következőképpen olvassa be: |
|||
* Ellenőrzi hogy létezik a kötelező `name` nevű attribútum és `string`. |
|||
* Ellenőrzi hogy létezik a kötelező `price` nevű attribútum és `float`. |
|||
* Ellenőrzi hogy létezik a `is_offer` nevű opcionális paraméter, ami ha létezik akkor `bool` |
|||
* Ez ágyazott JSON objektumokkal is működik |
|||
* JSONről való automatikus konvertálás. |
|||
* dokumentáljuk mindent OpenAPI-al amit használható: |
|||
* Interaktív dokumentációs rendszerekkel. |
|||
* Automatikus kliens kód generáló a rendszerekkel, több nyelven. |
|||
* Hozzá tartozik kettő interaktív dokumentációs web felület. |
|||
|
|||
--- |
|||
|
|||
Eddig csak a felszínt kapargattuk, de a lényeg hogy most már könnyebben érthető hogyan működik. |
|||
|
|||
Próbáld kicserélni a következő sorban: |
|||
|
|||
```Python |
|||
return {"item_name": item.name, "item_id": item_id} |
|||
``` |
|||
|
|||
...ezt: |
|||
|
|||
```Python |
|||
... "item_name": item.name ... |
|||
``` |
|||
|
|||
...erre: |
|||
|
|||
```Python |
|||
... "item_price": item.price ... |
|||
``` |
|||
|
|||
... És figyeld meg hogy a szerkesztő automatikusan tudni fogja a típusokat és kiegészíti azokat: |
|||
|
|||
 |
|||
|
|||
Teljesebb példákért és funkciókért tekintsd meg a <a href="https://fastapi.tiangolo.com/tutorial/">Tutorial - User Guide</a> -t. |
|||
|
|||
**Spoiler veszély**: a Tutorial - User Guidehoz tartozik: |
|||
|
|||
* **Paraméterek** deklarációja különböző helyekről: **header-ök**, **cookie-k**, **form mezők** és **fájlok**. |
|||
* Hogyan állíts be **validációs feltételeket** mint a `maximum_length` vagy a `regex`. |
|||
* Nagyon hatékony és erős **<abbr title="also known as components, resources, providers, services, injectables">Függőség Injekció</abbr>** rendszerek. |
|||
* Biztonság és autentikáció beleértve, **OAuth2**, **JWT tokens** és **HTTP Basic** támogatást. |
|||
* Több haladó (de ugyanannyira könnyű) technika **mélyen ágyazott JSON modellek deklarációjára** (Pydantic-nek köszönhetően). |
|||
* **GraphQL** integráció <a href="https://strawberry.rocks" class="external-link" target="_blank">Strawberry</a>-vel és más könyvtárakkal. |
|||
* több extra funkció (Starlette-nek köszönhetően) pl.: |
|||
* **WebSockets** |
|||
* rendkívül könnyű tesztek HTTPX és `pytest` alapokra építve |
|||
* **CORS** |
|||
* **Cookie Sessions** |
|||
* ...és több. |
|||
|
|||
## Teljesítmény |
|||
|
|||
A független TechEmpower benchmarkok szerint az Uvicorn alatt futó **FastAPI** alkalmazások az <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">egyik leggyorsabb Python keretrendszerek közé tartoznak</a>, éppen lemaradva a Starlette és az Uvicorn (melyeket a FastAPI belsőleg használ) mögött.(*) |
|||
|
|||
Ezeknek a további megértéséhez: <a href="https://fastapi.tiangolo.com/benchmarks/" class="internal-link" target="_blank">Benchmarks</a>. |
|||
|
|||
## Opcionális követelmények |
|||
|
|||
Pydantic által használt: |
|||
|
|||
* <a href="https://github.com/JoshData/python-email-validator" target="_blank"><code>email_validator</code></a> - e-mail validációkra. |
|||
* <a href="https://docs.pydantic.dev/latest/usage/pydantic_settings/" target="_blank"><code>pydantic-settings</code></a> - Beállítások követésére. |
|||
* <a href="https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/" target="_blank"><code>pydantic-extra-types</code></a> - Extra típusok Pydantic-hoz. |
|||
|
|||
Starlette által használt: |
|||
|
|||
* <a href="https://www.python-httpx.org" target="_blank"><code>httpx</code></a> - Követelmény ha a `TestClient`-et akarod használni. |
|||
* <a href="https://jinja.palletsprojects.com" target="_blank"><code>jinja2</code></a> - Követelmény ha az alap template konfigurációt akarod használni. |
|||
* <a href="https://andrew-d.github.io/python-multipart/" target="_blank"><code>python-multipart</code></a> - Követelmény ha <abbr title="converting the string that comes from an HTTP request into Python data">"parsing"</abbr>-ot akarsz támogatni, `request.form()`-al. |
|||
* <a href="https://pythonhosted.org/itsdangerous/" target="_blank"><code>itsdangerous</code></a> - Követelmény `SessionMiddleware` támogatáshoz. |
|||
* <a href="https://pyyaml.org/wiki/PyYAMLDocumentation" target="_blank"><code>pyyaml</code></a> - Követelmény a Starlette `SchemaGenerator`-ának támogatásához (valószínűleg erre nincs szükség FastAPI használása esetén). |
|||
* <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - Követelmény ha `UJSONResponse`-t akarsz használni. |
|||
|
|||
FastAPI / Starlette által használt |
|||
|
|||
* <a href="https://www.uvicorn.org" target="_blank"><code>uvicorn</code></a> - Szerverekhez amíg betöltik és szolgáltatják az applikációdat. |
|||
* <a href="https://github.com/ijl/orjson" target="_blank"><code>orjson</code></a> - Követelmény ha `ORJSONResponse`-t akarsz használni. |
|||
|
|||
Ezeket mind telepítheted a `pip install "fastapi[all]"` paranccsal. |
|||
|
|||
## Licensz |
|||
Ez a projekt az MIT license, licensz alatt fut |
|||
@ -0,0 +1 @@ |
|||
INHERIT: ../en/mkdocs.yml |
|||
@ -0,0 +1,182 @@ |
|||
aa: Afaraf |
|||
ab: аҧсуа бызшәа |
|||
ae: avesta |
|||
af: Afrikaans |
|||
ak: Akan |
|||
am: አማርኛ |
|||
an: aragonés |
|||
ar: اللغة العربية |
|||
as: অসমীয়া |
|||
av: авар мацӀ |
|||
ay: aymar aru |
|||
az: azərbaycan dili |
|||
ba: башҡорт теле |
|||
be: беларуская мова |
|||
bg: български език |
|||
bh: भोजपुरी |
|||
bi: Bislama |
|||
bm: bamanankan |
|||
bn: বাংলা |
|||
bo: བོད་ཡིག |
|||
br: brezhoneg |
|||
bs: bosanski jezik |
|||
ca: Català |
|||
ce: нохчийн мотт |
|||
ch: Chamoru |
|||
co: corsu |
|||
cr: ᓀᐦᐃᔭᐍᐏᐣ |
|||
cs: čeština |
|||
cu: ѩзыкъ словѣньскъ |
|||
cv: чӑваш чӗлхи |
|||
cy: Cymraeg |
|||
da: dansk |
|||
de: Deutsch |
|||
dv: Dhivehi |
|||
dz: རྫོང་ཁ |
|||
ee: Eʋegbe |
|||
el: Ελληνικά |
|||
en: English |
|||
eo: Esperanto |
|||
es: español |
|||
et: eesti |
|||
eu: euskara |
|||
fa: فارسی |
|||
ff: Fulfulde |
|||
fi: suomi |
|||
fj: Vakaviti |
|||
fo: føroyskt |
|||
fr: français |
|||
fy: Frysk |
|||
ga: Gaeilge |
|||
gd: Gàidhlig |
|||
gl: galego |
|||
gu: ગુજરાતી |
|||
gv: Gaelg |
|||
ha: هَوُسَ |
|||
he: עברית |
|||
hi: हिन्दी |
|||
ho: Hiri Motu |
|||
hr: Hrvatski |
|||
ht: Kreyòl ayisyen |
|||
hu: magyar |
|||
hy: Հայերեն |
|||
hz: Otjiherero |
|||
ia: Interlingua |
|||
id: Bahasa Indonesia |
|||
ie: Interlingue |
|||
ig: Asụsụ Igbo |
|||
ii: ꆈꌠ꒿ Nuosuhxop |
|||
ik: Iñupiaq |
|||
io: Ido |
|||
is: Íslenska |
|||
it: italiano |
|||
iu: ᐃᓄᒃᑎᑐᑦ |
|||
ja: 日本語 |
|||
jv: basa Jawa |
|||
ka: ქართული |
|||
kg: Kikongo |
|||
ki: Gĩkũyũ |
|||
kj: Kuanyama |
|||
kk: қазақ тілі |
|||
kl: kalaallisut |
|||
km: ខេមរភាសា |
|||
kn: ಕನ್ನಡ |
|||
ko: 한국어 |
|||
kr: Kanuri |
|||
ks: कश्मीरी |
|||
ku: Kurdî |
|||
kv: коми кыв |
|||
kw: Kernewek |
|||
ky: Кыргызча |
|||
la: latine |
|||
lb: Lëtzebuergesch |
|||
lg: Luganda |
|||
li: Limburgs |
|||
ln: Lingála |
|||
lo: ພາສາ |
|||
lt: lietuvių kalba |
|||
lu: Tshiluba |
|||
lv: latviešu valoda |
|||
mg: fiteny malagasy |
|||
mh: Kajin M̧ajeļ |
|||
mi: te reo Māori |
|||
mk: македонски јазик |
|||
ml: മലയാളം |
|||
mn: Монгол хэл |
|||
mr: मराठी |
|||
ms: Bahasa Malaysia |
|||
mt: Malti |
|||
my: ဗမာစာ |
|||
na: Ekakairũ Naoero |
|||
nb: Norsk bokmål |
|||
nd: isiNdebele |
|||
ne: नेपाली |
|||
ng: Owambo |
|||
nl: Nederlands |
|||
nn: Norsk nynorsk |
|||
'no': Norsk |
|||
nr: isiNdebele |
|||
nv: Diné bizaad |
|||
ny: chiCheŵa |
|||
oc: occitan |
|||
oj: ᐊᓂᔑᓈᐯᒧᐎᓐ |
|||
om: Afaan Oromoo |
|||
or: ଓଡ଼ିଆ |
|||
os: ирон æвзаг |
|||
pa: ਪੰਜਾਬੀ |
|||
pi: पाऴि |
|||
pl: Polski |
|||
ps: پښتو |
|||
pt: português |
|||
qu: Runa Simi |
|||
rm: rumantsch grischun |
|||
rn: Ikirundi |
|||
ro: Română |
|||
ru: русский язык |
|||
rw: Ikinyarwanda |
|||
sa: संस्कृतम् |
|||
sc: sardu |
|||
sd: सिन्धी |
|||
se: Davvisámegiella |
|||
sg: yângâ tî sängö |
|||
si: සිංහල |
|||
sk: slovenčina |
|||
sl: slovenščina |
|||
sn: chiShona |
|||
so: Soomaaliga |
|||
sq: shqip |
|||
sr: српски језик |
|||
ss: SiSwati |
|||
st: Sesotho |
|||
su: Basa Sunda |
|||
sv: svenska |
|||
sw: Kiswahili |
|||
ta: தமிழ் |
|||
te: తెలుగు |
|||
tg: тоҷикӣ |
|||
th: ไทย |
|||
ti: ትግርኛ |
|||
tk: Türkmen |
|||
tl: Wikang Tagalog |
|||
tn: Setswana |
|||
to: faka Tonga |
|||
tr: Türkçe |
|||
ts: Xitsonga |
|||
tt: татар теле |
|||
tw: Twi |
|||
ty: Reo Tahiti |
|||
ug: ئۇيغۇرچە |
|||
uk: українська мова |
|||
ur: اردو |
|||
uz: Ўзбек |
|||
ve: Tshivenḓa |
|||
vi: Tiếng Việt |
|||
vo: Volapük |
|||
wa: walon |
|||
wo: Wollof |
|||
xh: isiXhosa |
|||
yi: ייִדיש |
|||
yo: Yorùbá |
|||
za: Saɯ cueŋƅ |
|||
zh: 汉语 |
|||
zu: isiZulu |
|||
@ -0,0 +1,5 @@ |
|||
# Обучение |
|||
|
|||
Здесь представлены вводные разделы и учебные пособия для изучения **FastAPI**. |
|||
|
|||
Вы можете считать это **книгой**, **курсом**, **официальным** и рекомендуемым способом изучения FastAPI. 😎 |
|||
@ -0,0 +1,314 @@ |
|||
# Загрузка файлов |
|||
|
|||
Используя класс `File`, мы можем позволить клиентам загружать файлы. |
|||
|
|||
!!! info "Дополнительная информация" |
|||
Чтобы получать загруженные файлы, сначала установите <a href="https://andrew-d.github.io/python-multipart/" class="external-link" target="_blank">`python-multipart`</a>. |
|||
|
|||
Например: `pip install python-multipart`. |
|||
|
|||
Это связано с тем, что загружаемые файлы передаются как данные формы. |
|||
|
|||
## Импорт `File` |
|||
|
|||
Импортируйте `File` и `UploadFile` из модуля `fastapi`: |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="3" |
|||
{!> ../../../docs_src/request_files/tutorial001_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../../docs_src/request_files/tutorial001_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../../docs_src/request_files/tutorial001.py!} |
|||
``` |
|||
|
|||
## Определите параметры `File` |
|||
|
|||
Создайте параметры `File` так же, как вы это делаете для `Body` или `Form`: |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="9" |
|||
{!> ../../../docs_src/request_files/tutorial001_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="8" |
|||
{!> ../../../docs_src/request_files/tutorial001_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="7" |
|||
{!> ../../../docs_src/request_files/tutorial001.py!} |
|||
``` |
|||
|
|||
!!! info "Дополнительная информация" |
|||
`File` - это класс, который наследуется непосредственно от `Form`. |
|||
|
|||
Но помните, что когда вы импортируете `Query`, `Path`, `File` и другие из `fastapi`, на самом деле это функции, которые возвращают специальные классы. |
|||
|
|||
!!! tip "Подсказка" |
|||
Для объявления тела файла необходимо использовать `File`, поскольку в противном случае параметры будут интерпретироваться как параметры запроса или параметры тела (JSON). |
|||
|
|||
Файлы будут загружены как данные формы. |
|||
|
|||
Если вы объявите тип параметра у *функции операции пути* как `bytes`, то **FastAPI** прочитает файл за вас, и вы получите его содержимое в виде `bytes`. |
|||
|
|||
Следует иметь в виду, что все содержимое будет храниться в памяти. Это хорошо подходит для небольших файлов. |
|||
|
|||
Однако возможны случаи, когда использование `UploadFile` может оказаться полезным. |
|||
|
|||
## Загрузка файла с помощью `UploadFile` |
|||
|
|||
Определите параметр файла с типом `UploadFile`: |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="14" |
|||
{!> ../../../docs_src/request_files/tutorial001_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="13" |
|||
{!> ../../../docs_src/request_files/tutorial001_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="12" |
|||
{!> ../../../docs_src/request_files/tutorial001.py!} |
|||
``` |
|||
|
|||
Использование `UploadFile` имеет ряд преимуществ перед `bytes`: |
|||
|
|||
* Использовать `File()` в значении параметра по умолчанию не обязательно. |
|||
* При этом используется "буферный" файл: |
|||
* Файл, хранящийся в памяти до максимального предела размера, после преодоления которого он будет храниться на диске. |
|||
* Это означает, что он будет хорошо работать с большими файлами, такими как изображения, видео, большие бинарные файлы и т.д., не потребляя при этом всю память. |
|||
* Из загруженного файла можно получить метаданные. |
|||
* Он реализует <a href="https://docs.python.org/3/glossary.html#term-file-like-object" class="external-link" target="_blank">file-like</a> `async` интерфейс. |
|||
* Он предоставляет реальный объект Python <a href="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile" class="external-link" target="_blank">`SpooledTemporaryFile`</a> который вы можете передать непосредственно другим библиотекам, которые ожидают файл в качестве объекта. |
|||
|
|||
### `UploadFile` |
|||
|
|||
`UploadFile` имеет следующие атрибуты: |
|||
|
|||
* `filename`: Строка `str` с исходным именем файла, который был загружен (например, `myimage.jpg`). |
|||
* `content_type`: Строка `str` с типом содержимого (MIME type / media type) (например, `image/jpeg`). |
|||
* `file`: <a href="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile" class="external-link" target="_blank">`SpooledTemporaryFile`</a> (a <a href="https://docs.python.org/3/glossary.html#term-file-like-object" class="external-link" target="_blank">file-like</a> объект). Это фактический файл Python, который можно передавать непосредственно другим функциям или библиотекам, ожидающим файл в качестве объекта. |
|||
|
|||
`UploadFile` имеет следующие методы `async`. Все они вызывают соответствующие файловые методы (используя внутренний SpooledTemporaryFile). |
|||
|
|||
* `write(data)`: Записать данные `data` (`str` или `bytes`) в файл. |
|||
* `read(size)`: Прочитать количество `size` (`int`) байт/символов из файла. |
|||
* `seek(offset)`: Перейти к байту на позиции `offset` (`int`) в файле. |
|||
* Наример, `await myfile.seek(0)` перейдет к началу файла. |
|||
* Это особенно удобно, если вы один раз выполнили команду `await myfile.read()`, а затем вам нужно прочитать содержимое файла еще раз. |
|||
* `close()`: Закрыть файл. |
|||
|
|||
Поскольку все эти методы являются `async` методами, вам следует использовать "await" вместе с ними. |
|||
|
|||
Например, внутри `async` *функции операции пути* можно получить содержимое с помощью: |
|||
|
|||
```Python |
|||
contents = await myfile.read() |
|||
``` |
|||
|
|||
Если вы находитесь внутри обычной `def` *функции операции пути*, можно получить прямой доступ к файлу `UploadFile.file`, например: |
|||
|
|||
```Python |
|||
contents = myfile.file.read() |
|||
``` |
|||
|
|||
!!! note "Технические детали `async`" |
|||
При использовании методов `async` **FastAPI** запускает файловые методы в пуле потоков и ожидает их. |
|||
|
|||
!!! note "Технические детали Starlette" |
|||
**FastAPI** наследует `UploadFile` непосредственно из **Starlette**, но добавляет некоторые детали для совместимости с **Pydantic** и другими частями FastAPI. |
|||
|
|||
## Про данные формы ("Form Data") |
|||
|
|||
Способ, которым HTML-формы (`<form></form>`) отправляют данные на сервер, обычно использует "специальную" кодировку для этих данных, отличную от JSON. |
|||
|
|||
**FastAPI** позаботится о том, чтобы считать эти данные из нужного места, а не из JSON. |
|||
|
|||
!!! note "Технические детали" |
|||
Данные из форм обычно кодируются с использованием "media type" `application/x-www-form-urlencoded` когда он не включает файлы. |
|||
|
|||
Но когда форма включает файлы, она кодируется как multipart/form-data. Если вы используете `File`, **FastAPI** будет знать, что ему нужно получить файлы из нужной части тела. |
|||
|
|||
Если вы хотите узнать больше об этих кодировках и полях форм, перейдите по ссылке <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>. |
|||
|
|||
!!! warning "Внимание" |
|||
В операции *функции операции пути* можно объявить несколько параметров `File` и `Form`, но нельзя также объявлять поля `Body`, которые предполагается получить в виде JSON, поскольку тело запроса будет закодировано с помощью `multipart/form-data`, а не `application/json`. |
|||
|
|||
Это не является ограничением **FastAPI**, это часть протокола HTTP. |
|||
|
|||
## Необязательная загрузка файлов |
|||
|
|||
Вы можете сделать загрузку файла необязательной, используя стандартные аннотации типов и установив значение по умолчанию `None`: |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="9 17" |
|||
{!> ../../../docs_src/request_files/tutorial001_02_an_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="9 17" |
|||
{!> ../../../docs_src/request_files/tutorial001_02_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="10 18" |
|||
{!> ../../../docs_src/request_files/tutorial001_02_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.10+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="7 15" |
|||
{!> ../../../docs_src/request_files/tutorial001_02_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="9 17" |
|||
{!> ../../../docs_src/request_files/tutorial001_02.py!} |
|||
``` |
|||
|
|||
## `UploadFile` с дополнительными метаданными |
|||
|
|||
Вы также можете использовать `File()` вместе с `UploadFile`, например, для установки дополнительных метаданных: |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="9 15" |
|||
{!> ../../../docs_src/request_files/tutorial001_03_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="8 14" |
|||
{!> ../../../docs_src/request_files/tutorial001_03_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="7 13" |
|||
{!> ../../../docs_src/request_files/tutorial001_03.py!} |
|||
``` |
|||
|
|||
## Загрузка нескольких файлов |
|||
|
|||
Можно одновременно загружать несколько файлов. |
|||
|
|||
Они будут связаны с одним и тем же "полем формы", отправляемым с помощью данных формы. |
|||
|
|||
Для этого необходимо объявить список `bytes` или `UploadFile`: |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="10 15" |
|||
{!> ../../../docs_src/request_files/tutorial002_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="11 16" |
|||
{!> ../../../docs_src/request_files/tutorial002_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="8 13" |
|||
{!> ../../../docs_src/request_files/tutorial002_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="10 15" |
|||
{!> ../../../docs_src/request_files/tutorial002.py!} |
|||
``` |
|||
|
|||
Вы получите, как и было объявлено, список `list` из `bytes` или `UploadFile`. |
|||
|
|||
!!! note "Technical Details" |
|||
Можно также использовать `from starlette.responses import HTMLResponse`. |
|||
|
|||
**FastAPI** предоставляет тот же `starlette.responses`, что и `fastapi.responses`, просто для удобства разработчика. Однако большинство доступных ответов поступает непосредственно из Starlette. |
|||
|
|||
### Загрузка нескольких файлов с дополнительными метаданными |
|||
|
|||
Так же, как и раньше, вы можете использовать `File()` для задания дополнительных параметров, даже для `UploadFile`: |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="11 18-20" |
|||
{!> ../../../docs_src/request_files/tutorial003_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="12 19-21" |
|||
{!> ../../../docs_src/request_files/tutorial003_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="9 16" |
|||
{!> ../../../docs_src/request_files/tutorial003_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="11 18" |
|||
{!> ../../../docs_src/request_files/tutorial003.py!} |
|||
``` |
|||
|
|||
## Резюме |
|||
|
|||
Используйте `File`, `bytes` и `UploadFile` для работы с файлами, которые будут загружаться и передаваться в виде данных формы. |
|||
@ -0,0 +1,69 @@ |
|||
# Файлы и формы в запросе |
|||
|
|||
Вы можете определять файлы и поля формы одновременно, используя `File` и `Form`. |
|||
|
|||
!!! info "Дополнительная информация" |
|||
Чтобы получать загруженные файлы и/или данные форм, сначала установите <a href="https://andrew-d.github.io/python-multipart/" class="external-link" target="_blank">`python-multipart`</a>. |
|||
|
|||
Например: `pip install python-multipart`. |
|||
|
|||
## Импортируйте `File` и `Form` |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="3" |
|||
{!> ../../../docs_src/request_forms_and_files/tutorial001_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../../docs_src/request_forms_and_files/tutorial001_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="1" |
|||
{!> ../../../docs_src/request_forms_and_files/tutorial001.py!} |
|||
``` |
|||
|
|||
## Определите параметры `File` и `Form` |
|||
|
|||
Создайте параметры файла и формы таким же образом, как для `Body` или `Query`: |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="10-12" |
|||
{!> ../../../docs_src/request_forms_and_files/tutorial001_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="9-11" |
|||
{!> ../../../docs_src/request_forms_and_files/tutorial001_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ без Annotated" |
|||
|
|||
!!! tip "Подсказка" |
|||
Предпочтительнее использовать версию с аннотацией, если это возможно. |
|||
|
|||
```Python hl_lines="8" |
|||
{!> ../../../docs_src/request_forms_and_files/tutorial001.py!} |
|||
``` |
|||
|
|||
Файлы и поля формы будут загружены в виде данных формы, и вы получите файлы и поля формы. |
|||
|
|||
Вы можете объявить некоторые файлы как `bytes`, а некоторые - как `UploadFile`. |
|||
|
|||
!!! warning "Внимание" |
|||
Вы можете объявить несколько параметров `File` и `Form` в операции *path*, но вы не можете также объявить поля `Body`, которые вы ожидаете получить в виде JSON, так как запрос будет иметь тело, закодированное с помощью `multipart/form-data` вместо `application/json`. |
|||
|
|||
Это не ограничение **Fast API**, это часть протокола HTTP. |
|||
|
|||
## Резюме |
|||
|
|||
Используйте `File` и `Form` вместе, когда необходимо получить данные и файлы в одном запросе. |
|||
@ -0,0 +1,33 @@ |
|||
# Harici Bağlantılar ve Makaleler |
|||
|
|||
**FastAPI** sürekli büyüyen harika bir topluluğa sahiptir. |
|||
|
|||
**FastAPI** ile alakalı birçok yazı, makale, araç ve proje bulunmaktadır. |
|||
|
|||
Bunlardan bazılarının tamamlanmamış bir listesi aşağıda bulunmaktadır. |
|||
|
|||
!!! tip "İpucu" |
|||
Eğer **FastAPI** ile alakalı henüz burada listelenmemiş bir makale, proje, araç veya başka bir şeyiniz varsa, bunu eklediğiniz bir <a href="https://github.com/tiangolo/fastapi/edit/master/docs/en/data/external_links.yml" class="external-link" target="_blank">Pull Request</a> oluşturabilirsiniz. |
|||
|
|||
{% for section_name, section_content in external_links.items() %} |
|||
|
|||
## {{ section_name }} |
|||
|
|||
{% for lang_name, lang_content in section_content.items() %} |
|||
|
|||
### {{ lang_name }} |
|||
|
|||
{% for item in lang_content %} |
|||
|
|||
* <a href="{{ item.link }}" class="external-link" target="_blank">{{ item.title }}</a> by <a href="{{ item.author_link }}" class="external-link" target="_blank">{{ item.author }}</a>. |
|||
|
|||
{% endfor %} |
|||
{% endfor %} |
|||
{% endfor %} |
|||
|
|||
## Projeler |
|||
|
|||
`fastapi` konulu en son GitHub projeleri: |
|||
|
|||
<div class="github-topic-projects"> |
|||
</div> |
|||
@ -0,0 +1,5 @@ |
|||
# FastAPI ve Arkadaşları Bülteni |
|||
|
|||
<iframe data-w-type="embedded" frameborder="0" scrolling="no" marginheight="0" marginwidth="0" src="https://xr4n4.mjt.lu/wgt/xr4n4/hj5/form?c=40a44fa4" width="100%" style="height: 0;"></iframe> |
|||
|
|||
<script type="text/javascript" src="https://app.mailjet.com/pas-nc-embedded-v1.js"></script> |
|||
@ -0,0 +1,465 @@ |
|||
<p align="center"> |
|||
<a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" alt="FastAPI"></a> |
|||
</p> |
|||
<p align="center"> |
|||
<em>Готовий до продакшину, високопродуктивний, простий у вивченні та швидкий для написання коду фреймворк</em> |
|||
</p> |
|||
<p align="center"> |
|||
<a href="https://github.com/tiangolo/fastapi/actions?query=workflow%3ATest+event%3Apush+branch%3Amaster" target="_blank"> |
|||
<img src="https://github.com/tiangolo/fastapi/workflows/Test/badge.svg?event=push&branch=master" alt="Test"> |
|||
</a> |
|||
<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/tiangolo/fastapi" target="_blank"> |
|||
<img src="https://coverage-badge.samuelcolvin.workers.dev/tiangolo/fastapi.svg" alt="Coverage"> |
|||
</a> |
|||
<a href="https://pypi.org/project/fastapi" target="_blank"> |
|||
<img src="https://img.shields.io/pypi/v/fastapi?color=%2334D058&label=pypi%20package" alt="Package version"> |
|||
</a> |
|||
<a href="https://pypi.org/project/fastapi" target="_blank"> |
|||
<img src="https://img.shields.io/pypi/pyversions/fastapi.svg?color=%2334D058" alt="Supported Python versions"> |
|||
</a> |
|||
</p> |
|||
|
|||
--- |
|||
|
|||
**Документація**: <a href="https://fastapi.tiangolo.com" target="_blank">https://fastapi.tiangolo.com</a> |
|||
|
|||
**Програмний код**: <a href="https://github.com/tiangolo/fastapi" target="_blank">https://github.com/tiangolo/fastapi</a> |
|||
|
|||
--- |
|||
|
|||
FastAPI - це сучасний, швидкий (високопродуктивний), вебфреймворк для створення API за допомогою Python 3.8+,в основі якого лежить стандартна анотація типів Python. |
|||
|
|||
Ключові особливості: |
|||
|
|||
* **Швидкий**: Дуже висока продуктивність, на рівні з **NodeJS** та **Go** (завдяки Starlette та Pydantic). [Один із найшвидших фреймворків](#performance). |
|||
|
|||
* **Швидке написання коду**: Пришвидшує розробку функціоналу приблизно на 200%-300%. * |
|||
* **Менше помилок**: Зменшить кількість помилок спричинених людиною (розробником) на 40%. * |
|||
* **Інтуїтивний**: Чудова підтримка редакторами коду. <abbr title="Також відоме як auto-complete, autocompletion, IntelliSense.">Доповнення</abbr> всюди. Зменште час на налагодження. |
|||
* **Простий**: Спроектований, для легкого використання та навчання. Знадобиться менше часу на читання документації. |
|||
* **Короткий**: Зведе до мінімуму дублювання коду. Кожен оголошений параметр може виконувати кілька функцій. |
|||
* **Надійний**: Ви матимете стабільний код готовий до продакшину з автоматичною інтерактивною документацією. |
|||
* **Стандартизований**: Оснований та повністю сумісний з відкритими стандартами для API: <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> (попередньо відомий як Swagger) та <a href="https://json-schema.org/" class="external-link" target="_blank">JSON Schema</a>. |
|||
|
|||
<small>* оцінка на основі тестів внутрішньої команди розробників, створення продуктових застосунків.</small> |
|||
|
|||
## Спонсори |
|||
|
|||
<!-- sponsors --> |
|||
|
|||
{% if sponsors %} |
|||
{% for sponsor in sponsors.gold -%} |
|||
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a> |
|||
{% endfor -%} |
|||
{%- for sponsor in sponsors.silver -%} |
|||
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a> |
|||
{% endfor %} |
|||
{% endif %} |
|||
|
|||
<!-- /sponsors --> |
|||
|
|||
<a href="https://fastapi.tiangolo.com/fastapi-people/#sponsors" class="external-link" target="_blank">Other sponsors</a> |
|||
|
|||
## Враження |
|||
|
|||
"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Kabir Khan - <strong>Microsoft</strong> <a href="https://github.com/tiangolo/fastapi/pull/26" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_We adopted the **FastAPI** library to spawn a **REST** server that can be queried to obtain **predictions**. [for 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/" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_**Netflix** is pleased to announce the open-source release of our **crisis management** orchestration framework: **Dispatch**! [built with **FastAPI**]_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Kevin Glisson, Marc Vilanova, Forest Monsen - <strong>Netflix</strong> <a href="https://netflixtechblog.com/introducing-dispatch-da4b8a2a8072" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_I’m over the moon excited about **FastAPI**. It’s so fun!_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Brian Okken - <strong><a href="https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855" target="_blank">Python Bytes</a> podcast host</strong> <a href="https://twitter.com/brianokken/status/1112220079972728832" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Timothy Crosley - <strong><a href="https://www.hug.rest/" target="_blank">Hug</a> creator</strong> <a href="https://news.ycombinator.com/item?id=19455465" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
"_If you're looking to learn one **modern framework** for building REST APIs, check out **FastAPI** [...] It's fast, easy to use and easy to learn [...]_" |
|||
|
|||
"_We've switched over to **FastAPI** for our **APIs** [...] I think you'll like it [...]_" |
|||
|
|||
<div style="text-align: right; margin-right: 10%;">Ines Montani - Matthew Honnibal - <strong><a href="https://explosion.ai" target="_blank">Explosion AI</a> founders - <a href="https://spacy.io" target="_blank">spaCy</a> creators</strong> <a href="https://twitter.com/_inesmontani/status/1144173225322143744" target="_blank"><small>(ref)</small></a> - <a href="https://twitter.com/honnibal/status/1144031421859655680" target="_blank"><small>(ref)</small></a></div> |
|||
|
|||
--- |
|||
|
|||
## **Typer**, FastAPI CLI |
|||
|
|||
<a href="https://typer.tiangolo.com" target="_blank"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" style="width: 20%;"></a> |
|||
|
|||
Створюючи <abbr title="Command Line Interface">CLI</abbr> застосунок для використання в терміналі, замість веб-API зверніть увагу на <a href="https://typer.tiangolo.com/" class="external-link" target="_blank">**Typer**</a>. |
|||
|
|||
**Typer** є молодшим братом FastAPI. І це **FastAPI для CLI**. ⌨️ 🚀 |
|||
|
|||
## Вимоги |
|||
|
|||
Python 3.8+ |
|||
|
|||
FastAPI стоїть на плечах гігантів: |
|||
|
|||
* <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> для web частини. |
|||
* <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a> для частини даних. |
|||
|
|||
## Вставновлення |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install fastapi |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
Вам також знадобиться сервер ASGI для продакшину, наприклад <a href="https://www.uvicorn.org" class="external-link" target="_blank">Uvicorn</a> або <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>. |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install uvicorn[standard] |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
## Приклад |
|||
|
|||
### Створіть |
|||
|
|||
* Створіть файл `main.py` з: |
|||
|
|||
```Python |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.get("/") |
|||
def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
``` |
|||
|
|||
<details markdown="1"> |
|||
<summary>Або використайте <code>async def</code>...</summary> |
|||
|
|||
Якщо ваш код використовує `async` / `await`, скористайтеся `async def`: |
|||
|
|||
```Python hl_lines="9 14" |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
@app.get("/") |
|||
async def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
async def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
``` |
|||
|
|||
**Примітка**: |
|||
|
|||
Стикнувшись з проблемами, не зайвим буде ознайомитися з розділом _"In a hurry?"_ про <a href="https://fastapi.tiangolo.com/async/#in-a-hurry" target="_blank">`async` та `await` у документації</a>. |
|||
|
|||
</details> |
|||
|
|||
### Запустіть |
|||
|
|||
Запустіть server з: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
INFO: Started reloader process [28720] |
|||
INFO: Started server process [28722] |
|||
INFO: Waiting for application startup. |
|||
INFO: Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
<details markdown="1"> |
|||
<summary>Про команди <code>uvicorn main:app --reload</code>...</summary> |
|||
|
|||
Команда `uvicorn main:app` посилається на: |
|||
|
|||
* `main`: файл `main.py` ("Модуль" Python). |
|||
* `app`: об’єкт створений усередині `main.py` рядком `app = FastAPI()`. |
|||
* `--reload`: перезапускає сервер після зміни коду. Використовуйте виключно для розробки. |
|||
|
|||
</details> |
|||
|
|||
### Перевірте |
|||
|
|||
Відкрийте браузер та введіть адресу <a href="http://127.0.0.1:8000/items/5?q=somequery" class="external-link" target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a>. |
|||
|
|||
Ви побачите у відповідь подібний JSON: |
|||
|
|||
```JSON |
|||
{"item_id": 5, "q": "somequery"} |
|||
``` |
|||
|
|||
Ви вже створили API, який: |
|||
|
|||
* Отримує HTTP запити за _шляхами_ `/` та `/items/{item_id}`. |
|||
* Обидва _шляхи_ приймають `GET` <em>операції</em> (також відомі як HTTP _методи_). |
|||
* _Шлях_ `/items/{item_id}` містить _параметр шляху_ `item_id` який має бути типу `int`. |
|||
* _Шлях_ `/items/{item_id}` містить необовʼязковий `str` _параметр запиту_ `q`. |
|||
|
|||
### Інтерактивні документації API |
|||
|
|||
Перейдемо сюди <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
|||
|
|||
Ви побачите автоматичну інтерактивну API документацію (створену завдяки <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>): |
|||
|
|||
 |
|||
|
|||
### Альтернативні документації API |
|||
|
|||
Тепер перейдемо сюди <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>. |
|||
|
|||
Ви побачите альтернативну автоматичну документацію (створену завдяки <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>): |
|||
|
|||
 |
|||
|
|||
## Приклад оновлення |
|||
|
|||
Тепер модифікуйте файл `main.py`, щоб отримати вміст запиту `PUT`. |
|||
|
|||
Оголошуйте вміст запиту за допомогою стандартних типів Python завдяки Pydantic. |
|||
|
|||
```Python hl_lines="4 9-12 25-27" |
|||
from typing import Union |
|||
|
|||
from fastapi import FastAPI |
|||
from pydantic import BaseModel |
|||
|
|||
app = FastAPI() |
|||
|
|||
|
|||
class Item(BaseModel): |
|||
name: str |
|||
price: float |
|||
is_offer: Union[bool, None] = None |
|||
|
|||
|
|||
@app.get("/") |
|||
def read_root(): |
|||
return {"Hello": "World"} |
|||
|
|||
|
|||
@app.get("/items/{item_id}") |
|||
def read_item(item_id: int, q: Union[str, None] = None): |
|||
return {"item_id": item_id, "q": q} |
|||
|
|||
|
|||
@app.put("/items/{item_id}") |
|||
def update_item(item_id: int, item: Item): |
|||
return {"item_name": item.name, "item_id": item_id} |
|||
``` |
|||
|
|||
Сервер повинен автоматично перезавантажуватися (тому що Ви додали `--reload` до `uvicorn` команди вище). |
|||
|
|||
### Оновлення інтерактивної API документації |
|||
|
|||
Тепер перейдемо сюди <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
|||
|
|||
* Інтерактивна документація API буде автоматично оновлена, включаючи новий вміст: |
|||
|
|||
 |
|||
|
|||
* Натисніть кнопку "Try it out", це дозволить вам заповнити параметри та безпосередньо взаємодіяти з API: |
|||
|
|||
 |
|||
|
|||
* Потім натисніть кнопку "Execute", інтерфейс користувача зв'яжеться з вашим API, надішле параметри, у відповідь отримає результати та покаже їх на екрані: |
|||
|
|||
 |
|||
|
|||
### Оновлення альтернативної API документації |
|||
|
|||
Зараз перейдемо <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>. |
|||
|
|||
* Альтернативна документація також показуватиме новий параметр і вміст запиту: |
|||
|
|||
 |
|||
|
|||
### Підсумки |
|||
|
|||
Таким чином, Ви **один раз** оголошуєте типи параметрів, тіла тощо, як параметри функції. |
|||
|
|||
Ви робите це за допомогою стандартних сучасних типів Python. |
|||
|
|||
Вам не потрібно вивчати новий синтаксис, методи чи класи конкретної бібліотеки тощо. |
|||
|
|||
Використовуючи стандартний **Python 3.8+**. |
|||
|
|||
Наприклад, для `int`: |
|||
|
|||
```Python |
|||
item_id: int |
|||
``` |
|||
|
|||
або для більш складної моделі `Item`: |
|||
|
|||
```Python |
|||
item: Item |
|||
``` |
|||
|
|||
...і з цим єдиним оголошенням Ви отримуєте: |
|||
|
|||
* Підтримку редактора, включаючи: |
|||
* Варіанти заповнення. |
|||
* Перевірку типів. |
|||
* Перевірку даних: |
|||
* Автоматичні та зрозумілі помилки, у разі некоректних даних. |
|||
* Перевірка навіть для JSON з високим рівнем вкладеності. |
|||
* <abbr title="також відомий як: serialization, parsing, marshalling">Перетворення</abbr> вхідних даних: з мережі до даних і типів Python. Читання з: |
|||
* JSON. |
|||
* Параметрів шляху. |
|||
* Параметрів запиту. |
|||
* Cookies. |
|||
* Headers. |
|||
* Forms. |
|||
* Файлів. |
|||
* <abbr title="також відомий як: serialization, parsing, marshalling">Перетворення</abbr> вихідних даних: з типів і даних Python до мережевих даних (як JSON): |
|||
* Конвертація Python типів (`str`, `int`, `float`, `bool`, `list`, тощо). |
|||
* `datetime` об'єкти. |
|||
* `UUID` об'єкти. |
|||
* Моделі бази даних. |
|||
* ...та багато іншого. |
|||
* Автоматичну інтерактивну документацію API, включаючи 2 альтернативні інтерфейси користувача: |
|||
* Swagger UI. |
|||
* ReDoc. |
|||
|
|||
--- |
|||
|
|||
Повертаючись до попереднього прикладу коду, **FastAPI**: |
|||
|
|||
* Підтвердить наявність `item_id` у шляху для запитів `GET` та `PUT`. |
|||
* Підтвердить, що `item_id` має тип `int` для запитів `GET` and `PUT`. |
|||
* Якщо це не так, клієнт побачить корисну, зрозумілу помилку. |
|||
* Перевірить, чи є необов'язковий параметр запиту з назвою `q` (а саме `http://127.0.0.1:8000/items/foo?q=somequery`) для запитів `GET`. |
|||
* Оскільки параметр `q` оголошено як `= None`, він необов'язковий. |
|||
* За відсутності `None` він був би обов'язковим (як і вміст у випадку з `PUT`). |
|||
* Для запитів `PUT` із `/items/{item_id}`, читає вміст як JSON: |
|||
* Перевірить, чи має обов'язковий атрибут `name` тип `str`. |
|||
* Перевірить, чи має обов'язковий атрибут `price` тип `float`. |
|||
* Перевірить, чи існує необов'язковий атрибут `is_offer` та чи має він тип `bool`. |
|||
* Усе це також працюватиме для глибоко вкладених об'єктів JSON. |
|||
* Автоматично конвертує із та в JSON. |
|||
* Документує все за допомогою OpenAPI, який може бути використано в: |
|||
* Інтерактивних системах документації. |
|||
* Системах автоматичної генерації клієнтського коду для багатьох мов. |
|||
* Надає безпосередньо 2 вебінтерфейси інтерактивної документації. |
|||
|
|||
--- |
|||
|
|||
Ми лише трішки доторкнулися до коду, але Ви вже маєте уявлення про те, як все працює. |
|||
|
|||
Спробуйте змінити рядок: |
|||
|
|||
```Python |
|||
return {"item_name": item.name, "item_id": item_id} |
|||
``` |
|||
|
|||
...із: |
|||
|
|||
```Python |
|||
... "item_name": item.name ... |
|||
``` |
|||
|
|||
...на: |
|||
|
|||
```Python |
|||
... "item_price": item.price ... |
|||
``` |
|||
|
|||
...і побачите, як ваш редактор автоматично заповнюватиме атрибути та знатиме їхні типи: |
|||
|
|||
 |
|||
|
|||
Для більш повного ознайомлення з додатковими функціями, перегляньте <a href="https://fastapi.tiangolo.com/tutorial/">Туторіал - Посібник Користувача</a>. |
|||
|
|||
**Spoiler alert**: туторіал - посібник користувача містить: |
|||
|
|||
* Оголошення **параметрів** з інших місць як: **headers**, **cookies**, **form fields** та **files**. |
|||
* Як встановити **перевірку обмежень** як `maximum_length` або `regex`. |
|||
* Дуже потужна і проста у використанні система **<abbr title="також відома як: components, resources, providers, services, injectables">Ін'єкція Залежностей</abbr>**. |
|||
* Безпека та автентифікація, включаючи підтримку **OAuth2** з **JWT tokens** та **HTTP Basic** автентифікацію. |
|||
* Досконаліші (але однаково прості) техніки для оголошення **глибоко вкладених моделей JSON** (завдяки Pydantic). |
|||
* Багато додаткових функцій (завдяки Starlette) як-от: |
|||
* **WebSockets** |
|||
* надзвичайно прості тести на основі HTTPX та `pytest` |
|||
* **CORS** |
|||
* **Cookie Sessions** |
|||
* ...та більше. |
|||
|
|||
## Продуктивність |
|||
|
|||
Незалежні тести TechEmpower показують що застосунки **FastAPI**, які працюють під керуванням Uvicorn <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">є одними з найшвидших серед доступних фреймворків в Python</a>, поступаючись лише Starlette та Uvicorn (які внутрішньо використовуються в FastAPI). (*) |
|||
|
|||
Щоб дізнатися більше про це, перегляньте розділ <a href="https://fastapi.tiangolo.com/benchmarks/" class="internal-link" target="_blank">Benchmarks</a>. |
|||
|
|||
## Необов'язкові залежності |
|||
|
|||
Pydantic використовує: |
|||
|
|||
* <a href="https://github.com/JoshData/python-email-validator" target="_blank"><code>email_validator</code></a> - для валідації електронної пошти. |
|||
* <a href="https://docs.pydantic.dev/latest/usage/pydantic_settings/" target="_blank"><code>pydantic-settings</code></a> - для управління налаштуваннями. |
|||
* <a href="https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/" target="_blank"><code>pydantic-extra-types</code></a> - для додаткових типів, що можуть бути використані з Pydantic. |
|||
|
|||
|
|||
Starlette використовує: |
|||
|
|||
* <a href="https://www.python-httpx.org" target="_blank"><code>httpx</code></a> - Необхідно, якщо Ви хочете використовувати `TestClient`. |
|||
* <a href="https://jinja.palletsprojects.com" target="_blank"><code>jinja2</code></a> - Необхідно, якщо Ви хочете використовувати шаблони як конфігурацію за замовчуванням. |
|||
* <a href="https://andrew-d.github.io/python-multipart/" target="_blank"><code>python-multipart</code></a> - Необхідно, якщо Ви хочете підтримувати <abbr title="перетворення рядка, який надходить із запиту HTTP, на дані Python">"розбір"</abbr> форми за допомогою `request.form()`. |
|||
* <a href="https://pythonhosted.org/itsdangerous/" target="_blank"><code>itsdangerous</code></a> - Необхідно для підтримки `SessionMiddleware`. |
|||
* <a href="https://pyyaml.org/wiki/PyYAMLDocumentation" target="_blank"><code>pyyaml</code></a> - Необхідно для підтримки Starlette `SchemaGenerator` (ймовірно, вам це не потрібно з FastAPI). |
|||
* <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - Необхідно, якщо Ви хочете використовувати `UJSONResponse`. |
|||
|
|||
FastAPI / Starlette використовують: |
|||
|
|||
* <a href="https://www.uvicorn.org" target="_blank"><code>uvicorn</code></a> - для сервера, який завантажує та обслуговує вашу програму. |
|||
* <a href="https://github.com/ijl/orjson" target="_blank"><code>orjson</code></a> - Необхідно, якщо Ви хочете використовувати `ORJSONResponse`. |
|||
|
|||
Ви можете встановити все це за допомогою `pip install fastapi[all]`. |
|||
|
|||
## Ліцензія |
|||
|
|||
Цей проєкт ліцензовано згідно з умовами ліцензії MIT. |
|||
@ -0,0 +1,116 @@ |
|||
# Тіло - Поля |
|||
|
|||
Так само як ви можете визначати додаткову валідацію та метадані у параметрах *функції обробки шляху* за допомогою `Query`, `Path` та `Body`, ви можете визначати валідацію та метадані всередині моделей Pydantic за допомогою `Field` від Pydantic. |
|||
|
|||
## Імпорт `Field` |
|||
|
|||
Спочатку вам потрібно імпортувати це: |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="4" |
|||
{!> ../../../docs_src/body_fields/tutorial001_an_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="4" |
|||
{!> ../../../docs_src/body_fields/tutorial001_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.8+" |
|||
|
|||
```Python hl_lines="4" |
|||
{!> ../../../docs_src/body_fields/tutorial001_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.10+ non-Annotated" |
|||
|
|||
!!! tip |
|||
Варто користуватись `Annotated` версією, якщо це можливо. |
|||
|
|||
```Python hl_lines="2" |
|||
{!> ../../../docs_src/body_fields/tutorial001_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.8+ non-Annotated" |
|||
|
|||
!!! tip |
|||
Варто користуватись `Annotated` версією, якщо це можливо. |
|||
|
|||
```Python hl_lines="4" |
|||
{!> ../../../docs_src/body_fields/tutorial001.py!} |
|||
``` |
|||
|
|||
!!! warning |
|||
Зверніть увагу, що `Field` імпортується прямо з `pydantic`, а не з `fastapi`, як всі інші (`Query`, `Path`, `Body` тощо). |
|||
|
|||
## Оголошення атрибутів моделі |
|||
|
|||
Ви можете використовувати `Field` з атрибутами моделі: |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="11-14" |
|||
{!> ../../../docs_src/body_fields/tutorial001_an_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="11-14" |
|||
{!> ../../../docs_src/body_fields/tutorial001_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.8+" |
|||
|
|||
```Python hl_lines="12-15" |
|||
{!> ../../../docs_src/body_fields/tutorial001_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.10+ non-Annotated" |
|||
|
|||
!!! tip |
|||
Варто користуватись `Annotated` версією, якщо це можливо.. |
|||
|
|||
```Python hl_lines="9-12" |
|||
{!> ../../../docs_src/body_fields/tutorial001_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.8+ non-Annotated" |
|||
|
|||
!!! tip |
|||
Варто користуватись `Annotated` версією, якщо це можливо.. |
|||
|
|||
```Python hl_lines="11-14" |
|||
{!> ../../../docs_src/body_fields/tutorial001.py!} |
|||
``` |
|||
|
|||
`Field` працює так само, як `Query`, `Path` і `Body`, у нього такі самі параметри тощо. |
|||
|
|||
!!! note "Технічні деталі" |
|||
Насправді, `Query`, `Path` та інші, що ви побачите далі, створюють об'єкти підкласів загального класу `Param`, котрий сам є підкласом класу `FieldInfo` з Pydantic. |
|||
|
|||
І `Field` від Pydantic також повертає екземпляр `FieldInfo`. |
|||
|
|||
`Body` також безпосередньо повертає об'єкти підкласу `FieldInfo`. І є інші підкласи, які ви побачите пізніше, що є підкласами класу Body. |
|||
|
|||
Пам'ятайте, що коли ви імпортуєте 'Query', 'Path' та інше з 'fastapi', вони фактично є функціями, які повертають спеціальні класи. |
|||
|
|||
!!! tip |
|||
Зверніть увагу, що кожен атрибут моделі із типом, значенням за замовчуванням та `Field` має ту саму структуру, що й параметр *функції обробки шляху*, з `Field` замість `Path`, `Query` і `Body`. |
|||
|
|||
## Додавання додаткової інформації |
|||
|
|||
Ви можете визначити додаткову інформацію у `Field`, `Query`, `Body` тощо. І вона буде включена у згенеровану JSON схему. |
|||
|
|||
Ви дізнаєтеся більше про додавання додаткової інформації пізніше у документації, коли вивчатимете визначення прикладів. |
|||
|
|||
!!! warning |
|||
Додаткові ключі, передані в `Field`, також будуть присутні у згенерованій схемі OpenAPI для вашого додатка. |
|||
Оскільки ці ключі не обов'язково можуть бути частиною специфікації OpenAPI, деякі інструменти OpenAPI, наприклад, [OpenAPI валідатор](https://validator.swagger.io/), можуть не працювати з вашою згенерованою схемою. |
|||
|
|||
## Підсумок |
|||
|
|||
Ви можете використовувати `Field` з Pydantic для визначення додаткових перевірок та метаданих для атрибутів моделі. |
|||
|
|||
Ви також можете використовувати додаткові іменовані аргументи для передачі додаткових метаданих JSON схеми. |
|||
@ -0,0 +1,219 @@ |
|||
# OPENAPI 中的其他响应 |
|||
|
|||
您可以声明附加响应，包括附加状态代码、媒体类型、描述等。 |
|||
|
|||
这些额外的响应将包含在OpenAPI模式中，因此它们也将出现在API文档中。 |
|||
|
|||
但是对于那些额外的响应，你必须确保你直接返回一个像 `JSONResponse` 一样的 `Response` ，并包含你的状态代码和内容。 |
|||
|
|||
## `model`附加响应 |
|||
您可以向路径操作装饰器传递参数 `responses` 。 |
|||
|
|||
它接收一个 `dict`，键是每个响应的状态代码（如`200`），值是包含每个响应信息的其他 `dict`。 |
|||
|
|||
每个响应字典都可以有一个关键模型，其中包含一个 `Pydantic` 模型，就像 `response_model` 一样。 |
|||
|
|||
**FastAPI**将采用该模型，生成其`JSON Schema`并将其包含在`OpenAPI`中的正确位置。 |
|||
|
|||
例如，要声明另一个具有状态码 `404` 和`Pydantic`模型 `Message` 的响应，可以写： |
|||
```Python hl_lines="18 22" |
|||
{!../../../docs_src/additional_responses/tutorial001.py!} |
|||
``` |
|||
|
|||
|
|||
!!! Note |
|||
请记住，您必须直接返回 `JSONResponse` 。 |
|||
|
|||
!!! Info |
|||
`model` 密钥不是OpenAPI的一部分。 |
|||
**FastAPI**将从那里获取`Pydantic`模型，生成` JSON Schema` ，并将其放在正确的位置。 |
|||
- 正确的位置是： |
|||
- 在键 `content` 中，其具有另一个`JSON`对象（ `dict` ）作为值，该`JSON`对象包含： |
|||
- 媒体类型的密钥，例如 `application/json` ，它包含另一个`JSON`对象作为值，该对象包含： |
|||
- 一个键` schema` ，它的值是来自模型的`JSON Schema`，正确的位置在这里。 |
|||
- **FastAPI**在这里添加了对OpenAPI中另一个地方的全局JSON模式的引用，而不是直接包含它。这样，其他应用程序和客户端可以直接使用这些JSON模式，提供更好的代码生成工具等。 |
|||
|
|||
|
|||
**在OpenAPI中为该路径操作生成的响应将是：** |
|||
|
|||
```json hl_lines="3-12" |
|||
{ |
|||
"responses": { |
|||
"404": { |
|||
"description": "Additional Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/Message" |
|||
} |
|||
} |
|||
} |
|||
}, |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/Item" |
|||
} |
|||
} |
|||
} |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
|
|||
``` |
|||
**模式被引用到OpenAPI模式中的另一个位置：** |
|||
```json hl_lines="4-16" |
|||
{ |
|||
"components": { |
|||
"schemas": { |
|||
"Message": { |
|||
"title": "Message", |
|||
"required": [ |
|||
"message" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"message": { |
|||
"title": "Message", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"Item": { |
|||
"title": "Item", |
|||
"required": [ |
|||
"id", |
|||
"value" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"id": { |
|||
"title": "Id", |
|||
"type": "string" |
|||
}, |
|||
"value": { |
|||
"title": "Value", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"ValidationError": { |
|||
"title": "ValidationError", |
|||
"required": [ |
|||
"loc", |
|||
"msg", |
|||
"type" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"loc": { |
|||
"title": "Location", |
|||
"type": "array", |
|||
"items": { |
|||
"type": "string" |
|||
} |
|||
}, |
|||
"msg": { |
|||
"title": "Message", |
|||
"type": "string" |
|||
}, |
|||
"type": { |
|||
"title": "Error Type", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"HTTPValidationError": { |
|||
"title": "HTTPValidationError", |
|||
"type": "object", |
|||
"properties": { |
|||
"detail": { |
|||
"title": "Detail", |
|||
"type": "array", |
|||
"items": { |
|||
"$ref": "#/components/schemas/ValidationError" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
|
|||
``` |
|||
## 主响应的其他媒体类型 |
|||
|
|||
您可以使用相同的 `responses` 参数为相同的主响应添加不同的媒体类型。 |
|||
|
|||
例如，您可以添加一个额外的媒体类型` image/png` ，声明您的路径操作可以返回JSON对象（媒体类型 `application/json` ）或PNG图像： |
|||
|
|||
```Python hl_lines="19-24 28" |
|||
{!../../../docs_src/additional_responses/tutorial002.py!} |
|||
``` |
|||
|
|||
!!! Note |
|||
- 请注意，您必须直接使用 `FileResponse` 返回图像。 |
|||
|
|||
!!! Info |
|||
- 除非在 `responses` 参数中明确指定不同的媒体类型，否则**FastAPI**将假定响应与主响应类具有相同的媒体类型（默认为` application/json` ）。 |
|||
- 但是如果您指定了一个自定义响应类，并将 `None `作为其媒体类型，**FastAPI**将使用 `application/json` 作为具有关联模型的任何其他响应。 |
|||
|
|||
## 组合信息 |
|||
您还可以联合接收来自多个位置的响应信息，包括 `response_model `、 `status_code` 和 `responses `参数。 |
|||
|
|||
您可以使用默认的状态码 `200` （或者您需要的自定义状态码）声明一个 `response_model `，然后直接在OpenAPI模式中在 `responses` 中声明相同响应的其他信息。 |
|||
|
|||
**FastAPI**将保留来自 `responses` 的附加信息，并将其与模型中的JSON Schema结合起来。 |
|||
|
|||
例如，您可以使用状态码 `404` 声明响应，该响应使用`Pydantic`模型并具有自定义的` description` 。 |
|||
|
|||
以及一个状态码为 `200` 的响应，它使用您的 `response_model` ，但包含自定义的 `example` ： |
|||
|
|||
```Python hl_lines="20-31" |
|||
{!../../../docs_src/additional_responses/tutorial003.py!} |
|||
``` |
|||
|
|||
所有这些都将被合并并包含在您的OpenAPI中，并在API文档中显示： |
|||
|
|||
## 联合预定义响应和自定义响应 |
|||
|
|||
您可能希望有一些应用于许多路径操作的预定义响应，但是你想将不同的路径和自定义的相应组合在一块。 |
|||
对于这些情况，你可以使用Python的技术，将 `dict` 与 `**dict_to_unpack` 解包： |
|||
```Python |
|||
old_dict = { |
|||
"old key": "old value", |
|||
"second old key": "second old value", |
|||
} |
|||
new_dict = {**old_dict, "new key": "new value"} |
|||
``` |
|||
|
|||
这里， new_dict 将包含来自 old_dict 的所有键值对加上新的键值对： |
|||
```python |
|||
{ |
|||
"old key": "old value", |
|||
"second old key": "second old value", |
|||
"new key": "new value", |
|||
} |
|||
``` |
|||
您可以使用该技术在路径操作中重用一些预定义的响应，并将它们与其他自定义响应相结合。 |
|||
**例如：** |
|||
```Python hl_lines="13-17 26" |
|||
{!../../../docs_src/additional_responses/tutorial004.py!} |
|||
``` |
|||
## 有关OpenAPI响应的更多信息 |
|||
|
|||
要了解您可以在响应中包含哪些内容，您可以查看OpenAPI规范中的以下部分： |
|||
+ [OpenAPI响应对象](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responsesObject)，它包括 Response Object 。 |
|||
+ [OpenAPI响应对象](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responseObject)，您可以直接在 `responses` 参数中的每个响应中包含任何内容。包括 `description` 、 `headers` 、 `content` （其中是声明不同的媒体类型和JSON Schemas）和 `links` 。 |
|||
@ -0,0 +1,17 @@ |
|||
# 在云上部署 FastAPI |
|||
|
|||
您几乎可以使用**任何云服务商**来部署 FastAPI 应用程序。 |
|||
|
|||
在大多数情况下，主要的云服务商都有部署 FastAPI 的指南。 |
|||
|
|||
## 云服务商 - 赞助商 |
|||
|
|||
一些云服务商 ✨ [**赞助 FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨，这确保了FastAPI 及其**生态系统**持续健康地**发展**。 |
|||
|
|||
这表明了他们对 FastAPI 及其**社区**（您）的真正承诺，因为他们不仅想为您提供**良好的服务**，而且还想确保您拥有一个**良好且健康的框架**：FastAPI。 🙇 |
|||
|
|||
您可能想尝试他们的服务并阅读他们的指南： |
|||
|
|||
* <a href="https://docs.platform.sh/languages/python.html?utm_source=fastapi-signup&utm_medium=banner&utm_campaign=FastAPI-signup-June-2023" class="external-link" target="_blank" >Platform.sh</a> |
|||
* <a href="https://docs.porter.run/language-specific-guides/fastapi" class="external-link" target="_blank">Porter</a> |
|||
* <a href="https://www.deta.sh/?ref=fastapi" class="external-link" target="_blank">Deta</a> |
|||
@ -0,0 +1,192 @@ |
|||
# 关于 HTTPS |
|||
|
|||
人们很容易认为 HTTPS 仅仅是“启用”或“未启用”的东西。 |
|||
|
|||
但实际情况比这复杂得多。 |
|||
|
|||
!!!提示 |
|||
如果你很赶时间或不在乎，请继续阅读下一部分，下一部分会提供一个step-by-step的教程，告诉你怎么使用不同技术来把一切都配置好。 |
|||
|
|||
要从用户的视角**了解 HTTPS 的基础知识**，请查看 <a href="https://howhttps.works/" class="external-link" target="_blank">https://howhttps.works/</a>。 |
|||
|
|||
现在，从**开发人员的视角**，在了解 HTTPS 时需要记住以下几点： |
|||
|
|||
* 要使用 HTTPS，**服务器**需要拥有由**第三方**生成的**"证书(certificate)"**。 |
|||
* 这些证书实际上是从第三方**获取**的，而不是“生成”的。 |
|||
* 证书有**生命周期**。 |
|||
* 它们会**过期**。 |
|||
* 然后它们需要**更新**，**再次从第三方获取**。 |
|||
* 连接的加密发生在 **TCP 层**。 |
|||
* 这是 HTTP 协议**下面的一层**。 |
|||
* 因此，**证书和加密**处理是在 **HTTP之前**完成的。 |
|||
* **TCP 不知道域名**。 仅仅知道 IP 地址。 |
|||
* 有关所请求的 **特定域名** 的信息位于 **HTTP 数据**中。 |
|||
* **HTTPS 证书**“证明”**某个域名**，但协议和加密发生在 TCP 层，在知道正在处理哪个域名**之前**。 |
|||
* **默认情况下**，这意味着你**每个 IP 地址只能拥有一个 HTTPS 证书**。 |
|||
* 无论你的服务器有多大，或者服务器上的每个应用程序有多小。 |
|||
* 不过，对此有一个**解决方案**。 |
|||
* **TLS** 协议（在 HTTP 之下的TCP 层处理加密的协议）有一个**扩展**，称为 **<a href="https://en.wikipedia.org/wiki/Server_Name_Indication" class="external-link" target="_blank"><abbr title="服务器名称指示">SNI</abbr></a>**。 |
|||
* SNI 扩展允许一台服务器（具有 **单个 IP 地址**）拥有 **多个 HTTPS 证书** 并提供 **多个 HTTPS 域名/应用程序**。 |
|||
* 为此，服务器上会有**单独**的一个组件（程序）侦听**公共 IP 地址**，这个组件必须拥有服务器中的**所有 HTTPS 证书**。 |
|||
* **获得安全连接后**，通信协议**仍然是HTTP**。 |
|||
* 内容是 **加密过的**，即使它们是通过 **HTTP 协议** 发送的。 |
|||
|
|||
通常的做法是在服务器上运行**一个程序/HTTP 服务器**并**管理所有 HTTPS 部分**：接收**加密的 HTTPS 请求**， 将 **解密的 HTTP 请求** 发送到在同一服务器中运行的实际 HTTP 应用程序（在本例中为 **FastAPI** 应用程序），从应用程序中获取 **HTTP 响应**， 使用适当的 **HTTPS 证书**对其进行加密并使用 **HTTPS** 将其发送回客户端。 此服务器通常被称为 **<a href="https://en.wikipedia.org/wiki/TLS_termination_proxy" class="external-link" target="_blank">TLS 终止代理(TLS Termination Proxy)</a>**。 |
|||
|
|||
你可以用作 TLS 终止代理的一些选项包括： |
|||
|
|||
* Traefik（也可以处理证书更新） |
|||
* Caddy（也可以处理证书更新） |
|||
* Nginx |
|||
* HAProxy |
|||
|
|||
## Let's Encrypt |
|||
|
|||
在 Let's Encrypt 之前，这些 **HTTPS 证书** 由受信任的第三方出售。 |
|||
|
|||
过去，获得这些证书的过程非常繁琐，需要大量的文书工作，而且证书非常昂贵。 |
|||
|
|||
但随后 **<a href="https://letsencrypt.org/" class="external-link" target="_blank">Let's Encrypt</a>** 创建了。 |
|||
|
|||
它是 Linux 基金会的一个项目。 它以自动方式免费提供 **HTTPS 证书**。 这些证书可以使用所有符合标准的安全加密，并且有效期很短（大约 3 个月），因此**安全性实际上更好**，因为它们的生命周期缩短了。 |
|||
|
|||
域可以被安全地验证并自动生成证书。 这还允许自动更新这些证书。 |
|||
|
|||
我们的想法是自动获取和更新这些证书，以便你可以永远免费拥有**安全的 HTTPS**。 |
|||
|
|||
## 面向开发人员的 HTTPS |
|||
|
|||
这里有一个 HTTPS API 看起来是什么样的示例，我们会分步说明，并且主要关注对开发人员重要的部分。 |
|||
|
|||
|
|||
### 域名 |
|||
|
|||
第一步我们要先**获取**一些**域名(Domain Name)**。 然后可以在 DNS 服务器（可能是你的同一家云服务商提供的）中配置它。 |
|||
|
|||
你可能拥有一个云服务器（虚拟机）或类似的东西，并且它会有一个<abbr title="That isn't Change">固定</abbr> **公共IP地址**。 |
|||
|
|||
在 DNS 服务器中，你可以配置一条记录（“A 记录”）以将 **你的域名** 指向你服务器的公共 **IP 地址**。 |
|||
|
|||
这个操作一般只需要在最开始执行一次。 |
|||
|
|||
!!! tip |
|||
域名这部分发生在 HTTPS 之前，由于这一切都依赖于域名和 IP 地址，所以先在这里提一下。 |
|||
|
|||
### DNS |
|||
|
|||
现在让我们关注真正的 HTTPS 部分。 |
|||
|
|||
首先，浏览器将通过 **DNS 服务器** 查询**域名的IP** 是什么，在本例中为 `someapp.example.com`。 |
|||
|
|||
DNS 服务器会告诉浏览器使用某个特定的 **IP 地址**。 这将是你在 DNS 服务器中为你的服务器配置的公共 IP 地址。 |
|||
|
|||
<img src="/img/deployment/https/https01.svg"> |
|||
|
|||
### TLS 握手开始 |
|||
|
|||
然后，浏览器将在**端口 443**（HTTPS 端口）上与该 IP 地址进行通信。 |
|||
|
|||
通信的第一部分只是建立客户端和服务器之间的连接并决定它们将使用的加密密钥等。 |
|||
|
|||
<img src="/img/deployment/https/https02.svg"> |
|||
|
|||
客户端和服务器之间建立 TLS 连接的过程称为 **TLS 握手**。 |
|||
|
|||
### 带有 SNI 扩展的 TLS |
|||
|
|||
**服务器中只有一个进程**可以侦听特定 **IP 地址**的特定 **端口**。 可能有其他进程在同一 IP 地址的其他端口上侦听，但每个 IP 地址和端口组合只有一个进程。 |
|||
|
|||
TLS (HTTPS) 默认使用端口`443`。 这就是我们需要的端口。 |
|||
|
|||
由于只有一个进程可以监听此端口，因此监听端口的进程将是 **TLS 终止代理**。 |
|||
|
|||
TLS 终止代理可以访问一个或多个 **TLS 证书**（HTTPS 证书）。 |
|||
|
|||
使用上面讨论的 **SNI 扩展**，TLS 终止代理将检查应该用于此连接的可用 TLS (HTTPS) 证书，并使用与客户端期望的域名相匹配的证书。 |
|||
|
|||
在这种情况下，它将使用`someapp.example.com`的证书。 |
|||
|
|||
<img src="/img/deployment/https/https03.svg"> |
|||
|
|||
客户端已经**信任**生成该 TLS 证书的实体（在本例中为 Let's Encrypt，但我们稍后会看到），因此它可以**验证**该证书是否有效。 |
|||
|
|||
然后，通过使用证书，客户端和 TLS 终止代理 **决定如何加密** **TCP 通信** 的其余部分。 这就完成了 **TLS 握手** 部分。 |
|||
|
|||
此后，客户端和服务器就拥有了**加密的 TCP 连接**，这就是 TLS 提供的功能。 然后他们可以使用该连接来启动实际的 **HTTP 通信**。 |
|||
|
|||
这就是 **HTTPS**，它只是 **安全 TLS 连接** 内的普通 **HTTP**，而不是纯粹的（未加密的）TCP 连接。 |
|||
|
|||
!!! tip |
|||
请注意，通信加密发生在 **TCP 层**，而不是 HTTP 层。 |
|||
|
|||
### HTTPS 请求 |
|||
|
|||
现在客户端和服务器（特别是浏览器和 TLS 终止代理）具有 **加密的 TCP 连接**，它们可以开始 **HTTP 通信**。 |
|||
|
|||
接下来，客户端发送一个 **HTTPS 请求**。 这其实只是一个通过 TLS 加密连接的 HTTP 请求。 |
|||
|
|||
<img src="/img/deployment/https/https04.svg"> |
|||
|
|||
### 解密请求 |
|||
|
|||
TLS 终止代理将使用协商好的加密算法**解密请求**，并将**（解密的）HTTP 请求**传输到运行应用程序的进程（例如运行 FastAPI 应用的 Uvicorn 进程）。 |
|||
|
|||
<img src="/img/deployment/https/https05.svg"> |
|||
|
|||
### HTTP 响应 |
|||
|
|||
应用程序将处理请求并向 TLS 终止代理发送**（未加密）HTTP 响应**。 |
|||
|
|||
<img src="/img/deployment/https/https06.svg"> |
|||
|
|||
### HTTPS 响应 |
|||
|
|||
然后，TLS 终止代理将使用之前协商的加密算法（以`someapp.example.com`的证书开头）对响应进行加密，并将其发送回浏览器。 |
|||
|
|||
接下来，浏览器将验证响应是否有效和是否使用了正确的加密密钥等。然后它会**解密响应**并处理它。 |
|||
|
|||
<img src="/img/deployment/https/https07.svg"> |
|||
|
|||
客户端（浏览器）将知道响应来自正确的服务器，因为它使用了他们之前使用 **HTTPS 证书** 协商出的加密算法。 |
|||
|
|||
### 多个应用程序 |
|||
|
|||
在同一台（或多台）服务器中，可能存在**多个应用程序**，例如其他 API 程序或数据库。 |
|||
|
|||
只有一个进程可以处理特定的 IP 和端口（在我们的示例中为 TLS 终止代理），但其他应用程序/进程也可以在服务器上运行，只要它们不尝试使用相同的 **公共 IP 和端口的组合**。 |
|||
|
|||
<img src="/img/deployment/https/https08.svg"> |
|||
|
|||
这样，TLS 终止代理就可以为多个应用程序处理**多个域名**的 HTTPS 和证书，然后在每种情况下将请求传输到正确的应用程序。 |
|||
|
|||
### 证书更新 |
|||
|
|||
在未来的某个时候，每个证书都会**过期**（大约在获得证书后 3 个月）。 |
|||
|
|||
然后，会有另一个程序（在某些情况下是另一个程序，在某些情况下可能是同一个 TLS 终止代理）与 Let's Encrypt 通信并更新证书。 |
|||
|
|||
<img src="/img/deployment/https/https.svg"> |
|||
|
|||
**TLS 证书** **与域名相关联**，而不是与 IP 地址相关联。 |
|||
|
|||
因此，要更新证书，更新程序需要向权威机构（Let's Encrypt）**证明**它确实**“拥有”并控制该域名**。 |
|||
|
|||
有多种方法可以做到这一点。 一些流行的方式是： |
|||
|
|||
* **修改一些DNS记录**。 |
|||
* 为此，续订程序需要支持 DNS 提供商的 API，因此，要看你使用的 DNS 提供商是否提供这一功能。 |
|||
* **在与域名关联的公共 IP 地址上作为服务器运行**（至少在证书获取过程中）。 |
|||
* 正如我们上面所说，只有一个进程可以监听特定的 IP 和端口。 |
|||
* 这就是当同一个 TLS 终止代理还负责证书续订过程时它非常有用的原因之一。 |
|||
* 否则，你可能需要暂时停止 TLS 终止代理，启动续订程序以获取证书，然后使用 TLS 终止代理配置它们，然后重新启动 TLS 终止代理。 这并不理想，因为你的应用程序在 TLS 终止代理关闭期间将不可用。 |
|||
|
|||
通过拥有一个**单独的系统来使用 TLS 终止代理来处理 HTTPS**, 而不是直接将 TLS 证书与应用程序服务器一起使用 （例如 Uvicorn）,你可以在 |
|||
更新证书的过程中同时保持提供服务。 |
|||
|
|||
## 回顾 |
|||
|
|||
拥有**HTTPS** 非常重要，并且在大多数情况下相当**关键**。 作为开发人员，你围绕 HTTPS 所做的大部分努力就是**理解这些概念**以及它们的工作原理。 |
|||
|
|||
一旦你了解了**面向开发人员的 HTTPS** 的基础知识，你就可以轻松组合和配置不同的工具，以帮助你以简单的方式管理一切。 |
|||
|
|||
在接下来的一些章节中，我将向你展示几个为 **FastAPI** 应用程序设置 **HTTPS** 的具体示例。 🔒 |
|||
@ -0,0 +1,21 @@ |
|||
# 部署 |
|||
|
|||
部署 **FastAPI** 应用程序相对容易。 |
|||
|
|||
## 部署是什么意思 |
|||
|
|||
**部署**应用程序意味着执行必要的步骤以使其**可供用户使用**。 |
|||
|
|||
对于**Web API**来说，通常涉及将上传到**云服务器**中，搭配一个性能和稳定性都不错的**服务器程序**，以便你的**用户**可以高效地**访问**你的应用程序，而不会出现中断或其他问题。 |
|||
|
|||
这与**开发**阶段形成鲜明对比，在**开发**阶段，你不断更改代码、破坏代码、修复代码, 来回停止和重启服务器等。 |
|||
|
|||
## 部署策略 |
|||
|
|||
根据你的使用场景和使用的工具，有多种方法可以实现此目的。 |
|||
|
|||
你可以使用一些工具自行**部署服务器**，你也可以使用能为你完成部分工作的**云服务**，或其他可能的选项。 |
|||
|
|||
我将向你展示在部署 **FastAPI** 应用程序时你可能应该记住的一些主要概念（尽管其中大部分适用于任何其他类型的 Web 应用程序）。 |
|||
|
|||
在接下来的部分中，你将看到更多需要记住的细节以及一些技巧。 ✨ |
|||
@ -0,0 +1,148 @@ |
|||
# 手动运行服务器 - Uvicorn |
|||
|
|||
在远程服务器计算机上运行 **FastAPI** 应用程序所需的主要东西是 ASGI 服务器程序，例如 **Uvicorn**。 |
|||
|
|||
有 3 个主要可选方案： |
|||
|
|||
* <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>：高性能 ASGI 服务器。 |
|||
* <a href="https://pgjones.gitlab.io/hypercorn/" class="external-link" target="_blank">Hypercorn</a>：与 HTTP/2 和 Trio 等兼容的 ASGI 服务器。 |
|||
* <a href="https://github.com/django/daphne" class="external-link" target="_blank">Daphne</a>：为 Django Channels 构建的 ASGI 服务器。 |
|||
|
|||
## 服务器主机和服务器程序 |
|||
|
|||
关于名称，有一个小细节需要记住。 💡 |
|||
|
|||
“**服务器**”一词通常用于指远程/云计算机（物理机或虚拟机）以及在该计算机上运行的程序（例如 Uvicorn）。 |
|||
|
|||
请记住，当您一般读到“服务器”这个名词时，它可能指的是这两者之一。 |
|||
|
|||
当提到远程主机时，通常将其称为**服务器**，但也称为**机器**(machine)、**VM**（虚拟机）、**节点**。 这些都是指某种类型的远程计算机，通常运行 Linux，您可以在其中运行程序。 |
|||
|
|||
|
|||
## 安装服务器程序 |
|||
|
|||
您可以使用以下命令安装 ASGI 兼容服务器： |
|||
|
|||
=== "Uvicorn" |
|||
|
|||
* <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>，一个快如闪电 ASGI 服务器，基于 uvloop 和 httptools 构建。 |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "uvicorn[standard]" |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
!!! tip |
|||
通过添加`standard`，Uvicorn 将安装并使用一些推荐的额外依赖项。 |
|||
|
|||
其中包括`uvloop`，它是`asyncio`的高性能替代品，它提供了巨大的并发性能提升。 |
|||
|
|||
=== "Hypercorn" |
|||
|
|||
* <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>，一个也与 HTTP/2 兼容的 ASGI 服务器。 |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install hypercorn |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
...或任何其他 ASGI 服务器。 |
|||
|
|||
|
|||
## 运行服务器程序 |
|||
|
|||
您可以按照之前教程中的相同方式运行应用程序，但不使用`--reload`选项，例如： |
|||
|
|||
=== "Uvicorn" |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ 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) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
|
|||
=== "Hypercorn" |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ hypercorn main:app --bind 0.0.0.0:80 |
|||
|
|||
Running on 0.0.0.0:8080 over http (CTRL + C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
!!! warning |
|||
如果您正在使用`--reload`选项，请记住删除它。 |
|||
|
|||
`--reload` 选项消耗更多资源，并且更不稳定。 |
|||
|
|||
它在**开发**期间有很大帮助，但您**不应该**在**生产环境**中使用它。 |
|||
|
|||
## Hypercorn with Trio |
|||
|
|||
Starlette 和 **FastAPI** 基于 <a href="https://anyio.readthedocs.io/en/stable/" class="external-link" target="_blank">AnyIO</a>， 所以它们才能同时与 Python 的标准库 <a href="https://docs.python.org/3/library/asyncio-task.html" class="external-link" target="_blank">asyncio</a> 和<a href="https://trio.readthedocs.io/en/stable/" class="external-link" target="_blank">Trio</a> 兼容。 |
|||
|
|||
尽管如此，Uvicorn 目前仅与 asyncio 兼容，并且通常使用 <a href="https://github.com/MagicStack/uvloop" class="external-link" target="_blank">`uvloop`</a >, 它是`asyncio`的高性能替代品。 |
|||
|
|||
但如果你想直接使用**Trio**，那么你可以使用**Hypercorn**，因为它支持它。 ✨ |
|||
|
|||
### 安装具有 Trio 的 Hypercorn |
|||
|
|||
首先，您需要安装具有 Trio 支持的 Hypercorn： |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "hypercorn[trio]" |
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
### Run with Trio |
|||
|
|||
然后你可以传递值`trio`给命令行选项`--worker-class`: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ hypercorn main:app --worker-class trio |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
这将通过您的应用程序启动 Hypercorn，并使用 Trio 作为后端。 |
|||
|
|||
现在您可以在应用程序内部使用 Trio。 或者更好的是，您可以使用 AnyIO，使您的代码与 Trio 和 asyncio 兼容。 🎉 |
|||
|
|||
## 部署概念 |
|||
|
|||
这些示例运行服务器程序（例如 Uvicorn），启动**单个进程**，在所有 IP（`0.0.0.0`)上监听预定义端口（例如`80`)。 |
|||
|
|||
这是基本思路。 但您可能需要处理一些其他事情，例如： |
|||
|
|||
* 安全性 - HTTPS |
|||
* 启动时运行 |
|||
* 重新启动 |
|||
* Replication（运行的进程数） |
|||
* 内存 |
|||
* 开始前的步骤 |
|||
|
|||
在接下来的章节中，我将向您详细介绍每个概念、如何思考它们，以及一些具体示例以及处理它们的策略。 🚀 |
|||
@ -0,0 +1,184 @@ |
|||
# Server Workers - Gunicorn with Uvicorn |
|||
|
|||
让我们回顾一下之前的部署概念： |
|||
|
|||
* 安全性 - HTTPS |
|||
* 启动时运行 |
|||
* 重新启动 |
|||
* **复制（运行的进程数）** |
|||
* 内存 |
|||
* 启动前的先前步骤 |
|||
|
|||
到目前为止，通过文档中的所有教程，您可能已经在**单个进程**上运行了像 Uvicorn 这样的**服务器程序**。 |
|||
|
|||
部署应用程序时，您可能希望进行一些**进程复制**，以利用**多核**并能够处理更多请求。 |
|||
|
|||
正如您在上一章有关[部署概念](./concepts.md){.internal-link target=_blank}中看到的，您可以使用多种策略。 |
|||
|
|||
在这里我将向您展示如何将 <a href="https://gunicorn.org/" class="external-link" target="_blank">**Gunicorn**</a> 与 **Uvicorn worker 进程** 一起使用。 |
|||
|
|||
!!! info |
|||
如果您正在使用容器，例如 Docker 或 Kubernetes，我将在下一章中告诉您更多相关信息：[容器中的 FastAPI - Docker](./docker.md){.internal-link target=_blank}。 |
|||
|
|||
特别是，当在 **Kubernetes** 上运行时，您可能**不想**使用 Gunicorn，而是运行 **每个容器一个 Uvicorn 进程**，但我将在本章后面告诉您这一点。 |
|||
|
|||
|
|||
|
|||
## Gunicorn with Uvicorn Workers |
|||
|
|||
**Gunicorn**主要是一个使用**WSGI标准**的应用服务器。 这意味着 Gunicorn 可以为 Flask 和 Django 等应用程序提供服务。 Gunicorn 本身与 **FastAPI** 不兼容，因为 FastAPI 使用最新的 **<a href="https://asgi.readthedocs.io/en/latest/" class="external-link" target=" _blank">ASGI 标准</a>**。 |
|||
|
|||
但 Gunicorn 支持充当 **进程管理器** 并允许用户告诉它要使用哪个特定的 **worker类**。 然后 Gunicorn 将使用该类启动一个或多个 **worker进程**。 |
|||
|
|||
**Uvicorn** 有一个 Gunicorn 兼容的worker类。 |
|||
|
|||
使用这种组合，Gunicorn 将充当 **进程管理器**，监听 **端口** 和 **IP**。 它会将通信**传输**到运行**Uvicorn类**的worker进程。 |
|||
|
|||
然后与Gunicorn兼容的**Uvicorn worker**类将负责将Gunicorn发送的数据转换为ASGI标准以供FastAPI使用。 |
|||
|
|||
## 安装 Gunicorn 和 Uvicorn |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "uvicorn[standard]" gunicorn |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
这将安装带有`standard`扩展包（以获得高性能）的 Uvicorn 和 Gunicorn。 |
|||
|
|||
## Run Gunicorn with Uvicorn Workers |
|||
|
|||
接下来你可以通过以下命令运行Gunicorn: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:80 |
|||
|
|||
[19499] [INFO] Starting gunicorn 20.1.0 |
|||
[19499] [INFO] Listening at: http://0.0.0.0:80 (19499) |
|||
[19499] [INFO] Using worker: uvicorn.workers.UvicornWorker |
|||
[19511] [INFO] Booting worker with pid: 19511 |
|||
[19513] [INFO] Booting worker with pid: 19513 |
|||
[19514] [INFO] Booting worker with pid: 19514 |
|||
[19515] [INFO] Booting worker with pid: 19515 |
|||
[19511] [INFO] Started server process [19511] |
|||
[19511] [INFO] Waiting for application startup. |
|||
[19511] [INFO] Application startup complete. |
|||
[19513] [INFO] Started server process [19513] |
|||
[19513] [INFO] Waiting for application startup. |
|||
[19513] [INFO] Application startup complete. |
|||
[19514] [INFO] Started server process [19514] |
|||
[19514] [INFO] Waiting for application startup. |
|||
[19514] [INFO] Application startup complete. |
|||
[19515] [INFO] Started server process [19515] |
|||
[19515] [INFO] Waiting for application startup. |
|||
[19515] [INFO] Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
|
|||
让我们看看每个选项的含义： |
|||
|
|||
* `main:app`：这与 Uvicorn 使用的语法相同，`main` 表示名为"`main`"的 Python 模块，因此是文件 `main.py`。 `app` 是 **FastAPI** 应用程序的变量名称。 |
|||
* 你可以想象 `main:app` 相当于一个 Python `import` 语句，例如： |
|||
|
|||
```Python |
|||
from main import app |
|||
``` |
|||
|
|||
* 因此，`main:app` 中的冒号相当于 `from main import app` 中的 Python `import` 部分。 |
|||
|
|||
* `--workers`：要使用的worker进程数量，每个进程将运行一个 Uvicorn worker进程，在本例中为 4 个worker进程。 |
|||
|
|||
* `--worker-class`：在worker进程中使用的与 Gunicorn 兼容的工作类。 |
|||
* 这里我们传递了 Gunicorn 可以导入和使用的类： |
|||
|
|||
```Python |
|||
import uvicorn.workers.UvicornWorker |
|||
``` |
|||
|
|||
* `--bind`：这告诉 Gunicorn 要监听的 IP 和端口，使用冒号 (`:`) 分隔 IP 和端口。 |
|||
* 如果您直接运行 Uvicorn，则可以使用`--host 0.0.0.0`和`--port 80`，而不是`--bind 0.0.0.0:80`（Gunicorn 选项）。 |
|||
|
|||
|
|||
在输出中，您可以看到它显示了每个进程的 **PID**（进程 ID）（它只是一个数字）。 |
|||
|
|||
你可以看到： |
|||
|
|||
* Gunicorn **进程管理器** 以 PID `19499` 开头（在您的情况下，它将是一个不同的数字）。 |
|||
* 然后它开始`Listening at: http://0.0.0.0:80`。 |
|||
* 然后它检测到它必须使用 `uvicorn.workers.UvicornWorker` 处的worker类。 |
|||
* 然后它启动**4个worker**，每个都有自己的PID：`19511`、`19513`、`19514`和`19515`。 |
|||
|
|||
Gunicorn 还将负责管理**死进程**和**重新启动**新进程（如果需要保持worker数量）。 因此，这在一定程度上有助于上面列表中**重启**的概念。 |
|||
|
|||
尽管如此，您可能还希望有一些外部的东西，以确保在必要时**重新启动 Gunicorn**，并且**在启动时运行它**等。 |
|||
|
|||
## Uvicorn with Workers |
|||
|
|||
Uvicorn 也有一个选项可以启动和运行多个 **worker进程**。 |
|||
|
|||
然而，到目前为止，Uvicorn 处理worker进程的能力比 Gunicorn 更有限。 因此，如果您想拥有这个级别（Python 级别）的进程管理器，那么最好尝试使用 Gunicorn 作为进程管理器。 |
|||
|
|||
无论如何，您都可以像这样运行它： |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ 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>] |
|||
<font color="#A6E22E">INFO</font>: Waiting for application startup. |
|||
<font color="#A6E22E">INFO</font>: Application startup complete. |
|||
<font color="#A6E22E">INFO</font>: Started server process [<font color="#A1EFE4">27369</font>] |
|||
<font color="#A6E22E">INFO</font>: Waiting for application startup. |
|||
<font color="#A6E22E">INFO</font>: Application startup complete. |
|||
<font color="#A6E22E">INFO</font>: Started server process [<font color="#A1EFE4">27370</font>] |
|||
<font color="#A6E22E">INFO</font>: Waiting for application startup. |
|||
<font color="#A6E22E">INFO</font>: Application startup complete. |
|||
<font color="#A6E22E">INFO</font>: Started server process [<font color="#A1EFE4">27367</font>] |
|||
<font color="#A6E22E">INFO</font>: Waiting for application startup. |
|||
<font color="#A6E22E">INFO</font>: Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
这里唯一的新选项是 `--workers` 告诉 Uvicorn 启动 4 个工作进程。 |
|||
|
|||
您还可以看到它显示了每个进程的 **PID**，父进程（这是 **进程管理器**）的 PID 为`27365`，每个工作进程的 PID 为：`27368`、`27369`， `27370`和`27367`。 |
|||
|
|||
## 部署概念 |
|||
|
|||
在这里，您了解了如何使用 **Gunicorn**（或 Uvicorn）管理 **Uvicorn 工作进程**来**并行**应用程序的执行，利用 CPU 中的 **多核**，并 能够满足**更多请求**。 |
|||
|
|||
从上面的部署概念列表来看，使用worker主要有助于**复制**部分，并对**重新启动**有一点帮助，但您仍然需要照顾其他部分： |
|||
|
|||
* **安全 - HTTPS** |
|||
* **启动时运行** |
|||
* ***重新启动*** |
|||
* 复制（运行的进程数） |
|||
* **内存** |
|||
* **启动之前的先前步骤** |
|||
|
|||
## 容器和 Docker |
|||
|
|||
在关于 [容器中的 FastAPI - Docker](./docker.md){.internal-link target=_blank} 的下一章中，我将介绍一些可用于处理其他 **部署概念** 的策略。 |
|||
|
|||
我还将向您展示 **官方 Docker 镜像**，其中包括 **Gunicorn 和 Uvicorn worker** 以及一些对简单情况有用的默认配置。 |
|||
|
|||
在那里，我还将向您展示如何 **从头开始构建自己的镜像** 以运行单个 Uvicorn 进程（没有 Gunicorn）。 这是一个简单的过程，并且可能是您在使用像 **Kubernetes** 这样的分布式容器管理系统时想要做的事情。 |
|||
|
|||
## 回顾 |
|||
|
|||
您可以使用**Gunicorn**（或Uvicorn）作为Uvicorn工作进程的进程管理器，以利用**多核CPU**，**并行运行多个进程**。 |
|||
|
|||
如果您要设置**自己的部署系统**，同时自己处理其他部署概念，则可以使用这些工具和想法。 |
|||
|
|||
请查看下一章，了解带有容器（例如 Docker 和 Kubernetes）的 **FastAPI**。 您将看到这些工具也有简单的方法来解决其他**部署概念**。 ✨ |
|||
@ -0,0 +1,5 @@ |
|||
# 学习 |
|||
|
|||
以下是学习 **FastAPI** 的介绍部分和教程。 |
|||
|
|||
您可以认为这是一本 **书**，一门 **课程**，是 **官方** 且推荐的学习FastAPI的方法。😎 |
|||
Loading…
Reference in new issue