Fungsi penerima¶

Pertama, kami butuh menentukan fungsi penerima. Penerima dapat menjadi fungsi Phyton apapun atau cara:

def my_callback(sender, **kwargs):
    print("Request finished!")

Notice that the function takes a sender argument, along with wildcard keyword arguments (**kwargs); all signal handlers must take these arguments.

We'll look at senders a bit later, but right now look at the **kwargs argument. All signals send keyword arguments, and may change those keyword arguments at any time. In the case of request_finished, it's documented as sending no arguments, which means we might be tempted to write our signal handling as my_callback(sender).

This would be wrong -- in fact, Django will throw an error if you do so. That's because at any point arguments could get added to the signal and your receiver must be able to handle those new arguments.

Menyambung fungsi penerima¶

There are two ways you can connect a receiver to a signal. You can take the manual connect route:

from django.core.signals import request_finished

request_finished.connect(my_callback)

Cara lain, anda dapat menggunakan penghias receiver():

receiver(signal)[sumber]¶

Parameter:	signal -- A signal or a list of signals to connect a function to.

Here's how you connect with the decorator:

from django.core.signals import request_finished
from django.dispatch import receiver

@receiver(request_finished)
def my_callback(sender, **kwargs):
    print("Request finished!")

Now, our my_callback function will be called each time a request finishes.

Connecting to signals sent by specific senders¶

Some signals get sent many times, but you'll only be interested in receiving a certain subset of those signals. For example, consider the django.db.models.signals.pre_save signal sent before a model gets saved. Most of the time, you don't need to know when any model gets saved -- just when one specific model is saved.

In these cases, you can register to receive signals sent only by particular senders. In the case of django.db.models.signals.pre_save, the sender will be the model class being saved, so you can indicate that you only want signals sent by some model:

from django.db.models.signals import pre_save
from django.dispatch import receiver
from myapp.models import MyModel


@receiver(pre_save, sender=MyModel)
def my_handler(sender, **kwargs):
    ...

The my_handler function will only be called when an instance of MyModel is saved.

Different signals use different objects as their senders; you'll need to consult the built-in signal documentation for details of each particular signal.

Mencegah sinyal rangkap¶

In some circumstances, the code connecting receivers to signals may run multiple times. This can cause your receiver function to be registered more than once, and thus called multiple times for a single signal event.

Jika perilaku ini bermasalah (seperti ketika menggunakan sinyal mengirim surel dimanapun model disimpan), lewati penciri unik sebagai argumen dispatch_uid untuk mencirikan fungsi penerima anda. Penciri ini akan biasanya berupa string, meskipun obyek apapun yang mampu akan cukup. Hasil akhir adalah fungsi penerima anda akan hanya diikatkan ke sinyal sekali untuk setiap nilai dispatch_uid unik:

from django.core.signals import request_finished

request_finished.connect(my_callback, dispatch_uid="my_unique_identifier")

Menentukan sinyal¶

class Signal(providing_args=list)[sumber]¶

Semua sinyal adalah instance django.dispatch.Signal. providing_args adalah daftar dari nama-nama dari argumen sinyal akan menyediakan ke pendengar. Ini murni dokumentasi, bagaimanapun, ketika tidak ada yang memeriksa sinyal itu sebenarnya menyediakan argumen ini ke pendengarnya.

Sebagai contoh:

import django.dispatch

pizza_done = django.dispatch.Signal(providing_args=["toppings", "size"])

Ini menyatakan sebuah sinyal pizza_done yang akan menyediakan penerima dengan argumen toppings dan size.

Remember that you're allowed to change this list of arguments at any time, so getting the API right on the first try isn't necessary.

Mengirim sinyal¶

Terdapat dua jalan mengirim sinyal di Django.

Signal.send(sender, **kwargs)[sumber]¶

Signal.send_robust(sender, **kwargs)[sumber]¶

To send a signal, call either Signal.send() (all built-in signals use this) or Signal.send_robust(). You must provide the sender argument (which is a class most of the time) and may provide as many other keyword arguments as you like.

Sebagai contoh, ini adalah bagaimana mengirim sinyal pizza_done kami mungkin terlihat:

class PizzaStore:
    ...

    def send_pizza(self, toppings, size):
        pizza_done.send(sender=self.__class__, toppings=toppings, size=size)
        ...

Both send() and send_robust() return a list of tuple pairs [(receiver, response), ... ], representing the list of called receiver functions and their response values.

send() differs from send_robust() in how exceptions raised by receiver functions are handled. send() does not catch any exceptions raised by receivers; it simply allows errors to propagate. Thus not all receivers may be notified of a signal in the face of an error.

send_robust() catches all errors derived from Python's Exception class, and ensures all receivers are notified of the signal. If an error occurs, the error instance is returned in the tuple pair for the receiver that raised the error.

The tracebacks are present on the __traceback__ attribute of the errors returned when calling send_robust().