rarfile API documentation¶
Table Of Contents
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.
New 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.
-
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.
New 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.RawIOBase
interface, so it can be further wrapped withio.BufferedReader
andio.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
- member – filename or
-
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.
-
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 asdatetime
object 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.
New in version 4.0.
-
is_symlink
()¶ 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
()¶ 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.
-
writelines
()¶ 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
¶ 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.