📝 Modify
There are two types of modification available
- Non-replacing scenario: Shift or copy nodes within same tree or between two trees using
from_paths
(list of paths) andto_paths
(list of paths). - Replacing scenario: Shift or copy nodes within same tree or between two trees while replacing the to-node using
from_paths
(list of paths) andto_paths
(list of paths).
Available Configurations for Customization
In non-replacing scenario, there are several configurations available for customization.
Configuration | Description | Default Value |
---|---|---|
copy |
Indicates whether it is to shift the nodes, or copy the nodes | False (nodes are shifted, not copied) |
to_tree |
Indicates whether shifting/copying is within the same tree, or between different trees | None (nodes are shifted/copied within the same tree) |
skippable |
Skip shifting/copying of nodes if from_path cannot be found | False (from-node must be found) |
overriding |
Override existing node if it exists | False (to-node must not exist) |
merge_children |
Shift/copy children of from-node and remove intermediate parent node | False (children are not merged) |
merge_leaves |
Shift/copy leaves of from-node and remove all intermediate nodes | False (leaves are not merged) |
delete_children |
Shift/copy node only and delete its children | False (nodes are shifted/copied together with children) |
In replacing scenario, all the configurations are also available except overriding
, merge_children
, and merge_leaves
as it is doing a one-to-one replacement.
It is by default overriding, and there is nothing to merge.
Note
merge_children
and merge_leaves
cannot be simultaneously set to True
.
Note
Error will always be thrown if multiple from-nodes are found, paths in from_paths
must be unique.
Tree Modification Permutations
There are several ways you can mix and match the tree modification methods.
If you know all the parameters to choose, feel free to use copy_or_shift_logic
or replace_logic
methods as they are the most customizable.
All other methods calls these 2 methods directly.
Shift / Copy? | Same tree / Between two trees? | Replace destination node? | Method to use |
---|---|---|---|
Shift | Same tree | No | shift_nodes |
Copy | Same tree | No | copy_nodes |
Copy | Between two trees | No | copy_nodes_from_tree_to_tree |
Any | Any | No | copy_or_shift_logic |
Shift | Same tree | Yes | shift_and_replace_nodes |
Copy | Between two trees | Yes | copy_and_replace_nodes_from_tree_to_tree |
Any | Any | Yes | replace_logic |
Tree Modification Illustration
Sample Tree Modification (Shift, Copy, Delete)
Setting | Sample path in from_paths |
Sample path in to_paths |
Description |
---|---|---|---|
Default | "/a/c" | "/a/b/c" | Shift/copy node c |
Default | "/c" | "/a/b/c" | Shift/copy node c |
Default | "c" | "/a/b/c" | Shift/copy node c |
Default | "/a/e" | None | Delete node e |
skippable | "/a/c" | "/a/b/c" | Shift/copy node c , skip if "/a/c" cannot be found |
Sample Tree Modification (Advanced)
Setting | Sample path in from_paths |
Sample path in to_paths |
Description |
---|---|---|---|
overriding | "a/b/c" | "a/d/c" | Shift/copy node c , override if "a/d/c" exists |
merge_children | "a/b/c" | "a/d/c" | If path not present: Shift/copy children of node c to be children of node d , removing node c If path present: Shift/copy children of node c to be merged with existing "a/d/c" children |
merge_children + overriding | "a/b/c" | "a/d/c" | If path not present: Behaves like merge_children If path present: Behaves like overriding |
merge_leaves | "a/b/c" | "a/d/c" | If path not present: Shift/copy leaves of node c to be children of node d If path present: Shift/copy leaves of node c to be merged with existing "a/d/c" children |
- merge_leaves + overriding | "a/b/c" | "a/d/c" | If path not present: Behaves like merge_leaves If path present: Behaves like overriding, but original node c remains |
delete_children | "a/b" | "a/d/b" | Shift/copy node b only without any node b children |
bigtree.tree.modify
shift_nodes
shift_nodes(
tree,
from_paths,
to_paths,
sep="/",
skippable=False,
overriding=False,
merge_children=False,
merge_leaves=False,
delete_children=False,
with_full_path=False,
)
Shift nodes from from_paths
to to_paths
in-place.
- Creates intermediate nodes if to path is not present
- Able to skip nodes if from path is not found, defaults to False (from-nodes must be found; not skippable).
- Able to override existing node if it exists, defaults to False (to-nodes must not exist; not overridden).
- Able to merge children and remove intermediate parent node, defaults to False (nodes are shifted; not merged).
- Able to merge only leaf nodes and remove all intermediate nodes, defaults to False (nodes are shifted; not merged)
- Able to shift node only and delete children, defaults to False (nodes are shifted together with children).
For paths in from_paths
and to_paths
,
- Path name can be with or without leading tree path separator symbol.
For paths in from_paths
,
- Path name can be partial path (trailing part of path) or node name.
- If
with_full_path=True
, path name must be full path. - Path name must be unique to one node.
For paths in to_paths
,
- Path name must be full path.
- Can set to empty string or None to delete the path in
from_paths
, note thatcopy
must be set to False.
If merge_children=True
,
- If
to_path
is not present, it shifts children offrom_path
. - If
to_path
is present, andoverriding=False
, original and new children are merged. - If
to_path
is present andoverriding=True
, it behaves like overriding and only new children are retained.
If merge_leaves=True
,
- If
to_path
is not present, it shifts leaves offrom_path
. - If
to_path
is present, andoverriding=False
, original children and leaves are merged. - If
to_path
is present andoverriding=True
, it behaves like overriding and only new leaves are retained, original non-leaf nodes infrom_path
are retained.
Examples:
>>> from bigtree import list_to_tree, str_to_tree, shift_nodes
>>> root = list_to_tree(["Downloads/photo1.jpg", "Downloads/file1.doc"])
>>> root.show()
Downloads
├── photo1.jpg
└── file1.doc
>>> shift_nodes(
... tree=root,
... from_paths=["Downloads/photo1.jpg", "Downloads/file1.doc"],
... to_paths=["Downloads/Pictures/photo1.jpg", "Downloads/Files/file1.doc"],
... )
>>> root.show()
Downloads
├── Pictures
│ └── photo1.jpg
└── Files
└── file1.doc
To delete node,
>>> root = list_to_tree(["Downloads/photo1.jpg", "Downloads/file1.doc"])
>>> root.show()
Downloads
├── photo1.jpg
└── file1.doc
In overriding case,
>>> root = str_to_tree(
... "Downloads\n"
... "├── Misc\n"
... "│ └── Pictures\n"
... "│ └── photo1.jpg\n"
... "└── Pictures\n"
... " └── photo2.jpg"
... )
>>> root.show()
Downloads
├── Misc
│ └── Pictures
│ └── photo1.jpg
└── Pictures
└── photo2.jpg
>>> shift_nodes(root, ["Downloads/Misc/Pictures"], ["Downloads/Pictures"], overriding=True)
>>> root.show()
Downloads
├── Misc
└── Pictures
└── photo1.jpg
In merge_children=True
case, child nodes are shifted instead of the parent node.
- If the path already exists, child nodes are merged with existing children.
- If same node is shifted, the child nodes of the node are merged with the node's parent.
>>> root = str_to_tree(
... "Downloads\n"
... "├── Misc\n"
... "│ ├── Pictures\n"
... "│ │ └── photo2.jpg\n"
... "│ └── Applications\n"
... "│ └── Chrome.exe\n"
... "├── Pictures\n"
... "│ └── photo1.jpg\n"
... "└── dummy\n"
... " └── Files\n"
... " └── file1.doc"
... )
>>> root.show()
Downloads
├── Misc
│ ├── Pictures
│ │ └── photo2.jpg
│ └── Applications
│ └── Chrome.exe
├── Pictures
│ └── photo1.jpg
└── dummy
└── Files
└── file1.doc
>>> shift_nodes(
... root,
... ["Downloads/Misc/Pictures", "Applications", "Downloads/dummy"],
... ["Downloads/Pictures", "Downloads/Applications", "Downloads/dummy"],
... merge_children=True,
... )
>>> root.show()
Downloads
├── Misc
├── Pictures
│ ├── photo1.jpg
│ └── photo2.jpg
├── Chrome.exe
└── Files
└── file1.doc
In merge_leaves=True
case, leaf nodes are copied instead of the parent node.
- If the path already exists, leaf nodes are merged with existing children.
- If same node is copied, the leaf nodes of the node are merged with the node's parent.
>>> root = str_to_tree(
... "Downloads\n"
... "├── Misc\n"
... "│ ├── Pictures\n"
... "│ │ └── photo2.jpg\n"
... "│ └── Applications\n"
... "│ └── Chrome.exe\n"
... "├── Pictures\n"
... "│ └── photo1.jpg\n"
... "└── dummy\n"
... " └── Files\n"
... " └── file1.doc"
... )
>>> root.show()
Downloads
├── Misc
│ ├── Pictures
│ │ └── photo2.jpg
│ └── Applications
│ └── Chrome.exe
├── Pictures
│ └── photo1.jpg
└── dummy
└── Files
└── file1.doc
>>> shift_nodes(
... root,
... ["Downloads/Misc/Pictures", "Applications", "Downloads/dummy"],
... ["Downloads/Pictures", "Downloads/Applications", "Downloads/dummy"],
... merge_leaves=True,
... )
>>> root.show()
Downloads
├── Misc
│ ├── Pictures
│ └── Applications
├── Pictures
│ ├── photo1.jpg
│ └── photo2.jpg
├── dummy
│ └── Files
├── Chrome.exe
└── file1.doc
In delete_children=True
case, only the node is shifted without its accompanying children/descendants.
>>> root = str_to_tree(
... "Downloads\n"
... "├── Misc\n"
... "│ └── Applications\n"
... "│ └── Chrome.exe\n"
... "└── Pictures\n"
... " └── photo1.jpg"
... )
>>> root.show()
Downloads
├── Misc
│ └── Applications
│ └── Chrome.exe
└── Pictures
└── photo1.jpg
>>> shift_nodes(root, ["Applications"], ["Downloads/Applications"], delete_children=True)
>>> root.show()
Downloads
├── Misc
├── Pictures
│ └── photo1.jpg
└── Applications
Parameters:
Name | Type | Description | Default |
---|---|---|---|
tree |
Node
|
tree to modify |
required |
from_paths |
List[str]
|
original paths to shift nodes from |
required |
to_paths |
List[str]
|
new paths to shift nodes to |
required |
sep |
str
|
path separator for input paths, applies to |
'/'
|
skippable |
bool
|
indicator to skip if from path is not found, defaults to False |
False
|
overriding |
bool
|
indicator to override existing to path if there is clashes, defaults to False |
False
|
merge_children |
bool
|
indicator to merge children and remove intermediate parent node, defaults to False |
False
|
merge_leaves |
bool
|
indicator to merge leaf nodes and remove intermediate parent node(s), defaults to False |
False
|
delete_children |
bool
|
indicator to shift node only without children, defaults to False |
False
|
with_full_path |
bool
|
indicator to shift/copy node with full path in |
False
|
copy_nodes
copy_nodes(
tree,
from_paths,
to_paths,
sep="/",
skippable=False,
overriding=False,
merge_children=False,
merge_leaves=False,
delete_children=False,
with_full_path=False,
)
Copy nodes from from_paths
to to_paths
in-place.
- Creates intermediate nodes if to path is not present
- Able to skip nodes if from path is not found, defaults to False (from-nodes must be found; not skippable).
- Able to override existing node if it exists, defaults to False (to-nodes must not exist; not overridden).
- Able to merge children and remove intermediate parent node, defaults to False (nodes are shifted; not merged).
- Able to merge only leaf nodes and remove all intermediate nodes, defaults to False (nodes are shifted; not merged)
- Able to copy node only and delete children, defaults to False (nodes are copied together with children).
For paths in from_paths
and to_paths
,
- Path name can be with or without leading tree path separator symbol.
For paths in from_paths
,
- Path name can be partial path (trailing part of path) or node name.
- If
with_full_path=True
, path name must be full path. - Path name must be unique to one node.
For paths in to_paths
,
- Path name must be full path.
If merge_children=True
,
- If
to_path
is not present, it copies children offrom_path
. - If
to_path
is present, andoverriding=False
, original and new children are merged. - If
to_path
is present andoverriding=True
, it behaves like overriding and only new children are retained.
If merge_leaves=True
,
- If
to_path
is not present, it copies leaves offrom_path
. - If
to_path
is present, andoverriding=False
, original children and leaves are merged. - If
to_path
is present andoverriding=True
, it behaves like overriding and only new leaves are retained.
Examples:
>>> from bigtree import list_to_tree, str_to_tree, copy_nodes
>>> root = list_to_tree(["Downloads/Pictures", "Downloads/photo1.jpg", "Downloads/file1.doc"])
>>> root.show()
Downloads
├── Pictures
├── photo1.jpg
└── file1.doc
>>> copy_nodes(
... tree=root,
... from_paths=["Downloads/photo1.jpg", "Downloads/file1.doc"],
... to_paths=["Downloads/Pictures/photo1.jpg", "Downloads/Files/file1.doc"],
... )
>>> root.show()
Downloads
├── Pictures
│ └── photo1.jpg
├── photo1.jpg
├── file1.doc
└── Files
└── file1.doc
In overriding case,
>>> root = str_to_tree(
... "Downloads\n"
... "├── Misc\n"
... "│ └── Pictures\n"
... "│ └── photo1.jpg\n"
... "└── Pictures\n"
... " └── photo2.jpg"
... )
>>> root.show()
Downloads
├── Misc
│ └── Pictures
│ └── photo1.jpg
└── Pictures
└── photo2.jpg
>>> copy_nodes(root, ["Downloads/Misc/Pictures"], ["Downloads/Pictures"], overriding=True)
>>> root.show()
Downloads
├── Misc
│ └── Pictures
│ └── photo1.jpg
└── Pictures
└── photo1.jpg
In merge_children=True
case, child nodes are copied instead of the parent node.
- If the path already exists, child nodes are merged with existing children.
- If same node is copied, the child nodes of the node are merged with the node's parent.
>>> root = str_to_tree(
... "Downloads\n"
... "├── Misc\n"
... "│ ├── Pictures\n"
... "│ │ └── photo2.jpg\n"
... "│ └── Applications\n"
... "│ └── Chrome.exe\n"
... "├── Pictures\n"
... "│ └── photo1.jpg\n"
... "└── dummy\n"
... " └── Files\n"
... " └── file1.doc"
... )
>>> root.show()
Downloads
├── Misc
│ ├── Pictures
│ │ └── photo2.jpg
│ └── Applications
│ └── Chrome.exe
├── Pictures
│ └── photo1.jpg
└── dummy
└── Files
└── file1.doc
>>> copy_nodes(
... root,
... ["Downloads/Misc/Pictures", "Applications", "Downloads/dummy"],
... ["Downloads/Pictures", "Downloads/Applications", "Downloads/dummy"],
... merge_children=True,
... )
>>> root.show()
Downloads
├── Misc
│ ├── Pictures
│ │ └── photo2.jpg
│ └── Applications
│ └── Chrome.exe
├── Pictures
│ ├── photo1.jpg
│ └── photo2.jpg
├── Chrome.exe
└── Files
└── file1.doc
In merge_leaves=True
case, leaf nodes are copied instead of the parent node.
- If the path already exists, leaf nodes are merged with existing children.
- If same node is copied, the leaf nodes of the node are merged with the node's parent.
>>> root = str_to_tree(
... "Downloads\n"
... "├── Misc\n"
... "│ ├── Pictures\n"
... "│ │ └── photo2.jpg\n"
... "│ └── Applications\n"
... "│ └── Chrome.exe\n"
... "├── Pictures\n"
... "│ └── photo1.jpg\n"
... "└── dummy\n"
... " └── Files\n"
... " └── file1.doc"
... )
>>> root.show()
Downloads
├── Misc
│ ├── Pictures
│ │ └── photo2.jpg
│ └── Applications
│ └── Chrome.exe
├── Pictures
│ └── photo1.jpg
└── dummy
└── Files
└── file1.doc
>>> copy_nodes(
... root,
... ["Downloads/Misc/Pictures", "Applications", "Downloads/dummy"],
... ["Downloads/Pictures", "Downloads/Applications", "Downloads/dummy"],
... merge_leaves=True,
... )
>>> root.show()
Downloads
├── Misc
│ ├── Pictures
│ │ └── photo2.jpg
│ └── Applications
│ └── Chrome.exe
├── Pictures
│ ├── photo1.jpg
│ └── photo2.jpg
├── dummy
│ └── Files
│ └── file1.doc
├── Chrome.exe
└── file1.doc
In delete_children=True
case, only the node is copied without its accompanying children/descendants.
>>> root = str_to_tree(
... "Downloads\n"
... "├── Misc\n"
... "│ └── Applications\n"
... "│ └── Chrome.exe\n"
... "└── Pictures\n"
... " └── photo1.jpg"
... )
>>> root.show()
Downloads
├── Misc
│ └── Applications
│ └── Chrome.exe
└── Pictures
└── photo1.jpg
>>> copy_nodes(root, ["Applications"], ["Downloads/Applications"], delete_children=True)
>>> root.show()
Downloads
├── Misc
│ └── Applications
│ └── Chrome.exe
├── Pictures
│ └── photo1.jpg
└── Applications
Parameters:
Name | Type | Description | Default |
---|---|---|---|
tree |
Node
|
tree to modify |
required |
from_paths |
List[str]
|
original paths to shift nodes from |
required |
to_paths |
List[str]
|
new paths to shift nodes to |
required |
sep |
str
|
path separator for input paths, applies to |
'/'
|
skippable |
bool
|
indicator to skip if from path is not found, defaults to False |
False
|
overriding |
bool
|
indicator to override existing to path if there is clashes, defaults to False |
False
|
merge_children |
bool
|
indicator to merge children and remove intermediate parent node, defaults to False |
False
|
merge_leaves |
bool
|
indicator to merge leaf nodes and remove intermediate parent node(s), defaults to False |
False
|
delete_children |
bool
|
indicator to copy node only without children, defaults to False |
False
|
with_full_path |
bool
|
indicator to shift/copy node with full path in |
False
|
shift_and_replace_nodes
shift_and_replace_nodes(
tree,
from_paths,
to_paths,
sep="/",
skippable=False,
delete_children=False,
with_full_path=False,
)
Shift nodes from from_paths
to replace to_paths
in-place.
- Creates intermediate nodes if to path is not present
- Able to skip nodes if from path is not found, defaults to False (from-nodes must be found; not skippable).
- Able to shift node only and delete children, defaults to False (nodes are shifted together with children).
For paths in from_paths
and to_paths
,
- Path name can be with or without leading tree path separator symbol.
For paths in from_paths
,
- Path name can be partial path (trailing part of path) or node name.
- If
with_full_path=True
, path name must be full path. - Path name must be unique to one node.
For paths in to_paths
,
- Path name must be full path.
- Path must exist, node-to-be-replaced must be present.
Examples:
>>> from bigtree import str_to_tree, shift_and_replace_nodes
>>> root = str_to_tree(
... "Downloads\n"
... "├── Pictures\n"
... "│ └── photo1.jpg\n"
... "└── Misc\n"
... " └── dummy"
... )
>>> root.show()
Downloads
├── Pictures
│ └── photo1.jpg
└── Misc
└── dummy
>>> shift_and_replace_nodes(root, ["Downloads/Pictures"], ["Downloads/Misc/dummy"])
>>> root.show()
Downloads
└── Misc
└── Pictures
└── photo1.jpg
In delete_children=True
case, only the node is shifted without its accompanying children/descendants.
>>> root = str_to_tree(
... "Downloads\n"
... "├── Pictures\n"
... "│ └── photo1.jpg\n"
... "└── Misc\n"
... " └── dummy"
... )
>>> root.show()
Downloads
├── Pictures
│ └── photo1.jpg
└── Misc
└── dummy
>>> shift_and_replace_nodes(root, ["Downloads/Pictures"], ["Downloads/Misc/dummy"], delete_children=True)
>>> root.show()
Downloads
└── Misc
└── Pictures
Parameters:
Name | Type | Description | Default |
---|---|---|---|
tree |
Node
|
tree to modify |
required |
from_paths |
List[str]
|
original paths to shift nodes from |
required |
to_paths |
List[str]
|
new paths to shift nodes to |
required |
sep |
str
|
path separator for input paths, applies to |
'/'
|
skippable |
bool
|
indicator to skip if from path is not found, defaults to False |
False
|
delete_children |
bool
|
indicator to shift node only without children, defaults to False |
False
|
with_full_path |
bool
|
indicator to shift/copy node with full path in |
False
|
copy_nodes_from_tree_to_tree
copy_nodes_from_tree_to_tree(
from_tree,
to_tree,
from_paths,
to_paths,
sep="/",
skippable=False,
overriding=False,
merge_children=False,
merge_leaves=False,
delete_children=False,
with_full_path=False,
)
Copy nodes from from_paths
to to_paths
in-place.
- Creates intermediate nodes if to path is not present
- Able to skip nodes if from path is not found, defaults to False (from-nodes must be found; not skippable).
- Able to override existing node if it exists, defaults to False (to-nodes must not exist; not overridden).
- Able to merge children and remove intermediate parent node, defaults to False (nodes are shifted; not merged).
- Able to merge only leaf nodes and remove all intermediate nodes, defaults to False (nodes are shifted; not merged)
- Able to copy node only and delete children, defaults to False (nodes are copied together with children).
For paths in from_paths
and to_paths
,
- Path name can be with or without leading tree path separator symbol.
For paths in from_paths
,
- Path name can be partial path (trailing part of path) or node name.
- If
with_full_path=True
, path name must be full path. - Path name must be unique to one node.
For paths in to_paths
,
- Path name must be full path.
If merge_children=True
,
- If
to_path
is not present, it copies children offrom_path
- If
to_path
is present, andoverriding=False
, original and new children are merged - If
to_path
is present andoverriding=True
, it behaves like overriding and only new leaves are retained.
If merge_leaves=True
,
- If
to_path
is not present, it copies leaves offrom_path
. - If
to_path
is present, andoverriding=False
, original children and leaves are merged. - If
to_path
is present andoverriding=True
, it behaves like overriding and only new leaves are retained.
Examples:
>>> from bigtree import Node, str_to_tree, copy_nodes_from_tree_to_tree
>>> root = str_to_tree(
... "Downloads\n"
... "├── file1.doc\n"
... "├── Pictures\n"
... "│ └── photo1.jpg\n"
... "└── Misc\n"
... " └── dummy\n"
... " └── photo2.jpg"
... )
>>> root.show()
Downloads
├── file1.doc
├── Pictures
│ └── photo1.jpg
└── Misc
└── dummy
└── photo2.jpg
>>> root_other = Node("Documents")
>>> copy_nodes_from_tree_to_tree(
... from_tree=root,
... to_tree=root_other,
... from_paths=["Downloads/Pictures", "Downloads/Misc"],
... to_paths=["Documents/Pictures", "Documents/New Misc/Misc"],
... )
>>> root_other.show()
Documents
├── Pictures
│ └── photo1.jpg
└── New Misc
└── Misc
└── dummy
└── photo2.jpg
In overriding case,
>>> root_other = str_to_tree(
... "Documents\n"
... "└── Pictures\n"
... " └── photo3.jpg"
... )
>>> root_other.show()
Documents
└── Pictures
└── photo3.jpg
>>> copy_nodes_from_tree_to_tree(
... root,
... root_other,
... ["Downloads/Pictures", "Downloads/Misc"],
... ["Documents/Pictures", "Documents/Misc"],
... overriding=True,
... )
>>> root_other.show()
Documents
├── Pictures
│ └── photo1.jpg
└── Misc
└── dummy
└── photo2.jpg
In merge_children=True
case, child nodes are copied instead of the parent node.
- If the path already exists, child nodes are merged with existing children.
>>> root_other = str_to_tree(
... "Documents\n"
... "└── Pictures\n"
... " └── photo3.jpg"
... )
>>> root_other.show()
Documents
└── Pictures
└── photo3.jpg
>>> copy_nodes_from_tree_to_tree(
... root,
... root_other,
... ["Downloads/Pictures", "Downloads/Misc"],
... ["Documents/Pictures", "Documents/Misc"],
... merge_children=True,
... )
>>> root_other.show()
Documents
├── Pictures
│ ├── photo3.jpg
│ └── photo1.jpg
└── dummy
└── photo2.jpg
In merge_leaves=True
case, leaf nodes are copied instead of the parent node.
- If the path already exists, leaf nodes are merged with existing children.
>>> root_other = str_to_tree(
... "Documents\n"
... "└── Pictures\n"
... " └── photo3.jpg"
... )
>>> root_other.show()
Documents
└── Pictures
└── photo3.jpg
>>> copy_nodes_from_tree_to_tree(
... root,
... root_other,
... ["Downloads/Pictures", "Downloads/Misc"],
... ["Documents/Pictures", "Documents/Misc"],
... merge_leaves=True,
... )
>>> root_other.show()
Documents
├── Pictures
│ ├── photo3.jpg
│ └── photo1.jpg
└── photo2.jpg
In delete_children=True
case, only the node is copied without its accompanying children/descendants.
>>> copy_nodes_from_tree_to_tree(
... root,
... root_other,
... ["Downloads/Pictures", "Downloads/Misc"],
... ["Documents/Pictures", "Documents/Misc"],
... delete_children=True,
... )
>>> root_other.show()
Documents
├── Pictures
└── Misc
Parameters:
Name | Type | Description | Default |
---|---|---|---|
from_tree |
Node
|
tree to copy nodes from |
required |
to_tree |
Node
|
tree to copy nodes to |
required |
from_paths |
List[str]
|
original paths to shift nodes from |
required |
to_paths |
List[str]
|
new paths to shift nodes to |
required |
sep |
str
|
path separator for input paths, applies to |
'/'
|
skippable |
bool
|
indicator to skip if from path is not found, defaults to False |
False
|
overriding |
bool
|
indicator to override existing to path if there is clashes, defaults to False |
False
|
merge_children |
bool
|
indicator to merge children and remove intermediate parent node, defaults to False |
False
|
merge_leaves |
bool
|
indicator to merge leaf nodes and remove intermediate parent node(s), defaults to False |
False
|
delete_children |
bool
|
indicator to copy node only without children, defaults to False |
False
|
with_full_path |
bool
|
indicator to shift/copy node with full path in |
False
|
copy_and_replace_nodes_from_tree_to_tree
copy_and_replace_nodes_from_tree_to_tree(
from_tree,
to_tree,
from_paths,
to_paths,
sep="/",
skippable=False,
delete_children=False,
with_full_path=False,
)
Copy nodes from from_paths
to replace to_paths
in-place.
- Creates intermediate nodes if to path is not present
- Able to skip nodes if from path is not found, defaults to False (from-nodes must be found; not skippable).
- Able to copy node only and delete children, defaults to False (nodes are copied together with children).
For paths in from_paths
and to_paths
,
- Path name can be with or without leading tree path separator symbol.
For paths in from_paths
,
- Path name can be partial path (trailing part of path) or node name.
- If
with_full_path=True
, path name must be full path. - Path name must be unique to one node.
For paths in to_paths
,
- Path name must be full path.
- Path must exist, node-to-be-replaced must be present.
Examples:
>>> from bigtree import str_to_tree, copy_and_replace_nodes_from_tree_to_tree
>>> root = str_to_tree(
... "Downloads\n"
... "├── file1.doc\n"
... "├── Pictures\n"
... "│ └── photo1.jpg\n"
... "└── Misc\n"
... " └── dummy\n"
... " └── photo2.jpg"
... )
>>> root.show()
Downloads
├── file1.doc
├── Pictures
│ └── photo1.jpg
└── Misc
└── dummy
└── photo2.jpg
>>> root_other = str_to_tree(
... "Documents\n"
... "├── Pictures2\n"
... "│ └── photo2.jpg\n"
... "└── Misc2"
... )
>>> root_other.show()
Documents
├── Pictures2
│ └── photo2.jpg
└── Misc2
>>> copy_and_replace_nodes_from_tree_to_tree(
... from_tree=root,
... to_tree=root_other,
... from_paths=["Downloads/Pictures", "Downloads/Misc"],
... to_paths=["Documents/Pictures2/photo2.jpg", "Documents/Misc2"],
... )
>>> root_other.show()
Documents
├── Pictures2
│ └── Pictures
│ └── photo1.jpg
└── Misc
└── dummy
└── photo2.jpg
In delete_children=True
case, only the node is copied without its accompanying children/descendants.
>>> root_other = str_to_tree(
... "Documents\n"
... "├── Pictures2\n"
... "│ └── photo2.jpg\n"
... "└── Misc2"
... )
>>> root_other.show()
Documents
├── Pictures2
│ └── photo2.jpg
└── Misc2
>>> copy_and_replace_nodes_from_tree_to_tree(
... from_tree=root,
... to_tree=root_other,
... from_paths=["Downloads/Pictures", "Downloads/Misc"],
... to_paths=["Documents/Pictures2/photo2.jpg", "Documents/Misc2"],
... delete_children=True,
... )
>>> root_other.show()
Documents
├── Pictures2
│ └── Pictures
└── Misc
Parameters:
Name | Type | Description | Default |
---|---|---|---|
from_tree |
Node
|
tree to copy nodes from |
required |
to_tree |
Node
|
tree to copy nodes to |
required |
from_paths |
List[str]
|
original paths to shift nodes from |
required |
to_paths |
List[str]
|
new paths to shift nodes to |
required |
sep |
str
|
path separator for input paths, applies to |
'/'
|
skippable |
bool
|
indicator to skip if from path is not found, defaults to False |
False
|
delete_children |
bool
|
indicator to copy node only without children, defaults to False |
False
|
with_full_path |
bool
|
indicator to shift/copy node with full path in |
False
|
copy_or_shift_logic
copy_or_shift_logic(
tree,
from_paths,
to_paths,
sep="/",
copy=False,
skippable=False,
overriding=False,
merge_children=False,
merge_leaves=False,
delete_children=False,
to_tree=None,
with_full_path=False,
)
Shift or copy nodes from from_paths
to to_paths
in-place.
- Creates intermediate nodes if to path is not present
- Able to copy node, defaults to False (nodes are shifted; not copied).
- Able to skip nodes if from path is not found, defaults to False (from-nodes must be found; not skippable)
- Able to override existing node if it exists, defaults to False (to-nodes must not exist; not overridden)
- Able to merge children and remove intermediate parent node, defaults to False (nodes are shifted; not merged)
- Able to merge only leaf nodes and remove all intermediate nodes, defaults to False (nodes are shifted; not merged)
- Able to shift/copy node only and delete children, defaults to False (nodes are shifted/copied together with children).
- Able to shift/copy nodes from one tree to another tree, defaults to None (shifting/copying happens within same tree)
For paths in from_paths
and to_paths
,
- Path name can be with or without leading tree path separator symbol.
For paths in from_paths
,
- Path name can be partial path (trailing part of path) or node name.
- If
with_full_path=True
, path name must be full path. - Path name must be unique to one node.
For paths in to_paths
,
- Path name must be full path.
- Can set to empty string or None to delete the path in
from_paths
, note thatcopy
must be set to False.
If merge_children=True
,
- If
to_path
is not present, it shifts/copies children offrom_path
. - If
to_path
is present, andoverriding=False
, original and new children are merged. - If
to_path
is present andoverriding=True
, it behaves like overriding and only new children are retained.
If merge_leaves=True
,
- If
to_path
is not present, it shifts/copies leaves offrom_path
. - If
to_path
is present, andoverriding=False
, original children and leaves are merged. - If
to_path
is present andoverriding=True
, it behaves like overriding and only new leaves are retained, original non-leaf nodes infrom_path
are retained.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
tree |
Node
|
tree to modify |
required |
from_paths |
List[str]
|
original paths to shift nodes from |
required |
to_paths |
List[str]
|
new paths to shift nodes to |
required |
sep |
str
|
path separator for input paths, applies to |
'/'
|
copy |
bool
|
indicator to copy node, defaults to False |
False
|
skippable |
bool
|
indicator to skip if from path is not found, defaults to False |
False
|
overriding |
bool
|
indicator to override existing to path if there is clashes, defaults to False |
False
|
merge_children |
bool
|
indicator to merge children and remove intermediate parent node, defaults to False |
False
|
merge_leaves |
bool
|
indicator to merge leaf nodes and remove intermediate parent node(s), defaults to False |
False
|
delete_children |
bool
|
indicator to shift/copy node only without children, defaults to False |
False
|
to_tree |
Node
|
tree to copy to, defaults to None |
None
|
with_full_path |
bool
|
indicator to shift/copy node with full path in |
False
|
replace_logic
replace_logic(
tree,
from_paths,
to_paths,
sep="/",
copy=False,
skippable=False,
delete_children=False,
to_tree=None,
with_full_path=False,
)
Shift or copy nodes from from_paths
to replace to_paths
in-place.
- Creates intermediate nodes if to path is not present
- Able to copy node, defaults to False (nodes are shifted; not copied).
- Able to skip nodes if from path is not found, defaults to False (from-nodes must be found; not skippable)
- Able to replace node only and delete children, defaults to False (nodes are shifted/copied together with children).
- Able to shift/copy nodes from one tree to another tree, defaults to None (shifting/copying happens within same tree)
For paths in from_paths
and to_paths
,
- Path name can be with or without leading tree path separator symbol.
For paths in from_paths
,
- Path name can be partial path (trailing part of path) or node name.
- If
with_full_path=True
, path name must be full path. - Path name must be unique to one node.
For paths in to_paths
,
- Path name must be full path.
- Path must exist, node-to-be-replaced must be present.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
tree |
Node
|
tree to modify |
required |
from_paths |
List[str]
|
original paths to shift nodes from |
required |
to_paths |
List[str]
|
new paths to shift nodes to |
required |
sep |
str
|
path separator for input paths, applies to |
'/'
|
copy |
bool
|
indicator to copy node, defaults to False |
False
|
skippable |
bool
|
indicator to skip if from path is not found, defaults to False |
False
|
delete_children |
bool
|
indicator to shift/copy node only without children, defaults to False |
False
|
to_tree |
Node
|
tree to copy to, defaults to None |
None
|
with_full_path |
bool
|
indicator to shift/copy node with full path in |
False
|