Improve the frozenset.is(sub|super)set docstrings

[JDoepro-ctrl]

Documentation

RE: Documentation provided by built-in function help()

While reviewing built-in methods in detail I made note of:

• "help(frozenset)" issubset and issuperset methods both return bool type

Other comments that were not issues

See #129622 (comment).

• "help(slice)" third parameter typo
• "help(range)" third parameter typo
• "help(float)" quizzical hex method example
• "help(bool)" is bit_length method also for absolute value of self?
• "help(bool)" is_integer appears duck-like compatible with int (TypeError with float)
• "help(bool)" from_bytes appears to return a bool from byte array

Regards,
'EntryLevelJobSeeker'

Linked PRs

• gh-129622: Clarify the set.is{sub,super}set docstrings #129637

[AA-Turner]

Hi, this isn't a usable issue. Please provide sufficient context in bug reports, and consider first opening a discussion on Discourse.

A

[terryjreedy]

The comments are clearer if one tries the given commands. My response for each argument.

slice and range: no typo. OP likely misunderstands that [, step] means 'optional.

float: the help response incorporates docstrings; OP likely does not understand p in float 'hex'. Must read doc to understand. Docstrings are reminders, not complete documentation.

frozenset.issubset: "Report whether another set contains this set." .issuperset: has similar docstring. These are very unusual docstrings. All others for frozenset say "Return ...", as is standard. OP is suggesting new docstring, something like "Return True if self is a subset of other, else False. Similarly for issuperset. I agree.

bool.bit_length: Docstring, inherited from 'int' uses 37 as an example, which is not applicable to bool. (Nor is question about absolute value. But (-37).bit_length() is 6, as for 37.) A customized docstring for bool.bit_length would require a customized function which seems a pain. Users should notice that bool subclasses int and then ignore example.

bool.is_integer: Inherited int docstring is "Returns True. Exists for duck type compatibility with float.is_integer." The second sentence makes more sense as an explanation of why ints have an 'is_integer'. float.is_integer works; (1.0).is_integer() returns True and (1.1).is_integer is False. No type error.

bool.from_bytes: this is not int.from_bytes. The docstring, which likely copies the int.from_bytes docstring, says "Return the integer ...", which is not wrong in that bools, like ints, are integers. It is proper that the subclass return a subclass instance.

To me (EDIT), the only valid issue is the frozenset docstrings. A new title might be "Improve the frozenset.is(sub|super)set docstrings"

[JDoepro-ctrl]

help(slice) and help(range) should be:
"slice(start, stop, step)". Maybe your system accepts the square bracket syntax. Mine does not.

help(float): Thanks. As a beginner my syntax is more like "float.hex(3.14)" not "3.14.hex()"

help(frozenset): Thank you for understanding.

help(bool): bool.bit_length: I will learn to ignore examples. I do not expect customization for a built-in child class. However it is good to know where the Boolean methods are inconsistent. When I write a Boolean 'test' for a collection which is a pain, I am well-informed that bool methods do not count the way I expect, specifically by sometimes accepting non-zero-or-one values. This is a critical observation of bool methods.

help(bool): bool.is_integer: The built-in bool.is_integer may only accept 0 and 1 equivalents. You discuss float.is_integer. I noticed that some bool-methods accept values other than 0 and 1.

help(bool): bool.from_bytes: The built-in method appeared to only accept inputs with byte-array representation of a binary value (as I recall).

[skirpichev]

"slice(start, stop, step)". Maybe your system accepts the square bracket syntax.

As for range issue, #125897, I think we should use correct Python syntax here to describe function signatures.

[hridyasadanand]

Hi! I'm Hridya, a first-year BTech student eager to contribute to CPython's documentation. I'd like to work on this issue as part of my GSoC 2025 preparation. Could you please assign it to me?

[picnixz]

The issue can be considered stalled as per #129637 (comment) so there is nothing else to do for that one. You can however try to pick up other easy-labeled issues that do not have an associated open PR.

[hridyasadanand]

Hi! I’m Hridya, a first-year BTech student learning Python. I’d love to work on this issue as part of my GSoC preparation. Can I take it?