Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(157806)

Side by Side Diff: Doc/library/functions.rst

Issue 13424: Add examples for open’s new opener argument
Patch Set: Created 7 years, 1 month ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | Doc/library/io.rst » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 .. XXX document all delegations to __special__ methods 1 .. XXX document all delegations to __special__ methods
2 .. _built-in-funcs: 2 .. _built-in-funcs:
3 3
4 Built-in Functions 4 Built-in Functions
5 ================== 5 ==================
6 6
7 The Python interpreter has a number of functions and types built into it that 7 The Python interpreter has a number of functions and types built into it that
8 are always available. They are listed here in alphabetical order. 8 are always available. They are listed here in alphabetical order.
9 9
10 =================== ================= ================== ================ == ================== 10 =================== ================= ================== ================ == ==================
(...skipping 916 matching lines...) Expand 10 before | Expand all | Expand 10 after
927 If *closefd* is ``False`` and a file descriptor rather than a filename was 927 If *closefd* is ``False`` and a file descriptor rather than a filename was
928 given, the underlying file descriptor will be kept open when the file is 928 given, the underlying file descriptor will be kept open when the file is
929 closed. If a filename is given *closefd* has no effect and must be ``True`` 929 closed. If a filename is given *closefd* has no effect and must be ``True``
930 (the default). 930 (the default).
931 931
932 A custom opener can be used by passing a callable as *opener*. The underlying 932 A custom opener can be used by passing a callable as *opener*. The underlying
933 file descriptor for the file object is then obtained by calling *opener* with 933 file descriptor for the file object is then obtained by calling *opener* with
934 (*file*, *flags*). *opener* must return an open file descriptor (passing 934 (*file*, *flags*). *opener* must return an open file descriptor (passing
935 :mod:`os.open` as *opener* results in functionality similar to passing 935 :mod:`os.open` as *opener* results in functionality similar to passing
936 ``None``). 936 ``None``).
937
938 The following example is an alternative implementation for opening files
storchaka 2012/11/03 22:11:54 I doubt that an alternative implementation is a go
eric.araujo 2012/11/22 05:50:16 This was an easy idea for an example, and I though
939 for exclusive writing. Instead of passing ``'x'`` as the *mode*, we
940 create an open_exclusive function and use it as the *opener*::
941
942 >>> import os
943 >>> def open_exclusive(path, mode):
944 ... return os.open(path, mode | os.O_CREAT | os.O_EXCL)
945 ...
946 >>> filename = "/tmp/somefile"
947 >>> fp = open(filename, 'w', opener=open_exclusive)
948 >>> fp2 = open(filename, 'w', opener=open_exclusive)
949 Traceback (most recent call last):
950 File "<stdin>", line 1, in <module>
951 File "<stdin>", line 1, in <lambda>
952 FileExistsError: [Errno 17] File exists: '/tmp/somefile'
953
954 This other example uses the ``dir_fd`` parameter of the :mod:`os.open`
955 function to open a file relative to a given directory::
956
957 >>> import os
958 >>> def open_at(dirname):
959 ... dir_fd = os.open(dirname, os.O_RDONLY)
storchaka 2012/11/03 22:11:54 Here is a file descriptor leak.
eric.araujo 2012/11/22 05:50:16 Oops! I noticed the unclosed file objects in the
960 ... def opener(path, flags):
961 ... return os.open(path, flags, dir_fd=dir_fd)
962 ... return opener
963 ...
964 >>> with open("testfile", "w", opener=open_at("/tmp/somedir")) as f:
965 ... f.write("This will be written in the /tmp/somedir/testfile file.")
966 ...
937 967
938 .. versionchanged:: 3.3 968 .. versionchanged:: 3.3
939 The *opener* parameter was added. 969 The *opener* parameter was added.
940 The ``'x'`` mode was added. 970 The ``'x'`` mode was added.
941 971
942 The type of :term:`file object` returned by the :func:`open` function 972 The type of :term:`file object` returned by the :func:`open` function
943 depends on the mode. When :func:`open` is used to open a file in a text 973 depends on the mode. When :func:`open` is used to open a file in a text
944 mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of 974 mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
945 :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used 975 :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used
946 to open a file in a binary mode with buffering, the returned class is a 976 to open a file in a binary mode with buffering, the returned class is a
(...skipping 529 matching lines...) Expand 10 before | Expand all | Expand 10 after
1476 1506
1477 .. rubric:: Footnotes 1507 .. rubric:: Footnotes
1478 1508
1479 .. [#] Note that the parser only accepts the Unix-style end of line convention. 1509 .. [#] Note that the parser only accepts the Unix-style end of line convention.
1480 If you are reading the code from a file, make sure to use newline conversion 1510 If you are reading the code from a file, make sure to use newline conversion
1481 mode to convert Windows or Mac-style newlines. 1511 mode to convert Windows or Mac-style newlines.
1482 1512
1483 .. [#] In the current implementation, local variable bindings cannot normally be 1513 .. [#] In the current implementation, local variable bindings cannot normally be
1484 affected this way, but variables retrieved from other scopes (such as modules ) 1514 affected this way, but variables retrieved from other scopes (such as modules )
1485 can be. This may change. 1515 can be. This may change.
OLDNEW
« no previous file with comments | « no previous file | Doc/library/io.rst » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+