@@ -801,7 +801,8 @@ Only actions that consume command-line arguments (e.g. ``'store'``,
801
801
802
802
The recommended way to create a custom action is to extend :class: `Action `,
803
803
overriding the :meth: `!__call__ ` method and optionally the :meth: `!__init__ ` and
804
- :meth: `!format_usage ` methods.
804
+ :meth: `!format_usage ` methods. You can also register custom actions using the
805
+ :meth: `~ArgumentParser.register ` method and reference them by their registered name.
805
806
806
807
An example of a custom action::
807
808
@@ -1020,10 +1021,11 @@ necessary type-checking and type conversions to be performed.
1020
1021
If the type _ keyword is used with the default _ keyword, the type converter
1021
1022
is only applied if the default is a string.
1022
1023
1023
- The argument to ``type `` can be any callable that accepts a single string.
1024
+ The argument to ``type `` can be a callable that accepts a single string or
1025
+ the name of a registered type (see :meth: `~ArgumentParser.register `)
1024
1026
If the function raises :exc: `ArgumentTypeError `, :exc: `TypeError `, or
1025
1027
:exc: `ValueError `, the exception is caught and a nicely formatted error
1026
- message is displayed. No other exception types are handled.
1028
+ message is displayed. Other exception types are not handled.
1027
1029
1028
1030
Common built-in types and functions can be used as type converters:
1029
1031
@@ -2163,6 +2165,34 @@ Intermixed parsing
2163
2165
.. versionadded :: 3.7
2164
2166
2165
2167
2168
+ Registering custom types or actions
2169
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2170
+
2171
+ .. method :: ArgumentParser.register(registry_name, value, object)
2172
+
2173
+ Sometimes it's desirable to use a custom string in error messages to provide
2174
+ more user-friendly output. In these cases, :meth: `!register ` can be used to
2175
+ register custom actions or types with a parser and allow you to reference the
2176
+ type by their registered name instead of their callable name.
2177
+
2178
+ The :meth: `!register ` method accepts three arguments - a *registry_name *,
2179
+ specifying the internal registry where the object will be stored (e.g.,
2180
+ ``action ``, ``type ``), *value *, which is the key under which the object will
2181
+ be registered, and object, the callable to be registered.
2182
+
2183
+ The following example shows how to register a custom type with a parser::
2184
+
2185
+ >>> import argparse
2186
+ >>> parser = argparse.ArgumentParser()
2187
+ >>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))
2188
+ >>> parser.add_argument('--foo', type='hexadecimal integer')
2189
+ _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)
2190
+ >>> parser.parse_args(['--foo', '0xFA'])
2191
+ Namespace(foo=250)
2192
+ >>> parser.parse_args(['--foo', '1.2'])
2193
+ usage: PROG [-h] [--foo FOO]
2194
+ PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'
2195
+
2166
2196
Exceptions
2167
2197
----------
2168
2198
0 commit comments