Should iterator methods be added to the individual object class or the container class?

[Rajeev Bagra]

When beginners first learn Python iterators, one common confusion appears almost immediately:

Should __iter__() and __next__() be defined inside the Book class
or inside the Bookshelf class?

At first glance, both classes seem related to books, so it may not feel obvious where iteration logic belongs.

However, understanding the difference between:

• a single entity
• a collection of entities

makes the design decision much clearer.

---

Understanding What Iteration Really Means

Iteration simply means:

Accessing multiple items one by one

For example:

for number in numbers:

Python retrieves:

• first item
• second item
• third item

So before implementing iterator methods, one important question should be asked:

Which object actually contains multiple items?

---

The Book Class Represents One Item

Consider:

class Book:

A Book object typically stores:

• one title
• one author
• one page count

Example:

b1 = Book("Python Basics", "Alex", 200)

This object represents only one book.

It is a single entity.

---

The Bookshelf Class Represents a Collection

Now consider:

class Bookshelf:

Inside the bookshelf:

self._books = []

This list can contain:

• Book 1
• Book 2
• Book 3
• many more books

This makes the bookshelf a collection object.

---

The Key Design Question

Before adding:

__iter__()

or:

__next__()

developers should ask:

Which object should naturally work inside a for loop?

---

This Feels Natural

for book in shelf:

Why?

Because:

• a shelf contains many books
• iteration retrieves one book at a time

This makes logical sense.

---

This Feels Strange

for item in book:

Why does this feel unusual?

Because a single book is not normally treated as a collection.

A book is already one item.

---

Rule of Thumb

A very useful beginner rule is:

Object Type	Usually Iterable?
Single entity	No
Collection/container	Yes

---

Why Iteration Belongs in Bookshelf

Inside the bookshelf:

self._books = []

This internal list stores multiple objects.

Therefore:

def __iter__(self):

and:

def __next__(self):

naturally belong inside:

class Bookshelf:

The bookshelf controls traversal through the collection.

---

Real-World Analogy

Think about real-world objects:

Object	Iterable?
One student	No
Classroom	Yes
One song	No
Playlist	Yes
One book	No
Bookshelf	Yes

Iteration usually belongs to the thing containing multiple items.

---

When Could a Book Become Iterable?

Sometimes a single object internally contains multiple elements.

Example:

class Book:

    def __init__(self, chapters):
        self.chapters = chapters

Now this loop makes sense:

for chapter in book:

because the book contains multiple chapters.

In that case, implementing iteration inside the Book class would be reasonable.

---

The Core Design Principle

Good object-oriented programming often separates:

Class Type	Purpose
Entity class	Represents one thing
Container class	Stores many things

Iterator methods are usually added to container classes.

---

A Helpful Mental Model

Before writing:

__iter__()

ask:

What exactly should the loop traverse?

Examples:

Loop	Iterable Object
for student in classroom	classroom
for product in cart	cart
for book in shelf	shelf
for chapter in book	book

The iterable object is the object containing multiple items.

---

Final Thoughts

In the bookshelf example:

for book in shelf:

the bookshelf is the collection object.

Therefore:

• Bookshelf should implement iterator methods
• Book should remain a simple entity object

The easiest way to decide is to ask:

Which object logically contains multiple items that should be traversed one by one?

That object is usually the correct place for:

__iter__()
__next__()

in Python programs.

[Author]

Posts