I’ll check out the Docs Discord, but I’m happy to help support and collaborate on additional refactorings on both the argparse docs and tutorial, as I agree, there’s still a lot of improvement to be done.
@savannahostrowski Thank you for your work on the argparse docs. Would you like to work with the editorial board on auditing the argparse docs? I’m on the editorial board and would be happy to support you.
Here’s what that could look like:
I work with you and the rest of the editorial board to define the goals and questions of the audit.
You and I agree on a system for answering those questions.
You use that system to audit the docs, with me as support.
We define, list, and order the changes that will need to be made to meet the goals of the audit.
Does this sound like something you’d like to work on together?
One thing to keep in mind is that part of the problem here is the optparse docs: since the argparse docs and tutorial were initially derived from the optparse ones, but also written to be self-contained, there are likely parts of the optparse docs where either inline text should be replaced with references out to the relevant parts of the argparse docs, or else we need to make the explicit decision of “No, we also want the optparse docs to continue to be self-contained, so we will maintain two copies of this information in perpetuity”.
However, I don’t believe anyone has ever produced a clear list of what information actually is duplicated now, thus the trade-off between the two future approaches isn’t clear.
I am fine with keeping all three, un-deprecated, fully supported.
However, I propose that we gently nudge users to argparse, as the most recent offering. IMO the only cross-links should be short notes at the top or getopt and optparse suggesting to look at argparse for new projects (which fans of getopt and optparse can ignore without feeling they’re doing something cheeky).
I’m not sure that any of these need to have a more comprehensive “guide to choosing an argument parsing library”, as such a guide would be incomplete given the plethora of great 3rd party offerings – and IMO we shouldn’t weigh in on that choice: Opinions vary and popularity changes and we don’t want to have to update the docs with such recommendations. Nor do we want to put a hand on the scale in favor of this or that 3rd party option.
Historical notes don’t belong at the top of module documentation, because most first-time readers couldn’t care less, and the top of a module’s documentation is prime real estate to present the most essential information for all (but especially new) users. (A pointer to a preferred module is not a historical note and does belong there.)
IMO the only cross-links should be short notes at the top or getopt and optparse suggesting to look at argparse for new projects (which fans of getopt and optparse can ignore without feeling they’re doing something cheeky).
This would be a welcome relief. Users of the latter two modules had felt like they were on thin ice.
I did weigh in with a few “not wrong” suggestions for 3rd party argument parsing in a “See Also” box (while also trying to make it clear that argparse and optparse are both potentially viable options depending on what you’re wanting to do). Those recommendations are definitely based on “What would I personally choose?”, but I figure folks with strong opinions of their own won’t care what the docs say, while folks that are frustrated with argparse, but don’t yet know what they might want instead, may appreciate the pointers.
That said, my main goal in adding the “choosing an argument parsing library” subsection in the optparse docs was to have a definitive place to link to as the answer to why we have 3 different non-deprecated argument parsing modules in the standard library. I did it that way because it seemed the most useful format and placement, but I wouldn’t actually mind if we relocated the info to the Design FAQ or a separate HOWTO guide (I do think we need to publish the rationale for keeping all 3 somewhere though, otherwise we’ll get more pushes for outright deprecation of optparse and getopt in the future).
I can’t imagine there are a lot of folks (other than a few core devs or hard-core contributors) wondering why we have three versions, so I would definitely recommend streamlining all that (according to my proposal above). People looking for 3rd party alternatives can ask their favorite search engine, which has many links to various tutorials and official docs fo argparse, one for optparse, and a stack overflow entry that repeats those suggestions (in the same proportions) but also links to docopt (8k stars on GitHub) and Click (16k stars).
Also please re-read my note about how the top of module documentation is prime real estate.
I find the fact things got as far as formally deprecatingoptparse and getopt for Python 3.13.0 to be pretty solid evidence that people do wonder why we have three argument parsing libraries (hence my wanting us to ensure we have explicit guidance saying not to deprecate those two libraries somewhere).
However, as I noted above, I don’t mind if folks want to trim down the current start of the optparse docs by moving that info elsewhere. I find the argument for moving or shortening it insufficiently compelling to volunteer to make that further edit myself, but compelling enough that I wouldn’t object to someone else moving it.
Yes, the start of the optparse module docs is prime real estate (albeit not to the same degree as the start of the argparse docs), but my view is that this is exactly what makes it the best place to ask a reader if they’re sure they’re looking at the right documentation:
if they’re just starting out, they probably want argparse
if they’re just dissatisfied with how argparse works, they may be better off looking to one of the PyPI libraries rather than back towards optparse
if the specific problem they have aligns with the reasons that optparse isn’t deprecated, then this section will confirm that the library will solve their problem
if they’re already sure they want the optparse docs, then the left navbar lets them skip over not only the new guidance section, but also the longstanding introduction, background material, and tutorial
I’m going to chime in here as a user, not a developer, of these libraries. I imagine most of what I write here has appeared in some form in other posts to this thread, but at this point I’m not going to go back and reread 130 posts.
As a C programmer in my life before Python came along, getopt fit pretty nicely into a niche in the back corner of my brain. This was further reinforced by the built-in Bourne shell command, getopts. My guess is that other languages people might have experience with before learning Python will also have something like getopt(3) in their personal toolkit. (This is kind of implied by the introductory text in the module documentation. Maybe it should be made more explicit?)
I didn’t use optparse long before argparse came along (I don’t recall why I switched), but like Guido, I generally use the tried-and-true cargo cult technique to initialize argument parsing in a new script. (I suppose at this point I should just define an Emacs macro for that.)
I recently tried Click, but found for my kind of weird needs in the moment it didn’t quite work. Still, while reading its intro docs I noticed the author(s) explicitly built it on top of optparse, so maybe argparse isn’t entirely perfect under the covers.
Long story short, while it might be overkill, I think it’s fine to have all three in the stdlib. They appear to each serve a somewhat different community. The introduction to each library’s documentation should probably reflect that. If you want to trim some of the (duplicatative?) introductory text, I suggest adding a separate section on this page which describes a bit of the history and rationale for all three libraries. (I still think getopt should live in this section, not buried in the “stuff we wouldn’t keep in the stdlib if we felt we could toss it out” section, BTW.)