Merge pull request #107 from kayjan/v0.14.0

V0.14.0

Author: kayjan

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0] - 2023-10-18
+### Added
+- Tree Modifier: Shift nodes with replacement of to-node with `shift_and_replace_nodes`.
+- Tree Modifier: Copy nodes from tree to tree with replacement of to-node with `copy_and_replace_nodes_from_tree_to_tree`.
+- Tree Modifier: Any permutation of configuration with replacement of to-node with `replace_logic`.
+- Tree Modifier: Add relevant test cases and documentations accordingly.
+
 ## [0.13.3] - 2023-10-17
 ### Added
 - Misc: Add automatic release notes with content into GitHub workflow.
@@ -354,6 +361,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Utility Iterator: Tree traversal methods.
 - Workflow To Do App: Tree use case with to-do list implementation.
 
+[0.14.0]: https://github.com/kayjan/bigtree/compare/0.13.3...0.14.0
 [0.13.3]: https://github.com/kayjan/bigtree/compare/0.13.2...0.13.3
 [0.13.2]: https://github.com/kayjan/bigtree/compare/0.13.1...0.13.2
 [0.13.1]: https://github.com/kayjan/bigtree/compare/0.13.0...0.13.1

README.md

@@ -49,6 +49,8 @@ For **Tree** implementation, there are 9 main components.
    1. Shift nodes from location to destination
    2. Copy nodes from location to destination
    3. Copy nodes from one tree to another
+   4. Shift and replace nodes from location to destination
+   5. Copy and replace nodes from one tree to another
 5. [**Tree Search**](https://bigtree.readthedocs.io/en/latest/bigtree/tree/search.html)
    1. Find multiple nodes based on name, partial path, relative path, attribute value, user-defined condition
    2. Find single nodes based on name, partial path, relative path, full path, attribute value, user-defined condition

bigtree/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.13.3"
+__version__ = "0.14.0"
 
 from bigtree.binarytree.construct import list_to_binarytree
 from bigtree.dag.construct import dataframe_to_dag, dict_to_dag, list_to_dag

docs/source/_static/custom.css

@@ -32,6 +32,7 @@ blockquote p {
 }
 ol {
     padding-left: 40px;
+    margin-bottom: 0px;
 }
 ol p, li p {
     margin-bottom: 0;

docs/source/bigtree/tree/modify.rst

@@ -1,21 +1,93 @@
 |:memo:| Modify
 ===================
 
-Shift or copy nodes within same tree or between two trees using
-`from_paths` (list of paths) and `to_paths` (list of paths).
+There are two types of modification available,
 
-There are several configurations available for more customization
+  1. **Non-replacing scenario**: Shift or copy nodes within same tree or between two trees using `from_paths` (list of paths) and `to_paths` (list of paths).
+  2. **Replacing scenario**: Shift or copy nodes within same tree or between two trees *while replacing the to-node* using `from_paths` (list of paths) and `to_paths` (list of paths).
 
-- `skippable`: Skip shifting/copying of nodes if from_path cannot be found, defaults to False (from node must be found)
-- `overriding`: Override existing node if it exists, defaults to False (to node must not exist)
-- `merge_children`: Merge children and remove intermediate parent node, defaults to False (children are not merged)
-- `merge_leaves`: Merge leaves and remove all intermediate nodes, defaults to False (leaves are not merged)
-- `delete_children`: Shift/copy node only and delete its children, defaults to False (nodes are shifted/copied together with children)
+In **non-replacing scenario**, there are several configurations available for customization.
 
-.. note:: `merge_children` and `merge_leaves` cannot be simultaneously set to `True`
+.. list-table:: Available Configurations for Customization
+   :widths: 20 40 40
+   :header-rows: 1
+
+   * - 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.
+
+.. list-table:: Tree Modification Methods
+   :widths: 10 20 10 20
+   :header-rows: 1
+
+   * - 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
 ----------------------------------