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

csabella · 2017-05-22T00:54:42Z

Based on the original patch by Martin Panter to create a table categorizing str methods.

https://bugs.python.org/issue23560

Issue: Group the docs of similar methods in stdtypes.rst #67748

vadmium

I don’t have much of an opinion about adding this table comparing the methods that are available. If others think it would be good to add, don’t let me get in your way :)

FWIW I don’t think it helps with Ezio’s original goal to remove duplication and make the documentation shorter. But I don’t see a good way to accomplish that and at the same time satisfy @rhettinger by keeping an entry for each method in alphabetical order.

vadmium · 2017-05-27T02:18:09Z

Doc/library/stdtypes.rst

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


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

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.

csabella · 2017-05-27T11:57:03Z

@vadmium Thanks for your comments. I hope others chime in. Being fairly new to Python, I've found my chart (or your changes) very helpful in using the right str functions. To your point, it didn't really do much to shorten the page though.

ezio-melotti · 2017-10-13T13:20:31Z

Doc/library/stdtypes.rst

+==========================+==============================+==============================+
+| Formatting               |  :meth:`str.format`          |                              |
+                          +------------------------------+------------------------------+
+|                          |  :meth:`str.format_map`      |                              |


Maybe __mod__ (%) should be included here too.

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.

ezio-melotti · 2017-10-13T13:22:27Z

Doc/library/stdtypes.rst

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


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

ezio-melotti · 2017-10-13T13:22:32Z

Doc/library/stdtypes.rst

+                          +------------------------------+------------------------------+
+|                          |  :meth:`str.index`           |  :meth:`bytes.index`         |
+                          +------------------------------+------------------------------+
+|                          |  :meth:`str.rindex`          |  :meth:`bytes.rindex`        |


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.

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.

ezio-melotti · 2017-10-13T13:23:04Z

Doc/library/stdtypes.rst

@@ -1464,6 +1566,7 @@ multiple fragments.
   sections.  In addition, see the :ref:`stringservices` section.


+


Was this change intentional?

Thanks for catching that! I've removed it.

bedevere-bot · 2017-10-13T13:25:05Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

csabella · 2017-10-21T16:52:21Z

I have made the requested changes; please review again

bedevere-bot · 2017-10-21T16:52:22Z

Thanks for making the requested changes!

@ezio-melotti: please review the changes made to this pull request.

adorilson · 2021-03-22T00:56:16Z

@ezio-melotti Do you review this PR?

github-actions · 2022-02-19T00:08:35Z

This PR is stale because it has been open for 30 days with no activity.

github-actions · 2022-08-28T00:15:28Z

This PR is stale because it has been open for 30 days with no activity.

ezio-melotti · 2022-08-30T21:20:42Z

This is how the (first half of the) table looks like. The table intentionally splits some cells and uses a | on others to show two alternative styles.

One issue with the table is that it takes over a page and it has a lot of whitespace. Maybe we could do something that looks like this instead (using a proper colspan):

	Searching and Replacing
str	`str.find`/`str.rfind`, `str.index`/`str.rindex`, `str.startswith`/`str.endswith`, `str.count`, `str.replace`
bytes	`bytes.find`/`bytes.rfind`, `bytes.index`/`bytes.rindex`, `bytes.startswith`/`bytes.endswith`, `bytes.count`, `bytes.replace`
	Splitting and Joining
str	`str.split`/`str.rsplit`, `str.splitlines`, `str.partition`/`str.rpartition`,`str.join`
bytes	`bytes.split`/`bytes.rsplit`, `bytes.splitlines`, `bytes.partition`/`bytes.rpartition`, `bytes.join`

We lose the direct mapping from str to the equivalent bytes method, but since they are still grouped it's easy enough to find it.

CAM-Gerlach · 2022-08-31T04:31:02Z

Hmm, well take my opinion as just one data point, but while I do definitely see the concern of it being rather long, at least from what I can see so far, I find the current format a good deal easier to skim and consult as a structured summary, at least personally to my eyes. If we're going to go with a structure similar to what you propose, I'm not sure if we even need a table at all, as opposed to just a bulleted list, which has essentially the same structure, is even more compact and is simpler to read and write, e.g.

Searching and Replacing
- str.find/str.rfind, str.index/str.rindex, str.startswith/str.endswith, str.count, str.replace
- bytes.find/bytes.rfind, bytes.index/bytes.rindex, bytes.startswith/bytes.endswith, bytes.count, bytes.replace
Splitting and Joining
- str.split/str.rsplit, str.splitlines, str.partition/str.rpartition, str.join
- bytes.split/bytes.rsplit, bytes.splitlines, bytes.partition/bytes.rpartition, bytes.join

Meanwhile, the original table could be made more compact and maintainable, at least in the source, by formatting it as a list-table rather than a full literal table.

Also, of the two styles, FWIW a real cell split rather than a raw | looks a lot cleaner and clearer to me.

ezio-melotti · 2022-09-01T13:00:24Z

See also these issues:

github-actions · 2022-10-02T00:18:03Z

This PR is stale because it has been open for 30 days with no activity.

github-actions · 2023-05-27T00:11:03Z

This PR is stale because it has been open for 30 days with no activity.

willingc · 2024-10-31T02:02:28Z

@ezio-melotti I'm going through and rebooting and/or closing old Docs PRs. This one looks good and is an improvement over not having it. Would you be cool with merging? There would always be the option to iterate on it in the future. Thanks!

github-actions · 2024-11-30T12:03:30Z

This PR is stale because it has been open for 30 days with no activity.

encukou · 2024-12-19T16:23:09Z

Doc/library/stdtypes.rst

+--------------------------+-------------------------------------------+---------------------------------------------------+
+| Splitting and Joining    | :meth:`str.split` | :meth:`str.rsplit`    | :meth:`bytes.split` | :meth:`bytes.rsplit`        |
+--------------------------+-------------------------------------------+---------------------------------------------------+


The r/l pairs (split/rsplit, ljust/rjust, lstrip/rstrip) need +s to render as table cells:

Suggested change

+--------------------------+-------------------------------------------+---------------------------------------------------+

| Splitting and Joining | :meth:`str.split` | :meth:`str.rsplit` | :meth:`bytes.split` | :meth:`bytes.rsplit` |

+--------------------------+-------------------------------------------+---------------------------------------------------+

+--------------------------+-------------------+-----------------------+---------------------+-----------------------------+

| Splitting and Joining | :meth:`str.split` | :meth:`str.rsplit` | :meth:`bytes.split` | :meth:`bytes.rsplit` |

+--------------------------+-------------------+-----------------------+---------------------+-----------------------------+

encukou · 2024-12-19T16:25:14Z

I agree that it's an improvement and can be iterated on.
If there are no objections, I'll merge early next year.

the-knights-who-say-ni added the CLA signed label May 22, 2017

serhiy-storchaka requested review from vadmium and ezio-melotti May 22, 2017 06:07

vadmium reviewed May 27, 2017

View reviewed changes

bpo-23560: DOC:Add summary table for str methods in stdtypes.rst

937e8dd

csabella force-pushed the bpo23560 branch from 096ff95 to 937e8dd Compare June 1, 2017 23:14

ezio-melotti requested changes Oct 13, 2017

View reviewed changes

bedevere-bot added the awaiting changes label Oct 13, 2017

csabella added 3 commits October 21, 2017 11:26

Correct use of + where there was no intersection

b3d4477

Reformat to show left and right on same row

7352386

Add other methods of string formatting

b577580

bedevere-bot added awaiting change review and removed awaiting changes labels Oct 21, 2017

github-actions bot added the stale Stale PR or inactive for long period of time. label Feb 19, 2022

ezio-melotti removed the CLA signed label Jul 13, 2022

github-actions bot removed the stale Stale PR or inactive for long period of time. label Jul 28, 2022

github-actions bot added the stale Stale PR or inactive for long period of time. label Aug 28, 2022

Merge branch 'main' into bpo23560

e7ef462

ezio-melotti changed the title ~~bpo-23560: DOC:Add summary table for str methods in stdtypes.rst~~ gh-67748: DOC:Add summary table for str methods in stdtypes.rst Aug 30, 2022

ezio-melotti requested a review from CAM-Gerlach August 30, 2022 21:20

github-actions bot removed the stale Stale PR or inactive for long period of time. label Aug 31, 2022

CAM-Gerlach added the docs Documentation in the Doc dir label Aug 31, 2022

CAM-Gerlach added the skip news label Aug 31, 2022

github-actions bot added the stale Stale PR or inactive for long period of time. label Oct 2, 2022

Merge branch 'main' into bpo23560

35a0649

github-actions bot removed the stale Stale PR or inactive for long period of time. label Apr 26, 2023

github-actions bot added the stale Stale PR or inactive for long period of time. label May 27, 2023

dg-pb mentioned this pull request Oct 23, 2024

Doc: Add a single table as summary to math documentation #125810

Merged

willingc approved these changes Oct 31, 2024

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting change review labels Oct 31, 2024

Merge branch 'main' into bpo23560

63227f9

willingc requested a review from ezio-melotti October 31, 2024 02:00

github-actions bot removed the stale Stale PR or inactive for long period of time. label Oct 31, 2024

github-actions bot added the stale Stale PR or inactive for long period of time. label Nov 30, 2024

encukou reviewed Dec 19, 2024

View reviewed changes

github-actions bot removed the stale Stale PR or inactive for long period of time. label Dec 19, 2024

encukou added 2 commits January 7, 2025 14:30

Merge in the main branch

25ec485

Fix table formatting

f1a2a6d

encukou merged commit 5044c22 into python:main Jan 13, 2025
25 checks passed

bedevere-app bot removed the awaiting merge label Jan 13, 2025

		@@ -1464,6 +1566,7 @@ multiple fragments.
		sections. In addition, see the :ref:`stringservices` section.

Uh oh!

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

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

Uh oh!

Conversation

csabella commented May 22, 2017 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vadmium left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

csabella commented May 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-bot commented Oct 13, 2017

Uh oh!

csabella commented Oct 21, 2017

Uh oh!

bedevere-bot commented Oct 21, 2017

Uh oh!

adorilson commented Mar 22, 2021

Uh oh!

github-actions bot commented Feb 19, 2022

Uh oh!

github-actions bot commented Aug 28, 2022

Uh oh!

ezio-melotti commented Aug 30, 2022

Uh oh!

CAM-Gerlach commented Aug 31, 2022

Uh oh!

ezio-melotti commented Sep 1, 2022

Uh oh!

github-actions bot commented Oct 2, 2022

Uh oh!

github-actions bot commented May 27, 2023

Uh oh!

willingc commented Oct 31, 2024

Uh oh!

github-actions bot commented Nov 30, 2024

Uh oh!

encukou Dec 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

encukou commented Dec 19, 2024

Uh oh!

Uh oh!

Uh oh!

csabella commented May 22, 2017 •

edited by bedevere-bot

Loading

csabella commented May 27, 2017 •

edited

Loading

encukou Dec 19, 2024 •

edited

Loading