Consistency between DataTree methods and pathlib.PurePath methods
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 4.2k
- Forks
- 1.4k
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 14
Description
What is your issue?
Copied from https://github.com/xarray-contrib/datatree/issues/283
@eschalkargans suggested in #281 that the API of DataTree objects could more closely follow that of pathlib.PurePath objects. I think this aligning of APIs/nomenclature is a good idea. In general think it's conceptually useful to think of a DataTree object as if it were an instance of pathlib.PurePosixPath (even though the actual implementation should not work like that).
There are various methods we might want to add/change to make them more compatible:
Inspired by pathlib.PurePath:
-
DataTree.matchshould be renamed toDataTree.glob - Add a new method
DataTree.matchthat returns a boolean likePurePath.matchdoes -
DataTree.lineageshould be renamed to.parents -
Add an(this is deprecated in.is_relative_tomethodpathlib) - A new
.joinpathmethod could be useful -
DataTree.relative_toshould possibly have awalk_upmethod (see https://github.com/xarray-contrib/datatree/issues/258) - A new
.with_namemethod might be useful - A new
.with_segmentsmethod might be useful
Inspired by pathlib.Path (i.e. concrete paths):
- A new
DataTree.walkmethod might be a better way to expose the logic in iterators.py - A new
.renamemethod might be useful - A new
.replacemethod might be useful - A new
.rglobmethod (though having this and.globseems overkill)
Several of these might be useful abstractions internally, especially .joinpath, .walk, and .replace.
EDIT: Let's also document this similarity:
- Add section to documentation explicitly pointing out this alignment of APIs (#287)
- Reorganise
api.rstto have a sectionPath-like methods
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the existing DataTree methods and the logic referenced in datatree/iterators.py, then compare their APIs with pathlib.PurePath. Review api.rst and the linked issues and pull request before choosing a narrowly scoped subset; done should mean the selected API changes and the requested documentation alignment are clearly agreed and complete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend-api-design, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100