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 '\\' to be more compatible with old rarfile
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, errors='stop')

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
  • errors – Either “stop” to quietly stop parsing on errors, or “strict” to raise errors. Default is “stop”.
comment = None

Archive comment. Unicode string or None.

__enter__()

Open context.

__exit__(typ, value, traceback)

Exit context

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 RarFile.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.

strerror()

Return error string if parsing failed or None if no problems.

__delattr__

x.__delattr__(‘name’) <==> del x.name

__format__()

default object formatter

__getattribute__

x.__getattribute__(‘name’) <==> x.name

__hash__
__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__
__setattr__

x.__setattr__(‘name’, value) <==> x.name = value

__sizeof__() → int

size of object in memory, in bytes

__str__

RarInfo class

class rarfile.RarInfo

Bases: object

An entry in rar archive.

RAR3 extended timestamps are datetime.datetime objects without timezone. RAR5 extended timestamps are datetime.datetime objects with UTC timezone.

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.

file_size

Uncompressed size.

compress_size

Compressed size.

compress_type

Compression method: one of RAR_M0 .. RAR_M5 constants.

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_time but as datetime.datetime object with extended precision.

ctime

Optional time field: creation time. As datetime.datetime object.

atime

Optional time field: last access time. As datetime.datetime object.

arctime

Optional time field: archival time. As datetime.datetime object. (RAR3-only)

CRC

CRC-32 of uncompressed file, unsigned int.

RAR5: may be None.

blake2sp_hash

Blake2SP hash over decompressed data. (RAR5-only)

comment

Optional file comment field. Unicode string. (RAR3-only)

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 to target.
RAR5_XREDIR_WINDOWS_SYMLINK
windows symlink to target.
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 RAR5_XREDIR_ISDIR bit.

volume

Volume nr, starting from 0.

volume_file

Volume file name, where file starts.

isdir()

Returns True if entry is a directory.

needs_password()

Returns True if data is stored password-protected.

__delattr__

x.__delattr__(‘name’) <==> del x.name

__format__()

default object formatter

__getattribute__

x.__getattribute__(‘name’) <==> x.name

__hash__
__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__
__setattr__

x.__setattr__(‘name’, value) <==> x.name = value

__sizeof__() → int

size of object in memory, in bytes

__str__

RarExtFile class

class rarfile.RarExtFile(parser, 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.

Open archive entry.

name = None

Filename of the archive entry

read(cnt=None)

Read all or specified amount of data from archive entry.

close()

Close open resources.

__del__()

Hook delete to make sure tempfile is removed.

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

__delattr__

x.__delattr__(‘name’) <==> del x.name

__format__()

default object formatter

__getattribute__

x.__getattribute__(‘name’) <==> x.name

__hash__
__iter__
__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__
__setattr__

x.__setattr__(‘name’, value) <==> x.name = value

__sizeof__() → int

size of object in memory, in bytes

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

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.PATH_SEP = '/'

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

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.RarWrongPassword

Bases: rarfile.RarExecError

Incorrect password

class rarfile.RarUnknownError

Bases: rarfile.RarExecError

Unknown exit code

class rarfile.RarSignalExit

Bases: rarfile.RarExecError

Unrar exited with signal

class rarfile.RarCannotExec

Bases: rarfile.RarExecError

Executable not found.