From e7314083aae85136c71538e035f2670cfcb3f33e Mon Sep 17 00:00:00 2001 From: Ramon Rodriguez Date: Wed, 26 Aug 2026 21:57:21 -0300 Subject: [PATCH] Add imports modules and packages chapter --- README.md | 4 +- docs/learning-path.en.md | 5 +- docs/learning-path.es.md | 5 +- docs/learning-path.pt-BR.md | 5 +- docs/localized/README.es.md | 4 +- docs/localized/README.pt-BR.md | 4 +- docs/project-structure.en.md | 25 +- docs/project-structure.es.md | 25 +- docs/project-structure.pt-BR.md | 25 +- docs/roadmap.en.md | 8 +- docs/roadmap.es.md | 8 +- docs/roadmap.pt-BR.md | 8 +- .../README.es.md | 1034 +++++++++++++++++ .../05-imports-modules-and-packages/README.md | 1034 +++++++++++++++++ .../README.pt-BR.md | 1034 +++++++++++++++++ .../examples/grade_tools.py | 4 + .../examples/import_standard_library.py | 7 + .../examples/main_guard.py | 6 + .../examples/module_demo.py | 7 + .../examples/package_demo.py | 4 + .../examples/study_tools/__init__.py | 3 + .../examples/study_tools/formatting.py | 2 + errors-files-and-modules/README.es.md | 33 +- errors-files-and-modules/README.md | 33 +- errors-files-and-modules/README.pt-BR.md | 33 +- scripts/example_manifest.txt | 4 + 26 files changed, 3292 insertions(+), 72 deletions(-) create mode 100644 errors-files-and-modules/05-imports-modules-and-packages/README.es.md create mode 100644 errors-files-and-modules/05-imports-modules-and-packages/README.md create mode 100644 errors-files-and-modules/05-imports-modules-and-packages/README.pt-BR.md create mode 100644 errors-files-and-modules/05-imports-modules-and-packages/examples/grade_tools.py create mode 100644 errors-files-and-modules/05-imports-modules-and-packages/examples/import_standard_library.py create mode 100644 errors-files-and-modules/05-imports-modules-and-packages/examples/main_guard.py create mode 100644 errors-files-and-modules/05-imports-modules-and-packages/examples/module_demo.py create mode 100644 errors-files-and-modules/05-imports-modules-and-packages/examples/package_demo.py create mode 100644 errors-files-and-modules/05-imports-modules-and-packages/examples/study_tools/__init__.py create mode 100644 errors-files-and-modules/05-imports-modules-and-packages/examples/study_tools/formatting.py diff --git a/README.md b/README.md index 947b514..a1c3efd 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ Detailed explanations: The project foundation is complete. Phase 0 established the multilingual documentation, contribution workflow, collaboration templates, community standards, authorship, licensing, AI governance, automated quality checks, original visual identity, scalable repository structure, and final foundation audit. -The project foundation and six complete educational sections are available, and [Phase 7: Errors, Files, and Modules](errors-files-and-modules/README.md) is now in progress. [Phase 1: Fundamentals](fundamentals/README.md) provides six reviewed beginner chapters. Phase 6 contains six reviewed learning chapters: +The project foundation and seven complete educational sections are available. [Phase 7: Errors, Files, and Modules](errors-files-and-modules/README.md) is complete with five reviewed chapters, and Phase 8: Standard Library is the next planned learning section. [Phase 1: Fundamentals](fundamentals/README.md) provides six reviewed beginner chapters. Phase 6 contains six reviewed learning chapters: - [Comments in Python](comments-and-documentation/01-comments/README.md) - [Docstrings in Python](comments-and-documentation/02-docstrings/README.md) @@ -85,7 +85,7 @@ The project foundation and six complete educational sections are available, and - [Comments versus Logging in Python](comments-and-documentation/05-comments-vs-logging/README.md) - [PEP 8 and Readability in Python](comments-and-documentation/06-pep8-and-readability/README.md) -Phases 1, 2, 3, 4, 5, and 6 are complete. Phase 7 now includes four reviewed chapters: exception handling; deliberate raising and custom exceptions; safe file handling with `open()` and `with`; and [Working with TXT, CSV, and JSON](errors-files-and-modules/04-txt-csv-and-json/README.md), which adds line-oriented text contracts, CSV parsing and writing, JSON serialization and deserialization, and the boundary between parsing and validation. Phase 5: Functions contains nine reviewed chapters: [Defining and Calling Functions](functions/01-defining-and-calling-functions/README.md), [Parameters and Arguments](functions/02-parameters-and-arguments/README.md), [Return Values](functions/03-return-values/README.md), [Scope](functions/04-scope/README.md), [Type Hints](functions/05-type-hints/README.md), [Default Values](functions/06-default-values/README.md), [`*args` and `**kwargs`](functions/07-args-and-kwargs/README.md), [Functions Working Together](functions/08-functions-working-together/README.md), and [Data Flow Between Functions](functions/09-data-flow-between-functions/README.md). Together they establish function definition and calling, required input flow, returned results, local and global scope, typed interfaces, safe optional inputs, intentionally flexible positional and keyword argument collection, composition through helpers and coordinators, and explicit caller-to-parameter-to-return data flow including rebinding versus mutation. Phase 4 remains complete with eight reviewed Program Flow chapters, ending with [Choosing and Combining Program Flow](program-flow/08-choosing-and-combining-program-flow/README.md). Phase 3 contains six reviewed Collections chapters, ending with [Choosing the Right Collection](collections/06-choosing-the-right-collection/README.md). Phase 2 remains complete with four reviewed chapters, ending with [Numeric Built-ins](strings-and-numbers/04-numeric-builtins/README.md). See the [roadmap](docs/roadmap.en.md) or the [full learning path](docs/learning-path.en.md) for the current curriculum status and direct chapter links. +Phases 1, 2, 3, 4, 5, 6, and 7 are complete. Phase 7 contains five reviewed chapters: exception handling; deliberate raising and custom exceptions; safe file handling with `open()` and `with`; [Working with TXT, CSV, and JSON](errors-files-and-modules/04-txt-csv-and-json/README.md); and [Organizing Code with Imports, Modules, and Packages](errors-files-and-modules/05-imports-modules-and-packages/README.md), which closes the phase with explicit module imports, regular package structure, the main guard, import search context, absolute and relative imports, `python -m`, and dependency design. Phase 5: Functions contains nine reviewed chapters: [Defining and Calling Functions](functions/01-defining-and-calling-functions/README.md), [Parameters and Arguments](functions/02-parameters-and-arguments/README.md), [Return Values](functions/03-return-values/README.md), [Scope](functions/04-scope/README.md), [Type Hints](functions/05-type-hints/README.md), [Default Values](functions/06-default-values/README.md), [`*args` and `**kwargs`](functions/07-args-and-kwargs/README.md), [Functions Working Together](functions/08-functions-working-together/README.md), and [Data Flow Between Functions](functions/09-data-flow-between-functions/README.md). Together they establish function definition and calling, required input flow, returned results, local and global scope, typed interfaces, safe optional inputs, intentionally flexible positional and keyword argument collection, composition through helpers and coordinators, and explicit caller-to-parameter-to-return data flow including rebinding versus mutation. Phase 4 remains complete with eight reviewed Program Flow chapters, ending with [Choosing and Combining Program Flow](program-flow/08-choosing-and-combining-program-flow/README.md). Phase 3 contains six reviewed Collections chapters, ending with [Choosing the Right Collection](collections/06-choosing-the-right-collection/README.md). Phase 2 remains complete with four reviewed chapters, ending with [Numeric Built-ins](strings-and-numbers/04-numeric-builtins/README.md). See the [roadmap](docs/roadmap.en.md) or the [full learning path](docs/learning-path.en.md) for the current curriculum status and direct chapter links. ## Visual identity diff --git a/docs/learning-path.en.md b/docs/learning-path.en.md index fe4ecc9..211a636 100644 --- a/docs/learning-path.en.md +++ b/docs/learning-path.en.md @@ -87,7 +87,7 @@ This phase is already available and is the next recommended phase after Function 5. [Comments versus Logging in Python](../comments-and-documentation/05-comments-vs-logging/README.md) 6. [PEP 8 and Readability in Python](../comments-and-documentation/06-pep8-and-readability/README.md) -## Phase 7 · Errors, Files, and Modules 🚧 +## Phase 7 · Errors, Files, and Modules ✅ [Open the Errors, Files, and Modules section index](../errors-files-and-modules/README.md) @@ -95,8 +95,9 @@ This phase is already available and is the next recommended phase after Function 2. [Raising and Custom Exceptions](../errors-files-and-modules/02-raise-and-custom-exceptions/README.md) 3. [Opening Files Safely with `open()` and `with`](../errors-files-and-modules/03-open-and-with/README.md) 4. [Working with TXT, CSV, and JSON](../errors-files-and-modules/04-txt-csv-and-json/README.md) +5. [Organizing Code with Imports, Modules, and Packages](../errors-files-and-modules/05-imports-modules-and-packages/README.md) -Phase 7 is in progress. Chapters 01–02 establish exception handling and deliberate signaling. Chapter 03 adds safe file lifetime and text I/O. Chapter 04 adds TXT contracts, CSV parsing and writing, JSON serialization and deserialization, and explicit parsing-versus-validation boundaries. The next planned chapter is **Imports, Modules, and Packages**. +Phase 7 is complete with five reviewed chapters. Chapters 01–02 establish exception handling and deliberate signaling. Chapter 03 adds safe file lifetime and text I/O. Chapter 04 adds TXT, CSV, and JSON data boundaries. Chapter 05 closes the phase with modules, regular packages, `__name__`, the main guard, import search context, absolute and relative imports, `python -m`, and dependency design. ## Phase 8 · Standard Library ⏳ diff --git a/docs/learning-path.es.md b/docs/learning-path.es.md index aa6ba87..c21266a 100644 --- a/docs/learning-path.es.md +++ b/docs/learning-path.es.md @@ -87,7 +87,7 @@ Esta fase ya está disponible y es la siguiente fase recomendada después de Fun 5. [Comentarios frente a Logging en Python](../comments-and-documentation/05-comments-vs-logging/README.es.md) 6. [PEP 8 y legibilidad en Python](../comments-and-documentation/06-pep8-and-readability/README.es.md) -## Fase 7 · Errores, Archivos y Módulos 🚧 +## Fase 7 · Errores, Archivos y Módulos ✅ [Abrir el índice de la sección Errores, Archivos y Módulos](../errors-files-and-modules/README.es.md) @@ -95,8 +95,9 @@ Esta fase ya está disponible y es la siguiente fase recomendada después de Fun 2. [Lanzar Excepciones y Crear Excepciones Personalizadas](../errors-files-and-modules/02-raise-and-custom-exceptions/README.es.md) 3. [Abrir Archivos de Forma Segura con `open()` y `with`](../errors-files-and-modules/03-open-and-with/README.es.md) 4. [Trabajar con TXT, CSV y JSON](../errors-files-and-modules/04-txt-csv-and-json/README.es.md) +5. [Organizar Código con Imports, Módulos y Paquetes](../errors-files-and-modules/05-imports-modules-and-packages/README.es.md) -La Fase 7 está en progreso. Los Capítulos 01–02 establecen manejo y señalización deliberada de excepciones. El Capítulo 03 añade un tiempo de vida seguro de archivos e I/O de texto. El Capítulo 04 añade contratos TXT, parsing y escritura de CSV, serialización y deserialización JSON y límites explícitos entre parsing y validación. El próximo capítulo planificado es **Imports, Módulos y Paquetes**. +La Fase 7 está completada con cinco capítulos revisados. Los Capítulos 01–02 establecen manejo y señalización deliberada de excepciones. El Capítulo 03 añade un tiempo de vida seguro de archivos e I/O de texto. El Capítulo 04 añade límites de datos TXT, CSV y JSON. El Capítulo 05 cierra la fase con módulos, paquetes regulares, `__name__`, main guard, contexto de búsqueda de imports, imports absolutos y relativos, `python -m` y diseño de dependencias. ## Fase 8 · Biblioteca Estándar ⏳ diff --git a/docs/learning-path.pt-BR.md b/docs/learning-path.pt-BR.md index e123a6a..13bf58b 100644 --- a/docs/learning-path.pt-BR.md +++ b/docs/learning-path.pt-BR.md @@ -87,7 +87,7 @@ Esta fase já está disponível e é a próxima fase recomendada depois de Funç 5. [Comentários versus Logging em Python](../comments-and-documentation/05-comments-vs-logging/README.pt-BR.md) 6. [PEP 8 e legibilidade em Python](../comments-and-documentation/06-pep8-and-readability/README.pt-BR.md) -## Fase 7 · Erros, Arquivos e Módulos 🚧 +## Fase 7 · Erros, Arquivos e Módulos ✅ [Abrir o índice da seção Erros, Arquivos e Módulos](../errors-files-and-modules/README.pt-BR.md) @@ -95,8 +95,9 @@ Esta fase já está disponível e é a próxima fase recomendada depois de Funç 2. [Levantando Exceções e Criando Exceções Personalizadas](../errors-files-and-modules/02-raise-and-custom-exceptions/README.pt-BR.md) 3. [Abrindo Arquivos com Segurança com `open()` e `with`](../errors-files-and-modules/03-open-and-with/README.pt-BR.md) 4. [Trabalhando com TXT, CSV e JSON](../errors-files-and-modules/04-txt-csv-and-json/README.pt-BR.md) +5. [Organizando Código com Imports, Módulos e Pacotes](../errors-files-and-modules/05-imports-modules-and-packages/README.pt-BR.md) -A Fase 7 está em andamento. Os Capítulos 01–02 estabelecem tratamento e sinalização deliberada de exceções. O Capítulo 03 acrescenta tempo de vida seguro de arquivos e I/O de texto. O Capítulo 04 adiciona contratos TXT, parsing e escrita de CSV, serialização e desserialização JSON e fronteiras explícitas entre parsing e validação. O próximo capítulo planejado é **Imports, Módulos e Pacotes**. +A Fase 7 está concluída com cinco capítulos revisados. Os Capítulos 01–02 estabelecem tratamento e sinalização deliberada de exceções. O Capítulo 03 acrescenta tempo de vida seguro de arquivos e I/O de texto. O Capítulo 04 adiciona fronteiras de dados TXT, CSV e JSON. O Capítulo 05 encerra a fase com módulos, pacotes regulares, `__name__`, main guard, contexto de busca de imports, imports absolutos e relativos, `python -m` e design de dependências. ## Fase 8 · Biblioteca Padrão ⏳ diff --git a/docs/localized/README.es.md b/docs/localized/README.es.md index 1651bc0..7f9eb2c 100644 --- a/docs/localized/README.es.md +++ b/docs/localized/README.es.md @@ -76,7 +76,7 @@ Explicaciones detalladas: La base del proyecto está completada. La Fase 0 estableció la documentación multilingüe, el flujo de contribución, las plantillas de colaboración, los estándares de la comunidad, la autoría, la licencia, la gobernanza de IA, las verificaciones automáticas, la identidad visual original, la estructura escalable y la auditoría final de la base. -La base del proyecto y seis secciones educativas completas están disponibles, y la [Fase 7: Errores, Archivos y Módulos](../../errors-files-and-modules/README.es.md) está ahora en progreso. La [Fase 1: Fundamentos](../../fundamentals/README.es.md) ofrece seis capítulos revisados para principiantes. La Fase 6 reúne seis capítulos de aprendizaje revisados: +La base del proyecto y siete secciones educativas completas están disponibles. La [Fase 7: Errores, Archivos y Módulos](../../errors-files-and-modules/README.es.md) está completada con cinco capítulos revisados, y la Fase 8: Biblioteca Estándar es la siguiente sección de aprendizaje planificada. La [Fase 1: Fundamentos](../../fundamentals/README.es.md) ofrece seis capítulos revisados para principiantes. La Fase 6 reúne seis capítulos de aprendizaje revisados: - [Comentarios en Python](../../comments-and-documentation/01-comments/README.es.md) - [Docstrings en Python](../../comments-and-documentation/02-docstrings/README.es.md) @@ -85,7 +85,7 @@ La base del proyecto y seis secciones educativas completas están disponibles, y - [Comentarios frente a Logging en Python](../../comments-and-documentation/05-comments-vs-logging/README.es.md) - [PEP 8 y Legibilidad en Python](../../comments-and-documentation/06-pep8-and-readability/README.es.md) -Las Fases 1, 2, 3, 4, 5 y 6 están completadas. La Fase 7 ahora incluye cuatro capítulos revisados: manejo de excepciones; lanzamiento y excepciones personalizadas; uso seguro de archivos con `open()` y `with`; y [Trabajar con TXT, CSV y JSON](../../errors-files-and-modules/04-txt-csv-and-json/README.es.md), que añade contratos de texto orientados a líneas, parsing y escritura de CSV, serialización y deserialización JSON y el límite entre parsing y validación. La Fase 5: Funciones reúne nueve capítulos revisados: [Definir y Llamar Funciones](../../functions/01-defining-and-calling-functions/README.es.md), [Parámetros y Argumentos](../../functions/02-parameters-and-arguments/README.es.md), [Valores de Retorno](../../functions/03-return-values/README.es.md), [Alcance](../../functions/04-scope/README.es.md), [Type Hints](../../functions/05-type-hints/README.es.md), [Valores Predeterminados](../../functions/06-default-values/README.es.md), [`*args` y `**kwargs`](../../functions/07-args-and-kwargs/README.es.md), [Funciones Trabajando Juntas](../../functions/08-functions-working-together/README.es.md) y [Flujo de Datos Entre Funciones](../../functions/09-data-flow-between-functions/README.es.md). Juntos establecen definición y llamada, flujo de entrada obligatorio, resultados retornados, alcance local y global, interfaces tipadas, entradas opcionales seguras, recolección intencionalmente flexible de argumentos posicionales y por palabra clave, composición mediante funciones auxiliares y coordinadoras y flujo explícito desde el llamador hacia parámetros y retornos, incluida la reasignación frente a la mutación. La Fase 4 permanece completada con ocho capítulos revisados de Flujo del Programa, terminando con [Elegir y Combinar el Flujo del Programa](../../program-flow/08-choosing-and-combining-program-flow/README.es.md). La Fase 3 reúne seis capítulos revisados de Colecciones, terminando con [Elegir la Colección Adecuada](../../collections/06-choosing-the-right-collection/README.es.md). La Fase 2 permanece completada con cuatro capítulos revisados, terminando con [Funciones Numéricas Incorporadas](../../strings-and-numbers/04-numeric-builtins/README.es.md). Consulta el [roadmap](../roadmap.es.md) o la [ruta completa de aprendizaje](../learning-path.es.md) para seguir el estado del currículo y acceder directamente a los capítulos. +Las Fases 1, 2, 3, 4, 5, 6 y 7 están completadas. La Fase 7 reúne cinco capítulos revisados: manejo de excepciones; lanzamiento y excepciones personalizadas; uso seguro de archivos con `open()` y `with`; [Trabajar con TXT, CSV y JSON](../../errors-files-and-modules/04-txt-csv-and-json/README.es.md); y [Organizar Código con Imports, Módulos y Paquetes](../../errors-files-and-modules/05-imports-modules-and-packages/README.es.md), que cierra la fase con imports explícitos de módulos, estructura de paquete regular, main guard, contexto de búsqueda de imports, imports absolutos y relativos, `python -m` y diseño de dependencias. La Fase 5: Funciones reúne nueve capítulos revisados: [Definir y Llamar Funciones](../../functions/01-defining-and-calling-functions/README.es.md), [Parámetros y Argumentos](../../functions/02-parameters-and-arguments/README.es.md), [Valores de Retorno](../../functions/03-return-values/README.es.md), [Alcance](../../functions/04-scope/README.es.md), [Type Hints](../../functions/05-type-hints/README.es.md), [Valores Predeterminados](../../functions/06-default-values/README.es.md), [`*args` y `**kwargs`](../../functions/07-args-and-kwargs/README.es.md), [Funciones Trabajando Juntas](../../functions/08-functions-working-together/README.es.md) y [Flujo de Datos Entre Funciones](../../functions/09-data-flow-between-functions/README.es.md). Juntos establecen definición y llamada, flujo de entrada obligatorio, resultados retornados, alcance local y global, interfaces tipadas, entradas opcionales seguras, recolección intencionalmente flexible de argumentos posicionales y por palabra clave, composición mediante funciones auxiliares y coordinadoras y flujo explícito desde el llamador hacia parámetros y retornos, incluida la reasignación frente a la mutación. La Fase 4 permanece completada con ocho capítulos revisados de Flujo del Programa, terminando con [Elegir y Combinar el Flujo del Programa](../../program-flow/08-choosing-and-combining-program-flow/README.es.md). La Fase 3 reúne seis capítulos revisados de Colecciones, terminando con [Elegir la Colección Adecuada](../../collections/06-choosing-the-right-collection/README.es.md). La Fase 2 permanece completada con cuatro capítulos revisados, terminando con [Funciones Numéricas Incorporadas](../../strings-and-numbers/04-numeric-builtins/README.es.md). Consulta el [roadmap](../roadmap.es.md) o la [ruta completa de aprendizaje](../learning-path.es.md) para seguir el estado del currículo y acceder directamente a los capítulos. ## Identidad visual diff --git a/docs/localized/README.pt-BR.md b/docs/localized/README.pt-BR.md index ae52de1..e664664 100644 --- a/docs/localized/README.pt-BR.md +++ b/docs/localized/README.pt-BR.md @@ -76,7 +76,7 @@ Explicações detalhadas: A fundação do projeto está concluída. A Fase 0 estabeleceu a documentação multilíngue, o fluxo de contribuição, os templates de colaboração, os padrões da comunidade, a autoria, a licença, a governança de IA, as validações automáticas, a identidade visual original, a estrutura escalável e a auditoria final da fundação. -A fundação do projeto e seis seções educacionais completas estão disponíveis, e a [Fase 7: Erros, Arquivos e Módulos](../../errors-files-and-modules/README.pt-BR.md) agora está em andamento. A [Fase 1: Fundamentos](../../fundamentals/README.pt-BR.md) oferece seis capítulos revisados para iniciantes. A Fase 6 reúne seis capítulos de aprendizagem revisados: +A fundação do projeto e sete seções educacionais completas estão disponíveis. A [Fase 7: Erros, Arquivos e Módulos](../../errors-files-and-modules/README.pt-BR.md) está concluída com cinco capítulos revisados, e a Fase 8: Biblioteca Padrão é a próxima seção de aprendizagem planejada. A [Fase 1: Fundamentos](../../fundamentals/README.pt-BR.md) oferece seis capítulos revisados para iniciantes. A Fase 6 reúne seis capítulos de aprendizagem revisados: - [Comentários em Python](../../comments-and-documentation/01-comments/README.pt-BR.md) - [Docstrings em Python](../../comments-and-documentation/02-docstrings/README.pt-BR.md) @@ -85,7 +85,7 @@ A fundação do projeto e seis seções educacionais completas estão disponíve - [Comentários versus Logging em Python](../../comments-and-documentation/05-comments-vs-logging/README.pt-BR.md) - [PEP 8 e Legibilidade em Python](../../comments-and-documentation/06-pep8-and-readability/README.pt-BR.md) -As Fases 1, 2, 3, 4, 5 e 6 estão concluídas. A Fase 7 agora inclui quatro capítulos revisados: tratamento de exceções; levantamento e exceções personalizadas; uso seguro de arquivos com `open()` e `with`; e [Trabalhando com TXT, CSV e JSON](../../errors-files-and-modules/04-txt-csv-and-json/README.pt-BR.md), que acrescenta contratos de texto orientados por linhas, parsing e escrita de CSV, serialização e desserialização JSON e a fronteira entre parsing e validação. A Fase 5: Funções reúne nove capítulos revisados: [Definindo e Chamando Funções](../../functions/01-defining-and-calling-functions/README.pt-BR.md), [Parâmetros e Argumentos](../../functions/02-parameters-and-arguments/README.pt-BR.md), [Valores de Retorno](../../functions/03-return-values/README.pt-BR.md), [Escopo](../../functions/04-scope/README.pt-BR.md), [Type Hints](../../functions/05-type-hints/README.pt-BR.md), [Valores Padrão](../../functions/06-default-values/README.pt-BR.md), [`*args` e `**kwargs`](../../functions/07-args-and-kwargs/README.pt-BR.md), [Funções Trabalhando Juntas](../../functions/08-functions-working-together/README.pt-BR.md) e [Fluxo de Dados Entre Funções](../../functions/09-data-flow-between-functions/README.pt-BR.md). Juntos, eles estabelecem definição e chamada, fluxo de entrada obrigatório, resultados retornados, escopo local e global, interfaces tipadas, entradas opcionais seguras, coleta intencionalmente flexível de argumentos posicionais e nomeados, composição por funções auxiliares e coordenadoras e fluxo explícito do chamador aos parâmetros e retornos, incluindo reatribuição versus mutação. A Fase 4 permanece concluída com oito capítulos revisados de Fluxo do Programa, encerrando com [Escolhendo e Combinando o Fluxo do Programa](../../program-flow/08-choosing-and-combining-program-flow/README.pt-BR.md). A Fase 3 reúne seis capítulos revisados de Coleções, encerrando com [Escolhendo a Coleção Certa](../../collections/06-choosing-the-right-collection/README.pt-BR.md). A Fase 2 permanece concluída com quatro capítulos revisados, encerrando com [Funções Numéricas Embutidas](../../strings-and-numbers/04-numeric-builtins/README.pt-BR.md). Consulte o [roadmap](../roadmap.pt-BR.md) ou a [trilha completa de estudos](../learning-path.pt-BR.md) para acompanhar o status do currículo e acessar os capítulos diretamente. +As Fases 1, 2, 3, 4, 5, 6 e 7 estão concluídas. A Fase 7 reúne cinco capítulos revisados: tratamento de exceções; levantamento e exceções personalizadas; uso seguro de arquivos com `open()` e `with`; [Trabalhando com TXT, CSV e JSON](../../errors-files-and-modules/04-txt-csv-and-json/README.pt-BR.md); e [Organizando Código com Imports, Módulos e Pacotes](../../errors-files-and-modules/05-imports-modules-and-packages/README.pt-BR.md), que encerra a fase com imports explícitos de módulos, estrutura de pacote regular, main guard, contexto de busca de imports, imports absolutos e relativos, `python -m` e design de dependências. A Fase 5: Funções reúne nove capítulos revisados: [Definindo e Chamando Funções](../../functions/01-defining-and-calling-functions/README.pt-BR.md), [Parâmetros e Argumentos](../../functions/02-parameters-and-arguments/README.pt-BR.md), [Valores de Retorno](../../functions/03-return-values/README.pt-BR.md), [Escopo](../../functions/04-scope/README.pt-BR.md), [Type Hints](../../functions/05-type-hints/README.pt-BR.md), [Valores Padrão](../../functions/06-default-values/README.pt-BR.md), [`*args` e `**kwargs`](../../functions/07-args-and-kwargs/README.pt-BR.md), [Funções Trabalhando Juntas](../../functions/08-functions-working-together/README.pt-BR.md) e [Fluxo de Dados Entre Funções](../../functions/09-data-flow-between-functions/README.pt-BR.md). Juntos, eles estabelecem definição e chamada, fluxo de entrada obrigatório, resultados retornados, escopo local e global, interfaces tipadas, entradas opcionais seguras, coleta intencionalmente flexível de argumentos posicionais e nomeados, composição por funções auxiliares e coordenadoras e fluxo explícito do chamador aos parâmetros e retornos, incluindo reatribuição versus mutação. A Fase 4 permanece concluída com oito capítulos revisados de Fluxo do Programa, encerrando com [Escolhendo e Combinando o Fluxo do Programa](../../program-flow/08-choosing-and-combining-program-flow/README.pt-BR.md). A Fase 3 reúne seis capítulos revisados de Coleções, encerrando com [Escolhendo a Coleção Certa](../../collections/06-choosing-the-right-collection/README.pt-BR.md). A Fase 2 permanece concluída com quatro capítulos revisados, encerrando com [Funções Numéricas Embutidas](../../strings-and-numbers/04-numeric-builtins/README.pt-BR.md). Consulte o [roadmap](../roadmap.pt-BR.md) ou a [trilha completa de estudos](../learning-path.pt-BR.md) para acompanhar o status do currículo e acessar os capítulos diretamente. ## Identidade visual diff --git a/docs/project-structure.en.md b/docs/project-structure.en.md index 1378d93..1b532ac 100644 --- a/docs/project-structure.en.md +++ b/docs/project-structure.en.md @@ -165,15 +165,28 @@ python-study-guide/ │ │ ├── append_text.py │ │ ├── handle_missing_file.py │ │ └── write_and_read_text.py -│ └── 04-txt-csv-and-json/ +│ ├── 04-txt-csv-and-json/ +│ │ ├── README.md +│ │ ├── README.pt-BR.md +│ │ ├── README.es.md +│ │ └── examples/ +│ │ ├── csv_records.py +│ │ ├── handle_invalid_json.py +│ │ ├── json_document.py +│ │ └── text_records.py +│ └── 05-imports-modules-and-packages/ │ ├── README.md │ ├── README.pt-BR.md │ ├── README.es.md │ └── examples/ -│ ├── csv_records.py -│ ├── handle_invalid_json.py -│ ├── json_document.py -│ └── text_records.py +│ ├── grade_tools.py +│ ├── import_standard_library.py +│ ├── main_guard.py +│ ├── module_demo.py +│ ├── package_demo.py +│ └── study_tools/ +│ ├── __init__.py +│ └── formatting.py ├── exercises/ ├── external-libraries/ ├── functions/ @@ -425,7 +438,7 @@ python-study-guide/ - `comments-and-documentation/`: complete Phase 6 learning path. Reviewed chapters are available for comments, docstrings, meaningful names, task markers, comments versus logging, and PEP 8 and readability, each in English, Brazilian Portuguese, and Spanish with safe executable examples. - `collections/`: complete Phase 3 learning path. Its six chapters teach list creation, reading, mutation, common methods, shallow copying, tuples and immutability, dictionary key-value mappings and views, set uniqueness and relationships, and how to choose among lists, tuples, dictionaries, and sets by intent, in English, Brazilian Portuguese, and Spanish with safe executable examples. - `docs/`: master learning paths, roadmaps, project architecture, localized project documents, policies, and responsible AI-assisted development guidance. -- `errors-files-and-modules/`: in-progress Phase 7 learning path. Chapters 01–04 cover runtime exception handling, deliberate raising and custom exceptions, safe text-file I/O with `open()` and `with`, and TXT/CSV/JSON parsing, writing, conversion, and validation boundaries, in English, Brazilian Portuguese, and Spanish with deterministic executable examples. +- `errors-files-and-modules/`: complete Phase 7 learning path. Chapters 01–05 cover runtime exception handling, deliberate raising and custom exceptions, safe text-file I/O with `open()` and `with`, TXT/CSV/JSON parsing and writing, and code organization through imports, modules, regular packages, execution context, and dependency design, in English, Brazilian Portuguese, and Spanish with deterministic executable examples. - `exercises/`: focused practice activities connected to learning chapters. - `external-libraries/`: future guides to third-party packages. - `functions/`: complete Phase 5 learning path. Chapters 01–09 cover defining and calling functions, required inputs, returned values, scope and name lookup, type hints for function interfaces, default values including definition-time evaluation and mutable-default safety, variable-length positional and keyword argument collection with `*args` and `**kwargs`, composition through helper and coordinating functions with explicit dependencies and simple call graphs, and explicit data-flow tracing across calls including parameter bindings, rebinding versus mutation, `None`, tuple results, and return-based handoffs, in English, Brazilian Portuguese, and Spanish with deterministic executable examples. diff --git a/docs/project-structure.es.md b/docs/project-structure.es.md index 5589ca7..a60d2fe 100644 --- a/docs/project-structure.es.md +++ b/docs/project-structure.es.md @@ -165,15 +165,28 @@ python-study-guide/ │ │ ├── append_text.py │ │ ├── handle_missing_file.py │ │ └── write_and_read_text.py -│ └── 04-txt-csv-and-json/ +│ ├── 04-txt-csv-and-json/ +│ │ ├── README.md +│ │ ├── README.pt-BR.md +│ │ ├── README.es.md +│ │ └── examples/ +│ │ ├── csv_records.py +│ │ ├── handle_invalid_json.py +│ │ ├── json_document.py +│ │ └── text_records.py +│ └── 05-imports-modules-and-packages/ │ ├── README.md │ ├── README.pt-BR.md │ ├── README.es.md │ └── examples/ -│ ├── csv_records.py -│ ├── handle_invalid_json.py -│ ├── json_document.py -│ └── text_records.py +│ ├── grade_tools.py +│ ├── import_standard_library.py +│ ├── main_guard.py +│ ├── module_demo.py +│ ├── package_demo.py +│ └── study_tools/ +│ ├── __init__.py +│ └── formatting.py ├── exercises/ ├── external-libraries/ ├── functions/ @@ -425,7 +438,7 @@ python-study-guide/ - `comments-and-documentation/`: ruta completa de la Fase 6. Hay capítulos revisados sobre comentarios, docstrings, nombres significativos, marcadores de tareas, comentarios frente a logging y PEP 8 y legibilidad, cada uno en inglés, portugués de Brasil y español, con ejemplos ejecutables seguros. - `collections/`: ruta completa de la Fase 3. Sus seis capítulos enseñan creación, lectura, mutación y métodos comunes de listas, copia superficial, tuplas e inmutabilidad, mappings clave-valor y vistas de diccionarios, unicidad y relaciones de conjuntos y cómo elegir entre listas, tuplas, diccionarios y conjuntos según la intención, en inglés, portugués de Brasil y español, con ejemplos ejecutables seguros. - `docs/`: rutas completas de aprendizaje, roadmaps, arquitectura del proyecto, documentos localizados, políticas y guía de desarrollo responsable asistido por IA. -- `errors-files-and-modules/`: ruta de la Fase 7 en progreso. Los Capítulos 01–04 cubren manejo de excepciones en runtime, lanzamiento deliberado y excepciones personalizadas, I/O seguro de archivos de texto con `open()` y `with` y parsing, escritura, conversión y límites de validación para TXT/CSV/JSON, en inglés, portugués de Brasil y español con ejemplos ejecutables deterministas. +- `errors-files-and-modules/`: ruta completa de la Fase 7. Los Capítulos 01–05 cubren manejo de excepciones en runtime, lanzamiento deliberado y excepciones personalizadas, I/O seguro de archivos de texto con `open()` y `with`, parsing y escritura de TXT/CSV/JSON y organización del código mediante imports, módulos, paquetes regulares, contexto de ejecución y diseño de dependencias, en inglés, portugués de Brasil y español con ejemplos ejecutables deterministas. - `exercises/`: actividades prácticas relacionadas con los capítulos. - `external-libraries/`: futuras guías sobre paquetes de terceros. - `functions/`: ruta completa de la Fase 5. Los Capítulos 01–09 cubren definición y llamada de funciones, entradas obligatorias, valores retornados, alcance y búsqueda de nombres, type hints para interfaces de funciones, valores predeterminados incluida la evaluación al definir la función y la seguridad con valores mutables, recolección de argumentos posicionales y por palabra clave de cantidad variable con `*args` y `**kwargs`, composición mediante funciones auxiliares y coordinadoras con dependencias explícitas y grafos simples de llamadas, y seguimiento explícito del flujo de datos entre llamadas, incluidos vínculos de parámetros, reasignación frente a mutación, `None`, resultados en tupla y traspasos mediante `return`, en inglés, portugués de Brasil y español, con ejemplos ejecutables determinísticos. diff --git a/docs/project-structure.pt-BR.md b/docs/project-structure.pt-BR.md index 2c96e7f..6fada63 100644 --- a/docs/project-structure.pt-BR.md +++ b/docs/project-structure.pt-BR.md @@ -165,15 +165,28 @@ python-study-guide/ │ │ ├── append_text.py │ │ ├── handle_missing_file.py │ │ └── write_and_read_text.py -│ └── 04-txt-csv-and-json/ +│ ├── 04-txt-csv-and-json/ +│ │ ├── README.md +│ │ ├── README.pt-BR.md +│ │ ├── README.es.md +│ │ └── examples/ +│ │ ├── csv_records.py +│ │ ├── handle_invalid_json.py +│ │ ├── json_document.py +│ │ └── text_records.py +│ └── 05-imports-modules-and-packages/ │ ├── README.md │ ├── README.pt-BR.md │ ├── README.es.md │ └── examples/ -│ ├── csv_records.py -│ ├── handle_invalid_json.py -│ ├── json_document.py -│ └── text_records.py +│ ├── grade_tools.py +│ ├── import_standard_library.py +│ ├── main_guard.py +│ ├── module_demo.py +│ ├── package_demo.py +│ └── study_tools/ +│ ├── __init__.py +│ └── formatting.py ├── exercises/ ├── external-libraries/ ├── functions/ @@ -425,7 +438,7 @@ python-study-guide/ - `comments-and-documentation/`: trilha completa da Fase 6. Há capítulos revisados sobre comentários, docstrings, nomes significativos, marcadores de tarefas, comentários versus logging e PEP 8 e legibilidade, cada um em inglês, português brasileiro e espanhol, com exemplos executáveis seguros. - `collections/`: trilha completa da Fase 3. Seus seis capítulos ensinam criação, leitura, mutação e métodos comuns de listas, cópia rasa, tuplas e imutabilidade, mapeamentos chave-valor e views de dicionários, unicidade e relações de conjuntos e como escolher entre listas, tuplas, dicionários e conjuntos de acordo com a intenção, em inglês, português brasileiro e espanhol, com exemplos executáveis seguros. - `docs/`: trilhas completas de estudos, roadmaps, arquitetura do projeto, documentos localizados, políticas e guia de desenvolvimento responsável assistido por IA. -- `errors-files-and-modules/`: trilha da Fase 7 em andamento. Os Capítulos 01–04 cobrem tratamento de exceções em runtime, levantamento deliberado e exceções personalizadas, I/O seguro de arquivos de texto com `open()` e `with` e parsing, escrita, conversão e fronteiras de validação para TXT/CSV/JSON, em inglês, português brasileiro e espanhol com exemplos executáveis determinísticos. +- `errors-files-and-modules/`: trilha completa da Fase 7. Os Capítulos 01–05 cobrem tratamento de exceções em runtime, levantamento deliberado e exceções personalizadas, I/O seguro de arquivos de texto com `open()` e `with`, parsing e escrita de TXT/CSV/JSON e organização do código por imports, módulos, pacotes regulares, contexto de execução e design de dependências, em inglês, português brasileiro e espanhol com exemplos executáveis determinísticos. - `exercises/`: atividades práticas relacionadas aos capítulos. - `external-libraries/`: futuros guias sobre pacotes de terceiros. - `functions/`: trilha completa da Fase 5. Os Capítulos 01–09 cobrem definição e chamada de funções, entradas obrigatórias, valores retornados, escopo e busca de nomes, type hints para interfaces de funções, valores padrão incluindo avaliação no momento da definição e segurança com padrões mutáveis, coleta de argumentos posicionais e nomeados de quantidade variável com `*args` e `**kwargs`, composição por funções auxiliares e coordenadoras com dependências explícitas e grafos simples de chamadas e rastreamento explícito do fluxo de dados entre chamadas, incluindo vínculos de parâmetros, reatribuição versus mutação, `None`, resultados em tupla e passagens por `return`, em inglês, português brasileiro e espanhol com exemplos executáveis determinísticos. diff --git a/docs/roadmap.en.md b/docs/roadmap.en.md index e57c7cf..b46be99 100644 --- a/docs/roadmap.en.md +++ b/docs/roadmap.en.md @@ -21,12 +21,12 @@ This roadmap tracks both the educational curriculum and the repository foundatio | 4. Program flow | Complete | Eight reviewed chapters cover conditions, branching, structural pattern matching, `for`, iteration helpers, `while`, loop control, and choosing and combining flow tools by intent | | 5. Functions | Complete | Nine reviewed chapters cover `def`, calls, required inputs, returned values, scope, type hints, safe defaults, flexible arguments, function composition, and explicit data flow | | 6. Comments, documentation, and clean code | Complete | Six reviewed chapters are available and the pilot educational section is officially complete | -| 7. Errors, files, and modules | In progress | Chapters 01–04 cover exception handling, deliberate exception signaling, safe file I/O, and TXT/CSV/JSON data formats | +| 7. Errors, files, and modules | Complete | Five reviewed chapters cover exception handling, deliberate exception signaling, safe file I/O, TXT/CSV/JSON data formats, and imports/modules/packages | | 8. Standard library | Planned | Curriculum not started | | 9. External libraries | Planned | Curriculum not started | | 10. Practical projects | Planned | Curriculum not started | -Phases 0, 1, 2, 3, 4, 5, and 6 are complete. Phase 7 is in progress with exception handling, deliberate exception signaling, safe file I/O, and TXT/CSV/JSON data-format boundaries now available. The final planned Phase 7 chapter is **Imports, modules, and packages**. Phase 6 continues to provide the editorial and quality model for later sections. +Phases 0, 1, 2, 3, 4, 5, 6, and 7 are complete. Phase 7 now connects exception handling, deliberate exception signaling, safe file I/O, TXT/CSV/JSON data boundaries, and code organization through imports, modules, and packages. Phase 8: Standard Library is the next planned learning phase. Phase 6 continues to provide the editorial and quality model for later sections. ## Phase 0: Project foundation @@ -132,9 +132,9 @@ See the [section learning path](../errors-files-and-modules/README.md). - [x] [`raise` and custom exceptions](../errors-files-and-modules/02-raise-and-custom-exceptions/README.md) - [x] [`open()` and `with`](../errors-files-and-modules/03-open-and-with/README.md) - [x] [TXT, CSV, and JSON](../errors-files-and-modules/04-txt-csv-and-json/README.md) -- [ ] Imports, modules, and packages +- [x] [Imports, modules, and packages](../errors-files-and-modules/05-imports-modules-and-packages/README.md) -Phase 7 is in progress. Chapters 01–02 establish exception handling and deliberate signaling. Chapter 03 adds safe text-file I/O and resource lifetime. Chapter 04 adds TXT contracts, CSV and JSON parsing/writing, explicit type conversion, and parsing-versus-validation boundaries. The next planned chapter is **Imports, modules, and packages**. +Phase 7 is complete. Chapters 01–02 establish exception handling and deliberate signaling. Chapter 03 adds safe text-file I/O and resource lifetime. Chapter 04 adds TXT, CSV, and JSON parsing/writing with explicit data boundaries. Chapter 05 closes the phase with modules, regular packages, import namespaces and caching, `__name__`, the main guard, search context, absolute and relative imports, `python -m`, and dependency design. ## Phase 8: Standard library diff --git a/docs/roadmap.es.md b/docs/roadmap.es.md index 71f84f1..7d2e4de 100644 --- a/docs/roadmap.es.md +++ b/docs/roadmap.es.md @@ -21,12 +21,12 @@ Este roadmap acompaña tanto la ruta educativa como la base del repositorio que | 4. Flujo del programa | Completada | Ocho capítulos revisados cubren condiciones, ramificaciones, coincidencia de patrones estructurales, `for`, ayudas de iteración, `while`, control de bucles y elección y combinación de herramientas de flujo según la intención | | 5. Funciones | Completada | Nueve capítulos revisados cubren `def`, llamadas, entradas obligatorias, valores retornados, alcance, type hints, valores predeterminados seguros, argumentos flexibles, composición de funciones y flujo explícito de datos | | 6. Comentarios, documentación y código limpio | Completada | Seis capítulos revisados están disponibles y la sección educativa piloto está oficialmente completada | -| 7. Errores, archivos y módulos | En progreso | Los Capítulos 01–04 cubren manejo de excepciones, señalización deliberada, I/O seguro de archivos y formatos TXT/CSV/JSON | +| 7. Errores, archivos y módulos | Completada | Cinco capítulos revisados cubren manejo de excepciones, señalización deliberada, I/O seguro de archivos, formatos TXT/CSV/JSON e imports/módulos/paquetes | | 8. Biblioteca estándar | Planificada | Contenido todavía no iniciado | | 9. Bibliotecas externas | Planificada | Contenido todavía no iniciado | | 10. Proyectos prácticos | Planificada | Contenido todavía no iniciado | -Las Fases 0, 1, 2, 3, 4, 5 y 6 están completadas. La Fase 7 está en progreso con manejo de excepciones, señalización deliberada, I/O seguro de archivos y límites de formatos TXT/CSV/JSON ya disponibles. El último capítulo planificado de la Fase 7 es **Imports, módulos y paquetes**. La Fase 6 continúa proporcionando el modelo editorial y de calidad para las secciones posteriores. +Las Fases 0, 1, 2, 3, 4, 5, 6 y 7 están completadas. La Fase 7 ahora conecta manejo de excepciones, señalización deliberada, I/O seguro de archivos, límites de datos TXT/CSV/JSON y organización del código mediante imports, módulos y paquetes. La Fase 8: Biblioteca Estándar es la siguiente fase de aprendizaje planificada. La Fase 6 continúa proporcionando el modelo editorial y de calidad para las secciones posteriores. ## Fase 0: Base del proyecto @@ -132,9 +132,9 @@ Consulta la [ruta de aprendizaje de la sección](../errors-files-and-modules/REA - [x] [`raise` y excepciones personalizadas](../errors-files-and-modules/02-raise-and-custom-exceptions/README.es.md) - [x] [`open()` y `with`](../errors-files-and-modules/03-open-and-with/README.es.md) - [x] [TXT, CSV y JSON](../errors-files-and-modules/04-txt-csv-and-json/README.es.md) -- [ ] Imports, módulos y paquetes +- [x] [Imports, módulos y paquetes](../errors-files-and-modules/05-imports-modules-and-packages/README.es.md) -La Fase 7 está en progreso. Los Capítulos 01–02 establecen manejo y señalización deliberada de excepciones. El Capítulo 03 añade I/O seguro de archivos y gestión de recursos. El Capítulo 04 añade contratos TXT, parsing y escritura de CSV y JSON, conversión explícita de tipos y límites entre parsing y validación. El próximo capítulo planificado es **Imports, módulos y paquetes**. +La Fase 7 está completada. Los Capítulos 01–02 establecen manejo y señalización deliberada de excepciones. El Capítulo 03 añade I/O seguro de archivos y gestión de recursos. El Capítulo 04 añade parsing y escritura de TXT, CSV y JSON con límites explícitos de datos. El Capítulo 05 cierra la fase con módulos, paquetes regulares, namespaces y caché de imports, `__name__`, main guard, contexto de búsqueda, imports absolutos y relativos, `python -m` y diseño de dependencias. ## Fase 8: Biblioteca estándar diff --git a/docs/roadmap.pt-BR.md b/docs/roadmap.pt-BR.md index 65ab30e..aad8d3a 100644 --- a/docs/roadmap.pt-BR.md +++ b/docs/roadmap.pt-BR.md @@ -21,12 +21,12 @@ Este roadmap acompanha tanto a trilha educacional quanto a fundação do reposit | 4. Fluxo do programa | Concluída | Oito capítulos revisados cobrem condições, ramificações, correspondência de padrões estruturais, `for`, auxiliares de iteração, `while`, controle de loops e escolha e combinação das ferramentas de fluxo pela intenção | | 5. Funções | Concluída | Nove capítulos revisados cobrem `def`, chamadas, entradas obrigatórias, valores retornados, escopo, type hints, valores padrão seguros, argumentos flexíveis, composição de funções e fluxo explícito de dados | | 6. Comentários, documentação e código limpo | Concluída | Seis capítulos revisados estão disponíveis e a seção educacional-piloto está oficialmente concluída | -| 7. Erros, arquivos e módulos | Em andamento | Os Capítulos 01–04 cobrem tratamento de exceções, sinalização deliberada, I/O seguro de arquivos e formatos TXT/CSV/JSON | +| 7. Erros, arquivos e módulos | Concluída | Cinco capítulos revisados cobrem tratamento de exceções, sinalização deliberada, I/O seguro de arquivos, formatos TXT/CSV/JSON e imports/módulos/pacotes | | 8. Biblioteca padrão | Planejada | Conteúdo ainda não iniciado | | 9. Bibliotecas externas | Planejada | Conteúdo ainda não iniciado | | 10. Projetos práticos | Planejada | Conteúdo ainda não iniciado | -As Fases 0, 1, 2, 3, 4, 5 e 6 estão concluídas. A Fase 7 está em andamento com tratamento de exceções, sinalização deliberada, I/O seguro de arquivos e fronteiras de formatos TXT/CSV/JSON já disponíveis. O último capítulo planejado da Fase 7 é **Imports, módulos e pacotes**. A Fase 6 continua fornecendo o modelo editorial e de qualidade para as seções posteriores. +As Fases 0, 1, 2, 3, 4, 5, 6 e 7 estão concluídas. A Fase 7 agora conecta tratamento de exceções, sinalização deliberada, I/O seguro de arquivos, fronteiras de dados TXT/CSV/JSON e organização do código por imports, módulos e pacotes. A Fase 8: Biblioteca Padrão é a próxima fase de aprendizagem planejada. A Fase 6 continua fornecendo o modelo editorial e de qualidade para as seções posteriores. ## Fase 0: Fundação do projeto @@ -132,9 +132,9 @@ Consulte a [trilha de aprendizagem da seção](../errors-files-and-modules/READM - [x] [`raise` e exceções personalizadas](../errors-files-and-modules/02-raise-and-custom-exceptions/README.pt-BR.md) - [x] [`open()` e `with`](../errors-files-and-modules/03-open-and-with/README.pt-BR.md) - [x] [TXT, CSV e JSON](../errors-files-and-modules/04-txt-csv-and-json/README.pt-BR.md) -- [ ] Imports, módulos e pacotes +- [x] [Imports, módulos e pacotes](../errors-files-and-modules/05-imports-modules-and-packages/README.pt-BR.md) -A Fase 7 está em andamento. Os Capítulos 01–02 estabelecem tratamento e sinalização deliberada de exceções. O Capítulo 03 acrescenta I/O seguro de arquivos e gerenciamento de recursos. O Capítulo 04 acrescenta contratos TXT, parsing e escrita de CSV e JSON, conversão explícita de tipos e fronteiras entre parsing e validação. O próximo capítulo planejado é **Imports, módulos e pacotes**. +A Fase 7 está concluída. Os Capítulos 01–02 estabelecem tratamento e sinalização deliberada de exceções. O Capítulo 03 acrescenta I/O seguro de arquivos e gerenciamento de recursos. O Capítulo 04 acrescenta parsing e escrita de TXT, CSV e JSON com fronteiras explícitas de dados. O Capítulo 05 encerra a fase com módulos, pacotes regulares, namespaces e cache de imports, `__name__`, main guard, contexto de busca, imports absolutos e relativos, `python -m` e design de dependências. ## Fase 8: Biblioteca padrão diff --git a/errors-files-and-modules/05-imports-modules-and-packages/README.es.md b/errors-files-and-modules/05-imports-modules-and-packages/README.es.md new file mode 100644 index 0000000..acbbfd9 --- /dev/null +++ b/errors-files-and-modules/05-imports-modules-and-packages/README.es.md @@ -0,0 +1,1034 @@ +
+ +# Organizar Código con Imports, Módulos y Paquetes + +[🇺🇸 English](README.md) · [🇧🇷 Português](README.pt-BR.md) · [🇪🇸 Español](README.es.md) + +
+ +[← Volver a Errores, Archivos y Módulos](../README.es.md) · [← Anterior: Trabajar con TXT, CSV y JSON](../04-txt-csv-and-json/README.es.md) + +A medida que los programas crecen, mantener cada función, constante, parser y flujo de trabajo en un único archivo se vuelve más difícil de comprender y mantener. El sistema de importación de Python permite dividir el código en **módulos** y organizar módulos relacionados en **paquetes**. + +El objetivo de este capítulo no es memorizar cada detalle del mecanismo de importación de Python. Es construir un modelo mental confiable para programas pequeños y medianos: de dónde vienen los nombres importados, qué código se ejecuta durante un import, cómo los paquetes organizan módulos, por qué importa el contexto de ejecución y qué hábitos mantienen comprensibles las dependencias. + +**Tiempo estimado de estudio:** 120–160 minutos. + +**Requisito de Python:** Python 3.10 o posterior. El comportamiento de importación enseñado aquí fue verificado con el tutorial, la referencia del lenguaje y la documentación de línea de comandos oficiales de Python 3.14. + +## Objetivos de aprendizaje + +Al final de este capítulo, deberías poder: + +- explicar qué es un módulo de Python en proyectos comunes de código fuente; +- distinguir un objeto módulo de los nombres importados en otro módulo; +- usar `import module`, `from module import name` y `as` de forma deliberada; +- explicar por qué el acceso calificado por módulo suele mejorar la claridad; +- describir qué ocurre con el código de nivel superior cuando se importa un módulo; +- explicar el papel introductorio de `sys.modules` en el caché de imports; +- usar `if __name__ == "__main__":` para separar definiciones importables de la ejecución directa; +- describir el propósito de `sys.path` sin tratarlo como una lista que deba parchearse casualmente; +- distinguir `ModuleNotFoundError` de la familia más amplia de `ImportError`; +- explicar qué es un paquete regular y qué hace `__init__.py`; +- usar nombres punteados de paquetes e imports absolutos básicos; +- reconocer imports relativos y explicar por qué importa el contexto de ejecución; +- usar `python -m` cuando un módulo debe ejecutarse dentro de su contexto de paquete/import; +- distinguir un paquete de importación de una distribución instalable; +- evitar imports con comodín, colisiones accidentales de nombres de módulos, efectos secundarios en el import y diseños simples con imports circulares; +- organizar un pequeño programa Python de varios archivos con dependencias explícitas. + +## 1. ¿Por qué dividir el código entre archivos? + +Un único archivo es útil mientras el programa es pequeño. A medida que se acumulan responsabilidades, ese archivo puede convertirse en una sala llena donde ideas no relacionadas compiten por atención. + +Los módulos crean límites: + +```text +manejo de entrada + ↓ +validación + ↓ +cálculo + ↓ +formateo +``` + +Cada responsabilidad puede vivir en un archivo cuyo nombre comunica su propósito. + +Dividir código no es automáticamente mejor. Una función auxiliar de tres líneas no necesita su propio módulo solo porque Python admita módulos. Crea un límite cuando mejore la reutilización, navegación, pruebas, propiedad de una responsabilidad o claridad de las dependencias. + +## 2. En código fuente Python común, un archivo `.py` puede ser un módulo + +El tutorial de Python presenta un módulo como un archivo que contiene definiciones e instrucciones de Python. + +Por ejemplo: + +```text +study_tools.py +``` + +puede contener: + +```python +def build_label(topic: str, level: int) -> str: + return f"{topic} | level {level}" +``` + +y otro archivo puede importar ese módulo. + +Este modelo basado en archivos es el punto de partida adecuado para principiantes. El sistema completo de importación de Python también puede cargar módulos implementados de otras formas, incluidos módulos incorporados y de extensión, por lo que en el modelo completo del lenguaje "módulo" es más amplio que "un archivo `.py`". + +## 3. `import module` vincula el nombre del módulo + +Supongamos que `grade_tools.py` contiene: + +```python +def classify_score(score: int) -> str: + if score >= 80: + return "ready" + return "review" +``` + +Otro archivo puede importarlo: + +```python +import grade_tools + +status = grade_tools.classify_score(84) +print(status) +``` + +El nombre `grade_tools` ahora se refiere al objeto módulo importado dentro del namespace del módulo importador. + +## 4. El acceso calificado por módulo hace visible el origen de un nombre + +Con: + +```python +import grade_tools +``` + +llamas: + +```python +grade_tools.classify_score(84) +``` + +Ese prefijo adicional aporta información útil. Quien lee puede ver inmediatamente que `classify_score` proviene de otro módulo. + +Esta es una razón por la que `import module` suele ser un buen valor predeterminado cuando el nombre del módulo es corto y significativo. + +## 5. `from module import name` vincula directamente nombres seleccionados + +Python también permite: + +```python +from grade_tools import classify_score + +status = classify_score(84) +``` + +Aquí `classify_score` queda vinculado directamente en el namespace del módulo importador. El nombre `grade_tools` no queda vinculado automáticamente por esta instrucción. + +El módulo de origen aún debe encontrarse y cargarse. `from ... import ...` cambia qué nombres se vinculan en el importador; no evita el sistema de importación. + +## 6. `as` crea un alias local deliberado + +Un módulo puede importarse con otro nombre local: + +```python +import statistics as stats + +mean_score = stats.mean([80, 90, 100]) +``` + +Un nombre seleccionado también puede recibir un alias: + +```python +from math import sqrt as square_root + +print(square_root(81)) +``` + +Usa aliases cuando sean convencionales o realmente mejoren la legibilidad. Evita aliases crípticos que hagan el código más difícil de buscar y comprender. + +## 7. Elige el estilo de import por legibilidad, no por escribir menos + +Compara: + +```python +import decimal + +value = decimal.Decimal("0.1") +``` + +con: + +```python +from decimal import Decimal + +value = Decimal("0.1") +``` + +Ambos pueden ser apropiados. + +Preguntas útiles: + +- ¿El nombre del módulo aporta contexto importante? +- ¿Se usarán varios nombres del mismo módulo? +- ¿Un nombre importado directamente podría colisionar con otro nombre local? +- ¿La forma más corta ya es una convención fuerte en ese ecosistema? + +La línea más corta no siempre representa la dependencia más clara. + +## 8. Los imports son instrucciones ejecutables + +Un import no es una operación de copiar texto. Python localiza y carga un módulo, crea u obtiene un objeto módulo y ejecuta el código de nivel superior cuando se requiere inicialización. + +Considera un módulo que contiene: + +```python +print("Loading helpers") + + +def build_message() -> str: + return "Ready" +``` + +Importar ese módulo puede imprimir `Loading helpers` durante la inicialización. + +Por eso el trabajo ejecutable en el nivel superior debe ser intencional. + +## 9. Las definiciones del módulo se crean ejecutando su código + +Una definición de función también es una instrucción. Cuando se inicializa un módulo, Python ejecuta instrucciones que vinculan nombres como funciones, clases y constantes en el namespace de ese módulo. + +Un flujo simplificado útil es: + +```text +localizar módulo + ↓ +crear/obtener objeto módulo + ↓ +ejecutar código de inicialización si hace falta + ↓ +el namespace del módulo contiene sus definiciones +``` + +Este modelo mental explica por qué errores de sintaxis, dependencias ausentes y excepciones de nivel superior pueden hacer fallar un import. + +## 10. Los imports normales reutilizan módulos mediante `sys.modules` + +Durante una sesión normal del intérprete, los módulos importados se almacenan en caché en `sys.modules`. + +Eso significa que instrucciones repetidas como: + +```python +import math +import math +``` + +normalmente no vuelven a ejecutar desde cero la inicialización del módulo cada vez. + +Este es un modelo introductorio útil, no una regla que diga que el código de un módulo nunca puede volver a ejecutarse. Operaciones avanzadas como recarga explícita o cambios manuales del estado de importación pueden alterar ese comportamiento. + +## 11. Evita usar efectos secundarios de import como flujo oculto de la aplicación + +Esto es frágil: + +```python +# settings.py +print("Connecting to something...") +``` + +porque cualquier código que importe `settings` ahora dispara ese trabajo. + +Prefiere definiciones en el nivel del módulo y ejecución explícita mediante funciones: + +```python +def initialize_settings() -> None: + print("Settings initialized") +``` + +Así el llamador decide cuándo esa acción pertenece al flujo del programa. + +Algunos módulos realizan legítimamente una pequeña inicialización durante el import. La advertencia de diseño se refiere a trabajo sorprendente, costoso, irreversible o dependiente del orden. + +## 12. Todo módulo tiene un `__name__` + +Un módulo puede inspeccionar su propio valor global `__name__`. + +Cuando un módulo se importa normalmente, `__name__` refleja su nombre de importación. + +Por ejemplo, dentro de `grade_tools.py` importado como `grade_tools`, el valor normalmente es: + +```text +grade_tools +``` + +Cuando el código se ejecuta como programa de nivel superior, Python da a ese entorno de ejecución el nombre: + +```text +__main__ +``` + +## 13. El main guard separa definiciones de la ejecución directa + +Un patrón común es: + +```python +def main() -> None: + print("Program started") + + +if __name__ == "__main__": + main() +``` + +Si el archivo se ejecuta como programa principal, `main()` se ejecuta. + +Si el archivo se importa, la función se define, pero la llamada protegida no se ejecuta. + +## 14. Coloca el trabajo reutilizable en funciones antes del main guard + +Prefiere: + +```python +def build_report() -> str: + return "Study report" + + +def main() -> None: + print(build_report()) + + +if __name__ == "__main__": + main() +``` + +a colocar toda la aplicación directamente dentro del guard. + +Las funciones siguen siendo reutilizables y fáciles de probar, mientras el guard responde solo una pregunta: ¿debe comenzar ahora el comportamiento de entrada directa? + +## 15. `__name__ == "__main__"` no bloquea el import + +El guard no impide que el archivo sea importado. + +Solo evita que el bloque protegido se ejecute cuando el módulo se importa con otro nombre. + +Las definiciones anteriores al guard todavía se ejecutan como instrucciones del módulo y quedan disponibles en su namespace. + +## 16. Python necesita ubicaciones de búsqueda para encontrar módulos + +Cuando escribes: + +```python +import study_tools +``` + +Python debe determinar a qué se refiere `study_tools`. + +El sistema completo de importación admite varios tipos de finders y loaders. A nivel introductorio, la idea importante es que Python busca ubicaciones de importación según su mecanismo de import y el entorno de ejecución. + +Esas ubicaciones de búsqueda se reflejan en `sys.path` para imports comunes basados en rutas. + +## 17. `sys.path` es una lista de ubicaciones de búsqueda de módulos + +Puedes inspeccionarla: + +```python +import sys + +for location in sys.path: + print(location) +``` + +Su contenido exacto depende de cómo se inició Python, del entorno, de la configuración de la instalación y de otros ajustes. + +No memorices un orden universal de `sys.path` a partir de una captura de pantalla. Aprende el concepto: indica al mecanismo de importación basado en rutas dónde pueden encontrarse módulos y paquetes. + +## 18. No trates `sys.path.append(...)` como la solución normal para la estructura del proyecto + +Esto puede parecer una solución rápida a un import: + +```python +import sys + +sys.path.append("../somewhere") +``` + +pero hace que los imports dependan de una cirugía de rutas en runtime y a menudo oculta una estructura de proyecto o un comando de ejecución poco claros. + +Prefiere una estructura coherente de paquetes, un entorno de trabajo/instalación adecuado y una forma de ejecución que proporcione a Python el contexto de import esperado. + +Existen casos avanzados para personalizar rutas de importación, pero modificar `sys.path` casualmente no debería ser la primera herramienta de diseño. + +## 19. Los nombres de módulos pueden colisionar con otros módulos + +Imagina crear un archivo de estudio llamado: + +```text +json.py +``` + +y luego escribir: + +```python +import json +``` + +Según el contexto de búsqueda, tu archivo local puede ocultar el módulo de la biblioteca estándar que querías importar. + +Evita poner a tus archivos nombres de módulos de la biblioteca estándar o de dependencias importantes utilizadas por el mismo proyecto. + +## 20. `ModuleNotFoundError` normalmente significa que el módulo solicitado no se encontró + +Por ejemplo: + +```python +import module_that_does_not_exist +``` + +normalmente lanza `ModuleNotFoundError`. + +`ModuleNotFoundError` es una subclase de `ImportError`. + +El mensaje y el nombre exacto que falló importan porque un import puede encontrar tu primer módulo y aun así fallar al importar una dependencia de ese módulo. + +## 21. `ImportError` es la excepción más amplia relacionada con imports + +Un módulo puede existir mientras un nombre solicitado no existe: + +```python +from math import name_that_does_not_exist +``` + +Esto lanza `ImportError` porque `math` está disponible, pero el nombre importado solicitado no lo está. + +No captures `ImportError` alrededor de un bloque grande solo para hacer desaparecer los fallos. Captura excepciones de importación únicamente cuando el programa tenga una política deliberada, como una dependencia realmente opcional con un fallback documentado. + +## 22. Un paquete organiza módulos bajo un namespace punteado + +Los paquetes permiten que módulos relacionados usen nombres jerárquicos como: + +```text +study_tools.formatting +study_tools.validation +study_tools.reports +``` + +Un paquete puede contener módulos y subpaquetes. + +En el modelo completo de importación de Python, un paquete es un tipo especial de módulo que puede contener submódulos. La analogía con directorios es útil para proyectos comunes de código fuente, pero el modelo del lenguaje se basa en objetos módulo/paquete, no solo en carpetas. + +## 23. Un paquete regular suele usar `__init__.py` + +Un paquete regular simple puede verse así: + +```text +study_tools/ +├── __init__.py +├── formatting.py +└── validation.py +``` + +La presencia de `__init__.py` hace que este directorio sea un paquete regular en el diseño convencional basado en sistema de archivos. + +`__init__.py` puede estar vacío. También puede definir comportamiento de inicialización o exponer deliberadamente nombres seleccionados a nivel del paquete. + +## 24. Los namespace packages son una excepción avanzada a la regla de `__init__.py` + +Python moderno también admite **namespace packages**, que pueden existir sin `__init__.py` y abarcar varias ubicaciones. + +Por eso esta afirmación es demasiado amplia: + +```text +"Todo paquete Python debe tener __init__.py." +``` + +Para proyectos de principiantes, los paquetes regulares con `__init__.py` suelen ser el punto de partida más claro. Los namespace packages pueden esperar hasta que un proyecto realmente necesite ese modelo. + +## 25. `__init__.py` es código, así que mantén deliberado su comportamiento + +Esto es válido: + +```python +from .formatting import build_label + +__all__ = ["build_label"] +``` + +Ahora el paquete puede proporcionar intencionalmente un nombre público conveniente: + +```python +from study_tools import build_label +``` + +Pero un `__init__.py` grande, lleno de configuración costosa e imports sorprendentes, puede volver más difícil de entender el comportamiento del paquete. + +Trata la inicialización del paquete como parte de tu diseño de dependencias. + +## 26. Los nombres punteados expresan la jerarquía del paquete + +Este import: + +```python +import study_tools.formatting +``` + +carga el submódulo usando su nombre punteado completo. + +Luego accedes mediante: + +```python +study_tools.formatting.build_label("Modules", 2) +``` + +Otro estilo es: + +```python +from study_tools import formatting + +print(formatting.build_label("Modules", 2)) +``` + +Ambos dejan explícita la relación con el paquete. + +## 27. Importa la interfaz estable más estrecha que mantenga clara la intención + +Supongamos que un paquete expone intencionalmente `build_label` desde `__init__.py`: + +```python +from study_tools import build_label +``` + +Eso puede ser una API de paquete limpia. + +Si el paquete no promete ese atajo público, importar el módulo que define el nombre puede ser más honesto: + +```python +from study_tools.formatting import build_label +``` + +La mejor elección depende de la interfaz documentada por el paquete, no de cuántos caracteres ahorra el import. + +## 28. Un paquete de importación no es lo mismo que una distribución + +La palabra **paquete** está sobrecargada en conversaciones sobre Python. + +Un **paquete de importación** forma parte del namespace de módulos de Python, por ejemplo: + +```text +study_tools +``` + +Una **distribución** es algo instalado y gestionado por herramientas de empaquetado y puede proporcionar uno o más paquetes de importación o módulos. + +El nombre de instalación y el nombre de importación incluso pueden ser diferentes. + +Este capítulo enseña paquetes de importación. Empaquetar y publicar distribuciones son temas separados. + +## 29. Los imports absolutos nombran explícitamente la ruta del paquete + +Dentro de un paquete del proyecto, un import absoluto puede verse así: + +```python +from study_tools.formatting import build_label +``` + +Nombra el paquete desde el namespace de importación de nivel superior. + +Los imports absolutos suelen ser fáciles de buscar y comprender porque la ruta de la dependencia queda explícita. + +## 30. Los imports relativos usan puntos iniciales dentro de paquetes + +Un módulo dentro de `study_tools` puede importar un módulo hermano con: + +```python +from .formatting import build_label +``` + +Un punto inicial se refiere al paquete actual. Puntos adicionales pueden referirse a niveles de paquetes padres. + +Los imports relativos son útiles para relaciones internas de un paquete, pero dependen de que Python conozca el contexto de paquete del módulo. + +## 31. Los imports relativos no se basan en el directorio de trabajo actual + +Esta distinción es importante. + +Un import relativo como: + +```python +from .formatting import build_label +``` + +se resuelve a partir de la información de paquete del módulo actual, no caminando desde cualquier directorio en el que esté el terminal. + +Por eso "estoy en la carpeta correcta" no es una explicación completa de si un import relativo funcionará. + +## 32. Ejecutar directamente un módulo de paquete puede eliminar el contexto de paquete que espera + +Supongamos que un módulo contiene un import relativo y está pensado para vivir dentro de un paquete. + +Ejecutarlo por la ruta del archivo: + +```text +python study_tools/cli.py +``` + +puede ejecutarlo como el módulo de nivel superior `__main__` en lugar de como `study_tools.cli`. Entonces un import relativo puede fallar porque no se conoce el paquete padre esperado. + +Cuando el módulo está diseñado para ejecutarse en contexto de paquete, `python -m` suele ser la herramienta correcta. + +## 33. `python -m` localiza un módulo mediante el sistema de importación y lo ejecuta + +Por ejemplo: + +```text +python -m study_tools.cli +``` + +Python localiza `study_tools.cli` mediante el mecanismo de importación estándar y ejecuta su contenido como el módulo `__main__`. + +Esto preserva el hecho de que el código pertenece al paquete `study_tools` mientras lo convierte en el punto de entrada del programa. + +El comando usa un **nombre de módulo**, no un nombre de archivo `.py`. + +## 34. Un paquete puede definir `__main__.py` para `python -m package_name` + +Si un paquete contiene: + +```text +study_tools/ +├── __init__.py +├── __main__.py +└── formatting.py +``` + +entonces: + +```text +python -m study_tools +``` + +ejecuta `study_tools.__main__` como el módulo principal. + +Esto resulta útil cuando el propio paquete tiene un comportamiento de entrada por línea de comandos. Un paquete no adquiere ese comportamiento solo porque exista `__init__.py`. + +## 35. Los imports hacen visibles las dependencias + +Si `reports.py` importa `formatting.py`, entonces `reports` depende de `formatting`. + +Un esquema útil de dependencias es: + +```text +cli + ↓ +reports + ↓ +formatting +``` + +Mantener comprensible la dirección de las dependencias ayuda a evitar módulos enredados donde todo importa todo lo demás. + +## 36. Los imports circulares suelen ser una señal de diseño + +Una relación circular simple se ve así: + +```text +module_a importa module_b + ↑ ↓ + └─────────┘ +``` + +Python puede encontrar un módulo mientras todavía está solo parcialmente inicializado, produciendo errores de nombres ausentes o comportamientos confusos. + +Soluciones comunes de diseño incluyen: + +- mover definiciones compartidas a un tercer módulo; +- pasar valores o callables como parámetros en vez de volver a importar hacia arriba; +- aclarar qué módulo es propietario de una responsabilidad; +- reducir trabajo de nivel superior que dependa de que el otro módulo esté completamente inicializado. + +Mover un import dentro de una función a veces puede romper un ciclo, pero también puede limitarse a ocultar el problema arquitectónico. Comprende la dependencia antes de aplicar esa solución. + +## 37. Los imports dentro de funciones están permitidos, pero los imports de nivel superior son el valor predeterminado legible habitual + +Esto es Python válido: + +```python +def calculate_root(value: float) -> float: + import math + + return math.sqrt(value) +``` + +La mayoría de las dependencias comunes se ven con mayor facilidad cuando los imports aparecen cerca de la parte superior del módulo. + +Los imports locales pueden ser deliberados para dependencias opcionales, carga retrasada o ciclos bien comprendidos. Úsalos por una razón, no por reflejo. + +## 38. Evita imports con comodín en módulos comunes + +Esta sintaxis existe: + +```python +from math import * +``` + +pero hace menos explícito el namespace local. Quien lee debe saber qué nombres exporta el origen, y nuevos nombres exportados pueden crear colisiones. + +Prefiere imports explícitos: + +```python +from math import pi, sqrt +``` + +`__all__` puede influir en lo que expone un import con comodín, pero no convierte los wildcard imports en el valor predeterminado más claro para código de aplicación. + +## 39. Agrupa imports para mejorar la legibilidad + +Una organización común y legible es: + +```python +import csv +import json + +from study_tools import build_label +``` + +La convención de PEP 8 separa imports de la biblioteca estándar, de terceros y locales de la aplicación cuando existen esos grupos. + +El objetivo más profundo es la visibilidad: quien lee debería poder comprender las principales dependencias de un módulo sin buscar entre código no relacionado. + +## 40. Ejemplo práctico: importar la biblioteca estándar + +```python +import math + + +number = 81 +root = math.sqrt(number) + +print(f"Square root: {root}") +``` + +Salida: + +```text +Square root: 9.0 +``` + +Versión ejecutable: [`examples/import_standard_library.py`](examples/import_standard_library.py). + +## 41. Ejemplo práctico: importar tu propio módulo + +Módulo auxiliar `grade_tools.py`: + +```python +def classify_score(score: int) -> str: + if score >= 80: + return "ready" + return "review" +``` + +Módulo ejecutable `module_demo.py`: + +```python +import grade_tools + + +score = 84 +status = grade_tools.classify_score(score) + +print(f"Score {score}: {status}") +``` + +Salida: + +```text +Score 84: ready +``` + +Versión ejecutable: [`examples/module_demo.py`](examples/module_demo.py). Módulo de apoyo: [`examples/grade_tools.py`](examples/grade_tools.py). + +## 42. Ejemplo práctico: importar desde un paquete regular + +Estructura del paquete: + +```text +examples/ +├── package_demo.py +└── study_tools/ + ├── __init__.py + └── formatting.py +``` + +`formatting.py` define la función reutilizable: + +```python +def build_label(topic: str, level: int) -> str: + return f"{topic} | level {level}" +``` + +`__init__.py` la expone intencionalmente a nivel del paquete: + +```python +from .formatting import build_label + +__all__ = ["build_label"] +``` + +El archivo ejecutable importa la API del paquete: + +```python +from study_tools import build_label + + +print(build_label("Modules", 2)) +``` + +Salida: + +```text +Modules | level 2 +``` + +Versión ejecutable: [`examples/package_demo.py`](examples/package_demo.py). Paquete de apoyo: [`examples/study_tools/`](examples/study_tools/). + +## 43. Ejemplo práctico: main guard + +```python +def main() -> None: + print("Main guard executed") + + +if __name__ == "__main__": + main() +``` + +Salida cuando se ejecuta directamente: + +```text +Main guard executed +``` + +Versión ejecutable: [`examples/main_guard.py`](examples/main_guard.py). + +## 44. Error común: nombrar un archivo igual que una dependencia + +Archivos como estos pueden crear sombreados confusos: + +```text +json.py +csv.py +math.py +random.py +``` + +si el mismo proyecto también espera los módulos de la biblioteca estándar con esos nombres. + +Elige nombres de módulos que representen tu propia responsabilidad y no colisionen con dependencias que importas. + +## 45. Error común: ocultar el inicio de la aplicación dentro de un import + +Evita convertir esto en la arquitectura de la aplicación: + +```text +import app + ↓ +app lee archivos, conecta servicios e inicia bucles inmediatamente +``` + +Prefiere un punto de entrada explícito: + +```text +importar definiciones + ↓ +main() inicia deliberadamente el comportamiento de la aplicación +``` + +Un inicio explícito es más fácil de probar, reutilizar y comprender. + +## 46. Error común: asumir que ejecutar un archivo y ejecutar un módulo son idénticos + +Estos comandos pueden crear contextos de import distintos: + +```text +python path/to/tool.py +python -m package.tool +``` + +Ambos ejecutan código Python, pero `-m` localiza un módulo nombrado mediante el sistema de importación y lo ejecuta como `__main__`. + +La diferencia importa especialmente para paquetes e imports relativos. + +## 47. Error común: usar paquetes solo para crear árboles profundos de carpetas + +Esto no es automáticamente un buen diseño: + +```text +app/core/services/helpers/utils/common/ +``` + +Una jerarquía de paquetes debería comunicar namespaces y responsabilidades significativas. + +Más niveles añaden más rutas de importación, navegación y límites que comprender. Crea niveles que justifiquen su complejidad. + +## 48. Un proyecto pequeño puede crecer por etapas + +Comienza simple: + +```text +app.py +``` + +Después extrae una responsabilidad realmente reutilizable: + +```text +app.py +grade_tools.py +``` + +Luego agrupa módulos relacionados cuando el namespace sea útil: + +```text +app.py +study_tools/ +├── __init__.py +├── grades.py +└── formatting.py +``` + +La estructura debe seguir las responsabilidades, no el deseo de parecer "enterprise" antes de que el programa lo necesite. + +## 49. Ejercicio + +Crea una pequeña aplicación de estudio basada en paquetes con esta estructura: + +```text +study_app/ +├── __init__.py +├── grading.py +└── formatting.py +run_study_app.py +``` + +Requisitos: + +1. En `grading.py`, crea `classify_score(score: int) -> str`, que devuelva `"ready"` para puntuaciones de al menos 80 y `"review"` en caso contrario. +2. En `formatting.py`, crea `format_result(topic: str, status: str) -> str`. +3. En `study_app/__init__.py`, mantén mínima la inicialización. Puedes dejarlo vacío o exponer deliberadamente un nombre documentado a nivel del paquete. +4. En `run_study_app.py`, importa explícitamente la funcionalidad del paquete e imprime resultados para al menos tres temas ficticios. +5. Coloca el comportamiento ejecutable en una función `main()`. +6. Llama a `main()` solo bajo `if __name__ == "__main__":`. +7. No modifiques `sys.path`. +8. No uses `from ... import *`. +9. Cambia el nombre de cualquier archivo que sombree un módulo de la biblioteca estándar que utilices. + +Preguntas extra: + +- ¿Qué nombres vincula `import study_app.grading`? +- ¿Cómo cambiaría el namespace local con `from study_app.grading import classify_score`? +- ¿Qué se ejecuta cuando `study_app.grading` se importa por primera vez en una sesión normal del intérprete? +- ¿Qué contiene `__name__` en el archivo de entrada ejecutado directamente? +- ¿Por qué un import relativo puede comportarse de manera diferente cuando un módulo de paquete se ejecuta por su ruta de archivo? +- ¿Cuándo sería preferible `python -m package.module`? +- ¿Por qué `__init__.py` de un paquete regular puede estar vacío? + +## 50. Lista de revisión + +Antes de pasar a la fase de biblioteca estándar, confirma que puedes responder sin adivinar: + +- ¿Qué es un módulo en un proyecto común basado en archivos `.py`? +- ¿Qué nombre vincula `import grade_tools`? +- ¿Qué cambia con `from grade_tools import classify_score`? +- ¿Qué cambia un alias con `as`? +- ¿Puede ejecutarse código de nivel superior durante un import? +- ¿Cuál es el papel introductorio de `sys.modules`? +- ¿Cuál es el valor de `__name__` cuando un archivo es el programa de nivel superior? +- ¿Qué problema resuelve el main guard? +- ¿Qué representa `sys.path`? +- ¿Por qué nombrar tu archivo `json.py` puede causar problemas? +- ¿Cómo se relacionan `ModuleNotFoundError` e `ImportError`? +- ¿Qué hace reconocible un paquete regular basado en directorios en el diseño convencional? +- ¿Los namespace packages deben contener `__init__.py`? +- ¿Qué significan los puntos iniciales en un import relativo? +- ¿Por qué puede ser útil `python -m package.module`? +- ¿Cuál es la diferencia entre un paquete de importación y una distribución? +- ¿Por qué suelen evitarse los wildcard imports? +- ¿Qué pueden revelar los imports circulares sobre el diseño de módulos? + +## 51. Consulta rápida + +| Necesidad | Patrón o idea | +|---|---| +| Importar un módulo | `import module_name` | +| Acceder a un nombre del módulo | `module_name.item` | +| Importar nombre seleccionado | `from module_name import item` | +| Asignar alias a un módulo | `import module_name as alias` | +| Asignar alias a un nombre seleccionado | `from module_name import item as alias` | +| Guard de entrada directa | `if __name__ == "__main__":` | +| Ubicaciones de búsqueda de módulos | inspeccionar `sys.path` | +| Caché normal de imports | `sys.modules` | +| Módulo solicitado ausente | normalmente `ModuleNotFoundError` | +| Fallo de import más amplio | `ImportError` | +| Marcador convencional de paquete regular | `__init__.py` | +| Importar submódulo de paquete | `import package.submodule` | +| Import absoluto de paquete | `from package.module import item` | +| Import relativo de módulo hermano | `from .module import item` | +| Ejecutar módulo por nombre de import | `python -m package.module` | +| Ejecutar entrada del paquete | `python -m package` con `package/__main__.py` | +| Evitar namespace oculto | preferir nombres explícitos a `import *` | +| Evitar cirugía casual de rutas | no usar modificación de `sys.path` como estructura normal | + +Un modelo útil de dependencias es: + +```text +punto de entrada + ↓ importa +módulos coordinadores + ↓ importan +módulos reutilizables enfocados +``` + +Busca una dirección de dependencias que el estudiante pueda dibujar sin crear un nudo. + +## Fase 7 completada + +Este capítulo cierra la **Fase 7: Errores, Archivos y Módulos**. + +La fase ahora conecta manejo de fallos, límites de persistencia, datos textuales estructurados y organización del código: + +```text +excepciones + ↓ +señalización deliberada de excepciones + ↓ +tiempo de vida seguro de archivos + ↓ +límites de datos TXT / CSV / JSON + ↓ +imports / módulos / paquetes +``` + +Ahora puedes construir un pequeño programa que falla deliberadamente cuando se rompe un contrato, maneja fallos externos esperados, persiste datos textuales con seguridad, analiza formatos comunes y separa código reutilizable entre módulos y paquetes. + +## Qué sigue + +La **Fase 8: Biblioteca Estándar** aprovechará el modelo de importación para explorar herramientas útiles que vienen con Python, comenzando por módulos como `pathlib` y `datetime` según el roadmap del proyecto. + +La transición importante es: + +```text +aprender cómo los imports organizan dependencias + ↓ +usar deliberadamente módulos de la biblioteca estándar de Python +``` + +## Referencias oficiales + +- Tutorial de Python 3.14, Modules: +- Referencia del lenguaje Python 3.14, The import system: +- Referencia del lenguaje Python 3.14, The import statement: +- Documentación de línea de comandos de Python 3.14, `-m`: +- Documentación de Python 3.14 sobre `__main__`: \ No newline at end of file diff --git a/errors-files-and-modules/05-imports-modules-and-packages/README.md b/errors-files-and-modules/05-imports-modules-and-packages/README.md new file mode 100644 index 0000000..70dae94 --- /dev/null +++ b/errors-files-and-modules/05-imports-modules-and-packages/README.md @@ -0,0 +1,1034 @@ +
+ +# Organizing Code with Imports, Modules, and Packages + +[🇺🇸 English](README.md) · [🇧🇷 Português](README.pt-BR.md) · [🇪🇸 Español](README.es.md) + +
+ +[← Back to Errors, Files, and Modules](../README.md) · [← Previous: Working with TXT, CSV, and JSON](../04-txt-csv-and-json/README.md) + +As programs grow, keeping every function, constant, parser, and workflow in one file becomes harder to understand and maintain. Python's import system lets you divide code into **modules** and organize related modules into **packages**. + +The goal of this chapter is not to memorize every detail of Python's import machinery. It is to build a reliable mental model for small and medium programs: where imported names come from, what code runs during an import, how packages organize modules, why execution context matters, and which habits keep dependencies understandable. + +**Estimated study time:** 120–160 minutes. + +**Python requirement:** Python 3.10 or newer. The import behavior taught here was checked against the official Python 3.14 tutorial, language reference, and command-line documentation. + +## Learning objectives + +By the end of this chapter, you should be able to: + +- explain what a Python module is in ordinary source-code projects; +- distinguish a module object from the names imported into another module; +- use `import module`, `from module import name`, and `as` deliberately; +- explain why module-qualified access often improves clarity; +- describe what happens to top-level code when a module is imported; +- explain the beginner-level role of `sys.modules` in import caching; +- use `if __name__ == "__main__":` to separate importable definitions from direct execution; +- describe the purpose of `sys.path` without treating it as a list to patch casually; +- distinguish `ModuleNotFoundError` from the broader `ImportError` family; +- explain what a regular package is and what `__init__.py` does; +- use dotted package names and basic absolute imports; +- recognize relative imports and explain why execution context matters for them; +- use `python -m` when a module should run in its package/import context; +- distinguish an import package from an installable distribution package; +- avoid wildcard imports, accidental module-name collisions, import-time side effects, and simple circular-import designs; +- organize a small multi-file Python program with explicit dependencies. + +## 1. Why split code across files? + +A single file is useful while a program is small. As responsibilities accumulate, one file can become a crowded room where unrelated ideas compete for attention. + +Modules create boundaries: + +```text +input handling + ↓ +validation + ↓ +calculation + ↓ +formatting +``` + +Each responsibility can live in a file whose name communicates its purpose. + +Splitting code is not automatically better. A three-line helper does not need its own module merely because Python supports modules. Create a boundary when it improves reuse, navigation, testing, ownership of a responsibility, or dependency clarity. + +## 2. In ordinary Python source code, a `.py` file can be a module + +The Python tutorial introduces a module as a file containing Python definitions and statements. + +For example: + +```text +study_tools.py +``` + +can contain: + +```python +def build_label(topic: str, level: int) -> str: + return f"{topic} | level {level}" +``` + +and another file can import that module. + +This file-based model is the right starting point for learners. Python's full import system can also load modules implemented in other ways, including built-in and extension modules, so "module" is broader than "a `.py` file" in the complete language model. + +## 3. `import module` binds the module name + +Suppose `grade_tools.py` contains: + +```python +def classify_score(score: int) -> str: + if score >= 80: + return "ready" + return "review" +``` + +Another file can import it: + +```python +import grade_tools + +status = grade_tools.classify_score(84) +print(status) +``` + +The name `grade_tools` now refers to the imported module object in the importing module's namespace. + +## 4. Module-qualified access makes the source of a name visible + +With: + +```python +import grade_tools +``` + +you call: + +```python +grade_tools.classify_score(84) +``` + +That extra prefix is useful information. A reader can see immediately that `classify_score` comes from another module. + +This is one reason `import module` is often a clear default when the module name is short and meaningful. + +## 5. `from module import name` binds selected names directly + +Python also allows: + +```python +from grade_tools import classify_score + +status = classify_score(84) +``` + +Here `classify_score` is bound directly in the importing module's namespace. The name `grade_tools` is not automatically bound by this statement. + +The source module still has to be found and loaded. `from ... import ...` changes what names are bound in the importer; it does not bypass the import system. + +## 6. `as` creates a deliberate local alias + +A module can be imported under another local name: + +```python +import statistics as stats + +mean_score = stats.mean([80, 90, 100]) +``` + +A selected name can also be aliased: + +```python +from math import sqrt as square_root + +print(square_root(81)) +``` + +Use aliases when they are conventional or genuinely improve readability. Avoid cryptic aliases that make the code harder to search and understand. + +## 7. Choose an import style by readability, not by shortest typing + +Compare: + +```python +import decimal + +value = decimal.Decimal("0.1") +``` + +with: + +```python +from decimal import Decimal + +value = Decimal("0.1") +``` + +Both can be appropriate. + +Questions that help: + +- Is the module name useful context? +- Will several names come from the same module? +- Could a directly imported name collide with another local name? +- Is the shorter form already a strong convention in that ecosystem? + +The shortest line is not always the clearest dependency. + +## 8. Imports are executable statements + +An import is not a text-copy operation. Python locates and loads a module, creates or obtains a module object, and executes the module's top-level code when initialization is required. + +Consider a module containing: + +```python +print("Loading helpers") + + +def build_message() -> str: + return "Ready" +``` + +Importing that module can print `Loading helpers` during module initialization. + +This is why top-level executable work should be intentional. + +## 9. Module definitions are created by executing module code + +A function definition is itself a statement. When a module is initialized, Python executes statements that bind names such as functions, classes, and constants in that module's namespace. + +A useful simplified flow is: + +```text +find module + ↓ +create/obtain module object + ↓ +execute initialization code if needed + ↓ +module namespace contains its definitions +``` + +This mental model explains why syntax errors, missing dependencies, and top-level exceptions can make an import fail. + +## 10. Normal imports reuse modules through `sys.modules` + +During a normal interpreter session, imported modules are cached in `sys.modules`. + +That means repeated statements such as: + +```python +import math +import math +``` + +do not normally re-execute the module's initialization from scratch each time. + +This is a useful beginner model, not a rule that module code can never run again. Advanced operations such as explicit reloading or manually changing import state can alter that behavior. + +## 11. Avoid using import-time side effects as hidden application flow + +This is fragile: + +```python +# settings.py +print("Connecting to something...") +``` + +because any code that imports `settings` now triggers that work. + +Prefer definitions at module level and explicit execution through functions: + +```python +def initialize_settings() -> None: + print("Settings initialized") +``` + +The caller can then decide when that action belongs in the program flow. + +Some modules legitimately perform small initialization during import. The design warning is about surprising, expensive, irreversible, or order-dependent work. + +## 12. Every module has a `__name__` + +A module can inspect its own global `__name__` value. + +When a module is imported normally, `__name__` reflects its import name. + +For example, inside `grade_tools.py` imported as `grade_tools`, the value is typically: + +```text +grade_tools +``` + +When code is executed as the top-level program, Python gives that execution environment the name: + +```text +__main__ +``` + +## 13. The main guard separates definitions from direct execution + +A common pattern is: + +```python +def main() -> None: + print("Program started") + + +if __name__ == "__main__": + main() +``` + +If the file is executed as the main program, `main()` runs. + +If the file is imported, the function is defined but the guarded call does not run. + +## 14. Put reusable work in functions before the main guard + +Prefer: + +```python +def build_report() -> str: + return "Study report" + + +def main() -> None: + print(build_report()) + + +if __name__ == "__main__": + main() +``` + +over placing the whole application directly inside the guard. + +Functions remain reusable and testable, while the guard answers only one question: should direct-entry behavior start now? + +## 15. `__name__ == "__main__"` is not an import blocker + +The guard does not prevent the file from being imported. + +It prevents only the guarded block from running when the module is imported under another name. + +Definitions above the guard still execute as module statements and become available in the module namespace. + +## 16. Python needs search locations to find modules + +When you write: + +```python +import study_tools +``` + +Python must determine what `study_tools` refers to. + +The complete import system supports several kinds of finders and loaders. At beginner level, the important idea is that Python searches import locations according to its import machinery and execution environment. + +Those search locations are reflected in `sys.path` for ordinary path-based imports. + +## 17. `sys.path` is a list of module search locations + +You can inspect it: + +```python +import sys + +for location in sys.path: + print(location) +``` + +Its exact contents depend on how Python was started, the environment, installation configuration, and other settings. + +Do not memorize one universal `sys.path` order from a screenshot. Learn the concept: it tells path-based import machinery where modules and packages may be found. + +## 18. Do not treat `sys.path.append(...)` as the normal fix for project structure + +This may appear to solve an import quickly: + +```python +import sys + +sys.path.append("../somewhere") +``` + +but it makes imports depend on runtime path surgery and often hides an unclear project layout or execution command. + +Prefer a coherent package structure, a suitable working/install environment, and an execution method that gives Python the intended import context. + +There are advanced cases for customizing import paths, but casual `sys.path` mutation should not be the first design tool. + +## 19. Module names can collide with other modules + +Imagine creating a beginner file named: + +```text +json.py +``` + +and then writing: + +```python +import json +``` + +Depending on the search context, your local file may shadow the standard-library module you intended to import. + +Avoid naming your files after standard-library modules or important dependencies used by the same project. + +## 20. `ModuleNotFoundError` usually means the requested module could not be found + +For example: + +```python +import module_that_does_not_exist +``` + +normally raises `ModuleNotFoundError`. + +`ModuleNotFoundError` is a subclass of `ImportError`. + +The message and exact failing name matter because an import can find your first module and still fail while importing one of its dependencies. + +## 21. `ImportError` is the broader import-related exception + +A module may exist while a requested name does not: + +```python +from math import name_that_does_not_exist +``` + +This raises an `ImportError` because `math` is available but the requested imported name is not. + +Do not catch `ImportError` around a large block merely to make failures disappear. Catch import-related exceptions only when the program has a deliberate policy, such as a truly optional dependency with a documented fallback. + +## 22. A package organizes modules under a dotted namespace + +Packages let related modules use hierarchical names such as: + +```text +study_tools.formatting +study_tools.validation +study_tools.reports +``` + +A package can contain modules and subpackages. + +In Python's full import model, a package is a special kind of module that can contain submodules. The directory analogy is useful for ordinary source projects, but the language model is based on module/package objects rather than folders alone. + +## 23. A regular package commonly uses `__init__.py` + +A simple regular package might look like: + +```text +study_tools/ +├── __init__.py +├── formatting.py +└── validation.py +``` + +The presence of `__init__.py` makes this directory a regular package in the conventional file-system layout. + +`__init__.py` may be empty. It may also define initialization behavior or intentionally expose selected names at the package level. + +## 24. Namespace packages are an advanced exception to the `__init__.py` rule + +Modern Python also supports **namespace packages**, which can exist without an `__init__.py` and can span multiple locations. + +Therefore this statement is too broad: + +```text +"Every Python package must have __init__.py." +``` + +For beginner projects, regular packages with `__init__.py` are usually the clearest starting point. Namespace packages can wait until a project genuinely needs their model. + +## 25. `__init__.py` is code, so keep its behavior deliberate + +This is valid: + +```python +from .formatting import build_label + +__all__ = ["build_label"] +``` + +Now the package can intentionally provide a convenient public name: + +```python +from study_tools import build_label +``` + +But a large `__init__.py` full of expensive setup and surprising imports can make package behavior harder to understand. + +Treat package initialization as part of your dependency design. + +## 26. Dotted names express package hierarchy + +This import: + +```python +import study_tools.formatting +``` + +loads the submodule using its full dotted name. + +You then access: + +```python +study_tools.formatting.build_label("Modules", 2) +``` + +Another style is: + +```python +from study_tools import formatting + +print(formatting.build_label("Modules", 2)) +``` + +Both make the package relationship explicit. + +## 27. Import the narrowest stable interface that keeps intent clear + +Suppose a package intentionally exposes `build_label` from `__init__.py`: + +```python +from study_tools import build_label +``` + +That can be a clean package API. + +If the package does not promise that public shortcut, importing the defining module may be more honest: + +```python +from study_tools.formatting import build_label +``` + +The best choice depends on the interface the package documents, not on how many characters the import saves. + +## 28. An import package is not the same thing as a distribution package + +The word **package** is overloaded in Python conversations. + +An **import package** is part of Python's module namespace, such as: + +```text +study_tools +``` + +A **distribution package** is something installed and managed by packaging tools and may provide one or more import packages or modules. + +The install name and import name can even differ. + +This chapter teaches import packages. Packaging and publishing distributions are separate topics. + +## 29. Absolute imports name the package path explicitly + +Inside a project package, an absolute import can look like: + +```python +from study_tools.formatting import build_label +``` + +It names the package from the top-level import namespace. + +Absolute imports are often easy to search and understand because the dependency path is explicit. + +## 30. Relative imports use leading dots inside packages + +A module inside `study_tools` can import a sibling with: + +```python +from .formatting import build_label +``` + +A leading dot refers to the current package. Additional dots can refer to parent package levels. + +Relative imports are useful for internal package relationships, but they depend on Python knowing the module's package context. + +## 31. Relative imports are not based on the current working directory + +This is an important distinction. + +A relative import such as: + +```python +from .formatting import build_label +``` + +is resolved from the current module's package information, not by walking from whatever directory the terminal happens to be in. + +That is why "I am standing in the right folder" is not a complete explanation for whether a relative import will work. + +## 32. Directly executing a package module can remove the package context it expects + +Suppose a module contains a relative import and is intended to live inside a package. + +Running it by file path: + +```text +python study_tools/cli.py +``` + +may execute it as the top-level `__main__` module rather than as `study_tools.cli`. A relative import can then fail because the expected parent package is not known. + +When the module is designed to run in package context, `python -m` is often the correct tool. + +## 33. `python -m` locates a module through the import system and executes it + +For example: + +```text +python -m study_tools.cli +``` + +Python locates `study_tools.cli` using the standard import mechanism and executes its contents as the `__main__` module. + +This preserves the fact that the code belongs to the `study_tools` package while still making it the program entry point. + +The command uses a **module name**, not a `.py` filename. + +## 34. A package can define `__main__.py` for `python -m package_name` + +If a package contains: + +```text +study_tools/ +├── __init__.py +├── __main__.py +└── formatting.py +``` + +then: + +```text +python -m study_tools +``` + +executes `study_tools.__main__` as the main module. + +This is useful when the package itself has a command-line entry behavior. A package does not gain that behavior merely because `__init__.py` exists. + +## 35. Imports make dependencies visible + +If `reports.py` imports `formatting.py`, then `reports` depends on `formatting`. + +A useful dependency sketch is: + +```text +cli + ↓ +reports + ↓ +formatting +``` + +Keeping dependency direction understandable helps prevent tangled modules where everything imports everything else. + +## 36. Circular imports are often a design signal + +A simple circular relationship looks like: + +```text +module_a imports module_b + ↑ ↓ + └─────────┘ +``` + +Python may encounter one module while it is only partially initialized, producing missing-name errors or confusing behavior. + +Common design fixes include: + +- move shared definitions into a third module; +- pass values or callables as parameters instead of importing back upward; +- clarify which module owns a responsibility; +- reduce top-level work that depends on the other module being fully initialized. + +Moving an import inside a function can sometimes break a cycle, but it may only hide the architectural problem. Understand the dependency before applying that workaround. + +## 37. Imports inside functions are allowed, but top-level imports are the usual readable default + +This is valid Python: + +```python +def calculate_root(value: float) -> float: + import math + + return math.sqrt(value) +``` + +Most ordinary dependencies are easier to see when imports appear near the top of the module. + +Local imports can be deliberate for optional dependencies, delayed loading, or carefully understood cycles. Use them for a reason, not as a reflex. + +## 38. Avoid wildcard imports in ordinary modules + +This syntax exists: + +```python +from math import * +``` + +but it makes the local namespace less explicit. A reader has to know which names the source exports, and new exported names can create collisions. + +Prefer explicit imports: + +```python +from math import pi, sqrt +``` + +`__all__` can influence what a wildcard import exposes, but it does not turn wildcard imports into the clearest default for application code. + +## 39. Group imports for readability + +A common readable organization is: + +```python +import csv +import json + +from study_tools import build_label +``` + +PEP 8 convention groups standard-library, third-party, and local application imports separately when those groups exist. + +The deeper goal is visibility: a reader should be able to understand a module's main dependencies without hunting through unrelated code. + +## 40. Practical example: import the standard library + +```python +import math + + +number = 81 +root = math.sqrt(number) + +print(f"Square root: {root}") +``` + +Output: + +```text +Square root: 9.0 +``` + +Executable version: [`examples/import_standard_library.py`](examples/import_standard_library.py). + +## 41. Practical example: import your own module + +Helper module `grade_tools.py`: + +```python +def classify_score(score: int) -> str: + if score >= 80: + return "ready" + return "review" +``` + +Executable module `module_demo.py`: + +```python +import grade_tools + + +score = 84 +status = grade_tools.classify_score(score) + +print(f"Score {score}: {status}") +``` + +Output: + +```text +Score 84: ready +``` + +Executable version: [`examples/module_demo.py`](examples/module_demo.py). Supporting module: [`examples/grade_tools.py`](examples/grade_tools.py). + +## 42. Practical example: import from a regular package + +Package layout: + +```text +examples/ +├── package_demo.py +└── study_tools/ + ├── __init__.py + └── formatting.py +``` + +`formatting.py` defines the reusable function: + +```python +def build_label(topic: str, level: int) -> str: + return f"{topic} | level {level}" +``` + +`__init__.py` intentionally exposes it at the package level: + +```python +from .formatting import build_label + +__all__ = ["build_label"] +``` + +The executable file imports the package API: + +```python +from study_tools import build_label + + +print(build_label("Modules", 2)) +``` + +Output: + +```text +Modules | level 2 +``` + +Executable version: [`examples/package_demo.py`](examples/package_demo.py). Supporting package: [`examples/study_tools/`](examples/study_tools/). + +## 43. Practical example: main guard + +```python +def main() -> None: + print("Main guard executed") + + +if __name__ == "__main__": + main() +``` + +Output when executed directly: + +```text +Main guard executed +``` + +Executable version: [`examples/main_guard.py`](examples/main_guard.py). + +## 44. Common mistake: naming a file after a dependency + +Files such as these can create confusing shadows: + +```text +json.py +csv.py +math.py +random.py +``` + +if the same project also expects the standard-library modules with those names. + +Choose module names that represent your own responsibility and do not collide with dependencies you import. + +## 45. Common mistake: hiding application startup inside an import + +Avoid making this the program architecture: + +```text +import app + ↓ +app immediately reads files, connects services, and starts loops +``` + +Prefer an explicit entry point: + +```text +import definitions + ↓ +main() deliberately starts application behavior +``` + +Explicit startup is easier to test, reuse, and reason about. + +## 46. Common mistake: assuming file execution and module execution are identical + +These commands can create different import contexts: + +```text +python path/to/tool.py +python -m package.tool +``` + +Both execute Python code, but `-m` locates a named module through the import system and executes it as `__main__`. + +The difference matters especially for packages and relative imports. + +## 47. Common mistake: using packages only to create deep folder trees + +This is not automatically good design: + +```text +app/core/services/helpers/utils/common/ +``` + +A package hierarchy should communicate meaningful namespaces and responsibilities. + +More nesting adds more import paths, navigation, and boundaries to understand. Create levels that earn their complexity. + +## 48. A small project can grow in stages + +Start simple: + +```text +app.py +``` + +Then extract a real reusable responsibility: + +```text +app.py +grade_tools.py +``` + +Then group related modules when the namespace becomes useful: + +```text +app.py +study_tools/ +├── __init__.py +├── grades.py +└── formatting.py +``` + +Structure should follow responsibilities, not a desire to look "enterprise" before the program needs it. + +## 49. Exercise + +Create a small package-based study application with this structure: + +```text +study_app/ +├── __init__.py +├── grading.py +└── formatting.py +run_study_app.py +``` + +Requirements: + +1. In `grading.py`, create `classify_score(score: int) -> str` that returns `"ready"` for scores of at least 80 and `"review"` otherwise. +2. In `formatting.py`, create `format_result(topic: str, status: str) -> str`. +3. In `study_app/__init__.py`, keep initialization minimal. You may leave it empty or deliberately expose one documented package-level name. +4. In `run_study_app.py`, import the package functionality explicitly and print results for at least three fictional topics. +5. Put the executable behavior in a `main()` function. +6. Call `main()` only under `if __name__ == "__main__":`. +7. Do not mutate `sys.path`. +8. Do not use `from ... import *`. +9. Rename any file that would shadow a standard-library module you use. + +Extra questions: + +- Which names are bound by `import study_app.grading`? +- How would the local namespace differ with `from study_app.grading import classify_score`? +- What runs when `study_app.grading` is imported for the first time in a normal interpreter session? +- What does `__name__` contain in the directly executed entry file? +- Why can a relative import behave differently when a package module is executed by file path? +- When would `python -m package.module` be preferable? +- Why is a regular package's `__init__.py` allowed to be empty? + +## 50. Review checklist + +Before moving to the standard library phase, confirm that you can answer these without guessing: + +- What is a module in an ordinary `.py`-based project? +- What name does `import grade_tools` bind? +- What changes with `from grade_tools import classify_score`? +- What does an `as` alias change? +- Can top-level code run during an import? +- What beginner-level role does `sys.modules` play? +- What is `__name__` when a file is the top-level program? +- What problem does the main guard solve? +- What does `sys.path` represent? +- Why can naming your file `json.py` cause trouble? +- How are `ModuleNotFoundError` and `ImportError` related? +- What makes a regular directory-based package recognizable in the conventional layout? +- Are namespace packages required to contain `__init__.py`? +- What do leading dots mean in a relative import? +- Why can `python -m package.module` be useful? +- What is the difference between an import package and a distribution package? +- Why are wildcard imports usually avoided? +- What can circular imports reveal about module design? + +## 51. Quick reference + +| Need | Pattern or idea | +|---|---| +| Import a module | `import module_name` | +| Access a module name | `module_name.item` | +| Import selected name | `from module_name import item` | +| Alias a module | `import module_name as alias` | +| Alias a selected name | `from module_name import item as alias` | +| Direct-entry guard | `if __name__ == "__main__":` | +| Module search locations | inspect `sys.path` | +| Normal import cache | `sys.modules` | +| Missing requested module | commonly `ModuleNotFoundError` | +| Broader import failure | `ImportError` | +| Conventional regular package marker | `__init__.py` | +| Import a package submodule | `import package.submodule` | +| Absolute package import | `from package.module import item` | +| Relative sibling import | `from .module import item` | +| Execute module by import name | `python -m package.module` | +| Execute package entry | `python -m package` with `package/__main__.py` | +| Avoid hidden namespace imports | prefer explicit names over `import *` | +| Avoid casual path surgery | do not use `sys.path` mutation as normal structure | + +A useful dependency model is: + +```text +entry point + ↓ imports +coordinating modules + ↓ imports +focused reusable modules +``` + +Aim for dependency direction that a learner can draw without creating a knot. + +## Phase 7 complete + +This chapter closes **Phase 7: Errors, Files, and Modules**. + +The phase now connects failure handling, persistence boundaries, structured text data, and code organization: + +```text +exceptions + ↓ +deliberate exception signaling + ↓ +safe file lifetime + ↓ +TXT / CSV / JSON data boundaries + ↓ +imports / modules / packages +``` + +You can now build a small program that fails deliberately when a contract is broken, handles expected external failures, persists text data safely, parses common formats, and separates reusable code across modules and packages. + +## What comes next + +**Phase 8: Standard Library** will build on the import model by exploring useful batteries that ship with Python, beginning with modules such as `pathlib` and `datetime` according to the project roadmap. + +The important transition is: + +```text +learn how imports organize dependencies + ↓ +use Python's standard-library modules deliberately +``` + +## Official references + +- Python 3.14 tutorial, Modules: +- Python 3.14 language reference, The import system: +- Python 3.14 language reference, The import statement: +- Python 3.14 command-line documentation, `-m`: +- Python 3.14 `__main__` documentation: \ No newline at end of file diff --git a/errors-files-and-modules/05-imports-modules-and-packages/README.pt-BR.md b/errors-files-and-modules/05-imports-modules-and-packages/README.pt-BR.md new file mode 100644 index 0000000..7a79376 --- /dev/null +++ b/errors-files-and-modules/05-imports-modules-and-packages/README.pt-BR.md @@ -0,0 +1,1034 @@ +
+ +# Organizando Código com Imports, Módulos e Pacotes + +[🇺🇸 English](README.md) · [🇧🇷 Português](README.pt-BR.md) · [🇪🇸 Español](README.es.md) + +
+ +[← Voltar para Erros, Arquivos e Módulos](../README.pt-BR.md) · [← Anterior: Trabalhando com TXT, CSV e JSON](../04-txt-csv-and-json/README.pt-BR.md) + +À medida que os programas crescem, manter cada função, constante, parser e fluxo de trabalho em um único arquivo fica mais difícil de entender e manter. O sistema de importação do Python permite dividir o código em **módulos** e organizar módulos relacionados em **pacotes**. + +O objetivo deste capítulo não é memorizar cada detalhe do mecanismo de importação do Python. É construir um modelo mental confiável para programas pequenos e médios: de onde vêm os nomes importados, qual código roda durante um import, como pacotes organizam módulos, por que o contexto de execução importa e quais hábitos mantêm as dependências compreensíveis. + +**Tempo estimado de estudo:** 120–160 minutos. + +**Requisito de Python:** Python 3.10 ou mais recente. O comportamento de importação ensinado aqui foi conferido com o tutorial, a referência da linguagem e a documentação de linha de comando oficiais do Python 3.14. + +## Objetivos de aprendizagem + +Ao final deste capítulo, você deverá conseguir: + +- explicar o que é um módulo Python em projetos comuns de código-fonte; +- distinguir um objeto módulo dos nomes importados para outro módulo; +- usar `import module`, `from module import name` e `as` de forma deliberada; +- explicar por que o acesso qualificado pelo módulo muitas vezes melhora a clareza; +- descrever o que acontece com o código no nível superior quando um módulo é importado; +- explicar o papel introdutório de `sys.modules` no cache de imports; +- usar `if __name__ == "__main__":` para separar definições importáveis da execução direta; +- descrever o propósito de `sys.path` sem tratá-lo como uma lista para remendar casualmente; +- distinguir `ModuleNotFoundError` da família mais ampla de `ImportError`; +- explicar o que é um pacote regular e o que `__init__.py` faz; +- usar nomes pontuados de pacotes e imports absolutos básicos; +- reconhecer imports relativos e explicar por que o contexto de execução importa para eles; +- usar `python -m` quando um módulo deve rodar dentro do contexto de pacote/import; +- distinguir um pacote de importação de uma distribuição instalável; +- evitar imports com curinga, colisões acidentais de nomes de módulos, efeitos colaterais no import e designs simples com imports circulares; +- organizar um pequeno programa Python em vários arquivos com dependências explícitas. + +## 1. Por que dividir o código entre arquivos? + +Um único arquivo é útil enquanto o programa é pequeno. À medida que responsabilidades se acumulam, esse arquivo pode virar uma sala lotada onde ideias sem relação competem por atenção. + +Módulos criam fronteiras: + +```text +tratamento de entrada + ↓ +validação + ↓ +cálculo + ↓ +formatação +``` + +Cada responsabilidade pode viver em um arquivo cujo nome comunica seu propósito. + +Dividir código não é automaticamente melhor. Uma função auxiliar de três linhas não precisa de seu próprio módulo apenas porque Python suporta módulos. Crie uma fronteira quando ela melhorar reuso, navegação, testes, propriedade de uma responsabilidade ou clareza das dependências. + +## 2. Em código-fonte Python comum, um arquivo `.py` pode ser um módulo + +O tutorial do Python introduz um módulo como um arquivo contendo definições e instruções Python. + +Por exemplo: + +```text +study_tools.py +``` + +pode conter: + +```python +def build_label(topic: str, level: int) -> str: + return f"{topic} | level {level}" +``` + +e outro arquivo pode importar esse módulo. + +Esse modelo baseado em arquivos é o ponto de partida correto para iniciantes. O sistema completo de importação do Python também pode carregar módulos implementados de outras formas, incluindo módulos embutidos e de extensão. Portanto, no modelo completo da linguagem, "módulo" é mais amplo do que "um arquivo `.py`". + +## 3. `import module` vincula o nome do módulo + +Suponha que `grade_tools.py` contenha: + +```python +def classify_score(score: int) -> str: + if score >= 80: + return "ready" + return "review" +``` + +Outro arquivo pode importá-lo: + +```python +import grade_tools + +status = grade_tools.classify_score(84) +print(status) +``` + +O nome `grade_tools` agora se refere ao objeto módulo importado no namespace do módulo que fez o import. + +## 4. O acesso qualificado pelo módulo torna visível a origem de um nome + +Com: + +```python +import grade_tools +``` + +você chama: + +```python +grade_tools.classify_score(84) +``` + +Esse prefixo extra é informação útil. Quem lê consegue ver imediatamente que `classify_score` vem de outro módulo. + +Essa é uma das razões pelas quais `import module` costuma ser um padrão claro quando o nome do módulo é curto e significativo. + +## 5. `from module import name` vincula nomes selecionados diretamente + +Python também permite: + +```python +from grade_tools import classify_score + +status = classify_score(84) +``` + +Aqui, `classify_score` é vinculado diretamente no namespace do módulo importador. O nome `grade_tools` não é vinculado automaticamente por essa instrução. + +O módulo de origem ainda precisa ser encontrado e carregado. `from ... import ...` muda quais nomes são vinculados no importador; ele não ignora o sistema de importação. + +## 6. `as` cria um alias local deliberado + +Um módulo pode ser importado com outro nome local: + +```python +import statistics as stats + +mean_score = stats.mean([80, 90, 100]) +``` + +Um nome selecionado também pode receber alias: + +```python +from math import sqrt as square_root + +print(square_root(81)) +``` + +Use aliases quando forem convencionais ou realmente melhorarem a legibilidade. Evite aliases enigmáticos que tornem o código mais difícil de pesquisar e entender. + +## 7. Escolha o estilo de import pela legibilidade, não pela menor quantidade de digitação + +Compare: + +```python +import decimal + +value = decimal.Decimal("0.1") +``` + +com: + +```python +from decimal import Decimal + +value = Decimal("0.1") +``` + +Os dois podem ser adequados. + +Perguntas úteis: + +- O nome do módulo fornece contexto importante? +- Vários nomes virão do mesmo módulo? +- Um nome importado diretamente poderia colidir com outro nome local? +- A forma mais curta já é uma convenção forte naquele ecossistema? + +A linha mais curta nem sempre representa a dependência mais clara. + +## 8. Imports são instruções executáveis + +Um import não é uma operação de copiar texto. Python localiza e carrega um módulo, cria ou obtém um objeto módulo e executa o código no nível superior quando a inicialização é necessária. + +Considere um módulo contendo: + +```python +print("Loading helpers") + + +def build_message() -> str: + return "Ready" +``` + +Importar esse módulo pode imprimir `Loading helpers` durante a inicialização. + +É por isso que trabalho executável no nível superior deve ser intencional. + +## 9. Definições do módulo são criadas pela execução do código do módulo + +Uma definição de função também é uma instrução. Quando um módulo é inicializado, Python executa instruções que vinculam nomes como funções, classes e constantes no namespace daquele módulo. + +Um fluxo simplificado útil é: + +```text +localizar módulo + ↓ +criar/obter objeto módulo + ↓ +executar código de inicialização quando necessário + ↓ +namespace do módulo contém suas definições +``` + +Esse modelo mental explica por que erros de sintaxe, dependências ausentes e exceções no nível superior podem fazer um import falhar. + +## 10. Imports normais reutilizam módulos por meio de `sys.modules` + +Durante uma sessão normal do interpretador, módulos importados ficam em cache em `sys.modules`. + +Isso significa que instruções repetidas como: + +```python +import math +import math +``` + +normalmente não reexecutam do zero a inicialização do módulo a cada vez. + +Esse é um modelo introdutório útil, não uma regra dizendo que o código de um módulo nunca pode rodar novamente. Operações avançadas, como reload explícito ou alterações manuais do estado de importação, podem mudar esse comportamento. + +## 11. Evite usar efeitos colaterais de import como fluxo escondido da aplicação + +Isto é frágil: + +```python +# settings.py +print("Connecting to something...") +``` + +porque qualquer código que importar `settings` agora dispara esse trabalho. + +Prefira definições no nível do módulo e execução explícita por funções: + +```python +def initialize_settings() -> None: + print("Settings initialized") +``` + +Assim, o chamador decide quando aquela ação pertence ao fluxo do programa. + +Alguns módulos realizam legitimamente uma pequena inicialização no import. O alerta de design é sobre trabalho surpreendente, caro, irreversível ou dependente de ordem. + +## 12. Todo módulo possui um `__name__` + +Um módulo pode inspecionar seu próprio valor global `__name__`. + +Quando um módulo é importado normalmente, `__name__` reflete seu nome de importação. + +Por exemplo, dentro de `grade_tools.py` importado como `grade_tools`, o valor normalmente é: + +```text +grade_tools +``` + +Quando o código é executado como programa de nível superior, Python dá a esse ambiente de execução o nome: + +```text +__main__ +``` + +## 13. O main guard separa definições da execução direta + +Um padrão comum é: + +```python +def main() -> None: + print("Program started") + + +if __name__ == "__main__": + main() +``` + +Se o arquivo for executado como programa principal, `main()` roda. + +Se o arquivo for importado, a função é definida, mas a chamada protegida não roda. + +## 14. Coloque o trabalho reutilizável em funções antes do main guard + +Prefira: + +```python +def build_report() -> str: + return "Study report" + + +def main() -> None: + print(build_report()) + + +if __name__ == "__main__": + main() +``` + +a colocar a aplicação inteira diretamente dentro do guard. + +As funções continuam reutilizáveis e testáveis, enquanto o guard responde apenas a uma pergunta: o comportamento de entrada direta deve começar agora? + +## 15. `__name__ == "__main__"` não bloqueia o import + +O guard não impede que o arquivo seja importado. + +Ele impede apenas que o bloco protegido rode quando o módulo é importado com outro nome. + +As definições acima do guard ainda são executadas como instruções do módulo e ficam disponíveis no namespace do módulo. + +## 16. Python precisa de locais de busca para encontrar módulos + +Quando você escreve: + +```python +import study_tools +``` + +Python precisa determinar a que `study_tools` se refere. + +O sistema completo de importação suporta vários tipos de finders e loaders. No nível introdutório, a ideia importante é que Python pesquisa locais de importação de acordo com seu mecanismo de import e com o ambiente de execução. + +Esses locais de busca aparecem em `sys.path` para imports comuns baseados em caminhos. + +## 17. `sys.path` é uma lista de locais de busca de módulos + +Você pode inspecioná-la: + +```python +import sys + +for location in sys.path: + print(location) +``` + +Seu conteúdo exato depende de como Python foi iniciado, do ambiente, da configuração da instalação e de outras definições. + +Não memorize uma ordem universal de `sys.path` a partir de uma captura de tela. Aprenda o conceito: ela informa ao mecanismo de importação baseado em caminhos onde módulos e pacotes podem ser encontrados. + +## 18. Não trate `sys.path.append(...)` como a correção normal para a estrutura do projeto + +Isto pode parecer resolver rapidamente um import: + +```python +import sys + +sys.path.append("../somewhere") +``` + +mas faz os imports dependerem de uma cirurgia de caminhos em runtime e muitas vezes esconde uma estrutura de projeto ou comando de execução pouco claros. + +Prefira uma estrutura coerente de pacotes, um ambiente de trabalho/instalação adequado e uma forma de execução que dê ao Python o contexto de import pretendido. + +Existem casos avançados para personalizar caminhos de importação, mas mutar `sys.path` casualmente não deve ser a primeira ferramenta de design. + +## 19. Nomes de módulos podem colidir com outros módulos + +Imagine criar um arquivo de estudo chamado: + +```text +json.py +``` + +e depois escrever: + +```python +import json +``` + +Dependendo do contexto de busca, seu arquivo local pode sombrear o módulo da biblioteca padrão que você pretendia importar. + +Evite dar aos seus arquivos nomes de módulos da biblioteca padrão ou de dependências importantes usadas pelo mesmo projeto. + +## 20. `ModuleNotFoundError` normalmente significa que o módulo solicitado não foi encontrado + +Por exemplo: + +```python +import module_that_does_not_exist +``` + +normalmente levanta `ModuleNotFoundError`. + +`ModuleNotFoundError` é uma subclasse de `ImportError`. + +A mensagem e o nome exato que falhou importam porque um import pode encontrar seu primeiro módulo e ainda falhar ao importar uma dependência dele. + +## 21. `ImportError` é a exceção mais ampla relacionada a imports + +Um módulo pode existir enquanto um nome solicitado não existe: + +```python +from math import name_that_does_not_exist +``` + +Isso levanta `ImportError` porque `math` está disponível, mas o nome importado solicitado não está. + +Não capture `ImportError` em volta de um bloco grande apenas para fazer falhas desaparecerem. Capture exceções de importação somente quando o programa tiver uma política deliberada, como uma dependência realmente opcional com fallback documentado. + +## 22. Um pacote organiza módulos sob um namespace pontuado + +Pacotes permitem que módulos relacionados usem nomes hierárquicos como: + +```text +study_tools.formatting +study_tools.validation +study_tools.reports +``` + +Um pacote pode conter módulos e subpacotes. + +No modelo completo de importação do Python, um pacote é um tipo especial de módulo capaz de conter submódulos. A analogia com diretórios é útil em projetos comuns de código-fonte, mas o modelo da linguagem é baseado em objetos de módulo/pacote, não apenas em pastas. + +## 23. Um pacote regular normalmente usa `__init__.py` + +Um pacote regular simples pode ter: + +```text +study_tools/ +├── __init__.py +├── formatting.py +└── validation.py +``` + +A presença de `__init__.py` torna esse diretório um pacote regular no layout convencional de sistema de arquivos. + +`__init__.py` pode estar vazio. Ele também pode definir comportamento de inicialização ou expor deliberadamente nomes selecionados no nível do pacote. + +## 24. Namespace packages são uma exceção avançada à regra de `__init__.py` + +Python moderno também suporta **namespace packages**, que podem existir sem `__init__.py` e podem abranger vários locais. + +Portanto, esta afirmação é ampla demais: + +```text +"Todo pacote Python precisa ter __init__.py." +``` + +Para projetos de iniciantes, pacotes regulares com `__init__.py` costumam ser o ponto de partida mais claro. Namespace packages podem esperar até que um projeto realmente precise desse modelo. + +## 25. `__init__.py` é código, então mantenha seu comportamento deliberado + +Isto é válido: + +```python +from .formatting import build_label + +__all__ = ["build_label"] +``` + +Agora o pacote pode fornecer intencionalmente um nome público conveniente: + +```python +from study_tools import build_label +``` + +Mas um `__init__.py` grande, cheio de configuração cara e imports surpreendentes, pode tornar o comportamento do pacote mais difícil de entender. + +Trate a inicialização do pacote como parte do design de dependências. + +## 26. Nomes pontuados expressam a hierarquia do pacote + +Este import: + +```python +import study_tools.formatting +``` + +carrega o submódulo usando seu nome pontuado completo. + +Depois você acessa: + +```python +study_tools.formatting.build_label("Modules", 2) +``` + +Outro estilo é: + +```python +from study_tools import formatting + +print(formatting.build_label("Modules", 2)) +``` + +Os dois deixam explícita a relação com o pacote. + +## 27. Importe a interface estável mais estreita que mantenha a intenção clara + +Suponha que um pacote exponha intencionalmente `build_label` a partir de `__init__.py`: + +```python +from study_tools import build_label +``` + +Isso pode ser uma API de pacote limpa. + +Se o pacote não promete esse atalho público, importar o módulo que define o nome pode ser mais honesto: + +```python +from study_tools.formatting import build_label +``` + +A melhor escolha depende da interface documentada pelo pacote, não de quantos caracteres o import economiza. + +## 28. Um pacote de importação não é a mesma coisa que uma distribuição + +A palavra **pacote** é sobrecarregada em conversas sobre Python. + +Um **pacote de importação** faz parte do namespace de módulos do Python, como: + +```text +study_tools +``` + +Uma **distribuição** é algo instalado e gerenciado por ferramentas de empacotamento e pode fornecer um ou mais pacotes de importação ou módulos. + +O nome de instalação e o nome de importação podem até ser diferentes. + +Este capítulo ensina pacotes de importação. Empacotamento e publicação de distribuições são assuntos separados. + +## 29. Imports absolutos nomeiam explicitamente o caminho do pacote + +Dentro de um pacote de projeto, um import absoluto pode ser: + +```python +from study_tools.formatting import build_label +``` + +Ele nomeia o pacote a partir do namespace de importação de nível superior. + +Imports absolutos costumam ser fáceis de pesquisar e entender porque o caminho da dependência fica explícito. + +## 30. Imports relativos usam pontos iniciais dentro de pacotes + +Um módulo dentro de `study_tools` pode importar um vizinho com: + +```python +from .formatting import build_label +``` + +Um ponto inicial se refere ao pacote atual. Pontos adicionais podem se referir a níveis de pacote pai. + +Imports relativos são úteis para relações internas de um pacote, mas dependem de Python conhecer o contexto de pacote do módulo. + +## 31. Imports relativos não são baseados no diretório de trabalho atual + +Essa distinção é importante. + +Um import relativo como: + +```python +from .formatting import build_label +``` + +é resolvido a partir das informações de pacote do módulo atual, não caminhando a partir de qualquer diretório em que o terminal esteja. + +É por isso que "estou na pasta certa" não é uma explicação completa para dizer se um import relativo vai funcionar. + +## 32. Executar diretamente um módulo de pacote pode remover o contexto de pacote que ele espera + +Suponha que um módulo contenha um import relativo e tenha sido criado para viver dentro de um pacote. + +Executá-lo pelo caminho do arquivo: + +```text +python study_tools/cli.py +``` + +pode executá-lo como o módulo de nível superior `__main__`, e não como `study_tools.cli`. O import relativo pode então falhar porque o pacote pai esperado não é conhecido. + +Quando o módulo foi projetado para rodar no contexto do pacote, `python -m` costuma ser a ferramenta correta. + +## 33. `python -m` localiza um módulo pelo sistema de importação e o executa + +Por exemplo: + +```text +python -m study_tools.cli +``` + +Python localiza `study_tools.cli` usando o mecanismo padrão de importação e executa seu conteúdo como o módulo `__main__`. + +Isso preserva o fato de que o código pertence ao pacote `study_tools` enquanto ainda o transforma no ponto de entrada do programa. + +O comando usa um **nome de módulo**, não um nome de arquivo `.py`. + +## 34. Um pacote pode definir `__main__.py` para `python -m package_name` + +Se um pacote contém: + +```text +study_tools/ +├── __init__.py +├── __main__.py +└── formatting.py +``` + +então: + +```text +python -m study_tools +``` + +executa `study_tools.__main__` como o módulo principal. + +Isso é útil quando o próprio pacote possui comportamento de entrada por linha de comando. Um pacote não ganha esse comportamento apenas porque `__init__.py` existe. + +## 35. Imports tornam dependências visíveis + +Se `reports.py` importa `formatting.py`, então `reports` depende de `formatting`. + +Um desenho útil das dependências é: + +```text +cli + ↓ +reports + ↓ +formatting +``` + +Manter a direção das dependências compreensível ajuda a evitar módulos emaranhados em que tudo importa todo o resto. + +## 36. Imports circulares muitas vezes são um sinal de design + +Uma relação circular simples é: + +```text +module_a importa module_b + ↑ ↓ + └─────────┘ +``` + +Python pode encontrar um módulo enquanto ele ainda está apenas parcialmente inicializado, produzindo erros de nomes ausentes ou comportamento confuso. + +Correções comuns de design incluem: + +- mover definições compartilhadas para um terceiro módulo; +- passar valores ou callables como parâmetros em vez de importar de volta para cima; +- esclarecer qual módulo é dono de uma responsabilidade; +- reduzir trabalho no nível superior que dependa do outro módulo estar totalmente inicializado. + +Mover um import para dentro de uma função às vezes pode quebrar o ciclo, mas também pode apenas esconder o problema arquitetural. Entenda a dependência antes de aplicar esse contorno. + +## 37. Imports dentro de funções são permitidos, mas imports no nível superior são o padrão legível mais comum + +Isto é Python válido: + +```python +def calculate_root(value: float) -> float: + import math + + return math.sqrt(value) +``` + +A maioria das dependências comuns fica mais fácil de ver quando os imports aparecem próximos ao topo do módulo. + +Imports locais podem ser deliberados para dependências opcionais, carregamento adiado ou ciclos bem compreendidos. Use-os por uma razão, não por reflexo. + +## 38. Evite imports com curinga em módulos comuns + +Esta sintaxe existe: + +```python +from math import * +``` + +mas torna o namespace local menos explícito. Quem lê precisa saber quais nomes a origem exporta, e novos nomes exportados podem criar colisões. + +Prefira imports explícitos: + +```python +from math import pi, sqrt +``` + +`__all__` pode influenciar o que um import com curinga expõe, mas não transforma wildcard imports no padrão mais claro para código de aplicação. + +## 39. Agrupe imports para melhorar a legibilidade + +Uma organização comum e legível é: + +```python +import csv +import json + +from study_tools import build_label +``` + +A convenção da PEP 8 separa imports da biblioteca padrão, de terceiros e locais da aplicação quando esses grupos existem. + +O objetivo mais profundo é visibilidade: quem lê deve conseguir entender as principais dependências de um módulo sem caçar pelo código não relacionado. + +## 40. Exemplo prático: importar a biblioteca padrão + +```python +import math + + +number = 81 +root = math.sqrt(number) + +print(f"Square root: {root}") +``` + +Saída: + +```text +Square root: 9.0 +``` + +Versão executável: [`examples/import_standard_library.py`](examples/import_standard_library.py). + +## 41. Exemplo prático: importar seu próprio módulo + +Módulo auxiliar `grade_tools.py`: + +```python +def classify_score(score: int) -> str: + if score >= 80: + return "ready" + return "review" +``` + +Módulo executável `module_demo.py`: + +```python +import grade_tools + + +score = 84 +status = grade_tools.classify_score(score) + +print(f"Score {score}: {status}") +``` + +Saída: + +```text +Score 84: ready +``` + +Versão executável: [`examples/module_demo.py`](examples/module_demo.py). Módulo de apoio: [`examples/grade_tools.py`](examples/grade_tools.py). + +## 42. Exemplo prático: importar de um pacote regular + +Layout do pacote: + +```text +examples/ +├── package_demo.py +└── study_tools/ + ├── __init__.py + └── formatting.py +``` + +`formatting.py` define a função reutilizável: + +```python +def build_label(topic: str, level: int) -> str: + return f"{topic} | level {level}" +``` + +`__init__.py` a expõe intencionalmente no nível do pacote: + +```python +from .formatting import build_label + +__all__ = ["build_label"] +``` + +O arquivo executável importa a API do pacote: + +```python +from study_tools import build_label + + +print(build_label("Modules", 2)) +``` + +Saída: + +```text +Modules | level 2 +``` + +Versão executável: [`examples/package_demo.py`](examples/package_demo.py). Pacote de apoio: [`examples/study_tools/`](examples/study_tools/). + +## 43. Exemplo prático: main guard + +```python +def main() -> None: + print("Main guard executed") + + +if __name__ == "__main__": + main() +``` + +Saída quando executado diretamente: + +```text +Main guard executed +``` + +Versão executável: [`examples/main_guard.py`](examples/main_guard.py). + +## 44. Erro comum: nomear um arquivo como uma dependência + +Arquivos como estes podem criar sombreamentos confusos: + +```text +json.py +csv.py +math.py +random.py +``` + +se o mesmo projeto também espera os módulos da biblioteca padrão com esses nomes. + +Escolha nomes de módulos que representem sua própria responsabilidade e que não colidam com dependências importadas. + +## 45. Erro comum: esconder a inicialização da aplicação dentro de um import + +Evite transformar isto em arquitetura da aplicação: + +```text +import app + ↓ +app lê arquivos, conecta serviços e inicia loops imediatamente +``` + +Prefira um ponto de entrada explícito: + +```text +importar definições + ↓ +main() inicia deliberadamente o comportamento da aplicação +``` + +Uma inicialização explícita é mais fácil de testar, reutilizar e compreender. + +## 46. Erro comum: assumir que execução por arquivo e execução por módulo são idênticas + +Estes comandos podem criar contextos de import diferentes: + +```text +python path/to/tool.py +python -m package.tool +``` + +Os dois executam código Python, mas `-m` localiza um módulo nomeado pelo sistema de importação e o executa como `__main__`. + +A diferença importa especialmente para pacotes e imports relativos. + +## 47. Erro comum: usar pacotes apenas para criar árvores profundas de pastas + +Isto não é automaticamente um bom design: + +```text +app/core/services/helpers/utils/common/ +``` + +Uma hierarquia de pacotes deve comunicar namespaces e responsabilidades significativas. + +Mais níveis adicionam mais caminhos de importação, navegação e fronteiras para entender. Crie níveis que justifiquem sua complexidade. + +## 48. Um projeto pequeno pode crescer por etapas + +Comece simples: + +```text +app.py +``` + +Depois extraia uma responsabilidade realmente reutilizável: + +```text +app.py +grade_tools.py +``` + +Depois agrupe módulos relacionados quando o namespace se tornar útil: + +```text +app.py +study_tools/ +├── __init__.py +├── grades.py +└── formatting.py +``` + +A estrutura deve seguir as responsabilidades, não o desejo de parecer "enterprise" antes de o programa precisar disso. + +## 49. Exercício + +Crie uma pequena aplicação de estudos baseada em pacote com esta estrutura: + +```text +study_app/ +├── __init__.py +├── grading.py +└── formatting.py +run_study_app.py +``` + +Requisitos: + +1. Em `grading.py`, crie `classify_score(score: int) -> str`, que retorna `"ready"` para notas de pelo menos 80 e `"review"` caso contrário. +2. Em `formatting.py`, crie `format_result(topic: str, status: str) -> str`. +3. Em `study_app/__init__.py`, mantenha a inicialização mínima. Você pode deixá-lo vazio ou expor deliberadamente um nome documentado no nível do pacote. +4. Em `run_study_app.py`, importe explicitamente a funcionalidade do pacote e imprima resultados para pelo menos três tópicos fictícios. +5. Coloque o comportamento executável em uma função `main()`. +6. Chame `main()` apenas sob `if __name__ == "__main__":`. +7. Não altere `sys.path`. +8. Não use `from ... import *`. +9. Renomeie qualquer arquivo que sombreie um módulo da biblioteca padrão que você utiliza. + +Perguntas extras: + +- Quais nomes são vinculados por `import study_app.grading`? +- Como o namespace local seria diferente com `from study_app.grading import classify_score`? +- O que roda quando `study_app.grading` é importado pela primeira vez em uma sessão normal do interpretador? +- O que `__name__` contém no arquivo de entrada executado diretamente? +- Por que um import relativo pode se comportar de forma diferente quando um módulo de pacote é executado pelo caminho do arquivo? +- Quando `python -m package.module` seria preferível? +- Por que `__init__.py` de um pacote regular pode ficar vazio? + +## 50. Checklist de revisão + +Antes de avançar para a fase da biblioteca padrão, confirme que você consegue responder sem adivinhar: + +- O que é um módulo em um projeto comum baseado em arquivos `.py`? +- Qual nome `import grade_tools` vincula? +- O que muda com `from grade_tools import classify_score`? +- O que um alias com `as` muda? +- Código no nível superior pode rodar durante um import? +- Qual é o papel introdutório de `sys.modules`? +- Qual é o valor de `__name__` quando um arquivo é o programa de nível superior? +- Qual problema o main guard resolve? +- O que `sys.path` representa? +- Por que nomear seu arquivo `json.py` pode causar problemas? +- Como `ModuleNotFoundError` e `ImportError` se relacionam? +- O que torna reconhecível um pacote regular baseado em diretório no layout convencional? +- Namespace packages precisam conter `__init__.py`? +- O que pontos iniciais significam em um import relativo? +- Por que `python -m package.module` pode ser útil? +- Qual é a diferença entre pacote de importação e distribuição? +- Por que wildcard imports normalmente são evitados? +- O que imports circulares podem revelar sobre o design dos módulos? + +## 51. Consulta rápida + +| Necessidade | Padrão ou ideia | +|---|---| +| Importar um módulo | `import module_name` | +| Acessar um nome do módulo | `module_name.item` | +| Importar nome selecionado | `from module_name import item` | +| Dar alias a um módulo | `import module_name as alias` | +| Dar alias a um nome selecionado | `from module_name import item as alias` | +| Guard de entrada direta | `if __name__ == "__main__":` | +| Locais de busca de módulos | inspecionar `sys.path` | +| Cache normal de imports | `sys.modules` | +| Módulo solicitado ausente | normalmente `ModuleNotFoundError` | +| Falha de import mais ampla | `ImportError` | +| Marcador convencional de pacote regular | `__init__.py` | +| Importar submódulo de pacote | `import package.submodule` | +| Import absoluto de pacote | `from package.module import item` | +| Import relativo de módulo vizinho | `from .module import item` | +| Executar módulo pelo nome de import | `python -m package.module` | +| Executar entrada do pacote | `python -m package` com `package/__main__.py` | +| Evitar namespace escondido | preferir nomes explícitos a `import *` | +| Evitar cirurgia casual de caminhos | não usar mutação de `sys.path` como estrutura normal | + +Um modelo útil de dependências é: + +```text +ponto de entrada + ↓ importa +módulos coordenadores + ↓ importam +módulos reutilizáveis focados +``` + +Busque uma direção de dependências que o estudante consiga desenhar sem formar um nó. + +## Fase 7 concluída + +Este capítulo encerra a **Fase 7: Erros, Arquivos e Módulos**. + +A fase agora conecta tratamento de falhas, fronteiras de persistência, dados textuais estruturados e organização do código: + +```text +exceções + ↓ +sinalização deliberada de exceções + ↓ +tempo de vida seguro de arquivos + ↓ +fronteiras de dados TXT / CSV / JSON + ↓ +imports / módulos / pacotes +``` + +Agora você consegue criar um pequeno programa que falha deliberadamente quando um contrato é violado, trata falhas externas esperadas, persiste dados textuais com segurança, interpreta formatos comuns e separa código reutilizável entre módulos e pacotes. + +## O que vem depois + +A **Fase 8: Biblioteca Padrão** aproveitará o modelo de importação para explorar ferramentas úteis que acompanham o Python, começando por módulos como `pathlib` e `datetime` de acordo com o roadmap do projeto. + +A transição importante é: + +```text +aprender como imports organizam dependências + ↓ +usar deliberadamente módulos da biblioteca padrão do Python +``` + +## Referências oficiais + +- Tutorial do Python 3.14, Modules: +- Referência da linguagem Python 3.14, The import system: +- Referência da linguagem Python 3.14, The import statement: +- Documentação de linha de comando do Python 3.14, `-m`: +- Documentação do Python 3.14 sobre `__main__`: \ No newline at end of file diff --git a/errors-files-and-modules/05-imports-modules-and-packages/examples/grade_tools.py b/errors-files-and-modules/05-imports-modules-and-packages/examples/grade_tools.py new file mode 100644 index 0000000..7e2dceb --- /dev/null +++ b/errors-files-and-modules/05-imports-modules-and-packages/examples/grade_tools.py @@ -0,0 +1,4 @@ +def classify_score(score: int) -> str: + if score >= 80: + return "ready" + return "review" diff --git a/errors-files-and-modules/05-imports-modules-and-packages/examples/import_standard_library.py b/errors-files-and-modules/05-imports-modules-and-packages/examples/import_standard_library.py new file mode 100644 index 0000000..3841a0b --- /dev/null +++ b/errors-files-and-modules/05-imports-modules-and-packages/examples/import_standard_library.py @@ -0,0 +1,7 @@ +import math + + +number = 81 +root = math.sqrt(number) + +print(f"Square root: {root}") diff --git a/errors-files-and-modules/05-imports-modules-and-packages/examples/main_guard.py b/errors-files-and-modules/05-imports-modules-and-packages/examples/main_guard.py new file mode 100644 index 0000000..5eade4a --- /dev/null +++ b/errors-files-and-modules/05-imports-modules-and-packages/examples/main_guard.py @@ -0,0 +1,6 @@ +def main() -> None: + print("Main guard executed") + + +if __name__ == "__main__": + main() diff --git a/errors-files-and-modules/05-imports-modules-and-packages/examples/module_demo.py b/errors-files-and-modules/05-imports-modules-and-packages/examples/module_demo.py new file mode 100644 index 0000000..b6d8338 --- /dev/null +++ b/errors-files-and-modules/05-imports-modules-and-packages/examples/module_demo.py @@ -0,0 +1,7 @@ +import grade_tools + + +score = 84 +status = grade_tools.classify_score(score) + +print(f"Score {score}: {status}") diff --git a/errors-files-and-modules/05-imports-modules-and-packages/examples/package_demo.py b/errors-files-and-modules/05-imports-modules-and-packages/examples/package_demo.py new file mode 100644 index 0000000..c2efe2d --- /dev/null +++ b/errors-files-and-modules/05-imports-modules-and-packages/examples/package_demo.py @@ -0,0 +1,4 @@ +from study_tools import build_label + + +print(build_label("Modules", 2)) diff --git a/errors-files-and-modules/05-imports-modules-and-packages/examples/study_tools/__init__.py b/errors-files-and-modules/05-imports-modules-and-packages/examples/study_tools/__init__.py new file mode 100644 index 0000000..546ef8c --- /dev/null +++ b/errors-files-and-modules/05-imports-modules-and-packages/examples/study_tools/__init__.py @@ -0,0 +1,3 @@ +from .formatting import build_label + +__all__ = ["build_label"] diff --git a/errors-files-and-modules/05-imports-modules-and-packages/examples/study_tools/formatting.py b/errors-files-and-modules/05-imports-modules-and-packages/examples/study_tools/formatting.py new file mode 100644 index 0000000..cf96a38 --- /dev/null +++ b/errors-files-and-modules/05-imports-modules-and-packages/examples/study_tools/formatting.py @@ -0,0 +1,2 @@ +def build_label(topic: str, level: int) -> str: + return f"{topic} | level {level}" diff --git a/errors-files-and-modules/README.es.md b/errors-files-and-modules/README.es.md index 76ff397..e7582dd 100644 --- a/errors-files-and-modules/README.es.md +++ b/errors-files-and-modules/README.es.md @@ -18,7 +18,7 @@ La Fase 7 comienza con el manejo de excepciones, continúa con la generación de | [02. Lanzar Excepciones y Excepciones Personalizadas](02-raise-and-custom-exceptions/README.es.md) | Señalar estados inválidos deliberadamente con `raise`, volver a lanzar o encadenar fallos de forma intencional e introducir excepciones personalizadas simples | Intermedio | Disponible | | [03. `open()` y `with`](03-open-and-with/README.es.md) | Abrir, leer, escribir y añadir a archivos de texto gestionando recursos de forma segura con `with` | Principiante a intermedio | Disponible | | [04. TXT, CSV y JSON](04-txt-csv-and-json/README.es.md) | Analizar, escribir, convertir y validar formatos comunes de datos textuales con herramientas específicas del formato | Intermedio | Disponible | -| 05. Imports, Módulos y Paquetes | Dividir código en archivos reutilizables y comprender el modelo de importación de Python | Intermedio | Planificado | +| [05. Imports, Módulos y Paquetes](05-imports-modules-and-packages/README.es.md) | Dividir código en archivos reutilizables, organizar paquetes regulares y comprender el contexto de importación y ejecución de Python | Intermedio | Disponible | ## Orientación de prerrequisitos @@ -65,11 +65,11 @@ Al final de la Fase 7, deberías poder: - importar código desde módulos y paquetes; - explicar cómo archivos, excepciones, funciones y módulos se conectan en un pequeño programa real. -## Capítulo actual +## Estado de la fase -Continúa con [Trabajar con TXT, CSV y JSON](04-txt-csv-and-json/README.es.md). +La Fase 7 está completada. Termina la sección con [Organizar Código con Imports, Módulos y Paquetes](05-imports-modules-and-packages/README.es.md). -Los Capítulos 01–02 establecen manejo y señalización deliberada de excepciones. El Capítulo 03 añade un tiempo de vida seguro de archivos e I/O de texto. El Capítulo 04 añade contratos TXT orientados a líneas, readers y writers CSV, serialización y deserialización JSON, conversión explícita de tipos y límites entre parsing y validación. El próximo capítulo planificado es **Imports, Módulos y Paquetes**. +Los Capítulos 01–02 establecen manejo y señalización deliberada de excepciones. El Capítulo 03 añade un tiempo de vida seguro de archivos e I/O de texto. El Capítulo 04 añade límites de datos TXT, CSV y JSON. El Capítulo 05 cierra la fase con imports explícitos, módulos, paquetes regulares, `__name__`, main guard, contexto de búsqueda, imports relativos, `python -m` y diseño de dependencias. ## Estructura del directorio @@ -102,15 +102,28 @@ errors-files-and-modules/ │ ├── append_text.py │ ├── handle_missing_file.py │ └── write_and_read_text.py -└── 04-txt-csv-and-json/ +├── 04-txt-csv-and-json/ +│ ├── README.md +│ ├── README.pt-BR.md +│ ├── README.es.md +│ └── examples/ +│ ├── csv_records.py +│ ├── handle_invalid_json.py +│ ├── json_document.py +│ └── text_records.py +└── 05-imports-modules-and-packages/ ├── README.md ├── README.pt-BR.md ├── README.es.md └── examples/ - ├── csv_records.py - ├── handle_invalid_json.py - ├── json_document.py - └── text_records.py + ├── grade_tools.py + ├── import_standard_library.py + ├── main_guard.py + ├── module_demo.py + ├── package_demo.py + └── study_tools/ + ├── __init__.py + └── formatting.py ``` -Los directorios de capítulos planificados se añaden únicamente cuando su contenido se publica realmente. +Los cinco directorios planificados de la Fase 7 ya están publicados. diff --git a/errors-files-and-modules/README.md b/errors-files-and-modules/README.md index 3c0e7b8..6cd52a5 100644 --- a/errors-files-and-modules/README.md +++ b/errors-files-and-modules/README.md @@ -18,7 +18,7 @@ Phase 7 starts with exception handling, then moves into deliberately raising exc | [02. Raising and Custom Exceptions](02-raise-and-custom-exceptions/README.md) | Signal invalid states deliberately with `raise`, re-raise or chain failures deliberately, and introduce simple custom exceptions | Intermediate | Available | | [03. `open()` and `with`](03-open-and-with/README.md) | Open, read, write, and append text files while managing file resources safely with `with` | Beginner to intermediate | Available | | [04. TXT, CSV, and JSON](04-txt-csv-and-json/README.md) | Parse, write, convert, and validate common text-based data formats with format-aware tools | Intermediate | Available | -| 05. Imports, Modules, and Packages | Split code into reusable files and understand Python's import model | Intermediate | Planned | +| [05. Imports, Modules, and Packages](05-imports-modules-and-packages/README.md) | Split code into reusable files, organize regular packages, and understand Python's import and execution context | Intermediate | Available | ## Prerequisite guidance @@ -65,11 +65,11 @@ By the end of Phase 7, you should be able to: - import code from modules and packages; - explain how files, exceptions, functions, and modules connect in a small real program. -## Current chapter +## Phase status -Continue with [Working with TXT, CSV, and JSON](04-txt-csv-and-json/README.md). +Phase 7 is complete. Finish the section with [Organizing Code with Imports, Modules, and Packages](05-imports-modules-and-packages/README.md). -Chapters 01–02 establish exception handling and deliberate exception signaling. Chapter 03 adds safe text-file lifetime and I/O. Chapter 04 adds line-oriented TXT contracts, CSV readers and writers, JSON serialization and deserialization, explicit type conversion, and parsing-versus-validation boundaries. The next planned chapter is **Imports, Modules, and Packages**. +Chapters 01–02 establish exception handling and deliberate exception signaling. Chapter 03 adds safe text-file lifetime and I/O. Chapter 04 adds TXT, CSV, and JSON data boundaries. Chapter 05 closes the phase with explicit imports, modules, regular packages, `__name__`, the main guard, search context, relative imports, `python -m`, and dependency design. ## Directory structure @@ -102,15 +102,28 @@ errors-files-and-modules/ │ ├── append_text.py │ ├── handle_missing_file.py │ └── write_and_read_text.py -└── 04-txt-csv-and-json/ +├── 04-txt-csv-and-json/ +│ ├── README.md +│ ├── README.pt-BR.md +│ ├── README.es.md +│ └── examples/ +│ ├── csv_records.py +│ ├── handle_invalid_json.py +│ ├── json_document.py +│ └── text_records.py +└── 05-imports-modules-and-packages/ ├── README.md ├── README.pt-BR.md ├── README.es.md └── examples/ - ├── csv_records.py - ├── handle_invalid_json.py - ├── json_document.py - └── text_records.py + ├── grade_tools.py + ├── import_standard_library.py + ├── main_guard.py + ├── module_demo.py + ├── package_demo.py + └── study_tools/ + ├── __init__.py + └── formatting.py ``` -Planned chapter directories are added only when their content is actually published. +All five planned Phase 7 chapter directories are now published. diff --git a/errors-files-and-modules/README.pt-BR.md b/errors-files-and-modules/README.pt-BR.md index a172171..d285a70 100644 --- a/errors-files-and-modules/README.pt-BR.md +++ b/errors-files-and-modules/README.pt-BR.md @@ -18,7 +18,7 @@ A Fase 7 começa com tratamento de exceções, avança para a criação delibera | [02. Levantando Exceções e Exceções Personalizadas](02-raise-and-custom-exceptions/README.pt-BR.md) | Sinalizar estados inválidos deliberadamente com `raise`, relançar ou encadear falhas de forma intencional e introduzir exceções personalizadas simples | Intermediário | Disponível | | [03. `open()` e `with`](03-open-and-with/README.pt-BR.md) | Abrir, ler, escrever e acrescentar em arquivos de texto gerenciando recursos com segurança usando `with` | Iniciante a intermediário | Disponível | | [04. TXT, CSV e JSON](04-txt-csv-and-json/README.pt-BR.md) | Interpretar, escrever, converter e validar formatos comuns de dados textuais com ferramentas específicas do formato | Intermediário | Disponível | -| 05. Imports, Módulos e Pacotes | Dividir código em arquivos reutilizáveis e entender o modelo de importação do Python | Intermediário | Planejado | +| [05. Imports, Módulos e Pacotes](05-imports-modules-and-packages/README.pt-BR.md) | Dividir código em arquivos reutilizáveis, organizar pacotes regulares e entender o contexto de importação e execução do Python | Intermediário | Disponível | ## Orientação de pré-requisitos @@ -65,11 +65,11 @@ Ao final da Fase 7, você deverá conseguir: - importar código de módulos e pacotes; - explicar como arquivos, exceções, funções e módulos se conectam em um pequeno programa real. -## Capítulo atual +## Status da fase -Continue com [Trabalhando com TXT, CSV e JSON](04-txt-csv-and-json/README.pt-BR.md). +A Fase 7 está concluída. Encerre a seção com [Organizando Código com Imports, Módulos e Pacotes](05-imports-modules-and-packages/README.pt-BR.md). -Os Capítulos 01–02 estabelecem tratamento e sinalização deliberada de exceções. O Capítulo 03 adiciona tempo de vida seguro de arquivos e I/O de texto. O Capítulo 04 acrescenta contratos TXT orientados por linhas, readers e writers CSV, serialização e desserialização JSON, conversão explícita de tipos e fronteiras entre parsing e validação. O próximo capítulo planejado é **Imports, Módulos e Pacotes**. +Os Capítulos 01–02 estabelecem tratamento e sinalização deliberada de exceções. O Capítulo 03 adiciona tempo de vida seguro de arquivos e I/O de texto. O Capítulo 04 adiciona fronteiras de dados TXT, CSV e JSON. O Capítulo 05 encerra a fase com imports explícitos, módulos, pacotes regulares, `__name__`, main guard, contexto de busca, imports relativos, `python -m` e design de dependências. ## Estrutura do diretório @@ -102,15 +102,28 @@ errors-files-and-modules/ │ ├── append_text.py │ ├── handle_missing_file.py │ └── write_and_read_text.py -└── 04-txt-csv-and-json/ +├── 04-txt-csv-and-json/ +│ ├── README.md +│ ├── README.pt-BR.md +│ ├── README.es.md +│ └── examples/ +│ ├── csv_records.py +│ ├── handle_invalid_json.py +│ ├── json_document.py +│ └── text_records.py +└── 05-imports-modules-and-packages/ ├── README.md ├── README.pt-BR.md ├── README.es.md └── examples/ - ├── csv_records.py - ├── handle_invalid_json.py - ├── json_document.py - └── text_records.py + ├── grade_tools.py + ├── import_standard_library.py + ├── main_guard.py + ├── module_demo.py + ├── package_demo.py + └── study_tools/ + ├── __init__.py + └── formatting.py ``` -Os diretórios dos capítulos planejados são adicionados somente quando seu conteúdo é realmente publicado. +Todos os cinco diretórios planejados da Fase 7 agora estão publicados. diff --git a/scripts/example_manifest.txt b/scripts/example_manifest.txt index b291c58..4393621 100644 --- a/scripts/example_manifest.txt +++ b/scripts/example_manifest.txt @@ -118,3 +118,7 @@ errors-files-and-modules/04-txt-csv-and-json/examples/csv_records.py errors-files-and-modules/04-txt-csv-and-json/examples/handle_invalid_json.py errors-files-and-modules/04-txt-csv-and-json/examples/json_document.py errors-files-and-modules/04-txt-csv-and-json/examples/text_records.py +errors-files-and-modules/05-imports-modules-and-packages/examples/import_standard_library.py +errors-files-and-modules/05-imports-modules-and-packages/examples/main_guard.py +errors-files-and-modules/05-imports-modules-and-packages/examples/module_demo.py +errors-files-and-modules/05-imports-modules-and-packages/examples/package_demo.py