From 67a07097d5e8383741b4853c8effff5bc174fa93 Mon Sep 17 00:00:00 2001
From: Affan Shaikhsurab <51104750+AffanShaikhsurab@users.noreply.github.com>
Date: Tue, 25 Feb 2025 16:18:48 +0530
Subject: [PATCH] gh-123726: Document caveats of zipfile.Path around name
 sanitization

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.
---
 Doc/library/zipfile.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index afe1cd5c75fcbb..0e6439f75334e9 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -554,6 +554,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: