[Python-checkins] bpo-36260: Add pitfalls to zipfile module documentation (#13378)

[Jason R. Coombs]

https://github.com/python/cpython/commit/3ba51d587f6897a45301ce9126300c14fcd4eba2
commit: 3ba51d587f6897a45301ce9126300c14fcd4eba2
branch: master
author: JunWei Song <sungboss2004 at gmail.com>
committer: Jason R. Coombs <jaraco at jaraco.com>
date: 2019-09-11T16:04:11+01:00
summary:

bpo-36260: Add pitfalls to zipfile module documentation (#13378)

* bpo-36260: Add pitfalls to zipfile module documentation

We saw vulnerability warning description (including zip bomb) in Doc/library/xml.rst file.
This gave us the idea of documentation improvement. 

So, we moved a little bit forward :P
And the doc patch can be found (pr).

* fix trailing whitespace

* 📜🤖 Added by blurb_it.

* Reformat text for consistency.

files:
A Misc/NEWS.d/next/Documentation/2019-06-04-09-29-00.bpo-36260.WrGuc-.rst
M Doc/library/zipfile.rst

diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 9db9697105d6..18d2e9a60a7b 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -816,5 +816,45 @@ Command-line options
 
    Test whether the zipfile is valid or not.
 
+Decompression pitfalls
+----------------------
+
+The extraction in zipfile module might fail due to some pitfalls listed below.
+
+From file itself
+~~~~~~~~~~~~~~~~
+
+Decompression may fail due to incorrect password / CRC checksum / ZIP format or
+unsupported compression method / decryption.
+
+File System limitations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Exceeding limitations on different file systems can cause decompression failed.
+Such as allowable characters in the directory entries, length of the file name,
+length of the pathname, size of a single file, and number of files, etc.
+
+Resources limitations
+~~~~~~~~~~~~~~~~~~~~~
+
+The lack of memory or disk volume would lead to decompression
+failed. For example, decompression bombs (aka `ZIP bomb`_)
+apply to zipfile library that can cause disk volume exhaustion.
+
+Interruption
+~~~~~~~~~~~~
+
+Interruption during the decompression, such as pressing control-C or killing the
+decompression process may result in incomplete decompression of the archive.
+
+Default behaviors of extraction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Not knowing the default extraction behaviors
+can cause unexpected decompression results.
+For example, when extracting the same archive twice,
+it overwrites files without asking.
+
 
+.. _ZIP bomb: https://en.wikipedia.org/wiki/Zip_bomb
 .. _PKZIP Application Note: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
diff --git a/Misc/NEWS.d/next/Documentation/2019-06-04-09-29-00.bpo-36260.WrGuc-.rst b/Misc/NEWS.d/next/Documentation/2019-06-04-09-29-00.bpo-36260.WrGuc-.rst
new file mode 100644
index 000000000000..9276516a8823
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-06-04-09-29-00.bpo-36260.WrGuc-.rst
@@ -0,0 +1 @@
+Add decompression pitfalls to zipfile module documentation.
\ No newline at end of file