Skip to content

gh-67748: DOC:Add summary table for str methods in stdtypes.rst #1709

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Jan 13, 2025
Merged

gh-67748: DOC:Add summary table for str methods in stdtypes.rst #1709

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
937e8dd
bpo-23560: DOC:Add summary table for str methods in stdtypes.rst
csabella May 22, 2017
b3d4477
Correct use of + where there was no intersection
csabella Oct 21, 2017
7352386
Reformat to show left and right on same row
csabella Oct 21, 2017
b577580
Add other methods of string formatting
csabella Oct 21, 2017
e7ef462
Merge branch 'main' into bpo23560
ezio-melotti Aug 30, 2022
35a0649
Merge branch 'main' into bpo23560
arhadthedev Apr 25, 2023
63227f9
Merge branch 'main' into bpo23560
willingc Oct 31, 2024
25ec485
Merge in the main branch
encukou Jan 7, 2025
f1a2a6d
Fix table formatting
encukou Jan 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 103 additions & 0 deletions Doc/library/stdtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1376,6 +1376,108 @@ objects that compare equal might have different :attr:`~range.start`,
single: str (built-in class); (see also string)
object: string

.. _text-methods-summary:

Text and Binary Sequence Type Methods Summary
=============================================
The following table summarizes the text and binary sequence types methods by
category.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this paragraph necessary? It seems obvious just given the section and table headings.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, Martin. You're right. I wasn't quite sure where to place this overall and thought there would probably be suggestions, so I kept it vague. There wasn't a section that combined both text and binary sequence types before and I didn't know if people would like having str and bytes (and bytearray) types all in one table or if there should be a separate table for each one under the existing sections.



+--------------------------+------------------------------+------------------------------+
| Category | str methods | bytes methods |
+==========================+==============================+==============================+
| Formatting | :meth:`str.format` | |
+ +------------------------------+------------------------------+
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the leftmost + can/should be a |.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

| | :meth:`str.format_map` | |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe __mod__ (%) should be included here too.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added some lines for the printf-style and for f-strings. I think I linked them to the best places for a description.

+--------------------------+------------------------------+------------------------------+
| Searching and Replacing | :meth:`str.find` | :meth:`bytes.find` |
+ +------------------------------+------------------------------+
| | :meth:`str.rfind` | :meth:`bytes.rfind` |
+ +------------------------------+------------------------------+
| | :meth:`str.index` | :meth:`bytes.index` |
+ +------------------------------+------------------------------+
| | :meth:`str.rindex` | :meth:`bytes.rindex` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps the methods and their corresponding rmethods could be combined on the same line to make the table more compact. If however the end result isn't more readable, you could leave them separate.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added the methods and rmethods on the same lines, but I did it 2 different ways so that you could pick which one you prefer. find\rfind and index\rindex are done as columns while split\rsplit, ljust\rjust, and lstrip/rstrip are done as or.

+ +------------------------------+------------------------------+
| | :meth:`str.startswith` | :meth:`bytes.startswith` |
+ +------------------------------+------------------------------+
| | :meth:`str.endswith` | :meth:`bytes.endswith` |
+ +------------------------------+------------------------------+
| | :meth:`str.count` | :meth:`bytes.count` |
+ +------------------------------+------------------------------+
| | :meth:`str.replace` | :meth:`bytes.replace` |
+--------------------------+------------------------------+------------------------------+
| Splitting and Joining | :meth:`str.split` | :meth:`bytes.split` |
+ +------------------------------+------------------------------+
| | :meth:`str.splitlines` | :meth:`bytes.splitlines` |
+ +------------------------------+------------------------------+
| | :meth:`str.rsplit` | :meth:`bytes.rsplit` |
+ +------------------------------+------------------------------+
| | :meth:`str.partition` | :meth:`bytes.partition` |
+ +------------------------------+------------------------------+
| | :meth:`str.rpartition` | :meth:`bytes.rpartition` |
+ +------------------------------+------------------------------+
| | :meth:`str.join` | :meth:`bytes.join` |
+--------------------------+------------------------------+------------------------------+
| String Classification | :meth:`str.isalpha` | :meth:`bytes.isalpha` |
+ +------------------------------+------------------------------+
| | :meth:`str.isdecimal` | |
+ +------------------------------+------------------------------+
| | :meth:`str.isdigit` | :meth:`bytes.isdigit` |
+ +------------------------------+------------------------------+
| | :meth:`str.isnumeric` | |
+ +------------------------------+------------------------------+
| | :meth:`str.isalnum` | :meth:`bytes.isalnum` |
+ +------------------------------+------------------------------+
| | :meth:`str.isidentifier` | |
+ +------------------------------+------------------------------+
| | :meth:`str.islower` | :meth:`bytes.islower` |
+ +------------------------------+------------------------------+
| | :meth:`str.isupper` | :meth:`bytes.isupper` |
+ +------------------------------+------------------------------+
| | :meth:`str.istitle` | :meth:`bytes.istitle` |
+ +------------------------------+------------------------------+
| | :meth:`str.isspace` | :meth:`bytes.isspace` |
+ +------------------------------+------------------------------+
| | :meth:`str.isprintable` | |
+--------------------------+------------------------------+------------------------------+
| Case Manipulation | :meth:`str.lower` | :meth:`bytes.lower` |
+ +------------------------------+------------------------------+
| | :meth:`str.upper` | :meth:`bytes.upper` |
+ +------------------------------+------------------------------+
| | :meth:`str.casefold` | |
+ +------------------------------+------------------------------+
| | :meth:`str.capitalize` | :meth:`bytes.capitalize` |
+ +------------------------------+------------------------------+
| | :meth:`str.title` | :meth:`bytes.title` |
+ +------------------------------+------------------------------+
| | :meth:`str.swapcase` | :meth:`bytes.swapcase` |
+--------------------------+------------------------------+------------------------------+
| Padding and Stripping | :meth:`str.ljust` | :meth:`bytes.ljust` |
+ +------------------------------+------------------------------+
| | :meth:`str.rjust` | :meth:`bytes.rjust` |
+ +------------------------------+------------------------------+
| | :meth:`str.center` | :meth:`bytes.center` |
+ +------------------------------+------------------------------+
| | :meth:`str.zfill` | :meth:`bytes.zfill` |
+ +------------------------------+------------------------------+
| | :meth:`str.expandtabs` | :meth:`bytes.expandtabs` |
+ +------------------------------+------------------------------+
| | :meth:`str.strip` | :meth:`bytes.strip` |
+ +------------------------------+------------------------------+
| | :meth:`str.lstrip` | :meth:`bytes.lstrip` |
+ +------------------------------+------------------------------+
| | :meth:`str.rstrip` | :meth:`bytes.rstrip` |
+--------------------------+------------------------------+------------------------------+
| Translation and Encoding | :meth:`str.translate` | :meth:`bytes.translate` |
+ +------------------------------+------------------------------+
| | :meth:`str.maketrans` | :meth:`bytes.maketrans` |
+ +------------------------------+------------------------------+
| | :meth:`str.encode` | |
+ +------------------------------+------------------------------+
| | | :meth:`bytes.decode` |
+--------------------------+------------------------------+------------------------------+

.. _textseq:

Text Sequence Type --- :class:`str`
Expand Down Expand Up @@ -1464,6 +1566,7 @@ multiple fragments.
sections. In addition, see the :ref:`stringservices` section.



Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was this change intentional?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for catching that! I've removed it.

.. index::
pair: string; methods

Expand Down