How to use the __str__() method in Python

The __str__ method in Python is a powerful tool for developers. It defines a human-readable string representation for your objects, which is crucial for clear output and effective debugging.

In this article, you'll learn effective techniques to implement __str__. We'll cover practical tips, real-world applications, and common debugging advice to help you master this essential Python feature.

Basic implementation of the __str__ method

class Person:
def __init__(self, name, age):
self.name = name
self.age = age

def __str__(self):
return f"Person(name={self.name}, age={self.age})"

person = Person("Alice", 30)
print(person)--OUTPUT--Person(name=Alice, age=30)

In the Person class, the __str__ method is defined to return a custom string representation of an object. When you pass the person instance to a function like print(), Python automatically calls this method to get a readable output.

This is far more useful than the default object representation, which is typically just a memory address. By implementing __str__, you gain direct control over how your objects appear when printed, making debugging and logging much more intuitive. The f-string returns a clean snapshot of the object’s attributes.

Basic __str__ implementations

While the basic implementation is useful, mastering __str__ also means understanding its use with formatted strings, how it behaves in inheritance, and how it differs from __repr__.

Using __str__ with formatted strings

class Product:
def __init__(self, name, price, quantity):
self.name = name
self.price = price
self.quantity = quantity

def __str__(self):
return f"{self.name} - ${self.price:.2f} (Qty: {self.quantity})"

product = Product("Laptop", 999.99, 5)
print(product)--OUTPUT--Laptop - $999.99 (Qty: 5)

The Product class demonstrates how you can leverage f-strings within __str__ for more polished output. This goes beyond simply listing attributes; it allows you to control the presentation of your data for better readability.

• Notice the expression f"{self.price:.2f}". The :.2f part is a format specifier that rounds the price to two decimal places, making it perfect for currency.

This technique is incredibly useful for creating clean representations of objects that handle numbers, dates, or other data types needing specific formatting.

Inheriting and overriding __str__

class Animal:
def __init__(self, species):
self.species = species

def __str__(self):
return f"Animal of species {self.species}"

class Dog(Animal):
def __init__(self, name, breed):
super().__init__("Canine")
self.name = name
self.breed = breed

def __str__(self):
return f"{self.name} is a {self.breed} dog"

dog = Dog("Rex", "Golden Retriever")
print(dog)--OUTPUT--Rex is a Golden Retriever dog

The Dog class inherits from Animal but provides its own __str__ method. This is known as overriding. When you print a Dog object, Python executes the more specific method from the subclass, giving you a tailored output instead of the generic one from the parent class.

• If the Dog class didn't define its own __str__, it would automatically use the one from Animal.
• Overriding allows you to create more descriptive and context-aware string representations for your subclasses.

Distinguishing between __str__ and __repr__

class Point:
def __init__(self, x, y):
self.x = x
self.y = y

def __str__(self):
return f"Point at ({self.x}, {self.y})"

def __repr__(self):
return f"Point({self.x}, {self.y})"

point = Point(3, 4)
print(str(point)) # Calls __str__
print(repr(point)) # Calls __repr__
print(f"{point}") # Calls __str__
print(f"{point!r}") # Calls __repr__--OUTPUT--Point at (3, 4)
Point(3, 4)
Point at (3, 4)
Point(3, 4)

The key difference between __str__ and __repr__ is their intended audience. You should think of __str__ as the informal, readable output for end-users, while __repr__ provides an official, unambiguous representation for developers, often for debugging.

• __str__ is called by print() and standard f-string formatting. Its goal is readability.
• __repr__ is called by the repr() function or with the !r flag in an f-string. Its goal is to be explicit.

If a class doesn't have a __str__ method, Python will use __repr__ as a fallback for printing.

Advanced __str__ techniques

Beyond simple attributes, a powerful __str__ method can also gracefully handle nested objects, apply conditional logic, and use custom helpers for sophisticated formatting.

Handling nested objects in __str__

class Address:
def __init__(self, street, city):
self.street = street
self.city = city

def __str__(self):
return f"{self.street}, {self.city}"

class Employee:
def __init__(self, name, address):
self.name = name
self.address = address

def __str__(self):
return f"{self.name} lives at {self.address}"

address = Address("123 Main St", "Springfield")
employee = Employee("John Smith", address)
print(employee)--OUTPUT--John Smith lives at 123 Main St, Springfield

When an object contains another object, like the Employee class holding an Address instance, __str__ can create a clean, composite output. The Employee's __str__ method doesn't need to know the details of the address. It simply includes the self.address object in its f-string.

• Python automatically calls the __str__ method of the nested Address object.
• This creates a readable, hierarchical representation without cluttering the Employee class with address-formatting logic.

Implementing conditional logic in __str__

class BankAccount:
def __init__(self, owner, balance):
self.owner = owner
self.balance = balance
self.is_overdrawn = balance < 0

def __str__(self):
status = "OVERDRAWN" if self.is_overdrawn else "in good standing"
return f"Account owned by {self.owner} with ${abs(self.balance):.2f} is {status}"

account1 = BankAccount("Alice", 1000)
account2 = BankAccount("Bob", -50)
print(account1)
print(account2)--OUTPUT--Account owned by Alice with $1000.00 is in good standing
Account owned by Bob with $50.00 is OVERDRAWN

Your __str__ method doesn't have to be a static template. You can embed conditional logic to change the output based on the object's current state. In the BankAccount example, the string representation adapts to whether the account is overdrawn, providing more meaningful feedback.

• A conditional expression (... if ... else ...) concisely determines the account's status, making the output dynamic.
• The method also uses the abs() function to display the balance as a positive number, which improves readability regardless of the account's standing.

Using custom helpers for complex __str__ formatting

class Library:
def __init__(self, name, books):
self.name = name
self.books = books

def _format_book_list(self):
if not self.books:
return "no books"
elif len(self.books) <= 2:
return " and ".join(self.books)
else:
return f"{', '.join(self.books[:-1])}, and {self.books[-1]}"

def __str__(self):
return f"{self.name} Library contains {self._format_book_list()}"

lib1 = Library("City", ["1984", "Brave New World", "Fahrenheit 451"])
lib2 = Library("School", ["Math 101", "Physics"])
lib3 = Library("Empty", [])
print(lib1)
print(lib2)
print(lib3)--OUTPUT--City Library contains 1984, Brave New World, and Fahrenheit 451
School Library contains Math 101 and Physics
Empty Library contains no books

For complex formatting, you can delegate the work to a helper method to keep your __str__ implementation clean. The Library class uses _format_book_list to handle the tricky logic of creating a natural-sounding list of books, which keeps the main __str__ method simple and readable.

• The underscore prefix in _format_book_list is a convention indicating it’s an internal helper method.
• It contains all the conditional logic for handling an empty list, a short list, or a long list with proper comma and "and" placement.
• This separation makes your code much easier to debug and maintain.

Move faster with Replit

Replit is an AI-powered development platform that transforms natural language into working applications. You can describe what you want to build, and Replit Agent creates it—complete with databases, APIs, and deployment.

The __str__ techniques in this article are perfect for building apps with clear, user-friendly outputs. Replit Agent can turn these concepts into production-ready tools:

• A bank account dashboard that uses conditional logic to dynamically display an account's status, such as 'in good standing' or 'OVERDRAWN'.
• A simple CRM that displays employee details by calling the __str__ method on a nested address object for a clean, composite output.
• An inventory management app that uses a helper method to correctly format and display a list of items, no matter the length.

Describe your app idea, and Replit Agent writes the code, tests it, and fixes issues automatically, all in your browser. Start building your next application with Replit Agent.

Common errors and challenges

Implementing __str__ is straightforward, but a few common pitfalls can trip you up, leading to unexpected errors and crashes.

Forgetting to return a string from __str__

The __str__ method has one job—to return a string. A frequent mistake is to have it return None implicitly (by not having a return statement) or another data type entirely. This will raise a TypeError because functions like print() expect a string, not something else. Always ensure your __str__ method explicitly returns a string value.

Not handling None values properly in __str__

Your object's attributes might not always have a value; sometimes they can be None. If your __str__ method tries to access an attribute of a None object (e.g., self.address.city when self.address is None), your program will crash with an AttributeError. You can prevent this by adding conditional checks to handle None values gracefully, perhaps by displaying a placeholder like "N/A".

Handling circular references in __str__

Circular references occur when two or more objects refer to each other, creating a loop. For example, an Employee object might have a manager attribute, and the manager object might have a list of employees that includes the original employee. Calling print() on either object can trigger an infinite loop as each __str__ method calls the other, eventually causing a RecursionError. A common solution is to limit the depth of the representation or to avoid printing the problematic attribute in the __str__ output.

Forgetting to return a string from __str__

The __str__ method has one non-negotiable rule: it must return a string. It’s a common slip-up to return another data type, like a tuple, instead. When functions like print() receive the wrong type, Python will raise a TypeError. The following code demonstrates this exact issue.

class Rectangle:
def __init__(self, width, height):
self.width = width
self.height = height

def __str__(self):
return (self.width, self.height) # Returning a tuple instead of a string

rect = Rectangle(10, 5)
print(rect) # This will raise TypeError

The __str__ method returns a tuple, but print() expects a string, causing a TypeError. The corrected code below shows how to properly format the output as a string to resolve this.

class Rectangle:
def __init__(self, width, height):
self.width = width
self.height = height

def __str__(self):
return f"Rectangle({self.width}x{self.height})"

rect = Rectangle(10, 5)
print(rect) # Now correctly outputs a string

The fix is straightforward: ensure the __str__ method returns a string. By using an f-string like f"Rectangle({self.width}x{self.height})", you create a properly formatted string representation that resolves the TypeError.

• This mistake often happens when you're working with multiple attributes and accidentally return a collection like a tuple. Always double-check that your return statement produces a string, not another data type.

Not handling None values properly in __str__

When an object’s attribute is None, your __str__ method can easily trigger an AttributeError. This happens if you try to call a method on that None value, causing your program to crash unexpectedly. The following code demonstrates this exact problem.

class Patient:
def __init__(self, name, diagnosis=None):
self.name = name
self.diagnosis = diagnosis

def __str__(self):
return f"Patient: {self.name}, Diagnosis: {self.diagnosis.upper()}"

patient = Patient("John Doe") # No diagnosis provided
print(patient) # Will raise AttributeError: 'NoneType' has no attribute 'upper'

The code calls the .upper() method on the diagnosis attribute. Since no diagnosis was provided, the attribute is None, leading to an AttributeError. The corrected code below shows how to handle this scenario gracefully.

class Patient:
def __init__(self, name, diagnosis=None):
self.name = name
self.diagnosis = diagnosis

def __str__(self):
diagnosis_text = "UNKNOWN" if self.diagnosis is None else self.diagnosis.upper()
return f"Patient: {self.name}, Diagnosis: {diagnosis_text}"

patient = Patient("John Doe")
print(patient) # Safely handles None value

The solution is to check if an attribute is None before calling a method on it. The corrected code uses a conditional expression to assign a fallback string like "UNKNOWN" when self.diagnosis is None. This simple check prevents the AttributeError by providing a safe default.

• It's a good practice to anticipate optional attributes, especially when working with data from external sources like databases or user input, where values can often be missing.

Handling circular references in __str__

A circular reference occurs when two objects refer to each other, creating an infinite loop when their __str__ methods are called. For example, a Parent object might reference a Child, which in turn references the Parent, causing a RecursionError.

The code below demonstrates this exact problem, where printing the parent object triggers an unstoppable cycle.

class Parent:
def __init__(self, name):
self.name = name
self.children = []

def __str__(self):
return f"Parent {self.name} with children: {self.children}"

class Child:
def __init__(self, name, parent):
self.name = name
self.parent = parent

def __str__(self):
return f"Child {self.name} with parent: {self.parent}"

parent = Parent("John")
child = Child("Emma", parent)
parent.children.append(child)
print(parent) # This will cause recursion error

The Parent's __str__ method tries to print its children list, which calls the Child's __str__. This, in turn, calls the Parent's method again, creating an infinite loop. The corrected code below shows how to fix this.

class Parent:
def __init__(self, name):
self.name = name
self.children = []

def __str__(self):
children_names = [child.name for child in self.children]
return f"Parent {self.name} with children: {children_names}"

class Child:
def __init__(self, name, parent):
self.name = name
self.parent = parent

def __str__(self):
return f"Child {self.name} with parent: {self.parent.name}"

parent = Parent("John")
child = Child("Emma", parent)
parent.children.append(child)
print(parent) # Now safely prints without recursion

The solution is to avoid calling the other object's __str__ method. Instead of printing the full object, which triggers the recursive call, you access a simple attribute like a name. This breaks the infinite loop by preventing one __str__ method from calling another.

• The Parent class now prints a list of child names, not the Child objects.
• The Child class prints just the parent's name (self.parent.name).

Keep an eye out for this in data models with bidirectional relationships, like employee-manager structures.

Real-world applications

Now that you know how to dodge the common errors, you can put __str__ to work in real-world scenarios like logging and custom collections.

Using __str__ for effective logging and debugging

A custom __str__ method is essential for effective logging, as it automatically converts your objects into readable strings that make debug messages instantly understandable.

class NetworkConnection:
def __init__(self, ip, port, status):
self.ip = ip
self.port = port
self.status = status

def __str__(self):
return f"Connection to {self.ip}:{self.port} - Status: {self.status}"

connection = NetworkConnection("192.168.1.1", 8080, "ACTIVE")
print(f"DEBUG: {connection}")

The NetworkConnection class defines a custom __str__ method. This lets you control exactly how an object of this class appears when you print it. Instead of a generic memory address, you get a neatly formatted string that summarizes the connection's current state.

• When you use an f-string like f"DEBUG: {connection}", Python automatically calls the __str__ method on the connection object.
• This gives you an immediate snapshot of important attributes like the ip, port, and status all in one readable line.

Implementing __str__ for custom collections

When your class manages a collection of items, implementing the __str__ method allows you to present a clean, formatted summary of its contents.

class TaskManager:
def __init__(self, name):
self.name = name
self.tasks = []

def add_task(self, task):
self.tasks.append(task)

def __str__(self):
tasks_count = len(self.tasks)
if tasks_count == 0:
return f"{self.name}: No tasks pending"

summary = f"{self.name}: {tasks_count} task(s)\n"
for i, task in enumerate(self.tasks, 1):
summary += f" {i}. {task}\n"
return summary.strip()

manager = TaskManager("Project Alpha")
manager.add_task("Design database schema")
manager.add_task("Implement user authentication")
print(manager)

The TaskManager class demonstrates how __str__ can produce a detailed, multi-line summary. The method first checks if the tasks list is empty, returning a specific message if so. Otherwise, it constructs a formatted string that starts with a header showing the total task count.

• It uses enumerate to iterate through the tasks, which allows it to create a numbered list automatically.
• Each task is appended as a new line to the summary string, formatted with the \n character.
• The strip() method is called at the end to remove the final newline, ensuring the output is clean.

Get started with Replit

Turn your knowledge of __str__ into a real tool. Describe what you want to build, like "a task manager that displays a formatted list of tasks" or "a stock portfolio tracker that neatly prints each stock's details."

Replit Agent writes the code, tests for errors, and deploys your app for you. Start building with Replit.