doc/news.rst

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