Add DataTree.move to move a node to another place

[Armavica]

• Closes Is it possible to move a node drectly? xarray-contrib/datatree#210
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

[TomNicholas]

Thanks so much @Armavica !

[TomNicholas]

Suggested change

	DataTree
	DataTree
	Copied subtree with the node moved.

[TomNicholas]

I think this argument should be renamed, though I'm not sure what to. Perhaps create_intermediates?

[Armavica]

I am not sure either, I took inspiration from pathlib: https://docs.python.org/3/library/pathlib.html#pathlib.Path.mkdir
Happy to change to anything.

[TomNicholas]

Ah I see. Taking inspiration from pathlib was a good idea. But I don't think it's a great name in this case...

The exists_ok arg in pathlib.Path.mkdir is also potentially relevant - the user might want to avoid replacing the subtree already at that path.

[Armavica]

Ah, good point. I will add an exists_ok argument for now, until we settle on names for these arguments.

[TomNicholas]

There's another possible way of writing this method: dt.move(destination) where it's assumed that the origin is the current node, and the returned result is the root of the new tree.

But I think your way is probably the less surprising of the two.

[Armavica]

I see. Should we do both, or would that be too confusing?

[TomNicholas]

I think your way is fine! I just wanted to comment to point this out for posterity :)

[Armavica]

There are actually several non-trivial design questions to answer for this feature.
The main one I see is the semantics of the origin and destination paths. What do we want to happen when we do dt.move("/to_move", "/other/path") for the following DataTree:

dt = DataTree.from_dict({"/to_move/child": None, "other/path/here": None})

<xarray.DataTree>
Group: /
├── Group: /to_move
│   └── Group: /to_move/child
└── Group: /other
    └── Group: /other/path
        └── Group: /other/path/here

Option 1: destination is the new name of origin

dt.move("/to_move", "/other/path")

<xarray.DataTree>
Group: /
└── Group: /other
    └── Group: /other/path
        └── Group: /other/path/child

With this option, if destination existed before the move, it is overwritten by origin.

Option 2: destination is the new root of origin

dt.move("/to_move", "/other/path")

<xarray.DataTree>
Group: /
└── Group: /other
    └── Group: /other/path
        ├── Group: /other/path/here
        └── Group: /other/path/to_move
            └── Group: /other/path/to_move/child

With this option, if destination existed before the move, it is not overwritten, but one of its children might if it has the same name as origin

Option 3: if destination exists it is the new root, otherwise it is the new name

This seems closer to the unix mv semantics.