Ignore:
Timestamp:
Mar 19, 2014, 11:31:01 PM (11 years ago)
Author:
dmik
Message:

python: Merge vendor 2.7.6 to trunk.

Location:
python/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • python/trunk

  • python/trunk/Doc/library/zipfile.rst

    r2 r391  
    1 
    21:mod:`zipfile` --- Work with ZIP archives
    32=========================================
    … …  
    98
    109.. versionadded:: 1.6
     10
     11**Source code:** :source:`Lib/zipfile.py`
     12
     13--------------
    1114
    1215The ZIP file format is a common archive and compression standard. This module
    … …  
    1619<http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_.
    1720
    18 This module does not currently handle multi-disk ZIP files, or ZIP files
    19 which have appended comments (although it correctly handles comments
    20 added to individual archive members---for which see the :ref:`zipinfo-objects`
    21 documentation). It can handle ZIP files that use the ZIP64 extensions
     21This module does not currently handle multi-disk ZIP files.
     22It can handle ZIP files that use the ZIP64 extensions
    2223(that is ZIP files that are more than 4 GByte in size).  It supports
    2324decryption of encrypted files in ZIP archives, but it currently cannot
    2425create an encrypted file.  Decryption is extremely slow as it is
    25 implemented in native python rather than C.
    26 
    27 For other archive formats, see the :mod:`bz2`, :mod:`gzip`, and
    28 :mod:`tarfile` modules.
     26implemented in native Python rather than C.
    2927
    3028The module defines the following items:
    … …  
    4240
    4341.. class:: ZipFile
     42   :noindex:
    4443
    4544   The class for reading and writing ZIP files.  See section
    … …  
    5554
    5655   Class used to represent information about a member of an archive. Instances
    57    of this class are returned by the :meth:`getinfo` and :meth:`infolist`
     56   of this class are returned by the :meth:`.getinfo` and :meth:`.infolist`
    5857   methods of :class:`ZipFile` objects.  Most users of the :mod:`zipfile` module
    5958   will not need to create these, but only use those created by this
    … …  
    6766
    6867   Returns ``True`` if *filename* is a valid ZIP file based on its magic number,
    69    otherwise returns ``False``.  This module does not currently handle ZIP files
    70    which have appended comments.
    71 
     68   otherwise returns ``False``.  *filename* may be a file or file-like object too.
     69
     70   .. versionchanged:: 2.7
     71      Support for file and file-like objects.
    7272
    7373.. data:: ZIP_STORED
    … …  
    7979
    8080   The numeric constant for the usual ZIP compression method.  This requires the
    81    zlib module.  No other compression methods are currently supported.
     81   :mod:`zlib` module.  No other compression methods are currently supported.
    8282
    8383
    … …  
    104104   file-like object.  The *mode* parameter should be ``'r'`` to read an existing
    105105   file, ``'w'`` to truncate and write a new file, or ``'a'`` to append to an
    106    existing file.  If *mode* is ``'a'`` and *file* refers to an existing ZIP file,
    107    then additional files are added to it.  If *file* does not refer to a ZIP file,
    108    then a new ZIP archive is appended to the file.  This is meant for adding a ZIP
    109    archive to another file, such as :file:`python.exe`.  Using ::
    110 
    111       cat myzip.zip >> python.exe
    112 
    113    also works, and at least :program:`WinZip` can read such files. If *mode* is
    114    ``a`` and the file does not exist at all, it is created. *compression* is the
    115    ZIP compression method to use when writing the archive, and should be
    116    :const:`ZIP_STORED` or :const:`ZIP_DEFLATED`; unrecognized values will cause
    117    :exc:`RuntimeError` to be raised.  If :const:`ZIP_DEFLATED` is specified but the
    118    :mod:`zlib` module is not available, :exc:`RuntimeError` is also raised.  The
    119    default is :const:`ZIP_STORED`.  If *allowZip64* is ``True`` zipfile will create
    120    ZIP files that use the ZIP64 extensions when the zipfile is larger than 2 GB. If
    121    it is  false (the default) :mod:`zipfile` will raise an exception when the ZIP
    122    file would require ZIP64 extensions. ZIP64 extensions are disabled by default
    123    because the default :program:`zip` and :program:`unzip` commands on Unix (the
    124    InfoZIP utilities) don't support these extensions.
     106   existing file.  If *mode* is ``'a'`` and *file* refers to an existing ZIP
     107   file, then additional files are added to it.  If *file* does not refer to a
     108   ZIP file, then a new ZIP archive is appended to the file.  This is meant for
     109   adding a ZIP archive to another file (such as :file:`python.exe`).
    125110
    126111   .. versionchanged:: 2.6
    127       If the file does not exist, it is created if the mode is 'a'.
     112      If *mode* is ``a`` and the file does not exist at all, it is created.
     113
     114   *compression* is the ZIP compression method to use when writing the archive,
     115   and should be :const:`ZIP_STORED` or :const:`ZIP_DEFLATED`; unrecognized
     116   values will cause :exc:`RuntimeError` to be raised.  If :const:`ZIP_DEFLATED`
     117   is specified but the :mod:`zlib` module is not available, :exc:`RuntimeError`
     118   is also raised. The default is :const:`ZIP_STORED`.  If *allowZip64* is
     119   ``True`` zipfile will create ZIP files that use the ZIP64 extensions when
     120   the zipfile is larger than 2 GB. If it is  false (the default) :mod:`zipfile`
     121   will raise an exception when the ZIP file would require ZIP64 extensions.
     122   ZIP64 extensions are disabled by default because the default :program:`zip`
     123   and :program:`unzip` commands on Unix (the InfoZIP utilities) don't support
     124   these extensions.
     125
     126   .. versionchanged:: 2.7.1
     127      If the file is created with mode ``'a'`` or ``'w'`` and then
     128      :meth:`closed <close>` without adding any files to the archive, the appropriate
     129      ZIP structures for an empty archive will be written to the file.
     130
     131   ZipFile is also a context manager and therefore supports the
     132   :keyword:`with` statement.  In the example, *myzip* is closed after the
     133   :keyword:`with` statement's suite is finished---even if an exception occurs::
     134
     135      with ZipFile('spam.zip', 'w') as myzip:
     136          myzip.write('eggs.txt')
     137
     138   .. versionadded:: 2.7
     139      Added the ability to use :class:`ZipFile` as a context manager.
    128140
    129141
    … …  
    152164   Return a list of archive members by name.
    153165
     166   .. index::
     167      single: universal newlines; zipfile.ZipFile.open method
     168
    154169
    155170.. method:: ZipFile.open(name[, mode[, pwd]])
    … …  
    157172   Extract a member from the archive as a file-like object (ZipExtFile). *name* is
    158173   the name of the file in the archive, or a :class:`ZipInfo` object. The *mode*
    159    parameter, if included, must be one of the following: ``'r'`` (the  default),
    160    ``'U'``, or ``'rU'``. Choosing ``'U'`` or  ``'rU'`` will enable universal newline
     174   parameter, if included, must be one of the following: ``'r'`` (the default),
     175   ``'U'``, or ``'rU'``. Choosing ``'U'`` or  ``'rU'`` will enable
     176   :term:`universal newline <universal newlines>`
    161177   support in the read-only object. *pwd* is the password used for encrypted files.
    162    Calling  :meth:`open` on a closed ZipFile will raise a  :exc:`RuntimeError`.
     178   Calling  :meth:`.open` on a closed ZipFile will raise a  :exc:`RuntimeError`.
    163179
    164180   .. note::
    165181
    166182      The file-like object is read-only and provides the following methods:
    167       :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`__iter__`,
    168       :meth:`next`.
     183      :meth:`~file.read`, :meth:`~file.readline`,
     184      :meth:`~file.readlines`, :meth:`__iter__`,
     185      :meth:`~object.next`.
    169186
    170187   .. note::
    … …  
    181198   .. note::
    182199
    183       The :meth:`open`, :meth:`read` and :meth:`extract` methods can take a filename
     200      The :meth:`.open`, :meth:`read` and :meth:`extract` methods can take a filename
    184201      or a :class:`ZipInfo` object.  You will appreciate this when trying to read a
    185202      ZIP file that contains members with duplicate names.
    … …  
    198215   .. versionadded:: 2.6
    199216
     217   .. note::
     218
     219      If a member filename is an absolute path, a drive/UNC sharepoint and
     220      leading (back)slashes will be stripped, e.g.: ``///foo/bar`` becomes
     221      ``foo/bar`` on Unix, and ``C:\foo\bar`` becomes ``foo\bar`` on Windows.
     222      And all ``".."`` components in a member filename will be removed, e.g.:
     223      ``../../foo../../ba..r`` becomes ``foo../ba..r``.  On Windows illegal
     224      characters (``:``, ``<``, ``>``, ``|``, ``"``, ``?``, and ``*``)
     225      replaced by underscore (``_``).
     226
    200227
    201228.. method:: ZipFile.extractall([path[, members[, pwd]]])
    … …  
    212239      that have absolute filenames starting with ``"/"`` or filenames with two
    213240      dots ``".."``.
     241
     242   .. versionchanged:: 2.7.4
     243      The zipfile module attempts to prevent that.  See :meth:`extract` note.
    214244
    215245   .. versionadded:: 2.6
    … …  
    276306
    277307
    278 .. method:: ZipFile.writestr(zinfo_or_arcname, bytes)
     308.. method:: ZipFile.writestr(zinfo_or_arcname, bytes[, compress_type])
    279309
    280310   Write the string *bytes* to the archive; *zinfo_or_arcname* is either the file
    … …  
    286316   :meth:`writestr` on a closed ZipFile will raise a :exc:`RuntimeError`.
    287317
    288    .. note::
    289 
    290       When passing a :class:`ZipInfo` instance as the *zinfo_or_acrname* parameter,
     318   If given, *compress_type* overrides the value given for the *compression*
     319   parameter to the constructor for the new entry, or in the *zinfo_or_arcname*
     320   (if that is a :class:`ZipInfo` instance).
     321
     322   .. note::
     323
     324      When passing a :class:`ZipInfo` instance as the *zinfo_or_arcname* parameter,
    291325      the compression method used will be that specified in the *compress_type*
    292326      member of the given :class:`ZipInfo` instance.  By default, the
    293327      :class:`ZipInfo` constructor sets this member to :const:`ZIP_STORED`.
    294328
     329   .. versionchanged:: 2.7
     330      The *compress_type* argument.
     331
    295332The following data attributes are also available:
    296333
    … …  
    307344   :class:`ZipFile` instance created with mode 'a' or 'w', this should be a
    308345   string no longer than 65535 bytes.  Comments longer than this will be
    309    truncated in the written archive when :meth:`ZipFile.close` is called.
     346   truncated in the written archive when :meth:`.close` is called.
    310347
    311348.. _pyzipfile-objects:
    … …  
    347384---------------
    348385
    349 Instances of the :class:`ZipInfo` class are returned by the :meth:`getinfo` and
    350 :meth:`infolist` methods of :class:`ZipFile` objects.  Each object stores
     386Instances of the :class:`ZipInfo` class are returned by the :meth:`.getinfo` and
     387:meth:`.infolist` methods of :class:`ZipFile` objects.  Each object stores
    351388information about a single member of the ZIP archive.
    352389
    … …  
    367404   | Index | Value                    |
    368405   +=======+==========================+
    369    | ``0`` | Year                     |
     406   | ``0`` | Year (>= 1980)           |
    370407   +-------+--------------------------+
    371408   | ``1`` | Month (one-based)        |
    … …  
    379416   | ``5`` | Seconds (zero-based)     |
    380417   +-------+--------------------------+
     418
     419   .. note::
     420
     421      The ZIP file format does not support timestamps before 1980.
    381422
    382423
Note: See TracChangeset for help on using the changeset viewer.