Skip to content

gh-161803: Document that pickle's file.write() receives bytes-like objects - #161804

Open
eachimei wants to merge 2 commits into
python:mainfrom
eachimei:gh-161803-pickle-write-bytes-like
Open

eachimei wants to merge 2 commits into
python:mainfrom
eachimei:gh-161803-pickle-write-bytes-like

Conversation

@eachimei

@eachimei eachimei commented Nov 11, 2026 •

Copy link
Copy Markdown

The Pickler file contract says write() "accepts a single bytes argument". With protocols 4 and 5 that is inaccurate: both the C and the pure-Python picklers can pass bytearray, memoryview or PickleBuffer objects, and custom file objects that call len(data) then fail. See gh-161803; gh-88605 is the same problem in bz2/lzma.

This PR:

  • changes the wording to "bytes-like object" in Doc/library/pickle.rst, Lib/pickle.py and the two Modules/_pickle.c docstrings, and regenerates the clinic output;
  • adds a short note recommending memoryview(data).nbytes for byte counts.

Docs only; no behaviour change.

…ike objects

The Pickler file contract said write() accepts a single bytes argument,
but with protocols 4 and 5 both picklers may pass bytearray, memoryview
or PickleBuffer objects.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@python-cla-bot

python-cla-bot Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.

CLA signed

@bedevere-app

bedevere-app Bot commented Nov 11, 2026

Copy link
Copy Markdown

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

@eachimei
eachimei force-pushed the gh-161803-pickle-write-bytes-like branch from 8dc3d5e to bc120d7 Compare November 11, 2026 10:26
@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #35809842 | 📁 Comparing bc120d7 against main (de9a4fb)

  🔍 Preview build  

2 files changed
± library/pickle.html
± whatsnew/changelog.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant