Specify type of exception returned by os.remove()

[Rikuoja]

Documentation

Currently, the os.remove() documentation specifies that OSError is returned when trying to remove a directory:

   Remove (delete) the file *path*.  If *path* is a directory, an
   :exc:`OSError` is raised.  Use :func:`rmdir` to remove directories.
   If the file does not exist, a :exc:`FileNotFoundError` is raised.

However, actually a PermissionError: [Errno 1] Operation not permitted (subclass of OsError) is returned instead.

While this is technically correct, it causes excepting PermissionError to silently fail unexpectedly in code that expects a generic OSError when meeting a directory.

I would suggest the documentation should read

If *path* is a directory, a :exc:`PermissionError` is raised.

Linked PRs

• gh-145227: Clarify os.remove() directory exception is platform-dependent #145265

[gvanrossum]

@Rikuoja Can you sketch the scenario where this causes user code to fail?

[mohsinm-dev]

@Rikuoja Can you sketch the scenario where this causes user code to fail?

A concrete failure case is cross-platform code that treats "path is a directory" by catching IsADirectoryError (or checking errno == EISDIR) after os.remove().

Example:

try:
    os.remove(path)
except IsADirectoryError:
    os.rmdir(path)

This works where unlink(directory) returns EISDIR, but fails on platforms (e.g., macOS) where unlink(directory) returns EPERM and Python raises PermissionError instead.

So the issue is not that OSError is wrong, but that the specific subclass for this case is platform-dependent.

[gvanrossum]

I don't see how the documentation the OP references has a bearing on that issue. What am I missing?

[mohsinm-dev]

You’re actually correct because the os.remove docs line itself is not the source of failure. The cross-platform failure is when code expects a specific subclass (IsADirectoryError / EISDIR) for os.remove(directory). On macOS, this is often PermissionError (EPERM) instead. So the doc issue is really about clarifying subclass variability, not replacing OSError with PermissionError.

[gvanrossum]

Cool, that's what I thought. Can you create a PR? I'm not sure how much we can expect to hear from the OP (@Rikuoja).

[Rikuoja]

Thank you, the platform-dependency of the error explains my situation. In this case, of course, maybe the relevant subclasses could be listed per platform?

My issue arised exactly when I was catching a PermissionError running tests on Linux pipeline, but locally my code would catch a PermissionError caused by os.remove() on directory on my Mac OS, which was unintended, as I did not expect the error to be caused by a directory:

try:
  os.remove(path)
except PermissionError:
  # code to handle missing file permissions

[picnixz]

There are more than just a PermissionError that can be raised by os.remove as it depends on unlink and unlinkat. See #145265 (review). I'm therefore closing this.