From 5c5a3937ad993eb4caf49a54af42187893c0d3b7 Mon Sep 17 00:00:00 2001 From: Barney Gale Date: Sun, 2 Jun 2024 20:39:19 +0100 Subject: [PATCH 1/4] 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()`. (cherry picked from commit bd6d4ed6454378e48dab06f50a9be0bae6baa3a2) --- Doc/library/pathlib.rst | 158 +++++++++++++++++++++------------------- 1 file changed, 82 insertions(+), 76 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 0115ea8b3eb878..2a09d9dce9f9e8 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -959,6 +959,88 @@ 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 +1304,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 +1495,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 ----------------------------------------------- From b8d0090ac20c267e2f2a4412398f219d07e20cf9 Mon Sep 17 00:00:00 2001 From: barneygale Date: Sun, 2 Jun 2024 20:42:50 +0100 Subject: [PATCH 2/4] [3.12] GH-119054: Add "Reading and writing files" section to pathlib docs (GH-119524) 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 From ac5980a26cbcd3daa037de14038214e7276b5fac Mon Sep 17 00:00:00 2001 From: Barney Gale Date: Sun, 2 Jun 2024 20:44:19 +0100 Subject: [PATCH 3/4] Update Doc/library/pathlib.rst --- Doc/library/pathlib.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 2a09d9dce9f9e8..19d0e133128659 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -974,8 +974,6 @@ Reading and writing files ... '#!/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:: From 1d81d69382e68b9e2a02c47d24ea47b18c97495c Mon Sep 17 00:00:00 2001 From: Barney Gale Date: Sun, 2 Jun 2024 20:45:06 +0100 Subject: [PATCH 4/4] Update Doc/library/pathlib.rst --- Doc/library/pathlib.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 19d0e133128659..d4b0e0720849a4 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -974,6 +974,7 @@ Reading and writing files ... '#!/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::