GH-54732: Tweak wording around empty lines in argument files

[savannahostrowski]

Follow-up to #136795.

Revises the empty-lines note to address the concerns raised in #54732 (comment), and adds a caveat to the convert_arg_line_to_args example that split-based parsing can't represent arguments containing spaces.

• Issue: argparse has problem parsing option files containing empty rows #54732

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33060979 | 📁 Comparing 0f80836 against main (6544bf4)

  🔍 Preview build  

17 files changed · ± 17 modified

± Modified

• c-api/long.html
• c-api/typeobj.html
• howto/functional.html
• library/argparse.html
• library/bisect.html
• library/collections.abc.html
• library/collections.html
• library/importlib.resources.html
• library/logging.handlers.html
• library/math.html
• and 7 more...

[clytaemnestra]

I tried to simulate the situation where empty strings are passed from a file and it doesn't return an unrecognized argument, so this note makes much more sense to me and is perfectly understandable.

I also tried to simulate the unrecognized arguments error to see when it appears and my understanding is that it's related to leftover tokens in general rather than empty strings. So, if my understanding is correct, it also makes sense that it was removed here.

So, overall, the new wording is much clearer to me.

>>> import argparse
>>> with open("args.txt", "w") as f:
...   f.write("-f\n\nbar\n")
...
8
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars="@")
>>> parser.add_argument("-f")
_StoreAction(option_strings=['-f'], dest='f', nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None, deprecated=False)
>>> parser.add_argument("rest", nargs="*")
_StoreAction(option_strings=[], dest='rest', nargs='*', const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None, deprecated=False)
>>> parser._read_args_from_files(["@args.txt"])
['-f', '', 'bar']
>>> parser.parse_args(["@args.txt"])
Namespace(f='', rest=['bar'])
>>> p2 = argparse.ArgumentParser(fromfile_prefix_chars="@")
>>> p2.add_argument("-f")
_StoreAction(option_strings=['-f'], dest='f', nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None, deprecated=False)
>>> p2.parse_args(["@args.txt"])
usage: [-h] [-f F]
: error: unrecognized arguments: bar

[miss-islington-app]

Thanks @savannahostrowski for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

[bedevere-app]

GH-151165 is a backport of this pull request to the 3.15 branch.

[bedevere-app]

GH-151166 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-151167 is a backport of this pull request to the 3.13 branch.