Builder Pattern in Python
Assemble a complex object step by step with readable method calls instead of a constructor with ten arguments.
- Step-by-step construction
- Chaining builder methods
- Producing the final object with build()
- 1
.add_title()Add a title - 2
.add_chart()Add a chart - 3
.build()Report: title, chart
Add the parts you need, then build
The problem
Some objects have many optional parts: a report may have a title, a chart, a table, a footer, or any mix of them. A constructor with ten optional arguments is hard to read and easy to call wrong. A builder adds the parts one clear step at a time.
Think of it like this
A builder is like ordering a sandwich at a counter. You say "bread, then cheese, then tomato", and the sandwich grows with each instruction. When you say "done", you get the finished sandwich.
ReportBuilder()🍞 Start an empty order.add_title()🧀 Add one ingredient.add_chart()🍅 Add another; order matters.build()🥪 Hand over the finished sandwichThe Builder pattern constructs a complex object step by step through separate methods, then returns the finished object from a final build call.
Key points
self.partscollects the parts added so far.add_titleandadd_charteach add one part andreturn self, so calls can be chained.ReportBuilder().add_title().add_chart().build()reads like a list of instructions.build()turns the collected parts into the finished report text.
When should you use it?
- Objects with many optional parts: reports, HTTP requests, SQL queries, documents.
- Making step-by-step construction readable with method chaining.
- Creating different variants with the same building steps.
When not to use it
- Objects with two or three required fields: a normal constructor or a dataclass is simpler.
- Python code where keyword arguments with defaults already make the call clear.
Example code
class ReportBuilder:
# Builder: assemble a complex value one optional part at a time.
def __init__(self):
self.parts = []
def add_title(self):
self.parts.append("title")
return self
def add_chart(self):
self.parts.append("chart")
return self
def build(self):
# Hide the final assembly behind one operation.
return "Report: " + ", ".join(self.parts)
report = ReportBuilder().add_title().add_chart().build()
print(report)
Result of running the code
Report: title, chart
Code explanation
ReportBuilder starts with an empty list of parts. add_title and add_chart each append one part and return the builder itself, which is what makes the chained call possible. build() joins the parts into the final text, so the report contains exactly the parts that were added, in the order they were added.
Change the values and run the program in the CodeUtility online Python compiler without installing Python locally.
Practice exercises
Modify the runnable example with the exercises below to build understanding beyond copying the result.
- Replace the sample domain while preserving the pattern structure.
- Compare the pattern with a simpler implementation and explain the tradeoff.
- Write tests for each participant before adding another implementation.
Common mistakes
Forgetting to return self
Without return self, chaining fails because the method returns None.
def add_title(self):
self.parts.append("title")
def add_title(self):
self.parts.append("title")
return self
Finished this lesson?
Mark it as learned to track your progress.
Practice with a challenge
Use what this lesson covers to solve a real problem. Each challenge runs in your browser with instant tests and an AI review.
All challenges