API Reference¶
-
class
arlib.
Archive
[source]¶ Common-interface to different type of archive files manipulation
Parameters: - path (path-like, file-like) – Path of the archive to read or write
- mode (str) – The mode to open the member, same as in
open()
. Default to ‘r’. - engine (type) –
Class object of a specific subclass Archive which implements the logic of processing a specific type of Archive. Provided implements:
- ZipArchive: zip file archive using the zipfile module
- TarArchive: tar file archive using the tarfile module
- DirArchive: directory as an archive using the pathlib module
- None: Automatically determine engines by file properties and mode
- kwargs – Additional keyword arguments passed to the underlying engine constructor
Note
The constructor of a concrete engine should take at least one positional argument path and one optional argument mode with default value to r.
-
extract
(path=None, members=None)[source]¶ Extract members to a location
Parameters: - path (path-like) – Location of the extracted files.
- members (Seq[str]) – Members to extract, specified by a list of names.
-
member_is_dir
(name)[source]¶ Check if a specific member is a directory
Parameters: name (str) – Member name. Returns:
bool: True if the member is a directory, False otherwise.
-
member_is_file
(name)[source]¶ Check if a specific member is a regular file
Parameters: name (str) – Member name. Returns:
bool: True if the member is a regular file, False otherwise.
-
member_names
¶ Get list of names of the members (i.e. files contained in the archive)
Returns: list of member names Return type: list[str]
-
class
arlib.
DirArchive
(path, mode='r')[source]¶ Archive engine that treat a directory as an archive using pathlib module
-
extract
(path=None, members=None)[source]¶ Extract members to a location
Parameters: - path (path-like) – Location of the extracted files.
- members (Seq[str]) – Members to extract, specified by a list of names.
-
member_names
¶ Get list of names of the members (i.e. files contained in the archive)
Returns: list of member names Return type: list[str]
-
-
class
arlib.
TarArchive
(path, mode='r', **kwargs)[source]¶ Archive engine for tar files using the tarfile module
Parameters: -
extract
(path=None, members=None)[source]¶ Extract members to a location
Parameters: - path (path-like) – Location of the extracted files.
- members (Seq[str]) – Members to extract, specified by a list of names.
-
member_names
¶ Get list of names of the members (i.e. files contained in the archive)
Returns: list of member names Return type: list[str]
-
-
class
arlib.
ZipArchive
(path, *args, **kwargs)[source]¶ Archive engine for zip files using the zipfile module
-
extract
(path=None, members=None)[source]¶ Extract members to a location
Parameters: - path (path-like) – Location of the extracted files.
- members (Seq[str]) – Members to extract, specified by a list of names.
-
member_names
¶ Get list of names of the members (i.e. files contained in the archive)
Returns: list of member names Return type: list[str]
-
-
arlib.
assert_is_archive
(path, mode)[source]¶ Assert that
path
can be opened as a valid archive withmode
Parameters: - path (file-like, path-like) – Opened file object or path to the archive file.
- mode (str) – Mode str to open the file. Default to “r”.
Examples
>>> assert_is_archive('a.tar.gz', 'w') >>> assert_is_archive('a.txt', 'w') Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: a.txt cannot be opened as a valid archive with w
See also
-
arlib.
auto_engine
(path, mode='r')[source]¶ Automatically determine engine type from file properties and file mode using the registered determining functions
Parameters: - path (file-like, path-like) – Opened file object or path to the archive file
- mode (str) – Mode str to open the file. Default to “r”.
Returns: - a subclass of Archive if successfully find one
engine, otherwise None
Return type: type, NoneType
See also
-
arlib.
is_archive
(path, mode='r')[source]¶ Determine if the file specified by
path
is a valid archive when opened withmode
Basically, the function checks the result of
auto_engien()
, and returnTrue
if the result is not None, and returnFalse
otherwise.Parameters: - path (file-like, path-like) – Opened file object or path to the archive file.
- mode (str) – Mode str to open the file. Default to “r”.
Returns: True
if the path is valid archive,False
Return type: otherwise.
Examples
>>> is_archive('a.tar.gz', 'w') True >>> is_archive('a.tar.bz2', 'w') True >>> is_archive('a.txt', 'w') False
See also
-
arlib.
open
(path, mode='r', engine=None, *args, **kwargs)[source]¶ Open an archive file
Parameters: - path (path-like, file-like) – Path of the archive to read or write
- mode (str) – The mode to open the member, same as in
open()
. Default to ‘r’. - engine (type) –
Class object of a specific subclass Archive which implements the logic of processing a specific type of Archive. Provided implements:
- ZipArchive: zip file archive using the zipfile module
- TarArchive: tar file archive using the tarfile module
- DirArchive: directory as an archive using the pathlib module
- None: Automatically determine engines by file properties and mode
- kwargs – Additional keyword arguments passed to the underlying engine constructor
-
arlib.
register_auto_engine
(func, priority=50, prepend=False)[source]¶ Register automatic engine determing function
Two possible signatures:
register_auto_engine(func, priority=50, prepend=False)
register_auto-engine(priority=50, prepend=False)
The first one can be used as a regular function as well as a decorator. The second one is a decorator with arguments
Parameters: - func (callable) – A callable which determines archive engine from file properties and open mode. The signature should be: func(path, mode) where path is a file-like or path-like object, and mode str to open the file.
- priority (int, float) – Priority of the func, small number means higher priority. When multiple functions are registered by multiple call of register_auto_engine, functions will be used in an ordering determined by thier priortities. Default to 50.
- prepend (bool) – If there is already a function with the same priority registered, insert to the left (before) or right (after) of it. Default to False.
Returns: The first version of signature will return the input callable
func
, therefore it can be used as a decorator (without arguments). The second version will return a decorator wrap.