Skip to content

Facade Pattern

Category: Structural Pattern

Overview

Provide a simplified interface to a complex subsystem. This pattern defines a higher-level interface that makes the subsystem easier to use by wrapping a complicated set of objects with a single, simpler interface.

Usage Guidelines

Use when:

  • Subsystem has many classes and complex interactions
  • Want to provide simple interface to complex functionality
  • Creating layers in application architecture
  • Most clients need only subset of subsystem functionality

Avoid when:

  • Subsystem is already simple
  • Clients need fine-grained control
  • No common usage patterns exist
  • Facade overhead is unacceptable for performance

Implementation

from __future__ import annotations

# Subsystem Classes
class Projector:
    """Projector subsystem component."""

    def on(self) -> str:
        """Turn on projector."""
        return "Projector is on"

    def off(self) -> str:
        """Turn off projector."""
        return "Projector is off"

    def set_input(self, source: str) -> str:
        """Set input source."""
        return f"Projector input set to {source}"

class SoundSystem:
    """Sound system subsystem component."""

    def on(self) -> str:
        """Turn on sound system."""
        return "Sound system is on"

    def off(self) -> str:
        """Turn off sound system."""
        return "Sound system is off"

    def set_volume(self, level: int) -> str:
        """Set volume level."""
        return f"Volume set to {level}"

    def set_surround_sound(self) -> str:
        """Enable surround sound."""
        return "Surround sound enabled"

class DVDPlayer:
    """DVD player subsystem component."""

    def on(self) -> str:
        """Turn on DVD player."""
        return "DVD player is on"

    def off(self) -> str:
        """Turn off DVD player."""
        return "DVD player is off"

    def play(self, movie: str) -> str:
        """Play a movie."""
        return f"Playing {movie}"

    def stop(self) -> str:
        """Stop playback."""
        return "DVD player stopped"

class Lights:
    """Lights subsystem component."""

    def dim(self, level: int) -> str:
        """Dim lights to level."""
        return f"Lights dimmed to {level}%"

    def on(self) -> str:
        """Turn lights on."""
        return "Lights are on"

# Facade
class HomeTheaterFacade:
    """Facade providing simplified interface to home theater subsystems."""

    def __init__(self) -> None:
        """Initialize all subsystems."""
        self.projector = Projector()
        self.sound = SoundSystem()
        self.dvd = DVDPlayer()
        self.lights = Lights()

    def watch_movie(self, movie: str) -> list[str]:
        """Set up everything to watch a movie.

        Args:
            movie: Movie title to watch.

        Returns:
            List of all operations performed.
        """
        operations = []
        operations.append(self.lights.dim(10))
        operations.append(self.projector.on())
        operations.append(self.projector.set_input("DVD"))
        operations.append(self.sound.on())
        operations.append(self.sound.set_volume(50))
        operations.append(self.sound.set_surround_sound())
        operations.append(self.dvd.on())
        operations.append(self.dvd.play(movie))
        return operations

    def end_movie(self) -> list[str]:
        """Clean up after watching a movie.

        Returns:
            List of all operations performed.
        """
        operations = []
        operations.append(self.dvd.stop())
        operations.append(self.dvd.off())
        operations.append(self.sound.off())
        operations.append(self.projector.off())
        operations.append(self.lights.on())
        return operations

Usage

# With facade - simple interface
theater = HomeTheaterFacade()
operations = theater.watch_movie("Inception")
# All complexity hidden behind simple method

# Later, end movie with one call
operations = theater.end_movie()

Trade-offs

Benefits:

  1. Provides simple interface to complex subsystem
  2. Clients decoupled from subsystem classes reducing coupling
  3. Supports layering in application architecture
  4. Subsystem becomes easier to use

Drawbacks:

  1. Facade can become too large and complex (God object)
  2. May not expose all subsystem features limiting functionality
  3. Facade tightly coupled to subsystem
  4. Adds another layer of abstraction

Real-World Examples

  • Framework APIs providing simplified interfaces
  • Database libraries with high-level query builders hiding SQL complexity
  • Network libraries with simple HTTP client hiding socket complexity
  • Cloud SDKs with simplified interfaces to cloud services
  • Abstract Factory
  • Mediator
  • Singleton
  • Adapter

API Reference

design_patterns.structural.facade

Facade Pattern Module

The Facade pattern provides a simplified interface to a complex subsystem. It defines a higher-level interface that makes the subsystem easier to use by wrapping a complicated set of objects with a single, simpler interface.

Example

Home theater system with many components:

theater = HomeTheaterFacade()

# Simple interface hides complexity
theater.watch_movie("Inception")
# Internally: turns on projector, dims lights, starts audio, plays movie

theater.end_movie()
# Internally: stops playback, turns off equipment, raises lights

CPU

CPU subsystem component.

Source code in src/design_patterns/structural/facade.py 
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
class CPU:
    """CPU subsystem component."""

    def freeze(self) -> str:
        """Freeze CPU.

        Returns:
            Status message.
        """
        return "CPU frozen"

    def jump(self, position: int) -> str:
        """Jump to position.

        Args:
            position: Memory position.

        Returns:
            Status message.
        """
        return f"CPU jumped to position {position}"

    def execute(self) -> str:
        """Execute instructions.

        Returns:
            Status message.
        """
        return "CPU executing"

execute()

Execute instructions.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
224
225
226
227
228
229
230
def execute(self) -> str:
    """Execute instructions.

    Returns:
        Status message.
    """
    return "CPU executing"

freeze()

Freeze CPU.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
205
206
207
208
209
210
211
def freeze(self) -> str:
    """Freeze CPU.

    Returns:
        Status message.
    """
    return "CPU frozen"

jump(position)

Jump to position.

Parameters:

Name Type Description Default
position int

Memory position.

 required

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
213
214
215
216
217
218
219
220
221
222
def jump(self, position: int) -> str:
    """Jump to position.

    Args:
        position: Memory position.

    Returns:
        Status message.
    """
    return f"CPU jumped to position {position}"

ComputerFacade

Facade for computer boot process.

Source code in src/design_patterns/structural/facade.py 
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
class ComputerFacade:
    """Facade for computer boot process."""

    def __init__(self) -> None:
        """Initialize computer subsystems."""
        self.cpu = CPU()
        self.memory = Memory()
        self.hard_drive = HardDrive()

    def start(self) -> list[str]:
        """Start the computer with a simple interface.

        Returns:
            List of boot operations.
        """
        operations = []
        operations.append(self.cpu.freeze())
        operations.append(self.memory.load(0, "boot sector"))
        operations.append(self.hard_drive.read(0, 1024))
        operations.append(self.cpu.jump(0))
        operations.append(self.cpu.execute())
        return operations

__init__()

Initialize computer subsystems.

Source code in src/design_patterns/structural/facade.py 
268
269
270
271
272
def __init__(self) -> None:
    """Initialize computer subsystems."""
    self.cpu = CPU()
    self.memory = Memory()
    self.hard_drive = HardDrive()

start()

Start the computer with a simple interface.

Returns:

Type Description
list[str]

List of boot operations.
Source code in src/design_patterns/structural/facade.py 
274
275
276
277
278
279
280
281
282
283
284
285
286
def start(self) -> list[str]:
    """Start the computer with a simple interface.

    Returns:
        List of boot operations.
    """
    operations = []
    operations.append(self.cpu.freeze())
    operations.append(self.memory.load(0, "boot sector"))
    operations.append(self.hard_drive.read(0, 1024))
    operations.append(self.cpu.jump(0))
    operations.append(self.cpu.execute())
    return operations

DVDPlayer

DVD player subsystem component.

Source code in src/design_patterns/structural/facade.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
class DVDPlayer:
    """DVD player subsystem component."""

    def on(self) -> str:
        """Turn on DVD player.

        Returns:
            Status message.
        """
        return "DVD player is on"

    def off(self) -> str:
        """Turn off DVD player.

        Returns:
            Status message.
        """
        return "DVD player is off"

    def play(self, movie: str) -> str:
        """Play a movie.

        Args:
            movie: Movie title.

        Returns:
            Status message.
        """
        return f"Playing {movie}"

    def stop(self) -> str:
        """Stop playback.

        Returns:
            Status message.
        """
        return "DVD player stopped"

off()

Turn off DVD player.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
106
107
108
109
110
111
112
def off(self) -> str:
    """Turn off DVD player.

    Returns:
        Status message.
    """
    return "DVD player is off"

on()

Turn on DVD player.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
 98
 99
100
101
102
103
104
def on(self) -> str:
    """Turn on DVD player.

    Returns:
        Status message.
    """
    return "DVD player is on"

play(movie)

Play a movie.

Parameters:

Name Type Description Default
movie str

Movie title.

 required

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
114
115
116
117
118
119
120
121
122
123
def play(self, movie: str) -> str:
    """Play a movie.

    Args:
        movie: Movie title.

    Returns:
        Status message.
    """
    return f"Playing {movie}"

stop()

Stop playback.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
125
126
127
128
129
130
131
def stop(self) -> str:
    """Stop playback.

    Returns:
        Status message.
    """
    return "DVD player stopped"

HardDrive

Hard drive subsystem component.

Source code in src/design_patterns/structural/facade.py 
249
250
251
252
253
254
255
256
257
258
259
260
261
262
class HardDrive:
    """Hard drive subsystem component."""

    def read(self, sector: int, size: int) -> str:
        """Read data from hard drive.

        Args:
            sector: Disk sector.
            size: Number of bytes to read.

        Returns:
            Data read.
        """
        return f"Read {size} bytes from sector {sector}"

read(sector, size)

Read data from hard drive.

Parameters:

Name Type Description Default
sector int

Disk sector.

 required
size int

Number of bytes to read.

 required

Returns:

Type Description
str

Data read.
Source code in src/design_patterns/structural/facade.py 
252
253
254
255
256
257
258
259
260
261
262
def read(self, sector: int, size: int) -> str:
    """Read data from hard drive.

    Args:
        sector: Disk sector.
        size: Number of bytes to read.

    Returns:
        Data read.
    """
    return f"Read {size} bytes from sector {sector}"

HomeTheaterFacade

Facade providing simplified interface to home theater subsystems.

Source code in src/design_patterns/structural/facade.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
class HomeTheaterFacade:
    """Facade providing simplified interface to home theater subsystems."""

    def __init__(self) -> None:
        """Initialize all subsystems."""
        self.projector = Projector()
        self.sound = SoundSystem()
        self.dvd = DVDPlayer()
        self.lights = Lights()

    def watch_movie(self, movie: str) -> list[str]:
        """Set up everything to watch a movie.

        Args:
            movie: Movie title to watch.

        Returns:
            List of all operations performed.
        """
        operations = []
        operations.append(self.lights.dim(10))
        operations.append(self.projector.on())
        operations.append(self.projector.set_input("DVD"))
        operations.append(self.sound.on())
        operations.append(self.sound.set_volume(50))
        operations.append(self.sound.set_surround_sound())
        operations.append(self.dvd.on())
        operations.append(self.dvd.play(movie))
        return operations

    def end_movie(self) -> list[str]:
        """Clean up after watching a movie.

        Returns:
            List of all operations performed.
        """
        operations = []
        operations.append(self.dvd.stop())
        operations.append(self.dvd.off())
        operations.append(self.sound.off())
        operations.append(self.projector.off())
        operations.append(self.lights.on())
        return operations

__init__()

Initialize all subsystems.

Source code in src/design_patterns/structural/facade.py 
160
161
162
163
164
165
def __init__(self) -> None:
    """Initialize all subsystems."""
    self.projector = Projector()
    self.sound = SoundSystem()
    self.dvd = DVDPlayer()
    self.lights = Lights()

end_movie()

Clean up after watching a movie.

Returns:

Type Description
list[str]

List of all operations performed.
Source code in src/design_patterns/structural/facade.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
def end_movie(self) -> list[str]:
    """Clean up after watching a movie.

    Returns:
        List of all operations performed.
    """
    operations = []
    operations.append(self.dvd.stop())
    operations.append(self.dvd.off())
    operations.append(self.sound.off())
    operations.append(self.projector.off())
    operations.append(self.lights.on())
    return operations

watch_movie(movie)

Set up everything to watch a movie.

Parameters:

Name Type Description Default
movie str

Movie title to watch.

 required

Returns:

Type Description
list[str]

List of all operations performed.
Source code in src/design_patterns/structural/facade.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def watch_movie(self, movie: str) -> list[str]:
    """Set up everything to watch a movie.

    Args:
        movie: Movie title to watch.

    Returns:
        List of all operations performed.
    """
    operations = []
    operations.append(self.lights.dim(10))
    operations.append(self.projector.on())
    operations.append(self.projector.set_input("DVD"))
    operations.append(self.sound.on())
    operations.append(self.sound.set_volume(50))
    operations.append(self.sound.set_surround_sound())
    operations.append(self.dvd.on())
    operations.append(self.dvd.play(movie))
    return operations

Lights

Lights subsystem component.

Source code in src/design_patterns/structural/facade.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
class Lights:
    """Lights subsystem component."""

    def dim(self, level: int) -> str:
        """Dim lights to level.

        Args:
            level: Light level (0-100).

        Returns:
            Status message.
        """
        return f"Lights dimmed to {level}%"

    def on(self) -> str:
        """Turn lights on.

        Returns:
            Status message.
        """
        return "Lights are on"

dim(level)

Dim lights to level.

Parameters:

Name Type Description Default
level int

Light level (0-100).

 required

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
137
138
139
140
141
142
143
144
145
146
def dim(self, level: int) -> str:
    """Dim lights to level.

    Args:
        level: Light level (0-100).

    Returns:
        Status message.
    """
    return f"Lights dimmed to {level}%"

on()

Turn lights on.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
148
149
150
151
152
153
154
def on(self) -> str:
    """Turn lights on.

    Returns:
        Status message.
    """
    return "Lights are on"

Memory

Memory subsystem component.

Source code in src/design_patterns/structural/facade.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
class Memory:
    """Memory subsystem component."""

    def load(self, position: int, data: str) -> str:
        """Load data into memory.

        Args:
            position: Memory position.
            data: Data to load.

        Returns:
            Status message.
        """
        return f"Loaded {data} at position {position}"

load(position, data)

Load data into memory.

Parameters:

Name Type Description Default
position int

Memory position.

 required
data str

Data to load.

 required

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
236
237
238
239
240
241
242
243
244
245
246
def load(self, position: int, data: str) -> str:
    """Load data into memory.

    Args:
        position: Memory position.
        data: Data to load.

    Returns:
        Status message.
    """
    return f"Loaded {data} at position {position}"

Projector

Projector subsystem component.

Source code in src/design_patterns/structural/facade.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
class Projector:
    """Projector subsystem component."""

    def on(self) -> str:
        """Turn on projector.

        Returns:
            Status message.
        """
        return "Projector is on"

    def off(self) -> str:
        """Turn off projector.

        Returns:
            Status message.
        """
        return "Projector is off"

    def set_input(self, source: str) -> str:
        """Set input source.

        Args:
            source: Input source name.

        Returns:
            Status message.
        """
        return f"Projector input set to {source}"

off()

Turn off projector.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
36
37
38
39
40
41
42
def off(self) -> str:
    """Turn off projector.

    Returns:
        Status message.
    """
    return "Projector is off"

on()

Turn on projector.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
28
29
30
31
32
33
34
def on(self) -> str:
    """Turn on projector.

    Returns:
        Status message.
    """
    return "Projector is on"

set_input(source)

Set input source.

Parameters:

Name Type Description Default
source str

Input source name.

 required

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
44
45
46
47
48
49
50
51
52
53
def set_input(self, source: str) -> str:
    """Set input source.

    Args:
        source: Input source name.

    Returns:
        Status message.
    """
    return f"Projector input set to {source}"

SoundSystem

Sound system subsystem component.

Source code in src/design_patterns/structural/facade.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
class SoundSystem:
    """Sound system subsystem component."""

    def on(self) -> str:
        """Turn on sound system.

        Returns:
            Status message.
        """
        return "Sound system is on"

    def off(self) -> str:
        """Turn off sound system.

        Returns:
            Status message.
        """
        return "Sound system is off"

    def set_volume(self, level: int) -> str:
        """Set volume level.

        Args:
            level: Volume level (0-100).

        Returns:
            Status message.
        """
        return f"Volume set to {level}"

    def set_surround_sound(self) -> str:
        """Enable surround sound.

        Returns:
            Status message.
        """
        return "Surround sound enabled"

off()

Turn off sound system.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
67
68
69
70
71
72
73
def off(self) -> str:
    """Turn off sound system.

    Returns:
        Status message.
    """
    return "Sound system is off"

on()

Turn on sound system.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
59
60
61
62
63
64
65
def on(self) -> str:
    """Turn on sound system.

    Returns:
        Status message.
    """
    return "Sound system is on"

set_surround_sound()

Enable surround sound.

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
86
87
88
89
90
91
92
def set_surround_sound(self) -> str:
    """Enable surround sound.

    Returns:
        Status message.
    """
    return "Surround sound enabled"

set_volume(level)

Set volume level.

Parameters:

Name Type Description Default
level int

Volume level (0-100).

 required

Returns:

Type Description
str

Status message.
Source code in src/design_patterns/structural/facade.py 
75
76
77
78
79
80
81
82
83
84
def set_volume(self, level: int) -> str:
    """Set volume level.

    Args:
        level: Volume level (0-100).

    Returns:
        Status message.
    """
    return f"Volume set to {level}"