doc/news.rst

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