Docs: Code example locations in stdtypes

[aeros]

BPO	37618
Nosy	@kmoza, @Mariatta, @aeros

^{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: ```python assignee = None closed_at = None created_at = labels = ['3.7', '3.8', '3.9', 'docs'] title = 'Docs: Code example locations in stdtypes' updated_at = user = 'https://github.com/aeros' ``` bugs.python.org fields: ```python activity = actor = 'aeros' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = creator = 'aeros' dependencies = [] files = [] hgrepos = [] issue_num = 37618 keywords = [] message_count = 4.0 messages = ['348104', '348106', '348175', '348196'] nosy_count = 4.0 nosy_names = ['docs@python', 'Krishna Oza', 'Mariatta', 'aeros'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = None url = 'https://bugs.python.org/issue37618' versions = ['Python 3.7', 'Python 3.8', 'Python 3.9'] ```

[aeros]

In the docs for the module stdtypes, the code example for several commonly used functions are in the bytearray section instead of the str section, where new users are far more likely to look. The new users are much more likely to benefit from seeing examples of these functions. A few examples of this include: islower(), isupper(), and istitle(). Since the functionality is very similar for functions such as str.islower() and bytearray.islower(), it doesn't seem necessary to include separate examples for each. With that in mind, here's a couple of potential solutions:

1) Move the location of the code examples to the str equivalent. This would require only removing the 'b' notation proceeding the strings. A link to the str equivalent could be potentially provided.

2) Provide a reference link to equivalent bytearray function in the str function's summary. This would be a bit easier since the code examples would not have to me modified or moved. However, for reasons stated above, it seems to make a bit more sense to have the examples be in the str functions rather than in the bytearray functions.

I can start working on a PR to address this, but I'll wait on some feedback first.

[aeros]

Clarification on option 1: The last sentence should be "A link to the bytearray equivalent..."

Clarification on option 2: As a part of this option, a link to the str equivalent could optionally be provided.

[5aa52c34-8a05-4311-ad37-28c83733de50]

Kyle In my opinion the current documentation is correctly formed since the bytearray and str are two different classes in Python they could have different set of functions supported and hence the grouping of functions like islower() to be kept separated for different object types.

[aeros]

In my opinion the current documentation is correctly formed since the bytearray and str are two different classes in Python they could have different set of functions supported and hence the grouping of functions like islower() to be kept separated for different object types.

This could justify the grouping of the functions themselves, but doesn't explain why the code examples are contained in bytearray instead of str. New users of the language are far more likely to check the docs for the string functions, and thus benefit significantly more from seeing the code examples.