Skip to content

Commit fcfdb55

Browse files
GH-122679: Add register() to argparse docs (#126939)
* Add register() to argparse docs * Add newline * Formatting * Fix codeblock * Move section * Add signature * Add newline * Fix indent * Fix indent take 2 * Rephrase * Simplify language * Address PR comments * Add references to register in type and action * Remove unnecessary reference * Rephrase and add success case
1 parent fd133d4 commit fcfdb55

File tree

1 file changed

+33
-3
lines changed

1 file changed

+33
-3
lines changed

Doc/library/argparse.rst

+33-3
Original file line numberDiff line numberDiff line change
@@ -801,7 +801,8 @@ Only actions that consume command-line arguments (e.g. ``'store'``,
801801

802802
The recommended way to create a custom action is to extend :class:`Action`,
803803
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.
805806

806807
An example of a custom action::
807808

@@ -1020,10 +1021,11 @@ necessary type-checking and type conversions to be performed.
10201021
If the type_ keyword is used with the default_ keyword, the type converter
10211022
is only applied if the default is a string.
10221023

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`)
10241026
If the function raises :exc:`ArgumentTypeError`, :exc:`TypeError`, or
10251027
: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.
10271029

10281030
Common built-in types and functions can be used as type converters:
10291031

@@ -2163,6 +2165,34 @@ Intermixed parsing
21632165
.. versionadded:: 3.7
21642166

21652167

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+
21662196
Exceptions
21672197
----------
21682198

0 commit comments

Comments
 (0)