classification
Title: Add examples for open’s new opener argument
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: docs@python, eric.araujo, ezio.melotti, guillaumep, python-dev, rosslagerwall, serhiy.storchaka
Priority: normal Keywords: easy, patch

Created on 2011-11-18 09:52 by eric.araujo, last changed 2012-11-22 05:17 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
13424.patch guillaumep, 2012-11-03 20:18 review
Messages (11)
msg147840 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-11-18 09:52
The new opener argument to open and TextIOWrapper closed two bugs on this tracker: using O_CLOEXEC and replacing the unofficial 'c' mode (O_CREATE).  I think it’d be nice to have these as examples (maybe not in the docs of TextIOWrapper which are already huge, but for example in the os docs after the O_* constants).
msg147842 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-11-18 09:55
s/TextIOWrapper/FileIO/
msg174687 - (view) Author: Guillaume P (guillaumep) Date: 2012-11-03 20:18
Here is a proposed patch to the documentation.
msg174695 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-11-03 21:10
New changeset 17b094c08600 by Éric Araujo in branch '3.3':
Add examples for opener argument of open (#13424).
http://hg.python.org/cpython/rev/17b094c08600
msg174697 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-11-03 21:13
Fixed, thanks!
msg174698 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-11-03 21:14
See my comments in Rietveld.
msg174701 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-11-03 21:41
fd leak fixed in 95ea024f0569.
msg174779 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-11-04 11:09
Isn't it be clearer?

      >>> import os
      >>> dir_fd = os.open('somedir', os.O_RDONLY)
      >>> def opener(path, flags):
      ...     return os.open(path, flags, dir_fd=dir_fd)
      ...
      >>> with open('spamspam.txt', 'w', opener=opener) as f:
      ...     print('This will be written to somedir/spamspam.txt', file=f)
      ...
      >>> os.close(dir_fd)  # don't leak a file descriptor

Or if you want stronger example:

      >>> import os, contextlib, functools
      >>> @contextlib.contextmanager
      ... def open_relative(dirname):
      ...     dir_fd = os.open(dirname, os.O_RDONLY)
      ...     def opener(path, flags):
      ...         return os.open(path, flags, dir_fd=dir_fd)
      ...     try:
      ...         yield functools.partial(open, opener=opener)
      ...     finally:
      ...         os.close(dir_fd)
      ...
      >>> with open_relative('somedir') as open:
      ...     with open('spamspam.txt', 'w') as f:
      ...         print('This will be written to somedir/spamspam.txt', file=f)
      ...

Frankly speaking, all of these examples looks unconvincing to me.  Even the second example could be implemented without an "opener" argument.
msg175788 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-17 17:36
There's also a Sphinx warning that should be fixed:
Doc/library/functions.rst:955: WARNING: undefined label: dir_fd (if the link has no caption the label must precede a section header)
msg176096 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-11-22 05:15
New changeset bf1bf3bf3fe2 by Éric Araujo in branch '3.3':
Address reviews for open’s opener argument doc patch (#13424).
http://hg.python.org/cpython/rev/bf1bf3bf3fe2

New changeset 8ca6f4953c4b by Éric Araujo in branch 'default':
Merge #13424 followup from 3.3
http://hg.python.org/cpython/rev/8ca6f4953c4b
msg176097 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-11-22 05:17
Thanks for all comments.  If you think of a better example to show the usage of the argument, feel free to change it.
History
Date User Action Args
2012-11-22 05:17:30eric.araujosetstatus: open -> closed
messages: + msg176097

assignee: docs@python -> eric.araujo
resolution: fixed
stage: commit review -> resolved
2012-11-22 05:15:34python-devsetmessages: + msg176096
2012-11-17 17:36:02ezio.melottisetnosy: + ezio.melotti
messages: + msg175788
2012-11-04 11:09:54serhiy.storchakasetmessages: + msg174779
2012-11-03 21:41:59eric.araujosetmessages: + msg174701
2012-11-03 21:15:31eric.araujosetstatus: closed -> open
resolution: fixed -> (no value)
stage: resolved -> commit review
2012-11-03 21:14:35serhiy.storchakasettype: enhancement

messages: + msg174698
nosy: + serhiy.storchaka
2012-11-03 21:13:53eric.araujosetstatus: open -> closed
versions: + Python 3.4
messages: + msg174697

resolution: fixed
stage: needs patch -> resolved
2012-11-03 21:10:12python-devsetnosy: + python-dev
messages: + msg174695
2012-11-03 20:18:10guillaumepsetfiles: + 13424.patch

nosy: + guillaumep
messages: + msg174687

keywords: + patch
2011-11-19 14:09:03ezio.melottisetkeywords: + easy
stage: needs patch
2011-11-18 14:19:08rosslagerwallsetnosy: + rosslagerwall
2011-11-18 09:55:52eric.araujosetmessages: + msg147842
2011-11-18 09:52:13eric.araujocreate