Clarify os.stat_result.st_mode as int and mention stat earlier in os.stat_result

Documentation

Issue 1: Clarification that st_mode is an int while octal might be expected

Perhaps the description for st_mode here could use a .. note:: reminding the user that it is an int and a conversion to octal might be needed to see a familiar result.

When checking for file permission bits with os.stat() recently, I noticed the value of the st_mode member of the result was not what I expected - running the program on Unix I expected a familiar value such as 755 to appear at the end of the number. The number looked nothing like that and a quick web search told me I'd need to see that same int in octal notation to see the values I expected. This makes perfect sense after I've learned about it, but I figured maybe a note in the member's description could save someone else a web search.

Issue 2 (related): Moving the reference to the stat module earlier in os.stat_result

I'm also aware now that most such operations should involve the stat module instead of manual parsing of the values. The module is only mentioned at the end of the list of object's members (after st_reparse_tag), while for functions like chflags it is mentioned in the function's description. Could it be moved to the description of os.stat_result? If a user comes looking for a specific member of the os.stat_result object, they are most likely done with reading the member's list once they find it and therefore are unlikely to see the current mention of the module.

Thanks for looking into this!

Linked PRs

• gh-138532

Bắt đầu từ tài liệu về os.stat_result.st_mode được liên kết trong issue, sau đó xem lại danh sách member xung quanh của os.stat_result và tài liệu tham chiếu hiện tại của stat-module. Công việc được xem là hoàn tất khi đã ghi rõ rằng st_mode là một int mà các bit quyền quen thuộc của nó có thể cần được biểu diễn ở dạng bát phân, đồng thời chuyển phần hướng dẫn về stat-module lên trước; hãy kiểm tra PR được liên kết gh-138532 trước khi bắt đầu.