@@ -83,51 +83,52 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None, |
83 | 83 | wrapped. (If a file descriptor is given, it is closed when the |
84 | 84 | returned I/O object is closed, unless closefd is set to False.) |
85 | 85 |
|
86 | | - mode is an optional string that specifies the mode in which the file is |
87 | | - opened. It defaults to 'r' which means open for reading in text mode. Other |
88 | | - common values are 'w' for writing (truncating the file if it already |
89 | | - exists), 'x' for exclusive creation of a new file, and 'a' for appending |
90 | | - (which on some Unix systems, means that all writes append to the end of the |
91 | | - file regardless of the current seek position). In text mode, if encoding is |
92 | | - not specified the encoding used is platform dependent. (For reading and |
93 | | - writing raw bytes use binary mode and leave encoding unspecified.) The |
94 | | - available modes are: |
95 | | -
|
96 | | - ========= =============================================================== |
| 86 | + mode is an optional string that specifies the mode in which the file |
| 87 | + is opened. It defaults to 'r' which means open for reading in text |
| 88 | + mode. Other common values are 'w' for writing (truncating the file if |
| 89 | + it already exists), 'x' for exclusive creation of a new file, and |
| 90 | + 'a' for appending (which on some Unix systems, means that all writes |
| 91 | + append to the end of the file regardless of the current seek position). |
| 92 | + In text mode, if encoding is not specified the encoding used is platform |
| 93 | + dependent. (For reading and writing raw bytes use binary mode and leave |
| 94 | + encoding unspecified.) The available modes are: |
| 95 | +
|
| 96 | + ========= ========================================================== |
97 | 97 | Character Meaning |
98 | | - --------- --------------------------------------------------------------- |
| 98 | + --------- ---------------------------------------------------------- |
99 | 99 | 'r' open for reading (default) |
100 | 100 | 'w' open for writing, truncating the file first |
101 | 101 | 'x' create a new file and open it for writing |
102 | | - 'a' open for writing, appending to the end of the file if it exists |
| 102 | + 'a' open for writing, appending to the end of the file if it |
| 103 | + exists |
103 | 104 | 'b' binary mode |
104 | 105 | 't' text mode (default) |
105 | 106 | '+' open a disk file for updating (reading and writing) |
106 | | - ========= =============================================================== |
| 107 | + ========= ========================================================== |
107 | 108 |
|
108 | 109 | The default mode is 'rt' (open for reading text). For binary random |
109 | 110 | access, the mode 'w+b' opens and truncates the file to 0 bytes, while |
110 | 111 | 'r+b' opens the file without truncation. The 'x' mode implies 'w' and |
111 | 112 | raises an `FileExistsError` if the file already exists. |
112 | 113 |
|
113 | 114 | Python distinguishes between files opened in binary and text modes, |
114 | | - even when the underlying operating system doesn't. Files opened in |
| 115 | + even when the underlying operating system doesn't. Files opened in |
115 | 116 | binary mode (appending 'b' to the mode argument) return contents as |
116 | | - bytes objects without any decoding. In text mode (the default, or when |
| 117 | + bytes objects without any decoding. In text mode (the default, or when |
117 | 118 | 't' is appended to the mode argument), the contents of the file are |
118 | 119 | returned as strings, the bytes having been first decoded using a |
119 | 120 | platform-dependent encoding or using the specified encoding if given. |
120 | 121 |
|
121 | 122 | buffering is an optional integer used to set the buffering policy. |
122 | | - Pass 0 to switch buffering off (only allowed in binary mode), 1 to select |
123 | | - line buffering (only usable in text mode), and an integer > 1 to indicate |
124 | | - the size of a fixed-size chunk buffer. When no buffering argument is |
125 | | - given, the default buffering policy works as follows: |
| 123 | + Pass 0 to switch buffering off (only allowed in binary mode), 1 to |
| 124 | + select line buffering (only usable in text mode), and an integer > 1 to |
| 125 | + indicate the size of a fixed-size chunk buffer. When no buffering |
| 126 | + argument is given, the default buffering policy works as follows: |
126 | 127 |
|
127 | | - * Binary files are buffered in fixed-size chunks; the size of the buffer |
128 | | - is max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE) |
129 | | - when the device block size is available. |
130 | | - On most systems, the buffer will typically be 128 kilobytes long. |
| 128 | + * Binary files are buffered in fixed-size chunks; the size of the buffer |
| 129 | + is max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE) when the device |
| 130 | + block size is available. |
| 131 | + On most systems, the buffer will typically be 128 kilobytes long. |
131 | 132 |
|
132 | 133 | * "Interactive" text files (files for which isatty() returns True) |
133 | 134 | use line buffering. Other text files use the policy described above |
@@ -147,8 +148,8 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None, |
147 | 148 | encoding error strings. |
148 | 149 |
|
149 | 150 | newline is a string controlling how universal newlines works (it only |
150 | | - applies to text mode). It can be None, '', '\n', '\r', and '\r\n'. It works |
151 | | - as follows: |
| 151 | + applies to text mode). It can be None, '', '\n', '\r', and '\r\n'. It |
| 152 | + works as follows: |
152 | 153 |
|
153 | 154 | * On input, if newline is None, universal newlines mode is |
154 | 155 | enabled. Lines in the input can end in '\n', '\r', or '\r\n', and |
@@ -164,17 +165,17 @@ def open(file, mode="r", buffering=-1, encoding=None, errors=None, |
164 | 165 | other legal values, any '\n' characters written are translated to |
165 | 166 | the given string. |
166 | 167 |
|
167 | | - closedfd is a bool. If closefd is False, the underlying file descriptor will |
168 | | - be kept open when the file is closed. This does not work when a file name is |
169 | | - given and must be True in that case. |
| 168 | + closedfd is a bool. If closefd is False, the underlying file descriptor |
| 169 | + will be kept open when the file is closed. This does not work when |
| 170 | + a file name is given and must be True in that case. |
170 | 171 |
|
171 | 172 | The newly created file is non-inheritable. |
172 | 173 |
|
173 | 174 | A custom opener can be used by passing a callable as *opener*. The |
174 | | - underlying file descriptor for the file object is then obtained by calling |
175 | | - *opener* with (*file*, *flags*). *opener* must return an open file |
176 | | - descriptor (passing os.open as *opener* results in functionality similar to |
177 | | - passing None). |
| 175 | + underlying file descriptor for the file object is then obtained by |
| 176 | + calling *opener* with (*file*, *flags*). *opener* must return an open |
| 177 | + file descriptor (passing os.open as *opener* results in functionality |
| 178 | + similar to passing None). |
178 | 179 |
|
179 | 180 | open() returns a file object whose type depends on the mode, and |
180 | 181 | through which the standard file operations such as reading and writing |
@@ -351,10 +352,12 @@ def seek(self, pos, whence=0): |
351 | 352 | interpreted relative to the position indicated by whence. Values |
352 | 353 | for whence are ints: |
353 | 354 |
|
354 | | - * 0 -- start of stream (the default); offset should be zero or positive |
| 355 | + * 0 -- start of stream (the default); offset should be zero or |
| 356 | + positive |
355 | 357 | * 1 -- current stream position; offset may be negative |
356 | 358 | * 2 -- end of stream; offset is usually negative |
357 | | - Some operating systems / file systems could provide additional values. |
| 359 | + Some operating systems / file systems could provide additional |
| 360 | + values. |
358 | 361 |
|
359 | 362 | Return an int indicating the new absolute position. |
360 | 363 | """ |
@@ -367,8 +370,8 @@ def tell(self): |
367 | 370 | def truncate(self, pos=None): |
368 | 371 | """Truncate file to size bytes. |
369 | 372 |
|
370 | | - Size defaults to the current IO position as reported by tell(). Return |
371 | | - the new size. |
| 373 | + Size defaults to the current IO position as reported by tell(). |
| 374 | + Return the new size. |
372 | 375 | """ |
373 | 376 | self._unsupported("truncate") |
374 | 377 |
|
@@ -492,7 +495,8 @@ def __exit__(self, *args): |
492 | 495 | def fileno(self): |
493 | 496 | """Returns underlying file descriptor (an int) if one exists. |
494 | 497 |
|
495 | | - An OSError is raised if the IO object does not use a file descriptor. |
| 498 | + An OSError is raised if the IO object does not use a file |
| 499 | + descriptor. |
496 | 500 | """ |
497 | 501 | self._unsupported("fileno") |
498 | 502 |
|
@@ -1505,17 +1509,22 @@ class FileIO(RawIOBase): |
1505 | 1509 | _closefd = True |
1506 | 1510 |
|
1507 | 1511 | def __init__(self, file, mode='r', closefd=True, opener=None): |
1508 | | - """Open a file. The mode can be 'r' (default), 'w', 'x' or 'a' for reading, |
1509 | | - writing, exclusive creation or appending. The file will be created if it |
1510 | | - doesn't exist when opened for writing or appending; it will be truncated |
1511 | | - when opened for writing. A FileExistsError will be raised if it already |
1512 | | - exists when opened for creating. Opening a file for creating implies |
1513 | | - writing so this mode behaves in a similar way to 'w'. Add a '+' to the mode |
1514 | | - to allow simultaneous reading and writing. A custom opener can be used by |
1515 | | - passing a callable as *opener*. The underlying file descriptor for the file |
1516 | | - object is then obtained by calling opener with (*name*, *flags*). |
1517 | | - *opener* must return an open file descriptor (passing os.open as *opener* |
1518 | | - results in functionality similar to passing None). |
| 1512 | + """Open a file. |
| 1513 | +
|
| 1514 | + The mode can be 'r' (default), 'w', 'x' or 'a' for reading, |
| 1515 | + writing, exclusive creation or appending. The file will be created |
| 1516 | + if it doesn't exist when opened for writing or appending; it will be |
| 1517 | + truncated when opened for writing. A FileExistsError will be raised |
| 1518 | + if it already exists when opened for creating. Opening a file for |
| 1519 | + creating implies writing so this mode behaves in a similar way to |
| 1520 | + 'w'. Add a '+' to the mode to allow simultaneous reading and |
| 1521 | + writing. |
| 1522 | +
|
| 1523 | + A custom opener can be used by passing a callable as *opener*. |
| 1524 | + The underlying file descriptor for the file object is then obtained |
| 1525 | + by calling opener with (*name*, *flags*). *opener* must return |
| 1526 | + an open file descriptor (passing os.open as *opener* results in |
| 1527 | + functionality similar to passing None). |
1519 | 1528 | """ |
1520 | 1529 | if self._fd >= 0: |
1521 | 1530 | # Have to close the existing file first. |
@@ -1754,8 +1763,8 @@ def write(self, b): |
1754 | 1763 | """Write bytes b to file, return number written. |
1755 | 1764 |
|
1756 | 1765 | Only makes one system call, so not all of the data may be written. |
1757 | | - The number of bytes actually written is returned. In non-blocking mode, |
1758 | | - returns None if the write would block. |
| 1766 | + The number of bytes actually written is returned. In non-blocking |
| 1767 | + mode, returns None if the write would block. |
1759 | 1768 | """ |
1760 | 1769 | self._checkClosed() |
1761 | 1770 | self._checkWritable() |
@@ -1767,11 +1776,12 @@ def write(self, b): |
1767 | 1776 | def seek(self, pos, whence=SEEK_SET): |
1768 | 1777 | """Move to new file position. |
1769 | 1778 |
|
1770 | | - Argument offset is a byte count. Optional argument whence defaults to |
1771 | | - SEEK_SET or 0 (offset from start of file, offset should be >= 0); other values |
1772 | | - are SEEK_CUR or 1 (move relative to current position, positive or negative), |
1773 | | - and SEEK_END or 2 (move relative to end of file, usually negative, although |
1774 | | - many platforms allow seeking beyond the end of a file). |
| 1779 | + Argument offset is a byte count. Optional argument whence defaults |
| 1780 | + to SEEK_SET or 0 (offset from start of file, offset should be >= 0); |
| 1781 | + other values are SEEK_CUR or 1 (move relative to current position, |
| 1782 | + positive or negative), and SEEK_END or 2 (move relative to end of |
| 1783 | + file, usually negative, although many platforms allow seeking beyond |
| 1784 | + the end of a file). |
1775 | 1785 |
|
1776 | 1786 | Note that not all file objects are seekable. |
1777 | 1787 | """ |
@@ -1804,8 +1814,8 @@ def truncate(self, size=None): |
1804 | 1814 | def close(self): |
1805 | 1815 | """Close the file. |
1806 | 1816 |
|
1807 | | - A closed file cannot be used for further I/O operations. close() may be |
1808 | | - called more than once without error. |
| 1817 | + A closed file cannot be used for further I/O operations. |
| 1818 | + close() may be called more than once without error. |
1809 | 1819 | """ |
1810 | 1820 | if not self.closed: |
1811 | 1821 | self._stat_atopen = None |
@@ -1903,8 +1913,8 @@ class TextIOBase(IOBase): |
1903 | 1913 | def read(self, size=-1): |
1904 | 1914 | """Read at most size characters from stream, where size is an int. |
1905 | 1915 |
|
1906 | | - Read from underlying buffer until we have size characters or we hit EOF. |
1907 | | - If size is negative or omitted, read until EOF. |
| 1916 | + Read from underlying buffer until we have size characters or we hit |
| 1917 | + EOF. If size is negative or omitted, read until EOF. |
1908 | 1918 |
|
1909 | 1919 | Returns a string. |
1910 | 1920 | """ |
|