> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Como criar seu arquivo pyproject.toml

> Guia completo do arquivo pyproject.toml em Python: aprenda a criar, listar dependências, travar versões e preparar seu projeto para produção.

## Arquivo pyproject.toml para Python

O arquivo `pyproject.toml` é uma forma moderna de especificar todos os requisitos do sistema de build e as dependências do seu projeto em um único arquivo. Este guia mostra como criar, configurar e usar o `pyproject.toml` para garantir consistência entre os ambientes de desenvolvimento e produção.

## O que é um arquivo pyproject.toml?

Um `pyproject.toml` lista dependências, o sistema de build e outros metadados do seu projeto Python. Isso permite:

* Permitir que você e sua equipe mantenham ambientes idênticos
* Fazer com que novos colaboradores reproduzam o ambiente exatamente
* Configurar dependências de desenvolvimento e produção separadamente

***

<Steps>
  <Step title="Criar o arquivo pyproject.toml">
    Primeiro, crie um arquivo chamado `pyproject.toml` na raiz do seu projeto.
  </Step>

  <Step title="Defina os detalhes do seu projeto">
    No arquivo `pyproject.toml`, comece definindo os metadados do projeto. Vamos definir o nome do projeto, versão, descrição e outras informações relevantes.\
    O nome do projeto deve conter letras ASCII, dígitos, underscores "\_", hífens "-" e pontos ".". Não deve começar ou terminar com underscore, hífen ou ponto. Por exemplo:

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    ```
  </Step>

  <Step title="Listar dependências do projeto">
    Em seguida, vamos listar as dependências necessárias para o projeto. Podemos especificar dependências de produção e de desenvolvimento. As dependências de produção são listadas na seção `dependencies`, enquanto as dependências de desenvolvimento podem ser listadas em `optional-dependencies` com um nome de grupo específico (por exemplo, `dev`).\
    Você pode especificar versões para suas dependências usando operadores de comparação como `==`, `>=`, `<`... No exemplo abaixo não especificamos versões; isso significa que a versão mais recente será instalada. É recomendado especificar versões exatas para garantir reprodutibilidade e evitar que atualizações incompatíveis quebrem o ambiente em produção.

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    dependencies = [
        "discord-py",
        "aiohttp"
    ]

    [project.optional-dependencies]
    dev = [
        "pytest",
        "black"
    ]
    ```
  </Step>

  <Step title="Configurar o sistema de build">
    Por fim, precisamos especificar os requisitos do sistema de build. Isso é necessário para que ferramentas como o pip saibam como construir e instalar seu projeto. Usaremos `setuptools` como backend de build, que é uma escolha comum, mas você pode escolher outros como o `poetry`.

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    dependencies = [
        "discord.py",
        "aiohttp"
    ]

    [project.optional-dependencies]
    dev = [
        "pytest",
        "black"
    ]

    [build-system]
    requires = ["setuptools"]
    build-backend = "setuptools.build_meta"
    ```
  </Step>
</Steps>

***

## Instalar dependências com pip

Para instalar as dependências listadas no `pyproject.toml`, você pode usar o `pip` ou outras ferramentas que suportem `pyproject.toml`. Isso permite trabalhar no projeto com as dependências instaladas.

```bash theme={null}
pip install .
```

Esse comando irá ler o `pyproject.toml`, instalar as dependências listadas em `dependencies` e configurar seu projeto para desenvolvimento. Se quiser instalar também as dependências de desenvolvimento, use:

```bash theme={null}
pip install .[dev]
```

Isso instalará dependências de produção e de desenvolvimento, permitindo que você trabalhe no projeto com todas as ferramentas necessárias.

## Boas práticas e dicas:

* **Mantenha atualizado**: Revise e atualize o `pyproject.toml` regularmente conforme adicionar novas dependências
* **Use versões exatas**: Prefira `==` em vez de `>`, `>=` ou não especificar versão para evitar surpresas em produção
* **Versionamento**: Faça commit do `pyproject.toml` no Git para rastrear mudanças de dependências e versões
* **Ambiente isolado**: Mantenha um ambiente virtual por projeto para evitar conflitos globais
* **Teste localmente**: Antes de realizar deploy, teste o arquivo com `pip install .` em um ambiente novo

***

## Próximos passos

Com seu `pyproject.toml` configurado:

1. Faça commit no seu repositório Git.
2. Hospede seu projeto na **Square Cloud**.
3. Configure deploy automático via GitHub.
4. Bem-vindo à hospedagem profissional de aplicações Python!

Um `pyproject.toml` bem estruturado é a base para qualquer aplicação Python bem-sucedida, garantindo que sua aplicação funcione perfeitamente na Square Cloud.