Python Design Patterns

Proxy Pattern in Python

Put a stand-in in front of an object to load it lazily, check permissions or cache results.

  • Advanced
  • 2 min read
  • 1 runnable example
What you'll learn
  • A stand-in with the same interface
  • Lazy loading
  • Access control and caching
ReportProxy().display()
  1. 1ReportProxyClient talks to the proxy
  2. 2Loading reportFirst use: create the real report
  3. 3Quarterly reportDelegate the call

A stand-in decides when to call the real object

The problem

Some objects are expensive to create, such as a large report or a remote connection, and may not even be needed. Others need protection, such as an access check before use. A proxy stands in front of the real object and decides when and whether to use it.

Think of it like this

A proxy is like a report's title in a list of documents. The title is light and always there, standing in for the heavy file. The file itself is loaded only the first time you open it, and it stays open for every later look.

From a document list to code
ReportProxy()📄 The title in the list: light and always available
if self._report is None:🤔 Has the file been loaded yet?
self._report = Report()📥 Load the real report, only once
self._report.display()📖 Show the real report's content
The proxy offers the same method and controls access to the real object.
In one sentence

The Proxy pattern places a stand-in object with the same interface in front of a real object to control access to it.

Key points

  1. ReportProxy offers the same display() method as Report.
  2. self._report starts as None, so the expensive report is not created yet.
  3. The first call to display() prints "Loading report" and creates the real Report.
  4. Later calls reuse self._report without loading it again.

When should you use it?

  • Lazy loading of expensive objects, such as large files or images.
  • Access control, logging or caching in front of an object.
  • Local stand-ins for remote services.

When not to use it

  • The real object is cheap and always needed: the proxy only adds a layer.
  • Python's functools.cached_property already gives lazy loading for a single attribute.

Example code

Run code →
main.py
class Report:
    # Proxy: stand in for another object and control access to it.
    def display(self): return "Quarterly report"


class ReportProxy:
    def __init__(self): self._report = None

    def display(self):
        # Delay construction until the object is actually needed.
        if self._report is None:
            print("Loading report")
            self._report = Report()
        return self._report.display()


proxy = ReportProxy()
print(proxy.display())
Get a Run button for this example

Result of running the code

Loading report
Quarterly report

Code explanation

ReportProxy has the same display() method as Report but starts without a real report. The first time display() is called, it prints Loading report, creates the Report and keeps it in self._report. It then forwards the call to the real object, and any later call reuses the stored report.

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

Creating the real object in the constructor

That removes the benefit of lazy loading.

Problem
def __init__(self):
    self._report = Report()
Fix
def __init__(self):
    self._report = None

Finished this lesson?

Mark it as learned to track your progress.