Skip to content

Commit bd6d4ed

Browse files
barneygalebarneygale
authored
GH-119054: Add "Reading and writing files" section to pathlib docs (#119524)
Add a dedicated subsection for `open()`, `read_text()`, `read_bytes()`, `write_text()` and `write_bytes()`.
1 parent aa9fe98 commit bd6d4ed

File tree

1 file changed

+84
-79
lines changed

1 file changed

+84
-79
lines changed

‎Doc/library/pathlib.rst

+84-79
Original file line numberDiff line numberDiff line change
@@ -1067,6 +1067,90 @@ Querying file type and status
10671067
.. versionadded:: 3.5
10681068

10691069

1070+
Reading and writing files
1071+
^^^^^^^^^^^^^^^^^^^^^^^^^
1072+
1073+
1074+
.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)
1075+
1076+
Open the file pointed to by the path, like the built-in :func:`open`
1077+
function does::
1078+
1079+
>>> p = Path('setup.py')
1080+
>>> with p.open() as f:
1081+
... f.readline()
1082+
...
1083+
'#!/usr/bin/env python3\n'
1084+
1085+
1086+
.. method:: Path.read_text(encoding=None, errors=None, newline=None)
1087+
1088+
Return the decoded contents of the pointed-to file as a string::
1089+
1090+
>>> p = Path('my_text_file')
1091+
>>> p.write_text('Text file contents')
1092+
18
1093+
>>> p.read_text()
1094+
'Text file contents'
1095+
1096+
The file is opened and then closed. The optional parameters have the same
1097+
meaning as in :func:`open`.
1098+
1099+
.. versionadded:: 3.5
1100+
1101+
.. versionchanged:: 3.13
1102+
The *newline* parameter was added.
1103+
1104+
1105+
.. method:: Path.read_bytes()
1106+
1107+
Return the binary contents of the pointed-to file as a bytes object::
1108+
1109+
>>> p = Path('my_binary_file')
1110+
>>> p.write_bytes(b'Binary file contents')
1111+
20
1112+
>>> p.read_bytes()
1113+
b'Binary file contents'
1114+
1115+
.. versionadded:: 3.5
1116+
1117+
1118+
.. method:: Path.write_text(data, encoding=None, errors=None, newline=None)
1119+
1120+
Open the file pointed to in text mode, write *data* to it, and close the
1121+
file::
1122+
1123+
>>> p = Path('my_text_file')
1124+
>>> p.write_text('Text file contents')
1125+
18
1126+
>>> p.read_text()
1127+
'Text file contents'
1128+
1129+
An existing file of the same name is overwritten. The optional parameters
1130+
have the same meaning as in :func:`open`.
1131+
1132+
.. versionadded:: 3.5
1133+
1134+
.. versionchanged:: 3.10
1135+
The *newline* parameter was added.
1136+
1137+
1138+
.. method:: Path.write_bytes(data)
1139+
1140+
Open the file pointed to in bytes mode, write *data* to it, and close the
1141+
file::
1142+
1143+
>>> p = Path('my_binary_file')
1144+
>>> p.write_bytes(b'Binary file contents')
1145+
20
1146+
>>> p.read_bytes()
1147+
b'Binary file contents'
1148+
1149+
An existing file of the same name is overwritten.
1150+
1151+
.. versionadded:: 3.5
1152+
1153+
10701154
Other methods
10711155
^^^^^^^^^^^^^
10721156

@@ -1360,18 +1444,6 @@ example because the path doesn't exist).
13601444
The *exist_ok* parameter was added.
13611445

13621446

1363-
.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)
1364-
1365-
Open the file pointed to by the path, like the built-in :func:`open`
1366-
function does::
1367-
1368-
>>> p = Path('setup.py')
1369-
>>> with p.open() as f:
1370-
... f.readline()
1371-
...
1372-
'#!/usr/bin/env python3\n'
1373-
1374-
13751447
.. method:: Path.owner(*, follow_symlinks=True)
13761448

13771449
Return the name of the user owning the file. :exc:`KeyError` is raised
@@ -1388,37 +1460,6 @@ example because the path doesn't exist).
13881460
The *follow_symlinks* parameter was added.
13891461

13901462

1391-
.. method:: Path.read_bytes()
1392-
1393-
Return the binary contents of the pointed-to file as a bytes object::
1394-
1395-
>>> p = Path('my_binary_file')
1396-
>>> p.write_bytes(b'Binary file contents')
1397-
20
1398-
>>> p.read_bytes()
1399-
b'Binary file contents'
1400-
1401-
.. versionadded:: 3.5
1402-
1403-
1404-
.. method:: Path.read_text(encoding=None, errors=None, newline=None)
1405-
1406-
Return the decoded contents of the pointed-to file as a string::
1407-
1408-
>>> p = Path('my_text_file')
1409-
>>> p.write_text('Text file contents')
1410-
18
1411-
>>> p.read_text()
1412-
'Text file contents'
1413-
1414-
The file is opened and then closed. The optional parameters have the same
1415-
meaning as in :func:`open`.
1416-
1417-
.. versionadded:: 3.5
1418-
1419-
.. versionchanged:: 3.13
1420-
The *newline* parameter was added.
1421-
14221463
.. method:: Path.readlink()
14231464

14241465
Return the path to which the symbolic link points (as returned by
@@ -1593,42 +1634,6 @@ example because the path doesn't exist).
15931634
The *missing_ok* parameter was added.
15941635

15951636

1596-
.. method:: Path.write_bytes(data)
1597-
1598-
Open the file pointed to in bytes mode, write *data* to it, and close the
1599-
file::
1600-
1601-
>>> p = Path('my_binary_file')
1602-
>>> p.write_bytes(b'Binary file contents')
1603-
20
1604-
>>> p.read_bytes()
1605-
b'Binary file contents'
1606-
1607-
An existing file of the same name is overwritten.
1608-
1609-
.. versionadded:: 3.5
1610-
1611-
1612-
.. method:: Path.write_text(data, encoding=None, errors=None, newline=None)
1613-
1614-
Open the file pointed to in text mode, write *data* to it, and close the
1615-
file::
1616-
1617-
>>> p = Path('my_text_file')
1618-
>>> p.write_text('Text file contents')
1619-
18
1620-
>>> p.read_text()
1621-
'Text file contents'
1622-
1623-
An existing file of the same name is overwritten. The optional parameters
1624-
have the same meaning as in :func:`open`.
1625-
1626-
.. versionadded:: 3.5
1627-
1628-
.. versionchanged:: 3.10
1629-
The *newline* parameter was added.
1630-
1631-
16321637
.. _pathlib-pattern-language:
16331638

16341639
Pattern language

0 commit comments

Comments
 (0)