feat: add refile heading

org_rw/org_rw.py

@@ -329,7 +329,7 @@ class Headline:
         closed: Optional[Time] = None,
     ):
         self.start_line = start_line
-        self.depth = depth
+        self._depth = depth
         self.orig = orig
         self.properties = properties
         self.keywords = keywords
@@ -762,6 +762,16 @@ class Headline:
             pass
         self._state = new_state
 
+    @property
+    def depth(self):
+        return self._depth
+
+    @depth.setter
+    def depth(self, value):
+        self._depth = value
+        for child in self.children:
+            child.depth = value + 1
+
     @property
     def clock(self):
         times = []
@@ -1066,6 +1076,38 @@ class Headline:
         self.children.append(headline)
         return headline
 
+    def refile(
+        self, destination: Union["Headline", OrgDoc], top: bool = False
+    ) -> Union["Headline", OrgDoc]:
+        """Refile this headline to a new destination.
+
+        Args:
+            destination: The headline to which this headline will be moved
+            top: Whether to append to bottom or insert at top of destination's children
+
+        Returns:
+            The destination headline
+        """
+        # Remove from the parent
+        if self.parent:
+            if isinstance(self.parent, Headline):
+                self.parent.children.remove(self)
+            else:
+                self.parent.headlines.remove(self)
+
+        # Add ourselves to the destination
+        if top:
+            destination.children.insert(0, self)
+        else:
+            destination.children.append(self)
+
+        # Adjust the depth
+        self.depth = destination.depth + 1
+
+        # Adjust our parent
+        self.parent = destination
+        return destination
+
 
 RawLine = collections.namedtuple("RawLine", ("linenum", "line"))
 Keyword = collections.namedtuple(
@@ -2366,6 +2408,24 @@ class OrgDoc:
     def shallow_tags(self) -> list[str]:
         return self.tags
 
+    @property
+    def depth(self):
+        """
+        Attribute to be compatible with the signature of the Headlines.
+
+        Useful when doing operations across the headline hierarchy
+        """
+        return 0
+
+    @property
+    def children(self):
+        """
+        Attribute to be compatible with the signature of the Headlines.
+
+        Useful when doing operations across the headline hierarchy
+        """
+        return self.headlines
+
     ## Querying
     def get_links(self):
         for headline in self.headlines: