[Django] #11441: Signal documentation should mention 'weak' parameter for connect

[Django]

#11441: Signal documentation should mention 'weak' parameter for connect
---------------------------+------------------------------------------------
Reporter: Mike_A | Owner: nobody
Status: new | Milestone:
Component: Documentation | Version: 1.0
Keywords: weak signal | Stage: Unreviewed
Has_patch: 0 |
---------------------------+------------------------------------------------
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.

--
Ticket URL: <http://code.djangoproject.com/ticket/11441>
Django <http://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#11441: Signal documentation should mention 'weak' parameter for connect

------------------------------------+---------------------------------------

Reporter: Mike_A | Owner: nobody
Status: new | Milestone:

Component: Documentation | Version: SVN
Resolution: | Keywords: weak signal
Stage: Unreviewed | Has_patch: 0
Needs_docs: 0 | Needs_tests: 0
Needs_better_patch: 0 |
------------------------------------+---------------------------------------
Changes (by sayane):

* needs_better_patch: => 0
* version: 1.0 => SVN
* needs_tests: => 0
* needs_docs: => 0

Comment:

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

--
Ticket URL: <http://code.djangoproject.com/ticket/11441#comment:1>

[Django]

#11441: Signal documentation should mention 'weak' parameter for connect

------------------------------------+---------------------------------------

Reporter: Mike_A | Owner: nobody
Status: new | Milestone:

Component: Documentation | Version: SVN
Resolution: | Keywords: weak signal

Stage: Accepted | Has_patch: 0

Needs_docs: 0 | Needs_tests: 0
Needs_better_patch: 0 |
------------------------------------+---------------------------------------

Comment (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 :)

--
Ticket URL: <http://code.djangoproject.com/ticket/11441#comment:3>

[Django]

#11441: Signal documentation should mention 'weak' parameter for connect

------------------------------------+---------------------------------------

Reporter: Mike_A | Owner: nobody
Status: new | Milestone:

Component: Documentation | Version: SVN
Resolution: | Keywords: weak signal
Stage: Accepted | Has_patch: 0
Needs_docs: 0 | Needs_tests: 0
Needs_better_patch: 0 |
------------------------------------+---------------------------------------

Changes (by gremmie):

* cc: gremmie (added)

--
Ticket URL: <http://code.djangoproject.com/ticket/11441#comment:4>

[Django]

#11441: Signal documentation should mention 'weak' parameter for connect

------------------------------------+---------------------------------------
Reporter: Mike_A | Owner: gremmie
Status: new | Milestone:

Component: Documentation | Version: SVN
Resolution: | Keywords: weak signal
Stage: Accepted | Has_patch: 0
Needs_docs: 0 | Needs_tests: 0
Needs_better_patch: 0 |
------------------------------------+---------------------------------------
Changes (by gremmie):

* owner: nobody => gremmie

--
Ticket URL: <http://code.djangoproject.com/ticket/11441#comment:5>

[Django]

#11441: Signal documentation should mention 'weak' parameter for connect

------------------------------------+---------------------------------------
Reporter: Mike_A | Owner: gremmie

Status: assigned | Milestone:

Component: Documentation | Version: SVN
Resolution: | Keywords: weak signal
Stage: Accepted | Has_patch: 0
Needs_docs: 0 | Needs_tests: 0
Needs_better_patch: 0 |
------------------------------------+---------------------------------------
Changes (by gremmie):

* status: new => assigned

Comment:

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.

--
Ticket URL: <http://code.djangoproject.com/ticket/11441#comment:6>

[Django]

#11441: Signal documentation should mention 'weak' parameter for connect

------------------------------------+---------------------------------------
Reporter: Mike_A | Owner: gremmie
Status: assigned | Milestone:
Component: Documentation | Version: SVN
Resolution: | Keywords: weak signal

Stage: Accepted | Has_patch: 1

Needs_docs: 0 | Needs_tests: 0
Needs_better_patch: 0 |
------------------------------------+---------------------------------------
Changes (by gremmie):

* has_patch: 0 => 1

--
Ticket URL: <http://code.djangoproject.com/ticket/11441#comment:7>

[Django]

#11441: Signal documentation should mention 'weak' parameter for connect

------------------------------------+---------------------------------------
Reporter: Mike_A | Owner: gremmie
Status: assigned | Milestone:
Component: Documentation | Version: SVN
Resolution: | Keywords: weak signal
Stage: Accepted | Has_patch: 1
Needs_docs: 0 | Needs_tests: 0
Needs_better_patch: 0 |
------------------------------------+---------------------------------------

Comment (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...

--
Ticket URL: <http://code.djangoproject.com/ticket/11441#comment:8>

[Django]

#11441: Signal documentation should mention 'weak' parameter for connect

------------------------------------+---------------------------------------
Reporter: Mike_A | Owner: gremmie
Status: assigned | Milestone:
Component: Documentation | Version: SVN

Resolution: | Keywords: weak signal dispatch_uid docs

Stage: Accepted | Has_patch: 1
Needs_docs: 0 | Needs_tests: 0
Needs_better_patch: 0 |
------------------------------------+---------------------------------------

Changes (by airstrike):

* keywords: weak signal => weak signal dispatch_uid docs

--
Ticket URL: <http://code.djangoproject.com/ticket/11441#comment:9>

[Django]

#11441: Signal documentation should mention 'weak' parameter for connect

------------------------------------+---------------------------------------
Reporter: Mike_A | Owner: gremmie
Status: assigned | Milestone:
Component: Documentation | Version: SVN
Resolution: | Keywords: weak signal dispatch_uid docs
Stage: Accepted | Has_patch: 1
Needs_docs: 0 | Needs_tests: 0
Needs_better_patch: 0 |
------------------------------------+---------------------------------------

Comment (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.

--
Ticket URL: <http://code.djangoproject.com/ticket/11441#comment:10>