/Doc/library/tarfile.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 736 lines · 453 code · 283 blank · 0 comment · 0 complexity · 3f3addc6840bd5086e27da3eb344ad90 MD5 · raw file

  1. .. _tarfile-mod:
  2. :mod:`tarfile` --- Read and write tar archive files
  3. ===================================================
  4. .. module:: tarfile
  5. :synopsis: Read and write tar-format archive files.
  6. .. versionadded:: 2.3
  7. .. moduleauthor:: Lars Gust채bel <lars@gustaebel.de>
  8. .. sectionauthor:: Lars Gust채bel <lars@gustaebel.de>
  9. The :mod:`tarfile` module makes it possible to read and write tar
  10. archives, including those using gzip or bz2 compression.
  11. (:file:`.zip` files can be read and written using the :mod:`zipfile` module.)
  12. Some facts and figures:
  13. * reads and writes :mod:`gzip` and :mod:`bz2` compressed archives.
  14. * read/write support for the POSIX.1-1988 (ustar) format.
  15. * read/write support for the GNU tar format including *longname* and *longlink*
  16. extensions, read-only support for the *sparse* extension.
  17. * read/write support for the POSIX.1-2001 (pax) format.
  18. .. versionadded:: 2.6
  19. * handles directories, regular files, hardlinks, symbolic links, fifos,
  20. character devices and block devices and is able to acquire and restore file
  21. information like timestamp, access permissions and owner.
  22. .. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, \*\*kwargs)
  23. Return a :class:`TarFile` object for the pathname *name*. For detailed
  24. information on :class:`TarFile` objects and the keyword arguments that are
  25. allowed, see :ref:`tarfile-objects`.
  26. *mode* has to be a string of the form ``'filemode[:compression]'``, it defaults
  27. to ``'r'``. Here is a full list of mode combinations:
  28. +------------------+---------------------------------------------+
  29. | mode | action |
  30. +==================+=============================================+
  31. | ``'r' or 'r:*'`` | Open for reading with transparent |
  32. | | compression (recommended). |
  33. +------------------+---------------------------------------------+
  34. | ``'r:'`` | Open for reading exclusively without |
  35. | | compression. |
  36. +------------------+---------------------------------------------+
  37. | ``'r:gz'`` | Open for reading with gzip compression. |
  38. +------------------+---------------------------------------------+
  39. | ``'r:bz2'`` | Open for reading with bzip2 compression. |
  40. +------------------+---------------------------------------------+
  41. | ``'a' or 'a:'`` | Open for appending with no compression. The |
  42. | | file is created if it does not exist. |
  43. +------------------+---------------------------------------------+
  44. | ``'w' or 'w:'`` | Open for uncompressed writing. |
  45. +------------------+---------------------------------------------+
  46. | ``'w:gz'`` | Open for gzip compressed writing. |
  47. +------------------+---------------------------------------------+
  48. | ``'w:bz2'`` | Open for bzip2 compressed writing. |
  49. +------------------+---------------------------------------------+
  50. Note that ``'a:gz'`` or ``'a:bz2'`` is not possible. If *mode* is not suitable
  51. to open a certain (compressed) file for reading, :exc:`ReadError` is raised. Use
  52. *mode* ``'r'`` to avoid this. If a compression method is not supported,
  53. :exc:`CompressionError` is raised.
  54. If *fileobj* is specified, it is used as an alternative to a file object opened
  55. for *name*. It is supposed to be at position 0.
  56. For special purposes, there is a second format for *mode*:
  57. ``'filemode|[compression]'``. :func:`tarfile.open` will return a :class:`TarFile`
  58. object that processes its data as a stream of blocks. No random seeking will
  59. be done on the file. If given, *fileobj* may be any object that has a
  60. :meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize*
  61. specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant
  62. in combination with e.g. ``sys.stdin``, a socket file object or a tape
  63. device. However, such a :class:`TarFile` object is limited in that it does
  64. not allow to be accessed randomly, see :ref:`tar-examples`. The currently
  65. possible modes:
  66. +-------------+--------------------------------------------+
  67. | Mode | Action |
  68. +=============+============================================+
  69. | ``'r|*'`` | Open a *stream* of tar blocks for reading |
  70. | | with transparent compression. |
  71. +-------------+--------------------------------------------+
  72. | ``'r|'`` | Open a *stream* of uncompressed tar blocks |
  73. | | for reading. |
  74. +-------------+--------------------------------------------+
  75. | ``'r|gz'`` | Open a gzip compressed *stream* for |
  76. | | reading. |
  77. +-------------+--------------------------------------------+
  78. | ``'r|bz2'`` | Open a bzip2 compressed *stream* for |
  79. | | reading. |
  80. +-------------+--------------------------------------------+
  81. | ``'w|'`` | Open an uncompressed *stream* for writing. |
  82. +-------------+--------------------------------------------+
  83. | ``'w|gz'`` | Open an gzip compressed *stream* for |
  84. | | writing. |
  85. +-------------+--------------------------------------------+
  86. | ``'w|bz2'`` | Open an bzip2 compressed *stream* for |
  87. | | writing. |
  88. +-------------+--------------------------------------------+
  89. .. class:: TarFile
  90. Class for reading and writing tar archives. Do not use this class directly,
  91. better use :func:`tarfile.open` instead. See :ref:`tarfile-objects`.
  92. .. function:: is_tarfile(name)
  93. Return :const:`True` if *name* is a tar archive file, that the :mod:`tarfile`
  94. module can read.
  95. .. class:: TarFileCompat(filename, mode='r', compression=TAR_PLAIN)
  96. Class for limited access to tar archives with a :mod:`zipfile`\ -like interface.
  97. Please consult the documentation of the :mod:`zipfile` module for more details.
  98. *compression* must be one of the following constants:
  99. .. data:: TAR_PLAIN
  100. Constant for an uncompressed tar archive.
  101. .. data:: TAR_GZIPPED
  102. Constant for a :mod:`gzip` compressed tar archive.
  103. .. deprecated:: 2.6
  104. The :class:`TarFileCompat` class has been deprecated for removal in Python 3.0.
  105. .. exception:: TarError
  106. Base class for all :mod:`tarfile` exceptions.
  107. .. exception:: ReadError
  108. Is raised when a tar archive is opened, that either cannot be handled by the
  109. :mod:`tarfile` module or is somehow invalid.
  110. .. exception:: CompressionError
  111. Is raised when a compression method is not supported or when the data cannot be
  112. decoded properly.
  113. .. exception:: StreamError
  114. Is raised for the limitations that are typical for stream-like :class:`TarFile`
  115. objects.
  116. .. exception:: ExtractError
  117. Is raised for *non-fatal* errors when using :meth:`TarFile.extract`, but only if
  118. :attr:`TarFile.errorlevel`\ ``== 2``.
  119. .. exception:: HeaderError
  120. Is raised by :meth:`TarInfo.frombuf` if the buffer it gets is invalid.
  121. .. versionadded:: 2.6
  122. Each of the following constants defines a tar archive format that the
  123. :mod:`tarfile` module is able to create. See section :ref:`tar-formats` for
  124. details.
  125. .. data:: USTAR_FORMAT
  126. POSIX.1-1988 (ustar) format.
  127. .. data:: GNU_FORMAT
  128. GNU tar format.
  129. .. data:: PAX_FORMAT
  130. POSIX.1-2001 (pax) format.
  131. .. data:: DEFAULT_FORMAT
  132. The default format for creating archives. This is currently :const:`GNU_FORMAT`.
  133. The following variables are available on module level:
  134. .. data:: ENCODING
  135. The default character encoding i.e. the value from either
  136. :func:`sys.getfilesystemencoding` or :func:`sys.getdefaultencoding`.
  137. .. seealso::
  138. Module :mod:`zipfile`
  139. Documentation of the :mod:`zipfile` standard module.
  140. `GNU tar manual, Basic Tar Format <http://www.gnu.org/software/tar/manual/html_node/Standard.html>`_
  141. Documentation for tar archive files, including GNU tar extensions.
  142. .. _tarfile-objects:
  143. TarFile Objects
  144. ---------------
  145. The :class:`TarFile` object provides an interface to a tar archive. A tar
  146. archive is a sequence of blocks. An archive member (a stored file) is made up of
  147. a header block followed by data blocks. It is possible to store a file in a tar
  148. archive several times. Each archive member is represented by a :class:`TarInfo`
  149. object, see :ref:`tarinfo-objects` for details.
  150. .. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors=None, pax_headers=None, debug=0, errorlevel=0)
  151. All following arguments are optional and can be accessed as instance attributes
  152. as well.
  153. *name* is the pathname of the archive. It can be omitted if *fileobj* is given.
  154. In this case, the file object's :attr:`name` attribute is used if it exists.
  155. *mode* is either ``'r'`` to read from an existing archive, ``'a'`` to append
  156. data to an existing file or ``'w'`` to create a new file overwriting an existing
  157. one.
  158. If *fileobj* is given, it is used for reading or writing data. If it can be
  159. determined, *mode* is overridden by *fileobj*'s mode. *fileobj* will be used
  160. from position 0.
  161. .. note::
  162. *fileobj* is not closed, when :class:`TarFile` is closed.
  163. *format* controls the archive format. It must be one of the constants
  164. :const:`USTAR_FORMAT`, :const:`GNU_FORMAT` or :const:`PAX_FORMAT` that are
  165. defined at module level.
  166. .. versionadded:: 2.6
  167. The *tarinfo* argument can be used to replace the default :class:`TarInfo` class
  168. with a different one.
  169. .. versionadded:: 2.6
  170. If *dereference* is :const:`False`, add symbolic and hard links to the archive. If it
  171. is :const:`True`, add the content of the target files to the archive. This has no
  172. effect on systems that do not support symbolic links.
  173. If *ignore_zeros* is :const:`False`, treat an empty block as the end of the archive.
  174. If it is :const:`True`, skip empty (and invalid) blocks and try to get as many members
  175. as possible. This is only useful for reading concatenated or damaged archives.
  176. *debug* can be set from ``0`` (no debug messages) up to ``3`` (all debug
  177. messages). The messages are written to ``sys.stderr``.
  178. If *errorlevel* is ``0``, all errors are ignored when using :meth:`TarFile.extract`.
  179. Nevertheless, they appear as error messages in the debug output, when debugging
  180. is enabled. If ``1``, all *fatal* errors are raised as :exc:`OSError` or
  181. :exc:`IOError` exceptions. If ``2``, all *non-fatal* errors are raised as
  182. :exc:`TarError` exceptions as well.
  183. The *encoding* and *errors* arguments control the way strings are converted to
  184. unicode objects and vice versa. The default settings will work for most users.
  185. See section :ref:`tar-unicode` for in-depth information.
  186. .. versionadded:: 2.6
  187. The *pax_headers* argument is an optional dictionary of unicode strings which
  188. will be added as a pax global header if *format* is :const:`PAX_FORMAT`.
  189. .. versionadded:: 2.6
  190. .. method:: TarFile.open(...)
  191. Alternative constructor. The :func:`tarfile.open` function is actually a
  192. shortcut to this classmethod.
  193. .. method:: TarFile.getmember(name)
  194. Return a :class:`TarInfo` object for member *name*. If *name* can not be found
  195. in the archive, :exc:`KeyError` is raised.
  196. .. note::
  197. If a member occurs more than once in the archive, its last occurrence is assumed
  198. to be the most up-to-date version.
  199. .. method:: TarFile.getmembers()
  200. Return the members of the archive as a list of :class:`TarInfo` objects. The
  201. list has the same order as the members in the archive.
  202. .. method:: TarFile.getnames()
  203. Return the members as a list of their names. It has the same order as the list
  204. returned by :meth:`getmembers`.
  205. .. method:: TarFile.list(verbose=True)
  206. Print a table of contents to ``sys.stdout``. If *verbose* is :const:`False`,
  207. only the names of the members are printed. If it is :const:`True`, output
  208. similar to that of :program:`ls -l` is produced.
  209. .. method:: TarFile.next()
  210. Return the next member of the archive as a :class:`TarInfo` object, when
  211. :class:`TarFile` is opened for reading. Return :const:`None` if there is no more
  212. available.
  213. .. method:: TarFile.extractall(path=".", members=None)
  214. Extract all members from the archive to the current working directory or
  215. directory *path*. If optional *members* is given, it must be a subset of the
  216. list returned by :meth:`getmembers`. Directory information like owner,
  217. modification time and permissions are set after all members have been extracted.
  218. This is done to work around two problems: A directory's modification time is
  219. reset each time a file is created in it. And, if a directory's permissions do
  220. not allow writing, extracting files to it will fail.
  221. .. warning::
  222. Never extract archives from untrusted sources without prior inspection.
  223. It is possible that files are created outside of *path*, e.g. members
  224. that have absolute filenames starting with ``"/"`` or filenames with two
  225. dots ``".."``.
  226. .. versionadded:: 2.5
  227. .. method:: TarFile.extract(member, path="")
  228. Extract a member from the archive to the current working directory, using its
  229. full name. Its file information is extracted as accurately as possible. *member*
  230. may be a filename or a :class:`TarInfo` object. You can specify a different
  231. directory using *path*.
  232. .. note::
  233. The :meth:`extract` method does not take care of several extraction issues.
  234. In most cases you should consider using the :meth:`extractall` method.
  235. .. warning::
  236. See the warning for :meth:`extractall`.
  237. .. method:: TarFile.extractfile(member)
  238. Extract a member from the archive as a file object. *member* may be a filename
  239. or a :class:`TarInfo` object. If *member* is a regular file, a file-like object
  240. is returned. If *member* is a link, a file-like object is constructed from the
  241. link's target. If *member* is none of the above, :const:`None` is returned.
  242. .. note::
  243. The file-like object is read-only. It provides the methods
  244. :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`seek`, :meth:`tell`,
  245. and :meth:`close`, and also supports iteration over its lines.
  246. .. method:: TarFile.add(name, arcname=None, recursive=True, exclude=None)
  247. Add the file *name* to the archive. *name* may be any type of file (directory,
  248. fifo, symbolic link, etc.). If given, *arcname* specifies an alternative name
  249. for the file in the archive. Directories are added recursively by default. This
  250. can be avoided by setting *recursive* to :const:`False`. If *exclude* is given
  251. it must be a function that takes one filename argument and returns a boolean
  252. value. Depending on this value the respective file is either excluded
  253. (:const:`True`) or added (:const:`False`).
  254. .. versionchanged:: 2.6
  255. Added the *exclude* parameter.
  256. .. method:: TarFile.addfile(tarinfo, fileobj=None)
  257. Add the :class:`TarInfo` object *tarinfo* to the archive. If *fileobj* is given,
  258. ``tarinfo.size`` bytes are read from it and added to the archive. You can
  259. create :class:`TarInfo` objects using :meth:`gettarinfo`.
  260. .. note::
  261. On Windows platforms, *fileobj* should always be opened with mode ``'rb'`` to
  262. avoid irritation about the file size.
  263. .. method:: TarFile.gettarinfo(name=None, arcname=None, fileobj=None)
  264. Create a :class:`TarInfo` object for either the file *name* or the file object
  265. *fileobj* (using :func:`os.fstat` on its file descriptor). You can modify some
  266. of the :class:`TarInfo`'s attributes before you add it using :meth:`addfile`.
  267. If given, *arcname* specifies an alternative name for the file in the archive.
  268. .. method:: TarFile.close()
  269. Close the :class:`TarFile`. In write mode, two finishing zero blocks are
  270. appended to the archive.
  271. .. attribute:: TarFile.posix
  272. Setting this to :const:`True` is equivalent to setting the :attr:`format`
  273. attribute to :const:`USTAR_FORMAT`, :const:`False` is equivalent to
  274. :const:`GNU_FORMAT`.
  275. .. versionchanged:: 2.4
  276. *posix* defaults to :const:`False`.
  277. .. deprecated:: 2.6
  278. Use the :attr:`format` attribute instead.
  279. .. attribute:: TarFile.pax_headers
  280. A dictionary containing key-value pairs of pax global headers.
  281. .. versionadded:: 2.6
  282. .. _tarinfo-objects:
  283. TarInfo Objects
  284. ---------------
  285. A :class:`TarInfo` object represents one member in a :class:`TarFile`. Aside
  286. from storing all required attributes of a file (like file type, size, time,
  287. permissions, owner etc.), it provides some useful methods to determine its type.
  288. It does *not* contain the file's data itself.
  289. :class:`TarInfo` objects are returned by :class:`TarFile`'s methods
  290. :meth:`getmember`, :meth:`getmembers` and :meth:`gettarinfo`.
  291. .. class:: TarInfo(name="")
  292. Create a :class:`TarInfo` object.
  293. .. method:: TarInfo.frombuf(buf)
  294. Create and return a :class:`TarInfo` object from string buffer *buf*.
  295. .. versionadded:: 2.6
  296. Raises :exc:`HeaderError` if the buffer is invalid..
  297. .. method:: TarInfo.fromtarfile(tarfile)
  298. Read the next member from the :class:`TarFile` object *tarfile* and return it as
  299. a :class:`TarInfo` object.
  300. .. versionadded:: 2.6
  301. .. method:: TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='strict')
  302. Create a string buffer from a :class:`TarInfo` object. For information on the
  303. arguments see the constructor of the :class:`TarFile` class.
  304. .. versionchanged:: 2.6
  305. The arguments were added.
  306. A ``TarInfo`` object has the following public data attributes:
  307. .. attribute:: TarInfo.name
  308. Name of the archive member.
  309. .. attribute:: TarInfo.size
  310. Size in bytes.
  311. .. attribute:: TarInfo.mtime
  312. Time of last modification.
  313. .. attribute:: TarInfo.mode
  314. Permission bits.
  315. .. attribute:: TarInfo.type
  316. File type. *type* is usually one of these constants: :const:`REGTYPE`,
  317. :const:`AREGTYPE`, :const:`LNKTYPE`, :const:`SYMTYPE`, :const:`DIRTYPE`,
  318. :const:`FIFOTYPE`, :const:`CONTTYPE`, :const:`CHRTYPE`, :const:`BLKTYPE`,
  319. :const:`GNUTYPE_SPARSE`. To determine the type of a :class:`TarInfo` object
  320. more conveniently, use the ``is_*()`` methods below.
  321. .. attribute:: TarInfo.linkname
  322. Name of the target file name, which is only present in :class:`TarInfo` objects
  323. of type :const:`LNKTYPE` and :const:`SYMTYPE`.
  324. .. attribute:: TarInfo.uid
  325. User ID of the user who originally stored this member.
  326. .. attribute:: TarInfo.gid
  327. Group ID of the user who originally stored this member.
  328. .. attribute:: TarInfo.uname
  329. User name.
  330. .. attribute:: TarInfo.gname
  331. Group name.
  332. .. attribute:: TarInfo.pax_headers
  333. A dictionary containing key-value pairs of an associated pax extended header.
  334. .. versionadded:: 2.6
  335. A :class:`TarInfo` object also provides some convenient query methods:
  336. .. method:: TarInfo.isfile()
  337. Return :const:`True` if the :class:`Tarinfo` object is a regular file.
  338. .. method:: TarInfo.isreg()
  339. Same as :meth:`isfile`.
  340. .. method:: TarInfo.isdir()
  341. Return :const:`True` if it is a directory.
  342. .. method:: TarInfo.issym()
  343. Return :const:`True` if it is a symbolic link.
  344. .. method:: TarInfo.islnk()
  345. Return :const:`True` if it is a hard link.
  346. .. method:: TarInfo.ischr()
  347. Return :const:`True` if it is a character device.
  348. .. method:: TarInfo.isblk()
  349. Return :const:`True` if it is a block device.
  350. .. method:: TarInfo.isfifo()
  351. Return :const:`True` if it is a FIFO.
  352. .. method:: TarInfo.isdev()
  353. Return :const:`True` if it is one of character device, block device or FIFO.
  354. .. _tar-examples:
  355. Examples
  356. --------
  357. How to extract an entire tar archive to the current working directory::
  358. import tarfile
  359. tar = tarfile.open("sample.tar.gz")
  360. tar.extractall()
  361. tar.close()
  362. How to extract a subset of a tar archive with :meth:`TarFile.extractall` using
  363. a generator function instead of a list::
  364. import os
  365. import tarfile
  366. def py_files(members):
  367. for tarinfo in members:
  368. if os.path.splitext(tarinfo.name)[1] == ".py":
  369. yield tarinfo
  370. tar = tarfile.open("sample.tar.gz")
  371. tar.extractall(members=py_files(tar))
  372. tar.close()
  373. How to create an uncompressed tar archive from a list of filenames::
  374. import tarfile
  375. tar = tarfile.open("sample.tar", "w")
  376. for name in ["foo", "bar", "quux"]:
  377. tar.add(name)
  378. tar.close()
  379. How to read a gzip compressed tar archive and display some member information::
  380. import tarfile
  381. tar = tarfile.open("sample.tar.gz", "r:gz")
  382. for tarinfo in tar:
  383. print tarinfo.name, "is", tarinfo.size, "bytes in size and is",
  384. if tarinfo.isreg():
  385. print "a regular file."
  386. elif tarinfo.isdir():
  387. print "a directory."
  388. else:
  389. print "something else."
  390. tar.close()
  391. .. _tar-formats:
  392. Supported tar formats
  393. ---------------------
  394. There are three tar formats that can be created with the :mod:`tarfile` module:
  395. * The POSIX.1-1988 ustar format (:const:`USTAR_FORMAT`). It supports filenames
  396. up to a length of at best 256 characters and linknames up to 100 characters. The
  397. maximum file size is 8 gigabytes. This is an old and limited but widely
  398. supported format.
  399. * The GNU tar format (:const:`GNU_FORMAT`). It supports long filenames and
  400. linknames, files bigger than 8 gigabytes and sparse files. It is the de facto
  401. standard on GNU/Linux systems. :mod:`tarfile` fully supports the GNU tar
  402. extensions for long names, sparse file support is read-only.
  403. * The POSIX.1-2001 pax format (:const:`PAX_FORMAT`). It is the most flexible
  404. format with virtually no limits. It supports long filenames and linknames, large
  405. files and stores pathnames in a portable way. However, not all tar
  406. implementations today are able to handle pax archives properly.
  407. The *pax* format is an extension to the existing *ustar* format. It uses extra
  408. headers for information that cannot be stored otherwise. There are two flavours
  409. of pax headers: Extended headers only affect the subsequent file header, global
  410. headers are valid for the complete archive and affect all following files. All
  411. the data in a pax header is encoded in *UTF-8* for portability reasons.
  412. There are some more variants of the tar format which can be read, but not
  413. created:
  414. * The ancient V7 format. This is the first tar format from Unix Seventh Edition,
  415. storing only regular files and directories. Names must not be longer than 100
  416. characters, there is no user/group name information. Some archives have
  417. miscalculated header checksums in case of fields with non-ASCII characters.
  418. * The SunOS tar extended format. This format is a variant of the POSIX.1-2001
  419. pax format, but is not compatible.
  420. .. _tar-unicode:
  421. Unicode issues
  422. --------------
  423. The tar format was originally conceived to make backups on tape drives with the
  424. main focus on preserving file system information. Nowadays tar archives are
  425. commonly used for file distribution and exchanging archives over networks. One
  426. problem of the original format (that all other formats are merely variants of)
  427. is that there is no concept of supporting different character encodings. For
  428. example, an ordinary tar archive created on a *UTF-8* system cannot be read
  429. correctly on a *Latin-1* system if it contains non-ASCII characters. Names (i.e.
  430. filenames, linknames, user/group names) containing these characters will appear
  431. damaged. Unfortunately, there is no way to autodetect the encoding of an
  432. archive.
  433. The pax format was designed to solve this problem. It stores non-ASCII names
  434. using the universal character encoding *UTF-8*. When a pax archive is read,
  435. these *UTF-8* names are converted to the encoding of the local file system.
  436. The details of unicode conversion are controlled by the *encoding* and *errors*
  437. keyword arguments of the :class:`TarFile` class.
  438. The default value for *encoding* is the local character encoding. It is deduced
  439. from :func:`sys.getfilesystemencoding` and :func:`sys.getdefaultencoding`. In
  440. read mode, *encoding* is used exclusively to convert unicode names from a pax
  441. archive to strings in the local character encoding. In write mode, the use of
  442. *encoding* depends on the chosen archive format. In case of :const:`PAX_FORMAT`,
  443. input names that contain non-ASCII characters need to be decoded before being
  444. stored as *UTF-8* strings. The other formats do not make use of *encoding*
  445. unless unicode objects are used as input names. These are converted to 8-bit
  446. character strings before they are added to the archive.
  447. The *errors* argument defines how characters are treated that cannot be
  448. converted to or from *encoding*. Possible values are listed in section
  449. :ref:`codec-base-classes`. In read mode, there is an additional scheme
  450. ``'utf-8'`` which means that bad characters are replaced by their *UTF-8*
  451. representation. This is the default scheme. In write mode the default value for
  452. *errors* is ``'strict'`` to ensure that name information is not altered
  453. unnoticed.