[3.12] gh-123726: Document caveats of zipfile.Path around name sanitization (GH-13053...

gh-123726: Document caveats of zipfile.Path around name sanitization (GH-130537)

Add a note to the `zipfile.Path` class documentation clarifying that it does not sanitize filenames. This emphasizes the caller's responsibility to validate or sanitize inputs, especially when handling untrusted ZIP archives, to prevent path traversal vulnerabilities. The note also references the `extract` and `extractall` methods for comparison and suggests using `os.path.abspath` and `os.path.commonpath` for safe filename resolution.
(cherry picked from commit a3990df6121880e8c67824a101bb1316de232898)

Co-authored-by: Affan Shaikhsurab <51104750+AffanShaikhsurab@users.noreply.github.com>

diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 3fdbd97b8beb938a2a63ed3c24d0a59c98581cf8..9394746f6af2a95a4d32d04afaf5653249535cd4 100644 (file)
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -528,6 +528,14 @@ Path Objects
    e.g. 'dir/file.txt', 'dir/', or ''. Defaults to the empty string,
    indicating the root.
 
+   .. note::
+      The :class:`Path` class does not sanitize filenames within the ZIP archive. Unlike
+      the :meth:`ZipFile.extract` and :meth:`ZipFile.extractall` methods, it is the
+      caller's responsibility to validate or sanitize filenames to prevent path traversal
+      vulnerabilities (e.g., filenames containing ".." or absolute paths). When handling
+      untrusted archives, consider resolving filenames using :func:`os.path.abspath`
+      and checking against the target directory with :func:`os.path.commonpath`.
+
 Path objects expose the following features of :mod:`pathlib.Path`
 objects: