Unify terms in Signals docs.

[PASCAL FOUQUE]

Currently, the "Signals" documentation presents some inconsistency, mostly due to naming.

• Different terms are used: "Signal handler", "Signal Receiver", "callback"
• Users are told to store "Signal handlers/Receivers" into a module called "signals", which connects to a Signal from another module called "signal".

I think some minor changes, could help understand this feature:

• 1. Remove the term "callback": can lead to confusion with a function defined per call
• 2. Introducing another module name to define "Signal handlers/Receivers" would help understand this feature involves two different actors.
• 3. Unify the naming of "Signal handlers" / "Signal Receiver", I'm wondering if we need to keep both terms, or keep the term "receiver" reserved for the function and use "Signal Handler" for the connected function.

NB: I didn't make much research on how this kind of feature is explained in other frameworks / technologies

[Mariusz Felisiak]

I think some minor changes, could help understand this feature:

• 1. Remove the term "callback": can lead to confusion with a function defined per call

"callback" is widely used in Python and Django docs as a function that is passed to another function as an argument, in this case to Signal.connect(). I don't find it confusing, however, we could rename my_callback() to my_signal_receiver() to make it even more clearer.

• 2. Introducing another module name to define "Signal handlers/Receivers" would help understand this feature involves two different actors.

Users can freely organize their code, we recommend keeping signal receivers in signals.py. I'm not sure what other module you're proposing.

• 3. Unify the naming of "Signal handlers" / "Signal Receiver"

Agreed we could use the same term.

[PASCAL FOUQUE]

Replying to Mariusz Felisiak:

I think some minor changes, could help understand this feature:

• 1. Remove the term "callback": can lead to confusion with a function defined per call

"callback" is widely used in Python and Django docs as a function that is passed to another function as an argument, in this case to Signal.connect(). I don't find it confusing, however, we could rename my_callback() to my_signal_receiver() to make it even more clearer.

I agree, the term callback is a proper term, but it's only used once.
My proposal is not necessarily to remove it but to use consistent naming across the whole page.
Perhaps even callback is the term to keep!

• 2. Introducing another module name to define "Signal handlers/Receivers" would help understand this feature involves two different actors.

Users can freely organize their code, we recommend keeping signal receivers in signals.py. I'm not sure what other module you're proposing.

Personally I keep signals and receivers definitions in 2 separate files: signals.py and receivers.py:
Here are some reasons that led me not to follow the documentation:

• inside a file called signals.py someone would expect to find Signals
• if your app defines some Signals and some Receivers (to another app), it becomes a bit weird to mix up everything
• It becomes easier to check what events an app emit and listen

• 3. Unify the naming of "Signal handlers" / "Signal Receiver"

Agreed we could use the same term.

Then, I'm wondering what naming we should keep.
To summarize, here are the different terms I identified for the "function to be connected to a Signal":

• "(Signal) Receiver": the simplest modification, but the difference with the "decorator" will become even more subtle.
• "(Signal) Handler":
• "Callback": unambiguous and known term for similar feature in other frameworks or languages

In the meantime, to facilitate a decision I made some some previews of the Signal.connect with different terms:

CALLBACK

Signal.connect(receiver, sender=None, weak=True, dispatch_uid=None)
Parameters:
receiver – The callback function which will be connected to this signal. See Receiver functions for more information.
sender – Specifies a particular sender to receive signals from. See Connecting to signals sent by specific senders for more information.
weak – Django stores callbacks as weak references by default. Thus, if your callback is a local function, it may be garbage collected. To prevent this, pass weak=False when you call the signal’s connect() method.
dispatch_uid – A unique identifier for a callbacks in cases where duplicate signals may be sent. See Preventing duplicate signals for more information.

HANDLER

Signal.connect(receiver, sender=None, weak=True, dispatch_uid=None)
Parameters:
receiver – The handler function which will be connected to this signal. See Signal Handler functions for more information.
sender – Specifies a particular sender to receive signals from. See Connecting to signals sent by specific senders for more information.
weak – Django stores signal handlers as weak references by default. Thus, if your handler is a local function, it may be garbage collected. To prevent this, pass weak=False when you call the signal’s connect() method.
dispatch_uid – A unique identifier for a signal handler in cases where duplicate signals may be sent. See Preventing duplicate signals for more information.

RECEIVER

Signal.connect(receiver, sender=None, weak=True, dispatch_uid=None)
Parameters:
receiver – The receiver function which will be connected to this signal. See Receiver functions for more information.
sender – Specifies a particular sender to receive signals from. See Connecting to signals sent by specific senders for more information.
weak – Django stores signal receivers as weak references by default. Thus, if your receiver is a local function, it may be garbage collected. To prevent this, pass weak=False when you call the signal’s connect() method.
dispatch_uid – A unique identifier for a signal receiver in cases where duplicate signals may be sent. See Preventing duplicate signals for more information.