How do I actually get a list of files in a directory?

When you first start with the os module, you'll likely reach for os.listdir(). It's the simplest way to see what's inside a folder. It returns a list of strings representing the names of the entries in the directory you provide. If you leave the argument blank, it defaults to your current working directory.

import os

# Let's say we're looking at a folder full of reports
path = "./monthly_reports"
files = os.listdir(path)

for file in files:
    if file.endswith(".pdf"):
        print(f"Found a PDF report: {file}")

One thing to keep in mind: listdir just gives you the names. If you need to know if something is a file or a folder, or if you need the file size, you'll have to do more work. If you're dealing with thousands of files, I'd actually suggest using os.scandir() instead—it's significantly faster because it retrieves file attributes at the same time it lists the names.

I need to move files into folders based on their type. How do I handle folders and renaming?

This is where os.mkdir() and os.rename() come into play. A common mistake I see is using mkdir() and having the program crash because the folder already exists. To avoid that, you can either wrap it in a try-except block or use os.makedirs(path, exist_ok=True), which creates the directory (and any missing parent directories) without complaining if it's already there.

Here is a quick snippet of how I would handle a basic "cleanup" script that moves .txt files into a dedicated text folder:

import os

# Ensure the destination folder exists
os.makedirs("text_backups", exist_ok=True)

for filename in os.listdir("."):
    if filename.endswith(".txt"):
        # Move the file from current dir to the backup dir
        os.rename(filename, os.path.join("text_backups", filename))
        print(f"Archived {filename}")

Why does my path code work on my Mac but break when my teammate runs it on Windows?

Paths are a nightmare because Windows uses backslashes (\) and Unix-based systems (Linux, macOS) use forward slashes (/). If you hardcode your paths as strings, your code is destined to break the moment it leaves your machine.

Never manually concatenate paths with + "/" +. Instead, use os.path.join(). This function looks at the operating system the code is currently running on and inserts the correct separator automatically. I've spent way too many hours debugging "File Not Found" errors that were simply caused by a missing slash.

import os

# The wrong way: "folder/" + filename (Breaks on Windows)
# The right way:
folder = "user_data"
filename = "config.json"

full_path = os.path.join(folder, filename)
print(full_path) # Outputs 'user_data/config.json' on Mac, 'user_data\config.json' on Windows

How do I access secret API keys without hardcoding them in my script?

You should never, ever put passwords or API keys directly in your source code. If you push that to GitHub, you're asking for trouble. Instead, we use environment variables—values stored in the operating system itself. The os.environ dictionary lets you pull these values into Python.

I prefer using os.environ.get() over accessing the dictionary directly. Why? Because if the variable isn't set, os.environ['KEY'] will throw a KeyError and crash your app, while .get() will simply return None (or a default value you provide).

import os

# Pull the API key from the system environment
api_key = os.environ.get("SENDGRID_API_KEY", "default_dev_key")

if api_key == "default_dev_key":
    print("Warning: Running in dev mode with a dummy key.")
else:
    print("Production key loaded successfully.")

📋 Practical Task

Exercise: The Automated Project Structure Generator

You've been asked to write a script that standardizes how your team starts new Python projects. Instead of manually creating folders, you need to build a tool that generates a specific directory tree.

Your Task: Write a script that does the following:

• Prompts the user for a project name.
• Creates a main directory with that project name.
• Inside that main directory, creates three sub-directories: data, logs, and src.
• Inside the src folder, creates an empty file named main.py.
• Inside the logs folder, creates an empty file named app.log.

Requirements:

• Use os.makedirs() to ensure folders are created without errors.
• Use os.path.join() for all path constructions to ensure it works on any OS.
• Use a with open(...) block to create the empty files.