IFileTree

class mobase.IFileTree

Bases: mobase.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 weaks.

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, 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 previouis 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: IFileTree.WalkReturn = Ellipsis

FAIL_IF_EXISTS: IFileTree.InsertPolicy = Ellipsis

MERGE: IFileTree.InsertPolicy = Ellipsis

REPLACE: IFileTree.InsertPolicy = Ellipsis

SKIP: IFileTree.WalkReturn = Ellipsis

STOP: IFileTree.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.

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.

Return type

IFileTree

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.

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.

Return type

FileTreeEntry

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.

Returns

True if all entries have been detached, False otherwise.

Return type

bool

copy(entry, path='', policy=<InsertPolicy.FAIL_IF_EXISTS: Ellipsis>)

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.

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.

• 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.

Return type

FileTreeEntry

createOrphanTree(name='')

Create a new orphan empty tree.

Parameters

name – Name of the tree.

Returns

A new tree without any parent.

Return type

IFileTree

exists(path, type=<FileTypes.DIRECTORY: Ellipsis>)

Check if the given entry exists.

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.

Return type

bool

find(path, type=<FileTypes.DIRECTORY: Ellipsis>)

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.

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.

Return type

Union[IFileTree, FileTreeEntry, None]

insert(entry, policy=<InsertPolicy.FAIL_IF_EXISTS: Ellipsis>)

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

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

• 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().

    • Otherwize 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.

Return type

bool

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 overriden 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.

Parameters

• other – Tree to merge.

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

Returns

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

the number of overwritten entries.

Raises

RuntimeError – If the merge failed.

Return type

Union[Dict[FileTreeEntry, FileTreeEntry], int]

move(entry, path, policy=<InsertPolicy.FAIL_IF_EXISTS: Ellipsis>)

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.

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.

Return type

bool

pathTo(entry, sep='\\')

Retrieve the path from this tree to the given entry.

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.

Return type

str

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.

Parameters

names – Names of the entries to delete.

Returns

The number of deleted entry.

Return type

int

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.

Parameters

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

Returns

The number of deleted entry.

Return type

int

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.

Parameters

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

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