Opened 6 years ago

Closed 4 years ago

Last modified 4 years ago

#11441 closed (fixed)

Signal documentation should mention 'weak' parameter for connect

Reported by: Mike_A Owned by: gremmie
Component: Documentation Version: master
Severity: Keywords: weak signal dispatch_uid docs
Cc: gremmie 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 gremmie 5 years ago.

Download all attachments as: .zip

Change History (13)

comment:1 Changed 6 years ago by sayane

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Version changed from 1.0 to SVN

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

comment:2 Changed 6 years ago by Alex

  • Triage Stage changed from Unreviewed to Accepted

comment:3 Changed 5 years ago by aaugustin

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 5 years ago by gremmie

  • Cc gremmie added

comment:5 Changed 5 years ago by gremmie

  • Owner changed from nobody to gremmie

comment:6 Changed 5 years ago by gremmie

  • Status changed from new to assigned

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 5 years ago by gremmie

comment:7 Changed 5 years ago by gremmie

  • Has patch set

comment:8 Changed 5 years ago by airstrike

+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 5 years ago by airstrike

  • Keywords dispatch_uid docs added

comment:10 Changed 5 years ago by gremmie

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 4 years ago by gabrielhurley

  • Resolution set to fixed
  • Status changed from assigned to closed

(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 4 years ago by gabrielhurley

(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