Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#11441 closed (fixed)

Signal documentation should mention 'weak' parameter for connect

Reported by: Mike_A Owned by: Brian Neal
Component: Documentation Version: master
Severity: Keywords: weak signal dispatch_uid docs
Cc: Brian Neal Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

In the documentation for signals: http://docs.djangoproject.com/en/dev/topics/signals/

No reference at all is made to the 'weak' parameter of connect.
This caused me to spend about an hour scratching my head as to why my signals didn't seem to work at all.
In the end I realised I needed to set this to False to stop the signal from dropping the callback and silently failing, but only after writing a debugging signal class.

Attachments (1)

patch11441-1.diff (5.5 KB) - added by Brian Neal 6 years ago.

Download all attachments as: .zip

Change History (13)

comment:1 Changed 7 years ago by Sayane

Version: 1.0SVN

AND dispatch_uid argument
AND send_robust function
AND disconnect function
;-)

comment:2 Changed 7 years ago by Alex Gaynor

Triage Stage: UnreviewedAccepted

comment:3 Changed 6 years ago by Aymeric Augustin

There is already a short explanation for 'weak' here: http://docs.djangoproject.com/en/dev/ref/signals/#module-django.db.models.signals

If it should be set to False only for local functions, this explanation is sufficient.


On the other hand, the docs do not mention dispatch_uid at all. There is a note in the wiki, which could (should?) be moved to the signal documentation: http://code.djangoproject.com/wiki/Signals#Helppost_saveseemstobeemittedtwiceforeachsave

I found #3951 and that wiki page after a long pdb session, trying to understand why my handlers were called twice...


send_robust and disconnect only have docstrings, as far as I can tell. So currently it's RTFS :)

comment:4 Changed 6 years ago by Brian Neal

Cc: Brian Neal added

comment:5 Changed 6 years ago by Brian Neal

Owner: changed from nobody to Brian Neal

comment:6 Changed 6 years ago by Brian Neal

Status: newassigned

I have worked up my first substantial patch for Django for this ticket. Be advised this was the first time I had used sphinx or made a documentation change. I'm hoping a committer can either give me feedback on the patch, or just use it as the basis to provide better words. :-)

I have attempted to document the weak and dispatch_uid arguments to Signal.connect().
I have also attempted to document Signal.send_robust() and Signal.disconnect().

I also fixed some typos in the docstrings of dispatch.py.

Changed 6 years ago by Brian Neal

Attachment: patch11441-1.diff added

comment:7 Changed 6 years ago by Brian Neal

Has patch: set

comment:8 Changed 6 years ago by André Terra

+1 on documenting dispatch_uid!

I'm willing to go as far as suggesting that dispatch_uid be made a required kwarg in order to prevent post_save signals being duplicated. It caused me over 24 hours of frustrating commits, rollbacks, and debugging...

comment:9 Changed 6 years ago by André Terra

Keywords: dispatch_uid docs added

comment:10 Changed 6 years ago by Brian Neal

airstrike (or anyone else), I need someone to peer review my patch. If you are good with it, please mark this ticket's triage stage to "ready for checkin". Otherwise please leave comments on how I may improve it here. Thanks.

comment:11 Changed 6 years ago by Gabriel Hurley

Resolution: fixed
Status: assignedclosed

(In [14337]) Fixed #11441 -- Improved signal topic guide, particularly regarding the weak and dispatch_uid parameters to the Signal.connect method. Thanks to Mike_A and sayane for the report, and gremmie for the draft patch.

comment:12 Changed 6 years ago by Gabriel Hurley

(In [14338]) [1.2.X] Fixed #11441 -- Improved signal topic guide, particularly regarding the weak and dispatch_uid parameters to the Signal.connect method. Thanks to Mike_A and sayane for the report, and gremmie for the draft patch.

Backport of [14337] from trunk.

Note: See TracTickets for help on using tickets.
Back to Top