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).

s/TextIOWrapper/FileIO/

Here is a proposed patch to the documentation.

New changeset 17b094c08600 by Éric Araujo in branch '3.3':
Add examples for opener argument of open (bpo-13424).
http://hg.python.org/cpython/rev/17b094c08600

Fixed, thanks!

See my comments in Rietveld.

fd leak fixed in 95ea024f0569.

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.

There's also a Sphinx warning that should be fixed:
3.3/Doc/library/functions.rst:955: WARNING: undefined label: dir_fd (if the link has no caption the label must precede a section header)

New changeset bf1bf3bf3fe2 by Éric Araujo in branch '3.3':
Address reviews for open’s opener argument doc patch (bpo-13424).
http://hg.python.org/cpython/rev/bf1bf3bf3fe2

New changeset 8ca6f4953c4b by Éric Araujo in branch 'default':
Merge bpo-13424 followup from 3.3
http://hg.python.org/cpython/rev/8ca6f4953c4b

Thanks for all comments. If you think of a better example to show the usage of the argument, feel free to change it.