rarfile API documentation¶
Introduction¶
RAR archive reader.
This is Python module for Rar archive reading.  The interface
is made as zipfile-like as possible.
- Basic logic:
- Parse archive structure with Python. 
- Extract non-compressed files with Python 
- Extract compressed files with unrar. 
- Optionally write compressed data to temp file to speed up unrar, otherwise it needs to scan whole archive on each execution. 
 
Example:
import rarfile
rf = rarfile.RarFile("myarchive.rar")
for f in rf.infolist():
    print(f.filename, f.file_size)
    if f.filename == "README":
        print(rf.read(f))
Archive files can also be accessed via file-like object returned
by RarFile.open():
import rarfile
with rarfile.RarFile("archive.rar") as rf:
    with rf.open("README") as f:
        for ln in f:
            print(ln.strip())
For decompression to work, either unrar or unar tool must be in PATH.
RarFile class¶
- class rarfile.RarFile(file, mode='r', charset=None, info_callback=None, crc_check=True, errors='stop', part_only=False)¶
- Parse RAR structure, provide access to files in archive. - Parameters:
- file – archive file name or file-like object. 
- mode – only “r” is supported. 
- charset – fallback charset to use, if filenames are not already Unicode-enabled. 
- info_callback – debug callback, gets to see all archive entries. 
- crc_check – set to False to disable CRC checks 
- errors – Either “stop” to quietly stop parsing on errors, or “strict” to raise errors. Default is “stop”. 
- part_only – - If True, read only single file and allow it to be middle-part of multi-volume archive. - Added in version 4.0. 
 
 - comment = None¶
- Archive comment. Unicode string or None. 
 - filename = None¶
- File name, if available. Unicode string or None. 
 - __enter__()¶
- Open context. 
 - __exit__(typ, value, traceback)¶
- Exit context. 
 - __iter__()¶
- Iterate over members. 
 - setpassword(pwd)¶
- Sets the password to use when extracting. 
 - needs_password()¶
- Returns True if any archive entries require password for extraction. 
 - is_solid()¶
- Returns True if archive uses solid compression. - Added in version 4.2. 
 - namelist()¶
- Return list of filenames in archive. 
 - infolist()¶
- Return RarInfo objects for all files/directories in archive. 
 - volumelist()¶
- Returns filenames of archive volumes. - In case of single-volume archive, the list contains just the name of main archive file. 
 - getinfo(name)¶
- Return RarInfo for file. 
 - getinfo_orig(name)¶
- Return RarInfo for file source. - RAR5: if name is hard-linked or copied file, returns original entry with original filename. - Added in version 4.1. 
 - open(name, mode='r', pwd=None)¶
- Returns file-like object ( - RarExtFile) from where the data can be read.- The object implements - io.RawIOBaseinterface, so it can be further wrapped with- io.BufferedReaderand- io.TextIOWrapper.- On older Python where io module is not available, it implements only .read(), .seek(), .tell() and .close() methods. - The object is seekable, although the seeking is fast only on uncompressed files, on compressed files the seeking is implemented by reading ahead and/or restarting the decompression. - Parameters:
- name – file name or RarInfo instance. 
- mode – must be “r” 
- pwd – password to use for extracting. 
 
 
 - read(name, pwd=None)¶
- Return uncompressed data for archive entry. - For longer files using - open()may be better idea.- Parameters:
- name – filename or RarInfo instance 
- pwd – password to use for extracting. 
 
 
 - close()¶
- Release open resources. 
 - printdir(file=None)¶
- Print archive file list to stdout or given file. 
 - extract(member, path=None, pwd=None)¶
- Extract single file into current directory. - Parameters:
- member – filename or - RarInfoinstance
- path – optional destination path 
- pwd – optional password to use 
 
 
 - extractall(path=None, members=None, pwd=None)¶
- Extract all files into current directory. - Parameters:
- path – optional destination path 
- members – optional filename or - RarInfoinstance list to extract
- pwd – optional password to use 
 
 
 - testrar(pwd=None)¶
- Read all files and test CRC. 
 - strerror()¶
- Return error string if parsing failed or None if no problems. 
 
RarInfo class¶
- class rarfile.RarInfo¶
- An entry in rar archive. - Timestamps as - datetimeare without timezone in RAR3, with UTC timezone in RAR5 archives.- filename¶
- File name with relative path. Path separator is “/”. Always unicode string. 
 - date_time¶
- File modification timestamp. As tuple of (year, month, day, hour, minute, second). RAR5 allows archives where it is missing, it’s None then. 
 - comment¶
- Optional file comment field. Unicode string. (RAR3-only) 
 - file_size¶
- Uncompressed size. 
 - compress_size¶
- Compressed size. 
 - extract_version¶
- Minimal Rar version needed for decompressing. As (major*10 + minor), so 2.9 is 29. - RAR3: 10, 20, 29 - RAR5 does not have such field in archive, it’s simply set to 50. 
 - host_os¶
- Host OS type, one of RAR_OS_* constants. - RAR3: - RAR_OS_WIN32,- RAR_OS_UNIX,- RAR_OS_MSDOS,- RAR_OS_OS2,- RAR_OS_BEOS.- RAR5: - RAR_OS_WIN32,- RAR_OS_UNIX.
 - mode¶
- File attributes. May be either dos-style or unix-style, depending on host_os. 
 - mtime¶
- File modification time. Same value as - date_timebut as- datetimeobject with extended precision.
 - CRC¶
- CRC-32 of uncompressed file, unsigned int. - RAR5: may be None. 
 - blake2sp_hash¶
- Blake2SP hash over decompressed data. (RAR5-only) 
 - volume¶
- Volume nr, starting from 0. 
 - volume_file¶
- Volume file name, where file starts. 
 - file_redir¶
- If not None, file is link of some sort. Contains tuple of (type, flags, target). (RAR5-only) - Type is one of constants: - RAR5_XREDIR_UNIX_SYMLINK
- Unix symlink. 
- RAR5_XREDIR_WINDOWS_SYMLINK
- Windows symlink. 
- RAR5_XREDIR_WINDOWS_JUNCTION
- Windows junction. 
- RAR5_XREDIR_HARD_LINK
- Hard link to target. 
- RAR5_XREDIR_FILE_COPY
- Current file is copy of another archive entry. 
 - Flags may contain bits: - RAR5_XREDIR_ISDIR
- Symlink points to directory. 
 
 - is_dir()¶
- Returns True if entry is a directory. - Added in version 4.0. 
 - is_symlink()¶
- Returns True if entry is a symlink. - Added in version 4.0. 
 - is_file()¶
- Returns True if entry is a normal file. - Added in version 4.0. 
 - needs_password()¶
- Returns True if data is stored password-protected. 
 - isdir()¶
- Returns True if entry is a directory. - Deprecated since version 4.0. 
 
RarExtFile class¶
- class rarfile.RarExtFile¶
- Bases: - RawIOBase- Base class for file-like object that - RarFile.open()returns.- Provides public methods and common crc checking. - Behaviour:
- no short reads - .read() and .readinfo() read as much as requested. 
- no internal buffer, use io.BufferedReader for that. 
 
 - name = None¶
- Filename of the archive entry 
 - read(n=-1)¶
- Read all or specified amount of data from archive entry. 
 - close()¶
- Close open resources. 
 - readinto(buf)¶
- Zero-copy read directly into buffer. - Returns bytes read. 
 - tell()¶
- Return current reading position in uncompressed data. 
 - seek(offset, whence=0)¶
- Seek in data. - On uncompressed files, the seeking works by actual seeks so it’s fast. On compressed files its slow - forward seeking happens by reading ahead, backwards by re-opening and decompressing from the start. 
 - readable()¶
- Returns True 
 - writable()¶
- Returns False. - Writing is not supported. 
 - seekable()¶
- Returns True. - Seeking is supported, although it’s slow on compressed files. 
 - readall()¶
- Read all remaining data 
 - fileno()¶
- Return underlying file descriptor if one exists. - Raise OSError if the IO object does not use a file descriptor. 
 - isatty()¶
- Return whether this is an ‘interactive’ stream. - Return False if it can’t be determined. 
 - readline(size=-1, /)¶
- Read and return a line from the stream. - If size is specified, at most size bytes will be read. - The line terminator is always b’n’ for binary files; for text files, the newlines argument to open can be used to select the line terminator(s) recognized. 
 - readlines(hint=-1, /)¶
- Return a list of lines from the stream. - hint can be specified to control the number of lines read: no more lines will be read if the total size (in bytes/characters) of all lines so far exceeds hint. 
 - writelines(lines, /)¶
- Write a list of lines to stream. - Line separators are not added, so it is usual for each of the lines provided to have a line separator at the end. 
 
nsdatetime class¶
- class rarfile.nsdatetime(year, month=None, day=None, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0, nanosecond=0)¶
- Bases: - datetime- Datetime that carries nanoseconds. - Arithmetic operations will lose nanoseconds. - Added in version 4.0. - isoformat(sep='T', timespec='auto')¶
- Formats with nanosecond precision by default. 
 - astimezone(tz=None)¶
- Convert to new timezone. 
 - replace(year=None, month=None, day=None, hour=None, minute=None, second=None, microsecond=None, tzinfo=None, *, fold=None, nanosecond=None)¶
- Return new timestamp with specified fields replaced. 
 
Functions¶
- rarfile.is_rarfile(xfile)¶
- Check quickly whether file is rar archive. 
- rarfile.is_rarfile_sfx(xfile)¶
- Check whether file is rar archive with support for SFX. - It will read 2M from file. 
Constants¶
- rarfile.RAR_M0 = 48¶
- No compression. 
- rarfile.RAR_M1 = 49¶
- Compression level -m1 - Fastest compression. 
- rarfile.RAR_M2 = 50¶
- Compression level -m2. 
- rarfile.RAR_M3 = 51¶
- Compression level -m3. 
- rarfile.RAR_M4 = 52¶
- Compression level -m4. 
- rarfile.RAR_M5 = 53¶
- Compression level -m5 - Maximum compression. 
- rarfile.RAR_OS_WIN32 = 2¶
- Windows 
- rarfile.RAR_OS_UNIX = 3¶
- UNIX 
- rarfile.RAR_OS_MACOS = 4¶
- MacOS (only in RAR3) 
- rarfile.RAR_OS_BEOS = 5¶
- BeOS (only in RAR3) 
- rarfile.RAR_OS_OS2 = 1¶
- OS2 (only in RAR3) 
- rarfile.RAR_OS_MSDOS = 0¶
- MSDOS (only in RAR3) 
Warnings¶
- class rarfile.UnsupportedWarning¶
- Archive uses feature that are unsupported by rarfile. - Added in version 4.0. 
Exceptions¶
- class rarfile.Error¶
- Base class for rarfile errors. 
- class rarfile.BadRarFile¶
- Incorrect data in archive. 
- class rarfile.NotRarFile¶
- The file is not RAR archive. 
- class rarfile.BadRarName¶
- Cannot guess multipart name components. 
- class rarfile.NoRarEntry¶
- File not found in RAR 
- class rarfile.PasswordRequired¶
- File requires password 
- class rarfile.NeedFirstVolume(msg, volume)¶
- Need to start from first volume. - current_volume¶
- Volume number of current file or None if not known 
 
- class rarfile.NoCrypto¶
- Cannot parse encrypted headers - no crypto available. 
- class rarfile.RarExecError¶
- Problem reported by unrar/rar. 
- class rarfile.RarWarning¶
- Non-fatal error 
- class rarfile.RarFatalError¶
- Fatal error 
- class rarfile.RarCRCError¶
- CRC error during unpacking 
- class rarfile.RarLockedArchiveError¶
- Must not modify locked archive 
- class rarfile.RarWriteError¶
- Write error 
- class rarfile.RarOpenError¶
- Open error 
- class rarfile.RarUserError¶
- User error 
- class rarfile.RarMemoryError¶
- Memory error 
- class rarfile.RarCreateError¶
- Create error 
- class rarfile.RarNoFilesError¶
- No files that match pattern were found 
- class rarfile.RarUserBreak¶
- User stop 
- class rarfile.RarWrongPassword¶
- Incorrect password 
- class rarfile.RarUnknownError¶
- Unknown exit code 
- class rarfile.RarSignalExit¶
- Unrar exited with signal 
- class rarfile.RarCannotExec¶
- Executable not found.