Skip to content
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

gh-92446: Fix Argparse and LZMACompressor Docs #94627

Merged
merged 6 commits into from
Dec 26, 2022
Merged

gh-92446: Fix Argparse and LZMACompressor Docs #94627

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3e55685
Revert lzma documentation change
yourlefthandman Jul 6, 2022
956df83
Update the argparse documentation to refer to choices as a sequence
yourlefthandman Jul 6, 2022
3c512f1
Merge branch 'main' into fix_2_92446
yourlefthandman Jul 6, 2022
7ce0990
Merge branch 'main' into fix_2_92446
yourlefthandman Jul 7, 2022
917d4e9
Merge branch 'main' into fix_2_92446
yourlefthandman Jul 8, 2022
0e96c38
Say tuple instead of set
slateny Dec 25, 2022
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
12 changes: 6 additions & 6 deletions Doc/library/argparse.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -763,7 +763,7 @@ The add_argument() method

* type_ - The type to which the command-line argument should be converted.

* choices_ - A container of the allowable values for the argument.
* choices_ - A sequence of the allowable values for the argument.

* required_ - Whether or not the command-line option may be omitted
(optionals only).
Expand Down Expand Up @@ -1207,7 +1207,7 @@ choices
^^^^^^^

Some command-line arguments should be selected from a restricted set of values.
These can be handled by passing a container object as the *choices* keyword
These can be handled by passing a sequence object as the *choices* keyword
argument to :meth:`~ArgumentParser.add_argument`. When the command line is
parsed, argument values will be checked, and an error message will be displayed
if the argument was not one of the acceptable values::
Expand All @@ -1221,9 +1221,9 @@ if the argument was not one of the acceptable values::
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')

Note that inclusion in the *choices* container is checked after any type_
Note that inclusion in the *choices* sequence is checked after any type_
conversions have been performed, so the type of the objects in the *choices*
container should match the type_ specified::
sequence should match the type_ specified::

>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
Expand All @@ -1233,8 +1233,8 @@ container should match the type_ specified::
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

Any container can be passed as the *choices* value, so :class:`list` objects,
:class:`set` objects, and custom containers are all supported.
Any sequence can be passed as the *choices* value, so :class:`list` objects,
:class:`set` objects, and custom sequences are all supported.
Copy link
Member

Choose a reason for hiding this comment

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

Sets are not sequences, so this sentence doesn't make sense any more. @rhettinger wrote on the issue that sets don't work well, so I suggest we mention tuples as a second example here instead of sets.

slateny marked this conversation as resolved.
Show resolved Hide resolved

Use of :class:`enum.Enum` is not recommended because it is difficult to
control its appearance in usage, help, and error messages.
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/lzma.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ Compressing and decompressing data in memory
This format is more limited than ``.xz`` -- it does not support integrity
checks or multiple filters.

* :const:`FORMAT_RAW`: A raw data stream, not using sequences format.
* :const:`FORMAT_RAW`: A raw data stream, not using any container 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 don't know what the motivation is for this change, and it doesn't seem related to the linked issue. Why is it needed?

Copy link
Contributor

Choose a reason for hiding this comment

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

It was (seemingly) mistakenly changed in https://github.com/python/cpython/pull/92450/files , a previous attempt to fix the issue

This format specifier does not support integrity checks, and requires that
you always specify a custom filter chain (for both compression and
decompression). Additionally, data compressed in this manner cannot be
Expand Down