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

Parse RAR structure, provide access to files in archive.

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.

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.

open(name, mode='r', pwd=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

  • 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 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(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 datetime are 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.

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 object with extended precision.

ctime

Optional time field: creation time. As datetime object.

atime

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

arctime

Optional time field: archival time. As 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)

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.

New in version 4.0.

Returns True if entry is a symlink.

New in version 4.0.

is_file()

Returns True if entry is a normal file.

New 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: 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.

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

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.

nsdatetime class

class rarfile.nsdatetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0, nanosecond=0)

Bases: datetime.datetime

Datetime that carries nanoseconds.

Arithmetic not supported, will lose nanoseconds.

New in version 4.0.

nanosecond

Number of nanoseconds, 0 <= nanosecond < 999999999

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.

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