Python Design Patterns

Builder Pattern in Python

Assemble a complex object step by step with readable method calls instead of a constructor with ten arguments.

  • Advanced
  • 3 min read
  • 1 runnable example
What you'll learn
  • Step-by-step construction
  • Chaining builder methods
  • Producing the final object with build()
ReportBuilder()
  1. 1.add_title()Add a title
  2. 2.add_chart()Add a chart
  3. 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.

From a sandwich counter to code
ReportBuilder()🍞 Start an empty order
.add_title()🧀 Add one ingredient
.add_chart()🍅 Add another; order matters
.build()🥪 Hand over the finished sandwich
Add the parts you need, then build the result.
In one sentence

The Builder pattern constructs a complex object step by step through separate methods, then returns the finished object from a final build call.

Key points

  1. self.parts collects the parts added so far.
  2. add_title and add_chart each add one part and return self, so calls can be chained.
  3. ReportBuilder().add_title().add_chart().build() reads like a list of instructions.
  4. 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

Run code →
main.py
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)
Get a Run button for this example

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.

  1. Replace the sample domain while preserving the pattern structure.
  2. Compare the pattern with a simpler implementation and explain the tradeoff.
  3. Write tests for each participant before adding another implementation.
Run in the Python compiler →

Common mistakes

Forgetting to return self

Without return self, chaining fails because the method returns None.

Problem
def add_title(self):
    self.parts.append("title")
Fix
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