Cross-Platform Path Handling with pathlib

Introduction: Why pathlib Is Essential

In Lesson 2, you learned to read and write files using context managers. But there's a problem you might have glossed over: how do you construct file paths?

If you're on Windows, paths use backslashes: C:\Users\YourName\Documents\notes.txt. On Mac and Linux, they use forward slashes: /home/yourname/documents/notes.txt. If you hardcode paths in your code like this:

Loading Python environment...

Your code breaks on other systems. This isn't a theoretical problem—it's real. When you share code with colleagues, deploy to a server, or try to run your application on a different operating system, hardcoded paths fail.

The solution is pathlib, Python's modern way to handle file paths. Instead of treating paths as strings, pathlib gives you Path objects that understand your operating system and automatically use the correct separators. Write once, run anywhere—that's the promise of pathlib.

This lesson teaches you to work with paths as first-class Python objects, check if files exist, create directories, find files by pattern, and prevent security vulnerabilities. By the end, you'll be able to build file-based applications that work reliably across Windows, Mac, and Linux.

Understanding pathlib vs os.path: A Better Way to Build Paths

For decades, Python programmers used the os.path module to work with file paths. It works, but it's awkward. Here's why pathlib is better:

With os.path (old approach):

Loading Python environment...

With pathlib (modern approach):

Loading Python environment...

Notice the difference? With pathlib:

• You use the / operator to join paths (intuitive and readable)
• Path objects have methods like .exists(), .read_text(), .write_text()
• The same code works on Windows, Mac, and Linux without modification
• Path objects are immutable—operations return new Path objects

This is an example of object-oriented thinking: paths aren't just strings, they're objects with capabilities. You'll see this pattern throughout professional Python code.

💬 AI Colearning Prompt

"Explain how the / operator works with Path objects. Why is this better than using string concatenation like "config" + "/" + "app.json"?"

Expected Outcome: You'll understand that Path objects handle OS-specific separators automatically, making your code cross-platform.

Creating and Manipulating Paths

Let's start with the fundamentals: creating Path objects and accessing their properties.

Creating Path objects is straightforward:

Loading Python environment...

The / operator is the key insight here. Instead of worrying about backslashes or forward slashes, you just use / and Python handles the OS-specific details.

Path properties let you extract useful information:

Loading Python environment...

These properties are useful for extracting information about files without having to manually parse strings.

🎓 Expert Insight

In AI-native development, you don't hardcode paths with backslashes or forward slashes—you use pathlib. The syntax is cheap; understanding that your code must work on Windows, Mac, AND Linux is gold. Your AI can generate paths; your job is specifying the directory structure.

Checking Existence and File Types: Defensive Programming

Before you try to read a file, it's wise to check that it actually exists. This prevents crashes from attempting to open files that don't exist.

Loading Python environment...

Here's a practical pattern: check before operating:

Loading Python environment...

This defensive approach prevents your program from crashing when files or directories are missing.

Creating Directories: Building Nested Structures

Often, your application needs to organize files into directories. Rather than creating directories manually, you can ask Python to create them.

The .mkdir() method has two important parameters:

• parents=True — Create parent directories if they don't exist
• exist_ok=True — Don't raise an error if the directory already exists

Loading Python environment...

Without these parameters, .mkdir() would fail if parent directories don't exist:

Loading Python environment...

Here's a practical pattern for applications that organize data by category:

Loading Python environment...

This pattern will be essential for your Capstone project (Lesson 5).

🚀 CoLearning Challenge

Ask your AI Co-Teacher:

"Generate code that creates a directory structure for 5 projects, each with 'src', 'tests', and 'docs' subdirectories. Then show me how to use glob() to count total Python files across all projects."

Expected Outcome: You'll see pathlib for scaling (creating many dirs) and glob for discovering files across your entire project structure.

Finding Files with Glob Patterns

You now know how to create directories and check if files exist. Next: how do you find files matching a pattern?

The .glob() method searches for files matching a pattern. This is powerful for applications that need to discover files dynamically.

Basic glob patterns:

Loading Python environment...

Common glob patterns:

• *.txt — All files ending in .txt
• *.py — All Python files
• test_* — All files starting with "test_"
• * — All items in the directory
• **/*.txt — All .txt files recursively (Python 3.12+) [research current version]

Using .glob() instead of manually listing files is more maintainable: your code doesn't hardcode filenames, it discovers them dynamically.

✨ Teaching Tip

Use Claude Code to explore glob patterns: "What would data/**/2025/*.txt match in a directory tree? Show me an example of a directory structure and which files it would find."

Code Example 3.1: Creating Paths with pathlib

Let's write code that demonstrates Path object creation and properties. This example shows how pathlib handles cross-platform compatibility automatically.

Specification: Create paths using different syntax, access properties, and show how pathlib abstracts away OS-specific separators.

Prompt: "Show me how to create and manipulate file paths using pathlib, including accessing properties like name, suffix, and parent."

Loading Python environment...

Expected Output (on Mac/Linux):

Full path: config/app.json
File name: app.json
Suffix: .json
Stem: app
Parent: config
Cross-platform path: data/notes/personal
Path type: <class 'pathlib.PosixPath'>

Validation Steps:

1. Path objects are created successfully
2. The / operator works as expected
3. Properties return correct values
4. Same code produces correct paths on different operating systems

Key Insight: Notice that .parent returns a Path object, not a string. This means you can chain operations: config_file.parent.parent to go up multiple levels.

Code Example 3.2: Checking File Existence and Type

This example demonstrates the defensive programming pattern: always check if files/directories exist before operating on them.

Specification: Create validation checks for files and directories, showing the pattern for safe file operations.

Prompt: "Show me how to check if files and directories exist before operations using pathlib, and how to distinguish between files and directories."

Loading Python environment...

Expected Output (if paths don't exist):

Does config.json exist? False
Does data exist? False
Creating data because it doesn't exist
data already exists
data contains 0 items

Validation Steps:

1. .exists() correctly reports missing files
2. .is_file() and .is_dir() distinguish types
3. Directory can be created safely
4. Subsequent existence checks show created directory

Key Insight: This pattern prevents crashes. Your code never tries to read missing files or create existing directories.

Code Example 3.3: Creating Nested Directories

This example shows how to safely create multi-level directory structures—essential for the capstone project that organizes notes by category.

Specification: Create nested directories with parents=True, exist_ok=True, demonstrate the pattern for building application directory structures.

Prompt: "Show me how to create nested directories safely, including when parent directories don't exist. Demonstrate creating multiple category subdirectories."

Loading Python environment...

Expected Output:

Created: data/notes/2025/november
Created: data/notes/2025/november/work
Created: data/notes/2025/november/personal
Created: data/notes/2025/november/learning

Directory structure created at: data/notes/2025/november
Subdirectories: ['work', 'personal', 'learning']

Validation Steps:

1. All directories created (including parents)
2. Running again doesn't error (exist_ok=True works)
3. .iterdir() correctly lists created subdirectories
4. Structure is exactly what was specified

Key Insight: This pattern is used in Lesson 5's Capstone project to organize notes by category. You can create complex directory hierarchies programmatically.

Code Example 3.4: Finding Files with Glob Patterns

This example demonstrates how to search for files dynamically using glob patterns—critical for applications that need to discover files without hardcoding paths.

Specification: Create sample files and demonstrate glob patterns to find specific file types.

Prompt: "Show me how to find all files matching a pattern in a directory using glob(). Demonstrate finding files by extension."

Loading Python environment...

Expected Output:

Found 3 .txt files:
  - meeting.txt
  - todo.txt
  - archive.txt

All files in notes:
  Files: ['meeting.txt', 'todo.txt', 'notes.md', 'archive.txt']

Summary: 3 .txt files, 1 .md files

Validation Steps:

1. Files are created successfully
2. Glob pattern *.txt finds only .txt files
3. Glob pattern * finds all files
4. File counting works correctly

Key Insight: Using glob patterns makes your code flexible. If new files are added to the directory, your code automatically discovers them without modification.

Code Example 3.5: Path Traversal Security and Validation

This is the most important example. When users provide file paths as input, malicious users might try to access files outside your intended directory (path traversal attack). This example shows how to defend against that.

Specification: Implement secure path validation that prevents users from accessing files outside an allowed base directory.

Prompt: "Show me how to safely read files from a user-provided path without allowing access outside a directory. Include security validation using .resolve() and .is_relative_to()."

Loading Python environment...

Expected Output:

=== Safe Access ===
Read: Important note

=== Attempted Path Traversal ===
Security error: Attempted access outside allowed directory

=== Another Traversal Attempt ===
Security error: Attempted access outside allowed directory

Validation Steps:

1. Safe file access works (note1.txt is read)
2. Path traversal with ../../etc/passwd is blocked
3. Relative path tricks with ../outside_file.txt are blocked
4. .resolve() canonicalizes paths before checking

Key Insight: This pattern is critical for applications that take user input for filenames. The two-step process:

1. Resolve the path to canonical form (resolves .. and .)
2. Validate the resolved path is still within the allowed base directory

This prevents attackers from escaping your intended directory.

Practice Exercise 1: Create Nested Directories

Task: Create a nested directory structure projects/2025/november using pathlib with mkdir(parents=True, exist_ok=True). Verify the directories exist using .exists().

Acceptance Criteria:

• All directories created successfully
• Running the code twice doesn't error (exist_ok=True works)
• .exists() returns True for created directories

Validation Approach:

Loading Python environment...

Practice Exercise 2: List Files by Extension

Task: Create a directory with several files of different types (.txt, .py, .md). Write code using .glob() to count how many files exist of each type.

Acceptance Criteria:

• Code creates at least 3 files of different types
• .glob() patterns correctly identify files by extension
• Counts are accurate

Validation Approach:

Loading Python environment...

Practice Exercise 3: Path Validation Preventing Traversal

Task: Implement a simple version of the read_note() function from Code Example 3.5. Test it with both safe filenames and attempted path traversal patterns.

Acceptance Criteria:

• Safe filenames are allowed
• ../ patterns are blocked
• ../../ patterns are blocked
• Clear error messages indicate why access was denied

Validation Approach:

Loading Python environment...

Python 3.14 New Features

Python 3.14 added powerful new path manipulation methods that make file operations even easier:

• Path.copy(destination): Copy a file to a new location
• Path.copy_into(directory): Copy a file into a directory (name preserved)
• Path.move(destination): Move/rename a file atomically
• Path.move_into(directory): Move a file into a directory (name preserved)

These methods handle edge cases automatically and work recursively for directories.

Example (Python 3.14+):

Loading Python environment...

Why this matters for AI-native development: Your AI companion can now use pathlib for ALL file operations—no need to import shutil for copying/moving. Simpler code = fewer dependencies = easier to understand and maintain.

For this chapter: We focus on the core pathlib patterns that work in Python 3.4+. When you're ready to use Python 3.14+ exclusively, explore these new methods with your AI tool.

Try With AI

Master cross-platform path handling with pathlib for portable file operations.

🔍 Explore Path Portability:

"Compare string paths ('backups' + '/' + '2025' + '/' + 'january') vs pathlib (Path('backups') / '2025' / 'january'). Explain Windows backslash vs Mac/Linux forward slash issues, and why pathlib's / operator works on all platforms. Show mkdir error when parent doesn't exist."

🎯 Practice Pathlib Operations:

"Demonstrate pathlib methods: Path('data') / 'notes' / 'file.txt' for cross-platform joining, .name for filename extraction from /home/user/documents/notes.txt, .resolve() for absolute path, and .is_file() vs .is_dir() for type checking. Show why each is better than os.path."

🧪 Test Cross-Platform Features:

"Create nested directory structure backups/2025/january/data.txt using pathlib. Show mkdir(parents=True, exist_ok=True) handling missing parents, .glob('*.txt') finding files, .suffix extracting extensions, and why this works identically on Windows/Mac/Linux without platform-specific code."

🚀 Apply File Organizer:

"Build file organizer: take source directory, create backups/YYYY/MONTH/ structure, find .txt/.md files with .glob(), copy to organized backup, use recursive **/*.txt pattern for subdirectories, validate files under 10MB, show 'Organized 12 files into 3 directories' report. Pure pathlib, no os.path."

---