gh-101100: Fix os.statvfs and os.uname references#151301
Conversation
Restructure descriptive paragraphs to class definitions copying across descriptions. Add constants from statvfs to os as data directives. Expand the `os.uname` section slightly with a see also which matches the one at the beginning of os.rst added in pythongh-56535 (commit a83cdaa). --- The statvfs_result members had no definition before and I opted not to add ones ere. The C code in `posixmodule.c` just forwards them directly so I don't think a description would be more precise than what is in the man page.
cmaloney
requested review from
AA-Turner,
StanFromIreland and
hugovk
as code owners
bedevere-app
Bot
added
awaiting review
docs
Documentation build overview
23 files changed ·
|
| The return value is a :class:`uname_result` object whose attributes | ||
| correspond to the members described in :manpage:`uname(2)`. |
There was a problem hiding this comment.
| The return value is a :class:`uname_result` object whose attributes | |
| correspond to the members described in :manpage:`uname(2)`. | |
| The return value is a :class:`uname_result` object. |
I think the note should be with the attributes ("These attributes correspond to the ...").
There was a problem hiding this comment.
Misinterpreted this my first read, moved the manpage reference to the uname_result section
Co-authored-by: Stan Ulbrych <stan@python.org>
serhiy-storchaka
left a comment
serhiy-storchaka
left a comment
There was a problem hiding this comment.
In general good, but I have other suggestions which you can implement here or leave to other PRs.
9 data classes are defined in the os module: DirEntry, sched_param, stat_result, statvfs_result, statx_result, terminal_size, times_result, uname_result, and waitid_result. 4 of them are not explicitly documented: stat_result, times_result, uname_result, and waitid_result.
Could you please document times_result and waitid_result too? Or you prefer to leave this to other PR?
Please check that all 9 classes use similar style (except that DirEntry and statx_result are not tuples).
And you can turn other mentions of uname_result (in NEWS entries) to references.
|
|
||
| .. attribute:: f_flag | ||
|
|
||
| Bit-mask of mount flags. The following flags are defined: |
There was a problem hiding this comment.
Maybe just refer to them as ``ST_*`` flags?
| Filesystem statistics returned by :func:`os.statvfs` and :func:`os.fstatvfs`. | ||
| See :manpage:`statvfs(3)` for the meaning of each member. | ||
|
|
||
| .. attribute:: f_bsize |
There was a problem hiding this comment.
Maybe add short descriptions?
| .. versionadded:: 3.7 | ||
|
|
||
|
|
||
| .. data:: ST_RDONLY |
There was a problem hiding this comment.
Before these flags, add that the following flags are used in statvfs_result.f_flag.
|
|
||
| .. class:: statvfs_result | ||
|
|
||
| Filesystem statistics returned by :func:`os.statvfs` and :func:`os.fstatvfs`. |
There was a problem hiding this comment.
It would be nice to add to all other data classes where they are used.
3 participants
Restructure descriptive paragraphs to class definitions copying across descriptions. Add constants from
statvfstoosas data directives.Expand the
os.unamesection slightly with a see also which matches the one at the beginning of os.rst added in gh-56535 commit a83cdaa.This gets
os.rstout of nitignore.The statvfs_result members had no definition before and I opted not to add ones here. The C code in
posixmodule.cjust forwards them directly so I don't think a description would be more precise than what is in the man page.