Bidu's Python Template

copier copy gh:fbidu/cookie-py my-project

---

🇬🇧 English Description

Esse é um modelo de projeto Python usando Copier que inclui várias ferramentas modernas que gosto de usar.

Um template Copier serve para criar novos projetos com base em um formato pré-definido. No caso em todo projeto Python, eu gosto de usar certas ferramentas como Ruff, PyTest, Pyright, prek e uv. Esse meu modelo instala tudo e configura tudo isso para mim!

É um modelo fortemente enviesado para o que eu gosto, uma vez que ele reflete minhas escolhas particulares sobre ferramentas, análises estáticas, hooks e etc.

Sinta-se livre para usar, forkear e modificar a vontade!

Uso

1. Instale o uv
2. Instale o Copier: uv tool install copier
3. Execute copier copy gh:fbidu/cookie-py meu-projeto
4. O seu terminal irá te perguntar tudo o que precisar!

Respostas pessoais

Algumas respostas são as mesmas em todo projeto e não cabem em um modelo público, como o host da documentação (docs_host). O Copier lê respostas padrão de um arquivo de configurações na sua máquina: o settings.yml do diretório de configuração do Copier, ou o caminho na variável COPIER_SETTINGS_PATH.

defaults:
  docs_host: docs.example.com

A resposta fica registrada no .copier-answers.yml do projeto gerado, então um copier update posterior não depende desse arquivo.

Itens Inclusos

Itens marcados estão implementados!

• Usar o uv para gerenciar pacotes e ambientes virtuais
• Usar o prek para cuidar de hooks pre-commit do git
• Instalar o Pytest com plugins úteis (coverage, xdist, randomly)
• Instalar o Ruff para formatação e linting
• Instalar o Pyright para verificação de tipos
• Executar Pytest pre-push
• Relatório de Coverage no Pytest
• Configurações modernas em pyproject.toml
• Pipeline de CI opcional (GitHub Actions ou Forgejo Actions)
• Site de documentação MkDocs em todo projeto, com publicação opcional no Forgejo
• Tipo de projeto só de documentação, sem pacote Python
• Tipo de projeto cliente de API, com cliente httpx2, erros próprios e configurações via pydantic-settings
• Opção spec-first para clientes de API: agentes que escrevem o openapi.yaml a partir da documentação da API, uma skill que os configura e modelos pydantic gerados do documento
• Atualização de projetos existentes com copier update

Hooks Habilitados

• Ruff (linting e formatação)
• Pyright (verificação de tipos)
• Bandit (segurança)
• actionlint (valida workflows do GitHub Actions, quando aplicável)
• MkDocs (build estrito da documentação)
• Hooks básicos (trailing whitespace, end-of-file, etc.)

---

English

This is a Python project template using Copier that includes modern tools I like to use.

A Copier template is useful to create new projects based on a pre-defined model. In every Python project I like to use some tools like Ruff, PyTest, Pyright, prek and uv. This template installs and sets up all those tools for me!

It is highly opinionated since it reflects my personal choices about tooling, static analysis, hooks and so on.

Feel free to use, fork and modify at will!

Usage

1. Install uv
2. Install Copier: uv tool install copier
3. Run copier copy gh:fbidu/cookie-py my-project
4. Your terminal will ask you everything it needs!

Personal answers

Some answers are the same in every project and do not belong in a public template, such as the docs host (docs_host). Copier reads default answers from a settings file on your machine: settings.yml in Copier's config directory, or the path in the COPIER_SETTINGS_PATH variable.

defaults:
  docs_host: docs.example.com

The answer is recorded in the .copier-answers.yml of the generated project, so a later copier update does not depend on that file.

Batteries Included

Checked items are implemented

• Use uv to manage packages and virtual environments
• Use prek to handle git pre-commit hooks
• Install Pytest with useful plugins (coverage, xdist, randomly)
• Install Ruff for linting and formatting
• Install Pyright for type checking
• Run Pytest pre-push
• Coverage report on Pytest
• Modern pyproject.toml configuration
• Optional CI pipeline (GitHub Actions or Forgejo Actions)
• MkDocs documentation site in every project, with optional publishing on Forgejo
• Docs-only project type, with no Python package
• API client project type, with an httpx2 client, its own errors and pydantic-settings
• Spec-first option for API clients: agents that write openapi.yaml from the API's documentation, a skill that sets them up and pydantic models generated from the document
• Update existing projects with copier update

Hooks

• Ruff (linting and formatting)
• Pyright (type checking)
• Bandit (security)
• actionlint (validates GitHub Actions workflows, when applicable)
• MkDocs (strict build of the documentation)
• Basic hooks (trailing whitespace, end-of-file, etc.)