From fdddd20c9822bd86c165ce2204d38b19e0d6e241 Mon Sep 17 00:00:00 2001 From: Ramon Rodriguez Date: Thu, 27 Aug 2026 21:15:54 -0300 Subject: [PATCH] Add pathlib chapter --- README.md | 4 +- docs/learning-path.en.md | 8 +- docs/learning-path.es.md | 8 +- docs/learning-path.pt-BR.md | 8 +- docs/localized/README.es.md | 4 +- docs/localized/README.pt-BR.md | 4 +- docs/project-structure.en.md | 14 +- docs/project-structure.es.md | 14 +- docs/project-structure.pt-BR.md | 14 +- docs/roadmap.en.md | 26 +- docs/roadmap.es.md | 26 +- docs/roadmap.pt-BR.md | 26 +- scripts/example_manifest.txt | 4 + standard-library/01-pathlib/README.es.md | 767 +++++++++++++++++ standard-library/01-pathlib/README.md | 771 ++++++++++++++++++ standard-library/01-pathlib/README.pt-BR.md | 767 +++++++++++++++++ .../examples/discover_python_files.py | 16 + .../01-pathlib/examples/inspect_paths.py | 12 + .../01-pathlib/examples/path_parts.py | 10 + .../01-pathlib/examples/text_workspace.py | 13 + standard-library/README.es.md | 101 +++ standard-library/README.md | 100 ++- standard-library/README.pt-BR.md | 101 +++ 23 files changed, 2768 insertions(+), 50 deletions(-) create mode 100644 standard-library/01-pathlib/README.es.md create mode 100644 standard-library/01-pathlib/README.md create mode 100644 standard-library/01-pathlib/README.pt-BR.md create mode 100644 standard-library/01-pathlib/examples/discover_python_files.py create mode 100644 standard-library/01-pathlib/examples/inspect_paths.py create mode 100644 standard-library/01-pathlib/examples/path_parts.py create mode 100644 standard-library/01-pathlib/examples/text_workspace.py create mode 100644 standard-library/README.es.md create mode 100644 standard-library/README.pt-BR.md diff --git a/README.md b/README.md index a1c3efd..8411c33 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 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: +The project foundation and seven complete educational sections are available, and [Phase 8: Standard Library](standard-library/README.md) is now in progress with [Chapter 01: `pathlib`](standard-library/01-pathlib/README.md). [Phase 7: Errors, Files, and Modules](errors-files-and-modules/README.md) is complete with five reviewed chapters. [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 seven complete educational sections are available. [P - [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, 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. +Phases 1, 2, 3, 4, 5, 6, and 7 are complete. Phase 8 is in progress with [Working with Filesystem Paths Using `pathlib`](standard-library/01-pathlib/README.md), which introduces path objects, portable composition, path inspection, filesystem queries, directory traversal, globbing, text helpers, and the boundary between state checks and operation failures. 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 211a636..cd9e3c0 100644 --- a/docs/learning-path.en.md +++ b/docs/learning-path.en.md @@ -99,9 +99,13 @@ This phase is already available and is the next recommended phase after Function 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 ⏳ +## Phase 8 · Standard Library 🚧 -Planned. Direct chapter links will appear here when the phase begins. +[Open the Standard Library section index](../standard-library/README.md) + +1. [Working with Filesystem Paths Using `pathlib`](../standard-library/01-pathlib/README.md) + +Phase 8 is in progress. Chapter 01 introduces path objects, portable path composition, filesystem inspection, directory traversal, globbing, text helpers, and safe operation boundaries. The next planned chapter is **`datetime` and Time Calculations**. ## Phase 9 · External Libraries ⏳ diff --git a/docs/learning-path.es.md b/docs/learning-path.es.md index c21266a..057653d 100644 --- a/docs/learning-path.es.md +++ b/docs/learning-path.es.md @@ -99,9 +99,13 @@ Esta fase ya está disponible y es la siguiente fase recomendada después de Fun 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 ⏳ +## Fase 8 · Biblioteca Estándar 🚧 -Planificado. Los enlaces directos a los capítulos aparecerán aquí cuando comience la fase. +[Abrir el índice de la sección Biblioteca Estándar](../standard-library/README.es.md) + +1. [Trabajar con Rutas del Sistema de Archivos Usando `pathlib`](../standard-library/01-pathlib/README.es.md) + +La Fase 8 está en progreso. El Capítulo 01 introduce objetos de ruta, composición portable, inspección del filesystem, recorrido de directorios, globbing, helpers de texto y límites seguros de operación. El próximo capítulo planificado es **`datetime` y Cálculos de Tiempo**. ## Fase 9 · Bibliotecas Externas ⏳ diff --git a/docs/learning-path.pt-BR.md b/docs/learning-path.pt-BR.md index 13bf58b..7b7ecf4 100644 --- a/docs/learning-path.pt-BR.md +++ b/docs/learning-path.pt-BR.md @@ -99,9 +99,13 @@ Esta fase já está disponível e é a próxima fase recomendada depois de Funç 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 ⏳ +## Fase 8 · Biblioteca Padrão 🚧 -Planejado. Os links diretos dos capítulos aparecerão aqui quando a fase começar. +[Abrir o índice da seção Biblioteca Padrão](../standard-library/README.pt-BR.md) + +1. [Trabalhando com Caminhos do Sistema de Arquivos Usando `pathlib`](../standard-library/01-pathlib/README.pt-BR.md) + +A Fase 8 está em andamento. O Capítulo 01 introduz objetos de caminho, composição portável, inspeção do filesystem, percurso de diretórios, globbing, helpers de texto e fronteiras seguras de operação. O próximo capítulo planejado é **`datetime` e Cálculos de Tempo**. ## Fase 9 · Bibliotecas Externas ⏳ diff --git a/docs/localized/README.es.md b/docs/localized/README.es.md index 7f9eb2c..275d345 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 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: +La base del proyecto y siete secciones educativas completas están disponibles, y la [Fase 8: Biblioteca Estándar](../../standard-library/README.es.md) está ahora en progreso con el [Capítulo 01: `pathlib`](../../standard-library/01-pathlib/README.es.md). La [Fase 7: Errores, Archivos y Módulos](../../errors-files-and-modules/README.es.md) está completada con cinco capítulos revisados. 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 siete secciones educativas completas están disponibles. - [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, 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. +Las Fases 1, 2, 3, 4, 5, 6 y 7 están completadas. La Fase 8 está en progreso con [Trabajar con Rutas del Sistema de Archivos Usando `pathlib`](../../standard-library/01-pathlib/README.es.md), que introduce objetos de ruta, composición portable, inspección de rutas, consultas al filesystem, recorrido de directorios, globbing, helpers de texto y el límite entre comprobaciones de estado y fallos de operación. 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 e664664..f1a4f01 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 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: +A fundação do projeto e sete seções educacionais completas estão disponíveis, e a [Fase 8: Biblioteca Padrão](../../standard-library/README.pt-BR.md) agora está em andamento com o [Capítulo 01: `pathlib`](../../standard-library/01-pathlib/README.pt-BR.md). A [Fase 7: Erros, Arquivos e Módulos](../../errors-files-and-modules/README.pt-BR.md) está concluída com cinco capítulos revisados. 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 sete 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, 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. +As Fases 1, 2, 3, 4, 5, 6 e 7 estão concluídas. A Fase 8 está em andamento com [Trabalhando com Caminhos do Sistema de Arquivos Usando `pathlib`](../../standard-library/01-pathlib/README.pt-BR.md), que introduz objetos de caminho, composição portável, inspeção de caminhos, consultas ao filesystem, percurso de diretórios, globbing, helpers de texto e a fronteira entre verificações de estado e falhas de operação. 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 1b532ac..eb68f84 100644 --- a/docs/project-structure.en.md +++ b/docs/project-structure.en.md @@ -385,6 +385,18 @@ python-study-guide/ │ ├── run_examples.py │ └── validate_repository_structure.py ├── standard-library/ +│ ├── README.md +│ ├── README.pt-BR.md +│ ├── README.es.md +│ └── 01-pathlib/ +│ ├── README.md +│ ├── README.pt-BR.md +│ ├── README.es.md +│ └── examples/ +│ ├── discover_python_files.py +│ ├── inspect_paths.py +│ ├── path_parts.py +│ └── text_workspace.py ├── strings-and-numbers/ │ ├── README.md │ ├── README.pt-BR.md @@ -446,7 +458,7 @@ python-study-guide/ - `practical-projects/`: future small projects combining several concepts. - `program-flow/`: complete Phase 4 learning path. Chapters 01–08 teach conditions, comparisons, truth-value testing, membership, identity, Boolean logic, conditional branching with `if`, `elif`, and `else`, structural pattern matching, iterable-driven repetition with `for`, numeric progressions with `range()`, position-aware iteration with `enumerate()`, parallel iteration with `zip()` including explicit equal-length validation with `strict=True`, state-driven repetition with `while`, deliberate loop control with `break`, `continue`, and loop `else`, and how to choose and combine program-flow tools according to intent, in English, Brazilian Portuguese, and Spanish with deterministic executable examples. - `scripts/`: dependency-free maintenance tools used locally and by GitHub Actions. -- `standard-library/`: future guides to modules distributed with Python. +- `standard-library/`: in-progress Phase 8 learning path. Chapter 01 teaches `pathlib` path objects, portable composition, structural inspection, filesystem queries, text helpers, directory traversal, globbing, resolution, and exception-aware operation boundaries in English, Brazilian Portuguese, and Spanish with deterministic executable examples. - `strings-and-numbers/`: complete Phase 2 learning path. Its four reviewed chapters cover string creation and indexing, common string methods, integer, floating-point, and Boolean behavior, floating-point precision, and `round()`, `abs()`, `min()`, `max()`, and `sum()` in English, Brazilian Portuguese, and Spanish with safe executable examples. - `tests/`: regression tests for repository quality tools and later educational code. diff --git a/docs/project-structure.es.md b/docs/project-structure.es.md index a60d2fe..c37a75d 100644 --- a/docs/project-structure.es.md +++ b/docs/project-structure.es.md @@ -385,6 +385,18 @@ python-study-guide/ │ ├── run_examples.py │ └── validate_repository_structure.py ├── standard-library/ +│ ├── README.md +│ ├── README.pt-BR.md +│ ├── README.es.md +│ └── 01-pathlib/ +│ ├── README.md +│ ├── README.pt-BR.md +│ ├── README.es.md +│ └── examples/ +│ ├── discover_python_files.py +│ ├── inspect_paths.py +│ ├── path_parts.py +│ └── text_workspace.py ├── strings-and-numbers/ │ ├── README.md │ ├── README.pt-BR.md @@ -446,7 +458,7 @@ python-study-guide/ - `practical-projects/`: futuros proyectos pequeños que combinarán varios conceptos. - `program-flow/`: ruta completa de la Fase 4. Los Capítulos 01–08 enseñan condiciones, comparaciones, pruebas de valor de verdad, pertenencia, identidad, lógica booleana, ramificación condicional con `if`, `elif` y `else`, coincidencia de patrones estructurales, repetición guiada por iterables con `for`, progresiones numéricas con `range()`, iteración con posición usando `enumerate()`, iteración paralela con `zip()` incluida la validación explícita de longitudes iguales con `strict=True`, repetición guiada por estado con `while`, control deliberado de bucles con `break`, `continue` y `else` de bucle y cómo elegir y combinar herramientas de flujo del programa según la intención, en inglés, portugués de Brasil y español, con ejemplos ejecutables determinísticos. - `scripts/`: herramientas de mantenimiento sin dependencias externas utilizadas localmente y por GitHub Actions. -- `standard-library/`: futuras guías sobre módulos distribuidos con Python. +- `standard-library/`: ruta de la Fase 8 en progreso. El Capítulo 01 enseña objetos de ruta con `pathlib`, composición portable, inspección estructural, consultas al filesystem, helpers de texto, recorrido de directorios, globbing, resolución y límites de operación conscientes de excepciones en inglés, portugués de Brasil y español, con ejemplos ejecutables determinísticos. - `strings-and-numbers/`: ruta completa de la Fase 2. Sus cuatro capítulos revisados cubren creación e indexación de strings, métodos comunes, comportamiento de enteros, punto flotante y booleanos, precisión de punto flotante y `round()`, `abs()`, `min()`, `max()` y `sum()` en inglés, portugués de Brasil y español, con ejemplos ejecutables seguros. - `tests/`: pruebas de regresión de las herramientas de calidad y, más adelante, del contenido educativo. diff --git a/docs/project-structure.pt-BR.md b/docs/project-structure.pt-BR.md index 6fada63..b6fdc72 100644 --- a/docs/project-structure.pt-BR.md +++ b/docs/project-structure.pt-BR.md @@ -385,6 +385,18 @@ python-study-guide/ │ ├── run_examples.py │ └── validate_repository_structure.py ├── standard-library/ +│ ├── README.md +│ ├── README.pt-BR.md +│ ├── README.es.md +│ └── 01-pathlib/ +│ ├── README.md +│ ├── README.pt-BR.md +│ ├── README.es.md +│ └── examples/ +│ ├── discover_python_files.py +│ ├── inspect_paths.py +│ ├── path_parts.py +│ └── text_workspace.py ├── strings-and-numbers/ │ ├── README.md │ ├── README.pt-BR.md @@ -446,7 +458,7 @@ python-study-guide/ - `practical-projects/`: futuros projetos pequenos combinando diversos conceitos. - `program-flow/`: trilha completa da Fase 4. Os Capítulos 01–08 ensinam condições, comparações, teste de valor de verdade, pertencimento, identidade, lógica booleana, ramificação condicional com `if`, `elif` e `else`, correspondência de padrões estruturais, repetição guiada por iteráveis com `for`, progressões numéricas com `range()`, iteração com posição usando `enumerate()`, iteração paralela com `zip()` incluindo validação explícita de comprimentos iguais com `strict=True`, repetição guiada por estado com `while`, controle deliberado de loops com `break`, `continue` e `else` de loop e como escolher e combinar ferramentas de fluxo do programa de acordo com a intenção, em inglês, português brasileiro e espanhol, com exemplos executáveis determinísticos. - `scripts/`: ferramentas de manutenção sem dependências externas, utilizadas localmente e pelo GitHub Actions. -- `standard-library/`: futuros guias sobre módulos distribuídos com o Python. +- `standard-library/`: trilha da Fase 8 em andamento. O Capítulo 01 ensina objetos de caminho com `pathlib`, composição portável, inspeção estrutural, consultas ao filesystem, helpers de texto, percurso de diretórios, globbing, resolução e fronteiras de operação conscientes de exceções em inglês, português brasileiro e espanhol, com exemplos executáveis determinísticos. - `strings-and-numbers/`: trilha completa da Fase 2. Seus quatro capítulos revisados cobrem criação e indexação de strings, métodos comuns, comportamento de inteiros, ponto flutuante e booleanos, precisão de ponto flutuante e `round()`, `abs()`, `min()`, `max()` e `sum()` em inglês, português brasileiro e espanhol, com exemplos executáveis seguros. - `tests/`: testes de regressão das ferramentas de qualidade e, futuramente, do conteúdo educacional. diff --git a/docs/roadmap.en.md b/docs/roadmap.en.md index b46be99..1828985 100644 --- a/docs/roadmap.en.md +++ b/docs/roadmap.en.md @@ -22,11 +22,11 @@ This roadmap tracks both the educational curriculum and the repository foundatio | 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 | 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 | +| 8. Standard library | In progress | Chapter 01 introduces `pathlib` for path modeling, portable composition, filesystem inspection, directory traversal, globbing, and text-file helpers | | 9. External libraries | Planned | Curriculum not started | | 10. Practical projects | Planned | Curriculum not started | -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. +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 in progress with `pathlib` as its first reviewed chapter. Phase 6 continues to provide the editorial and quality model for later sections. ## Phase 0: Project foundation @@ -138,15 +138,19 @@ Phase 7 is complete. Chapters 01–02 establish exception handling and deliberat ## Phase 8: Standard library -- `pathlib` -- `datetime` -- `json` -- `csv` -- `logging` -- `collections` -- `itertools` -- `decimal` -- `os` and `shutil` +See the [section learning path](../standard-library/README.md). + +- [x] [`pathlib`](../standard-library/01-pathlib/README.md) +- [ ] `datetime` +- [ ] `json` +- [ ] `csv` +- [ ] `logging` +- [ ] `collections` +- [ ] `itertools` +- [ ] `decimal` +- [ ] `os` and `shutil` + +Phase 8 is in progress. Chapter 01 establishes `Path`, pure paths, relative and absolute paths, structural inspection, portable composition, text helpers, directory creation and traversal, globbing, resolution, and filesystem exception boundaries. Chapter 02 will continue with `datetime` and time calculations. ## Phase 9: External libraries diff --git a/docs/roadmap.es.md b/docs/roadmap.es.md index 7d2e4de..4edbdd6 100644 --- a/docs/roadmap.es.md +++ b/docs/roadmap.es.md @@ -22,11 +22,11 @@ Este roadmap acompaña tanto la ruta educativa como la base del repositorio que | 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 | 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 | +| 8. Biblioteca estándar | En progreso | El Capítulo 01 introduce `pathlib` para modelado de rutas, composición portable, inspección del filesystem, recorrido de directorios, globbing y helpers de archivos de texto | | 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, 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. +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 está en progreso con `pathlib` como su primer capítulo revisado. La Fase 6 continúa proporcionando el modelo editorial y de calidad para las secciones posteriores. ## Fase 0: Base del proyecto @@ -138,15 +138,19 @@ La Fase 7 está completada. Los Capítulos 01–02 establecen manejo y señaliza ## Fase 8: Biblioteca estándar -- `pathlib` -- `datetime` -- `json` -- `csv` -- `logging` -- `collections` -- `itertools` -- `decimal` -- `os` y `shutil` +Consulta la [ruta de aprendizaje de la sección](../standard-library/README.es.md). + +- [x] [`pathlib`](../standard-library/01-pathlib/README.es.md) +- [ ] `datetime` +- [ ] `json` +- [ ] `csv` +- [ ] `logging` +- [ ] `collections` +- [ ] `itertools` +- [ ] `decimal` +- [ ] `os` y `shutil` + +La Fase 8 está en progreso. El Capítulo 01 establece `Path`, rutas puras, rutas relativas y absolutas, inspección estructural, composición portable, helpers de texto, creación y recorrido de directorios, globbing, resolución y límites de excepciones del filesystem. El Capítulo 02 continuará con `datetime` y cálculos de tiempo. ## Fase 9: Bibliotecas externas diff --git a/docs/roadmap.pt-BR.md b/docs/roadmap.pt-BR.md index aad8d3a..3e01faa 100644 --- a/docs/roadmap.pt-BR.md +++ b/docs/roadmap.pt-BR.md @@ -22,11 +22,11 @@ Este roadmap acompanha tanto a trilha educacional quanto a fundação do reposit | 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 | 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 | +| 8. Biblioteca padrão | Em andamento | O Capítulo 01 introduz `pathlib` para modelagem de caminhos, composição portável, inspeção do filesystem, percurso de diretórios, globbing e helpers de arquivos de texto | | 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, 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. +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 está em andamento com `pathlib` como seu primeiro capítulo revisado. A Fase 6 continua fornecendo o modelo editorial e de qualidade para as seções posteriores. ## Fase 0: Fundação do projeto @@ -138,15 +138,19 @@ A Fase 7 está concluída. Os Capítulos 01–02 estabelecem tratamento e sinali ## Fase 8: Biblioteca padrão -- `pathlib` -- `datetime` -- `json` -- `csv` -- `logging` -- `collections` -- `itertools` -- `decimal` -- `os` e `shutil` +Consulte a [trilha de aprendizagem da seção](../standard-library/README.pt-BR.md). + +- [x] [`pathlib`](../standard-library/01-pathlib/README.pt-BR.md) +- [ ] `datetime` +- [ ] `json` +- [ ] `csv` +- [ ] `logging` +- [ ] `collections` +- [ ] `itertools` +- [ ] `decimal` +- [ ] `os` e `shutil` + +A Fase 8 está em andamento. O Capítulo 01 estabelece `Path`, caminhos puros, caminhos relativos e absolutos, inspeção estrutural, composição portável, helpers de texto, criação e percurso de diretórios, globbing, resolução e fronteiras de exceções do filesystem. O Capítulo 02 continuará com `datetime` e cálculos de tempo. ## Fase 9: Bibliotecas externas diff --git a/scripts/example_manifest.txt b/scripts/example_manifest.txt index 4393621..b2c02da 100644 --- a/scripts/example_manifest.txt +++ b/scripts/example_manifest.txt @@ -122,3 +122,7 @@ errors-files-and-modules/05-imports-modules-and-packages/examples/import_standar 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 +standard-library/01-pathlib/examples/discover_python_files.py +standard-library/01-pathlib/examples/inspect_paths.py +standard-library/01-pathlib/examples/path_parts.py +standard-library/01-pathlib/examples/text_workspace.py diff --git a/standard-library/01-pathlib/README.es.md b/standard-library/01-pathlib/README.es.md new file mode 100644 index 0000000..846b744 --- /dev/null +++ b/standard-library/01-pathlib/README.es.md @@ -0,0 +1,767 @@ +# Trabajar con Rutas del Sistema de Archivos Usando `pathlib` + +[🇺🇸 English](README.md) · [🇧🇷 Português](README.pt-BR.md) · [🇪🇸 Español](README.es.md) + +`pathlib` es el módulo de la biblioteca estándar para representar y manipular rutas del sistema de archivos como objetos. + +En capítulos anteriores usamos strings como `"notes.txt"` y `"reports/data.csv"` al abrir archivos. Eso funciona, pero las rutas tienen estructura: directorios, nombres, stems, sufijos, padres y separadores dependientes de la plataforma. `pathlib` ofrece una API específica para esa estructura. + +Para la mayoría del trabajo cotidiano, comienza con: + +```python +from pathlib import Path +``` + +Después crea objetos `Path` y combínalos en lugar de concatenar strings manualmente. + +## Objetivos de aprendizaje + +Al final de este capítulo deberías poder: + +- explicar qué representa un objeto `Path`; +- crear rutas relativas y absolutas; +- combinar segmentos con `/`; +- inspeccionar nombres, sufijos, padres y partes; +- usar `Path.cwd()` y `Path.home()` de forma deliberada; +- crear directorios con `mkdir()`; +- leer y escribir texto mediante un objeto de ruta; +- comprobar si una ruta apunta actualmente a un archivo o directorio; +- recorrer directorios con `iterdir()`; +- buscar con `glob()` y `rglob()`; +- transformar nombres con `with_name()` y `with_suffix()`; +- entender por qué una comprobación de existencia no garantiza que una operación posterior tendrá éxito; +- distinguir `Path` de las clases de rutas puras a nivel introductorio; +- evitar separadores de ruta fijos cuando importa la portabilidad. + +## 1. ¿Qué problema resuelve `pathlib`? + +Una ruta es más que texto. + +Considera: + +```text +reports/2026/summary.txt +``` + +Esa ruta contiene varias piezas con significado: + +- `reports` es un segmento de directorio; +- `2026` es otro segmento; +- `summary.txt` es el nombre final; +- `summary` es el stem; +- `.txt` es el sufijo. + +Podrías manipular todo con métodos de strings, pero el código también tendría que comprender separadores y convenciones del sistema operativo. + +`pathlib` coloca el comportamiento de las rutas en objetos específicos para rutas. + +```python +from pathlib import Path + +report_path = Path("reports") / "2026" / "summary.txt" + +print(report_path) +print(report_path.name) +print(report_path.stem) +print(report_path.suffix) +print(report_path.parent) +``` + +El separador mostrado por `print(report_path)` depende del sistema operativo. Ese es precisamente uno de los beneficios: el código expresa la estructura de la ruta sin insertar manualmente `/` o `\\`. + +## 2. `Path` suele ser la clase que necesitas + +El módulo `pathlib` contiene varias clases. + +Para trabajo normal con el sistema de archivos, usa `Path`: + +```python +from pathlib import Path + +config_path = Path("config") / "settings.json" +``` + +`Path` es una clase de ruta concreta. Puede manipular la estructura de la ruta y también realizar operaciones del sistema de archivos, como leer un archivo, crear un directorio o consultar qué existe. + +También existen clases puras como `PurePath`, `PurePosixPath` y `PureWindowsPath`. Las rutas puras manipulan sintaxis de rutas sin tocar el sistema de archivos. + +Normalmente **no** necesitas elegir `PosixPath` o `WindowsPath` directamente. `Path` selecciona la variante concreta apropiada para la plataforma en ejecución. + +## 3. Crear rutas + +Una ruta puede crearse desde un string: + +```python +from pathlib import Path + +file_path = Path("notes.txt") +``` + +También puede crearse con varios segmentos: + +```python +from pathlib import Path + +file_path = Path("reports", "2026", "summary.txt") +``` + +O puedes combinar objetos y segmentos con `/`: + +```python +from pathlib import Path + +reports_dir = Path("reports") +file_path = reports_dir / "2026" / "summary.txt" +``` + +Aquí `/` no realiza una división. `Path` define ese operador como una forma conveniente de unir segmentos. + +Prefiere: + +```python +file_path = Path("reports") / "2026" / "summary.txt" +``` + +en lugar de construir separadores manualmente: + +```python +file_path = "reports/" + "2026/" + "summary.txt" +``` + +La versión con `Path` comunica intención y evita incrustar el separador de una sola plataforma. + +## 4. Rutas relativas y absolutas + +Una **ruta relativa** se interpreta en relación con algún contexto, normalmente el directorio de trabajo actual del proceso. + +```python +from pathlib import Path + +relative_path = Path("reports") / "summary.txt" + +print(relative_path.is_absolute()) +``` + +Una **ruta absoluta** identifica una ubicación desde la raíz o desde el contexto de unidad del sistema de archivos. + +No asumas que una ruta relativa es relativa al archivo `.py`. Normalmente se interpreta desde el directorio de trabajo actual del proceso. + +Esa diferencia explica muchos casos de "el archivo existe, pero Python no lo encuentra". + +## 5. Directorio de trabajo y directorio home + +`Path.cwd()` devuelve el directorio de trabajo actual: + +```python +from pathlib import Path + +current_dir = Path.cwd() +print(current_dir) +``` + +`Path.home()` devuelve el directorio home del usuario actual: + +```python +from pathlib import Path + +home_dir = Path.home() +print(home_dir) +``` + +Usa estos métodos cuando el programa dependa intencionalmente de esas ubicaciones. + +No los utilices solo para hacer que una ruta "parezca absoluta". Primero decide con respecto a qué ubicación debe existir la ruta. + +## 6. Inspeccionar la estructura de una ruta + +`Path` expone componentes comunes como atributos. + +```python +from pathlib import Path + +path = Path("archive") / "report.final.csv" + +print(path.name) +print(path.stem) +print(path.suffix) +print(path.suffixes) +print(path.parent) +print(path.parts) +``` + +Significados habituales: + +| Atributo | Significado | +|---|---| +| `.name` | componente final de la ruta | +| `.stem` | nombre final sin su último sufijo | +| `.suffix` | último sufijo | +| `.suffixes` | lista de sufijos | +| `.parent` | ruta padre lógica | +| `.parents` | secuencia de ancestros lógicos | +| `.parts` | tupla con los componentes | + +El sufijo se basa en la sintaxis de la ruta, no en el contenido real del archivo. Un archivo llamado `table.csv` no necesariamente contiene CSV válido. + +## 7. Transformar nombres sin cirugía de strings + +Usa métodos de rutas cuando la operación se refiera a la estructura de la ruta. + +```python +from pathlib import Path + +source = Path("exports") / "report.csv" + +print(source.with_suffix(".json")) +print(source.with_name("summary.csv")) +``` + +`with_suffix()` devuelve una nueva ruta. No renombra un archivo en el disco. + +Del mismo modo, `with_name()` devuelve otro objeto de ruta con un nombre final distinto. + +La distinción es: + +```text +construir o transformar un Path + != +modificar el sistema de archivos +``` + +## 8. Leer y escribir texto + +`Path.read_text()` y `Path.write_text()` son atajos convenientes para archivos de texto pequeños. + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + notes_dir = workspace / "notes" + notes_dir.mkdir() + + notes_path = notes_dir / "pathlib.txt" + notes_path.write_text("Paths are objects.\n", encoding="utf-8") + + print(notes_path.read_text(encoding="utf-8").strip()) +``` + +Indica un encoding explícito cuando el formato o contrato de la aplicación lo requiera. + +Para datos portables del proyecto, UTF-8 suele ser una buena elección explícita: + +```python +text = path.read_text(encoding="utf-8") +``` + +y: + +```python +path.write_text(text, encoding="utf-8") +``` + +### Importante: `write_text()` reemplaza el contenido existente + +`Path.write_text()` abre el destino para escritura. Si el archivo ya existe, su contenido anterior se reemplaza. + +Eso es peligroso cuando el archivo existente debe conservarse. + +Usa este método solo cuando el reemplazo sea intencional. + +Para añadir contenido o usar modos de apertura especializados, utiliza `open()` o `Path.open()` con el modo adecuado. + +## 9. `Path.open()` y el `open()` incorporado + +Un objeto `Path` puede pasarse directamente al `open()` incorporado porque implementa el protocolo path-like de Python. + +```python +from pathlib import Path + +path = Path("notes.txt") + +with open(path, "r", encoding="utf-8") as file: + text = file.read() +``` + +También puedes usar el método del propio objeto: + +```python +with path.open("r", encoding="utf-8") as file: + text = file.read() +``` + +Ambas formas son válidas. Intenta mantener un estilo coherente dentro de un mismo proyecto. + +## 10. Crear directorios con `mkdir()` + +`Path.mkdir()` crea un directorio. + +```python +from pathlib import Path + +output_dir = Path("output") +output_dir.mkdir() +``` + +Para crear también padres ausentes: + +```python +output_dir = Path("build") / "reports" / "daily" +output_dir.mkdir(parents=True) +``` + +Cuando un directorio ya existente sea aceptable: + +```python +output_dir.mkdir(parents=True, exist_ok=True) +``` + +Sé preciso con `exist_ok=True`: significa que un directorio ya existente en esa ruta es aceptable. No convierte cualquier problema del sistema de archivos en éxito. Los errores de permisos y objetos incompatibles todavía pueden fallar. + +## 11. Consultar el sistema de archivos + +Consultas comunes: + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + file_path = workspace / "lesson.txt" + file_path.write_text("pathlib", encoding="utf-8") + + print(file_path.exists()) + print(file_path.is_file()) + print(workspace.is_dir()) +``` + +Métodos centrales: + +| Método | Pregunta | +|---|---| +| `.exists()` | ¿esta ruta existe ahora? | +| `.is_file()` | ¿apunta actualmente a un archivo regular? | +| `.is_dir()` | ¿apunta actualmente a un directorio? | +| `.is_symlink()` | ¿es un enlace simbólico? | + +Estos métodos informan el resultado de la consulta al sistema de archivos en el momento en que se ejecuta, pero un resultado `False` no siempre demuestra que una entrada esté ausente. En Python 3.14, métodos booleanos de estado como `exists()`, `is_file()` e `is_dir()` devuelven `False` cuando un `OSError` impide la inspección. Con el valor predeterminado `follow_symlinks=True`, `exists()` también devuelve `False` cuando falta el destino de un enlace simbólico. Si necesitas distinguir entre una ruta ausente, inaccesible, inválida u otro fallo al consultar su estado, usa `stat()` y maneja su excepción en lugar de depender únicamente de la consulta booleana. + +Por lo tanto, estas comprobaciones son instantáneas útiles de lo que la consulta pudo establecer, no garantías autoritativas sobre el sistema de archivos. La operación que realmente necesitas ejecutar, y cualquier excepción que produzca, sigue siendo la frontera autoritativa. + +## 12. Una comprobación no es una garantía + +Este código parece prudente: + +```python +if path.exists(): + text = path.read_text(encoding="utf-8") +``` + +Pero el sistema de archivos puede cambiar entre la comprobación y la lectura. Los permisos pueden cambiar. Otro proceso puede eliminar o reemplazar el archivo. Un sistema de archivos de red puede dejar de estar disponible. + +Por eso `exists()` es útil cuando importa el **estado actual**, pero no debe tratarse como una promesa de que la siguiente operación no puede fallar. + +En la frontera de la operación, maneja la excepción que la propia operación puede producir: + +```python +from pathlib import Path + +settings_path = Path("settings.json") + +try: + text = settings_path.read_text(encoding="utf-8") +except FileNotFoundError: + print("Settings file is missing") +else: + print(text) +``` + +Esto conecta directamente con la Fase 7: las APIs del sistema de archivos y el manejo de excepciones están diseñados para trabajar juntos. + +## 13. Recorrer un directorio + +`iterdir()` produce los hijos directos de un directorio. + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + + for name in ("gamma.txt", "alpha.txt", "beta.txt"): + (workspace / name).write_text(name, encoding="utf-8") + + for path in sorted(workspace.iterdir()): + print(path.name) +``` + +El sistema de archivos no promete un orden útil. Si el orden determinista importa, ordena explícitamente. + +Esto es especialmente importante en: + +- pruebas; +- informes generados; +- tutoriales; +- automatizaciones reproducibles. + +`iterdir()` no es recursivo. + +## 14. Buscar con `glob()` y `rglob()` + +`glob()` encuentra rutas mediante un patrón relativo a la ruta actual. + +```python +from pathlib import Path + +for path in Path("src").glob("*.py"): + print(path) +``` + +La búsqueda se limita al nivel indicado por el patrón. + +`rglob()` busca recursivamente: + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + source_dir = workspace / "src" + nested_dir = source_dir / "tools" + nested_dir.mkdir(parents=True) + + (source_dir / "app.py").write_text("print('app')\n", encoding="utf-8") + (nested_dir / "helper.py").write_text("VALUE = 1\n", encoding="utf-8") + (nested_dir / "notes.txt").write_text("notes\n", encoding="utf-8") + + for path in sorted(source_dir.rglob("*.py")): + print(path.relative_to(workspace)) +``` + +De nuevo, el orden no está garantizado. Usa `sorted()` cuando el orden forme parte del contrato de salida. + +Las búsquedas recursivas pueden ser costosas en árboles grandes. Restringe el patrón y la raíz de búsqueda tanto como permita la tarea. + +## 15. Hacer una ruta relativa a otra + +`relative_to()` expresa una ruta con respecto a un padre conocido: + +```python +from pathlib import Path + +workspace = Path("/project") +file_path = Path("/project/docs/guide.md") + +print(file_path.relative_to(workspace)) +``` + +Conceptualmente, el resultado es: + +```text +docs/guide.md +``` + +`relative_to()` trabaja con una relación entre rutas. No es lo mismo que consultar el directorio de trabajo actual. + +Puede generar `ValueError` cuando la relación solicitada no puede formarse según sus reglas. + +## 16. Resolver rutas + +`resolve()` devuelve una ruta absoluta resolviendo componentes `..` y enlaces simbólicos según la semántica del sistema de archivos. + +```python +from pathlib import Path + +path = Path("docs") / ".." / "README.md" +resolved = path.resolve() + +print(resolved) +``` + +Como `resolve()` puede involucrar semántica del sistema de archivos, no lo confundas con una simple limpieza de strings. + +Úsalo cuando realmente necesites una ruta resuelta, no automáticamente en cada `Path`. + +## 17. Rutas puras + +Las clases de rutas puras son útiles cuando quieres semántica de rutas sin acceso al sistema de archivos. + +Por ejemplo, un programa que se ejecuta en Linux puede analizar sintaxis de rutas de Windows: + +```python +from pathlib import PureWindowsPath + +windows_path = PureWindowsPath("C:/Users/Ana/Documents/report.txt") + +print(windows_path.name) +print(windows_path.parent) +``` + +`PureWindowsPath` no comprueba si esa ruta existe. + +Para código normal que trabaja con el sistema de archivos local, `Path` sigue siendo el punto de partida. + +## 18. Pensar en portabilidad + +Evita separadores fijos cuando la ruta deba ser portable. + +Frágil: + +```python +path = "reports\\2026\\summary.txt" +``` + +Mejor: + +```python +from pathlib import Path + +path = Path("reports") / "2026" / "summary.txt" +``` + +Pero "multiplataforma" no significa que toda ruta tenga el mismo significado en cualquier sistema. Unidades, rutas UNC, permisos, sensibilidad a mayúsculas, enlaces simbólicos, nombres reservados y reglas del filesystem pueden variar. + +`pathlib` ofrece una abstracción consciente de la plataforma. No elimina al sistema operativo. + +## 19. Los objetos `Path` funcionan con muchas APIs de Python + +Las APIs modernas de Python suelen aceptar objetos path-like. + +```python +from pathlib import Path +import json + +path = Path("config.json") + +with path.open("r", encoding="utf-8") as file: + data = json.load(file) +``` + +Por eso `pathlib` encaja bien con los capítulos anteriores de archivos y módulos. + +Normalmente no necesitas convertir cada `Path` a `str`. + +Convierte solo cuando una API externa exija específicamente una representación textual. + +## 20. Excepciones comunes + +Las operaciones del sistema de archivos todavía pueden fallar. + +| Excepción | Situación típica | +|---|---| +| `FileNotFoundError` | falta el archivo solicitado o alguna ruta padre | +| `FileExistsError` | la creación requería ausencia, pero ya existe una entrada | +| `PermissionError` | la operación no está permitida | +| `IsADirectoryError` | una operación de archivo recibe un directorio | +| `NotADirectoryError` | un componente esperado como directorio no lo es | +| `OSError` | fallos más amplios del sistema operativo o filesystem | + +Captura la excepción más específica que realmente puedas manejar. + +No envuelvas cada llamada a `Path` en `except Exception:` solo porque las operaciones del filesystem pueden fallar. + +## 21. Cuándo usar `pathlib` + +Usa `pathlib` cuando: + +- construyas rutas a partir de segmentos; +- necesites nombres, stems, sufijos o relaciones de parentesco; +- leas o escribas archivos; +- crees directorios; +- descubras archivos; +- necesites construcción portable de rutas; +- quieras que la intención de ruta sea explícita en interfaces. + +Ejemplo: + +```python +from pathlib import Path + +def load_template(template_path: Path) -> str: + return template_path.read_text(encoding="utf-8") +``` + +Un type hint `Path` puede hacer más claro un contrato que espera específicamente un objeto `Path`. + +Según la interfaz, aceptar una entrada path-like más amplia también puede ser adecuado. Es una decisión de diseño de API, no una regla universal. + +## 22. Cuándo no forzar `pathlib` + +No introduzcas objetos de ruta donde no exista un problema de rutas. + +Algunas APIs de bajo nivel o heredadas siguen diseñadas alrededor de `os`, `os.path`, descriptores de archivo o strings. + +La Fase 8 cubrirá más adelante `os` y `shutil`. Esos módulos no quedan obsoletos porque exista `pathlib`. Hay superposición, pero también responsabilidades en niveles diferentes. + +## 23. Errores comunes + +### Error 1: asumir que relativo significa relativo al archivo fuente + +```python +Path("data.json") +``` + +normalmente parte del directorio de trabajo del proceso. + +### Error 2: comprobar `exists()` y asumir que la siguiente operación está garantizada + +El estado del sistema de archivos puede cambiar. + +### Error 3: olvidar que `write_text()` reemplaza contenido + +Si debes preservar datos existentes, elige otra estrategia de apertura. + +### Error 4: concatenar separadores manualmente + +Prefiere composición estructural. + +### Error 5: suponer que el sufijo valida el formato + +`.json` en el nombre no demuestra JSON válido. + +### Error 6: depender del orden de iteración del directorio + +Ordena cuando la salida deba ser determinista. + +### Error 7: llamar `resolve()` automáticamente en todas partes + +Resuelve solo cuando necesites esa semántica. + +### Error 8: convertir cada `Path` a `str` + +Muchas APIs de Python aceptan objetos path-like directamente. + +## 24. Ejemplo práctico + +Imagina un pequeño programa que crea un workspace, escribe un informe y descubre archivos de texto generados. + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + reports_dir = workspace / "reports" + reports_dir.mkdir() + + report_path = reports_dir / "summary.txt" + report_path.write_text("status=ready\n", encoding="utf-8") + + for path in sorted(reports_dir.glob("*.txt")): + print(path.name, path.read_text(encoding="utf-8").strip()) +``` + +La idea importante no es solo una sintaxis más corta. + +El programa usa una sola abstracción de rutas para: + +```text +construir + ↓ +crear + ↓ +escribir + ↓ +descubrir + ↓ +leer +``` + +Eso deja visible la intención del filesystem de principio a fin. + +## 25. Ejercicio + +Crea un programa usando `TemporaryDirectory` y `Path` que: + +1. cree un directorio llamado `study`; +2. cree `notes` y `archive` dentro de él; +3. escriba dos archivos `.txt` dentro de `notes`; +4. liste los hijos directos de `notes` en orden; +5. encuentre todos los `.txt` bajo `study` recursivamente; +6. muestre cada ruta encontrada con respecto a `study`; +7. lea un archivo usando UTF-8; +8. no deje archivos permanentes. + +Después responde: + +- ¿Qué rutas son relativas? +- ¿Qué operaciones de este ejercicio realmente acceden o modifican el sistema de archivos y cuáles son solo operaciones estructurales de rutas, como componer rutas o usar `relative_to()`? +- ¿Por qué comprobar `.exists()` primero no garantiza que `.read_text()` funcione después? +- ¿Cuándo sería útil `PureWindowsPath` en lugar de `Path`? + +## 26. Lista de revisión + +Antes de avanzar, asegúrate de poder explicar: + +- qué representa un objeto `Path`; +- por qué `/` es útil para componer rutas; +- rutas relativas y absolutas; +- directorio de trabajo frente a ubicación del archivo fuente; +- `.name`, `.stem`, `.suffix`, `.parent` y `.parts`; +- `read_text()` y `write_text()`; +- `mkdir(parents=True, exist_ok=True)`; +- `.exists()`, `.is_file()` y `.is_dir()`; +- por qué las comprobaciones no son garantías; +- `iterdir()`, `glob()` y `rglob()`; +- por qué una salida determinista puede requerir `sorted()`; +- `with_name()` y `with_suffix()`; +- el propósito de `resolve()`; +- la diferencia entre `Path` y rutas puras; +- por qué `pathlib` complementa en vez de sustituir totalmente a `os` y `shutil`. + +## Referencia rápida + +```python +from pathlib import Path + +path = Path("reports") / "summary.txt" + +path.name +path.stem +path.suffix +path.parent +path.parts + +Path.cwd() +Path.home() + +path.exists() +path.is_file() +path.is_dir() + +path.read_text(encoding="utf-8") +path.write_text("text\n", encoding="utf-8") + +directory.mkdir(parents=True, exist_ok=True) + +list(directory.iterdir()) +list(directory.glob("*.txt")) +list(directory.rglob("*.txt")) + +path.with_name("other.txt") +path.with_suffix(".json") +path.resolve() +``` + +## Ejemplos ejecutables + +- [`examples/path_parts.py`](examples/path_parts.py) +- [`examples/text_workspace.py`](examples/text_workspace.py) +- [`examples/discover_python_files.py`](examples/discover_python_files.py) +- [`examples/inspect_paths.py`](examples/inspect_paths.py) + +Los ejemplos son deterministas y usan solo operaciones estructurales de rutas o directorios temporales, por lo que no dejan archivos persistentes. + +## Próximo capítulo + +Continúa con **Capítulo 02: `datetime` y Cálculos de Tiempo**, donde la biblioteca estándar añade objetos explícitos para fechas, horas, duraciones, parsing, formato y aritmética de fechas. + +## Referencias oficiales + +- [Python 3.14 `pathlib` - rutas de sistema de archivos orientadas a objetos](https://docs.python.org/3.14/library/pathlib.html) +- [Python 3.14 `os.PathLike` y `os.fspath()`](https://docs.python.org/3.14/library/os.html#os.PathLike) +- [Python 3.14 función incorporada `open()`](https://docs.python.org/3.14/library/functions.html#open) diff --git a/standard-library/01-pathlib/README.md b/standard-library/01-pathlib/README.md new file mode 100644 index 0000000..8f60ceb --- /dev/null +++ b/standard-library/01-pathlib/README.md @@ -0,0 +1,771 @@ +# Working with Filesystem Paths Using `pathlib` + +[🇺🇸 English](README.md) · [🇧🇷 Português](README.pt-BR.md) · [🇪🇸 Español](README.es.md) + +`pathlib` is the standard-library module for representing and manipulating filesystem paths as objects. + +Earlier chapters used strings such as `"notes.txt"` and `"reports/data.csv"` when opening files. That works, but paths have structure: they contain directories, names, stems, suffixes, parents, and platform-specific separators. `pathlib` gives that structure a dedicated API. + +For most everyday work, start with: + +```python +from pathlib import Path +``` + +Then create `Path` objects and combine them instead of manually concatenating path strings. + +## Learning goals + +By the end of this chapter, you should be able to: + +- explain what a `Path` object represents; +- create relative and absolute paths; +- combine path segments with `/`; +- inspect names, suffixes, parents, and parts; +- use `Path.cwd()` and `Path.home()` deliberately; +- create directories with `mkdir()`; +- read and write text through a path object; +- inspect whether a path currently points to a file or directory; +- iterate through directories with `iterdir()`; +- search with `glob()` and `rglob()`; +- transform path names with `with_name()` and `with_suffix()`; +- understand why existence checks do not guarantee that a later filesystem operation will succeed; +- distinguish `Path` from the pure path classes at a beginner level; +- avoid hard-coded path separators when portability matters. + +## 1. What problem does `pathlib` solve? + +A path is more than text. + +Consider: + +```text +reports/2026/summary.txt +``` + +That path has several meaningful pieces: + +- `reports` is a directory segment; +- `2026` is another directory segment; +- `summary.txt` is the final name; +- `summary` is the stem; +- `.txt` is the suffix. + +You could manipulate those pieces with string methods, but then your code must also understand path separators and operating-system conventions. + +`pathlib` puts path-specific behavior behind path-specific objects. + +```python +from pathlib import Path + +report_path = Path("reports") / "2026" / "summary.txt" + +print(report_path) +print(report_path.name) +print(report_path.stem) +print(report_path.suffix) +print(report_path.parent) +``` + +The exact separator shown by `print(report_path)` depends on the operating system. That is part of the point: your code expresses path structure instead of manually inserting `/` or `\\`. + +## 2. `Path` is usually the class you want + +The `pathlib` module contains several path classes. + +For normal filesystem work, use `Path`: + +```python +from pathlib import Path + +config_path = Path("config") / "settings.json" +``` + +`Path` is a concrete path class. It can both manipulate path structure and perform filesystem operations such as reading a file, creating a directory, or checking what currently exists. + +The module also contains pure path classes such as `PurePath`, `PurePosixPath`, and `PureWindowsPath`. Pure paths manipulate path syntax without touching the filesystem. + +You normally do **not** need to choose `PosixPath` or `WindowsPath` directly. `Path` chooses the concrete path flavor appropriate for the running platform. + +## 3. Creating paths + +A path can be created from one string: + +```python +from pathlib import Path + +file_path = Path("notes.txt") +``` + +It can also be created from multiple segments: + +```python +from pathlib import Path + +file_path = Path("reports", "2026", "summary.txt") +``` + +Or you can combine path objects and segments with `/`: + +```python +from pathlib import Path + +reports_dir = Path("reports") +file_path = reports_dir / "2026" / "summary.txt" +``` + +The `/` operator here does not perform division. `Path` defines it as a convenient path-joining operation. + +Prefer this: + +```python +file_path = Path("reports") / "2026" / "summary.txt" +``` + +over manual separator construction such as: + +```python +file_path = "reports/" + "2026/" + "summary.txt" +``` + +The `Path` version communicates intent and avoids embedding one platform's separator into the program. + +## 4. Relative and absolute paths + +A **relative path** is interpreted relative to some context, commonly the process's current working directory. + +```python +from pathlib import Path + +relative_path = Path("reports") / "summary.txt" + +print(relative_path.is_absolute()) +``` + +An **absolute path** identifies a location from the filesystem's root or drive context. + +Do not assume that a relative path is relative to the Python source file. It is normally interpreted relative to the current working directory of the running process. + +That distinction is one of the most common sources of "the file exists, but Python cannot find it" confusion. + +## 5. Current working directory and home directory + +`Path.cwd()` returns the current working directory: + +```python +from pathlib import Path + +current_dir = Path.cwd() +print(current_dir) +``` + +`Path.home()` returns the current user's home directory: + +```python +from pathlib import Path + +home_dir = Path.home() +print(home_dir) +``` + +These methods are useful when the program intentionally depends on those locations. + +Do not use them merely to make a path "look absolute". First decide what the path is supposed to be relative to. + +## 6. Inspecting path structure + +`Path` exposes common path components as attributes. + +```python +from pathlib import Path + +path = Path("archive") / "report.final.csv" + +print(path.name) +print(path.stem) +print(path.suffix) +print(path.suffixes) +print(path.parent) +print(path.parts) +``` + +Typical meanings: + +| Attribute | Meaning | +|---|---| +| `.name` | final path component | +| `.stem` | final name without its last suffix | +| `.suffix` | last file suffix | +| `.suffixes` | list of suffixes | +| `.parent` | logical parent path | +| `.parents` | sequence of logical ancestors | +| `.parts` | tuple of path components | + +A suffix is based on path syntax, not on the file's actual contents. A file named `table.csv` is not guaranteed to contain valid CSV just because its suffix is `.csv`. + +## 7. Transforming names without string surgery + +Use path methods when the operation is about path structure. + +```python +from pathlib import Path + +source = Path("exports") / "report.csv" + +print(source.with_suffix(".json")) +print(source.with_name("summary.csv")) +``` + +`with_suffix()` returns a new path. It does not rename a file on disk. + +Likewise, `with_name()` returns another path object with a different final name. + +This distinction matters: + +```text +construct or transform a Path object + != +perform a filesystem mutation +``` + +## 8. Reading and writing text + +`Path.read_text()` and `Path.write_text()` are convenient wrappers for small text files. + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + notes_dir = workspace / "notes" + notes_dir.mkdir() + + notes_path = notes_dir / "pathlib.txt" + notes_path.write_text("Paths are objects.\n", encoding="utf-8") + + print(notes_path.read_text(encoding="utf-8").strip()) +``` + +Use an explicit encoding for text data when the file format or application contract expects one. + +For portable project data, UTF-8 is usually a good explicit choice: + +```python +text = path.read_text(encoding="utf-8") +``` + +and: + +```python +path.write_text(text, encoding="utf-8") +``` + +### Important: `write_text()` replaces existing contents + +`Path.write_text()` opens the target for writing. If the file already exists, its previous contents are replaced. + +That makes this dangerous if the existing file must be preserved. + +Use it only when replacement is intentional. + +For append workflows or more specialized opening modes, use `open()` or `Path.open()` with an appropriate mode. + +## 9. `Path.open()` and the built-in `open()` + +A `Path` object can be passed directly to the built-in `open()` because it implements Python's path-like protocol. + +```python +from pathlib import Path + +path = Path("notes.txt") + +with open(path, "r", encoding="utf-8") as file: + text = file.read() +``` + +You can also call the path's own method: + +```python +with path.open("r", encoding="utf-8") as file: + text = file.read() +``` + +Both are valid. Choose one style consistently within a codebase. + +## 10. Creating directories with `mkdir()` + +`Path.mkdir()` creates a directory. + +```python +from pathlib import Path + +output_dir = Path("output") +output_dir.mkdir() +``` + +If missing parent directories should also be created: + +```python +output_dir = Path("build") / "reports" / "daily" +output_dir.mkdir(parents=True) +``` + +If an already-existing directory is acceptable: + +```python +output_dir.mkdir(parents=True, exist_ok=True) +``` + +Be precise about `exist_ok=True`: it says an existing directory at that path is acceptable. It does not turn every filesystem problem into success. Permission errors and incompatible existing objects can still fail. + +## 11. Checking the filesystem + +Common queries include: + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + file_path = workspace / "lesson.txt" + file_path.write_text("pathlib", encoding="utf-8") + + print(file_path.exists()) + print(file_path.is_file()) + print(workspace.is_dir()) +``` + +The central methods are: + +| Method | Question | +|---|---| +| `.exists()` | does this path currently exist? | +| `.is_file()` | does it currently refer to a regular file? | +| `.is_dir()` | does it currently refer to a directory? | +| `.is_symlink()` | is it a symbolic link? | + +These methods report the result of the filesystem query at the time it runs, but a `False` result is not always proof that an entry is absent. In Python 3.14, boolean status methods such as `exists()`, `is_file()`, and `is_dir()` return `False` when an `OSError` prevents inspection. With the default `follow_symlinks=True`, `exists()` also returns `False` when a symbolic link's target is missing. If you need to distinguish missing, inaccessible, invalid, or another status failure, use `stat()` and handle its exception rather than relying on the boolean query alone. + +These checks are therefore useful snapshots of what the query could establish, not authoritative guarantees about the filesystem. The operation you actually need to perform, and any exception it raises, remains the authoritative boundary. + +## 12. A check is not a guarantee + +This code looks cautious: + +```python +if path.exists(): + text = path.read_text(encoding="utf-8") +``` + +But the filesystem can change between the check and the read. Permissions can change. Another process can remove or replace the file. A network filesystem can become unavailable. + +So `exists()` is useful when the **current state itself** matters, but it should not be treated as a promise that the next operation cannot fail. + +At an operation boundary, handle the exception that the operation itself can raise: + +```python +from pathlib import Path + +settings_path = Path("settings.json") + +try: + text = settings_path.read_text(encoding="utf-8") +except FileNotFoundError: + print("Settings file is missing") +else: + print(text) +``` + +This connects directly to Phase 7: filesystem APIs and exception handling are designed to work together. + +## 13. Iterating over a directory + +`iterdir()` yields the direct children of a directory. + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + + for name in ("gamma.txt", "alpha.txt", "beta.txt"): + (workspace / name).write_text(name, encoding="utf-8") + + for path in sorted(workspace.iterdir()): + print(path.name) +``` + +The filesystem does not promise a useful order. If deterministic order matters, sort explicitly. + +This is especially important in: + +- tests; +- generated reports; +- tutorials; +- reproducible automation. + +`iterdir()` is not recursive. It sees only the direct children of that directory. + +## 14. Searching with `glob()` and `rglob()` + +`glob()` matches paths using a pattern relative to the current path. + +```python +from pathlib import Path + +for path in Path("src").glob("*.py"): + print(path) +``` + +That searches only the matching level. + +`rglob()` searches recursively: + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + source_dir = workspace / "src" + nested_dir = source_dir / "tools" + nested_dir.mkdir(parents=True) + + (source_dir / "app.py").write_text("print('app')\n", encoding="utf-8") + (nested_dir / "helper.py").write_text("VALUE = 1\n", encoding="utf-8") + (nested_dir / "notes.txt").write_text("notes\n", encoding="utf-8") + + for path in sorted(source_dir.rglob("*.py")): + print(path.relative_to(workspace)) +``` + +Again, results are not guaranteed to arrive in a particular order. Sort when order is part of the output contract. + +Patterns can be powerful, but recursive searches such as `**` or `rglob()` can become expensive on large directory trees. Search as narrowly as the task allows. + +## 15. Making a path relative to another path + +`relative_to()` expresses one path relative to a known parent context: + +```python +from pathlib import Path + +workspace = Path("/project") +file_path = Path("/project/docs/guide.md") + +print(file_path.relative_to(workspace)) +``` + +Conceptually, the result is: + +```text +docs/guide.md +``` + +`relative_to()` is a path relationship operation. It is not the same as asking the operating system for the current working directory. + +It raises `ValueError` when the requested relationship cannot be formed under its rules. + +## 16. Resolving paths + +`resolve()` returns an absolute path while resolving `..` components and symbolic links according to the filesystem. + +```python +from pathlib import Path + +path = Path("docs") / ".." / "README.md" +resolved = path.resolve() + +print(resolved) +``` + +Because `resolve()` can involve filesystem semantics, do not confuse it with simple string cleanup. + +Use it when you actually need a resolved filesystem path, not automatically on every `Path`. + +## 17. Pure paths + +Pure path classes are useful when you want path semantics without filesystem access. + +For example, code running on Linux can still reason about Windows path syntax: + +```python +from pathlib import PureWindowsPath + +windows_path = PureWindowsPath("C:/Users/Ana/Documents/report.txt") + +print(windows_path.name) +print(windows_path.parent) +``` + +`PureWindowsPath` does not check whether that Windows path exists. + +For ordinary application code that works with the local filesystem, `Path` remains the default starting point. + +## 18. Cross-platform thinking + +Avoid manually hard-coding separators when the path is meant to be portable. + +Fragile: + +```python +path = "reports\\2026\\summary.txt" +``` + +Better: + +```python +from pathlib import Path + +path = Path("reports") / "2026" / "summary.txt" +``` + +But "cross-platform" does not mean every path is meaningful on every platform. Drive letters, UNC paths, permissions, case sensitivity, symbolic-link behavior, reserved names, and filesystem rules can differ. + +`pathlib` gives you the platform-aware abstraction. It does not erase the operating system. + +## 19. `Path` objects work with many Python APIs + +Modern Python APIs commonly accept path-like objects. + +For example: + +```python +from pathlib import Path +import json + +path = Path("config.json") + +with path.open("r", encoding="utf-8") as file: + data = json.load(file) +``` + +This is one reason `pathlib` composes well with the earlier file and module chapters. + +You do not normally need to convert every `Path` to `str`. + +Convert to a string only when an external API specifically requires a string representation. + +## 20. Common exceptions + +Filesystem operations can still fail. + +Common exceptions include: + +| Exception | Typical situation | +|---|---| +| `FileNotFoundError` | a requested file or parent path is missing | +| `FileExistsError` | creation required absence, but an entry already exists | +| `PermissionError` | the operation is not permitted | +| `IsADirectoryError` | a file operation targets a directory | +| `NotADirectoryError` | a directory component is not actually a directory | +| `OSError` | broader operating-system or filesystem failures | + +Catch the most specific exception you can actually handle. + +Do not wrap every `Path` call in `except Exception:` just because filesystem operations can fail. + +## 21. When to use `pathlib` + +Use `pathlib` when: + +- you are building paths from segments; +- you need names, stems, suffixes, or parent relationships; +- you are reading or writing files; +- you are creating directories; +- you are discovering files; +- you need portable path construction; +- you want path intent to be explicit in function interfaces. + +For example: + +```python +from pathlib import Path + +def load_template(template_path: Path) -> str: + return template_path.read_text(encoding="utf-8") +``` + +A type hint of `Path` can make a path-oriented contract clearer when your function intentionally expects a `Path` object. + +Depending on the interface, accepting a broader path-like input can also be appropriate. That is an API-design decision, not a rule that every path parameter must use one exact type. + +## 22. When not to force `pathlib` + +Do not introduce path objects where there is no path problem to solve. + +Also remember that some low-level or legacy APIs may still be designed around `os`, `os.path`, file descriptors, or raw strings. + +Phase 8 will later cover `os` and `shutil`. Those modules are not "obsolete because `pathlib` exists". They overlap in some areas and serve different levels of the standard library. + +## 23. Common mistakes + +### Mistake 1: assuming relative means relative to the source file + +```python +Path("data.json") +``` + +is normally interpreted from the process's current working directory. + +### Mistake 2: checking `exists()` and assuming the next operation is guaranteed + +Filesystem state can change between operations. + +### Mistake 3: forgetting that `write_text()` replaces contents + +If preserving existing data matters, choose the appropriate file-opening strategy. + +### Mistake 4: manually concatenating separators + +Prefer structural path composition. + +### Mistake 5: assuming suffix equals format validation + +`.json` in the name does not prove valid JSON. + +### Mistake 6: relying on directory iteration order + +Sort when deterministic ordering matters. + +### Mistake 7: calling `resolve()` automatically everywhere + +Resolve when you need resolution semantics. + +### Mistake 8: converting every `Path` to `str` + +Many Python APIs accept path-like objects directly. + +## 24. Practical example + +Imagine a small reporting program that creates a workspace, writes a report, then discovers generated text files. + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + reports_dir = workspace / "reports" + reports_dir.mkdir() + + report_path = reports_dir / "summary.txt" + report_path.write_text("status=ready\n", encoding="utf-8") + + for path in sorted(reports_dir.glob("*.txt")): + print(path.name, path.read_text(encoding="utf-8").strip()) +``` + +The important design idea is not merely shorter syntax. + +The program uses one path abstraction consistently for: + +```text +construct + ↓ +create + ↓ +write + ↓ +discover + ↓ +read +``` + +That makes filesystem intent visible from end to end. + +## 25. Exercise + +Create a program using `TemporaryDirectory` and `Path` that: + +1. creates a directory named `study`; +2. creates `notes` and `archive` inside it; +3. writes two `.txt` files inside `notes`; +4. lists the direct children of `notes` in sorted order; +5. finds every `.txt` file below `study` recursively; +6. prints each discovered path relative to `study`; +7. reads one file using UTF-8; +8. does not leave permanent files behind. + +Then answer: + +- Which paths are relative? +- Which operations in this exercise actually access or modify the filesystem, and which are only structural path operations such as path composition or `relative_to()`? +- Why would checking `.exists()` first not guarantee that `.read_text()` succeeds later? +- When would `PureWindowsPath` be useful instead of `Path`? + +## 26. Review checklist + +Before moving on, make sure you can explain: + +- what a `Path` object represents; +- why `/` is useful for path composition; +- relative versus absolute paths; +- current working directory versus source-file location; +- `.name`, `.stem`, `.suffix`, `.parent`, and `.parts`; +- `read_text()` and `write_text()`; +- `mkdir(parents=True, exist_ok=True)`; +- `.exists()`, `.is_file()`, and `.is_dir()`; +- why checks are not guarantees; +- `iterdir()`, `glob()`, and `rglob()`; +- why deterministic output may require `sorted()`; +- `with_name()` and `with_suffix()`; +- the purpose of `resolve()`; +- the difference between `Path` and pure paths; +- why `pathlib` complements rather than replaces all of `os` and `shutil`. + +## Quick reference + +```python +from pathlib import Path + +path = Path("reports") / "summary.txt" + +path.name +path.stem +path.suffix +path.parent +path.parts + +Path.cwd() +Path.home() + +path.exists() +path.is_file() +path.is_dir() + +path.read_text(encoding="utf-8") +path.write_text("text\n", encoding="utf-8") + +directory.mkdir(parents=True, exist_ok=True) + +list(directory.iterdir()) +list(directory.glob("*.txt")) +list(directory.rglob("*.txt")) + +path.with_name("other.txt") +path.with_suffix(".json") +path.resolve() +``` + +## Runnable examples + +- [`examples/path_parts.py`](examples/path_parts.py) +- [`examples/text_workspace.py`](examples/text_workspace.py) +- [`examples/discover_python_files.py`](examples/discover_python_files.py) +- [`examples/inspect_paths.py`](examples/inspect_paths.py) + +These examples are deterministic and use either path-only operations or temporary directories so they do not leave persistent files behind. + +## Next chapter + +Continue with **Chapter 02: `datetime` and Time Calculations**, where the standard library adds explicit objects for dates, times, durations, parsing, formatting, and date arithmetic. + +## Official references + +- [Python 3.14 `pathlib` - object-oriented filesystem paths](https://docs.python.org/3.14/library/pathlib.html) +- [Python 3.14 `os.PathLike` and `os.fspath()`](https://docs.python.org/3.14/library/os.html#os.PathLike) +- [Python 3.14 built-in `open()`](https://docs.python.org/3.14/library/functions.html#open) diff --git a/standard-library/01-pathlib/README.pt-BR.md b/standard-library/01-pathlib/README.pt-BR.md new file mode 100644 index 0000000..ef18b7e --- /dev/null +++ b/standard-library/01-pathlib/README.pt-BR.md @@ -0,0 +1,767 @@ +# Trabalhando com Caminhos do Sistema de Arquivos Usando `pathlib` + +[🇺🇸 English](README.md) · [🇧🇷 Português](README.pt-BR.md) · [🇪🇸 Español](README.es.md) + +`pathlib` é o módulo da biblioteca padrão para representar e manipular caminhos do sistema de arquivos como objetos. + +Nos capítulos anteriores, usamos strings como `"notes.txt"` e `"reports/data.csv"` ao abrir arquivos. Isso funciona, mas caminhos possuem estrutura: diretórios, nomes, stems, sufixos, pais e separadores que dependem da plataforma. `pathlib` oferece uma API própria para essa estrutura. + +Para a maior parte do trabalho cotidiano, comece com: + +```python +from pathlib import Path +``` + +Depois, crie objetos `Path` e combine-os em vez de concatenar strings manualmente. + +## Objetivos de aprendizagem + +Ao final deste capítulo, você deverá conseguir: + +- explicar o que um objeto `Path` representa; +- criar caminhos relativos e absolutos; +- combinar segmentos com `/`; +- inspecionar nomes, sufixos, pais e partes; +- usar `Path.cwd()` e `Path.home()` de forma intencional; +- criar diretórios com `mkdir()`; +- ler e escrever texto por meio de um caminho; +- verificar se um caminho aponta atualmente para arquivo ou diretório; +- percorrer diretórios com `iterdir()`; +- pesquisar com `glob()` e `rglob()`; +- transformar nomes com `with_name()` e `with_suffix()`; +- entender por que verificar existência não garante que uma operação posterior terá sucesso; +- distinguir `Path` das classes de caminhos puros em nível introdutório; +- evitar separadores de caminho fixos quando a portabilidade importa. + +## 1. Que problema o `pathlib` resolve? + +Um caminho é mais do que texto. + +Considere: + +```text +reports/2026/summary.txt +``` + +Esse caminho possui partes com significado: + +- `reports` é um segmento de diretório; +- `2026` é outro segmento; +- `summary.txt` é o nome final; +- `summary` é o stem; +- `.txt` é o sufixo. + +Seria possível manipular tudo com métodos de string, mas o código também teria de entender separadores e convenções do sistema operacional. + +`pathlib` coloca comportamento de caminhos em objetos específicos para caminhos. + +```python +from pathlib import Path + +report_path = Path("reports") / "2026" / "summary.txt" + +print(report_path) +print(report_path.name) +print(report_path.stem) +print(report_path.suffix) +print(report_path.parent) +``` + +O separador exibido por `print(report_path)` depende do sistema operacional. Esse é justamente um dos benefícios: o código expressa a estrutura do caminho sem inserir manualmente `/` ou `\\`. + +## 2. `Path` normalmente é a classe certa + +O módulo `pathlib` possui várias classes. + +Para trabalho normal com o sistema de arquivos, use `Path`: + +```python +from pathlib import Path + +config_path = Path("config") / "settings.json" +``` + +`Path` é uma classe concreta. Ela pode manipular a estrutura do caminho e também executar operações no sistema de arquivos, como ler um arquivo, criar um diretório ou consultar o que existe. + +Também existem classes puras, como `PurePath`, `PurePosixPath` e `PureWindowsPath`. Elas manipulam a sintaxe do caminho sem acessar o sistema de arquivos. + +Normalmente você **não** precisa escolher `PosixPath` ou `WindowsPath` diretamente. `Path` seleciona a variante concreta adequada para a plataforma em execução. + +## 3. Criando caminhos + +Um caminho pode ser criado a partir de uma string: + +```python +from pathlib import Path + +file_path = Path("notes.txt") +``` + +Também pode receber vários segmentos: + +```python +from pathlib import Path + +file_path = Path("reports", "2026", "summary.txt") +``` + +Ou podemos combinar objetos e segmentos com `/`: + +```python +from pathlib import Path + +reports_dir = Path("reports") +file_path = reports_dir / "2026" / "summary.txt" +``` + +Nesse contexto, `/` não executa divisão. `Path` define esse operador como uma forma conveniente de unir segmentos. + +Prefira: + +```python +file_path = Path("reports") / "2026" / "summary.txt" +``` + +em vez de construir separadores manualmente: + +```python +file_path = "reports/" + "2026/" + "summary.txt" +``` + +A versão com `Path` comunica a intenção e evita amarrar o programa ao separador de uma única plataforma. + +## 4. Caminhos relativos e absolutos + +Um **caminho relativo** é interpretado em relação a algum contexto, normalmente o diretório de trabalho atual do processo. + +```python +from pathlib import Path + +relative_path = Path("reports") / "summary.txt" + +print(relative_path.is_absolute()) +``` + +Um **caminho absoluto** identifica uma localização a partir da raiz ou do contexto de unidade do sistema de arquivos. + +Não suponha que um caminho relativo é relativo ao arquivo `.py`. Normalmente ele é interpretado a partir do diretório de trabalho atual do processo. + +Essa diferença explica muitos casos de "o arquivo existe, mas o Python não encontra". + +## 5. Diretório de trabalho e diretório home + +`Path.cwd()` retorna o diretório de trabalho atual: + +```python +from pathlib import Path + +current_dir = Path.cwd() +print(current_dir) +``` + +`Path.home()` retorna o diretório home do usuário atual: + +```python +from pathlib import Path + +home_dir = Path.home() +print(home_dir) +``` + +Use esses métodos quando o programa realmente depende dessas localizações. + +Não os utilize apenas para fazer um caminho "parecer absoluto". Primeiro defina em relação a que localização o caminho deve existir. + +## 6. Inspecionando a estrutura do caminho + +`Path` expõe componentes comuns como atributos. + +```python +from pathlib import Path + +path = Path("archive") / "report.final.csv" + +print(path.name) +print(path.stem) +print(path.suffix) +print(path.suffixes) +print(path.parent) +print(path.parts) +``` + +Significados comuns: + +| Atributo | Significado | +|---|---| +| `.name` | componente final do caminho | +| `.stem` | nome final sem o último sufixo | +| `.suffix` | último sufixo | +| `.suffixes` | lista de sufixos | +| `.parent` | caminho pai lógico | +| `.parents` | sequência de ancestrais lógicos | +| `.parts` | tupla com os componentes | + +O sufixo é baseado na sintaxe do caminho, não no conteúdo real do arquivo. Um arquivo chamado `table.csv` não é necessariamente um CSV válido. + +## 7. Transformando nomes sem cirurgia de strings + +Use métodos de caminho quando a operação diz respeito à estrutura do caminho. + +```python +from pathlib import Path + +source = Path("exports") / "report.csv" + +print(source.with_suffix(".json")) +print(source.with_name("summary.csv")) +``` + +`with_suffix()` retorna um novo caminho. Ele não renomeia um arquivo no disco. + +Da mesma forma, `with_name()` retorna outro objeto de caminho com um nome final diferente. + +A distinção é: + +```text +construir ou transformar um Path + != +alterar o sistema de arquivos +``` + +## 8. Lendo e escrevendo texto + +`Path.read_text()` e `Path.write_text()` são atalhos convenientes para arquivos de texto pequenos. + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + notes_dir = workspace / "notes" + notes_dir.mkdir() + + notes_path = notes_dir / "pathlib.txt" + notes_path.write_text("Paths are objects.\n", encoding="utf-8") + + print(notes_path.read_text(encoding="utf-8").strip()) +``` + +Informe um encoding explícito quando o formato ou contrato da aplicação exigir. + +Para dados portáveis do projeto, UTF-8 costuma ser uma boa escolha explícita: + +```python +text = path.read_text(encoding="utf-8") +``` + +e: + +```python +path.write_text(text, encoding="utf-8") +``` + +### Importante: `write_text()` substitui o conteúdo existente + +`Path.write_text()` abre o destino para escrita. Se o arquivo já existir, o conteúdo anterior é substituído. + +Isso é perigoso quando o arquivo existente precisa ser preservado. + +Use esse método somente quando a substituição for intencional. + +Para acrescentar conteúdo ou usar modos especiais, utilize `open()` ou `Path.open()` com o modo adequado. + +## 9. `Path.open()` e o `open()` embutido + +Um objeto `Path` pode ser passado diretamente ao `open()` embutido porque implementa o protocolo path-like do Python. + +```python +from pathlib import Path + +path = Path("notes.txt") + +with open(path, "r", encoding="utf-8") as file: + text = file.read() +``` + +Também é possível usar o método do próprio caminho: + +```python +with path.open("r", encoding="utf-8") as file: + text = file.read() +``` + +As duas formas são válidas. Procure manter um estilo consistente no mesmo projeto. + +## 10. Criando diretórios com `mkdir()` + +`Path.mkdir()` cria um diretório. + +```python +from pathlib import Path + +output_dir = Path("output") +output_dir.mkdir() +``` + +Para criar também pais ausentes: + +```python +output_dir = Path("build") / "reports" / "daily" +output_dir.mkdir(parents=True) +``` + +Quando um diretório já existente for aceitável: + +```python +output_dir.mkdir(parents=True, exist_ok=True) +``` + +Seja preciso sobre `exist_ok=True`: ele indica que um diretório já existente naquele caminho é aceitável. Isso não transforma todo problema de sistema de arquivos em sucesso. Erros de permissão e objetos incompatíveis ainda podem causar falhas. + +## 11. Consultando o sistema de arquivos + +Consultas comuns: + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + file_path = workspace / "lesson.txt" + file_path.write_text("pathlib", encoding="utf-8") + + print(file_path.exists()) + print(file_path.is_file()) + print(workspace.is_dir()) +``` + +Métodos centrais: + +| Método | Pergunta | +|---|---| +| `.exists()` | este caminho existe agora? | +| `.is_file()` | ele aponta atualmente para um arquivo regular? | +| `.is_dir()` | ele aponta atualmente para um diretório? | +| `.is_symlink()` | ele é um link simbólico? | + +Esses métodos informam o resultado da consulta ao sistema de arquivos no momento em que ela é executada, mas um resultado `False` nem sempre prova que uma entrada está ausente. No Python 3.14, métodos booleanos de estado como `exists()`, `is_file()` e `is_dir()` retornam `False` quando um `OSError` impede a inspeção. Com o padrão `follow_symlinks=True`, `exists()` também retorna `False` quando o destino de um link simbólico está ausente. Se você precisar distinguir entre caminho ausente, inacessível, inválido ou outra falha de consulta de estado, use `stat()` e trate sua exceção em vez de depender apenas da consulta booleana. + +Portanto, essas verificações são fotografias úteis daquilo que a consulta conseguiu estabelecer, e não garantias autoritativas sobre o sistema de arquivos. A operação que você realmente precisa executar, e qualquer exceção que ela gerar, continua sendo a fronteira autoritativa. + +## 12. Uma verificação não é uma garantia + +Este código parece cuidadoso: + +```python +if path.exists(): + text = path.read_text(encoding="utf-8") +``` + +Mas o sistema de arquivos pode mudar entre a verificação e a leitura. Permissões podem mudar. Outro processo pode remover ou substituir o arquivo. Um recurso de rede pode ficar indisponível. + +Por isso, `exists()` é útil quando o **estado atual** é relevante, mas não deve ser tratado como promessa de que a operação seguinte não falhará. + +Na fronteira da operação, trate a exceção que a própria operação pode gerar: + +```python +from pathlib import Path + +settings_path = Path("settings.json") + +try: + text = settings_path.read_text(encoding="utf-8") +except FileNotFoundError: + print("Settings file is missing") +else: + print(text) +``` + +Essa ideia se conecta diretamente à Fase 7: APIs de sistema de arquivos e tratamento de exceções trabalham juntas. + +## 13. Percorrendo um diretório + +`iterdir()` produz os filhos diretos de um diretório. + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + + for name in ("gamma.txt", "alpha.txt", "beta.txt"): + (workspace / name).write_text(name, encoding="utf-8") + + for path in sorted(workspace.iterdir()): + print(path.name) +``` + +O sistema de arquivos não promete uma ordem útil. Se a ordem determinística fizer parte do resultado, ordene explicitamente. + +Isso é especialmente importante em: + +- testes; +- relatórios gerados; +- tutoriais; +- automações reproduzíveis. + +`iterdir()` não é recursivo. + +## 14. Pesquisando com `glob()` e `rglob()` + +`glob()` encontra caminhos usando um padrão relativo ao caminho atual. + +```python +from pathlib import Path + +for path in Path("src").glob("*.py"): + print(path) +``` + +Essa busca considera o nível correspondente ao padrão. + +`rglob()` pesquisa recursivamente: + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + source_dir = workspace / "src" + nested_dir = source_dir / "tools" + nested_dir.mkdir(parents=True) + + (source_dir / "app.py").write_text("print('app')\n", encoding="utf-8") + (nested_dir / "helper.py").write_text("VALUE = 1\n", encoding="utf-8") + (nested_dir / "notes.txt").write_text("notes\n", encoding="utf-8") + + for path in sorted(source_dir.rglob("*.py")): + print(path.relative_to(workspace)) +``` + +Novamente, a ordem não é garantida. Use `sorted()` quando a ordem fizer parte do contrato. + +Buscas recursivas podem ficar caras em árvores grandes. Restrinja o padrão e a raiz de busca conforme a necessidade real. + +## 15. Tornando um caminho relativo a outro + +`relative_to()` expressa um caminho em relação a um pai conhecido: + +```python +from pathlib import Path + +workspace = Path("/project") +file_path = Path("/project/docs/guide.md") + +print(file_path.relative_to(workspace)) +``` + +Conceitualmente, o resultado é: + +```text +docs/guide.md +``` + +`relative_to()` trabalha com uma relação entre caminhos. Não é equivalente a consultar o diretório de trabalho atual. + +Ele pode gerar `ValueError` quando a relação solicitada não pode ser formada de acordo com suas regras. + +## 16. Resolvendo caminhos + +`resolve()` retorna um caminho absoluto, resolvendo componentes `..` e links simbólicos conforme a semântica do sistema de arquivos. + +```python +from pathlib import Path + +path = Path("docs") / ".." / "README.md" +resolved = path.resolve() + +print(resolved) +``` + +Como `resolve()` envolve semântica do sistema de arquivos, não o confunda com simples limpeza de string. + +Use-o quando realmente precisar de um caminho resolvido, e não automaticamente em todo `Path`. + +## 17. Caminhos puros + +Classes de caminhos puros são úteis quando queremos a semântica de um caminho sem acessar o sistema de arquivos. + +Por exemplo, um programa executando em Linux pode analisar sintaxe de caminhos do Windows: + +```python +from pathlib import PureWindowsPath + +windows_path = PureWindowsPath("C:/Users/Ana/Documents/report.txt") + +print(windows_path.name) +print(windows_path.parent) +``` + +`PureWindowsPath` não verifica se esse caminho existe. + +Para código comum que trabalha com o sistema de arquivos local, `Path` continua sendo o ponto de partida. + +## 18. Pensando em portabilidade + +Evite separadores fixos quando o caminho precisa ser portável. + +Frágil: + +```python +path = "reports\\2026\\summary.txt" +``` + +Melhor: + +```python +from pathlib import Path + +path = Path("reports") / "2026" / "summary.txt" +``` + +Mas "multiplataforma" não significa que todo caminho possui o mesmo significado em qualquer sistema. Unidades, caminhos UNC, permissões, sensibilidade a maiúsculas, links simbólicos, nomes reservados e regras de filesystem podem variar. + +`pathlib` oferece uma abstração consciente da plataforma. Ele não apaga o sistema operacional. + +## 19. Objetos `Path` funcionam com muitas APIs do Python + +APIs modernas do Python frequentemente aceitam objetos path-like. + +```python +from pathlib import Path +import json + +path = Path("config.json") + +with path.open("r", encoding="utf-8") as file: + data = json.load(file) +``` + +Por isso `pathlib` se integra bem aos capítulos anteriores de arquivos e módulos. + +Normalmente não é necessário converter todo `Path` para `str`. + +Converta apenas quando uma API externa exigir especificamente uma representação textual. + +## 20. Exceções comuns + +Operações de sistema de arquivos ainda podem falhar. + +| Exceção | Situação típica | +|---|---| +| `FileNotFoundError` | arquivo solicitado ou algum caminho pai está ausente | +| `FileExistsError` | a criação exigia ausência, mas já existe uma entrada | +| `PermissionError` | a operação não é permitida | +| `IsADirectoryError` | uma operação de arquivo recebeu um diretório | +| `NotADirectoryError` | um componente esperado como diretório não é diretório | +| `OSError` | falhas mais amplas do sistema operacional ou filesystem | + +Capture a exceção mais específica que você realmente consegue tratar. + +Não envolva toda chamada de `Path` em `except Exception:` apenas porque operações de filesystem podem falhar. + +## 21. Quando usar `pathlib` + +Use `pathlib` quando: + +- estiver construindo caminhos a partir de segmentos; +- precisar de nomes, stems, sufixos ou relações de parentesco; +- estiver lendo ou escrevendo arquivos; +- estiver criando diretórios; +- estiver descobrindo arquivos; +- precisar de construção portável de caminhos; +- quiser tornar explícita a intenção de caminho em interfaces. + +Exemplo: + +```python +from pathlib import Path + +def load_template(template_path: Path) -> str: + return template_path.read_text(encoding="utf-8") +``` + +Um type hint `Path` pode tornar claro um contrato que espera especificamente um objeto `Path`. + +Dependendo da interface, aceitar uma entrada path-like mais ampla também pode fazer sentido. Isso é uma decisão de design de API, não uma regra universal. + +## 22. Quando não forçar `pathlib` + +Não introduza objetos de caminho onde não existe um problema de caminho. + +Algumas APIs de baixo nível ou legadas continuam organizadas em torno de `os`, `os.path`, descritores de arquivo ou strings. + +A Fase 8 ainda abordará `os` e `shutil`. Esses módulos não se tornam obsoletos porque `pathlib` existe. Há sobreposição, mas também responsabilidades em níveis diferentes. + +## 23. Erros comuns + +### Erro 1: assumir que relativo significa relativo ao arquivo-fonte + +```python +Path("data.json") +``` + +normalmente parte do diretório de trabalho do processo. + +### Erro 2: verificar `exists()` e assumir que a próxima operação está garantida + +O estado do sistema de arquivos pode mudar. + +### Erro 3: esquecer que `write_text()` substitui conteúdo + +Se preservar dados existentes for necessário, escolha outra estratégia de abertura. + +### Erro 4: concatenar separadores manualmente + +Prefira composição estrutural. + +### Erro 5: supor que o sufixo valida o formato + +`.json` no nome não prova JSON válido. + +### Erro 6: depender da ordem de iteração de diretório + +Ordene quando a saída precisa ser determinística. + +### Erro 7: chamar `resolve()` automaticamente em todo lugar + +Resolva somente quando precisar dessa semântica. + +### Erro 8: converter todo `Path` para `str` + +Muitas APIs do Python aceitam objetos path-like diretamente. + +## 24. Exemplo prático + +Imagine um programa pequeno que cria um workspace, escreve um relatório e descobre arquivos de texto gerados. + +```python +from pathlib import Path +from tempfile import TemporaryDirectory + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + reports_dir = workspace / "reports" + reports_dir.mkdir() + + report_path = reports_dir / "summary.txt" + report_path.write_text("status=ready\n", encoding="utf-8") + + for path in sorted(reports_dir.glob("*.txt")): + print(path.name, path.read_text(encoding="utf-8").strip()) +``` + +A ideia principal não é apenas uma sintaxe menor. + +O programa usa uma única abstração de caminho para: + +```text +construir + ↓ +criar + ↓ +escrever + ↓ +descobrir + ↓ +ler +``` + +Isso deixa a intenção do filesystem visível de ponta a ponta. + +## 25. Exercício + +Crie um programa usando `TemporaryDirectory` e `Path` que: + +1. crie um diretório chamado `study`; +2. crie `notes` e `archive` dentro dele; +3. escreva dois arquivos `.txt` dentro de `notes`; +4. liste os filhos diretos de `notes` em ordem; +5. encontre todos os `.txt` abaixo de `study` recursivamente; +6. imprima cada caminho encontrado de forma relativa a `study`; +7. leia um arquivo usando UTF-8; +8. não deixe arquivos permanentes. + +Depois responda: + +- Quais caminhos são relativos? +- Quais operações deste exercício realmente acessam ou alteram o sistema de arquivos, e quais são apenas operações estruturais de caminho, como composição de caminhos ou `relative_to()`? +- Por que verificar `.exists()` antes não garante que `.read_text()` funcionará depois? +- Quando `PureWindowsPath` seria útil no lugar de `Path`? + +## 26. Checklist de revisão + +Antes de avançar, confirme que você consegue explicar: + +- o que um objeto `Path` representa; +- por que `/` é útil para composição; +- caminhos relativos e absolutos; +- diretório de trabalho versus localização do arquivo-fonte; +- `.name`, `.stem`, `.suffix`, `.parent` e `.parts`; +- `read_text()` e `write_text()`; +- `mkdir(parents=True, exist_ok=True)`; +- `.exists()`, `.is_file()` e `.is_dir()`; +- por que verificações não são garantias; +- `iterdir()`, `glob()` e `rglob()`; +- por que uma saída determinística pode exigir `sorted()`; +- `with_name()` e `with_suffix()`; +- a finalidade de `resolve()`; +- a diferença entre `Path` e caminhos puros; +- por que `pathlib` complementa, em vez de substituir totalmente, `os` e `shutil`. + +## Referência rápida + +```python +from pathlib import Path + +path = Path("reports") / "summary.txt" + +path.name +path.stem +path.suffix +path.parent +path.parts + +Path.cwd() +Path.home() + +path.exists() +path.is_file() +path.is_dir() + +path.read_text(encoding="utf-8") +path.write_text("text\n", encoding="utf-8") + +directory.mkdir(parents=True, exist_ok=True) + +list(directory.iterdir()) +list(directory.glob("*.txt")) +list(directory.rglob("*.txt")) + +path.with_name("other.txt") +path.with_suffix(".json") +path.resolve() +``` + +## Exemplos executáveis + +- [`examples/path_parts.py`](examples/path_parts.py) +- [`examples/text_workspace.py`](examples/text_workspace.py) +- [`examples/discover_python_files.py`](examples/discover_python_files.py) +- [`examples/inspect_paths.py`](examples/inspect_paths.py) + +Os exemplos são determinísticos e usam apenas operações estruturais de caminhos ou diretórios temporários, então não deixam arquivos persistentes. + +## Próximo capítulo + +Continue com **Capítulo 02: `datetime` e Cálculos de Tempo**, onde a biblioteca padrão adiciona objetos explícitos para datas, horários, durações, parsing, formatação e aritmética de datas. + +## Referências oficiais + +- [Python 3.14 `pathlib` - caminhos de sistema de arquivos orientados a objetos](https://docs.python.org/3.14/library/pathlib.html) +- [Python 3.14 `os.PathLike` e `os.fspath()`](https://docs.python.org/3.14/library/os.html#os.PathLike) +- [Python 3.14 função embutida `open()`](https://docs.python.org/3.14/library/functions.html#open) diff --git a/standard-library/01-pathlib/examples/discover_python_files.py b/standard-library/01-pathlib/examples/discover_python_files.py new file mode 100644 index 0000000..fa63a78 --- /dev/null +++ b/standard-library/01-pathlib/examples/discover_python_files.py @@ -0,0 +1,16 @@ +from pathlib import Path +from tempfile import TemporaryDirectory + + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + source_dir = workspace / "src" + tools_dir = source_dir / "tools" + tools_dir.mkdir(parents=True) + + (source_dir / "app.py").write_text("print('app')\n", encoding="utf-8") + (tools_dir / "helper.py").write_text("VALUE = 1\n", encoding="utf-8") + (tools_dir / "notes.txt").write_text("notes\n", encoding="utf-8") + + for path in sorted(source_dir.rglob("*.py")): + print(path.relative_to(workspace)) diff --git a/standard-library/01-pathlib/examples/inspect_paths.py b/standard-library/01-pathlib/examples/inspect_paths.py new file mode 100644 index 0000000..a517fba --- /dev/null +++ b/standard-library/01-pathlib/examples/inspect_paths.py @@ -0,0 +1,12 @@ +from pathlib import Path +from tempfile import TemporaryDirectory + + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + file_path = workspace / "lesson.txt" + file_path.write_text("pathlib", encoding="utf-8") + + print(f"File exists: {file_path.exists()}") + print(f"Is file: {file_path.is_file()}") + print(f"Workspace is directory: {workspace.is_dir()}") diff --git a/standard-library/01-pathlib/examples/path_parts.py b/standard-library/01-pathlib/examples/path_parts.py new file mode 100644 index 0000000..747b95c --- /dev/null +++ b/standard-library/01-pathlib/examples/path_parts.py @@ -0,0 +1,10 @@ +from pathlib import Path + + +report_path = Path("reports") / "2026" / "summary.txt" + +print(f"Path: {report_path}") +print(f"Name: {report_path.name}") +print(f"Stem: {report_path.stem}") +print(f"Suffix: {report_path.suffix}") +print(f"Parent: {report_path.parent}") diff --git a/standard-library/01-pathlib/examples/text_workspace.py b/standard-library/01-pathlib/examples/text_workspace.py new file mode 100644 index 0000000..6ee0340 --- /dev/null +++ b/standard-library/01-pathlib/examples/text_workspace.py @@ -0,0 +1,13 @@ +from pathlib import Path +from tempfile import TemporaryDirectory + + +with TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + notes_dir = workspace / "notes" + notes_dir.mkdir() + + notes_path = notes_dir / "pathlib.txt" + notes_path.write_text("Paths are objects.\n", encoding="utf-8") + + print(notes_path.read_text(encoding="utf-8").strip()) diff --git a/standard-library/README.es.md b/standard-library/README.es.md new file mode 100644 index 0000000..cf8cec1 --- /dev/null +++ b/standard-library/README.es.md @@ -0,0 +1,101 @@ +
+ +# Biblioteca Estándar + +[🇺🇸 English](README.md) · [🇧🇷 Português](README.pt-BR.md) · [🇪🇸 Español](README.es.md) + +
+ +Python incluye una biblioteca estándar amplia. Estos módulos resuelven problemas comunes sin requerir instalación de terceros, pero cada herramienta mantiene sus propios contratos, trade-offs y modos de fallo. + +La Fase 8 parte del modelo de imports aprendido en la Fase 7 y estudia un conjunto enfocado de módulos frecuentes en programas Python reales. + +## Ruta de aprendizaje + +| Capítulo | Foco principal | Nivel | Estado | +|---|---|---|---| +| [01. `pathlib`](01-pathlib/README.es.md) | Representar, componer, inspeccionar, crear, leer y descubrir rutas del sistema de archivos con objetos específicos para rutas | Intermedio | Disponible | +| 02. `datetime` | Trabajar con fechas, horas, duraciones, parsing, formato y aritmética | Intermedio | Planificado | +| 03. `json` | Usar el módulo `json` más allá de la persistencia básica, incluidas opciones de serialización y contratos más estrictos | Intermedio | Planificado | +| 04. `csv` | Trabajar con dialectos CSV, quoting, readers, writers y límites de texto tabular | Intermedio | Planificado | +| 05. `logging` | Configurar loggers, handlers, formatters, niveles y logging de aplicación frente a biblioteca | Intermedio | Planificado | +| 06. `collections` | Usar contenedores especializados como `Counter`, `defaultdict` y `deque` | Intermedio | Planificado | +| 07. `itertools` | Construir pipelines eficientes de iteradores con herramientas reutilizables | Intermedio | Planificado | +| 08. `decimal` | Realizar aritmética decimal exacta con redondeo y contexto explícitos | Intermedio | Planificado | +| 09. `os` y `shutil` | Trabajar con entorno, operaciones de filesystem de nivel más bajo, copia, movimiento y árboles de directorios | Intermedio | Planificado | + +## Prerrequisitos + +Antes de comenzar esta fase conviene dominar: + +- funciones y valores de retorno; +- colecciones e iteración; +- excepciones; +- archivos y context managers; +- imports, módulos y paquetes. + +La ruta completa de las Fases 1-7 proporciona esas bases. + +## Secuencia recomendada + +Al seguir el currículo completo, estudia en orden: + +```text +01. Modelar rutas con pathlib + ↓ +02. Modelar fechas y duraciones con datetime + ↓ +03. Profundizar JSON + ↓ +04. Profundizar CSV + ↓ +05. Configurar logging en runtime + ↓ +06. Usar colecciones especializadas + ↓ +07. Componer pipelines de iteradores + ↓ +08. Usar aritmética decimal exacta + ↓ +09. Trabajar con utilidades de OS y filesystem +``` + +El orden es intencional. Empieza con trabajo familiar de archivos y continúa por tiempo, formatos de datos, diagnóstico, contenedores, iteración, precisión numérica y utilidades de sistema de nivel más bajo. + +## Objetivos de la sección + +Al final de la Fase 8 deberías poder: + +- elegir herramientas de la biblioteca estándar en lugar de reinventar infraestructura común; +- leer la documentación oficial de módulos con mayor confianza; +- entender que el nombre de un módulo no es un contrato completo de uso; +- combinar módulos de la biblioteca estándar con funciones, excepciones, archivos y paquetes; +- reconocer APIs superpuestas y elegir según la intención; +- preservar comportamiento determinista cuando orden y entorno pueden variar; +- escribir programas pequeños que dependan solo de Python y su biblioteca estándar. + +## Estado de la fase + +La Fase 8 está en progreso. El Capítulo 01 introduce [`pathlib`](01-pathlib/README.es.md) como el primer módulo estudiado de forma enfocada. + +Los capítulos posteriores revisitarán `json`, `csv` y `logging` a un nivel más profundo de biblioteca. Sus apariciones anteriores enseñaron formatos de archivo o conceptos más amplios de diseño; en esta fase estudiamos los módulos, sus APIs y sus trade-offs. + +## Estructura del directorio + +```text +standard-library/ +├── README.md +├── README.pt-BR.md +├── README.es.md +└── 01-pathlib/ + ├── README.md + ├── README.pt-BR.md + ├── README.es.md + └── examples/ + ├── discover_python_files.py + ├── inspect_paths.py + ├── path_parts.py + └── text_workspace.py +``` + +Se añadirán nuevos directorios de capítulos a medida que avance la fase. diff --git a/standard-library/README.md b/standard-library/README.md index 323f8a9..03fec63 100644 --- a/standard-library/README.md +++ b/standard-library/README.md @@ -1,5 +1,101 @@ +
+ # Standard Library -Guides to useful modules distributed with Python, including `pathlib`, `datetime`, `json`, `csv`, `logging`, `collections`, `itertools`, `decimal`, `os`, and `shutil`. +[🇺🇸 English](README.md) · [🇧🇷 Português](README.pt-BR.md) · [🇪🇸 Español](README.es.md) + +
+ +Python ships with a broad standard library. These modules solve common problems without requiring third-party installation, but each tool still has its own contracts, trade-offs, and failure modes. + +Phase 8 builds on the import model from Phase 7 and studies a focused set of modules that appear frequently in real Python programs. + +## Learning path + +| Chapter | Main focus | Level | Status | +|---|---|---|---| +| [01. `pathlib`](01-pathlib/README.md) | Represent, compose, inspect, create, read, and discover filesystem paths with path-aware objects | Intermediate | Available | +| 02. `datetime` | Work with dates, times, durations, parsing, formatting, and arithmetic | Intermediate | Planned | +| 03. `json` | Use the `json` module beyond basic file persistence, including serialization options and stricter contracts | Intermediate | Planned | +| 04. `csv` | Work with CSV dialects, quoting, readers, writers, and tabular text boundaries | Intermediate | Planned | +| 05. `logging` | Configure loggers, handlers, formatters, levels, and application versus library logging | Intermediate | Planned | +| 06. `collections` | Use specialized containers such as `Counter`, `defaultdict`, and `deque` | Intermediate | Planned | +| 07. `itertools` | Build efficient iterator pipelines with reusable iteration tools | Intermediate | Planned | +| 08. `decimal` | Perform exact decimal arithmetic with explicit rounding and context | Intermediate | Planned | +| 09. `os` and `shutil` | Work with environment, low-level filesystem operations, copying, moving, and directory trees | Intermediate | Planned | + +## Prerequisite guidance + +Before starting this phase, learners should be comfortable with: + +- functions and return values; +- collections and iteration; +- exceptions; +- files and context managers; +- imports, modules, and packages. + +The complete path through Phases 1-7 provides those foundations. + +## Recommended sequence + +Study the chapters in order when following the complete curriculum: + +```text +01. Model filesystem paths with pathlib + ↓ +02. Model dates and durations with datetime + ↓ +03. Deepen JSON handling + ↓ +04. Deepen CSV handling + ↓ +05. Configure runtime logging + ↓ +06. Use specialized collections + ↓ +07. Compose iterator pipelines + ↓ +08. Use exact decimal arithmetic + ↓ +09. Work with OS and filesystem utilities +``` + +The order is intentional. It starts from familiar file-oriented work, then moves through time, data formats, diagnostics, containers, iteration, numeric precision, and lower-level system utilities. + +## Section goals + +By the end of Phase 8, you should be able to: + +- choose standard-library tools instead of reinventing common infrastructure; +- read official module documentation with more confidence; +- understand that a module name is not a complete usage contract; +- combine standard-library modules with functions, exceptions, files, and packages; +- recognize overlapping APIs and choose by intent; +- preserve deterministic behavior where order and environment can vary; +- write small programs that rely only on Python and its standard library. + +## Phase status + +Phase 8 is in progress. Chapter 01 introduces [`pathlib`](01-pathlib/README.md) as the first focused standard-library module. + +Later chapters will revisit `json`, `csv`, and `logging` at a deeper library level. Their earlier appearances taught file formats or broader design concepts; this phase studies the modules themselves, their APIs, and their trade-offs. + +## Directory structure + +```text +standard-library/ +├── README.md +├── README.pt-BR.md +├── README.es.md +└── 01-pathlib/ + ├── README.md + ├── README.pt-BR.md + ├── README.es.md + └── examples/ + ├── discover_python_files.py + ├── inspect_paths.py + ├── path_parts.py + └── text_workspace.py +``` -> Status: planned. +New chapter directories will be added as the phase progresses. diff --git a/standard-library/README.pt-BR.md b/standard-library/README.pt-BR.md new file mode 100644 index 0000000..76fa0a1 --- /dev/null +++ b/standard-library/README.pt-BR.md @@ -0,0 +1,101 @@ +
+ +# Biblioteca Padrão + +[🇺🇸 English](README.md) · [🇧🇷 Português](README.pt-BR.md) · [🇪🇸 Español](README.es.md) + +
+ +O Python inclui uma biblioteca padrão ampla. Esses módulos resolvem problemas comuns sem exigir instalação de terceiros, mas cada ferramenta ainda possui contratos, trade-offs e modos de falha próprios. + +A Fase 8 parte do modelo de imports aprendido na Fase 7 e estuda um conjunto focado de módulos muito presentes em programas Python reais. + +## Trilha de aprendizagem + +| Capítulo | Foco principal | Nível | Status | +|---|---|---|---| +| [01. `pathlib`](01-pathlib/README.pt-BR.md) | Representar, compor, inspecionar, criar, ler e descobrir caminhos do sistema de arquivos com objetos próprios para caminhos | Intermediário | Disponível | +| 02. `datetime` | Trabalhar com datas, horários, durações, parsing, formatação e aritmética | Intermediário | Planejado | +| 03. `json` | Usar o módulo `json` além da persistência básica, incluindo opções de serialização e contratos mais estritos | Intermediário | Planejado | +| 04. `csv` | Trabalhar com dialetos CSV, quoting, readers, writers e fronteiras de texto tabular | Intermediário | Planejado | +| 05. `logging` | Configurar loggers, handlers, formatters, níveis e logging de aplicação versus biblioteca | Intermediário | Planejado | +| 06. `collections` | Usar contêineres especializados como `Counter`, `defaultdict` e `deque` | Intermediário | Planejado | +| 07. `itertools` | Construir pipelines eficientes de iteradores com ferramentas reutilizáveis | Intermediário | Planejado | +| 08. `decimal` | Executar aritmética decimal exata com arredondamento e contexto explícitos | Intermediário | Planejado | +| 09. `os` e `shutil` | Trabalhar com ambiente, operações de filesystem de nível mais baixo, cópia, movimentação e árvores de diretórios | Intermediário | Planejado | + +## Pré-requisitos + +Antes de iniciar esta fase, é importante estar confortável com: + +- funções e valores de retorno; +- coleções e iteração; +- exceções; +- arquivos e context managers; +- imports, módulos e pacotes. + +A trilha completa pelas Fases 1-7 fornece essa base. + +## Sequência recomendada + +Ao seguir o currículo completo, estude em ordem: + +```text +01. Modelar caminhos com pathlib + ↓ +02. Modelar datas e durações com datetime + ↓ +03. Aprofundar JSON + ↓ +04. Aprofundar CSV + ↓ +05. Configurar logging em runtime + ↓ +06. Usar coleções especializadas + ↓ +07. Compor pipelines de iteradores + ↓ +08. Usar aritmética decimal exata + ↓ +09. Trabalhar com utilitários de OS e filesystem +``` + +A ordem é intencional. Ela parte de um trabalho já familiar com arquivos e avança por tempo, formatos de dados, diagnóstico, contêineres, iteração, precisão numérica e utilitários de sistema de nível mais baixo. + +## Objetivos da seção + +Ao final da Fase 8, você deverá conseguir: + +- escolher ferramentas da biblioteca padrão em vez de reinventar infraestrutura comum; +- ler a documentação oficial dos módulos com mais segurança; +- entender que o nome de um módulo não é um contrato completo de uso; +- combinar módulos da biblioteca padrão com funções, exceções, arquivos e pacotes; +- reconhecer APIs que se sobrepõem e escolher pela intenção; +- preservar comportamento determinístico quando ordem e ambiente podem variar; +- escrever programas pequenos que dependam apenas do Python e de sua biblioteca padrão. + +## Status da fase + +A Fase 8 está em andamento. O Capítulo 01 introduz [`pathlib`](01-pathlib/README.pt-BR.md) como o primeiro módulo estudado de forma focada. + +Capítulos posteriores revisitarão `json`, `csv` e `logging` em um nível mais profundo de biblioteca. As aparições anteriores ensinaram formatos de arquivo ou conceitos maiores de design; nesta fase estudamos os módulos, suas APIs e seus trade-offs. + +## Estrutura do diretório + +```text +standard-library/ +├── README.md +├── README.pt-BR.md +├── README.es.md +└── 01-pathlib/ + ├── README.md + ├── README.pt-BR.md + ├── README.es.md + └── examples/ + ├── discover_python_files.py + ├── inspect_paths.py + ├── path_parts.py + └── text_workspace.py +``` + +Novos diretórios de capítulos serão adicionados conforme a fase avançar.