Observer

Code in:JavaC#PythonJavaScript

In short: Observer lets one object notify a list of subscribers when something happens, without knowing who they are or what they do.

Problem

The payment that calls everyone

A customer pays order #1042 for €80. After that, a receipt has to go out by email and SMS, the warehouse has to reserve the goods, and accounting has to issue an invoice. The payments class does it all itself:

class Payments:
    def __init__(self):
        self.email = EmailService()
        self.sms = SmsService()
        self.warehouse = Warehouse()
        self.invoices = InvoiceService()

    def mark_paid(self, order):
        self.email.send_receipt(order)
        self.sms.notify_paid(order)
        self.warehouse.reserve(order)
        self.invoices.issue(order)

Each service is a small class that prints what it did:

payments = Payments()
payments.mark_paid(Order(1042, 80))

Output

Email: receipt for #1042
SMS: order #1042 is paid
Warehouse: reserve #1042
Invoice: €80.00 for #1042

It works. But marketing wants loyalty points on every payment. That is one more field and one more line in mark_paid. Tomorrow comes a push notification, the day after, statistics. The code every payment goes through is touched for things that have nothing to do with the payment.

Worse, today the SMS gateway is not responding:

class SmsService:
    def notify_paid(self, order):
        raise ConnectionError("SMS gateway is not responding")

payments = Payments()
try:
    payments.mark_paid(Order(1042, 80))
except ConnectionError as e:
    print(f"Payment failed: {e}")

Output

Email: receipt for #1042
Payment failed: SMS gateway is not responding

The money is taken, and the page tells the customer the payment failed. The warehouse reserved nothing, there is no invoice. One service nobody thinks is important stopped the whole payment.

The idea

Observer: whoever wants to know subscribes

The payments shouldn't know who cares about them. They should only know that someone wants to find out when an order is paid.

So the payments keep a list of subscribers. Every subscriber has the same shape: a function that takes the order. Whoever wants to know subscribes from outside. On a payment, the object walks the list and calls every subscriber with the order.

This is the Observer pattern. It has three roles:

• the subject is where something happens. Here it is the payments. Books also call it the publisher;
• the subscribers (observers) want to find out. They are email, SMS, the warehouse;
• the notification is the walk through the list: every subscriber is given what happened, here the paid order.

A new subscriber is new code outside. The subject is not touched. A subscriber can also unsubscribe, and then it doesn't hear any more.

See it

The subscribers find out on their own

The payments keep a list of functions:

from dataclasses import dataclass


@dataclass(frozen=True)
class Order:
    id: int
    total: float


class Payments:
    def __init__(self):
        self._listeners = []

    def subscribe(self, listener):
        self._listeners.append(listener)

    def unsubscribe(self, listener):
        self._listeners.remove(listener)

    def mark_paid(self, order):
        for listener in self._listeners:
            listener(order)

Every subscriber is an ordinary function that takes the order:

def email(order):
    print(f"Email: receipt for #{order.id}")


def sms(order):
    print(f"SMS: order #{order.id} is paid")


def warehouse(order):
    print(f"Warehouse: reserve #{order.id}")


def loyalty(order):
    print(f"Points: +{int(order.total)} for #{order.id}")

Three subscribers, a payment. Then loyalty points arrive, and the customer turns SMS off:

payments = Payments()
payments.subscribe(email)
payments.subscribe(sms)
payments.subscribe(warehouse)
payments.mark_paid(Order(1042, 80))

payments.subscribe(loyalty)
payments.unsubscribe(sms)
payments.mark_paid(Order(1043, 25))

Output

Email: receipt for #1042
SMS: order #1042 is paid
Warehouse: reserve #1042
Email: receipt for #1043
Warehouse: reserve #1043
Points: +25 for #1043

payments = Payments()
payments.subscribe(email)
payments.subscribe(sms)
payments.subscribe(warehouse)
payments.mark_paid(Order(1042, 80))

payments.subscribe(loyalty)
payments.unsubscribe(sms)
payments.mark_paid(Order(1043, 25))

Step by step, in words

1. Payments starts with an empty _listeners list.
2. email subscribes: it goes into the _listeners list.
3. sms and warehouse too. Payments doesn't know who they are, only that they take an order.
4. Order #1042 is paid. The notification goes out to every subscriber, in the order they subscribed.
5. One after another, in the same call: receipt, SMS, reservation. Each subscriber does its own job.
6. Loyalty points arrive: loyalty subscribes from outside. Not a single line of Payments changes.
7. The customer turns SMS off: sms unsubscribes and leaves the list.
8. Order #1043: the notification reaches email, warehouse and loyalty. sms is not on the list any more and hears nothing.

Payments is the same code from start to end. The points appeared without a single line of it changing, and the SMS stopped without the payments noticing.

More precisely, if you are curious

• A subscriber can be anything you can call: a function, a lambda, a method of an object. payments.subscribe(mailer.send_receipt) subscribes the method of one specific object. Written twice, mailer.send_receipt gives equal values, so unsubscribe(mailer.send_receipt) finds it and removes it. The payment after that prints nothing:

payments = Payments()
mailer = EmailService()
payments.subscribe(mailer.send_receipt)
payments.unsubscribe(mailer.send_receipt)
payments.mark_paid(Order(1042, 80))

• Python has no built-in Observer. A list of functions is the usual way. The name _listeners with an underscore says "don't touch from outside, use subscribe".
• Subscribers are called one after another, in the same call to mark_paid. A slow SMS gateway slows down the payment too. Big shops send the event to a queue (a message broker), and the services pick it up from there when they are ready.

See it

One subscriber fails, the others shouldn't

Observer removed the link between the payment and the SMS, but not the error. The SMS subscriber throws:

def sms(order):
    raise ConnectionError("SMS gateway is not responding")

payments = Payments()
payments.subscribe(email)
payments.subscribe(sms)
payments.subscribe(warehouse)
try:
    payments.mark_paid(Order(1042, 80))
except ConnectionError as e:
    print(f"Payment failed: {e}")

Output

Email: receipt for #1042
Payment failed: SMS gateway is not responding

Subscribers are called in a loop, and the exception from the SMS leaves the loop. The warehouse still reserves nothing, and the error still reaches the payment. The subject has to protect every call on its own:

def mark_paid(self, order):
    for listener in self._listeners:
        try:
            listener(order)
        except Exception as e:
            print(f"A subscriber failed: {e}")

With the same program:

payments = Payments()
payments.subscribe(email)
payments.subscribe(sms)
payments.subscribe(warehouse)
try:
    payments.mark_paid(Order(1042, 80))
except ConnectionError as e:
    print(f"Payment failed: {e}")

Output

Email: receipt for #1042
A subscriber failed: SMS gateway is not responding
Warehouse: reserve #1042

The payment went through, the warehouse reserved, and the failure is recorded. In a real shop this line goes to the log, and the SMS is retried later.

Try it

Predict the output

The subscribers are the ones from the card "The subscribers find out on their own". What does the program print?

payments = Payments()
payments.subscribe(email)
payments.subscribe(warehouse)
payments.subscribe(email)
payments.mark_paid(Order(7, 10))

payments.unsubscribe(warehouse)
payments.mark_paid(Order(8, 10))

Answer

Email: receipt for #7
Warehouse: reserve #7
Email: receipt for #8

Email: receipt for #7
Email: receipt for #7
Warehouse: reserve #7
Email: receipt for #8
Email: receipt for #8

Email: receipt for #7
Warehouse: reserve #7
Email: receipt for #7
Email: receipt for #8
Email: receipt for #8

Check

Try it

Find the bug

The welcome coupon is given only for the first paid order. So the coupon subscriber unsubscribes itself as soon as it sends it:

def welcome_coupon(order):
    print(f"Welcome coupon: #{order.id}")
    payments.unsubscribe(welcome_coupon)

payments = Payments()
payments.subscribe(welcome_coupon)
payments.subscribe(email)
payments.subscribe(warehouse)
payments.mark_paid(Order(1042, 80))
payments.mark_paid(Order(1043, 25))

Output

Welcome coupon: #1042
Warehouse: reserve #1042
Email: receipt for #1043
Warehouse: reserve #1043

Order #1042 got no receipt by email. Which line in Payments has the bug?

Pick the line with the bug.

1class Payments:2 def __init__(self):3 self._listeners = []45 def subscribe(self, listener):6 self._listeners.append(listener)78 def unsubscribe(self, listener):9 self._listeners.remove(listener)1011 def mark_paid(self, order):12 for listener in self._listeners:13 listener(order)

Check

More precisely, if you are curious

In C# and JavaScript this bug doesn't happen if you use the built-in tools. The delegate of a C# event doesn't change: -= makes a new list, and the current notification goes on over the old one. emit in EventEmitter copies the list before calling the listeners. A list of your own you have to protect by hand.

The idea

When you don't need it

Observer has a price. The code doesn't say who will react to the payment: to find out, you search for every place that subscribes. A subscriber nobody unsubscribes lives in memory as long as the subject lives. It's not worth it when:

• there is one reaction and it is always the same. One call is clearer than a list with one subscriber;
• the step is part of the action itself. If the payment is invalid without an invoice, the invoice is not a subscriber: it is called directly, and its failure stops the payment;
• the order matters and the steps depend on each other (first the warehouse, then the payment, then the invoice). That is a sequence, not an event. How to put it in one place is in the lesson "Adapter and Facade".

It's worth it when the reactions are many, they grow, and the subject must not depend on them: notifications, points, statistics, logs.

Exercise

The invoice as a subscriber

Solve the task in your editor.

Invoice. Make the invoice a subscriber: a function invoice that prints the amount with two digits after the point. Subscribe email, the warehouse and the invoice, and pay order #1042 for €80. The payments are not touched.

Output

Email: receipt for #1042
Warehouse: reserve #1042
Invoice: €80.00 for #1042

More tasks

• A gift over €100. A subscriber that prints "Gift: free delivery for #…" only for orders over €100. Pay one for €80 and one for €120.
• The coupon that unsubscribes itself. Write the coupon subscriber from "Find the bug" and payments that handle it. Walk a copy of the list.
• Two events. Add refunds too. A dictionary event name → list of subscribers. Email listens to both, the warehouse only to the payment.

Test

Check yourself

1. The shop adds loyalty points on every payment. What do you write with Observer?

A new class that inherits from the paymentsA new subscriber that subscribes from outside; the payments are not touchedA new line in the method that marks the order as paid

2. The SMS subscriber throws an exception and the notification is not protected. What happens?

The subscribers after it aren't called, and the error reaches whoever marked the order as paidOnly the SMS is not sent, the other subscribers keep workingThe program skips the error

3. The same subscriber is subscribed twice. How many times does it hear about one payment?

Never: the second subscription cancels the firstTwiceOnce: the list keeps every subscriber once

4. The invoice must be issued, or the payment does not count. Does Observer fit here?

Yes, everything after the payment is a subscriberNo: a step without which the payment is invalid is called directly, and its failure stops the paymentYes, but only if the subscriber is first on the list

Check

Start the lesson over

Related lessons

• Builds on: Lambdas · dataclass, match and patterns · Design patterns · Strategy
• Continues in: The shop: which pattern where · Events and queues · Transactional outbox
• Tasks on this topic: Design patterns