classification
Title: hmac.new docs show optional args incorrectly
Type: Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, docs@python, r.david.murray, roysmith
Priority: normal Keywords:

Created on 2014-11-16 03:25 by roysmith, last changed 2014-11-16 16:54 by r.david.murray. This issue is now closed.

Messages (3)
msg231231 - (view) Author: Roy Smith (roysmith) Date: 2014-11-16 03:25
At https://docs.python.org/2/library/hmac.html, hmac.new() is shown as

hmac.new(key[, msg[, digestmod]])

This implies that digestmod can only be given if msg is given.  This is incorrect.  Either can be given without the other.
msg231236 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-11-16 08:22
Thanks for the report, but the signature is correct.

From https://docs.python.org/devguide/documenting.html#information-units

    "The signature should include the parameters, enclosing optional parameters in brackets."

See also http://sphinx-doc.org/domains.html#python-signatures
msg231252 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-11-16 16:54
To be clear: this was/is the python2 documentation style.  In python3 we've switched to using keyword argument notation in functions that support specifying optional arguments via keyword (which is many more of the C functions than in python2).
History
Date User Action Args
2014-11-16 16:54:44r.david.murraysetnosy: + r.david.murray
messages: + msg231252
2014-11-16 08:22:59berker.peksagsetstatus: open -> closed

nosy: + berker.peksag
messages: + msg231236

resolution: not a bug
stage: resolved
2014-11-16 03:25:58roysmithcreate