8000 gh-135041: Expand and update ``pickletools`` module docstrings by Legoclones · Pull Request #135042 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

gh-135041: Expand and update pickletools module docstrings #135042

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

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
Open

gh-135041: Expand and update pickletools module docstrings #135042

Changes from 1 commit
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
a181c01
Minor documentation updates + typo fixing
Legoclones Nov 20, 2024
6801bd2
Expand documentation on opcodes
Legoclones Nov 20, 2024
9ff845c
Lint
Legoclones Nov 20, 2024
51fc59f
Lint2
Legoclones Nov 20, 2024
11dadba
Expand some FRAME opcode code documentation
Legoclones Jun 2, 2025
ee4df6c
📜🤖 Added by blurb_it.
blurb-it[bot] Jun 2, 2025< 8000 /relative-time>
3a8a1c9
Merge branch 'main' into pickle-documentation-update
Legoclones Jun 2, 2025
42eaa17
Fixes
Legoclones Jun 3, 2025
d889990
Update Lib/pickletools.py
Legoclones Jun 3, 2025
05f1c48
Update Lib/pickletools.py
Legoclones Jun 17, 2025
c5455d2
Removed implementation details from EXT1 opcode
Legoclones Jun 17, 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
Prev Previous commit
Next Next commit
Expand documentation on opcodes
  • Loading branch information
@Legoclones
Legoclones authored Nov 20, 2024
commit 6801bd24405dd73b7c068170b7dc4312bfa8f405
60 changes: 40 additions & 20 deletions Lib/pickletools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1375,15 +1375,24 @@ def __init__(self, name, code, arg,
stack_before=[],
stack_after=[pybuffer],
proto=5,
doc="Push an out-of-band buffer object."),
doc="""Push an out-of-band buffer object.

An iterable must be passed to the Unpickler's 'buffer' argument, and
this opcode takes the next element from that iterable and puts it on
the stack.
"""),

I(name='READONLY_BUFFER',
code='\x98',
arg=None,
stack_before=[pybuffer],
stack_after=[pybuffer],
proto=5,
doc="Make an out-of-band buffer object read-only."),
doc="""Make an out-of-band buffer object read-only.

The top of the stack should be the out-of-band buffer object from
NEXT_BUFFER, and this object is set to read-only.
"""),

# Ways to spell None.

Expand Down Expand Up @@ -1541,7 +1550,9 @@ def __init__(self, name, code, arg,
Stack before: ... pylist markobject stackslice
Stack after: ... pylist+stackslice

although pylist is really extended in-place.
although pylist is really extended in-place. The .extend() attribute
function is attempted first, and if that fails the .append() attribute
is ran instead.
"""),

I(name='LIST',
Expand Down Expand Up @@ -1669,7 +1680,9 @@ def __init__(self, name, code, arg,
Stack before: ... pydict key value
Stack after: ... pydict

where pydict has been modified via pydict[key] = value.
where pydict has been modified via pydict[key] = value. Note that any
Copy link
Member

Choose a reason for hiding this comment

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

Should not we change "dict" to "mapping" in the description? And "list" to "sequence" in the description of APPEND?

type that supports item assignment can be modified here, such as a list
or bytearray.
"""),

I(name='SETITEMS',
Expand All @@ -1691,6 +1704,9 @@ def __init__(self, name, code, arg,

where pydict has been modified via pydict[key_i] = value_i for i in
1, 2, ..., n, and in that order.

Note that any type that supports item assignment can be modified here,
such as a list or bytearray.
"""),

# Ways to build sets
Expand Down Expand Up @@ -1749,7 +1765,12 @@ def __init__(self, name, code, arg,
stack_before=[anyobject],
stack_after=[],
proto=0,
doc="Discard the top stack item, shrinking the stack by one item."),
doc="""Discard the top stack item, shrinking the stack by one item.

If the stack has no items in it and the metastack is not empty, then
this opcode will act like POP_MARK and pop the top of the metastack
into the current stack.
"""),

I(name='DUP',
code='2',
Expand Down Expand Up @@ -1796,9 +1817,9 @@ def __init__(self, nam 8000 e, code, arg,
proto=0,
doc="""Read an object from the memo and push it on the stack.

The index of the memo object to push is given by the newline-terminated
decimal string following. BINGET and LONG_BINGET are space-optimized
versions.
The index of the memo object to push is given by the positive
newline-terminated decimal string following. BINGET and LONG_BINGET
are space-optimized versions.
"""),

I(name='BINGET',
Expand Down Expand Up @@ -1833,9 +1854,9 @@ def __init__(self, name, code, arg,
proto=0,
doc="""Store the stack top into the memo. The stack is not popped.

The index of the memo location to write into is given by the newline-
terminated decimal string following. BINPUT and LONG_BINPUT are
space-optimized versions.
The index of the memo location to write into is given by the positive
newline-terminated decimal string following. BINPUT and LONG_BINPUT
are space-optimized versions.
"""),

I(name='BINPUT',
Expand Down Expand Up @@ -1895,8 +1916,11 @@ def __init__(self, name, code, arg,
code registry ought to be global, although a range of codes may
be reserved for private use.

EXT1 has a 1-byte integer argument. This is used to index into the
extension registry, and the object at that index is pushed on the stack.
EXT1 has a 1-byte integer argument. This is used to index into
the inverted extension registry, which contains integer to tuple
mappings. The tuples have a length of two in the format of
'("module", "name")'. This tuple is then passed through find_class,
and the result is pushed onto the stack.
Copy link
Member

Choose a reason for hiding this comment

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

It mentions too much implementation details (the inverted extension registry and its format). It should only refer to copyreg.add_extension() (which unfortunately is not documented) and find_class() (like in GLOBAL, or just refer to it).

"""),

I(name='EXT2',
Expand Down Expand Up @@ -1946,6 +1970,9 @@ def __init__(self, name, code, arg,
stack_after=[anyobject],
proto=4,
doc="""Push a global object (module.attr) on the stack.

This opcode behaves the same way as GLOBAL except the module and name
arguments are two separate strings popped from the top of the stack.
"""),

# Ways to build objects of classes pickle doesn't know about directly
Expand Down Expand Up @@ -1973,13 +2000,6 @@ def __init__(self, name, code, arg,
argument to be passed to the object's __setstate__, and then the REDUCE
opcode is followed by code to create setstate's argument, and then a
BUILD opcode to apply __setstate__ to that argument.

If not isinstance(callable, type), REDUCE complains unless the
callable has been registered with the copyreg module's
safe_constructors dict, or the callable has a magic
'__safe_for_unpickling__' attribute with a true value. I'm not sure
why it does this, but I've sure seen this complaint often enough when
I didn't want to <wink>.
Comment on lines -1976 to -1981
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 no longer accurate?

"""),

I(name='BUILD',
Expand Down
0