update tempfile docs to say that TemporaryFile is secure

[zbysz]

BPO	23725
Nosy	@rhettinger, @gpshead, @ericvsmith, @rbtcollins, @bitdancer, @berkerpeksag, @vadmium
Files	0001-docs-update-description-of-TemporaryFile-and-tempfil.patch 0001-docs-update-description-of-TemporaryFile-and-tempfil.patch 0001-docs-update-description-of-TemporaryFile-and-tempfil.patch 0001-docs-update-description-of-TemporaryFile-and-tempfil.patch tempfile_docs.patch tempfile_docs.patch: v5 of patch tempfile_docs.patch issue-23725.patch issue-23725.patch: v8 of the patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2015-08-12.23:41:21.266>
created_at = <Date 2015-03-20.19:14:52.219>
labels = ['type-feature', 'docs']
title = 'update tempfile docs to say that TemporaryFile is secure'
updated_at = <Date 2015-08-12.23:41:21.265>
user = 'https://bugs.python.org/zbysz'

bugs.python.org fields:

activity = <Date 2015-08-12.23:41:21.265>
actor = 'rbcollins'
assignee = 'docs@python'
closed = True
closed_date = <Date 2015-08-12.23:41:21.266>
closer = 'rbcollins'
components = ['Documentation']
creation = <Date 2015-03-20.19:14:52.219>
creator = 'zbysz'
dependencies = []
files = ['38608', '38634', '38640', '38643', '39026', '39104', '39112', '40120', '40122']
hgrepos = []
issue_num = 23725
keywords = ['patch']
message_count = 26.0
messages = ['238713', '238750', '238759', '238916', '238959', '238970', '238972', '238974', '238980', '241060', '241062', '241063', '241420', '241447', '241448', '241467', '247954', '247958', '247959', '247962', '247968', '247970', '247974', '248482', '248489', '248490']
nosy_count = 10.0
nosy_names = ['rhettinger', 'gregory.p.smith', 'eric.smith', 'rbcollins', 'r.david.murray', 'zbysz', 'docs@python', 'python-dev', 'berker.peksag', 'martin.panter']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23725'
versions = ['Python 3.5', 'Python 3.6']

[zbysz]

tempfile docs can use some refreshing.

[berkerpeksag]

Thanks for the patch, Zbyszek. For future reference, please send patches from the Mercurial repository. It will make the patch review process easier. See also devguide.

+:func:`TemporaryDirectory`, :func:`SpooledTemporaryFile`, which can be

Both TemporaryDirectory and SpooledTemporaryFile are actually a class. See https://hg.python.org/cpython/file/3.4/Lib/tempfile.py#l510

+ :ref:`context-managers`). On completion of the context or

:ref:`context-managers` link is unnecessary in my opinion. It would be better to link https://docs.python.org/3/library/tempfile.html#examples

(Please update tempfile.TemporaryDirectory docs too.)

[bitdancer]

It would also be helpful to have a patch with minimum changes (that is, do not reflow the lines).

[zbysz]

v2:

• remove reflows
• update TemporaryDirectory description too
• do not call things which are not functions "functions"
• with O_TMPFILE the file is not unlinked, also update TemporaryFile description for that
• link to Examples

[vadmium]

[Padding]

Please start sentences with capital letters, specifically “mkstemp() and mkdtemp() are lower-level functions . . .”.

The new sentence at the top about context managers seems out-of-place. Perhaps something like “They can also be used as context managers, which triggers the cleanup on exit.”

The new paragraph about cleanup of TemporaryFile is good, but I think it now makes the last sentence of that entry redundant: “. . . can be used in a ‘with’ statement . . .”

[bitdancer]

If the first word is a function name that does not start with a capital, the sentence can't start with a capital. Sometimes it is worthwhile to reword the sentence so you can start it with a capitalizable word, but sometimes it isn't. (I haven't reviewed the patch, just putting in my two cents on this particular topic ;)

[zbysz]

Please start sentences with capital letters, specifically “mkstemp() and mkdtemp() are lower-level functions . . .”.

This would make the sentence more convoluted... I think that with markup it is pretty clear that this is a function name and the lowercase letter it not misleading.

The new sentence at the top about context managers seems out-of-place. Perhaps something like “They can also be used as context managers, which triggers the cleanup on exit.”

The two sentences are merged now.

The new paragraph about cleanup of TemporaryFile is good, but I think it now makes the last sentence of that entry redundant: “. . . can be used in a ‘with’ statement . . .”

Yes, removed.

v3:

• remove sentence “. . . can be used in a ‘with’ statement . . .”
• merge two senteces in first paragraph

[vadmium]

The current proposed text would be rendered something like this:

'''
TemporaryFile, NamedTemporaryFile, TemporaryDirectory, SpooledTemporaryFile are high-level interfaces which provide automatic cleanup and can be used as context managers. mkstemp() and mkdtemp() are lower-level functions which require manual cleanup.
'''

My opinion is it is very often worthwhile rewording the sentence. It is awkward to read at the moment, especially if you are trying to skim over it without reading the whole paragraph. Unlike in Python, in English there’s always more than one way to do it. Perhaps you could consider this version instead:

'''
The TemporaryFile, NamedTemporaryFile, TemporaryDirectory, [and] SpooledTemporaryFile classes are high-level interfaces which provide automatic cleanup and can be used as context managers. The mkstemp() and mkdtemp() functions are lower-level, and require manual cleanup.
'''

Only about three more words, and not particularly convoluted. But if you disagree, I can live with it, since there are plenty more examples of this in the Python documentation and elsewhere :)

Other than that, I think the patch is good.

[zbysz]

Actually they are not classes, so the proposed wording cannot be used. But indeed it sounds better with the "and".

v4:

• one more "and"