doc/faq.rst

   1
   2 rarfile FAQ
   3 ===========
   4
   5 .. contents:: Table of Contents
   6
   7 What are the dependencies?
   8 --------------------------
   9
  10 It depends on ``unrar`` command-line utility to do the actual decompression.
  11 Note that by default it expect it to be in ``PATH``.  If unrar
  12 launching fails, you need to fix this.
  13
  14 Alternatively, :mod:`rarfile` can use bsdtar_ from libarchive_ as
  15 decompression backend, but that is a bit problematic as bsdtar_ does not support
  16 all RAR features.
  17
  18 .. _bsdtar: https://github.com/libarchive/libarchive/wiki/ManPageBsdtar1
  19 .. _libarchive: http://www.libarchive.org/
  20
  21 It depends on cryptography_ or PyCrypto_ modules to process
  22 archives with password-protected headers.
  23
  24 .. _cryptography: https://pypi.python.org/pypi/cryptography
  25 .. _PyCrypto: https://pypi.python.org/pypi/pycrypto
  26
  27 Does it parse ``unrar`` output to get archive contents?
  28 -------------------------------------------------------
  29
  30 No, :mod:`rarfile` parses RAR structure in Python code.  Also it can
  31 read uncompressed files from archive without external utility.
  32
  33 Will rarfile support wrapping unrarlib/unrar.dll/unrar.so in the future?
  34 ------------------------------------------------------------------------
  35
  36 No.  The current architecture - parsing in Python and decompression with
  37 command line tools work well across all interesting operating systems
  38 (Windows/Linux/MacOS), wrapping a library does not bring any advantages.
  39
  40 Simple execution of command-line tools is also legally simpler situation
  41 than linking with external library.
  42
  43 How can I get it work on Windows?
  44 ---------------------------------
  45
  46 On Windows the ``unrar.exe`` is not in ``PATH`` so simple ``Popen("unrar ..")`` does not work.
  47 It can be solved several ways:
  48
  49 1. Add location of ``unrar.exe`` to PATH.
  50 2. Set :data:`rarfile.UNRAR_TOOL` to full path of ``unrar.exe``.
  51 3. Copy ``unrar.exe`` to your program directory.
  52 4. Copy ``unrar.exe`` to system directory that is in PATH, eg. ``C:\Windows``.
  53
  54 How to avoid the need for user to manually install rarfile/unrar?
  55 -----------------------------------------------------------------
  56
  57 Include ``rarfile.py`` and/or ``unrar`` with your application.
  58
  59 Will it support creating RAR archives?
  60 --------------------------------------
  61
  62 No.  RARLAB_ is not interested in RAR becoming open format
  63 and specifically discourages writing RAR creation software.
  64
  65 In the meantime use either Zip_ (better compatibility) or 7z_ (better compression)
  66 format for your own archives.
  67
  68 .. _RARLAB: http://www.rarlab.com/
  69 .. _Zip: https://en.wikipedia.org/wiki/ZIP_%28file_format%29
  70 .. _7z:  https://en.wikipedia.org/wiki/7z
  71
  72 What is the USE_EXTRACT_HACK?
  73 -----------------------------
  74
  75 RarFile uses ``unrar`` to extract compressed files.  But when extracting
  76 single file from archive containing many entries, ``unrar`` needs to parse
  77 whole archive until it finds the right entry.  This makes random-access
  78 to entries slow.  To avoid that, RarFile remembers location of compressed
  79 data for each entry and on read it copies it to temporary archive containing
  80 only data for that one file, thus making ``unrar`` fast.
  81
  82 The logic is only activated for entries smaller than :data:`rarfile.HACK_SIZE_LIMIT`
  83 (20M by default).  Bigger files are accessed directly from RAR.
  84
  85 Note - it only works for non-solid archives.  So if you care about
  86 random access to files in your archive, do not create solid archives.
  87