Maximize compatibility with `pathlib.Path`

[5j9]

This project does aspire to align with pathlib where possible, so it should probably do the same (and probably implement iterdir at the same time, if it's not present already).

Originally posted by @jaraco in https://github.com/jaraco/path/issues/212#issuecomment-1623882608

Here some other methods that are worth considering:

set(vars(pathlib.Path)) - set(vars(path.Path)) 
Out[9]: 
{'__slots__',
 '_make_child_relpath',
 '_scandir',
 'absolute',
 'cwd',
 'group',
 'hardlink_to',
 'home',
 'is_block_device',
 'is_char_device',
 'is_dir',
 'is_fifo',
 'is_file',
 'is_mount',
 'is_socket',
 'is_symlink',
 'iterdir',
 'lchmod',
 'link_to',
 'replace',
 'resolve',
 'rglob',
 'symlink_to'}

• [x] absolute
• [x] cwd
• [x] group
• [x] hardlink_to
• [x] home
• [ ] is_block_device
• [ ] is_char_device
• [x] is_dir
• [ ] is_fifo
• [x] is_file
• [ ] is_mount
• [ ] is_socket
• [ ] is_symlink
• [x] iterdir
• [ ] lchmod
• [x] ~link_to~
• [ ] owner
• [x] replace
• [ ] resolve
• [ ] rglob
• [x] suffix
• [x] symlink_to
• [x] with_stem
• [x] with_name

[jaraco]

Nice. Sounds good. I welcome the contributions. In cases where the functionality is duplicative and the pathlib syntax is inarguably as good, let's also deprecate any local pecularities.

[jaraco]

In #218, I'm working on adding support for .suffix, .with_stem, and .with_name.

[jaraco]

Looks like link_to was replaced by hardlink_to and removed.

[jaraco]

I'm looking at symlink_to and hardlink_to, and it's interesting. pathlib's implementation is very different, switching the order of arguments. It's not obvious why the order of arguments was switched (from os.path equivalents) and in fact, the order was only switched in symlink_to originally and later in hardlink_to. I'm not sure yet if the other ones should be deprecated. I'm leaning toward keeping them for now. Another difference is that pathlib doesn't return anything for symlink_to or hardlink_to, but the path implementation does. It seems to me that returning something would be useful, but I'm yet unsure what is best to return. I'll probably start with not returning anything at all (matching the pathlib behavior) unless there's a case to be made for a returned value.

[jaraco]

I observe that Path.owner and pathlib.Path.owner() are incompatible. It won't be possible to align those without first deprecating .owner.

[jaraco]

I took at replace. This case is a more difficult one, because path.Path is a str subclass, so already has a replace that's different from how pathlib.Path.replace works.

I'm thinking maybe this library can support both:

• If one parameter is passed, follow the pathlib.Path logic (rename the file).
• If two parameters are passed, perform a str.replace, but wrap in a "next" Path class.