User report (Jiachang Xu) from the docs mailing list:

The theading.Condition.notify method has a parameter - n, which isn't documented in the the documentation of the threading module.

1. The parameter should be documented
2. notify() is mentioned multiple times in the docs of threading - perhaps the parameter should be mentioned in more than one place as well
3. The parameter should also be documented in the doc-string of notify in Lib/theading.py - however, this may be a separate issue since currently none of the methods of Condition has docstrings.

Opened Issue 12768 on the general lack of docstrings in the threading module

From a quick look at the code and docs I suspect that 'n' is an internal implementation detail and not meant to be exposed.  Is there an use case for notifying waiters where n!=1 and n!=len(waiters)?  If my speculation is correct it might be a good idea to refactor this so that notify itself does not take an argument but instead both it an notify_all call an explicitly internal routine _notify.

David, while you make a valid point, consider that 'n' is part of the public API of the threading module (although not documented) and it's conceivable that there is existing code "in the wild" using it. To do what you suggest we should maybe go through a normal deprecation process for this argument first?

Adding Antoine as the listed threading expert.

Good point.  Probably, then, we should just put a comment in the code that 'n' is an internal implementation detail and leave it at that.

I asked the user who reported this documentation omission what he's using the 'n' argument for. His reply:

    "Yes I am using the n parameter, it is mainly to implement a subclass of Queue that supports "bulk" get and put operations. This enhances the performance of repeated get/put calls when the Queue is created using multiprocessing.Manager."

> I asked the user who reported this documentation omission what he's
> using the 'n' argument for. His reply:
> 
>     "Yes I am using the n parameter, it is mainly to implement a
> subclass of Queue that supports "bulk" get and put operations. This
> enhances the performance of repeated get/put calls when the Queue is
> created using multiprocessing.Manager."

I think it's fine to document it. It's been there for a long time.
Besides, if we know how to notify one thread, we are certainly able to
notify n of them :)

I have added documentation for the 'n' parameter of threading.Condition.notify as part of the overhaul of the threading module's docstrings.

Reference: #12768

I propose the attached patch for the documentation. Any objections?

+      This method wakes up at most *n* of the threads
+      The current implementation wakes up exactly *n* threads
+      A future, optimized implementation may occasionally wake up more than
+      one thread.

Isn't this a bit contradictory?

Ezio, thanks for the catch. I missed that one. Attaching a new, fixed patch.

New changeset 63a24bff6f36 by Eli Bendersky in branch '3.2':
Issue #12767: documenting threading.Condition.notify
http://hg.python.org/cpython/rev/63a24bff6f36

New changeset ac12dcea69e1 by Eli Bendersky in branch 'default':
Issue 12767: document the argument of threading.Condition.notify
http://hg.python.org/cpython/rev/ac12dcea69e1

New changeset 63a00d019bb2 by Eli Bendersky in branch '2.7':
Closes issue 12767: document the argument of threading.Condition.notify
http://hg.python.org/cpython/rev/63a00d019bb2