gh-101021: Document binary parameters as bytes #101024

bkline · 2023-01-13T23:59:52Z

The existing documentation refers to binary parameters as "strings" when they are actually bytes.

Issue: The docs for email.mime types incorrectly identify bytes as strings #101021

warsaw

Can you resolve the conflicts and make sure all the checks pass? Since this is a just a docstring change, adding the skip-news label is probably fine.

This could probably be backported to maintenance branches.

Have you checked the actual stdlib documentation for its language?

Lib/email/mime/application.py

bedevere-bot · 2023-01-14T01:42:00Z

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.

The existing documentation refers to binary parameters as "strings" when they are actually bytes. Fixes python#101021

bkline · 2023-01-14T13:59:08Z

I have made the requested changes; please review again.

bedevere-bot · 2023-01-14T13:59:12Z

Thanks for making the requested changes!

@warsaw: please review the changes made to this pull request.

bitdancer · 2023-01-14T15:19:13Z

For your question about the labels, if you can't actually change labels using the 'labels' section in the right column of the PR on the github web interface, then you don't have permission to change those labels. If I'm right about that then Barry probably just forgot that regular users can't make such changes.

On the subject of the documentation, the answer is that the Python documentation is not so much documentation of the cpython interpreter and the standard library as it is a specification of the Python language and the standard library. (This fact is sometimes forgotten and results in later doc fixes prompted by people from other implementations of python noticing a statement that is cpython specific but not marked as such.) While it would be technically possible to have the documentation for things written in python be docstrings extracted into the specification docs, it has so far been deemed undesirable to do that. I think this is a combination of the aforementioned specification nature of the docs leading to a desire to be consistent (all the docs are in the doc source tree, not just some of them, to emphasize their independence from the specific implementation), and the fact that the language in the specification version of the docs, while often very similar or even identical to the function descriptions in the docstrings, is often enough different from what you would write if you were thinking of the function doc as a standalone docstring. Including the fact that we prefer to not have sphinx markup in docstrings.

bkline · 2023-01-14T16:12:56Z

Thanks, David. Love your avatar.

Might be a good idea to teach the bots (if not the maintainers) not to nag contributors to do something they aren't allowed to do. 😉

I understand your explanation of how the documentation system works, and I agree that what you've described is probably the right approach. One of the costs of that approach, though, is that it increases the work for keeping the documentation current and in sync with itself (and the likelihood that problems like the one being fixed here will persist). Oh, well. Life involves tradeoffs. 😅

warsaw · 2023-01-14T18:58:15Z

I was trying to look through the dev guide to find a description of permissions for labeling. I think the closest it gets is in the triage team description. So yes, @bitdancer is probably right that @bkline doesn't have permission to add labels.

Normally in my own libraries, I extract API documentation from docstrings and type hints, but even with that, it's difficult to describe the APIs with the level of detail necessary for the standard library.

warsaw

Thanks again for your contribution @bkline. Everything looks great.

miss-islington · 2023-01-14T19:01:30Z

Thanks @bkline for the PR, and @warsaw for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

(cherry picked from commit 49cae39) Co-authored-by: Bob Kline <bkline@users.noreply.github.com>

miss-islington · 2023-01-14T19:02:11Z

Sorry, @bkline and @warsaw, I could not cleanly backport this to 3.10 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 49cae39ef020eaf242607bb2d2d193760b9855a6 3.10

bedevere-bot · 2023-01-14T19:02:12Z

GH-101043 is a backport of this pull request to the 3.11 branch.

warsaw · 2023-01-14T19:09:43Z

@bkline - as you can see, the automation couldn't backport the change. If you're able to do that and submit a PR, I can help get that landed. If you can't or don't want to, let me know and I'll try to get to it when I'm back on my laptop.

bkline · 2023-01-14T19:16:58Z

I'd be willing to give it a shot, given adequate instructions. Not 100% sure I'd know all the steps which are needed otherwise. Fortunately, Google has gotten a lot better about bringing up the most current version of the docs in response to searches, so it's not as critical as the backport to 3.11 (which succeeded). Short answer: we're probably better off if you do it. 😎

warsaw · 2023-01-14T19:35:55Z

@bkline The devguide does explain how to manually backport changes. It's entirely up to you - if you want to learn how to do it and it would be fun for you, go for it! Just tag me in the PR. If not, I'll give it a shot.

(cherry picked from commit 49cae39) Co-authored-by: Bob Kline <bkline@users.noreply.github.com>

warsaw · 2023-01-14T20:23:18Z

Now that I'm on my desktop, I can see that the 3.11 backport worked fine. I've approved and merged it. It's only the 3.10 backport that failed. I'm looking at that now.

bkline · 2023-01-14T20:27:33Z

@warsaw Yes, those look like excellent instructions. I will definitely give it a shot.

bkline · 2023-01-14T23:52:00Z

Well, not as much fun as we thought it would be.

(venv) √ mime % cherry_picker --dry-run 49cae39ef020eaf242607bb2d2d193760b9855a6 3.10
🐍 🍒 ⛏
Dry run requested, listing expected command sequence
  dry-run: git remote get-url upstream
  dry-run: git fetch upstream --no-tags
Now backporting '49cae39ef020eaf242607bb2d2d193760b9855a6' into '3.10'
  dry-run: git remote get-url upstream
  dry-run: git checkout -b backport-49cae39-3.10 upstream/3.10
  dry-run: git cherry-pick -x 49cae39ef020eaf242607bb2d2d193760b9855a6

  dry-run: git show -s --format=%B 49cae39ef020eaf242607bb2d2d193760b9855a6
Traceback (most recent call last):
  File "/Users/bkline/.venvs/cdr/bin/cherry_picker", line 8, in <module>
    sys.exit(cherry_pick_cli())
  File "/Users/bkline/.venvs/cdr/lib/python3.10/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/Users/bkline/.venvs/cdr/lib/python3.10/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/Users/bkline/.venvs/cdr/lib/python3.10/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/bkline/.venvs/cdr/lib/python3.10/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/Users/bkline/.venvs/cdr/lib/python3.10/site-packages/click/decorators.py", line 26, in new_func
    return f(get_current_context(), *args, **kwargs)
  File "/Users/bkline/.venvs/cdr/lib/python3.10/site-packages/cherry_picker/cherry_picker.py", line 645, in cherry_pick_cli
    cherry_picker.backport()
  File "/Users/bkline/.venvs/cdr/lib/python3.10/site-packages/cherry_picker/cherry_picker.py", line 387, in backport
    commit_message = self.amend_commit_message(cherry_pick_branch)
  File "/Users/bkline/.venvs/cdr/lib/python3.10/site-packages/cherry_picker/cherry_picker.py", line 269, in amend_commit_message
    updated_commit_message = f"""{commit_prefix}{self.get_commit_message(self.commit_sha1)}
  File "/Users/bkline/.venvs/cdr/lib/python3.10/site-packages/cherry_picker/cherry_picker.py", line 211, in get_commit_message
    message = self.run_cmd(cmd).strip()
AttributeError: 'NoneType' object has no attribute 'strip'

I think I'll leave this to the big dogs. 😆🐾

bedevere-bot · 2023-01-15T05:05:48Z

GH-101052 is a backport of this pull request to the 3.10 branch.

…101052) (cherry picked from commit 49cae39) Co-authored-by: Bob Kline <bkline@users.noreply.github.com> Co-authored-by: Bob Kline <bkline@users.noreply.github.com>

warsaw · 2023-01-15T05:49:24Z

I think I'll leave this to the big dogs

Yeah, I'm sorry about all the friction. I ran into a few things myself so at least the core devs have also had a good discussion about this experience.

That all aside, I was able to manually backport the change the 3.10, so we're all done here. Thanks again for your contribution!

bkline · 2023-01-15T10:46:31Z

No worries, and thanks for all your help (and for helping to keep Python the best of the many languages I've used over the decades).

bkline requested a review from a team as a code owner January 13, 2023 23:59

bedevere-bot added the awaiting review label Jan 13, 2023

bedevere-bot mentioned this pull request Jan 13, 2023

The docs for email.mime types incorrectly identify bytes as strings #101021

Closed

warsaw requested changes Jan 14, 2023

View reviewed changes

Lib/email/mime/application.py Show resolved Hide resolved

bedevere-bot added awaiting changes and removed awaiting review labels Jan 14, 2023

warsaw added skip news needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes labels Jan 14, 2023

bkline force-pushed the call-a-byte-a-byte branch 3 times, most recently from 3ae1c6d to 5fe70e4 Compare January 14, 2023 13:21

pythonGH-101021: Document binary parameters as bytes

ae1b8b7

The existing documentation refers to binary parameters as "strings" when they are actually bytes. Fixes python#101021

bkline force-pushed the call-a-byte-a-byte branch from 5fe70e4 to ae1b8b7 Compare January 14, 2023 13:28

bedevere-bot added awaiting change review and removed awaiting changes labels Jan 14, 2023

bedevere-bot requested a review from warsaw January 14, 2023 13:59

warsaw approved these changes Jan 14, 2023

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting change review labels Jan 14, 2023

warsaw merged commit 49cae39 into python:main Jan 14, 2023

bedevere-bot removed the awaiting merge label Jan 14, 2023

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 14, 2023

pythongh-101021: Document binary parameters as bytes (pythonGH-101024)

e14b0d2

(cherry picked from commit 49cae39) Co-authored-by: Bob Kline <bkline@users.noreply.github.com>

miss-islington assigned warsaw Jan 14, 2023

bedevere-bot removed the needs backport to 3.11 only security fixes label Jan 14, 2023

miss-islington added a commit that referenced this pull request Jan 14, 2023

gh-101021: Document binary parameters as bytes (GH-101024)

39c1f68

(cherry picked from commit 49cae39) Co-authored-by: Bob Kline <bkline@users.noreply.github.com>

CAM-Gerlach mentioned this pull request Jan 15, 2023

Backport branch deleted even if push fails python/cherry-picker#78

Open

bedevere-bot removed the needs backport to 3.10 only security fixes label Jan 15, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-101021: Document binary parameters as bytes #101024

gh-101021: Document binary parameters as bytes #101024

bkline commented Jan 13, 2023 •

edited by bedevere-bot

Loading

warsaw left a comment

bedevere-bot commented Jan 14, 2023

bkline commented Jan 14, 2023

bedevere-bot commented Jan 14, 2023

bitdancer commented Jan 14, 2023

bkline commented Jan 14, 2023

warsaw commented Jan 14, 2023

warsaw left a comment

miss-islington commented Jan 14, 2023

miss-islington commented Jan 14, 2023

bedevere-bot commented Jan 14, 2023

warsaw commented Jan 14, 2023

bkline commented Jan 14, 2023 •

edited

Loading

warsaw commented Jan 14, 2023

warsaw commented Jan 14, 2023

bkline commented Jan 14, 2023

bkline commented Jan 14, 2023

bedevere-bot commented Jan 15, 2023

warsaw commented Jan 15, 2023

bkline commented Jan 15, 2023

gh-101021: Document binary parameters as bytes #101024

gh-101021: Document binary parameters as bytes #101024

Conversation

bkline commented Jan 13, 2023 • edited by bedevere-bot Loading

warsaw left a comment

Choose a reason for hiding this comment

bedevere-bot commented Jan 14, 2023

bkline commented Jan 14, 2023

bedevere-bot commented Jan 14, 2023

bitdancer commented Jan 14, 2023

bkline commented Jan 14, 2023

warsaw commented Jan 14, 2023

warsaw left a comment

Choose a reason for hiding this comment

miss-islington commented Jan 14, 2023

miss-islington commented Jan 14, 2023

bedevere-bot commented Jan 14, 2023

warsaw commented Jan 14, 2023

bkline commented Jan 14, 2023 • edited Loading

warsaw commented Jan 14, 2023

warsaw commented Jan 14, 2023

bkline commented Jan 14, 2023

bkline commented Jan 14, 2023

bedevere-bot commented Jan 15, 2023

warsaw commented Jan 15, 2023

bkline commented Jan 15, 2023

bkline commented Jan 13, 2023 •

edited by bedevere-bot

Loading

bkline commented Jan 14, 2023 •

edited

Loading