rarfile API¶
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(file: str | Path | FileLike, mode: str = 'r', charset: str | None = None, info_callback: Callable[[RarEntry], None] | None = None, crc_check: bool = True, errors: Literal['stop', 'strict'] = 'stop', part_only: bool = 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.
Added in version 4.0.
- __exit__(typ: type[BaseException] | None, value: BaseException | None, traceback: TracebackType | None) None¶
Exit context.
- volumelist() Sequence[str | bytes | Path | FileLike]¶
Returns filenames of archive volumes.
In case of single-volume archive, the list contains just the name of main archive file.
- getinfo_orig(name: str | Path | RarInfo) RarInfo¶
Return RarInfo for file source.
RAR5: if name is hard-linked or copied file, returns original entry with original filename.
Added in version 4.1.
- open(name: str | Path | RarInfo, mode: str = 'r', pwd: str | None = None) RarExtFile¶
Returns file-like object (
RarExtFile) from where the data can be read.The object implements
io.RawIOBaseinterface, so it can be further wrapped withio.BufferedReaderandio.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: str | Path | RarInfo, pwd: str | None = None) bytes¶
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.
- extract(member: str | Path | RarInfo, path: str | Path | None = None, pwd: str | None = None) str | None¶
Extract single file into current directory.
- Parameters:
member -- filename or
RarInfoinstancepath -- optional destination path
pwd -- optional password to use
- extractall(path: str | Path | None = None, members: Iterable[str | Path | RarInfo] | None = None, pwd: str | None = None) None¶
Extract all files into current directory.
- Parameters:
path -- optional destination path
members -- optional filename or
RarInfoinstance list to extractpwd -- optional password to use
RarInfo class¶
- class RarInfo¶
Bases:
RarEntryA file entry in rar archive.
Timestamps as
datetimeare without timezone in RAR3, with UTC timezone in RAR5 archives.- 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.
- 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.
- Type:
- 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.- Type:
- mtime¶
File modification time. Same value as
date_timebut asdatetimeobject with extended precision.- Type:
datetime.datetime | None
- ctime¶
Optional time field: creation time. As
datetimeobject.- Type:
datetime.datetime | None
- atime¶
Optional time field: last access time. As
datetimeobject.- Type:
datetime.datetime | None
- arctime¶
Optional time field: archival time. As
datetimeobject. (RAR3-only)- Type:
datetime.datetime | None
- volume_file¶
Volume file name, where file starts.
- Type:
str | bytes | pathlib.Path | rarfile.utils.FileLike | None
- 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_SYMLINKUnix symlink.
RAR5_XREDIR_WINDOWS_SYMLINKWindows symlink.
RAR5_XREDIR_WINDOWS_JUNCTIONWindows junction.
RAR5_XREDIR_HARD_LINKHard link to target.
RAR5_XREDIR_FILE_COPYCurrent file is copy of another archive entry.
Flags may contain bits:
RAR5_XREDIR_ISDIRSymlink points to directory.
RarEntry class¶
RarExtFile class¶
- class RarExtFile¶
Bases:
RawIOBaseBase 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.
- readinto(buf: bytearray | memoryview | Buffer) int¶
Zero-copy read directly into buffer.
Returns bytes read.
- seek(offset: int, whence: int = 0) int¶
Seek in data.
On uncompressed files, the seeking works by actual seeks so it's fast. On compressed files its slow - forward seeking happens by reading ahead, backwards by re-opening and decompressing from the start.
- fileno()¶
Return underlying file descriptor if one exists.
Raise OSError 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.
- writelines(lines, /)¶
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 nsdatetime(..., nanosecond=0)¶
Bases:
datetimeDatetime that carries nanoseconds.
Arithmetic operations will lose nanoseconds.
Added in version 4.0.
- astimezone(tz: tzinfo | None = None) nsdatetime¶
Convert to new timezone.
- isoformat(sep: str = 'T', timespec: str = 'auto') str¶
Formats with nanosecond precision by default.
- replace(..., nanosecond=0)¶
Return new timestamp with specified fields replaced.
Functions¶
Constants¶
RAR constants
Warnings¶
- class UnsupportedWarning¶
Archive uses feature that are unsupported by rarfile.
Added in version 4.0.
Exceptions¶
- class Error¶
Base class for rarfile errors.
- class BadRarFile¶
Incorrect data in archive.
- class NotRarFile¶
The file is not RAR archive.
- class BadRarName¶
Cannot guess multipart name components.
- class NoRarEntry¶
File not found in RAR
- class PasswordRequired¶
File requires password
- class BadSymLinkError¶
Invalid symbolic link
- class NeedFirstVolume(msg: str, volume: int | None)¶
Need to start from first volume.
- current_volume¶
Volume number of current file or None if not known
- class NoCrypto¶
Cannot parse encrypted headers - no crypto available.
- class RarExecError¶
Problem reported by unrar/rar.
- class RarWarning¶
Non-fatal error
- class RarFatalError¶
Fatal error
- class RarCRCError¶
CRC error during unpacking
- class RarLockedArchiveError¶
Must not modify locked archive
- class RarWriteError¶
Write error
- class RarOpenError¶
Open error
- class RarUserError¶
User error
- class RarMemoryError¶
Memory error
- class RarCreateError¶
Create error
- class RarNoFilesError¶
No files that match pattern were found
- class RarUserBreak¶
User stop
- class RarWrongPassword¶
Incorrect password
- class RarUnknownError¶
Unknown exit code
- class RarSignalExit¶
Unrar exited with signal
- class RarCannotExec¶
Executable not found.