documentation for os.getgrouplist potentially misleading

[woodfighter]

BPO	40376
Nosy	@woodfighter
PRs	gh-84556: slightly improved the wording for os.getgrouplist #19702

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-04-24.11:03:53.995>
labels = ['type-feature', 'docs']
title = 'documentation for os.getgrouplist potentially misleading'
updated_at = <Date 2020-04-24.12:00:32.174>
user = 'https://github.com/woodfighter'

bugs.python.org fields:

activity = <Date 2020-04-24.12:00:32.174>
actor = 'woodfighter'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-04-24.11:03:53.995>
creator = 'woodfighter'
dependencies = []
files = []
hgrepos = []
issue_num = 40376
keywords = ['patch']
message_count = 1.0
messages = ['367187']
nosy_count = 2.0
nosy_names = ['docs@python', 'woodfighter']
pr_nums = ['19702']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue40376'
versions = []

[woodfighter]

https://docs.python.org/3/library/os.html#os.getgrouplist states „Return list of group ids that user belongs to. If group is not in the list, it is included; typically, group is specified as the group ID field from the password record for user.“, but the function is at least on Linux a wrapper for getgrouplist from the C standard library, which lists only the membership in groups in the group-database. Users can be members of groups without it being declared in the group database, this is often the case with the default group of the user which is only declared in the passwd database.

e.g.
/etc/passwd: woodfighter:x:1000:1000:,,,:/home/woodfighter:/bin/bash
/etc/group: woodfighter:x:1000:

os.getgrouplist("woodfighter",65534) then doesn't contain group id 1000.

The documentation tries to steer a developer in the right direction with the second sentence but fails to state, that the list will be possibly incomplete otherwise. I would add something like „, because that group ID will otherwise be potentially omitted.“ before the last period.