Skip to content

Proxy Pattern

Category: Structural Pattern

Overview

Provide a surrogate or placeholder for another object to control access to it. This pattern is used to create a representative object that controls access to another object, which may be remote, expensive to create, or require protection.

Usage Guidelines

Use when:

  • Defer expensive object creation until needed (lazy initialization)
  • Control access based on permissions or authentication
  • Access objects in different address spaces (remote objects)
  • Log access to objects or cache results of expensive operations

Avoid when:

  • Direct access is sufficient and simple
  • No access control or lazy loading required
  • Proxy overhead is unacceptable for performance
  • Can modify original class directly

Implementation

from __future__ import annotations
from abc import ABC, abstractmethod
from typing import Optional

class Image(ABC):
    """Abstract interface for images."""

    @abstractmethod
    def display(self) -> str:
        """Display the image."""
        pass

    @abstractmethod
    def get_filename(self) -> str:
        """Get the image filename."""
        pass

class RealImage(Image):
    """Real image that is expensive to load."""

    def __init__(self, filename: str) -> None:
        """Initialize and load the image."""
        self.filename = filename
        self._load_from_disk()

    def _load_from_disk(self) -> None:
        """Simulate expensive loading operation."""
        pass

    def display(self) -> str:
        """Display the image."""
        return f"Displaying {self.filename}"

    def get_filename(self) -> str:
        """Get filename."""
        return self.filename

class ImageProxy(Image):
    """Virtual proxy for lazy loading images."""

    def __init__(self, filename: str) -> None:
        """Initialize proxy without loading image."""
        self.filename = filename
        self._real_image: Optional[RealImage] = None

    def display(self) -> str:
        """Display image, loading it if necessary."""
        if self._real_image is None:
            self._real_image = RealImage(self.filename)
        return self._real_image.display()

    def get_filename(self) -> str:
        """Get filename without loading image."""
        return self.filename

    def is_loaded(self) -> bool:
        """Check if real image is loaded."""
        return self._real_image is not None

Usage

# Virtual Proxy - lazy loading
image = ImageProxy("large_photo.jpg")
print(image.is_loaded())  # False - not loaded yet
print(image.display())  # Now loaded and displayed
print(image.is_loaded())  # True - already loaded

Trade-offs

Benefits:

  1. Controls access to real object
  2. Defers expensive operations until needed (lazy initialization)
  3. Implements authentication and authorization for access control
  4. Adds behavior without modifying real object

Drawbacks:

  1. Adds additional classes and indirection increasing complexity
  2. Proxy adds overhead affecting performance
  3. Lazy initialization may cause delays in response time
  4. Thread-safe proxies can be complex

Real-World Examples

  • ORM frameworks with database proxy objects for lazy loading
  • Virtual images as placeholders in documents
  • Network proxies like HTTP proxies, SOCKS proxies
  • Security proxies for authentication and authorization layers
  • Adapter
  • Decorator
  • Facade

API Reference

design_patterns.structural.proxy

Proxy Pattern Module

The Proxy pattern provides a surrogate or placeholder for another object to control access to it. There are several types of proxies: - Virtual Proxy: Controls access to expensive-to-create objects - Protection Proxy: Controls access based on permissions - Remote Proxy: Represents an object in a different address space - Caching Proxy: Caches results of expensive operations

Example

Using a virtual proxy for lazy loading:

image = ImageProxy("large_photo.jpg")
# Image not loaded yet

image.display()  # Now image is loaded and displayed
image.display()  # Uses cached image, no reload

Database

Bases: ABC

Abstract interface for database.

Source code in src/design_patterns/structural/proxy.py 
185
186
187
188
189
190
191
192
193
194
195
196
197
198
class Database(ABC):
    """Abstract interface for database."""

    @abstractmethod
    def query(self, sql: str) -> str:
        """Execute a query.

        Args:
            sql: SQL query.

        Returns:
            Query result.
        """
        pass

query(sql) abstractmethod

Execute a query.

Parameters:

Name Type Description Default
sql str

SQL query.

 required

Returns:

Type Description
str

Query result.
Source code in src/design_patterns/structural/proxy.py 
188
189
190
191
192
193
194
195
196
197
198
@abstractmethod
def query(self, sql: str) -> str:
    """Execute a query.

    Args:
        sql: SQL query.

    Returns:
        Query result.
    """
    pass

DatabaseProxy

Bases: Database

Caching proxy for database queries.

Source code in src/design_patterns/structural/proxy.py 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
class DatabaseProxy(Database):
    """Caching proxy for database queries."""

    def __init__(self) -> None:
        """Initialize proxy with real database and cache."""
        self._real_database = RealDatabase()
        self._cache: dict[str, str] = {}

    def query(self, sql: str) -> str:
        """Execute query with caching.

        Args:
            sql: SQL query.

        Returns:
            Cached or fresh query result.
        """
        if sql in self._cache:
            return f"Cached: {self._cache[sql]}"

        result = self._real_database.query(sql)
        self._cache[sql] = result
        return result

    def clear_cache(self) -> None:
        """Clear the query cache."""
        self._cache.clear()

    def get_cache_size(self) -> int:
        """Get number of cached queries.

        Returns:
            Cache size.
        """
        return len(self._cache)

__init__()

Initialize proxy with real database and cache.

Source code in src/design_patterns/structural/proxy.py 
219
220
221
222
def __init__(self) -> None:
    """Initialize proxy with real database and cache."""
    self._real_database = RealDatabase()
    self._cache: dict[str, str] = {}

clear_cache()

Clear the query cache.

Source code in src/design_patterns/structural/proxy.py 
240
241
242
def clear_cache(self) -> None:
    """Clear the query cache."""
    self._cache.clear()

get_cache_size()

Get number of cached queries.

Returns:

Type Description
int

Cache size.
Source code in src/design_patterns/structural/proxy.py 
244
245
246
247
248
249
250
def get_cache_size(self) -> int:
    """Get number of cached queries.

    Returns:
        Cache size.
    """
    return len(self._cache)

query(sql)

Execute query with caching.

Parameters:

Name Type Description Default
sql str

SQL query.

 required

Returns:

Type Description
str

Cached or fresh query result.
Source code in src/design_patterns/structural/proxy.py 
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
def query(self, sql: str) -> str:
    """Execute query with caching.

    Args:
        sql: SQL query.

    Returns:
        Cached or fresh query result.
    """
    if sql in self._cache:
        return f"Cached: {self._cache[sql]}"

    result = self._real_database.query(sql)
    self._cache[sql] = result
    return result

Document

Bases: ABC

Abstract interface for documents.

Source code in src/design_patterns/structural/proxy.py 
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
class Document(ABC):
    """Abstract interface for documents."""

    @abstractmethod
    def read(self) -> str:
        """Read the document.

        Returns:
            Document content.
        """
        pass

    @abstractmethod
    def write(self, content: str) -> str:
        """Write to the document.

        Args:
            content: Content to write.

        Returns:
            Write result.
        """
        pass

read() abstractmethod

Read the document.

Returns:

Type Description
str

Document content.
Source code in src/design_patterns/structural/proxy.py 
256
257
258
259
260
261
262
263
@abstractmethod
def read(self) -> str:
    """Read the document.

    Returns:
        Document content.
    """
    pass

write(content) abstractmethod

Write to the document.

Parameters:

Name Type Description Default
content str

Content to write.

 required

Returns:

Type Description
str

Write result.
Source code in src/design_patterns/structural/proxy.py 
265
266
267
268
269
270
271
272
273
274
275
@abstractmethod
def write(self, content: str) -> str:
    """Write to the document.

    Args:
        content: Content to write.

    Returns:
        Write result.
    """
    pass

Image

Bases: ABC

Abstract interface for images.

Source code in src/design_patterns/structural/proxy.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
class Image(ABC):
    """Abstract interface for images."""

    @abstractmethod
    def display(self) -> str:
        """Display the image.

        Returns:
            Display message.
        """
        pass

    @abstractmethod
    def get_filename(self) -> str:
        """Get the image filename.

        Returns:
            Filename string.
        """
        pass

display() abstractmethod

Display the image.

Returns:

Type Description
str

Display message.
Source code in src/design_patterns/structural/proxy.py 
31
32
33
34
35
36
37
38
@abstractmethod
def display(self) -> str:
    """Display the image.

    Returns:
        Display message.
    """
    pass

get_filename() abstractmethod

Get the image filename.

Returns:

Type Description
str

Filename string.
Source code in src/design_patterns/structural/proxy.py 
40
41
42
43
44
45
46
47
@abstractmethod
def get_filename(self) -> str:
    """Get the image filename.

    Returns:
        Filename string.
    """
    pass

ImageProxy

Bases: Image

Virtual proxy for lazy loading images.

Source code in src/design_patterns/structural/proxy.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 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
class ImageProxy(Image):
    """Virtual proxy for lazy loading images."""

    def __init__(self, filename: str) -> None:
        """Initialize proxy without loading image.

        Args:
            filename: Image filename.
        """
        self.filename = filename
        self._real_image: Optional[RealImage] = None

    def display(self) -> str:
        """Display image, loading it if necessary.

        Returns:
            Display message.
        """
        if self._real_image is None:
            self._real_image = RealImage(self.filename)
        return self._real_image.display()

    def get_filename(self) -> str:
        """Get filename without loading image.

        Returns:
            Filename.
        """
        return self.filename

    def is_loaded(self) -> bool:
        """Check if real image is loaded.

        Returns:
            True if loaded, False otherwise.
        """
        return self._real_image is not None

__init__(filename)

Initialize proxy without loading image.

Parameters:

Name Type Description Default
filename str

Image filename.

 required
Source code in src/design_patterns/structural/proxy.py 
86
87
88
89
90
91
92
93
def __init__(self, filename: str) -> None:
    """Initialize proxy without loading image.

    Args:
        filename: Image filename.
    """
    self.filename = filename
    self._real_image: Optional[RealImage] = None

display()

Display image, loading it if necessary.

Returns:

Type Description
str

Display message.
Source code in src/design_patterns/structural/proxy.py 
 95
 96
 97
 98
 99
100
101
102
103
def display(self) -> str:
    """Display image, loading it if necessary.

    Returns:
        Display message.
    """
    if self._real_image is None:
        self._real_image = RealImage(self.filename)
    return self._real_image.display()

get_filename()

Get filename without loading image.

Returns:

Type Description
str

Filename.
Source code in src/design_patterns/structural/proxy.py 
105
106
107
108
109
110
111
def get_filename(self) -> str:
    """Get filename without loading image.

    Returns:
        Filename.
    """
    return self.filename

is_loaded()

Check if real image is loaded.

Returns:

Type Description
bool

True if loaded, False otherwise.
Source code in src/design_patterns/structural/proxy.py 
113
114
115
116
117
118
119
def is_loaded(self) -> bool:
    """Check if real image is loaded.

    Returns:
        True if loaded, False otherwise.
    """
    return self._real_image is not None

Internet

Bases: ABC

Abstract interface for internet access.

Source code in src/design_patterns/structural/proxy.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
class Internet(ABC):
    """Abstract interface for internet access."""

    @abstractmethod
    def connect(self, url: str) -> str:
        """Connect to a URL.

        Args:
            url: URL to connect to.

        Returns:
            Connection result.
        """
        pass

connect(url) abstractmethod

Connect to a URL.

Parameters:

Name Type Description Default
url str

URL to connect to.

 required

Returns:

Type Description
str

Connection result.
Source code in src/design_patterns/structural/proxy.py 
125
126
127
128
129
130
131
132
133
134
135
@abstractmethod
def connect(self, url: str) -> str:
    """Connect to a URL.

    Args:
        url: URL to connect to.

    Returns:
        Connection result.
    """
    pass

ProtectedDocumentProxy

Bases: Document

Protection proxy that requires authentication.

Source code in src/design_patterns/structural/proxy.py 
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
class ProtectedDocumentProxy(Document):
    """Protection proxy that requires authentication."""

    def __init__(self, filename: str, user_role: str) -> None:
        """Initialize protected document proxy.

        Args:
            filename: Document filename.
            user_role: User's role (admin or user).
        """
        self._real_document = RealDocument(filename)
        self.user_role = user_role

    def read(self) -> str:
        """Read document (allowed for all users).

        Returns:
            Document content.
        """
        return self._real_document.read()

    def write(self, content: str) -> str:
        """Write to document (requires admin role).

        Args:
            content: Content to write.

        Returns:
            Write result or access denied message.
        """
        if self.user_role == "admin":
            return self._real_document.write(content)
        return "Access denied: admin role required for writing"

__init__(filename, user_role)

Initialize protected document proxy.

Parameters:

Name Type Description Default
filename str

Document filename.

 required
user_role str

User's role (admin or user).

 required
Source code in src/design_patterns/structural/proxy.py 
314
315
316
317
318
319
320
321
322
def __init__(self, filename: str, user_role: str) -> None:
    """Initialize protected document proxy.

    Args:
        filename: Document filename.
        user_role: User's role (admin or user).
    """
    self._real_document = RealDocument(filename)
    self.user_role = user_role

read()

Read document (allowed for all users).

Returns:

Type Description
str

Document content.
Source code in src/design_patterns/structural/proxy.py 
324
325
326
327
328
329
330
def read(self) -> str:
    """Read document (allowed for all users).

    Returns:
        Document content.
    """
    return self._real_document.read()

write(content)

Write to document (requires admin role).

Parameters:

Name Type Description Default
content str

Content to write.

 required

Returns:

Type Description
str

Write result or access denied message.
Source code in src/design_patterns/structural/proxy.py 
332
333
334
335
336
337
338
339
340
341
342
343
def write(self, content: str) -> str:
    """Write to document (requires admin role).

    Args:
        content: Content to write.

    Returns:
        Write result or access denied message.
    """
    if self.user_role == "admin":
        return self._real_document.write(content)
    return "Access denied: admin role required for writing"

ProxyInternet

Bases: Internet

Protection proxy that filters internet access.

Source code in src/design_patterns/structural/proxy.py 
153
154
155
156
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
class ProxyInternet(Internet):
    """Protection proxy that filters internet access."""

    def __init__(self) -> None:
        """Initialize proxy with real internet and banned sites."""
        self._real_internet = RealInternet()
        self._banned_sites = ["banned.com", "restricted.net", "blocked.org"]

    def connect(self, url: str) -> str:
        """Connect to URL if not banned.

        Args:
            url: URL to connect to.

        Returns:
            Connection result or blocked message.
        """
        for banned in self._banned_sites:
            if banned in url:
                return f"Access denied to {url}"
        return self._real_internet.connect(url)

    def add_banned_site(self, site: str) -> None:
        """Add a site to the banned list.

        Args:
            site: Site to ban.
        """
        if site not in self._banned_sites:
            self._banned_sites.append(site)

__init__()

Initialize proxy with real internet and banned sites.

Source code in src/design_patterns/structural/proxy.py 
156
157
158
159
def __init__(self) -> None:
    """Initialize proxy with real internet and banned sites."""
    self._real_internet = RealInternet()
    self._banned_sites = ["banned.com", "restricted.net", "blocked.org"]

add_banned_site(site)

Add a site to the banned list.

Parameters:

Name Type Description Default
site str

Site to ban.

 required
Source code in src/design_patterns/structural/proxy.py 
175
176
177
178
179
180
181
182
def add_banned_site(self, site: str) -> None:
    """Add a site to the banned list.

    Args:
        site: Site to ban.
    """
    if site not in self._banned_sites:
        self._banned_sites.append(site)

connect(url)

Connect to URL if not banned.

Parameters:

Name Type Description Default
url str

URL to connect to.

 required

Returns:

Type Description
str

Connection result or blocked message.
Source code in src/design_patterns/structural/proxy.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
def connect(self, url: str) -> str:
    """Connect to URL if not banned.

    Args:
        url: URL to connect to.

    Returns:
        Connection result or blocked message.
    """
    for banned in self._banned_sites:
        if banned in url:
            return f"Access denied to {url}"
    return self._real_internet.connect(url)

RealDatabase

Bases: Database

Real database implementation.

Source code in src/design_patterns/structural/proxy.py 
201
202
203
204
205
206
207
208
209
210
211
212
213
class RealDatabase(Database):
    """Real database implementation."""

    def query(self, sql: str) -> str:
        """Execute query on real database.

        Args:
            sql: SQL query.

        Returns:
            Query result.
        """
        return f"Executed: {sql}"

query(sql)

Execute query on real database.

Parameters:

Name Type Description Default
sql str

SQL query.

 required

Returns:

Type Description
str

Query result.
Source code in src/design_patterns/structural/proxy.py 
204
205
206
207
208
209
210
211
212
213
def query(self, sql: str) -> str:
    """Execute query on real database.

    Args:
        sql: SQL query.

    Returns:
        Query result.
    """
    return f"Executed: {sql}"

RealDocument

Bases: Document

Real document implementation.

Source code in src/design_patterns/structural/proxy.py 
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
class RealDocument(Document):
    """Real document implementation."""

    def __init__(self, filename: str) -> None:
        """Initialize document.

        Args:
            filename: Document filename.
        """
        self.filename = filename
        self._content = ""

    def read(self) -> str:
        """Read document content.

        Returns:
            Document content.
        """
        return f"Reading {self.filename}: {self._content}"

    def write(self, content: str) -> str:
        """Write content to document.

        Args:
            content: Content to write.

        Returns:
            Write confirmation.
        """
        self._content = content
        return f"Written to {self.filename}"

__init__(filename)

Initialize document.

Parameters:

Name Type Description Default
filename str

Document filename.

 required
Source code in src/design_patterns/structural/proxy.py 
281
282
283
284
285
286
287
288
def __init__(self, filename: str) -> None:
    """Initialize document.

    Args:
        filename: Document filename.
    """
    self.filename = filename
    self._content = ""

read()

Read document content.

Returns:

Type Description
str

Document content.
Source code in src/design_patterns/structural/proxy.py 
290
291
292
293
294
295
296
def read(self) -> str:
    """Read document content.

    Returns:
        Document content.
    """
    return f"Reading {self.filename}: {self._content}"

write(content)

Write content to document.

Parameters:

Name Type Description Default
content str

Content to write.

 required

Returns:

Type Description
str

Write confirmation.
Source code in src/design_patterns/structural/proxy.py 
298
299
300
301
302
303
304
305
306
307
308
def write(self, content: str) -> str:
    """Write content to document.

    Args:
        content: Content to write.

    Returns:
        Write confirmation.
    """
    self._content = content
    return f"Written to {self.filename}"

RealImage

Bases: Image

Real image that is expensive to load.

Source code in src/design_patterns/structural/proxy.py 
50
51
52
53
54
55
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
class RealImage(Image):
    """Real image that is expensive to load."""

    def __init__(self, filename: str) -> None:
        """Initialize and load the image.

        Args:
            filename: Image filename.
        """
        self.filename = filename
        self._load_from_disk()

    def _load_from_disk(self) -> None:
        """Simulate expensive loading operation."""
        pass

    def display(self) -> str:
        """Display the image.

        Returns:
            Display message.
        """
        return f"Displaying {self.filename}"

    def get_filename(self) -> str:
        """Get filename.

        Returns:
            Filename.
        """
        return self.filename

__init__(filename)

Initialize and load the image.

Parameters:

Name Type Description Default
filename str

Image filename.

 required
Source code in src/design_patterns/structural/proxy.py 
53
54
55
56
57
58
59
60
def __init__(self, filename: str) -> None:
    """Initialize and load the image.

    Args:
        filename: Image filename.
    """
    self.filename = filename
    self._load_from_disk()

display()

Display the image.

Returns:

Type Description
str

Display message.
Source code in src/design_patterns/structural/proxy.py 
66
67
68
69
70
71
72
def display(self) -> str:
    """Display the image.

    Returns:
        Display message.
    """
    return f"Displaying {self.filename}"

get_filename()

Get filename.

Returns:

Type Description
str

Filename.
Source code in src/design_patterns/structural/proxy.py 
74
75
76
77
78
79
80
def get_filename(self) -> str:
    """Get filename.

    Returns:
        Filename.
    """
    return self.filename

RealInternet

Bases: Internet

Real internet connection.

Source code in src/design_patterns/structural/proxy.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
class RealInternet(Internet):
    """Real internet connection."""

    def connect(self, url: str) -> str:
        """Connect to URL.

        Args:
            url: URL to connect to.

        Returns:
            Connection success message.
        """
        return f"Connected to {url}"

connect(url)

Connect to URL.

Parameters:

Name Type Description Default
url str

URL to connect to.

 required

Returns:

Type Description
str

Connection success message.
Source code in src/design_patterns/structural/proxy.py 
141
142
143
144
145
146
147
148
149
150
def connect(self, url: str) -> str:
    """Connect to URL.

    Args:
        url: URL to connect to.

    Returns:
        Connection success message.
    """
    return f"Connected to {url}"