Proxy: control access to another object

A proxy is an object that stands in for another object, its subject, behind exactly the same interface. Callers talk to the proxy as if it were the subject, and the proxy decides when and how each call reaches the real thing. It can create the subject only when it is first needed, check that the caller may make the call, answer from a cache, record the call, or forward it to another process. Use a proxy when you need that kind of control over an object without changing the object or the code that calls it.

One interface, a gatekeeper in front

Because the proxy has the subject’s interface, code written against that interface cannot tell the two apart, and that is what makes the pattern useful. A gallery that draws pictures through an Image interface does not care whether it holds a decoded image or a placeholder that decodes itself on the first draw.

Here is that placeholder, a virtual proxy, in a gallery of 100 images of which three fit on the screen:

"""A virtual proxy: a gallery of 100 images that loads only the ones it actually draws."""


class DiskImage:
    """The real subject: creating one reads and decodes the whole file, which is slow."""

    loads = 0

    def __init__(self, path):
        DiskImage.loads += 1
        self.path = path

    def draw(self, x, y):
        return f"{self.path} drawn at {x},{y}"


class LazyImage:
    """The proxy: the same draw() method, but the real image is created on the first draw only."""

    def __init__(self, path):
        self.path = path
        self._real = None

    def draw(self, x, y):
        if self._real is None:
            self._real = DiskImage(self.path)
        return self._real.draw(x, y)


gallery = [LazyImage(f"photo{n}.jpg") for n in range(1, 101)]
print("gallery of", len(gallery), "images, files loaded:", DiskImage.loads)

for row, image in enumerate(gallery[:3]):  # only three fit on the screen
    print(image.draw(0, row * 200))
print(gallery[0].draw(0, 0))  # drawn again: no second load

print("files loaded:", DiskImage.loads)

gallery of 100 images, files loaded: 0
photo1.jpg drawn at 0,0
photo2.jpg drawn at 0,200
photo3.jpg drawn at 0,400
photo1.jpg drawn at 0,0
files loaded: 3

Building the gallery loaded nothing. Drawing the three visible images loaded three files, and drawing the first one again loaded nothing more, because the proxy kept the real image once it had made it. A gallery that decoded all 100 images up front would have done 97 loads that nobody looked at.

The same two counts check any proxy: count the calls that clients make and the calls that reach the subject. The difference is the work the proxy saved, or the work it refused, and a test can assert both numbers.

Proxies are named after the control they add:

• A virtual proxy creates an expensive subject only when it is first used.
• A protection proxy checks whether the caller may make a call before passing it on.
• A caching proxy answers repeated requests from stored results instead of asking the subject again.
• A logging or counting proxy, sometimes called a smart reference, records each call and passes it on unchanged.
• A remote proxy stands in for an object in another process and turns each call into a network request.

Some languages build proxies in. JavaScript’s Proxy object sends operations on another object to handler functions, Java’s java.lang.reflect.Proxy creates proxy classes for interfaces at run time, and Python forwards unknown attributes with __getattr__.

A decorator has the same shape, an object that wraps another behind the same interface, but a different purpose: it adds behaviour and is meant to be stacked, while a proxy controls access to one subject. A proxy has a cost too: every call passes through one more object, and a proxy that hides slow or failing work, such as a network call, makes that work look as cheap as a local method call.

Three proxies behind one interface, and why their order matters Pro: opens with a Pro, Premium or Ultimate pass