mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-09 03:19:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[3.12] GH-119054: Add "Reading and writing files" section to pathlib docs (GH-119524) (#119955)

Browse source 
Add a dedicated subsection for `open()`, `read_text()`, `read_bytes()`,
`write_text()` and `write_bytes()`.

(cherry picked from commit bd6d4ed645)
This commit is contained in:
Barney Gale 2024-06-02 21:14:29 +01:00 • committed by GitHub
parent 85020647c2
commit 059be67b51
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 81 additions and 76 deletions
Download patch file Download diff file Expand all files Collapse all files

157
Doc/library/pathlib.rst
View file

@ -959,6 +959,87 @@ Querying file type and status
.. versionadded:: 3.5
Reading and writing files
^^^^^^^^^^^^^^^^^^^^^^^^^
.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)
Open the file pointed to by the path, like the built-in :func:`open`
function does::
>>> p = Path('setup.py')
>>> with p.open() as f:
... f.readline()
...
'#!/usr/bin/env python3\n'
.. method:: Path.read_text(encoding=None, errors=None)
Return the decoded contents of the pointed-to file as a string::
>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'
The file is opened and then closed. The optional parameters have the same
meaning as in :func:`open`.
.. versionadded:: 3.5
.. method:: Path.read_bytes()
Return the binary contents of the pointed-to file as a bytes object::
>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'
.. versionadded:: 3.5
.. method:: Path.write_text(data, encoding=None, errors=None, newline=None)
Open the file pointed to in text mode, write *data* to it, and close the
file::
>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'
An existing file of the same name is overwritten. The optional parameters
have the same meaning as in :func:`open`.
.. versionadded:: 3.5
.. versionchanged:: 3.10
The *newline* parameter was added.
.. method:: Path.write_bytes(data)
Open the file pointed to in bytes mode, write *data* to it, and close the
file::
>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'
An existing file of the same name is overwritten.
.. versionadded:: 3.5
Other methods
^^^^^^^^^^^^^
@ -1222,53 +1303,12 @@ example because the path doesn't exist).
The *exist_ok* parameter was added.
.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)
Open the file pointed to by the path, like the built-in :func:`open`
function does::
>>> p = Path('setup.py')
>>> with p.open() as f:
... f.readline()
...
'#!/usr/bin/env python3\n'
.. method:: Path.owner()
Return the name of the user owning the file. :exc:`KeyError` is raised
if the file's uid isn't found in the system database.
.. method:: Path.read_bytes()
Return the binary contents of the pointed-to file as a bytes object::
>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'
.. versionadded:: 3.5
.. method:: Path.read_text(encoding=None, errors=None)
Return the decoded contents of the pointed-to file as a string::
>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'
The file is opened and then closed. The optional parameters have the same
meaning as in :func:`open`.
.. versionadded:: 3.5
.. method:: Path.readlink()
Return the path to which the symbolic link points (as returned by
@ -1454,41 +1494,6 @@ example because the path doesn't exist).
The *missing_ok* parameter was added.
.. method:: Path.write_bytes(data)
Open the file pointed to in bytes mode, write *data* to it, and close the
file::
>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'
An existing file of the same name is overwritten.
.. versionadded:: 3.5
.. method:: Path.write_text(data, encoding=None, errors=None, newline=None)
Open the file pointed to in text mode, write *data* to it, and close the
file::
>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'
An existing file of the same name is overwritten. The optional parameters
have the same meaning as in :func:`open`.
.. versionadded:: 3.5
.. versionchanged:: 3.10
The *newline* parameter was added.
Correspondence to tools in the :mod:`os` module
-----------------------------------------------