Skip to content

Commit 059be67

Browse files
authored
[3.12] GH-119054: Add "Reading and writing files" section to pathlib docs (GH-119524) (#119955)
Add a dedicated subsection for `open()`, `read_text()`, `read_bytes()`, `write_text()` and `write_bytes()`. (cherry picked from commit bd6d4ed)
1 parent 8502064 commit 059be67

File tree

1 file changed

+81
-76
lines changed

1 file changed

+81
-76
lines changed

Doc/library/pathlib.rst

Lines changed: 81 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -959,6 +959,87 @@ Querying file type and status
959959
.. versionadded:: 3.5
960960

961961

962+
Reading and writing files
963+
^^^^^^^^^^^^^^^^^^^^^^^^^
964+
965+
966+
.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)
967+
968+
Open the file pointed to by the path, like the built-in :func:`open`
969+
function does::
970+
971+
>>> p = Path('setup.py')
972+
>>> with p.open() as f:
973+
... f.readline()
974+
...
975+
'#!/usr/bin/env python3\n'
976+
977+
978+
.. method:: Path.read_text(encoding=None, errors=None)
979+
980+
Return the decoded contents of the pointed-to file as a string::
981+
982+
>>> p = Path('my_text_file')
983+
>>> p.write_text('Text file contents')
984+
18
985+
>>> p.read_text()
986+
'Text file contents'
987+
988+
The file is opened and then closed. The optional parameters have the same
989+
meaning as in :func:`open`.
990+
991+
.. versionadded:: 3.5
992+
993+
994+
.. method:: Path.read_bytes()
995+
996+
Return the binary contents of the pointed-to file as a bytes object::
997+
998+
>>> p = Path('my_binary_file')
999+
>>> p.write_bytes(b'Binary file contents')
1000+
20
1001+
>>> p.read_bytes()
1002+
b'Binary file contents'
1003+
1004+
.. versionadded:: 3.5
1005+
1006+
1007+
.. method:: Path.write_text(data, encoding=None, errors=None, newline=None)
1008+
1009+
Open the file pointed to in text mode, write *data* to it, and close the
1010+
file::
1011+
1012+
>>> p = Path('my_text_file')
1013+
>>> p.write_text('Text file contents')
1014+
18
1015+
>>> p.read_text()
1016+
'Text file contents'
1017+
1018+
An existing file of the same name is overwritten. The optional parameters
1019+
have the same meaning as in :func:`open`.
1020+
1021+
.. versionadded:: 3.5
1022+
1023+
.. versionchanged:: 3.10
1024+
The *newline* parameter was added.
1025+
1026+
1027+
.. method:: Path.write_bytes(data)
1028+
1029+
Open the file pointed to in bytes mode, write *data* to it, and close the
1030+
file::
1031+
1032+
>>> p = Path('my_binary_file')
1033+
>>> p.write_bytes(b'Binary file contents')
1034+
20
1035+
>>> p.read_bytes()
1036+
b'Binary file contents'
1037+
1038+
An existing file of the same name is overwritten.
1039+
1040+
.. versionadded:: 3.5
1041+
1042+
9621043
Other methods
9631044
^^^^^^^^^^^^^
9641045

@@ -1222,53 +1303,12 @@ example because the path doesn't exist).
12221303
The *exist_ok* parameter was added.
12231304

12241305

1225-
.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)
1226-
1227-
Open the file pointed to by the path, like the built-in :func:`open`
1228-
function does::
1229-
1230-
>>> p = Path('setup.py')
1231-
>>> with p.open() as f:
1232-
... f.readline()
1233-
...
1234-
'#!/usr/bin/env python3\n'
1235-
1236-
12371306
.. method:: Path.owner()
12381307

12391308
Return the name of the user owning the file. :exc:`KeyError` is raised
12401309
if the file's uid isn't found in the system database.
12411310

12421311

1243-
.. method:: Path.read_bytes()
1244-
1245-
Return the binary contents of the pointed-to file as a bytes object::
1246-
1247-
>>> p = Path('my_binary_file')
1248-
>>> p.write_bytes(b'Binary file contents')
1249-
20
1250-
>>> p.read_bytes()
1251-
b'Binary file contents'
1252-
1253-
.. versionadded:: 3.5
1254-
1255-
1256-
.. method:: Path.read_text(encoding=None, errors=None)
1257-
1258-
Return the decoded contents of the pointed-to file as a string::
1259-
1260-
>>> p = Path('my_text_file')
1261-
>>> p.write_text('Text file contents')
1262-
18
1263-
>>> p.read_text()
1264-
'Text file contents'
1265-
1266-
The file is opened and then closed. The optional parameters have the same
1267-
meaning as in :func:`open`.
1268-
1269-
.. versionadded:: 3.5
1270-
1271-
12721312
.. method:: Path.readlink()
12731313

12741314
Return the path to which the symbolic link points (as returned by
@@ -1454,41 +1494,6 @@ example because the path doesn't exist).
14541494
The *missing_ok* parameter was added.
14551495

14561496

1457-
.. method:: Path.write_bytes(data)
1458-
1459-
Open the file pointed to in bytes mode, write *data* to it, and close the
1460-
file::
1461-
1462-
>>> p = Path('my_binary_file')
1463-
>>> p.write_bytes(b'Binary file contents')
1464-
20
1465-
>>> p.read_bytes()
1466-
b'Binary file contents'
1467-
1468-
An existing file of the same name is overwritten.
1469-
1470-
.. versionadded:: 3.5
1471-
1472-
1473-
.. method:: Path.write_text(data, encoding=None, errors=None, newline=None)
1474-
1475-
Open the file pointed to in text mode, write *data* to it, and close the
1476-
file::
1477-
1478-
>>> p = Path('my_text_file')
1479-
>>> p.write_text('Text file contents')
1480-
18
1481-
>>> p.read_text()
1482-
'Text file contents'
1483-
1484-
An existing file of the same name is overwritten. The optional parameters
1485-
have the same meaning as in :func:`open`.
1486-
1487-
.. versionadded:: 3.5
1488-
1489-
.. versionchanged:: 3.10
1490-
The *newline* parameter was added.
1491-
14921497
Correspondence to tools in the :mod:`os` module
14931498
-----------------------------------------------
14941499

0 commit comments

Comments
 (0)