doc/news.rst

   1
   2 rarfile history
   3 ===============
   4
   5 .. py:currentmodule:: rarfile
   6
   7 Version 4.1 (xxxx-xx-xx)
   8 ------------------------
   9
  10 Features:
  11
  12 * Support 7zip/p7zip as decompression backend.
  13   [`#71 <https://github.com/markokr/rarfile/issues/71>`_]
  14 * RAR5: check password before trying to read file (chigusa)
  15   [`#79 <https://github.com/markokr/rarfile/pull/79>`_]
  16
  17 New APIs:
  18
  19 * Make get_rar_version a public function (Safihre)
  20   [`#63 <https://github.com/markokr/rarfile/pull/63>`_]
  21 * New option: ``part_only`` for :class:`RarFile`,
  22   to read only single file and allow it to be middle-part
  23   of multi-volume archive.
  24 * Add :meth:`RarFile.printdir`, use it in dumprar.  Needed to examine
  25   FILE_COPY or HARD_LINK entries that do not contain data.
  26
  27 Fixes:
  28
  29 * Use OS separator to access filename.  Should fix
  30   subdirectory entry access on Windows.
  31   [`#96 <https://github.com/markokr/rarfile/pull/96>`_]
  32 * DirectReader: check seek position on each read.
  33   Fixes read reading from multiple entries in parallel
  34   on RarFile backed by file object.
  35   [`#81 <https://github.com/markokr/rarfile/pull/81>`_]
  36 * DirectReader: properly disable CRC check when seeking.
  37   [`#73 <https://github.com/markokr/rarfile/issues/73>`_]
  38 * Reset _hdrenc_main before processing a new volume.
  39   Fixes CRC checks on multi-volume reads.
  40   [`#80 <https://github.com/markokr/rarfile/pull/80>`_]
  41 * Adapt to Python 3.10 argparse (MeggyCal)
  42   [`#85 <https://github.com/markokr/rarfile/pull/85>`_]
  43 * SFX: Handle volume numbering special cases better.
  44 * nsdatetime: support pypy internal use
  45 * Throw error if backend does not support passwords.
  46
  47 Cleanups:
  48
  49 * ci: Use proper unrar on Windows.  MingW one is tolaretes
  50   paths with ``/`` better than upstream build.
  51 * ci: Add Python 3.10 to the testing (Christian Clauss)
  52   [`#76 <https://github.com/markokr/rarfile/pull/76>`_]
  53 * Avoid isascii, not in 3.6
  54
  55 Version 4.0 (2020-07-31)
  56 ------------------------
  57
  58 Main goals are:
  59
  60 * Increased ``zipfile``-compatibility, thus also achieving smaller
  61   difference between RAR3 and RAR5 archives.
  62 * Implement :meth:`RarFile.extract` on top of :meth:`RarFile.open` instead
  63   using ``unrar x`` directly, thus making maintenance of alternative backends
  64   more manageable.  Negative aspect of that is that there are features that
  65   internal extract code does not support - hard links, NTFS streams and
  66   junctions.
  67
  68 Breaking changes:
  69
  70 * Directory names will have "/" appended.
  71   [`#31 <https://github.com/markokr/rarfile/issues/31>`_]
  72 * :meth:`RarFile.extract` operates only on single entry,
  73   so when used on directory it will create directory
  74   but not extract files under it.
  75 * :meth:`RarFile.extract`/:meth:`RarFile.extractall`/:meth:`RarFile.testrar`
  76   will not launch special unrar command line, instead they are
  77   implemented on top of :meth:`RarFile.open`.
  78 * Keyword args in top-level APIs were renamed to match zipfile:
  79
  80   * RarFile(rarfile) -> RarFile(file)
  81   * RarFile.setpassword(password) -> .setpassword(pwd)
  82   * RarFile.getinfo(fname) -> .getinfo(name)
  83   * RarFile.open(fname, mode, psw) -> .open(name, mode, pwd)
  84   * RarFile.read(fname, psw) -> .read(name, pwd)
  85
  86 * :data:`PATH_SEP` cannot be changed from "/".
  87
  88 New features:
  89
  90 * :meth:`RarFile.extract` will return final sanitized filename for
  91   target file.
  92   [`#42 <https://github.com/markokr/rarfile/issues/42>`_,
  93   `#52 <https://github.com/markokr/rarfile/issues/52>`_]
  94 * :meth:`RarInfo.is_dir` is now preferred spelling of ``isdir()``.
  95   Old method kept as alias.
  96   [`#44 <https://github.com/markokr/rarfile/issues/44>`_]
  97 * New :meth:`RarInfo.is_file` and :meth:`RarInfo.is_symlink`
  98   methods. Only one of :meth:`~RarInfo.is_file`, :meth:`~RarInfo.is_dir`
  99   or :meth:`~RarInfo.is_symlink` can be True.
 100 * :meth:`RarFile.printdir` has ``file`` argument for output.
 101 * :meth:`RarFile.__iter__` loops over :class:`RarInfo` entries.
 102 * RAR3: throw :exc:`NeedFirstVolume` exception with current volume number,
 103   like RAR5 does.
 104   [`#58 <https://github.com/markokr/rarfile/issues/58>`_]
 105 * Nanosecond timestamp support.  Visible as :class:`nsdatetime`
 106   instance.
 107 * Minimal CLI when run as script: ``python3 -m rarfile``
 108 * Skip old file versions in versioned archive.
 109
 110 Cleanups:
 111
 112 * Use PBKDF2 implementation from :mod:`hashlib`.
 113 * Improve test coverage.
 114
 115 Version 3.3 (2020-07-26)
 116 ------------------------
 117
 118 Fixes:
 119
 120 * Add the .sfx test files to MANIFEST.in for inclusion in pypi tarball.
 121   [`#60 <https://github.com/markokr/rarfile/issues/60>`_]
 122 * Add all files in git to tarball.
 123
 124 Version 3.2 (2020-07-19)
 125 ------------------------
 126
 127 New features:
 128
 129 * Support ``unar`` as decompression backend.  It has much better
 130   support for RAR features than ``bsdtar``.
 131   [`#36 <https://github.com/markokr/rarfile/issues/36>`_]
 132
 133 * Support SFX archives - archive header is searched in first
 134   2MB of the file.
 135   [`#48 <https://github.com/markokr/rarfile/issues/48>`_]
 136
 137 * Add :data:`HACK_TMP_DIR` option, to force temp files into
 138   specific directory.
 139   [`#43 <https://github.com/markokr/rarfile/issues/43>`_]
 140
 141 Fixes:
 142
 143 * Always use "/" for path separator in command-line, gives better
 144   results on Windows.
 145
 146 Cleanups:
 147
 148 * Drop module-level options from docs, they create confusion.
 149   [`#47 <https://github.com/markokr/rarfile/issues/47>`_]
 150
 151 * Drop support for Python 2 and 3.5 and earlier.  Python 2 is dead
 152   and requiring Python 3.6 gives blake2s, stdlib that supports pathlib,
 153   and ordered dict without compat hacks.
 154
 155 * Replace PyCrypto with PyCryptodome in tests.
 156
 157 * Use Github Actions for CI.
 158
 159 Version 3.1 (2019-09-15)
 160 ------------------------
 161
 162 **This will be last version with support for Python 2.x**
 163
 164 New feature:
 165
 166 * Accept pathlib objects as filenames.
 167   (Aleksey Popov)
 168
 169 * Accept `bytes` filenames in Python 3
 170   (Nate Bogdanowicz)
 171
 172 Fixes:
 173
 174 * Use bug-compatible SHA1 for longer passwords (> 28 chars)
 175   in RAR3 encrypted headers.
 176   (Marko Kreen)
 177
 178 * Return true/false from _check_unrar_tool
 179   (miigotu)
 180
 181 * Include all test files in archive
 182   (Benedikt Morbach)
 183
 184 * Include volume number in NeedFirstVolume exception if available (rar5).
 185
 186 Cleanups:
 187
 188 * Convert tests to pytest.
 189
 190 Version 3.0 (2016-12-27)
 191 ------------------------
 192
 193 New feature:
 194
 195 * Support RAR5 archive format.  It is actually completely different
 196   archive format from RAR3 one, only is uses same file extension
 197   and tools are old one.
 198
 199   Except incompatibilies noted below, most of code should notice no change,
 200   existing :class:`RarInfo` fields will continue using RAR3-compatible
 201   values (eg. :attr:`RarInfo.host_os`).  RAR5-specific values will use
 202   new fields.
 203
 204 Incompatibilities between rarfile v2.x and 3.x:
 205
 206 * Default :data:`PATH_SEP` is now '/' instead '\\'.
 207
 208 * Removed :data:`NEED_COMMENTS` option, comments are always extracted.
 209
 210 * Removed :data:`UNICODE_COMMENTS` option, they are always decoded.
 211
 212 * Removed :data:`USE_DATETIME` option, :attr:`RarInfo.date_time` is always tuple,
 213   :attr:`RarInfo.mtime`, :attr:`RarInfo.atime`, :attr:`RarInfo.ctime` and
 214   :attr:`RarInfo.arctime` are always :class:`datetime.datetime` objects.
 215
 216 Fixes:
 217
 218 * Fixed bug when calling rarfp.open() on a RarInfo structure.
 219
 220 Cleanups:
 221
 222 * Code refactor to allow 2 different file format parsers.
 223
 224 * Code cleanups to pass modern linters.
 225
 226 * New testing and linting setup based on Tox_.
 227
 228 * Use setuptools instead distutils for install.
 229
 230 .. _Tox: https://tox.readthedocs.io/en/latest/
 231
 232 Version 2.8 (2016-06-07)
 233 ------------------------
 234
 235 * Fix: support solid archives from in-memory file object.
 236   Full archive will be written out to temp file.
 237   [`#21 <https://github.com/markokr/rarfile/issues/21>`_]
 238
 239 * Fix: ask unrar stop switches scanning,
 240   to handle archive names starting with "-".
 241   (Alexander Shadchin)
 242   [`#12 <https://github.com/markokr/rarfile/pull/12>`_]
 243
 244 * Fix: add missing _parse_error variable to RarFile object.
 245   (Gregory Mazzola)
 246   [`#20 <https://github.com/markokr/rarfile/pull/20>`_]
 247
 248 * Fix: return proper boolean from :meth:`RarInfo.needs_password`.
 249   [`#22 <https://github.com/markokr/rarfile/issues/22>`_]
 250
 251 * Fix: do not insert non-string rarfile into exception string.
 252   (Tim Muller)
 253   [`#23 <https://github.com/markokr/rarfile/pull/23>`_]
 254
 255 * Fix: make :meth:`RarFile.extract` and :meth:`RarFile.testrar`
 256   support in-memory archives.
 257
 258 * Use cryptography_ module as preferred crypto backend.
 259   PyCrypto_ will be used as fallback.
 260
 261 * Cleanup: remove compat code for Python 2.4/2.5/2.6.
 262
 263 .. _cryptography: https://pypi.org/project/cryptography/
 264 .. _PyCrypto: https://pypi.org/project/pycrypto/
 265
 266 Version 2.7 (2014-11-23)
 267 ------------------------
 268
 269 * Allow use of bsdtar_ as decompression backend.  It sits
 270   on top of libarchive_, which has support for reading RAR archives.
 271
 272   Limitations of ``libarchive`` RAR backend:
 273
 274   - Does not support solid archives.
 275   - Does not support password-protected archives.
 276   - Does not support "parsing filters" used for audio/image/executable data,
 277     so few non-solid, non-encrypted archives also fail.
 278
 279   Now :mod:`rarfile` checks if ``unrar`` and if not then tries ``bsdtar``.
 280   If that works, then keeps using it.  If not then configuration
 281   stays with ``unrar`` which will then appear in error messages.
 282
 283 .. _bsdtar: https://github.com/libarchive/libarchive/wiki/ManPageBsdtar1
 284 .. _libarchive: https://www.libarchive.org/
 285
 286 * Both :class:`RarFile` and :func:`is_rarfile` now accept file-like
 287   object.  Eg. :class:`io.BytesIO`.  Only requirement is that the object
 288   must be seekable.  This mirrors similar funtionality in zipfile.
 289
 290   Based on patch by Chase Zhang.
 291
 292 * Uniform error handling.  :class:`RarFile` accepts ``errors="strict"``
 293   argument.
 294
 295   Allow user to tune whether parsing and missing file errors will raise
 296   exception.  If error is not raised, the error string can be queried
 297   with :meth:`RarFile.strerror` method.
 298
 299 Version 2.6 (2013-04-10)
 300 ------------------------
 301
 302 * Add context manager support for :class:`RarFile` class.
 303   Both :class:`RarFile` and :class:`RarExtFile` support
 304   :keyword:`with` statement now.
 305   (Wentao Han)
 306 * :meth:`RarFile.volumelist` method, returns filenames of archive volumes.
 307 * Re-throw clearer error in case ``unrar`` is not found in ``PATH``.
 308 * Sync new unrar4.x error code from ``rar.txt``.
 309 * Use Sphinx for documentation, push docs to rtfd.org_
 310
 311 .. _rtfd.org: https://rarfile.readthedocs.org/
 312
 313 Version 2.5 (2012-01-19)
 314 ------------------------
 315
 316 Fixes:
 317
 318 * :meth:`RarExtFile.read` and :meth:`RarExtFile.readinto` now do looping read
 319   to work properly on short reads.  Important for Python 3.2+ where read from pipe
 320   can return short result even on blocking file descriptor.
 321 * Proper error reporting in :meth:`RarFile.extract`, :meth:`RarFile.extractall`
 322   and  :meth:`RarFile.testrar`.
 323 * :meth:`RarExtFile.read` from unrar pipe: prefer to return unrar error code,
 324   if thats not available, do own error checks.
 325 * Avoid string addition in :meth:`RarExtFile.read`, instead use always list+join to
 326   merge multi-part reads.
 327 * dumprar: dont re-encode byte strings (Python 2.x).  This avoids
 328   unneccessary failure when printing invalid unicode.
 329
 330 Version 2.4 (2011-11-05)
 331 ------------------------
 332
 333 Fixes:
 334
 335 * :data:`USE_DATETIME`: survive bad values from RAR
 336 * Fix bug in corrupt unicode filename handling
 337 * dumprar: make unicode chars work with both pipe and console
 338
 339 Version 2.3 (2011-07-03)
 340 ------------------------
 341
 342 Features:
 343
 344 * Support .seek() method on file streams.  (Kristian Larsson)
 345 * Support .readinto() method on file streams.  Optimized implementation
 346   is available on Python 2.6+ where :class:`memoryview` is available.
 347 * Support file comments - :attr:`RarInfo.comment` contains decompressed data if available.
 348 * File objects returned by :meth:`RarFile.open()` are :class:`io.RawIOBase`-compatible.
 349   They can further wrapped with :class:`io.BufferedReader` and :class:`io.TextIOWrapper`.
 350 * Now .getinfo() uses dict lookup instead of sequential scan when
 351   searching archive entry.  This speeds up prococessing for archives that
 352   have many entries.
 353 * Option :data:`UNICODE_COMMENTS` to decode both archive and file comments to unicode.
 354   It uses :data:`TRY_ENCODINGS` for list of encodings to try.  If off, comments are
 355   left as byte strings.  Default: 0
 356 * Option :data:`PATH_SEP` to change path separator.  Default: ``r'\'``,
 357   set ``rarfile.PATH_SEP='/'`` to be compatibe with zipfile.
 358 * Option :data:`USE_DATETIME` to convert timestamps to datetime objects.
 359   Default: 0, timestamps are tuples.
 360 * Option :data:`TRY_ENCODINGS` to allow tuning attempted encoding list.
 361 * Reorder :class:`RarInfo` fiels to better show zipfile-compatible fields.
 362 * Standard regtests to make sure various features work
 363
 364 Compatibility:
 365
 366 * Drop :attr:`RarInfo.unicode_filename`, plain :attr:`RarInfo.filename` is already unicode since 2.0.
 367 * .read(-1) reads now until EOF.  Previously it returned empty buffer.
 368
 369 Fixes:
 370
 371 * Make encrypted headers work with Python 3.x bytes() and with old 2.x 'sha' module.
 372 * Simplify :class:`subprocess.Popen` usage when launching ``unrar``.  Previously
 373   it tried to optimize and work around OS/Python bugs, but this is not
 374   maintainable.
 375 * Use temp rar file hack on multi-volume archives too.
 376 * Always .wait() on unrar, to avoid zombies
 377 * Convert struct.error to BadRarFile
 378 * Plug some fd leaks.  Affected: Jython, PyPy.
 379 * Broken archives are handled more robustly.
 380
 381 Version 2.2 (2010-08-19)
 382 ------------------------
 383
 384 Fixes:
 385
 386 * Relaxed volume naming.  Now it just calculates new volume name by finding number
 387   in old one and increasing it, without any expectations what that number should be.
 388 * Files with 4G of compressed data in one colume were handled wrong.  Fix.
 389 * DOS timestamp seconds need to be multiplied with 2.
 390 * Correct EXTTIME parsing.
 391
 392 Cleanups:
 393
 394 * Compressed size is per-volume, sum them together, so that user sees complete
 395   compressed size for files split over several volumes.
 396 * dumprar: Show unknown bits.
 397 * Use :class:`struct.Struct` to cache unpack formats.
 398 * Support missing :data:`os.devnull`. (Python 2.3)
 399
 400 Version 2.1 (2010-07-31)
 401 ------------------------
 402
 403 Features:
 404
 405 * Minimal implmentation for :meth:`RarFile.extract`, :meth:`RarFile.extractall`, :meth:`RarFile.testrar`.
 406   They are simple shortcuts to ``unrar`` invocation.
 407 * Accept :class:`RarInfo` object where filename is expected.
 408 * Include ``dumprar.py`` in .tgz.  It can be used to visualize RAR structure
 409   and test module.
 410 * Support for encrypted file headers.
 411
 412 Fixes:
 413
 414 * Don't read past ENDARC, there could be non-RAR data there.
 415 * RAR 2.x: It does not write ENDARC, but our volume code expected it.  Fix that.
 416 * RAR 2.x: Support more than 200 old-style volumes.
 417
 418 Cleanups:
 419
 420 * Load comment only when requested.
 421 * Cleanup of internal config variables.  They should have now final names.
 422 * :meth:`RarFile.open`: Add mode=r argument to match zipfile.
 423 * Doc and comments cleanup, minimize duplication.
 424 * Common wrappers for both compressed and uncompressed files,
 425   now :meth:`RarFile.open` also does CRC-checking.
 426
 427 Version 2.0 (2010-04-29)
 428 ------------------------
 429
 430 Features:
 431
 432 * Python 3 support.  Still works with 2.x.
 433 * Parses extended time fields. (.mtime, .ctime, .atime)
 434 * :meth:`RarFile.open` method.  This makes possible to process large
 435   entries that do not fit into memory.
 436 * Supports password-protected archives.
 437 * Supports archive comments.
 438
 439 Cleanups:
 440
 441 * Uses :mod:`subprocess` module to launch ``unrar``.
 442 * .filename is always Unicode string, .unicode_filename is now deprecated.
 443 * .CRC is unsigned again, as python3 crc32() is unsigned.
 444
 445 Version 1.1 (2008-08-31)
 446 ------------------------
 447
 448 Fixes:
 449
 450 * Replace :func:`os.tempnam` with :func:`tempfile.mkstemp`.  (Jason Moiron)
 451 * Fix infinite loop in _extract_hack on unexpected EOF
 452 * :attr:`RarInfo.CRC` is now signed value to match crc32()
 453 * :meth:`RarFile.read` now checks file crc
 454
 455 Cleanups:
 456
 457 * more docstrings
 458 * throw proper exceptions (subclasses of :exc:`rarfile.Error`)
 459 * RarInfo has fields pre-initialized, so they appear in help()
 460 * rename RarInfo.data to RarInfo.header_data
 461 * dont use "print" when header parsing fails
 462 * use try/finally to delete temp rar
 463
 464 Version 1.0 (2005-08-08)
 465 ------------------------
 466
 467 * First release.
 468