From e808645133675dfb140440896642dace051d7abc Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Sat, 12 Oct 2024 14:52:44 -0700 Subject: [PATCH 01/10] Add custom type converter to tutorial --- Doc/howto/argparse.rst | 62 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 30d9ac700376e6..1d467b7bd743b4 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -841,6 +841,68 @@ translated messages. To translate your own strings in the :mod:`argparse` output, use :mod:`gettext`. +Custom type converters +====================== + +The :mod:`argparse` module allows you to specify custom type converters for +your command-line arguments. This allows you to modify user input before it is +stored in the :class:`argparse.Namespace`. This can be useful when you need to +pre-process the input before it is used in your program. + +For example, let's say that you want to accept a string that represents a +fraction, and you want to convert it to a :class:`fractions.Fraction` object. + +Here is how you can do it:: + + import argparse + import fractions + + parser = argparse.ArgumentParser() + parser.add_argument("x", type=lambda s: fractions.Fraction(s)) + args = parser.parse_args() + print(type(args.x)) + +Output: + +.. code-block:: shell-session + + $ python prog.py 1/2 + + +You can also use custom type converters to handle more complex scenarios. For +example, let's say you want to handle arguments with different prefixes and +process them accordingly:: + + import argparse + + parser = argparse.ArgumentParser(prefix_chars='-+') + + parser.add_argument('-a', metavar='', action='append', + type=lambda x: ('-', x)) + parser.add_argument('+a', metavar='', action='append', + type=lambda x: ('+', x)) + + args = parser.parse_args('-a value1 +a value2'.split()) + print(args) + +Output: + +.. code-block:: shell-session + + $ python prog.py -a value1 +a value2 + Namespace(a=[('-', 'value1'), ('+', 'value2')]) + +In this example, we: +* Created a parser with custom prefix characters using the ``prefix_chars`` + parameter. + +* Defined two arguments, ``-a`` and ``+a``, which used the ``type`` parameter to + create custom type converters to prepend a prefix to the argument values. + +Without the custom type converters, the arguments would have treated the ``-a`` +and ``+a`` as the same flag, which would have been undesirable. By using custom +type converters, we were able to differentiate between the two arguments. + Conclusion ========== From bb9f41c883111693902d59dee4790063e802aec7 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Sat, 12 Oct 2024 14:55:39 -0700 Subject: [PATCH 02/10] Fix typo --- Doc/howto/argparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 1d467b7bd743b4..9afa44ba542fa4 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -845,7 +845,7 @@ Custom type converters ====================== The :mod:`argparse` module allows you to specify custom type converters for -your command-line arguments. This allows you to modify user input before it is +your command-line arguments. This allows you to modify user input before it's stored in the :class:`argparse.Namespace`. This can be useful when you need to pre-process the input before it is used in your program. @@ -900,7 +900,7 @@ In this example, we: create custom type converters to prepend a prefix to the argument values. Without the custom type converters, the arguments would have treated the ``-a`` -and ``+a`` as the same flag, which would have been undesirable. By using custom +and ``+a`` as the same argument, which would have been undesirable. By using custom type converters, we were able to differentiate between the two arguments. Conclusion From 4595acf13e6a0c1d05452248dffc0e1864f21afd Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Sat, 12 Oct 2024 14:57:24 -0700 Subject: [PATCH 03/10] Reword --- Doc/howto/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 9afa44ba542fa4..17f9629bf0b70e 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -897,7 +897,7 @@ In this example, we: parameter. * Defined two arguments, ``-a`` and ``+a``, which used the ``type`` parameter to - create custom type converters to prepend a prefix to the argument values. + create custom type converters to store the value in a tuple with the prefix. Without the custom type converters, the arguments would have treated the ``-a`` and ``+a`` as the same argument, which would have been undesirable. By using custom From cda70c520260d198e26b01d5aee2438f4efdd97e Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Sat, 12 Oct 2024 15:05:35 -0700 Subject: [PATCH 04/10] fix indentation --- Doc/howto/argparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 17f9629bf0b70e..26c8c0e12bc8e0 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -893,10 +893,10 @@ Output: Namespace(a=[('-', 'value1'), ('+', 'value2')]) In this example, we: -* Created a parser with custom prefix characters using the ``prefix_chars`` + * Created a parser with custom prefix characters using the ``prefix_chars`` parameter. -* Defined two arguments, ``-a`` and ``+a``, which used the ``type`` parameter to + * Defined two arguments, ``-a`` and ``+a``, which used the ``type`` parameter to create custom type converters to store the value in a tuple with the prefix. Without the custom type converters, the arguments would have treated the ``-a`` From b4b18e7160812abf7801f243695f4df1cc4b60b5 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Sat, 12 Oct 2024 15:12:06 -0700 Subject: [PATCH 05/10] fix indentation --- Doc/howto/argparse.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 26c8c0e12bc8e0..8559346a8211a2 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -891,12 +891,11 @@ Output: $ python prog.py -a value1 +a value2 Namespace(a=[('-', 'value1'), ('+', 'value2')]) - In this example, we: - * Created a parser with custom prefix characters using the ``prefix_chars`` +* Created a parser with custom prefix characters using the ``prefix_chars`` parameter. - * Defined two arguments, ``-a`` and ``+a``, which used the ``type`` parameter to +* Defined two arguments, ``-a`` and ``+a``, which used the ``type`` parameter to create custom type converters to store the value in a tuple with the prefix. Without the custom type converters, the arguments would have treated the ``-a`` From 44d83247759cfcf59e3ba1d6024ca4f6de08bb8f Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Sat, 12 Oct 2024 15:16:22 -0700 Subject: [PATCH 06/10] Fix indentation...I think --- Doc/howto/argparse.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 8559346a8211a2..4a7b6b41e86f92 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -891,7 +891,9 @@ Output: $ python prog.py -a value1 +a value2 Namespace(a=[('-', 'value1'), ('+', 'value2')]) + In this example, we: + * Created a parser with custom prefix characters using the ``prefix_chars`` parameter. From ecaed1222fd0e9cd1b988e262c969779848589e5 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Sat, 12 Oct 2024 15:17:55 -0700 Subject: [PATCH 07/10] Run pre-commit --- Doc/howto/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 4a7b6b41e86f92..34443d468db4b1 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -891,7 +891,7 @@ Output: $ python prog.py -a value1 +a value2 Namespace(a=[('-', 'value1'), ('+', 'value2')]) - + In this example, we: * Created a parser with custom prefix characters using the ``prefix_chars`` From f2ff33fa0de8703ed5efc810ce9bcb10333beb51 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Sun, 13 Oct 2024 13:30:09 -0700 Subject: [PATCH 08/10] Update Doc/howto/argparse.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/howto/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 34443d468db4b1..6f7d788e63470e 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -882,7 +882,7 @@ process them accordingly:: parser.add_argument('+a', metavar='', action='append', type=lambda x: ('+', x)) - args = parser.parse_args('-a value1 +a value2'.split()) + args = parser.parse_args() print(args) Output: From c6a7562f87b7c7e27d917a7804563569981139d3 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Sun, 13 Oct 2024 15:24:07 -0700 Subject: [PATCH 09/10] Add a note about how the custom type converter is called --- Doc/howto/argparse.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 6f7d788e63470e..dd89302de829b4 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -869,6 +869,12 @@ Output: $ python prog.py 1/2 + +When using a custom type converter, you can use any callable that takes a +single string argument (the argument value) and returns the converted value. +However, if you need to handle more complex scenarios, you can use a custom +action class with the **action** parameter instead. + You can also use custom type converters to handle more complex scenarios. For example, let's say you want to handle arguments with different prefixes and process them accordingly:: From 46e9454146fa0ffa0d59ede0ea327329e78c7950 Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski Date: Wed, 16 Oct 2024 19:49:26 -0700 Subject: [PATCH 10/10] Remove first example --- Doc/howto/argparse.rst | 24 +----------------------- 1 file changed, 1 insertion(+), 23 deletions(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index dd89302de829b4..1efbee64d60bb3 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -849,34 +849,12 @@ your command-line arguments. This allows you to modify user input before it's stored in the :class:`argparse.Namespace`. This can be useful when you need to pre-process the input before it is used in your program. -For example, let's say that you want to accept a string that represents a -fraction, and you want to convert it to a :class:`fractions.Fraction` object. - -Here is how you can do it:: - - import argparse - import fractions - - parser = argparse.ArgumentParser() - parser.add_argument("x", type=lambda s: fractions.Fraction(s)) - args = parser.parse_args() - print(type(args.x)) - -Output: - -.. code-block:: shell-session - - $ python prog.py 1/2 - - - When using a custom type converter, you can use any callable that takes a single string argument (the argument value) and returns the converted value. However, if you need to handle more complex scenarios, you can use a custom action class with the **action** parameter instead. -You can also use custom type converters to handle more complex scenarios. For -example, let's say you want to handle arguments with different prefixes and +For example, let's say you want to handle arguments with different prefixes and process them accordingly:: import argparse