roadmap.en.md

Python Study Guide Roadmap

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

This roadmap tracks both the educational curriculum and the repository foundation that supports it. Phase numbers describe the intended learning sequence, while repository work may prepare later sections earlier when doing so establishes useful standards.

Status legend

• Complete: the planned scope is available and reviewed.
• In progress: useful material exists, but the planned scope is not finished.
• Planned: the phase has not started as a complete learning section.

Current progress

Phase	Status	Current result
0. Project foundation	Complete	Foundation available, audited, and officially completed
1. Fundamentals	Complete	Six reviewed chapters cover execution, input/output, variables and naming, built-in data types, type inspection, and type conversion
2. Strings and numbers	Complete	Four reviewed chapters cover string creation, common methods, numeric and Boolean behavior, floating-point precision, and common numeric built-ins
3. Collections	Complete	Six reviewed chapters cover lists, tuples, dictionaries, sets, and choosing a collection by intent
4. Program flow	Complete	Eight reviewed chapters cover conditions, branching, structural pattern matching, for, iteration helpers, while, loop control, and choosing and combining flow tools by intent
5. Functions	Complete	Nine reviewed chapters cover def, calls, required inputs, returned values, scope, type hints, safe defaults, flexible arguments, function composition, and explicit data flow
6. Comments, documentation, and clean code	Complete	Six reviewed chapters are available and the pilot educational section is officially complete
7. Errors, files, and modules	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	Complete	Nine reviewed chapters cover paths, date/time, JSON, CSV, logging, specialized collections, lazy iteration, decimal arithmetic, and OS/filesystem operations
9. External libraries	Complete	Four reviewed chapters cover pandas, openpyxl, requests, and pytest with explicit dependency contracts and deterministic examples
10. Practical projects	In progress	Projects 01–05 are complete; Project 06 File Organizer is in progress with deterministic planning, collision safety, filesystem identity checks, anchored directories, and atomic no-replace commit behavior

Phases 0–9 are complete. Phase 10: Practical Projects is in progress with Expense Tracker, Grade Calculator, User Registration, CSV Analyzer, and Report Generator complete as Projects 01–05, while File Organizer is the current Project 06. The practical-project phase turns previously studied concepts into complete workflows with requirements, design decisions, implementation, validation, extension paths, and portfolio discussion.

Phase 0: Project foundation

Completed

• Multilingual root README files
• Initial scalable project structure
• Multilingual contribution guidelines
• GitHub pull request and issue templates
• Community standards and reporting guidance
• Consistent editorial chapter format
• MIT License
• Project authorship and maintenance records
• Pull-request-based workflow and protected main branch
• Repository instructions for contributors and AI agents
• Responsible AI-assisted development guide
• Multilingual roadmap and project-structure documentation
• Automated quality checks for Python files, approved examples, internal links, and repository structure
• Original visual identity and repository assets
• Final navigation, terminology, accessibility, and status audit
• Officially mark Phase 0 as complete

Planned non-blocking follow-up

• Refine and replace visual assets with high-quality exports after the final logo framing is complete.

Phase 1: Fundamentals

• How Python runs a program
• print() and input()
• Variables and naming
• Built-in data types
• type() and isinstance()
• Type conversion

Phase 2: Strings and numbers

• String creation and indexing
• Common string methods
• int, float, and bool
• Numeric built-ins: round(), abs(), min(), max(), and sum()

Phase 3: Collections

• List creation, indexing, and slicing
• Modifying lists and common list methods
• Tuples and immutability
• Dictionaries: keys and values
• Sets and unique values
• Choosing the right collection

Phase 4: Program flow

See the section learning path.

• Conditions, comparisons, and Boolean logic
• if, elif, and else
• match and case: structural pattern matching
• for loops and iteration
• range(), enumerate(), and zip()
• while loops and state-driven repetition
• break, continue, and loop else
• Choosing and combining program flow

Phase 4 intentionally builds trustworthy conditions first, uses them for conditional branching, introduces structural pattern matching, moves into repetition with for, adds helpers for numeric progressions, positions, and parallel iteration, introduces state-driven repetition with while, adds deliberate loop control with break, continue, and loop else, and closes by teaching how to choose and combine those tools according to intent. Chapters 01–08 are complete and Phase 4 is officially complete.

Phase 5: Functions

See the section learning path.

• Defining and calling functions
• Parameters and arguments
• Return values
• Scope
• Type hints
• Default values
• *args and **kwargs
• Functions working together
• Data flow between functions

Phase 5 is complete. Chapter 01 establishes def, calls, reuse, execution order, naming, pass, implicit None, and the connection with program flow. Chapter 02 adds required parameters, positional and basic keyword arguments, argument expressions, call errors, and input-flow tracing. Chapter 03 adds return, reusable results, branch-specific and early returns, None, and tuple returns. Chapter 04 adds local and global names, function-local namespaces, lookup, shadowing, NameError, UnboundLocalError, and cautious use of global. Chapter 05 adds parameter and return annotations, built-in and collection type hints, -> None, str | None, annotation metadata, and the distinction between static type information, runtime validation, and conversion. Chapter 06 adds default values, selective positional and keyword overrides, definition-time evaluation, the mutable-default trap, and the safe None pattern for fresh mutable objects. Chapter 07 adds variable-length positional and keyword argument collection with *args and **kwargs, tuple and dictionary behavior inside the function, simple mixed signatures, basic type hints for collected values, and the distinction between definition-side collection and later call-side unpacking. Chapter 08 composes helpers and coordinating functions, passes returned results between steps, keeps dependencies explicit through parameters and returns, combines functions with conditions and loops, distinguishes reusable calculation from presentation, and introduces simple call graphs. Chapter 09 closes the phase by tracing caller-to-parameter-to-return flow, local parameter bindings, rebinding versus mutation, tuple and None results, explicit pipelines, collection transformations, and the difference between call graphs and data-flow traces.

Phase 6: Comments, documentation, and clean code

See the section learning path.

• When and why to comment
• When not to comment
• Useful and harmful comments
• Docstrings
• Meaningful names and self-explanatory code
• TODO, FIXME, NOTE, and related task markers
• Comments versus logging
• PEP 8 and readability

Phase 6 is officially complete and provides the editorial and quality model for the remaining learning sections.

Phase 7: Errors, files, and modules

See the section learning path.

• try, except, else, and finally
• raise and custom exceptions
• open() and with
• TXT, CSV, and JSON
• Imports, modules, and packages

Phase 7 is complete. Chapters 01–02 establish exception handling and deliberate signaling. Chapter 03 adds safe text-file I/O and resource lifetime. Chapter 04 adds TXT, CSV, and JSON parsing/writing with explicit data boundaries. Chapter 05 closes the phase with modules, regular packages, import namespaces and caching, __name__, the main guard, search context, absolute and relative imports, python -m, and dependency design.

Phase 8: Standard library

See the section learning path.

• pathlib
• datetime
• json
• csv
• logging
• collections
• itertools
• decimal
• os and shutil

Phase 8 is complete. Chapters 01–08 build contracts for paths, date/time, structured formats, logging, specialized collections, lazy iteration, and decimal arithmetic. Chapter 09 closes the phase by connecting those foundations to process environment state, path-like interfaces, directory scanning and traversal, metadata, copying, moving, recursive deletion, platform capabilities, and archive safety.

Phase 9: External libraries

See the section learning path.

• pandas
• openpyxl
• requests
• pytest

Phase 9 is complete. Chapter 01 introduces pandas 3.0.x for labeled tabular data. Chapter 02 adds openpyxl 3.1.x workbook automation. Chapter 03 adds Requests 2.34.x HTTP/API contracts. Chapter 04 closes the phase with pytest 9.1.x automated-testing contracts covering discovery, assertions, fixtures, parametrization, temporary resources, monkeypatching, capture, marks, deterministic isolation, and CI. Executable external-library examples use the dependency contract declared in requirements-external.txt.

Phase 10: Practical projects

See the Practical Projects section index.

• Expense Tracker
• Grade Calculator
• User Registration
• CSV Analyzer
• Report Generator
• File Organizer — current project
• Fictional Reconciliation Workflow
• Simulated Automation Flow

Project 01 establishes the Phase 10 contract with explicit requirements, validated data modeling, exact Decimal money, persistence, deterministic demonstration, automated pytest coverage, extension challenges, and portfolio discussion. Project 02 extends the contract with configurable grading rules, exact weighted aggregation, explicit partial/final reporting, and boundary-focused validation. Project 03 adds canonical identity-like data, Unicode and IDNA normalization, duplicate prevention, secondary lookup indexes, safe indexed-field updates, explicit lifecycle transitions, and mutation-focused pytest coverage without introducing authentication. Project 04 adds strict CSV schemas, typed conversion, structural-versus-row failure handling, partial-success parsing, duplicate accepted identifiers, deterministic aggregation, and filtering with standard-library CSV mechanics exposed explicitly. Project 05 adds explicit inclusive date windows, source identity validation, exact deterministic summary metrics, immutable report construction, TXT/Markdown rendering, format-specific escaping, and UTF-8 file output. Project 06 adds shallow deterministic discovery, immutable planning, suffix categories, explicit collision policies, symlink boundaries, (device, inode) identity checks, root/category descriptor anchoring, bounded staging names, and platform-aware atomic no-replace commits with Linux renameat2(RENAME_NOREPLACE).

Each project should include:

• requirements;
• design notes;
• implementation;
• explanation;
• automated test coverage for important behavior;
• extension challenges;
• portfolio discussion.

Ongoing quality gates

Every phase should preserve:

• technical accuracy;
• multilingual consistency;
• original and public-safe examples;
• privacy-safe data;
• executable Python examples when appropriate;
• internal navigation integrity;
• PEP 8 awareness;
• documentation of meaningful structure changes;
• honest dependency and version assumptions.

The roadmap will evolve as the project grows, but changes should preserve the progression from beginner concepts to integrated practical work.