How Django’s listdir() Separates Files and Folders

When working on projects like the CS50 Wiki, you often come across this line:

_, filenames = default_storage.listdir("entries")

At first glance, it feels like magic:

🤔 How does Django know which are files and which are folders?
🤔 Where are these two lists coming from?

Let’s break it down step by step with proper context.

---

🧩 Initial Context (Real Use Case)

In the Wiki project, you store entries like this:

entries/
  Python.md
  Django.md
  HTML.md

Your goal is:

👉 Get a list of all encyclopedia entry names (without .md)

So you write:

def list_entries():
    _, filenames = default_storage.listdir("entries")
    return list(sorted(
        re.sub(r"\.md$", "", filename)
        for filename in filenames if filename.endswith(".md")
    ))

---

❗ The Big Question

Where do these two lists come from?

_, filenames = default_storage.listdir("entries")

Why not just one list?

---

🔍 The Answer Lies Inside Django

This behavior is defined in Django’s internal class:

FileSystemStorage.listdir()

📍 Located in:

django/core/files/storage.py

---

⚙️ Django’s Internal Logic (Simplified)

Here’s a simplified version of what Django actually does:

def listdir(self, path):
    full_path = self.path(path)

    directories = []
    files = []

    for entry in os.listdir(full_path):
        full_entry_path = os.path.join(full_path, entry)

        if os.path.isdir(full_entry_path):
            directories.append(entry)
        else:
            files.append(entry)

    return directories, files

---

🧠 Step-by-Step Understanding

1. Django looks inside the folder

os.listdir(full_path)

👉 Gets everything inside "entries"
(both files and folders)

---

2. It creates two empty lists

directories = []
files = []

---

3. It checks each item

if os.path.isdir(full_entry_path):

👉 Uses the OS to decide:

• Folder → goes to directories
• File → goes to files

---

4. It returns BOTH lists

return directories, files

---

📂 Example

Suppose your folder looks like:

entries/
  Python.md
  Django.md
  drafts/
  notes.txt

Django will return:

(["drafts"], ["Python.md", "Django.md", "notes.txt"])

---

🔄 How YOUR code uses it

_, filenames = default_storage.listdir("entries")

This means:

• _ → ignore folders (["drafts"])
• filenames → keep files (["Python.md", "Django.md", "notes.txt"])

---

🔍 Final Filtering Happens Here

if filename.endswith(".md")

👉 Keeps only:

["Python.md", "Django.md"]

---

🎯 Final Output

After removing .md:

["Django", "Python"]

---

⚡ Key Takeaways

• Django explicitly creates two lists:
  • 📁 directories
  • 📄 files
• It uses:

  os.path.isdir()
  

  to decide where each item goes

• You control what to use:

  _, filenames = ...
  

---

💡 Simple Mental Model

Think of Django doing this:

🧺 “Here are two baskets:
one for folders, one for files — you choose what you want.”

---

🚀 Bonus Insight

Even if you switch to cloud storage (like AWS S3):

• Django still returns (directories, files)
• But internally it may simulate folders

---