API Reference

class arlib.Archive

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.

close()

Release resources such as closing files etc

extract(path=None, members=None)

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)

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)

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]

open_member(name, mode='r', **kwargs)

Open a member file contained in the archive

Parameters:

• name (str) – name of the member file to open
• mode (str) – The mode to open the member, same as in open(). Default to ‘r’.
• kwargs – Additional keyword arguments that will be passed to the underlying function.

Returns:

A opened file object associated with the member file

Return type:

file-like

class arlib.DirArchive(path, mode='r')

Archive engine that treat a directory as an archive using pathlib module

extract(path=None, members=None)

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]

open_member(name, mode='r', **kwargs)

Open a member in the directory

Parameters:

• name (str) – Name of the member file
• mode (str) – The mode argument to open. Same as in open().
• kwargs – Additional keyword arguments that will be passed to open()

Returns:

The opened file object associated with the member file.

Return type:

file-like

class arlib.TarArchive(path, mode='r', **kwargs)

Archive engine for tar files using the tarfile module

Parameters:

• path (path-like) – Path to the archive
• mode (str) – The mode to open the member, same as in open().
• kwargs – Other keyword arguments that will be passed to the underlying function.

close()

Release resources such as closing files etc

extract(path=None, members=None)

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]

open_member(name, mode='r')

Open member file contained in the tar archive

Parameters:

• name (str) – Name of the member to open
• mode (str) – The mode argument to open. Same as in open().

Returns:

The opened file object associated with the member file.

Return type:

file-like

Note

Members of tar archive cannot be opened in write mode.

class arlib.ZipArchive(path, *args, **kwargs)

Archive engine for zip files using the zipfile module

close()

Release resources such as closing files etc

extract(path=None, members=None)

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]

open_member(name, mode='r', **kwargs)

Open a member file in the zip archive

Parameters:

• name (str) – Name of the member file
• mode (str) – The mode argument to open. Same as in open().
• kwargs – Additional keyword arguments that will be passed to zipfile.ZipFile.open()

Returns:

The opened file object associated with the member file.

Return type:

file-like

arlib.assert_is_archive(path, mode)

Assert that path can be opened as a valid archive with mode

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

is_archive()

arlib.auto_engine(path, mode='r')

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

is_archive()

arlib.is_archive(path, mode='r')

Determine if the file specified by path is a valid archive when opened with mode

Basically, the function checks the result of auto_engien(), and return True if the result is not None, and return False 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:

bool

otherwise.

Examples

>>> is_archive('a.tar.gz', 'w')
True
>>> is_archive('a.tar.bz2', 'w')
True
>>> is_archive('a.txt', 'w')
False

See also

auto_engine()

arlib.open(path, mode='r', engine=None, *args, **kwargs)

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)

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.