Skip to content

project-structure.pt-BR.md

Latest commit

 

History

History
132 lines (119 loc) · 7.66 KB

project-structure.pt-BR.md

File metadata and controls

132 lines (119 loc) · 7.66 KB
Raw

Estrutura do Projeto

🇺🇸 English · 🇧🇷 Português · 🇪🇸 Español

Este documento descreve a estrutura atualmente versionada no repositório. Diretórios planejados não são apresentados como se já existissem.

Mapa atual do repositório

python-study-guide/
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug-report.yml
│   │   ├── config.yml
│   │   ├── content-suggestion.yml
│   │   ├── learning-question.yml
│   │   ├── private-contact-request.yml
│   │   └── translation-improvement.yml
│   ├── workflows/
│   │   └── quality-checks.yml
│   └── pull_request_template.md
├── .gitignore
├── AGENTS.md
├── AUTHORS.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── SECURITY.md
├── SUPPORT.md
├── assets/
│   ├── README.md
│   ├── banner.png
│   ├── banner.svg
│   ├── logo-mark.png
│   ├── logo.png
│   ├── repository-preview.png
│   └── repository-preview.svg
├── comments-and-documentation/
│   ├── README.md
│   ├── README.pt-BR.md
│   ├── README.es.md
│   └── 01-comments/
│       ├── README.md
│       ├── README.pt-BR.md
│       ├── README.es.md
│       └── examples/
│           ├── business_rule_comments.py
│           ├── unnecessary_comments.py
│           └── useful_comments.py
├── docs/
│   ├── ai-assisted-development/
│   │   ├── README.en.md
│   │   ├── README.pt-BR.md
│   │   └── README.es.md
│   ├── localized/
│   │   ├── AUTHORS.pt-BR.md
│   │   ├── AUTHORS.es.md
│   │   ├── CODE_OF_CONDUCT.pt-BR.md
│   │   ├── CODE_OF_CONDUCT.es.md
│   │   ├── CONTRIBUTING.pt-BR.md
│   │   ├── CONTRIBUTING.es.md
│   │   ├── README.pt-BR.md
│   │   ├── README.es.md
│   │   ├── SECURITY.pt-BR.md
│   │   ├── SECURITY.es.md
│   │   ├── SUPPORT.pt-BR.md
│   │   └── SUPPORT.es.md
│   ├── project-structure.en.md
│   ├── project-structure.pt-BR.md
│   ├── project-structure.es.md
│   ├── roadmap.en.md
│   ├── roadmap.pt-BR.md
│   └── roadmap.es.md
├── exercises/
│   └── README.md
├── external-libraries/
│   └── README.md
├── functions/
│   └── README.md
├── fundamentals/
│   └── README.md
├── practical-projects/
│   └── README.md
├── scripts/
│   ├── check_internal_links.py
│   ├── example_manifest.txt
│   ├── run_examples.py
│   └── validate_repository_structure.py
├── standard-library/
│   └── README.md
└── tests/
    ├── README.md
    └── test_check_internal_links.py

Guia dos arquivos da raiz

  • .gitignore: impede que artefatos locais do Python e outros arquivos gerados sejam versionados.
  • AGENTS.md: reúne instruções gerais do repositório para colaboradores e agentes de IA.
  • AUTHORS.md: registro canônico em inglês sobre autoria, manutenção e crédito das contribuições.
  • CODE_OF_CONDUCT.md: política canônica em inglês sobre conduta e relatos privados, reconhecida pelo GitHub.
  • CONTRIBUTING.md: fluxo canônico em inglês para contribuições e critérios de qualidade, reconhecido pelo GitHub.
  • LICENSE: contém a Licença MIT aplicada ao repositório.
  • README.md: porta de entrada canônica em inglês reconhecida pelo GitHub.
  • SECURITY.md: política canônica em inglês sobre segurança e relatos privados de vulnerabilidades, reconhecida pelo GitHub.
  • SUPPORT.md: orientação canônica em inglês sobre canais e limites do suporte do projeto.

Guia de diretórios

  • .github/: configuração de colaboração e automação do GitHub. O template de pull request solicita escopo, validação, alinhamento entre idiomas, declaração de assistência por IA, verificações de privacidade e observações para revisão. Os formulários de issue separam relatos de erros, sugestões de conteúdo, perguntas de aprendizagem, melhorias de tradução e solicitações seguras de um canal privado. O config.yml desativa issues em branco sem estrutura e direciona às orientações de contribuição, segurança e conduta. O workflow quality-checks.yml compila arquivos Python, executa testes de regressão das ferramentas de qualidade e exemplos aprovados, verifica caminhos internos em Markdown e valida a estrutura do repositório em pull requests e envios para a main.
  • assets/: identidade visual original do projeto, com arquivos PNG finais para o banner, logo principal transparente, símbolo compacto e prévia do repositório. O diretório também contém composições SVG editáveis que incorporam arte raster e, por isso, não são infinitamente escaláveis, além da documentação da paleta, significados, orientações de acessibilidade e regras de uso.
  • comments-and-documentation/: trilha sobre comentários, docstrings, nomes, marcadores de tarefas, decisões de logging, PEP 8 e código legível. O primeiro capítulo está disponível em 01-comments/.
  • docs/: roadmaps, arquitetura do projeto, políticas e documentos multilíngues de referência. O diretório ai-assisted-development/ explica o uso responsável de ChatGPT e Codex no fluxo do projeto. O diretório localized/ contém as versões em português brasileiro e espanhol dos documentos principais do projeto, autoria, contribuição, conduta, segurança e suporte. Manter somente os arquivos canônicos em inglês na raiz evita detecção ambígua das abas automáticas do GitHub sem reduzir a navegação multilíngue.
  • exercises/: futuras atividades práticas relacionadas aos capítulos.
  • external-libraries/: futuros guias sobre pacotes de terceiros instalados separadamente.
  • functions/: futura trilha sobre criação de funções, parâmetros, argumentos, retornos, escopo, type hints e colaboração entre funções.
  • fundamentals/: futura trilha sobre variáveis, tipos de dados, entrada, saída, strings, números, coleções e controle de fluxo.
  • practical-projects/: futuros projetos pequenos que combinarão vários conceitos.
  • scripts/: ferramentas de manutenção sem dependências externas, utilizadas localmente e pelo GitHub Actions para executar exemplos aprovados, verificar links internos e validar a estrutura do repositório.
  • standard-library/: futuros guias sobre módulos distribuídos com o Python.
  • tests/: testes de regressão das ferramentas de qualidade do repositório e, futuramente, testes automatizados dos exemplos educacionais e projetos práticos.

Convenções de nomes e idiomas

Os diretórios, nomes de arquivos, variáveis, funções, classes e demais identificadores do código usam inglês. Os documentos explicativos são oferecidos em inglês, português brasileiro e espanhol.

O inglês utiliza os arquivos canônicos da raiz reconhecidos automaticamente pelo GitHub. As versões em português brasileiro e espanhol desses documentos ficam em docs/localized/. Seções de aprendizagem podem manter os READMEs traduzidos ao lado do capítulo em inglês quando isso melhorar a navegação.

Regra de manutenção

Um pull request que mover, criar ou remover caminhos importantes deverá atualizar esta estrutura na mesma alteração. Diretórios de capítulos planejados deverão ser adicionados somente quando contiverem material útil, e não como placeholders vazios.