Opened 21 months ago
Last modified 20 months ago
#34352 assigned Cleanup/optimization
Unify terms in Signals docs.
Reported by: | PASCAL FOUQUE | Owned by: | stimver |
---|---|---|---|
Component: | Documentation | Version: | 4.1 |
Severity: | Normal | Keywords: | |
Cc: | Triage Stage: | Accepted | |
Has patch: | no | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
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
Change History (5)
follow-up: 4 comment:1 by , 21 months ago
comment:2 by , 21 months ago
Triage Stage: | Unreviewed → Accepted |
---|
comment:3 by , 21 months ago
Summary: | Clarify Signals documentation → Unify terms in Signals docs. |
---|
comment:4 by , 20 months ago
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 renamemy_callback()
tomy_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 findSignals
- if your app defines some
Signals
and someReceivers
(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.
comment:5 by , 20 months ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
"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 renamemy_callback()
tomy_signal_receiver()
to make it even more clearer.Users can freely organize their code, we recommend keeping signal receivers in
signals.py
. I'm not sure what other module you're proposing.Agreed we could use the same term.