os.remove is documented to raise IsADirectoryError but macOS raises PermissionError

[chrisburr]

Documentation

In the documentation for os.remove it states:

Remove (delete) the file path. If path is a directory, an IsADirectoryError is raised. Use rmdir() to remove directories. If the file does not exist, a FileNotFoundError is raised.

This is the case on Linux:

$ python -c 'import os, tempfile; os.remove(tempfile.mkdtemp())'
Traceback (most recent call last):
  File "<string>", line 1, in <module>
IsADirectoryError: [Errno 21] Is a directory: '/tmp/tmphxrd1p6n'

However on macOS this results in a PermissionError:

$ python3 -c 'import os, tempfile; os.remove(tempfile.mkdtemp())'
Traceback (most recent call last):
  File "<string>", line 1, in <module>
PermissionError: [Errno 1] Operation not permitted: '/var/folders/1g/q2y74s696ng0v_cmb9sv7qgr0000gn/T/tmpawxhz8wm'

Linked PRs

• GH-95815: Document less specific error for os.remove #99571
• [3.10] GH-95815: Document less specific error for os.remove (GH-99571) #99639
• [3.11] GH-95815: Document less specific error for os.remove (GH-99571) #99641

[eryksun]

In Windows, calling os.unlink() or os.remove() on a directory also raises PermissionError. It can be clarified by checking the last status value from the internal NT API. Unfortunately, Microsoft doesn't document either the function to return this value or when it's valid. For example:

import ctypes
import os
import tempfile

RtlGetLastNtStatus = ctypes.WinDLL('ntdll').RtlGetLastNtStatus
STATUS_FILE_IS_A_DIRECTORY = ctypes.c_long(0xC000_00BA).value

def test():
    path = tempfile.mkdtemp()
    try:
        os.remove(path)
    except PermissionError as e:
        if RtlGetLastNtStatus() != STATUS_FILE_IS_A_DIRECTORY:
            raise
        raise IsADirectoryError(errno.EISDIR,
                                os.strerror(errno.EISDIR),
                                e.filename,
                                e.winerror)

>>> try: test()
... except OSError as ex: e = ex
...
>>> e
IsADirectoryError(13, 'Is a directory')
>>> e.__context__
PermissionError(13, 'Access is denied')

>>> os.rmdir(e.filename)

[ronaldoussoren]

The behaviour on macOS matches the documentation of the underlying os, the manpage for unlink(2) and unlinkat(2) mention:

     [EPERM]            The named file is a directory and the effective user ID of the process is not the super-user.

IMHO we shouldn't try to work around this, but should mention this in the documentation.

[ronaldoussoren]

The current text was introduced in #14262, replacing OSError in the text. In this case the new more specific exception is incorrect.

[ronaldoussoren]

I've added a PR that reverts the text back to mentioning OSError instead of IsADirectoryError, but I'm not convinced yet that this is the best way to change the documentation. An alternative is to document both exceptions.

I'm -1 on changing the implementation to raise the documented exception, that's not possible to do without a race condition because there are other reasons for getting EPERM (e.g. the folder in which the to-be-removed object is located is not writable).