rarfile API documentation ¶

Table Of Contents

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

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.

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.

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.

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.

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

readline()¶

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

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.