IFileTree

class mobase.IFileTree

Bases: FileTreeEntry

Interface to classes that provides way to visualize and alter file trees. The tree may not correspond to an actual file tree on the disk (e.g., inside an archive, from a QTree Widget, …).

Read-only operations on the tree are thread-safe, even when the tree has not been populated yet.

In order to prevent wrong usage of the tree, implementing classes may throw UnsupportedOperationException if an operation is not supported. By default, all operations are supported, but some may not make sense in many situations.

The goal of this is not reflect the change made to a IFileTree to the disk, but child classes may override relevant methods to do so.

The tree is built upon FileTreeEntry. A given tree holds shared pointers to its entries while each entry holds a weak pointer to its parent, this means that the descending link are strong (shared pointers) but the uplink are weak.

Accessing the parent is always done by locking the weak pointer so that returned pointer or either null or valid. This structure implies that as long as the initial root lives, entry should not be destroyed, unless the entry are detached from the root and no shared pointers are kept.

However, it is not guarantee that one can go up the tree from a single node entry. If the root node is destroyed, it will not be possible to go up the tree, even if we still have a valid shared pointer.

Attributes Summary

CONTINUE
FAIL_IF_EXISTS
MERGE
REPLACE
SKIP
STOP

Methods Summary

addDirectory(path)	Create a new directory tree under this tree.
addFile(path[, replace_if_exists])	Create a new file directly under this tree.
clear()	Delete (detach) all the entries from this tree.
copy(entry[, path, insert_policy])	Move the given entry to the given path under this tree.
createOrphanTree([name])	Create a new orphan empty tree.
exists(path[, type])	Check if the given entry exists.
find(path[, type])	Retrieve the given entry.
insert(entry[, policy])	Insert the given entry in this tree, removing it from its previous parent.
merge(other[, overwrites])	Merge the given tree with this tree, i.e., insert all entries of the given tree into this tree.
move(entry, path[, policy])	Move the given entry to the given path under this tree.
pathTo(entry[, sep])	Retrieve the path from this tree to the given entry.
remove(**kwds)	Helper for @overload to raise when called.
removeAll(names)	Delete the entries with the given names from the tree.
removeIf(filter)	Delete entries matching the given predicate from the tree.
walk(callback[, sep])	Walk this tree, calling the given function for each entry in it.

Attributes Documentation

CONTINUE: WalkReturn = Ellipsis

FAIL_IF_EXISTS: InsertPolicy = Ellipsis

MERGE: InsertPolicy = Ellipsis

REPLACE: InsertPolicy = Ellipsis

SKIP: WalkReturn = Ellipsis

STOP: WalkReturn = Ellipsis

Methods Documentation

addDirectory(path)

Create a new directory tree under this tree.

This method will create missing folders in the given path and will not fail if the directory already exists but will fail if the given path contains “.” or “..”. This method invalidates iterators to this tree and all the subtrees present in the given path.

Return type:

IFileTree

Parameters:

path – Path to the directory to create.

Returns:

An IFileTree corresponding to the created directory.

Raises:

RuntimeError – If the directory could not be created.

addFile(path, replace_if_exists=False)

Create a new file directly under this tree.

This method will fail if the file already exists and replace_if_exists is False. This method invalidates iterators to this tree and all the subtrees present in the given path.

Return type:

FileTreeEntry

Parameters:

• path – Path to the file to create.

• replace_if_exists – If True and an entry already exists at the given location, it will be replaced by a new entry. This will replace both files and directories.

Returns:

A FileTreeEntry corresponding to the created file.

Raises:

RuntimeError – If the file could not be created.

clear()

Delete (detach) all the entries from this tree.

This method will go through the entries in this tree and stop at the first entry that cannot be deleted, this means that the tree can be partially cleared.

Return type:

bool

Returns:

True if all entries have been detached, False otherwise.

copy(entry, path='', insert_policy=InsertPolicy.None)

Move the given entry to the given path under this tree.

The entry must not be a parent tree of this tree. This method can also be used to rename entries.

If the insert policy if FAIL_IF_EXISTS, the call will fail if an entry at the same location already exists. If the policy is REPLACE, an existing entry will be replaced. If MERGE, the entry will be merged with the existing one (if the entry is a file, and a file exists, the file will be replaced).

This method invalidates iterator to this tree, to the parent tree of the given entry, and to subtrees of this tree if the insert policy is MERGE.

Return type:

FileTreeEntry

Parameters:

• entry – Entry to copy.

• path – The path to copy the entry to. If the path ends with / or , the entry will be copied in the corresponding directory instead of replacing it. If the given path is empty (“”), the entry is copied directly under this tree.

• insert_policy – Policy to use to resolve conflicts.

Returns:

The new entry (copy of the specified entry).

Raises:

RuntimeError – If the entry could not be copied.

createOrphanTree(name='')

Create a new orphan empty tree.

Return type:

IFileTree

Parameters:

name – Name of the tree.

Returns:

A new tree without any parent.

exists(path, type=FileTypes.None)

Check if the given entry exists.

Return type:

bool

Parameters:

• path – Path to the entry, separated by / or .

• type – The type of the entry to check.

Returns:

True if the entry was found, False otherwise.

find(path, type=FileTypes.None)

Retrieve the given entry.

If no entry exists at the given path, or if the entry is not of the right type, None is returned.

Return type:

UnionType[IFileTree, FileTreeEntry, None]

Parameters:

• path – Path to the entry, separated by / or .

• type – The type of the entry to check.

Returns:

The entry at the given location, or None if the entry was not found or

was not of the correct type.

insert(entry, policy=InsertPolicy.None)

Insert the given entry in this tree, removing it from its previous parent.

The entry must not be this tree or a parent entry of this tree. :rtype: bool

• If the insert policy if FAIL_IF_EXISTS, the call will fail if an entry with the same name already exists.

• If the policy is REPLACE, an existing entry will be replaced by the given entry.

• If the policy is MERGE:

  • If there is no entry with the same name, the new entry is inserted.

  • If there is an entry with the same name:

    • If both entries are files, the old file is replaced by the given entry.

    • If both entries are directories, a merge is performed as if using merge().

    • Otherwise the insertion fails (two entries with different types).

This method invalidates iterator to this tree, to the parent tree of the given entry, and to subtrees of this tree if the insert policy is MERGE.

Parameters:

• entry – Entry to insert.

• policy – Policy to use to resolve conflicts.

Returns:

True if the entry was insert, False otherwise.

merge(other, overwrites=False)

Merge the given tree with this tree, i.e., insert all entries of the given tree into this tree.

The tree must not be this tree or a parent entry of this tree. Files present in both tree will be replaced by files in the given tree. After a merge, the source tree will be empty but still attached to its parent.

If overwrites is True, a map from overridden files to new files will be returned.

Note that the merge process makes no distinction between files and directories when merging: if a directory is present in this tree and a file from source is in conflict with it, the tree will be removed and the file inserted; if a file is in this tree and a directory from source is in conflict with it, the file will be replaced with the directory.

This method invalidates iterators to this tree, all the subtrees under this tree present in the given path, and all the subtrees of the given source.

Return type:

Union[Dict[FileTreeEntry, FileTreeEntry], int]

Parameters:

• other – Tree to merge.

• overwrites – If True, a mapping from overridden files to new files will be returned.

Returns:

If overwrites is True, a mapping from overridden files to new files, otherwise

the number of overwritten entries.

Raises:

RuntimeError – If the merge failed.

move(entry, path, policy=InsertPolicy.None)

Move the given entry to the given path under this tree.

The entry must not be a parent tree of this tree. This method can also be used to rename entries.

If the insert policy if FAIL_IF_EXISTS, the call will fail if an entry at the same location already exists. If the policy is REPLACE, an existing entry will be replaced. If MERGE, the entry will be merged with the existing one (if the entry is a file, and a file exists, the file will be replaced).

This method invalidates iterator to this tree, to the parent tree of the given entry, and to subtrees of this tree if the insert policy is MERGE.

Return type:

bool

Parameters:

• entry – Entry to move.

• path – The path to move the entry to. If the path ends with / or , the entry will be inserted in the corresponding directory instead of replacing it. If the given path is empty (“”), this is equivalent to insert().

• policy – Policy to use to resolve conflicts.

Returns:

True if the entry was moved correctly, False otherwise.

pathTo(entry, sep='\\\\')

Retrieve the path from this tree to the given entry.

Return type:

str

Parameters:

• entry – The entry to reach, must be in this tree.

• sep – The type of separator to use to create the path.

Returns:

The path from this tree to the given entry, including the name of the entry, or

an empty string if the given entry was not found under this tree.

remove(**kwds)

Helper for @overload to raise when called.

removeAll(names)

Delete the entries with the given names from the tree.

This method does not recurse into subtrees, so only entries accessible directly from this tree will be removed. This method invalidates iterators.

Return type:

int

Parameters:

names – Names of the entries to delete.

Returns:

The number of deleted entry.

removeIf(filter)

Delete entries matching the given predicate from the tree.

This method does not recurse into subtrees, so only entries accessible directly from this tree will be removed. This method invalidates iterators.

Return type:

int

Parameters:

filter – Predicate that should return true for entries to delete.

Returns:

The number of deleted entry.

walk(callback, sep='\\\\')

Walk this tree, calling the given function for each entry in it.

The given callback will be called with two parameters: the path from this tree to the given entry (with a trailing separator, not including the entry name), and the actual entry. The method returns a WalkReturn object to indicates what to do.

Return type:

None

Parameters:

• callback – Method to call for each entry in the tree.

• sep – Type of separator to use to construct the path.