Template para criação de novos projetos Python utilizando Copier, uv e uma estrutura moderna baseada no padrão src/.
O objetivo deste projeto é fornecer uma base reutilizável para iniciar rapidamente novos projetos Python, mantendo uma estrutura consistente e preparada para ferramentas modernas de desenvolvimento.
O template fornece inicialmente:
- Estrutura Python utilizando
src/ - Gerenciamento de ambiente e dependências com uv
- Configuração através de
pyproject.toml - Testes com Pytest
- Estrutura separada para testes:
unitintegratione2e
- Lint e formatação com Ruff
- Diretório para documentação
- Diretório para scripts auxiliares
- Configuração automática do nome do pacote
- Configuração da versão mínima do Python
- Geração de projetos através do Copier
python_template/
│
├── copier.yml
├── README.md
│
└── template/
├── pyproject.toml.jinja
├── README.md.jinja
├── .gitignore
├── .python-version
│
├── src/
│ └── {{ package_name }}/
│ ├── __init__.py
│ └── __main__.py
│
├── tests/
│ ├── __init__.py
│ ├── unit/
│ │ └── __init__.py
│ ├── integration/
│ │ └── __init__.py
│ └── e2e/
│ └── __init__.py
│
├── docs/
│ └── index.md
│
└── scripts/
└── README.md
Durante a geração do projeto, {{ package_name }} é substituído automaticamente pelo nome do pacote Python.
Por exemplo:
{{ package_name }}
pode resultar em:
meu_projeto
gerando:
src/
└── meu_projeto/
├── __init__.py
└── __main__.py
Antes de utilizar o template, é necessário ter instalado:
- Python
uv- Git
- Copier
python --versionou:
python3 --versionuv --versiongit --versioncopier --versionA recomendação é instalar o Copier utilizando uv:
uv tool install copierDepois verifique:
copier --versionSe o Copier já estiver instalado, esta etapa não é necessária.
Existem duas formas principais de utilizar o template:
- A partir de uma cópia local do template
- Diretamente a partir do GitHub
Para utilizar este template localmentente é necessário antes baixar o repositório do GitHut para seu PC, execute o seguinte comando para clonar o repositório:
git clone https://github.com/Cpharles/python_template.gitQuando o repositório já estiver disponível localmente execute:
Primeiro crie um diretório para o projeto:
mkdir meu_projeto
cd meu_projetoVamos ter algo como:
Documents/
├── python_template/
└── <MEU_PROJETO>/
Entre no diretório onde deseja criar o novo projeto:
cd ~/Documents/<MEU_PROJETO>Execute o Copier:
copier copy ../python_template .Note
Atenção para o "ponto" ( . ) ao final do comando, garante e força que o projeto seja criado dentro da pasta atual
Durante a criação o projeto o Copier apresentará algumas perguntas, por exemplo:
Nome do projeto: meu_projeto
Nome do pacote Python: meu_projeto
Descrição do projeto: Meu novo projeto Python
Versão mínima do Python: 3.12
Nome do autor: Charles
E-mail do autor:
Adicionar configuração do Pytest? Yes
Adicionar configuração do Ruff? Yes
O Copier utilizará essas informações para gerar os arquivos do projeto.
Existe a possibilidade de criar seu projeto a partir do GitHub, sem a necessidade de abaixar o projeto do GitHub, neste caso execute o comando:
Note
Neste caso não é necessário a criação da pasta do projeto, pois o comando via GitHub já leva o nome da pasta do projeto que será criado.
Exemplo:
copier copy gh:Cpharles/python_template.git meu_projetoOu utilizando a URL completa:
copier copy https://github.com/Cpharles/python_template.git meu_projetoDepois:
cd meu_projetoDurante o desenvolvimento do template, recomenda-se utilizar a versão local para facilitar os testes e a depuração.
Assim como na execução local para a criação do seu projeto, durante a execução do Copier pelo GitHub, os valores definidos em copier.yml serão solicitados.
Um exemplo:
Nome do projeto: meu_projeto
Nome do pacote Python: meu_projeto
Descrição do projeto: Meu novo projeto Python
Versão mínima do Python: 3.12
Nome do autor: Charles
E-mail do autor:
Adicionar configuração do Pytest? Yes
Adicionar configuração do Ruff? Yes
O Copier utilizará essas informações para gerar os arquivos do projeto.
Após a execução do Copier, a estrutura será semelhante a:
meu_projeto/
│
├── .env
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
│
├── docs/
│ └── index.md
│
├── scripts/
│ └── README.md
│
├── src/
│ └── meu_projeto/
│ ├── __init__.py
│ └── __main__.py
│
└── tests/
├── __init__.py
├── unit/
│ └── __init__.py
├── integration/
│ └── __init__.py
└── e2e/
└── __init__.py
Entre no diretório do projeto:
cd meu_projetoExecute:
Execute uma linha por vez
uv python list
uv venv --python "py_version"
uv syncO uv irá:
- criar o ambiente virtual
.venv; - resolver as dependências;
- instalar as dependências caso já tenha;
- instalar o próprio projeto em modo editável.
Após isso, o ambiente estará pronto para utilização.
O projeto possui um __main__.py, permitindo sua execução através do Python.
Utilize:
uv run python -m meu_projetoExemplo de saída:
Hello from meu_projeto!
Caso o Pytest esteja habilitado no template:
uv run pytestPara executar testes com informações mais detalhadas:
uv run pytest -vOs testes estão organizados em:
tests/
├── unit/
├── integration/
└── e2e/
Para executar o lint:
uv run ruff check .Para corrigir automaticamente problemas que possam ser corrigidos pelo Ruff:
uv run ruff check . --fixPara formatar o projeto:
uv run ruff format .Para apenas verificar se o código está formatado:
uv run ruff format --check .O Copier também permite atualizar um projeto existente a partir do template.
Dentro do projeto gerado:
copier updateAntes de executar a atualização em um projeto real, recomenda-se verificar as alterações que serão aplicadas e manter o projeto versionado com Git.
Um fluxo seguro é:
git status
git add .
git commit -m "chore: save current state before template update"
copier updateDepois:
git diffpara revisar as alterações.
Após gerar o projeto, inicialize um repositório Git:
git initAdicione os arquivos:
git add .Crie o primeiro commit:
git commit -m "chore: initial project structure"Para conectar ao GitHub:
git remote add origin https://github.com/USUARIO/REPOSITORIO.gitDepois:
git branch -M main
git push -u origin mainCharles
Repositório: Repo New project Python Template