Argparse: Required arguments listed under "optional arguments"?

Crafty renaming to distinguish required from optional

A tricky aspect in argparse is the placement of required arguments in the optional category. Here are ways to sidestep this confusion:

• Exclude required arguments from the default optional category. This means not mixing required=True arguments outside your argument_group.
• Spotlight required arguments in your help output by listing them first. The mandatory fields get due attention this way.
• Deactivate argparse's default help with add_help=False. This handy trick allows you to steer clear of argparse automatically placing its help option into the optional group.
• Maintain a consistent code pattern across versions of your script to avoid future confusion.

Arrange argument groups for user friendliness

A well-ordered help message can give your CLI a professional look:

• Reorder the argument groups as per their importance using parser._action_groups.pop() and append().
• Make sure that required arguments are easily visible by positioning them advantageously in the output.

Remember, argparse designed flags as optional

While tweaking argparse's configuration, keep in sync with its fundamental principles:

• Named arguments (those with prefixes) were designed to be optional, not mandatory. This convention prevents creating paradoxical "required optional" arguments.
• Required arguments lack square brackets in usage, which visually sets them apart from optional ones. Abiding by this convention supports user expectations.

Code visualisation, or the Pictionary game

Imagine argparse as a kitchen:

Kitchen Tools (🍳): [Spatula (required), Whisk (optional), Bowl (optional)]

Misplaced tools:

Optional Hooks (🪝) wall shelters:
- Spatula (required) 🪝
- Whisk (optional) 🪝
- Bowl (optional) 🪝
# Oops! Argparse hung REQUIRED Spatula on OPTIONAL hooks. Tricky!

Organised kitchen with argparse help:

REQUIRED tools wall (🔨):
- Spatula (required) 🔨

OPTIONAL tools wall (🪝):
- Whisk (optional) 🪝
- Bowl (optional) 🪝
# Thanks, argparse! We sorted the utensils.

Your code organization should reflect the intended role of each element, just like a well-organised kitchen.

Handling edge cases to save your day

Argparse sometimes throws up intricate challenges:

• Adding an argument without a prefix signals a required positional argument, but you miss out on the flexibility of named arguments.
• A swarm of required arguments can cause redundancy. Try creating helper functions to streamline this process.

User-friendly practices: Happy users, happy you

Adhering to certain conventions will bring a smile to your users:

• Stick to a naming convention that's both brief and expressive so that users can grasp the workflow quickly.
• Whenever you deviate from argparse defaults, back it up with a comprehensive help message using parser.print_help() to avoid catching users off-guard.

Write for your future self: Clean code matters

While tweaking argparse's behavior, consider these practices:

• Write clean, readable code, since your future self will thank you. In-line documentation is a must when working with complex argparse setups.
• Avoid over-reliance on private methods like parser._action_groups, though useful, they aren't part of the public API and are subject to change.