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())

There are few module-level parameters to tune behaviour, here they are with defaults, and reason to change it:

import rarfile

# Set to full path of unrar.exe if it is not in PATH
rarfile.UNRAR_TOOL = "unrar"

# Set to 0 if you don't look at comments and want to
# avoid wasting time for parsing them
rarfile.NEED_COMMENTS = 1

# Set up to 1 if you don't want to deal with decoding comments
# from unknown encoding.  rarfile will try couple of common
# encodings in sequence.
rarfile.UNICODE_COMMENTS = 0

# Set to 1 if you prefer timestamps to be datetime objects
# instead tuples
rarfile.USE_DATETIME = 0

# Set to '/' to be more compatible with zipfile
rarfile.PATH_SEP = '\\'

For more details, refer to source.

RarFile class

class rarfile.RarFile(rarfile, mode='r', charset=None, info_callback=None, crc_check=True)

Bases: object

Parse RAR structure, provide access to files in archive.

Open and parse a RAR archive.

Parameters:

rarfile
archive file name
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
comment = None

Archive comment. Byte string or None. Use UNICODE_COMMENTS to get automatic decoding to unicode.

setpassword(password)

Sets the password to use when extracting.

needs_password()

Returns True if any archive entries require password for extraction.

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(fname)

Return RarInfo for file.

open(fname, mode='r', psw=None)

Returns file-like object (RarExtFile), from where the data can be read.

The object implements io.RawIOBase interface, so it can be further wrapped with io.BufferedReader and 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:

fname
file name or RarInfo instance.
mode
must be ‘r’
psw
password to use for extracting.
read(fname, psw=None)

Return uncompressed data for archive entry.

For longer files using .open() may be better idea.

Parameters:

fname
filename or RarInfo instance
psw
password to use for extracting.
close()

Release open resources.

printdir()

Print archive file list to stdout.

extract(member, path=None, pwd=None)

Extract single file into current directory.

Parameters:

member
filename or RarInfo instance
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 RarInfo instance list to extract
pwd
optional password to use
testrar()

Let ‘unrar’ test the archive.

RarInfo class

class rarfile.RarInfo

Bases: object

An entry in rar archive.

zipfile-compatible fields:

filename
File name with relative path. Default path separator is ‘\’, to change set rarfile.PATH_SEP. Always unicode string.
date_time
Modification time, tuple of (year, month, day, hour, minute, second). Or datetime() object if USE_DATETIME is set.
file_size
Uncompressed size.
compress_size
Compressed size.
CRC
CRC-32 of uncompressed file, unsigned int.
comment
File comment. Byte string or None. Use UNICODE_COMMENTS to get automatic decoding to unicode.
volume
Volume nr, starting from 0.

RAR-specific fields:

compress_type
Compression method: 0x30 - 0x35.
extract_version
Minimal Rar version needed for decompressing.
host_os
Host OS type, one of RAR_OS_* constants.
mode
File attributes. May be either dos-style or unix-style, depending on host_os.
volume_file
Volume file name, where file starts.
mtime
Optional time field: Modification time, with float seconds. Same as .date_time but with more precision.
ctime
Optional time field: creation time, with float seconds.
atime
Optional time field: last access time, with float seconds.
arctime
Optional time field: archival time, with float seconds.

Internal fields:

type
One of RAR_BLOCK_* types. Only entries with type==RAR_BLOCK_FILE are shown in .infolist().
flags
For files, RAR_FILE_* bits.
isdir()

Returns True if the entry is a directory.

RarExtFile class

class rarfile.RarExtFile(rf, inf)

Bases: io.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.

If io module is available (Python 2.6+, 3.x), then this calls will inherit from io.RawIOBase class. This makes line-based access available: RarExtFile.readline() and for ln in f.

name = None

Filename of the archive entry

read(cnt=None)

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(ofs, whence=0)

Seek in data.

On uncompressed files, the seeking works by actual seeks so it’s fast. On compresses files its slow - forward seeking happends 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()

Returns underlying file descriptor if one exists.

An IOError is raised if the IO object does not use a file descriptor.

flush()

Flush write buffers, if applicable.

This is not implemented for read-only and non-blocking streams.

isatty()

Return whether this is an ‘interactive’ stream.

Return False if it can’t be determined.

next

x.next() -> the next value, or raise StopIteration

readline()

Read and return a line from the stream.

If limit is specified, at most limit 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()

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.

truncate()

Truncate file to size bytes.

File pointer is left unchanged. Size defaults to the current IO position as reported by tell(). Returns the new size.

Functions

rarfile.is_rarfile(fn)

Check quickly whether file is rar archive.

Module Configuration

rarfile.UNRAR_TOOL = 'unrar'

‘unrar’, ‘rar’ or full path to either one

rarfile.DEFAULT_CHARSET = 'windows-1252'

default fallback charset

rarfile.TRY_ENCODINGS = ('utf8', 'utf-16le')

list of encodings to try, with fallback to DEFAULT_CHARSET if none succeed

rarfile.USE_DATETIME = 0

Convert RAR time tuple into datetime() object

rarfile.PATH_SEP = '\\'

Separator for path name components. RAR internally uses ‘\’. Use ‘/’ to be similar with zipfile.

rarfile.NEED_COMMENTS = 1

whether to parse file/archive comments.

rarfile.UNICODE_COMMENTS = 0

whether to convert comments to unicode strings

rarfile.REPORT_BAD_HEADER = 0

When RAR is corrupt, stopping on bad header is better On unknown/misparsed RAR headers reporting is better

rarfile.USE_EXTRACT_HACK = 1

whether to speed up decompression by using tmp archive

rarfile.HACK_SIZE_LIMIT = 20971520

limit the filesize for tmp archive usage

Constants

rarfile.RAR_M0

No compression.

rarfile.RAR_M1

Compression level -m1 - Fastest compression.

rarfile.RAR_M2

Compression level -m2.

rarfile.RAR_M3

Compression level -m3.

rarfile.RAR_M4

Compression level -m4.

rarfile.RAR_M5

Compression level -m5 - Maximum compression.

rarfile.RAR_OS_MSDOS
rarfile.RAR_OS_OS2
rarfile.RAR_OS_WIN32
rarfile.RAR_OS_UNIX
rarfile.RAR_OS_MACOS
rarfile.RAR_OS_BEOS

Exceptions

class rarfile.Error

Bases: exceptions.Exception

Base class for rarfile errors.

class rarfile.BadRarFile

Bases: rarfile.Error

Incorrect data in archive.

class rarfile.NotRarFile

Bases: rarfile.Error

The file is not RAR archive.

class rarfile.BadRarName

Bases: rarfile.Error

Cannot guess multipart name components.

class rarfile.NoRarEntry

Bases: rarfile.Error

File not found in RAR

class rarfile.PasswordRequired

Bases: rarfile.Error

File requires password

class rarfile.NeedFirstVolume

Bases: rarfile.Error

Need to start from first volume.

class rarfile.NoCrypto

Bases: rarfile.Error

Cannot parse encrypted headers - no crypto available.

class rarfile.RarExecError

Bases: rarfile.Error

Problem reported by unrar/rar.

class rarfile.RarWarning

Bases: rarfile.RarExecError

Non-fatal error

class rarfile.RarFatalError

Bases: rarfile.RarExecError

Fatal error

class rarfile.RarCRCError

Bases: rarfile.RarExecError

CRC error during unpacking

class rarfile.RarLockedArchiveError

Bases: rarfile.RarExecError

Must not modify locked archive

class rarfile.RarWriteError

Bases: rarfile.RarExecError

Write error

class rarfile.RarOpenError

Bases: rarfile.RarExecError

Open error

class rarfile.RarUserError

Bases: rarfile.RarExecError

User error

class rarfile.RarMemoryError

Bases: rarfile.RarExecError

Memory error

class rarfile.RarCreateError

Bases: rarfile.RarExecError

Create error

class rarfile.RarNoFilesError

Bases: rarfile.RarExecError

No files that match pattern were found

class rarfile.RarUserBreak

Bases: rarfile.RarExecError

User stop

class rarfile.RarUnknownError

Bases: rarfile.RarExecError

Unknown exit code

class rarfile.RarSignalExit

Bases: rarfile.RarExecError

Unrar exited with signal

Table Of Contents

Previous topic

rarfile - RAR archive reader for Python

Next topic

rarfile FAQ

This Page