Ir para o conte√ļdo

Desenvolvimento - Contribuindo

Primeiramente, você deveria ver os meios básicos para ajudar FastAPI e pedir ajuda.

Desenvolvendo

Se voc√™ j√° clonou o reposit√≥rio e precisa mergulhar no c√≥digo, aqui est√£o algumas orienta√ß√Ķes para configurar seu ambiente.

Ambiente virtual com venv

Você pode criar um ambiente virtual em um diretório utilizando o módulo venv do Python:

$ python -m venv env

Isso criará o diretório ./env/ com os binários Python e então você será capaz de instalar pacotes nesse ambiente isolado.

Ativar o ambiente

Ative o novo ambiente com:

$ source ./env/bin/activate
$ .\env\Scripts\Activate.ps1

Ou se você usa Bash para Windows (por exemplo Git Bash):

$ source ./env/Scripts/activate

Para verificar se funcionou, use:

$ which pip

some/directory/fastapi/env/bin/pip
$ Get-Command pip

some/directory/fastapi/env/bin/pip

Se ele exibir o bin√°rio pip em env/bin/pip ent√£o funcionou. ūüéČ

Tip

Toda vez que você instalar um novo pacote com pip nesse ambiente, ative o ambiente novamente.

Isso garante que se você usar um programa instalado por aquele pacote (como flit), você utilizará aquele de seu ambiente local e não outro que possa estar instalado globalmente.

Flit

FastAPI utiliza Flit para construir, empacotar e publicar o projeto.

Após ativar o ambiente como descrito acima, instale o flit:

$ pip install flit

---> 100%

Ative novamente o ambiente para ter certeza que você esteja utilizando o flit que você acabou de instalar (e não um global).

E agora use flit para instalar as dependências de desenvolvimento:

$ flit install --deps develop --symlink

---> 100%

Se você está no Windows, use --pth-file ao invés de --symlink:

$ flit install --deps develop --pth-file

---> 100%

Isso irá instalar todas as dependências e seu FastAPI local em seu ambiente local.

Usando seu FastAPI local

Se você cria um arquivo Python que importa e usa FastAPI, e roda com Python de seu ambiente local, ele irá utilizar o código fonte de seu FastAPI local.

E se você atualizar o código fonte do FastAPI local, como ele é instalado com --symlink (ou --pth-file no Windows), quando você rodar aquele arquivo Python novamente, ele irá utilizar a nova versão do FastAPI que você acabou de editar.

Desse modo, você não tem que "instalar" sua versão local para ser capaz de testar cada mudança.

Formato

Tem um arquivo que você pode rodar que irá formatar e limpar todo o seu código:

$ bash scripts/format.sh

Ele irá organizar também todos os seus imports.

Para que ele organize os imports corretamente, você precisa ter o FastAPI instalado localmente em seu ambiente, com o comando na seção acima usando --symlink (ou --pth-file no Windows).

Formato dos imports

Tem outro script que formata todos os imports e garante que você não tenha imports não utilizados:

$ bash scripts/format-imports.sh

Como ele roda um comando após o outro, modificando e revertendo muitos arquivos, ele demora um pouco para concluir, então pode ser um pouco mais fácil utilizar scripts/format.sh frequentemente e scripts/format-imports.sh somente após "commitar uma branch".

Documentação

Primeiro, tenha certeza de configurar seu ambiente como descrito acima, isso ir√° instalar todas as requisi√ß√Ķes.

A documentação usa MkDocs.

E existem ferramentas/scripts extras para controlar as tradu√ß√Ķes em ./scripts/docs.py.

Tip

Você não precisa ver o código em ./scripts/docs.py, você apenas o utiliza na linha de comando.

Toda a documentação está no formato Markdown no diretório ./docs/pt/.

Muitos dos tutoriais tem blocos de código.

Na maioria dos casos, esse blocos de c√≥digo s√£o aplica√ß√Ķes completas que podem ser rodadas do jeito que est√£o apresentados.

De fato, esses blocos de código não estão escritos dentro do Markdown, eles são arquivos Python dentro do diretório ./docs_src/.

E esses arquivos Python são incluídos/injetados na documentação quando se gera o site.

Testes para Documentação

A maioria dos testes na verdade rodam encima dos arquivos fonte na documentação.

Isso ajuda a garantir:

  • Que a documenta√ß√£o esteja atualizada.
  • Que os exemplos da documenta√ß√£o possam ser rodadas do jeito que est√£o apresentadas.
  • A maior parte dos recursos √© coberta pela documenta√ß√£o, garantida por cobertura de testes.

Durante o desenvolvimento local, existe um script que constrói o site e procura por quaisquer mudanças, carregando na hora:

$ python ./scripts/docs.py live

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

Isso irá servir a documentação em http://127.0.0.1:8008.

Desse jeito, você poderá editar a documentação/arquivos fonte e ver as mudanças na hora.

Typer CLI (opcional)

As instru√ß√Ķes aqui mostram como utilizar scripts em ./scripts/docs.py com o programa python diretamente.

Mas você pode usar também Typer CLI, e você terá auto-completação para comandos no seu terminal após instalar o completion.

Se você instalou Typer CLI, você pode instalar completion com:

$ typer --install-completion

zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.

Aplica√ß√Ķes e documenta√ß√£o ao mesmo tempo

Se você rodar os exemplos com, por exemplo:

$ uvicorn tutorial001:app --reload

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

como Uvicorn utiliza por padrão a porta 8000, a documentação na porta 8008 não dará conflito.

Tradu√ß√Ķes

Ajuda com tradu√ß√Ķes √Č MUITO apreciada! E essa tarefa n√£o pode ser conclu√≠da sem a ajuda da comunidade. ūüĆé ūüöÄ

Aqui est√£o os passos para ajudar com as tradu√ß√Ķes.

Dicas e orienta√ß√Ķes

  • Verifique sempre os pull requests existentes para a sua linguagem e fa√ßa revis√Ķes das altera√ß√Ķes e aprove elas.

Tip

Voc√™ pode adicionar coment√°rios com sugest√Ķes de altera√ß√Ķes para pull requests existentes.

Verifique as documenta√ß√Ķes sobre adicionar revis√£o ao pull request para aprova√ß√£o ou solicita√ß√£o de altera√ß√Ķes.

  • Verifique em issues para ver se existe algu√©m coordenando tradu√ß√Ķes para a sua linguagem.

  • Adicione um √ļnico pull request por p√°gina traduzida. Isso tornar√° muito mais f√°cil a revis√£o para as outras pessoas.

Para as linguagens que eu não falo, vou esperar por várias pessoas revisarem a tradução antes de mergear.

  • Voc√™ pode verificar tamb√©m se h√° tradu√ß√Ķes para sua linguagem e adicionar revis√£o para elas, isso ir√° me ajudar a saber que a tradu√ß√£o est√° correta e eu possa mergear.

  • Utilize os mesmos exemplos Python e somente traduza o texto na documenta√ß√£o. Voc√™ n√£o tem que alterar nada no c√≥digo para que funcione.

  • Utilize as mesmas imagens, nomes de arquivo e links. Voc√™ n√£o tem que alterar nada disso para que funcione.

  • Para verificar o c√≥digo de duas letras para a linguagem que voc√™ quer traduzir, voc√™ pode usar a Lista de c√≥digos ISO 639-1.

Linguagem existente

Vamos dizer que voc√™ queira traduzir uma p√°gina para uma linguagem que j√° tenha tradu√ß√Ķes para algumas p√°ginas, como o Espanhol.

No caso do Espanhol, o c√≥digo de duas letras √© es. Ent√£o, o diret√≥rio para tradu√ß√Ķes em Espanhol est√° localizada em docs/es/.

Tip

A principal ("oficial") linguagem é o Inglês, localizado em docs/en/.

Agora rode o servidor ao vivo para as documenta√ß√Ķes em Espanhol:

// Use o comando "live" e passe o código da linguagem como um argumento de linha de comando
$ python ./scripts/docs.py live es

<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
<span style="color: green;">[INFO]</span> Start watching changes
<span style="color: green;">[INFO]</span> Start detecting changes

Agora você pode ir em http://127.0.0.1:8008 e ver suas mudanças ao vivo.

Se você procurar no site da documentação do FastAPI, você verá que toda linguagem tem todas as páginas. Mas algumas páginas não estão traduzidas e tem notificação sobre a falta da tradução.

Mas quando você rodar localmente como descrito acima, você somente verá as páginas que já estão traduzidas.

Agora vamos dizer que você queira adicionar uma tradução para a seção Recursos.

  • Copie o arquivo em:
docs/en/docs/features.md
  • Cole ele exatamente no mesmo local mas para a linguagem que voc√™ quer traduzir, por exemplo:
docs/es/docs/features.md

Tip

Observe que a √ļnica mudan√ßa na rota √© o c√≥digo da linguagem, de en para es.

  • Agora abra o arquivo de configura√ß√£o MkDocs para Ingl√™s em:
docs/en/docs/mkdocs.yml
  • Procure o lugar onde docs/features.md est√° localizado no arquivo de configura√ß√£o. Algum lugar como:
site_name: FastAPI
# Mais coisas
nav:
- FastAPI: index.md
- Languages:
  - en: /
  - es: /es/
- features.md
  • Abra o arquivo de configura√ß√£o MkDocs para a linguagem que voc√™ est√° editando, por exemplo:
docs/es/docs/mkdocs.yml
  • Adicione no mesmo local que est√° no arquivo em Ingl√™s, por exemplo:
site_name: FastAPI
# Mais coisas
nav:
- FastAPI: index.md
- Languages:
  - en: /
  - es: /es/
- features.md

Tenha certeza que se existem outras entradas, a nova entrada com sua tradução esteja exatamente na mesma ordem como na versão em Inglês.

Se voc√™ for no seu navegador ver√° que agora a documenta√ß√£o mostra sua nova se√ß√£o. ūüéČ

Agora você poderá traduzir tudo e ver como está toda vez que salva o arquivo.

Nova linguagem

Vamos dizer que voc√™ queira adicionar tradu√ß√Ķes para uma linguagem que ainda n√£o foi traduzida, nem sequer uma p√°gina.

Vamos dizer que você queira adicionar tradução para Haitiano, e ainda não tenha na documentação.

Verificando o link acima, o código para "Haitiano" é ht.

O próximo passo é rodar o script para gerar um novo diretório de tradução:

// Use o comando new-lang, passe o código da linguagem como um argumento de linha de comando
$ python ./scripts/docs.py new-lang ht

Successfully initialized: docs/ht
Updating ht
Updating en

Agora você pode verificar em seu editor de código o mais novo diretório criado docs/ht/.

Tip

Crie um primeiro pull request com apenas isso, para iniciar a configura√ß√£o da nova linguagem, antes de adicionar tradu√ß√Ķes.

Desse modo outros poder√£o ajudar com outras p√°ginas enquanto voc√™ trabalha na primeira. ūüöÄ

Inicie traduzindo a p√°gina principal, docs/ht/index.md.

Ent√£o voc√™ pode continuar com as instru√ß√Ķes anteriores, para uma "Linguagem Existente".

Nova linguagem n√£o suportada

Se quando rodar o script do servidor ao vivo você pega um erro sobre linguagem não suportada, alguma coisa como:

 raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: partials/language/xx.html

Isso significa que o tema não suporta essa linguagem (nesse caso, com um código falso de duas letras xx).

Mas n√£o se preocupe, voc√™ pode configurar o tema de linguagem para Ingl√™s e ent√£o traduzir o conte√ļdo da documenta√ß√£o.

Se você precisar fazer isso, edite o mkdocs.yml para sua nova linguagem, teremos algo como:

site_name: FastAPI
# Mais coisas
theme:
  # Mais coisas
  language: xx

Altere essa linguagem de xx (do seu código de linguagem) para en.

Então você poderá iniciar novamente o servidor ao vivo.

Pré-visualize o resultado

Quando voc√™ usa o script em ./scripts/docs.py com o comando live ele somente exibe os arquivos e tradu√ß√Ķes dispon√≠veis para a linguagem atual.

Mas uma vez que você tenha concluído, você poderá testar tudo como se parecesse online.

Para fazer isso, primeiro construa toda a documentação:

// Use o comando "build-all", isso lever√° um tempinho
$ python ./scripts/docs.py build-all

Updating es
Updating en
Building docs for: en
Building docs for: es
Successfully built docs for: es
Copying en index.md to README.md

Isso gera toda a documentação em ./docs_build/ para cada linguagem. Isso inclui a adição de quaisquer arquivos com tradução faltando, com uma nota dizendo que "esse arquivo ainda não tem tradução". Mas você não tem que fazer nada com esse diretório.

Então ele constrói todos aqueles sites independentes MkDocs para cada linguagem, combina eles, e gera a saída final em ./site/.

Então você poderá "servir" eles com o comando serve:

// Use o comando "serve" após rodar "build-all"
$ python ./scripts/docs.py serve

Warning: this is a very simple server. For development, use mkdocs serve instead.
This is here only to preview a site with translations already built.
Make sure you run the build-all command first.
Serving at: http://127.0.0.1:8008

Testes

Tem um script que você pode rodar localmente para testar todo o código e gerar relatórios de cobertura em HTML:

$ bash scripts/test-cov-html.sh

Esse comando gera um diret√≥rio ./htmlcov/, se voc√™ abrir o arquivo ./htmlcov/index.html no seu navegador, poder√° explorar interativamente as regi√Ķes de c√≥digo que est√£o cobertas pelos testes, e observar se existe alguma regi√£o faltando.

Testes no seu editor

Se você quer usar os testes integrados em seu editor adicione ./docs_src na sua variável PYTHONPATH.

Por exemplo, no VS Code você pode criar um arquivo .env com:

PYTHONPATH=./docs_src