From 1085c11c7cab8a9d154e0b56ac000b1eae120523 Mon Sep 17 00:00:00 2001 From: Arthur-Barreto Date: Sun, 17 Nov 2024 21:59:22 -0300 Subject: [PATCH 1/4] =?UTF-8?q?add=20support=20for=20catal=C3=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ca/docs/async.md | 7 + docs/ca/docs/benchmarks.md | 7 + docs/ca/docs/features.md | 7 + docs/ca/docs/index.md | 486 +++++++++++++++++++++++++++++ docs/ca/docs/project-generation.md | 7 + docs/ca/docs/python-types.md | 7 + docs/ca/mkdocs.yml | 1 + 7 files changed, 522 insertions(+) create mode 100644 docs/ca/docs/async.md create mode 100644 docs/ca/docs/benchmarks.md create mode 100644 docs/ca/docs/features.md create mode 100644 docs/ca/docs/index.md create mode 100644 docs/ca/docs/project-generation.md create mode 100644 docs/ca/docs/python-types.md create mode 100644 docs/ca/mkdocs.yml diff --git a/docs/ca/docs/async.md b/docs/ca/docs/async.md new file mode 100644 index 000000000..c2882e90e --- /dev/null +++ b/docs/ca/docs/async.md @@ -0,0 +1,7 @@ +/// warning + +The current page still doesn't have a translation for this language. + +But you can help translating it: [Contributing](https://fastapi.tiangolo.com/contributing/){.internal-link target=_blank}. + +/// diff --git a/docs/ca/docs/benchmarks.md b/docs/ca/docs/benchmarks.md new file mode 100644 index 000000000..c2882e90e --- /dev/null +++ b/docs/ca/docs/benchmarks.md @@ -0,0 +1,7 @@ +/// warning + +The current page still doesn't have a translation for this language. + +But you can help translating it: [Contributing](https://fastapi.tiangolo.com/contributing/){.internal-link target=_blank}. + +/// diff --git a/docs/ca/docs/features.md b/docs/ca/docs/features.md new file mode 100644 index 000000000..c2882e90e --- /dev/null +++ b/docs/ca/docs/features.md @@ -0,0 +1,7 @@ +/// warning + +The current page still doesn't have a translation for this language. + +But you can help translating it: [Contributing](https://fastapi.tiangolo.com/contributing/){.internal-link target=_blank}. + +/// diff --git a/docs/ca/docs/index.md b/docs/ca/docs/index.md new file mode 100644 index 000000000..7396dd675 --- /dev/null +++ b/docs/ca/docs/index.md @@ -0,0 +1,486 @@ +# FastAPI + + + +

+ FastAPI +

+

+ Framework FastAPI, alt rendiment, fàcil d'aprendre, ràpid de programar, preparat per a producció +

+

+ + Test + + + Coverage + + + Package version + +

+ +--- + +**Documentació**: https://fastapi.tiangolo.com + +**Codi Font**: https://github.com/fastapi/fastapi + +--- +FastAPI és un framework web modern i ràpid (d’alt rendiment) per construir APIs amb Python, basat en les anotacions de tipus estàndard de Python. + +Les seves característiques principals són: + +* **Rapidesa**: Alt rendiment, comparable amb **NodeJS** i **Go** (gràcies a Starlette i Pydantic). [Un dels frameworks de Python més ràpids](#rendiment). + +* **Ràpid de programar**: Incrementa la velocitat de desenvolupament entre un 200% i un 300%. * +* **Menys errors**: Redueix els errors humans (de programador) aproximadament un 40%.* +* **Intuïtiu**: Gran suport als editors amb autocompletat a tot arreu. Es perd menys temps depanant. +* **Fàcil**: Està dissenyat per ser fàcil d'utilitzar i d'aprendre, dedicant menys temps a llegir documentació. +* **Curt**: Minimitza la duplicació de codi. Múltiples funcionalitats amb cada declaració de paràmetres. Menys errors. +* **Robust**: Crea codi preparat per a producció amb documentació automàtica i interactiva. +* **Basat en estàndards**: Basat i totalment compatible amb els estàndards oberts per a APIs: OpenAPI (anteriorment conegut com Swagger) i JSON Schema. + +* Aquesta estimació està basada en proves amb un equip de desenvolupament intern construint aplicacions preparades per a producció. + +## Sponsors + + + +{% if sponsors %} +{% for sponsor in sponsors.gold -%} + +{% endfor -%} +{%- for sponsor in sponsors.silver -%} + +{% endfor %} +{% endif %} + + + +Altres patrocinadors + +## Opinions + +"_[...] 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._" + +
Kabir Khan - Microsoft (ref)
+ +--- + +"_We adopted the **FastAPI** library to spawn a **REST** server that can be queried to obtain **predictions**. [for Ludwig]_" + +
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - Uber (ref)
+ +--- + +"_**Netflix** is pleased to announce the open-source release of our **crisis management** orchestration framework: **Dispatch**! [built with **FastAPI**]_" + +
Kevin Glisson, Marc Vilanova, Forest Monsen - Netflix (ref)
+ +--- + +"_I’m over the moon excited about **FastAPI**. It’s so fun!_" + +
Brian Okken - Python Bytes podcast host (ref)
+ +--- + +"_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._" + +
Timothy Crosley - Hug creator (ref)
+ +--- + +"_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 [...]_" + +
Ines Montani - Matthew Honnibal - Explosion AI founders - spaCy creators (ref) - (ref)
+ +--- + +## **Typer**, el FastAPI de les CLIs + + + +Si estàs construint una aplicació de CLI per ser utilitzada al terminal en comptes d'una API web, fes un cop d'ull a **Typer**. + +**Typer** és el germà petit de FastAPI. Està dissenyat per ser el **FastAPI de les CLIs**. ⌨️ 🚀 + +## Requisits + +FastAPI es basa en les espatlles de gegants: + +* Starlette per a les parts web. +* Pydantic per a les parts de dades. + +## Instal·lació + +Crea i activa un entorn virtual i després instal·la FastAPI: + +
+ +```console +$ pip install "fastapi[standard]" + +---> 100% +``` + +
+ +**Nota**: Assegura't de posar `"fastapi[standard]"` ntre cometes per garantir que funcioni en tots els terminals. + +## Exemple + +### Crea-ho + +* Crea un fitxer `main.py` amb: + +```Python +from fastapi import FastAPI +from typing import Union + +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} +``` + +
+O utilitzar async def... + +Si el teu codi utilitza `async` / `await`, fes servir `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} +``` + +**Nota**: + +Si no ho saps, revisa la secció "Amb pressa?" sobre async i await a la documentació. + +
+ +### Executa-ho + +Executa el servidor amb: + +
+ +```console +$ fastapi dev main.py + + ╭────────── FastAPI CLI - Development mode ───────────╮ + │ │ + │ Serving at: http://127.0.0.1:8000 │ + │ │ + │ API docs: http://127.0.0.1:8000/docs │ + │ │ + │ Running in development mode, for production use: │ + │ │ + │ fastapi run │ + │ │ + ╰─────────────────────────────────────────────────────╯ + +INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp'] +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +INFO: Started reloader process [2248755] using WatchFiles +INFO: Started server process [2248757] +INFO: Waiting for application startup. +INFO: Application startup complete. +``` + +
+ +
+Sobre l'ordre fastapi dev main.py... + +L'ordre `fastapi dev` llegeix el teu fitxer `main.py`, detecta l'aplicació **FastAPI** que hi ha i inicia un servidor utilitzant Uvicorn. + +Per defecte, `fastapi dev` s'iniciarà amb l'auto-reload habilitat per al desenvolupament local. + +Pots llegir més sobre això a la documentació de la CLI de FastAPI. + +
+ +### Revisa-ho + +Obre el teu navegador a http://127.0.0.1:8000/items/5?q=somequery. + +Veuràs la resposta en format JSON com: + +```JSON +{"item_id": 5, "q": "somequery"} +``` + +Ja has creat una API que: + +* Rep sol·licituds HTTP en els _paths_ `/` i `/items/{item_id}`. +* Ambdós _paths_ accepten operacions `GET` (també conegudes com a _methods_ HTTP). +* El _path_ `/items/{item_id}` té un _path parameter_ `item_id` que hauria de ser un `int`. +* El _path_ `/items/{item_id}` té un _query parameter_ `q` opcional de tipus `str`. + +### Documentació interactiva de l'API + +Ara ves a http://127.0.0.1:8000/docs. + +Veureu la documentació automàtica i interactiva de l'API (proporcionada per Swagger UI): + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) + +### Documentació alternativa de l'API + +Ara ves a http://127.0.0.1:8000/redoc. + +Ara veuràs la documentació automàtica alternativa (proporcionada per ReDoc): + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) + +## Millora de l'exemple + +Ara modifica el fitxer `main.py` per rebre un body d'una sol·licitud `PUT`. + +Declara el body utilitzant tipus estàndard de Python, gràcies a 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} +``` + +El servidor `fastapi dev` hauria de recarregar-se automàticament. + +### Actualització de documents de l'API interactiva + +Ara ves a http://127.0.0.1:8000/docs. + +* La documentació interactiva de l'API s'actualitzarà automàticament, incloent-hi el nou body: + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) + +* Fes clic al botó "Try it out", que et permet omplir els paràmetres i interactuar directament amb l'API: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) + +* Després, fes clic al botó "Execute". La interfície d'usuari es comunicarà amb la teva API, enviarà els paràmetres, obtindrà els resultats i els mostrarà a la pantalla: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) + +### Actualització de la documentació alternativa de l'API + +I ara, ves a http://127.0.0.1:8000/redoc. + +* La documentació alternativa també reflectirà el nou paràmetre de consulta i el body: + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) + +### Resum + +En resum, declares **una sola vegada** els tipus de paràmetres, body, etc., com a paràmetres de funció. + +Ho fas amb tipus moderns estàndard de Python. + +No necessites aprendre una nova sintaxi, ni els mètodes o classes d’una biblioteca específica, etc. + +Només **Python** estàndard. + +Per exemple, per un `int`: + +```Python +item_id: int +``` + +o per a un model més complex com `Item` + +```Python +item: Item +``` + +...i amb aquesta única declaració obtens: + +* Suport de l'editor, incloent: + * Autocompletat. + * Comprovacions de tipus. +* Validació de dades: + * Errors automàtics i clars quan les dades són invàlides. + * Validació fins i tot per a objectes JSON profundament imbricats. +* Conversió de dades d'entrada: des de la xarxa fins a dades i tipus de Python. Llegint de: + * JSON. + * Paràmetres de path. + * Paràmetres de consulta. + * Cookies. + * Headers. + * Formularis. + * Fitxers. +* Conversió de dades de sortida: convertint de dades i tipus de Python a dades de xarxa (com JSON): + * Converteix tipus de Python (`str`, `int`, `float`, `bool`, `list`, etc). + * Objectes `datetime`. + * Objectes `UUID`. + * Models de bases de dades. + * ...i molts més. +* Documentació automàtica i interactiva de l'API, incloent 2 interfícies d'usuari alternatives: + * Swagger UI. + * ReDoc. + +--- + +Tornant a l'exemple de codi anterior, **FastAPI** farà el següent: + +* Validarà que hi ha un `item_id` al path per a les sol·licituds `GET` i `PUT`. +* Validarà que el `item_id` és de tipus `int` per a les sol·licituds `GET` i `PUT`. + * Si no ho és, el client veurà un error clar i útil. +* Comprovarà si hi ha un paràmetre de consulta opcional anomenat `q` (com en `http://127.0.0.1:8000/items/foo?q=somequery`) per a les sol·licituds `GET`. + * Com que el paràmetre `q` està declarat amb `= None` és opcional. + * Sense el `None` seria obligatori (com ho és el body en el cas de `PUT`). +* Per a les sol·licituds `PUT` a `/items/{item_id}` llegirà el body com JSON: + * Comprovarà que té un atribut requerit `name`que ha de ser un `str`. + * Comprovarà que té un atribut requerit `price` que ha de ser un `float`. + * Comprovarà que té un atribut opcional `is_offer`, que ha de ser un `bool`si està present. + * Tot això també funcionaria per a objectes JSON profundament imbricats. +* Convertirà automàticament de i cap a JSON. +* Documentarà tot amb OpenAPI, que pot ser utilitzat per: + * Sistemes de documentació interactiva. + * Sistemes de generació automàtica de codi client, per a molts llenguatges. +* Proporcionarà directament 2 interfícies web de documentació interactiva. + +--- + +Només hem començat a gratar la superfície, però ja tens una idea de com funciona tot plegat. + +Prova de canviar la línia amb: + +```Python + return {"item_name": item.name, "item_id": item_id} +``` + +...de: + +```Python + ... "item_name": item.name ... +``` + +...a: + +```Python + ... "item_price": item.price ... +``` + +...i observa com el teu editor autocompletarà els atributs i reconeixerà els seus tipus: + +![soporte de editor](https://fastapi.tiangolo.com/img/vscode-completion.png) + +Per a un exemple més complet que inclogui més funcionalitats, consulta el Tutorial - Guia d'Usuari. + +**Spoiler alert**: el tutorial - guia d'usuari inclou: + +Declaració de **paràmetres** des de diferents llocs com: **headers**, **cookies**, **camps de formulari** i **fitxers**. +* Com establir **restriccions de validació** com `maximum_length` o `regex`. +* Un sistema de Dependency Injection molt potent i fàcil d'utilitzar. +* Seguretat i autenticació, incloent suport per a **OAuth2** amb **JWT tokens** i **HTTP Basic** auth. +* Tècniques més avançades (però igualment fàcils) per declarar **models JSON profundament imbricats** (gràcies a Pydantic). +* Integració amb **GraphQL** utilitzant Strawberry i altres biblioteques. +* Moltes funcionalitats extres (gràcies a Starlette) com: + * **WebSockets** + * proves extremadament fàcils basades en HTTPX i `pytest` + * **CORS** + * **Sessions amb Cookies** + * ...i molt més. + +## Rendiment + +Els benchmarks independents de TechEmpower mostren que les aplicacions de FastAPI executades amb Uvicorn són un dels frameworks de Python més ràpids disponibles, només per darrere de Starlette i Uvicorn (utilitzats internament per FastAPI). (*) + +Per entendre'n més, consulta la secció Benchmarks. + +## Dependències + +FastAPI depèn de Pydantic i Starlette. + +### Dependències `standard` + +Quan instal·les FastAPI amb `pip install "fastapi[standard]"`, inclou el grup de dependències opcionals `standard`: + +Utilitzat per Pydantic: + +* email-validator - per a la validació de correus electrònics. + +Utilitzat per Starlette: + +* httpx - Necessari si vols utilitzar el `TestClient`. +* jinja2 - Necessari si vols utilitzar la configuració de plantilles per defecte. +* python-multipart - Necessari si vols donar suport al "parsing" de formularis, amb `request.form()`. + +Utilitzat per FastAPI / Starlette: + +* uvicorn - per al servidor que carrega i serveix la teva aplicació. Això inclou `uvicorn[standard]`, que inclou algunes dependències (per exemple, `uvloop`) necessàries per a un servei d'alt rendiment. +* `fastapi-cli` - per proporcionar l'ordre `fastapi`. + +### Sense les dependències `standard` + +Si no vols incloure les dependències opcionals `standard`, pots instal·lar amb `pip install fastapi` en lloc de `pip install "fastapi[standard]"`. + +### Dependències opcionals addicionals + +Hi ha algunes dependències addicionals que podries voler instal·lar. + +Dependències opcionals addicionals de Pydantic: + +* pydantic-settings - per a la gestió de configuracions. +* pydantic-extra-types - per a tipus addicionals que es poden utilitzar amb Pydantic. + +Dependències opcionals addicionals de FastAPI: + +* orjson - Necessari si vols utilitzar `ORJSONResponse`. +* ujson - Necessari si vols utilitzar `UJSONResponse`. + +## Llicència + +Aquest projecte està llicenciat sota els termes de la llicència MIT. diff --git a/docs/ca/docs/project-generation.md b/docs/ca/docs/project-generation.md new file mode 100644 index 000000000..c2882e90e --- /dev/null +++ b/docs/ca/docs/project-generation.md @@ -0,0 +1,7 @@ +/// warning + +The current page still doesn't have a translation for this language. + +But you can help translating it: [Contributing](https://fastapi.tiangolo.com/contributing/){.internal-link target=_blank}. + +/// diff --git a/docs/ca/docs/python-types.md b/docs/ca/docs/python-types.md new file mode 100644 index 000000000..c2882e90e --- /dev/null +++ b/docs/ca/docs/python-types.md @@ -0,0 +1,7 @@ +/// warning + +The current page still doesn't have a translation for this language. + +But you can help translating it: [Contributing](https://fastapi.tiangolo.com/contributing/){.internal-link target=_blank}. + +/// diff --git a/docs/ca/mkdocs.yml b/docs/ca/mkdocs.yml new file mode 100644 index 000000000..de18856f4 --- /dev/null +++ b/docs/ca/mkdocs.yml @@ -0,0 +1 @@ +INHERIT: ../en/mkdocs.yml From 55a3a155b24723f0358ecb3bb2f48b45f0345150 Mon Sep 17 00:00:00 2001 From: svlandeg Date: Thu, 2 Jan 2025 17:23:45 +0100 Subject: [PATCH 2/4] update en mkdocs to include Catalan --- docs/en/mkdocs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index 6443b290a..8c69c1920 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -341,6 +341,8 @@ extra: name: az - azərbaycan dili - link: /bn/ name: bn - বাংলা + - link: /ca/ + name: ca - Catalan - link: /de/ name: de - Deutsch - link: /es/ From 79f4c63087fe444ebbc4e73f781d7e58d1bb697d Mon Sep 17 00:00:00 2001 From: svlandeg Date: Thu, 2 Jan 2025 17:31:22 +0100 Subject: [PATCH 3/4] fix name --- docs/en/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index 8c69c1920..f852a2f1e 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -342,7 +342,7 @@ extra: - link: /bn/ name: bn - বাংলা - link: /ca/ - name: ca - Catalan + name: ca - Català - link: /de/ name: de - Deutsch - link: /es/ From 03ef06f013b09ba89071e568818c7fe1fe514129 Mon Sep 17 00:00:00 2001 From: svlandeg Date: Thu, 2 Jan 2025 17:37:41 +0100 Subject: [PATCH 4/4] remove unnecessary files --- docs/ca/docs/async.md | 7 ------- docs/ca/docs/benchmarks.md | 7 ------- docs/ca/docs/features.md | 7 ------- docs/ca/docs/project-generation.md | 7 ------- docs/ca/docs/python-types.md | 7 ------- 5 files changed, 35 deletions(-) delete mode 100644 docs/ca/docs/async.md delete mode 100644 docs/ca/docs/benchmarks.md delete mode 100644 docs/ca/docs/features.md delete mode 100644 docs/ca/docs/project-generation.md delete mode 100644 docs/ca/docs/python-types.md diff --git a/docs/ca/docs/async.md b/docs/ca/docs/async.md deleted file mode 100644 index c2882e90e..000000000 --- a/docs/ca/docs/async.md +++ /dev/null @@ -1,7 +0,0 @@ -/// warning - -The current page still doesn't have a translation for this language. - -But you can help translating it: [Contributing](https://fastapi.tiangolo.com/contributing/){.internal-link target=_blank}. - -/// diff --git a/docs/ca/docs/benchmarks.md b/docs/ca/docs/benchmarks.md deleted file mode 100644 index c2882e90e..000000000 --- a/docs/ca/docs/benchmarks.md +++ /dev/null @@ -1,7 +0,0 @@ -/// warning - -The current page still doesn't have a translation for this language. - -But you can help translating it: [Contributing](https://fastapi.tiangolo.com/contributing/){.internal-link target=_blank}. - -/// diff --git a/docs/ca/docs/features.md b/docs/ca/docs/features.md deleted file mode 100644 index c2882e90e..000000000 --- a/docs/ca/docs/features.md +++ /dev/null @@ -1,7 +0,0 @@ -/// warning - -The current page still doesn't have a translation for this language. - -But you can help translating it: [Contributing](https://fastapi.tiangolo.com/contributing/){.internal-link target=_blank}. - -/// diff --git a/docs/ca/docs/project-generation.md b/docs/ca/docs/project-generation.md deleted file mode 100644 index c2882e90e..000000000 --- a/docs/ca/docs/project-generation.md +++ /dev/null @@ -1,7 +0,0 @@ -/// warning - -The current page still doesn't have a translation for this language. - -But you can help translating it: [Contributing](https://fastapi.tiangolo.com/contributing/){.internal-link target=_blank}. - -/// diff --git a/docs/ca/docs/python-types.md b/docs/ca/docs/python-types.md deleted file mode 100644 index c2882e90e..000000000 --- a/docs/ca/docs/python-types.md +++ /dev/null @@ -1,7 +0,0 @@ -/// warning - -The current page still doesn't have a translation for this language. - -But you can help translating it: [Contributing](https://fastapi.tiangolo.com/contributing/){.internal-link target=_blank}. - -///