classification
Title: Import secrets module in secrets examples
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: dchimeno, docs@python, steven.daprano
Priority: normal Keywords: patch

Created on 2018-05-05 08:54 by dchimeno, last changed 2018-05-19 15:04 by steven.daprano. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 6705 merged dchimeno, 2018-05-05 09:43
Messages (4)
msg316200 - (view) Author: Daniel Chimeno (dchimeno) * Date: 2018-05-05 08:54
In the secrets module documentation, the examples in `15.3.4. Recipes and best practices` need change things, I think this examples must run after a copy & paste into user terminal.

Options for first example:
1:
````
import string
from secrets import choice
alphabet = string.ascii_letters + string.digits
password = ''.join(choice(alphabet) for i in range(8))
````

2:
```
import string
import secrets
alphabet = string.ascii_letters + string.digits
password = ''.join(secrets.choice(alphabet) for i in range(8))
````

I've looked in the devguide, but I haven't found what's the standard approach here.

First issue here, be nice :)
msg316201 - (view) Author: Daniel Chimeno (dchimeno) * Date: 2018-05-05 09:04
Relevant link: https://docs.python.org/3.7/library/secrets.html#recipes-and-best-practices
msg316202 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2018-05-05 09:14
I've always expected that documentation for a module can assume that the module itself, and/or the function being described, has been imported.

On the other hand, I have no objection to making this explicit, especially in the recipes section where it might not be as clear which functions come from the module and which are builtins.

I'm inclined to go for your 2nd option, import the module and use a full-qualified name:

password = ''.join(secrets.choice(alphabet) for i in range(8))
msg317124 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2018-05-19 15:04
Unless I've mucked it up, I just committed your patch on Github so I'm closing this ticket. Thanks.
History
Date User Action Args
2018-05-19 15:04:03steven.dapranosetstatus: open -> closed

messages: + msg317124
stage: patch review -> resolved
2018-05-05 09:43:10dchimenosetkeywords: + patch
stage: patch review
pull_requests: + pull_request6397
2018-05-05 09:14:29steven.dapranosetnosy: + steven.daprano
messages: + msg316202
2018-05-05 09:04:18dchimenosetmessages: + msg316201
2018-05-05 08:54:12dchimenocreate