summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorMiss Islington (bot) <31488909+miss-islington@users.noreply.github.com>2024-06-02 19:58:41 (GMT)
committerGitHub <noreply@github.com>2024-06-02 19:58:41 (GMT)
commitd33b0868d6aa6246a420fb7991bfd9cb907c951b (patch)
tree37d6101a7d875fa9f78bf6bd856c7536e96948b7 /Doc/library
parent590fd9ccd4443b991f7b01134fb8486cf5f5a79c (diff)
downloadcpython-d33b0868d6aa6246a420fb7991bfd9cb907c951b.zip
cpython-d33b0868d6aa6246a420fb7991bfd9cb907c951b.tar.gz
cpython-d33b0868d6aa6246a420fb7991bfd9cb907c951b.tar.bz2
[3.13] GH-119054: Add "Reading and writing files" section to pathlib docs (GH-119524) (#119954)
Add a dedicated subsection for `open()`, `read_text()`, `read_bytes()`, `write_text()` and `write_bytes()`. (cherry picked from commit bd6d4ed6454378e48dab06f50a9be0bae6baa3a2) Co-authored-by: Barney Gale <barney.gale@gmail.com>
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/pathlib.rst163
1 files changed, 84 insertions, 79 deletions
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 598d3df..93a908d 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1050,6 +1050,90 @@ 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, newline=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
+
+ .. versionchanged:: 3.13
+ The *newline* parameter was added.
+
+
+.. 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
^^^^^^^^^^^^^
@@ -1343,18 +1427,6 @@ 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(*, follow_symlinks=True)
Return the name of the user owning the file. :exc:`KeyError` is raised
@@ -1371,37 +1443,6 @@ example because the path doesn't exist).
The *follow_symlinks* parameter was added.
-.. 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, newline=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
-
- .. versionchanged:: 3.13
- The *newline* parameter was added.
-
.. method:: Path.readlink()
Return the path to which the symbolic link points (as returned by
@@ -1576,42 +1617,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.
-
-
.. _pathlib-pattern-language:
Pattern language