#34352: Unify terms in Signals docs.
--------------------------------------+------------------------------------
Reporter: PASCAL FOUQUE | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 4.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by PASCAL FOUQUE):
Replying to [comment:1 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/34352#comment:4>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/01070186ab52646b-465f9b6f-a3dd-400d-855c-8d6b0378a64f-000000%40eu-central-1.amazonses.com.
