> I personally think that offering mere wrappers around syscalls doesn't
> make much sense: Python is a very-high level language, and so should
> its library be.

I very much agree.  I suggest anyone who thinks the os module is a thin
veneer over syscalls needs to examine the Win32 implementation of os.stat.


> - *at() syscalls are not portable: if it's not supported, what's
> remove(path='toto', dir_fd=fd) supposed to do? Throw an exception?

NotImplementedError.


> - it's not clear how one's supposed to check that the functions are
> available: right now, one can do [a hasattr check]
> How would that work with dir_fd argument?

try/except.  If someone (maybe even me) championed PEP 362 (Function
Signature Object, introspection on functions) then we could LBYL,
but that's only a theory right now.


>   stat(path, *, followlinks=True, dirfd=None)
> is backwards, it should be
>   stat(dirfd, path, *, followlinks=True)
> since, `path` is relative to `dirfd`.

You could hypothetically rearrange all the arguments
at the call site by using 100% keyword arguments:
  stat(dir_fd=whatever, path=thingy, follow_symlinks=True)

I admit it's unlikely anyone will bother.


> Actually, the proper way to do this would be to use overloading, but
> Python doesn't support it (and even if it did, I think overloading
> would probably be a bad idea anyway).

Speaking *purely hypothetically*, we could actually overload it.  It'd
be at runtime, as what in Python is not.  Since stat is implemented in
C it would look like:

  if (-1 == PyArg_ParseTupleAndKeyword(arguments-with-dir_fd)) {
    PyErr_Clear();
    if (-1 == PyArg_ParseTupleAndKeyword(arguments-without-dir_fd)) {
      /* etc. */

However, Python doesn't have overloading because we shouldn't do it.
I'm against overloading here, for the same reason that I'm against
argument polymorphism (fold faccess into access by allowing the first
argument to be either an int or a string).  This sort of polymorphism
leads to lack of clarity and awkward problems.


> I'll probably have to think some time to understand what the hell is
> the last dir_fd argument. Renaming, removing a file is simple and
> direct, so should the API be.

I counter with TOOWWTDI.  There are currently four chmod functions in
os: chmod, fchmod, fchmodat, and lchmod.  If you want to change the
mode of a file, which do you use?

You may also face the problem that you don't want chmod to follow
symbolic links, yet you've never heard of lchmod.

I feel the sad truth of the situation is, it is desirable that Python
support all this functionality, but there is no simple and
obviously-right way to do so.  So which alternative is less undesirable:
a combinatoric explosion of functions, or a combinatoric explosion of
arguments to existing functions?  I suggest the latter is less
undesirable because it is marginally clearer: at least you always
know which function to call, and the documentation on how to use it
in its multiple forms will be all in one place.

(Though this would not help the hapless programmer who suspected maybe
there *was* a second function somewhere, searching forever for a
function that doesn't actually exist.)

Also, I suggest that the programmer reading the documentation for os
would see the same parameters (dir_fd, follow_symlinks) as part of many
different functions and would quickly learn their semantics.


> - finally, although useful, the *at() family is a really poor and
> confusing API, which will likely be used by less than 0.1% of the
> overall Python users. Complicating the whole posix module API just
> to shave off a few functions is IMHO a bad idea.

I understand your critique.  In defense of the proposal, I will say that
when Guido asked me to connect with the storchaka and try to shepherd
the process, he specifically cited the *at() functions as examples of
new functions that could be obviated by folding the functionality
into the existing APIs.

Not that I claim this gives me carte blanche to check an implementation
in.  Simply that I believe Guido liked the idea in the abstract.  It
could be that he wouldn't like the result, or that my proposal (which
purposely carried out the idea to its logical extreme) goes too far.

In the absence of a BDFL ruling on the proposal, I think I should
produce a patch implementing the full proposal, then bring it up in
c.l.p-d and get a community vote.  How's that sound?