Documentation is self-contradictory regarding Windows-supported file permissions

[cemysce]

Documentation

One the one hand, the os.chmod documentation says that Windows only supports stat.S_IWRITE and stat.S_IREAD.

But on the other hand, the stat module documentation says that both of those (S_IWRITE and S_IREAD) are Unix V7 synonyms for S_IWUSR and S_IRUSR (and in fact comments in the stat code say the same thing).

That's confusing. One piece of documentation says Windows supports them (in fact, only them) and another piece of documentation says they're for Unix (i.e. not Windows).

The naming "IWUSR" and "IRUSR" implies the typical Unix permission model, which does not apply on Windows, so it makes sense that Windows code should ideally not use S_IWUSR or S_IRUSR (even though the code would happen to work because the values are identical to S_IWRITE and S_IREAD).

Therefore, I think the fix should be to replace the "Unix V7 synonym for ..." statements with "Unix V7 synonym for ..., also used on Windows" in both of the following:

• comments in the stat module code
• statements in the stat documentation

Linked PRs

• gh-101675: Fix os Windows-supported file permissions #101694

[eryksun]

Back in the 1980s, Microsoft decided to support Unix chmod() in the C runtime on MS-DOS by mapping S_IWRITE inversely to the readonly file attribute and by implementing S_IREAD as an always-enabled permission. For the stat*() functions, the C runtime also sets S_IEXEC for filenames that have an extension in the set ".exe", ".com", ".bat", and ".cmd". Python's implementations of os.chmod() and os.stat() copy the C runtime behavior.

Note that none of these has anything to do with actual file permissions. The readonly file attribute on Windows is no more a file permission than is the immutable file attribute on Linux, BSD, and macOS.

[cemysce]

Thanks for the background information @eryksun! I'm aware the readonly attribute is mostly informational on Windows and obeyed only on a voluntary basis. The stat documentation should explain what you said — it should not be implicitly encouraging use of S_IWUSR and S_IRUSR on Windows by virtue of stating that S_IWRITE and S_IREAD are for Unix while neglecting to mention that they're also appropriate for use on Windows. And the comments in the stat code should similarly be updated.