@@ -192,6 +192,12 @@ arguments it contains. The default message can be overridden with the
192192The ``%(prog)s `` format specifier is available to fill in the program name in
193193your usage messages.
194194
195+ When a custom usage message is specified for the main parser, you may also want to
196+ consider passing the ``prog `` argument to :meth: `~ArgumentParser.add_subparsers `
197+ or the ``prog `` and the ``usage `` arguments to
198+ :meth: `~_SubParsersAction.add_parser `, to ensure consistent command prefixes and
199+ usage information across subparsers.
200+
195201
196202.. _description :
197203
@@ -801,7 +807,8 @@ Only actions that consume command-line arguments (e.g. ``'store'``,
801807
802808The recommended way to create a custom action is to extend :class: `Action `,
803809overriding the :meth: `!__call__ ` method and optionally the :meth: `!__init__ ` and
804- :meth: `!format_usage ` methods.
810+ :meth: `!format_usage ` methods. You can also register custom actions using the
811+ :meth: `~ArgumentParser.register ` method and reference them by their registered name.
805812
806813An example of a custom action::
807814
@@ -1020,10 +1027,11 @@ necessary type-checking and type conversions to be performed.
10201027If the type _ keyword is used with the default _ keyword, the type converter
10211028is only applied if the default is a string.
10221029
1023- The argument to ``type `` can be any callable that accepts a single string.
1030+ The argument to ``type `` can be a callable that accepts a single string or
1031+ the name of a registered type (see :meth: `~ArgumentParser.register `)
10241032If the function raises :exc: `ArgumentTypeError `, :exc: `TypeError `, or
10251033:exc: `ValueError `, the exception is caught and a nicely formatted error
1026- message is displayed. No other exception types are handled.
1034+ message is displayed. Other exception types are not handled.
10271035
10281036Common built-in types and functions can be used as type converters:
10291037
@@ -1808,6 +1816,10 @@ Sub-commands
18081816 .. versionchanged :: 3.7
18091817 New *required * keyword-only parameter.
18101818
1819+ .. versionchanged :: 3.14
1820+ Subparser's *prog * is no longer affected by a custom usage message in
1821+ the main parser.
1822+
18111823
18121824FileType objects
18131825^^^^^^^^^^^^^^^^
@@ -2163,6 +2175,34 @@ Intermixed parsing
21632175 .. versionadded :: 3.7
21642176
21652177
2178+ Registering custom types or actions
2179+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2180+
2181+ .. method :: ArgumentParser.register(registry_name, value, object)
2182+
2183+ Sometimes it's desirable to use a custom string in error messages to provide
2184+ more user-friendly output. In these cases, :meth: `!register ` can be used to
2185+ register custom actions or types with a parser and allow you to reference the
2186+ type by their registered name instead of their callable name.
2187+
2188+ The :meth: `!register ` method accepts three arguments - a *registry_name *,
2189+ specifying the internal registry where the object will be stored (e.g.,
2190+ ``action ``, ``type ``), *value *, which is the key under which the object will
2191+ be registered, and object, the callable to be registered.
2192+
2193+ The following example shows how to register a custom type with a parser::
2194+
2195+ >>> import argparse
2196+ >>> parser = argparse.ArgumentParser()
2197+ >>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))
2198+ >>> parser.add_argument('--foo', type='hexadecimal integer')
2199+ _StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='hexadecimal integer', choices=None, required=False, help=None, metavar=None, deprecated=False)
2200+ >>> parser.parse_args(['--foo', '0xFA'])
2201+ Namespace(foo=250)
2202+ >>> parser.parse_args(['--foo', '1.2'])
2203+ usage: PROG [-h] [--foo FOO]
2204+ PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'
2205+
21662206Exceptions
21672207----------
21682208
0 commit comments