Deprecate `pathlib.Path.lstat()` and `lchmod()`

These methods have non-obvious names, unless you already know that “l” stands for “link”. They can be readily replaced with stat(follow_symlinks=False) and chmod(follow_symlinks=False), which are more explicit and conform better to pathlib’s other APIs. IMHO the pathlib interface would be better off without them.

OTOH it may be too late to deprecate + remove in the name of a tidier interface. lstat() appears to be widely used, though lchmod() is fairly niche: it’s not supported on Windows or Linux. Both methods are part of PEP 428, though the follow_symlinks argument didn’t exist back then.

Thoughts? I’ve been considering this one for a while and haven’t been able to make my mind up. Thanks!


Could their implementation just be replaced with the respective method calls you mentioned and the documentation updated to state to prefer using those method calls directly?

Seems better than breaking packages for the sake of tidiness.

1 Like

This is a unix system call that will work on all but Windows.

Anyone that is a unix dev will be familiar with the l prefix i expect.

Too much existing code will be using these API calls to be able to remove i would think.

1 Like

It’s not supported on Linux, see use of lchmod

Aha it is on freebsd kernel not linux. I read a unbuntu page and assumed linux.

UNIX dev: yes, familiar. While I’m only just starting to dip my toe into
pathlib (ah, the siren call of Path.stem and Path.suffix) I
certainly use the “l” prefixed os.* calls when needed. To be fair,
mostly lstat():

 CSS[~/hg/css(hg:default)]fleet2*> agf -c lstat cs/

I think anyone using the “l”-prefixed methods will have some thought to
portability constraints. And I’d certainly expect to use Path.lstat()
in like circumstances.

Cameron Simpson

1 Like

Are these methods a maintenance burden?

Does Python have a word for “discouraged but not deprecated”, i.e., its use is not recommended, it is relegated to a footnote in the documentation, its docstring says you should not use it, but no plans are made to remove it? I think it would be better than imposing code churn.

There’s no lchmod() function in POSIX. It does specify fchmodat() with the flag AT_SYMLINK_NOFOLLOW, but this is qualified as follows:

Some implementations might allow changing the mode of symbolic links. This is not supported by the interfaces in the POSIX specification. Systems with such support provide an interface named lchmod(). To support such implementations fchmodat() has a flag parameter.

On Linux, the flag AT_SYMLINK_NOFOLLOW is “not currently implemented” for fchmodat(). POSIX assumes that the permissions of a symlink are ignored, but apparently on BSD and macOS, one needs read permission on the symlink itself in order to follow it.

Thanks for your feedback, all. It sounds like lstat() is important to retain.

Digging around in and the CPython source code, I do see lchmod() used in a few places. Upon reflection it seems like needless churn to deprecate/remove it.