"argparse" — Analizador sintáctico (*Parser*) para las opciones, argumentos y sub-comandos de la línea de comandos
******************************************************************************************************************

Nuevo en la versión 3.2.

**Código fuente:** Lib/argparse.py

======================================================================


Tutorial
^^^^^^^^

Esta página contiene la información de referencia de la API. Para una
introducción más amigable al análisis de la línea de comandos de
Python, echa un vistazo al argparse tutorial.

El módulo "argparse" facilita la escritura de interfaces de línea de
comandos amigables. El programa define qué argumentos requiere, y
"argparse" averiguará cómo analizar los de "sys.argv". El módulo
"argparse" también genera automáticamente mensajes de ayuda y de uso y
muestra errores cuando los usuarios dan parámetros incorrectos al
programa.


Ejemplo
=======

El siguiente código es un programa Python que toma una lista de
números enteros y obtiene la suma o el máximo:

   import argparse

   parser = argparse.ArgumentParser(description='Process some integers.')
   parser.add_argument('integers', metavar='N', type=int, nargs='+',
                       help='an integer for the accumulator')
   parser.add_argument('--sum', dest='accumulate', action='store_const',
                       const=sum, default=max,
                       help='sum the integers (default: find the max)')

   args = parser.parse_args()
   print(args.accumulate(args.integers))

Asumiendo que el código Python anterior se guarda en un archivo
llamado "prog.py", se puede ejecutar en la línea de comandos y
proporciona mensajes de ayuda útiles:

   $ python prog.py -h
   usage: prog.py [-h] [--sum] N [N ...]

   Process some integers.

   positional arguments:
    N           an integer for the accumulator

   optional arguments:
    -h, --help  show this help message and exit
    --sum       sum the integers (default: find the max)

Cuando se ejecuta con los parámetros apropiados, muestra la suma o el
máximo de los números enteros de la línea de comandos:

   $ python prog.py 1 2 3 4
   4

   $ python prog.py 1 2 3 4 --sum
   10

Si se pasan argumentos incorrectos, se mostrará un error:

   $ python prog.py a b c
   usage: prog.py [-h] [--sum] N [N ...]
   prog.py: error: argument N: invalid int value: 'a'

Las siguientes secciones te guiarán a través de este ejemplo.


Creando un analizador sintáctico (*parser*)
-------------------------------------------

El primer paso para usar "argparse" es crear un objeto
"ArgumentParser"

   >>> parser = argparse.ArgumentParser(description='Process some integers.')

El objeto "ArgumentParser" contendrá toda la información necesaria
para analizar la línea de comandos con los tipos de datos de Python.


Añadiendo argumentos
--------------------

Completar un "ArgumentParser" con información sobre los argumentos del
programa se hace realizando llamadas al método "add_argument()".
Generalmente, estas llamadas le dicen a "ArgumentParser" cómo capturar
las cadenas de caracteres de la línea de comandos y convertirlas en
objetos. Esta información se almacena y se usa cuando se llama a
"parse_args()". Por ejemplo:

   >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
   ...                     help='an integer for the accumulator')
   >>> parser.add_argument('--sum', dest='accumulate', action='store_const',
   ...                     const=sum, default=max,
   ...                     help='sum the integers (default: find the max)')

Más tarde, llamando a "parse_args()" retornará un objeto con dos
atributos, "integers" y "accumulate". El atributo "integers" será una
lista de uno o más enteros, y el atributo "accumulate" será la función
"sum()", si se especificó "--sum" en la línea de comandos, o la
función "max()" si no.


Analizando argumentos
---------------------

"ArgumentParser" analiza los argumentos mediante el método
"parse_args()". Éste inspeccionará la línea de comandos, convertirá
cada argumento al tipo apropiado y luego invocará la acción
correspondiente. En la mayoría de los casos, esto significa que un
simple objeto "Namespace" se construirá a partir de los atributos
analizados en la línea de comandos:

   >>> parser.parse_args(['--sum', '7', '-1', '42'])
   Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

En un *script*, "parse_args()" será llamado típicamente sin
argumentos, y la "ArgumentParser" determinará automáticamente los
argumentos de la línea de comandos de "sys.argv".


Objetos *ArgumentParser*
========================

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True)

   Crea un nuevo objeto "ArgumentParser". Todos los parámetros deben
   pasarse como argumentos de palabra clave. Cada parámetro tiene su
   propia descripción más detallada a continuación, pero en resumen
   son:

   * prog - El nombre del programa (default: "sys.argv[0]")

   * usage - La cadena de caracteres que describe el uso del programa
     (por defecto: generado a partir de los argumentos añadidos al
     analizador)

   * description - Texto a mostrar antes del argumento ayuda (por
     defecto: ninguno)

   * epilog - Texto a mostrar después del argumento ayuda (por
     defecto: ninguno)

   * parents - Una lista de objetos "ArgumentParser" cuyos argumentos
     también deberían ser incluidos

   * formatter_class - Una clase para personalizar la salida de la
     ayuda

   * prefix_chars - El conjunto de caracteres que preceden a los
     argumentos opcionales (por defecto: ‘-‘)

   * fromfile_prefix_chars - El conjunto de caracteres que preceden a
     los archivos de los cuales se deberían leer los argumentos
     adicionales (por defecto: "None")

   * argument_default - El valor global por defecto de los argumentos
     (por defecto: "None")

   * conflict_handler - La estrategia para resolver los opcionales
     conflictivos (normalmente es innecesaria)

   * add_help - Añade una opción "-h/--help" al analizador (por
     defecto: "True")

   * allow_abbrev - Permite abreviar las opciones largas si la
     abreviatura es inequívoca. (por defecto: "True")

   Distinto en la versión 3.5: se añadió el parámetro *allow_abbrev*.

   Distinto en la versión 3.8: En versiones anteriores, *allow_abbrev*
   también deshabilitaba la agrupación de banderas (*flags*) cortas
   como "-vv" para que sea "-v -v".

En las siguientes secciones se describe cómo se utiliza cada una de
ellas.


*prog*
------

Por defecto, los objetos "ArgumentParser" utilizan "sys.argv[0]" para
determinar cómo mostrar el nombre del programa en los mensajes de
ayuda. Este valor por defecto es casi siempre deseable porque hará que
los mensajes de ayuda coincidan con la forma en que el programa fue
invocado en la línea de comandos. Por ejemplo, considera un archivo
llamado "myprogram.py" con el siguiente código:

   import argparse
   parser = argparse.ArgumentParser()
   parser.add_argument('--foo', help='foo help')
   args = parser.parse_args()

La ayuda para este programa mostrará "myprogram.py" como el nombre del
programa (sin importar desde dónde se haya invocado el programa):

   $ python myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo help
   $ cd ..
   $ python subdir/myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo help

Para cambiar este comportamiento por defecto, se puede proporcionar
otro valor usando el argumento``prog=`` para "ArgumentParser":

   >>> parser = argparse.ArgumentParser(prog='myprogram')
   >>> parser.print_help()
   usage: myprogram [-h]

   optional arguments:
    -h, --help  show this help message and exit

Ten en cuenta que el nombre del programa, ya sea determinado a partir
de "sys.argv[0]" o del argumento "prog=" , está disponible para los
mensajes de ayuda usando el especificador de formato "%(prog)s".

   >>> parser = argparse.ArgumentParser(prog='myprogram')
   >>> parser.add_argument('--foo', help='foo of the %(prog)s program')
   >>> parser.print_help()
   usage: myprogram [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo of the myprogram program


uso
---

Por defecto, "ArgumentParser" determina el mensaje de uso a partir de
los argumentos que contiene:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('--foo', nargs='?', help='foo help')
   >>> parser.add_argument('bar', nargs='+', help='bar help')
   >>> parser.print_help()
   usage: PROG [-h] [--foo [FOO]] bar [bar ...]

   positional arguments:
    bar          bar help

   optional arguments:
    -h, --help   show this help message and exit
    --foo [FOO]  foo help

El mensaje por defecto puede ser sustituido con el argumento de
palabra clave "usage=":

   >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
   >>> parser.add_argument('--foo', nargs='?', help='foo help')
   >>> parser.add_argument('bar', nargs='+', help='bar help')
   >>> parser.print_help()
   usage: PROG [options]

   positional arguments:
    bar          bar help

   optional arguments:
    -h, --help   show this help message and exit
    --foo [FOO]  foo help

El especificador de formato "%(prog)s" está preparado para introducir
el nombre del programa en los mensajes de ayuda.


*description*
-------------

La mayoría de las llamadas al constructor "ArgumentParser" usarán el
argumento de palabra clave "description=". Este argumento da una breve
descripción de lo que hace el programa y cómo funciona. En los
mensajes de ayuda, la descripción se muestra entre la cadena de
caracteres de uso (*usage*) de la línea de comandos y los mensajes de
ayuda para los distintos argumentos:

   >>> parser = argparse.ArgumentParser(description='A foo that bars')
   >>> parser.print_help()
   usage: argparse.py [-h]

   A foo that bars

   optional arguments:
    -h, --help  show this help message and exit

Por defecto, la descripción será ajustada a una línea para que encaje
en el espacio dado. Para cambiar este comportamiento, revisa el
argumento formatter_class.


*epilog*
--------

A algunos programas les gusta mostrar una descripción adicional del
programa después de la descripción de los argumentos. Dicho texto
puede ser especificado usando el argumento "epilog=" para
"ArgumentParser":

   >>> parser = argparse.ArgumentParser(
   ...     description='A foo that bars',
   ...     epilog="And that's how you'd foo a bar")
   >>> parser.print_help()
   usage: argparse.py [-h]

   A foo that bars

   optional arguments:
    -h, --help  show this help message and exit

   And that's how you'd foo a bar

Al igual que con el argumento description, el texto "epilog=" está por
defecto ajustado a una línea, pero este comportamiento puede ser
modificado con el argumento formatter_class para "ArgumentParser".


*parents*
---------

A veces, varios analizadores comparten un conjunto de argumentos
comunes. En lugar de repetir las definiciones de estos argumentos, se
puede usar un único analizador con todos los argumentos compartidos y
pasarlo en el argumento "parents=" a "ArgumentParser". El argumento
"parents=" toma una lista de objetos "ArgumentParser", recoge todas
las acciones de posición y de opción de éstos, y añade estas acciones
al objeto "ArgumentParser" que se está construyendo:

   >>> parent_parser = argparse.ArgumentParser(add_help=False)
   >>> parent_parser.add_argument('--parent', type=int)

   >>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
   >>> foo_parser.add_argument('foo')
   >>> foo_parser.parse_args(['--parent', '2', 'XXX'])
   Namespace(foo='XXX', parent=2)

   >>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
   >>> bar_parser.add_argument('--bar')
   >>> bar_parser.parse_args(['--bar', 'YYY'])
   Namespace(bar='YYY', parent=None)

Ten en cuenta que la mayoría de los analizadores padre especificarán
"add_help=False". De lo contrario, el "ArgumentParser" verá dos
opciones "-h/—help" (una para el padre y otra para el hijo) y generará
un error.

Nota:

  Debes inicializar completamente los analizadores antes de pasarlos a
  través de "parents=". Si cambias los analizadores padre después del
  analizador hijo, esos cambios no se reflejarán en el hijo.


*formatter_class*
-----------------

los objetos "ArgumentParser" permiten personalizar el formato de la
ayuda especificando una clase de formato alternativa. Actualmente, hay
cuatro clases de este tipo:

class argparse.RawDescriptionHelpFormatter
class argparse.RawTextHelpFormatter
class argparse.ArgumentDefaultsHelpFormatter
class argparse.MetavarTypeHelpFormatter

"RawDescriptionHelpFormatter" y "RawTextHelpFormatter" dan más control
sobre cómo se muestran las descripciones de texto. Por defecto, los
objetos "ArgumentParser" ajustan a la línea los textos de description
y epilog en los mensajes de ayuda de la línea de comandos:

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     description='''this description
   ...         was indented weird
   ...             but that is okay''',
   ...     epilog='''
   ...             likewise for this epilog whose whitespace will
   ...         be cleaned up and whose words will be wrapped
   ...         across a couple lines''')
   >>> parser.print_help()
   usage: PROG [-h]

   this description was indented weird but that is okay

   optional arguments:
    -h, --help  show this help message and exit

   likewise for this epilog whose whitespace will be cleaned up and whose words
   will be wrapped across a couple lines

Pasar "RawDescriptionHelpFormatter" como "formatter_class=" indica que
description y epilog ya tienen el formato correcto y no deben ser
ajustados a la línea:

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     formatter_class=argparse.RawDescriptionHelpFormatter,
   ...     description=textwrap.dedent('''\
   ...         Please do not mess up this text!
   ...         --------------------------------
   ...             I have indented it
   ...             exactly the way
   ...             I want it
   ...         '''))
   >>> parser.print_help()
   usage: PROG [-h]

   Please do not mess up this text!
   --------------------------------
      I have indented it
      exactly the way
      I want it

   optional arguments:
    -h, --help  show this help message and exit

"RawTextHelpFormatter" mantiene espacios en blanco para todo tipo de
texto de ayuda, incluyendo descripciones de argumentos. Sin embargo,
varias líneas nuevas son reemplazadas por una sola. Si deseas
conservar varias líneas en blanco, añade espacios entre las nuevas
líneas.

"ArgumentDefaultsHelpFormatter" añade automáticamente información
sobre los valores por defecto a cada uno de los mensajes de ayuda de
los argumentos:

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
   >>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
   >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
   >>> parser.print_help()
   usage: PROG [-h] [--foo FOO] [bar [bar ...]]

   positional arguments:
    bar         BAR! (default: [1, 2, 3])

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   FOO! (default: 42)

"MetavarTypeHelpFormatter" utiliza el nombre del parámetro type para
cada argumento como el nombre a mostrar para sus valores (en lugar de
utilizar dest como lo hace el formato habitual):

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     formatter_class=argparse.MetavarTypeHelpFormatter)
   >>> parser.add_argument('--foo', type=int)
   >>> parser.add_argument('bar', type=float)
   >>> parser.print_help()
   usage: PROG [-h] [--foo int] float

   positional arguments:
     float

   optional arguments:
     -h, --help  show this help message and exit
     --foo int


*prefix_chars*
--------------

La mayoría de las opciones de la línea de comandos usarán "-" como
prefijo, por ejemplo "-f/--foo". Los analizadores que necesiten
soportar caracteres prefijo diferentes o adicionales, por ejemplo,
para opciones como "+f" o "/foo", pueden especificarlos usando el
argumento``prefix_chars=`` para el constructor *ArgumentParser*:

   >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
   >>> parser.add_argument('+f')
   >>> parser.add_argument('++bar')
   >>> parser.parse_args('+f X ++bar Y'.split())
   Namespace(bar='Y', f='X')

El argumento "prefix_chars=" tiene un valor por defecto de "'-'".
Proporcionar un conjunto de caracteres que no incluya "-" causará que
las opciones "-f/--foo" no sean inhabilitadas.


*fromfile_prefix_chars*
-----------------------

A veces, por ejemplo, cuando se trata de una lista de argumentos
particularmente larga, puede tener sentido mantener la lista de
argumentos en un archivo en lugar de escribirla en la línea de
comandos. Si el argumento "fromfile_prefix_chars=" se da al
constructor "ArgumentParser", entonces los argumentos que empiezan con
cualquiera de los caracteres especificados se tratarán como archivos,
y serán reemplazados por los argumentos que contienen. Por ejemplo:

   >>> with open('args.txt', 'w') as fp:
   ...     fp.write('-f\nbar')
   >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
   >>> parser.add_argument('-f')
   >>> parser.parse_args(['-f', 'foo', '@args.txt'])
   Namespace(f='bar')

Los argumentos leídos de un archivo deben ser por defecto uno por
línea (pero vea también "convert_arg_line_to_args()") y se tratan como
si estuvieran en el mismo lugar que el argumento de referencia del
archivo original en la línea de comandos. Así, en el ejemplo anterior,
la expresión "[‘-f’, ‘foo’, ‘@args.txt’]" se considera equivalente a
la expresión "[‘-f’, ‘foo’, ‘-f’, ‘bar’]".

El argumento``fromfile_prefix_chars=`` por defecto es "None", lo que
significa que los argumentos nunca serán tratados como referencias de
archivos.


*argument_default*
------------------

Generalmente, los valores por defecto de los argumentos se especifican
ya sea pasando un valor por defecto a "add_argument()" o llamando a
los métodos "set_defaults()" con un conjunto específico de pares
nombre-valor. A veces, sin embargo, puede ser útil especificar un
único valor por defecto para todos los argumentos del analizador. Esto
se puede lograr pasando el argumento de palabra clave
"argument_default=" a "ArgumentParser". Por ejemplo, para suprimir
globalmente la creación de atributos en las llamadas a "parse_args()"
, proporcionamos el argumento "argument_default=SUPPRESS":

   >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('bar', nargs='?')
   >>> parser.parse_args(['--foo', '1', 'BAR'])
   Namespace(bar='BAR', foo='1')
   >>> parser.parse_args([])
   Namespace()


*allow_abbrev*
--------------

Normalmente, cuando pasas una lista de argumentos al método
"parse_args()" de un "ArgumentParser", reconoce las abreviaturas de
las opciones largas.

Esta característica puede ser desactivada poniendo "allow_abbrev" a
"False":

   >>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
   >>> parser.add_argument('--foobar', action='store_true')
   >>> parser.add_argument('--foonley', action='store_false')
   >>> parser.parse_args(['--foon'])
   usage: PROG [-h] [--foobar] [--foonley]
   PROG: error: unrecognized arguments: --foon

Nuevo en la versión 3.5.


*conflict_handler*
------------------

Los objetos "ArgumentParser" no permiten dos acciones con la misma
cadena de caracteres de opción. Por defecto, los objetos
"ArgumentParser" lanzan una excepción si se intenta crear un argumento
con una cadena de caracteres de opción que ya está en uso:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-f', '--foo', help='old foo help')
   >>> parser.add_argument('--foo', help='new foo help')
   Traceback (most recent call last):
    ..
   ArgumentError: argument --foo: conflicting option string(s): --foo

A veces (por ejemplo, cuando se utiliza parents) puede ser útil anular
simplemente cualquier argumento antiguo con la misma cadena de
caracteres de opción. Para lograr este comportamiento, se puede
suministrar el valor "'resolve'" al argumento "conflict_handler=" de
"ArgumentParser":

   >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
   >>> parser.add_argument('-f', '--foo', help='old foo help')
   >>> parser.add_argument('--foo', help='new foo help')
   >>> parser.print_help()
   usage: PROG [-h] [-f FOO] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    -f FOO      old foo help
    --foo FOO   new foo help

Ten en cuenta que los objetos "ArgumentParser" sólo eliminan una
acción si todas sus cadenas de caracteres de opción están anuladas.
Así, en el ejemplo anterior, la antigua acción "-f/--foo" se mantiene
como la acción``-f``, porque sólo la cadena de caracteres de opción "
--foo" fue anulada.


*add_help*
----------

Por defecto, los objetos *ArgumentParser* añaden una opción que
simplemente muestra el mensaje de ayuda del analizador. Por ejemplo,
considera un archivo llamado "myprogram.py" que contiene el siguiente
código:

   import argparse
   parser = argparse.ArgumentParser()
   parser.add_argument('--foo', help='foo help')
   args = parser.parse_args()

Si "-h" o "--help" se indica en la línea de comandos, se imprimirá la
ayuda de *ArgumentParser*:

   $ python myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo help

Ocasionalmente, puede ser útil desactivar la inclusión de esta opción
de ayuda. Esto se puede lograr pasando "False" como argumento de
"add_help=" a "ArgumentParser":

   >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
   >>> parser.add_argument('--foo', help='foo help')
   >>> parser.print_help()
   usage: PROG [--foo FOO]

   optional arguments:
    --foo FOO  foo help

La opción de ayuda es típicamente "-h/--help". La excepción a esto es
si "prefix_chars=" se especifica y no incluye "-", en cuyo caso "-h" y
"--help" no son opciones válidas. En este caso, el primer carácter en
"prefix_chars" se utiliza para preceder a las opciones de ayuda:

   >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
   >>> parser.print_help()
   usage: PROG [+h]

   optional arguments:
     +h, ++help  show this help message and exit


El método *add_argument()*
==========================

ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])

   Define cómo se debe interpretar un determinado argumento de línea
   de comandos. Cada parámetro tiene su propia descripción más
   detallada a continuación, pero en resumen son:

   * name or flags - Ya sea un nombre o una lista de cadena de
     caracteres de opción, e.g. "foo" o "-f, --foo".

   * action - El tipo básico de acción a tomar cuando este argumento
     se encuentra en la línea de comandos.

   * nargs - El número de argumentos de la línea de comandos que deben
     ser consumidos.

   * const - Un valor fijo requerido por algunas selecciones de action
     y nargs.

   * default - El valor dado si el argumento está ausente de la línea
     de comandos.

   * type - El tipo al que debe convertirse el argumento de la línea
     de comandos.

   * choices - Un contenedor con los valores permitidos para el
     argumento.

   * required - Si se puede omitir o no la opción de la línea de
     comandos (sólo opcionales).

   * help - Una breve descripción de lo que hace el argumento.

   * metavar - Un nombre para el argumento en los mensajes de uso.

   * dest - El nombre del atributo que será añadido al objeto
     retornado por "parse_args()".

En las siguientes secciones se describe cómo se utiliza cada una de
ellas.


*name or flags*
---------------

El método "add_argument()" debe saber si se espera un argumento
opcional, como "-f" o "--foo", o un argumento posicional, como una
lista de nombres de archivos. Por lo tanto, los primeros argumentos
que se pasan a "add_argument()" deben ser una serie de indicadores
(*flags*), o un simple nombre de argumento (*name*). Por ejemplo, se
puede crear un argumento opcional como:

   >>> parser.add_argument('-f', '--foo')

mientras que un argumento posicional podría ser creado como:

   >>> parser.add_argument('bar')

Cuando se llama a "parse_args()" , los argumentos opcionales serán
identificados por el prefijo "-", y el resto de los argumentos serán
asumidos como posicionales:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-f', '--foo')
   >>> parser.add_argument('bar')
   >>> parser.parse_args(['BAR'])
   Namespace(bar='BAR', foo=None)
   >>> parser.parse_args(['BAR', '--foo', 'FOO'])
   Namespace(bar='BAR', foo='FOO')
   >>> parser.parse_args(['--foo', 'FOO'])
   usage: PROG [-h] [-f FOO] bar
   PROG: error: the following arguments are required: bar


*action*
--------

Los objetos "ArgumentParser" asocian los argumentos de la línea de
comandos con las acciones. Esta acciones pueden hacer casi cualquier
cosa con los argumentos de línea de comandos asociados a ellas, aunque
la mayoría de las acciones simplemente añaden un atributo al objeto
retornado por "parse_args()". El argumento de palabra clave "action"
especifica cómo deben ser manejados los argumentos de la línea de
comandos. Las acciones proporcionadas son:

* "'store'" - Esta sólo almacena el valor del argumento. Esta es la
  acción por defecto. Por ejemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo')
     >>> parser.parse_args('--foo 1'.split())
     Namespace(foo='1')

* "'store_const'" - Esta almacena el valor especificado por el
  argumento de palabra clave const . La acción "'store_const'" se usa
  más comúnmente con argumentos opcionales que especifican algún tipo
  de indicador (*flag*). Por ejemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='store_const', const=42)
     >>> parser.parse_args(['--foo'])
     Namespace(foo=42)

* "'store_true'" y "'store_false'" - Son casos especiales de
  "'store_const'" usados para almacenar los valores "True" y "False"
  respectivamente. Además, crean valores por defecto de "False" y
  "True" respectivamente. Por ejemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='store_true')
     >>> parser.add_argument('--bar', action='store_false')
     >>> parser.add_argument('--baz', action='store_false')
     >>> parser.parse_args('--foo --bar'.split())
     Namespace(foo=True, bar=False, baz=True)

* "'append'" - Esta almacena una lista, y añade cada valor del
  argumento a la lista. Esto es útil para permitir que una opción sea
  especificada varias veces. Ejemplo de uso:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='append')
     >>> parser.parse_args('--foo 1 --foo 2'.split())
     Namespace(foo=['1', '2'])

* "'append_const'" - Esta almacena una lista, y añade el valor
  especificado por el argumento de palabra clave const a la lista.
  (Nótese que el argumento de palabra clave const por defecto es
  "None".) La acción "'append_const'" es útil típicamente cuando
  múltiples argumentos necesitan almacenar constantes a la misma
  lista. Por ejemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
     >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
     >>> parser.parse_args('--str --int'.split())
     Namespace(types=[<class 'str'>, <class 'int'>])

* "'count'" - Esta cuenta el número de veces que un argumento de
  palabra clave aparece. Por ejemplo, esto es útil para incrementar
  los niveles de detalle:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--verbose', '-v', action='count', default=0)
     >>> parser.parse_args(['-vvv'])
     Namespace(verbose=3)

  Observa, *default* (el valor por defecto) será "None" a menos que
  explícitamente se establezca como *0*.

* "'help'" - Esta imprime un mensaje de ayuda completo para todas las
  opciones del analizador actual y luego termina. Por defecto, se
  añade una acción de ayuda automáticamente al analizador. Ver
  "ArgumentParser" para detalles de cómo se genera la salida.

* "’version’" - Esta espera un argumento de palabra clave "version="
  en la llamada "add_argument()", e imprime la información de la
  versión y finaliza cuando es invocada:

     >>> import argparse
     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
     >>> parser.parse_args(['--version'])
     PROG 2.0

* "’extend’" - Esta almacena una lista, y extiende cada valor del
  argumento a la lista. Ejemplo de uso:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
     >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
     Namespace(foo=['f1', 'f2', 'f3', 'f4'])

  Nuevo en la versión 3.8.

También puedes especificar una acción arbitraria pasando una subclase
*Action* u otro objeto que implemente la misma interfaz. La forma
recomendada de hacer esto es extender "Action", sobrescribiendo el
método``__call__`` y opcionalmente el método``__init__``.

Un ejemplo de una acción personalizada:

   >>> class FooAction(argparse.Action):
   ...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
   ...         if nargs is not None:
   ...             raise ValueError("nargs not allowed")
   ...         super().__init__(option_strings, dest, **kwargs)
   ...     def __call__(self, parser, namespace, values, option_string=None):
   ...         print('%r %r %r' % (namespace, values, option_string))
   ...         setattr(namespace, self.dest, values)
   ...
   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action=FooAction)
   >>> parser.add_argument('bar', action=FooAction)
   >>> args = parser.parse_args('1 --foo 2'.split())
   Namespace(bar=None, foo=None) '1' None
   Namespace(bar='1', foo=None) '2' '--foo'
   >>> args
   Namespace(bar='1', foo='2')

Para más detalles, ver "Action".


*nargs*
-------

Los objetos *ArgumentParser* suelen asociar un único argumento de
línea de comandos con una única acción a realizar. El argumento de
palabra clave "nargs" asocia un número diferente de argumentos de
línea de comandos con una sola acción. Los valores admitidos son:

* "N" (un entero). "N" argumentos de la línea de comandos se agruparán
  en una lista. Por ejemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs=2)
     >>> parser.add_argument('bar', nargs=1)
     >>> parser.parse_args('c --foo a b'.split())
     Namespace(bar=['c'], foo=['a', 'b'])

  Ten en cuenta que "nargs=1" produce una lista de un elemento. Esto
  es diferente del valor por defecto, en el que el elemento se produce
  por sí mismo.

* "’?’". Un argumento se consumirá desde la línea de comandos si es
  posible, y se generará como un sólo elemento. Si no hay ningún
  argumento de línea de comandos, se obtendrá el valor de default. Ten
  en cuenta que para los argumentos opcionales, hay un caso adicional
  - la cadena de caracteres de opción está presente pero no va seguida
  de un argumento de línea de comandos. En este caso se obtendrá el
  valor de const. Algunos ejemplos para ilustrar esto:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
     >>> parser.add_argument('bar', nargs='?', default='d')
     >>> parser.parse_args(['XX', '--foo', 'YY'])
     Namespace(bar='XX', foo='YY')
     >>> parser.parse_args(['XX', '--foo'])
     Namespace(bar='XX', foo='c')
     >>> parser.parse_args([])
     Namespace(bar='d', foo='d')

  Uno de los usos más comunes de "nargs='?'" es permitir archivos de
  entrada y salida opcionales:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
     ...                     default=sys.stdin)
     >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
     ...                     default=sys.stdout)
     >>> parser.parse_args(['input.txt', 'output.txt'])
     Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
               outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
     >>> parser.parse_args([])
     Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
               outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)

* "’*’". Todos los argumentos presentes en la línea de comandos se
  recogen en una lista. Ten en cuenta que generalmente no tiene mucho
  sentido tener más de un argumento posicional con "nargs=‘*’", pero
  es posible tener múltiples argumentos opcionales con "nargs=‘*’".
  Por ejemplo:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs='*')
     >>> parser.add_argument('--bar', nargs='*')
     >>> parser.add_argument('baz', nargs='*')
     >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
     Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

* "'+'". Al igual que "'*'", todos los argumentos de la línea de
  comandos se recogen en una lista. Además, se generará un mensaje de
  error si no había al menos un argumento presente en la línea de
  comandos. Por ejemplo:

     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('foo', nargs='+')
     >>> parser.parse_args(['a', 'b'])
     Namespace(foo=['a', 'b'])
     >>> parser.parse_args([])
     usage: PROG [-h] foo [foo ...]
     PROG: error: the following arguments are required: foo

* "argparse.REMAINDER". Todos los argumentos restantes de la línea de
  comandos se recogen en una lista. Esto es útil habitualmente para
  utilidades de línea de comandos que envían a otras utilidades de
  línea de comandos:

     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('--foo')
     >>> parser.add_argument('command')
     >>> parser.add_argument('args', nargs=argparse.REMAINDER)
     >>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split()))
     Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')

Si no se proporciona el argumento de palabra clave "nargs", el número
de argumentos consumidos se determina por action. Generalmente esto
significa que se consumirá un único argumento de línea de comandos y
se obtendrá un único elemento (no una lista).


*const*
-------

El argumento "const" de "add_argument()" se usa para mantener valores
constantes que no se leen desde la línea de comandos pero que son
necesarios para las diversas acciones de "ArgumentParser". Los dos
usos más comunes son:

* Cuando "add_argument()" se llama con "action='store_const'" o
  "action='append_const'". Estas acciones añaden el valor "const" a
  uno de los atributos del objeto retornado por "parse_args()". Mira
  la descripción action para ver ejemplos.

* Cuando "add_argument()" se llama con cadenas de caracteres de opción
  (como "-f" o "—foo") y "nargs=‘?’". Esto crea un argumento opcional
  que puede ir seguido de cero o un argumento de línea de comandos. Al
  analizar la línea de comandos, si la cadena de opciones se encuentra
  sin ningún argumento de línea de comandos que la siga, asumirá en su
  lugar el valor de "const". Mira la descripción nargs para ejemplos.

Con las acciones "'store_const'" y "'append_const'", se debe asignar
el argumento palabra clave "const". Para otras acciones, por defecto
es "None".


*default*
---------

Todos los argumentos opcionales y algunos argumentos posicionales
pueden ser omitidos en la línea de comandos. El argumento de palabra
clave "default" de "add_argument()", cuyo valor por defecto es "None",
especifica qué valor debe usarse si el argumento de línea de comandos
no está presente. Para los argumentos opcionales, se usa el valor
"default" cuando la cadena de caracteres de opción no está presente en
la línea de comandos:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', default=42)
   >>> parser.parse_args(['--foo', '2'])
   Namespace(foo='2')
   >>> parser.parse_args([])
   Namespace(foo=42)

Si el valor "default" es una cadena de caracteres, el analizador
procesa el valor como si fuera un argumento de la línea de comandos.
En particular, el analizador aplica cualquier argumento de conversión
type , si se proporciona, antes de establecer el atributo en el valor
de retorno "Namespace". En caso contrario, el analizador utiliza el
valor tal y como es:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--length', default='10', type=int)
   >>> parser.add_argument('--width', default=10.5, type=int)
   >>> parser.parse_args()
   Namespace(length=10, width=10.5)

Para argumentos posiciones con nargs igual a "?" o "*", el valor
"default" se utiliza cuando no hay ningún argumento de línea de
comandos presente:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('foo', nargs='?', default=42)
   >>> parser.parse_args(['a'])
   Namespace(foo='a')
   >>> parser.parse_args([])
   Namespace(foo=42)

Proporcionar "default=argparse.SUPPRESS" causa que no se agregue
ningún atributo si el argumento de la línea de comandos no está
presente:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
   >>> parser.parse_args([])
   Namespace()
   >>> parser.parse_args(['--foo', '1'])
   Namespace(foo='1')


*type*
------

Por defecto, los objetos "ArgumentParser" leen los argumentos de la
línea de comandos como simples cadenas de caracteres. Sin embargo, muy
a menudo la cadena de caracteres de la línea de comandos debe ser
interpretada como otro tipo, como una "float" o "int". El argumento de
palabra clave "type" de "add_argument()" permite realizar cualquier
comprobación y conversión de tipos que sea necesaria. Los tipos y
funciones incorporadas (*built-in*) comunes pueden ser usados
directamente como el valor del argumento "type":

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('foo', type=int)
   >>> parser.add_argument('bar', type=open)
   >>> parser.parse_args('2 temp.txt'.split())
   Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)

Consulta la sección sobre el argumento de palabra clave default para
obtener información sobre cuándo se aplica el argumento "type" a los
argumentos por defecto.

Para facilitar el uso de varios tipos de archivos, el módulo
*argparse* proporciona *FileType* de fábrica que toma los argumentos
"mode=", "bufsize=", "encoding=" y "errors=" de la función "open()".
Por ejemplo, "FileType('w')" puede usarse para crear un archivo
modificable:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('bar', type=argparse.FileType('w'))
   >>> parser.parse_args(['out.txt'])
   Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)

"type=" puede aceptar cualquier invocable que use un sólo argumento de
cadena de caracteres y retorne el valor convertido:

   >>> def perfect_square(string):
   ...     value = int(string)
   ...     sqrt = math.sqrt(value)
   ...     if sqrt != int(sqrt):
   ...         msg = "%r is not a perfect square" % string
   ...         raise argparse.ArgumentTypeError(msg)
   ...     return value
   ...
   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('foo', type=perfect_square)
   >>> parser.parse_args(['9'])
   Namespace(foo=9)
   >>> parser.parse_args(['7'])
   usage: PROG [-h] foo
   PROG: error: argument foo: '7' is not a perfect square

El argumento de palabra clave choices puede ser más conveniente para
las verificadoras de tipo que simplemente comparan contra un rango de
valores:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('foo', type=int, choices=range(5, 10))
   >>> parser.parse_args(['7'])
   Namespace(foo=7)
   >>> parser.parse_args(['11'])
   usage: PROG [-h] {5,6,7,8,9}
   PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)

Consulta la sección choices para más detalles.


*choices*
---------

Algunos argumentos de la línea de comandos deberían seleccionarse de
un conjunto restringido de valores. Estos pueden ser manejados pasando
un objeto contenedor como el argumento de palabra clave *choices* a
"add_argument()". Cuando se analiza la línea de comandos, se
comprueban los valores de los argumentos y se muestra un mensaje de
error si el argumento no era uno de los valores aceptables:

   >>> parser = argparse.ArgumentParser(prog='game.py')
   >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
   >>> parser.parse_args(['rock'])
   Namespace(move='rock')
   >>> parser.parse_args(['fire'])
   usage: game.py [-h] {rock,paper,scissors}
   game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
   'paper', 'scissors')

Ten en cuenta que la inclusión en el contenedor *choices* se comprueba
después de que se haya realizado cualquier conversión de type, por lo
que el tipo de los objetos del contenedor *choices* debe coincidir con
el type especificado:

   >>> parser = argparse.ArgumentParser(prog='doors.py')
   >>> parser.add_argument('door', type=int, choices=range(1, 4))
   >>> print(parser.parse_args(['3']))
   Namespace(door=3)
   >>> parser.parse_args(['4'])
   usage: doors.py [-h] {1,2,3}
   doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

Se puede pasar cualquier contenedor como el valor para *choices*, así
que los objetos "list", "set" , y los contenedores personalizados
están todos soportados.


*required*
----------

En general, el módulo "argparse" asume que los indicadores (*flags*)
como "-f" y "--bar" señalan argumentos *opcionales*, que siempre
pueden ser omitidos en la línea de comandos. Para hacer una opción
*requerida*, se puede especificar``True`` para el argumento de palabra
clave``required=`` en "add_argument()":

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', required=True)
   >>> parser.parse_args(['--foo', 'BAR'])
   Namespace(foo='BAR')
   >>> parser.parse_args([])
   usage: [-h] --foo FOO
   : error: the following arguments are required: --foo

Como muestra el ejemplo, si una opción está marcada como "required",
"parse_args()" informará de un error si esa opción no está presente en
la línea de comandos.

Nota:

  Las opciones requeridas están consideradas generalmente mala
  práctica porque los usuarios esperan que las *opciones* sean
  *opcionales*, y por lo tanto deberían ser evitadas cuando sea
  posible.


*help*
------

El valor "help" es una cadena de caracteres que contiene una breve
descripción del argumento. Cuando un usuario solicita ayuda
(normalmente usando "-h" o "--help" en la línea de comandos), estas
descripciones "help" se mostrarán con cada argumento:

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('--foo', action='store_true',
   ...                     help='foo the bars before frobbling')
   >>> parser.add_argument('bar', nargs='+',
   ...                     help='one of the bars to be frobbled')
   >>> parser.parse_args(['-h'])
   usage: frobble [-h] [--foo] bar [bar ...]

   positional arguments:
    bar     one of the bars to be frobbled

   optional arguments:
    -h, --help  show this help message and exit
    --foo   foo the bars before frobbling

Las cadenas de texto "help" pueden incluir varios descriptores de
formato para evitar la repetición de cosas como el nombre del programa
o el argumento default. Los descriptores disponibles incluyen el
nombre del programa, "%(prog)s" y la mayoría de los argumentos de
palabra clave de "add_argument()", por ejemplo "%(default)s",
"%(type)s", etc.:

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('bar', nargs='?', type=int, default=42,
   ...                     help='the bar to %(prog)s (default: %(default)s)')
   >>> parser.print_help()
   usage: frobble [-h] [bar]

   positional arguments:
    bar     the bar to frobble (default: 42)

   optional arguments:
    -h, --help  show this help message and exit

Como la cadena de caracteres de ayuda soporta el formato-%, si quieres
que aparezca un "%" literal en la ayuda, debes escribirlo como "%%".

"argparse" soporta el silenciar la ayuda para ciertas opciones,
ajustando el valor "help" a "argparse.SUPPRESS":

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('--foo', help=argparse.SUPPRESS)
   >>> parser.print_help()
   usage: frobble [-h]

   optional arguments:
     -h, --help  show this help message and exit


*metavar*
---------

Cuando "ArgumentParser" genera mensajes de ayuda, necesita alguna
forma de referirse a cada argumento esperado. Por defecto, los objetos
*ArgumentParser* utilizan el valor dest como "nombre" de cada objeto.
Por defecto, para las acciones de argumento posicional, el valor dest
se utiliza directamente, y para las acciones de argumento opcional, el
valor dest está en mayúsculas. Así, un único argumento posicional con
"dest='bar'" se denominará "bar". Un único argumento opcional "--foo"
que debería seguirse por un único argumento de línea de comandos se
denominará "FOO". Un ejemplo:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('bar')
   >>> parser.parse_args('X --foo Y'.split())
   Namespace(bar='X', foo='Y')
   >>> parser.print_help()
   usage:  [-h] [--foo FOO] bar

   positional arguments:
    bar

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO

Un nombre alternativo se puede especificar con "metavar":

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', metavar='YYY')
   >>> parser.add_argument('bar', metavar='XXX')
   >>> parser.parse_args('X --foo Y'.split())
   Namespace(bar='X', foo='Y')
   >>> parser.print_help()
   usage:  [-h] [--foo YYY] XXX

   positional arguments:
    XXX

   optional arguments:
    -h, --help  show this help message and exit
    --foo YYY

Ten en cuenta que "metavar" sólo cambia el nombre *mostrado* - el
nombre del atributo en el objeto "parse_args()" sigue estando
determinado por el valor dest.

Diferentes valores de "nargs" pueden causar que *metavar* sea usado
múltiples veces. Proporcionar una tupla a "metavar" especifica una
visualización diferente para cada uno de los argumentos:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x', nargs=2)
   >>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
   >>> parser.print_help()
   usage: PROG [-h] [-x X X] [--foo bar baz]

   optional arguments:
    -h, --help     show this help message and exit
    -x X X
    --foo bar baz


*dest*
------

La mayoría de las acciones "ArgumentParser" añaden algún valor como
atributo del objeto retornado por "parse_args()". El nombre de este
atributo está determinado por el argumento de palabra clave "dest" de
"add_argument()". Para acciones de argumento posicional, se
proporciona "dest" normalmente como primer argumento de
"add_argument()":

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('bar')
   >>> parser.parse_args(['XXX'])
   Namespace(bar='XXX')

Para las acciones de argumentos opcionales, el valor de "dest" se
infiere normalmente de las cadenas de caracteres de opción.
"ArgumentParser" genera el valor de "dest" tomando la primera cadena
de caracteres de opción larga y quitando la cadena inicial "--". Si no
se proporcionaron cadenas de caracteres de opción largas, "dest" se
derivará de la primera cadena de caracteres de opción corta quitando
el carácter "-". Cualquier carácter "-" interno se convertirá a
caracteres "_" para asegurarse de que la cadena de caracteres es un
nombre de atributo válido. Los ejemplos siguientes ilustran este
comportamiento:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('-f', '--foo-bar', '--foo')
   >>> parser.add_argument('-x', '-y')
   >>> parser.parse_args('-f 1 -x 2'.split())
   Namespace(foo_bar='1', x='2')
   >>> parser.parse_args('--foo 1 -y 2'.split())
   Namespace(foo_bar='1', x='2')

"dest" permite que se proporcione un nombre de atributo personalizado:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', dest='bar')
   >>> parser.parse_args('--foo XXX'.split())
   Namespace(bar='XXX')


Las clases *Action*
-------------------

Las clases *Action* implementan la API de *Action*, un invocable que
retorna un invocable que procesa los argumentos de la línea de
comandos. Cualquier objeto que siga esta API puede ser pasado como el
parámetro "action" a "add_argument()".

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Los objetos *Action* son utilizados por un *ArgumentParser* para
representar la información necesaria para analizar un sólo argumento
de una o más cadenas de caracteres de la línea de comandos. La clase
*Action* debe aceptar los dos argumentos de posición más cualquier
argumento de palabra clave pasado a "ArgumentParser.add_argument()"
excepto para la propia "action".

Las instancias de *Action* (o el valor de retorno de cualquier
invocable al parámetro "action" ) deben tener definidos los atributos
*”dest”*, *”option_strings”*, *”default”*, *”type”*, *”required”*,
*”help”*, etc. La forma más fácil de asegurar que estos atributos
estén definidos es llamar a "Action.__init__".

Las instancias de *Action* deben ser invocables, por lo que las
subclases deben anular el método "__call__", que debería aceptar
cuatro parámetros:

* "parser" - El objeto *ArgumentParser* que contiene esta acción.

* "namespace" - El objeto "Namespace" que será retornado por
  "parse_args()". La mayoría de las acciones añaden un atributo a este
  objeto usando "setattr()".

* "values" - Los argumentos de la línea de comandos asociados, con
  cualquier tipo de conversión aplicada. Las conversiones de tipos se
  especifican con el argumento de palabra clave type a
  "add_argument()".

* "option_string" - La cadena de caracteres de opción que se usó para
  invocar esta acción. El argumento "option_string" es opcional, y
  estará ausente si la acción está asociada a un argumento de
  posición.

El método "__call__" puede realizar acciones arbitrarias, pero
típicamente estable atributos en "namespace" basados en "dest" y
"values".


El método *parse_args()*
========================

ArgumentParser.parse_args(args=None, namespace=None)

   Convierte las cadenas de caracteres de argumentos en objetos y los
   asigna como atributos del espacio de nombres (*namespace*). Retorna
   el espacio de nombres (*namespace*) ocupado.

   Las llamadas previas a "add_argument()" determinan exactamente qué
   objetos se crean y cómo se asignan. Mira la documentación de
   "add_argument()" para más detalles.

   * args - Lista de cadenas de caracteres para analizar. El valor por
     defecto se toma de "sys.argv".

   * namespace - Un objeto para obtener los atributos. Por defecto es
     un nuevo objeto vacío "Namespace".


Sintaxis del valor de la opción
-------------------------------

El método "parse_args()" soporta diversas formas de especificar el
valor de una opción (si requiere uno). En el caso más simple, la
opción y su valor se pasan como dos argumentos separados:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x')
   >>> parser.add_argument('--foo')
   >>> parser.parse_args(['-x', 'X'])
   Namespace(foo=None, x='X')
   >>> parser.parse_args(['--foo', 'FOO'])
   Namespace(foo='FOO', x=None)

En el caso de opciones largas (opciones con nombres más largos que un
sólo carácter), la opción y el valor también se pueden pasar como un
sólo argumento de línea de comandos, utilizando "=" para separarlos:

   >>> parser.parse_args(['--foo=FOO'])
   Namespace(foo='FOO', x=None)

Para las opciones cortas (opciones de un sólo carácter de largo), la
opción y su valor pueden ser concatenados:

   >>> parser.parse_args(['-xX'])
   Namespace(foo=None, x='X')

Se pueden unir varias opciones cortas, usando un sólo prefijo "-",
siempre y cuando sólo la última opción (o ninguna de ellas) requiera
un valor:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x', action='store_true')
   >>> parser.add_argument('-y', action='store_true')
   >>> parser.add_argument('-z')
   >>> parser.parse_args(['-xyzZ'])
   Namespace(x=True, y=True, z='Z')


Argumentos no válidos
---------------------

Mientras analiza la línea de comandos, "parse_args()" comprueba una
variedad de errores, incluyendo opciones ambiguas, tipos no válidos,
opciones no válidas, número incorrecto de argumentos de posición, etc.
Cuando encuentra un error de este tipo, termina y muestra el error
junto con un mensaje de uso:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('--foo', type=int)
   >>> parser.add_argument('bar', nargs='?')

   >>> # invalid type
   >>> parser.parse_args(['--foo', 'spam'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: argument --foo: invalid int value: 'spam'

   >>> # invalid option
   >>> parser.parse_args(['--bar'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: no such option: --bar

   >>> # wrong number of arguments
   >>> parser.parse_args(['spam', 'badger'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: extra arguments found: badger


Argumentos conteniendo "-"
--------------------------

El método "parse_args()" busca generar errores cuando el usuario ha
cometido claramente una equivocación, pero algunas situaciones son
inherentemente ambiguas. Por ejemplo, el argumento de línea de
comandos "-1" podría ser un intento de especificar una opción o un
intento de proporcionar un argumento de posición. El método
"parse_args()" es cauteloso aquí: los argumentos de posición sólo
pueden comenzar con "-" si se ven como números negativos y no hay
opciones en el analizador que se puedan ver como números negativos

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x')
   >>> parser.add_argument('foo', nargs='?')

   >>> # no negative number options, so -1 is a positional argument
   >>> parser.parse_args(['-x', '-1'])
   Namespace(foo=None, x='-1')

   >>> # no negative number options, so -1 and -5 are positional arguments
   >>> parser.parse_args(['-x', '-1', '-5'])
   Namespace(foo='-5', x='-1')

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-1', dest='one')
   >>> parser.add_argument('foo', nargs='?')

   >>> # negative number options present, so -1 is an option
   >>> parser.parse_args(['-1', 'X'])
   Namespace(foo=None, one='X')

   >>> # negative number options present, so -2 is an option
   >>> parser.parse_args(['-2'])
   usage: PROG [-h] [-1 ONE] [foo]
   PROG: error: no such option: -2

   >>> # negative number options present, so both -1s are options
   >>> parser.parse_args(['-1', '-1'])
   usage: PROG [-h] [-1 ONE] [foo]
   PROG: error: argument -1: expected one argument

Si tienes argumentos de posición que deben comenzar con "-" y no
parecen números negativos, puedes insertar el pseudo-argumento "'--'"
que indica a "parse_args()" que todo lo que sigue es un argumento de
posición:

   >>> parser.parse_args(['--', '-f'])
   Namespace(foo='-f', one=None)


Abreviaturas de los argumentos (coincidencia de prefijos)
---------------------------------------------------------

El método "parse_args()" por defecto permite abreviar las opciones
largas a un prefijo, si la abreviatura es inequívoca (el prefijo
coincide con una opción única):

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-bacon')
   >>> parser.add_argument('-badger')
   >>> parser.parse_args('-bac MMM'.split())
   Namespace(bacon='MMM', badger=None)
   >>> parser.parse_args('-bad WOOD'.split())
   Namespace(bacon=None, badger='WOOD')
   >>> parser.parse_args('-ba BA'.split())
   usage: PROG [-h] [-bacon BACON] [-badger BADGER]
   PROG: error: ambiguous option: -ba could match -badger, -bacon

Se incurre en un error por argumentos que podrían derivar en más de
una opción. Esta característica puede ser desactivada poniendo
allow_abbrev a "False".


Más allá de "sys.argv"
----------------------

A veces puede ser útil tener un *ArgumentParser* analizando argumentos
que no sean los de "sys.argv". Esto se puede lograr pasando una lista
de cadenas de caracteres a "parse_args()". Esto es útil para probar en
el *prompt* interactivo:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument(
   ...     'integers', metavar='int', type=int, choices=range(10),
   ...     nargs='+', help='an integer in the range 0..9')
   >>> parser.add_argument(
   ...     '--sum', dest='accumulate', action='store_const', const=sum,
   ...     default=max, help='sum the integers (default: find the max)')
   >>> parser.parse_args(['1', '2', '3', '4'])
   Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
   >>> parser.parse_args(['1', '2', '3', '4', '--sum'])
   Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])


El objeto *Namespace*
---------------------

class argparse.Namespace

   Clase simple utilizada por defecto por "parse_args()" para crear un
   objeto que contenga atributos y retornarlo.

Esta clase es deliberadamente simple, sólo una subclase "object" con
una representación de cadena de texto legible. Si prefieres tener una
vista en forma de diccionario de los atributos, puedes usar el
lenguaje estándar de Python, "vars()":

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> args = parser.parse_args(['--foo', 'BAR'])
   >>> vars(args)
   {'foo': 'BAR'}

También puede ser útil tener un "ArgumentParser" que asigne atributos
a un objeto ya existente, en lugar de un nuevo objeto "Namespace".
Esto se puede lograr especificando el argumento de palabra clave
"namespace=":

   >>> class C:
   ...     pass
   ...
   >>> c = C()
   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
   >>> c.foo
   'BAR'


Otras utilidades
================


Sub-comandos
------------

ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_string][, dest][, required][, help][, metavar])

   Muchos programas dividen su funcionalidad en varios sub-comandos,
   por ejemplo, el programa "svn" puede llamar sub-comandos como "svn
   checkout", "svn update", y "svn commit". Dividir la funcionalidad
   de esta forma puede ser una idea particularmente buena cuando un
   programa realiza varias funciones diferentes que requieren
   diferentes tipos de argumentos en la línea de comandos.
   "ArgumentParser" soporta la creación de tales sub-comandos con el
   método "add_subparsers()". El método "add_subparsers()" se llama
   normalmente sin argumentos y retorna un objeto de acción especial.
   Este objeto tiene un único método, "add_parser()", que toma un
   nombre de comando y cualquier argumento de construcción
   "ArgumentParser", y retorna un objeto "ArgumentParser" que puede
   ser modificado de la forma habitual.

   Descripción de los parámetros:

   * *title* - título para el grupo del analizador secundario en la
     salida de la ayuda; por defecto *"subcommands"* si se proporciona
     la descripción, de lo contrario utiliza el título para los
     argumentos de posición

   * *description* - descripción para el grupo del analizador
     secundario en la salida de la ayuda, por defecto "None"

   * *prog* - información de uso que se mostrará con la ayuda de los
     sub-comandos, por defecto el nombre del programa y cualquier
     argumento de posición antes del argumento del analizador
     secundario

   * *parser_class* - clase que se usará para crear instancias de
     análisis secundario, por defecto la clase del analizador actual
     (por ejemplo, ArgumentParser)

   * action - el tipo básico de acción a tomar cuando este argumento
     se encuentre en la línea de comandos

   * dest - nombre del atributo en el que se almacenará el nombre del
     sub-comando; por defecto "None" y no se almacena ningún valor

   * required - Si se debe proporcionar o no un sub-comando, por
     defecto "False" (añadido en 3.7)

   * help - ayuda para el grupo de análisis secundario en la salida de
     la ayuda, por defecto "None"

   * metavar - cadena de caracteres que presenta los sub-comandos
     disponibles en la ayuda; por defecto es "None" y presenta los
     sub-comandos de la forma {cmd1, cmd2, ..}

   Algún ejemplo de uso:

      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('--foo', action='store_true', help='foo help')
      >>> subparsers = parser.add_subparsers(help='sub-command help')
      >>>
      >>> # create the parser for the "a" command
      >>> parser_a = subparsers.add_parser('a', help='a help')
      >>> parser_a.add_argument('bar', type=int, help='bar help')
      >>>
      >>> # create the parser for the "b" command
      >>> parser_b = subparsers.add_parser('b', help='b help')
      >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
      >>>
      >>> # parse some argument lists
      >>> parser.parse_args(['a', '12'])
      Namespace(bar=12, foo=False)
      >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
      Namespace(baz='Z', foo=True)

   Ten en cuenta que el objeto retornado por "parse_args()" sólo
   contendrá atributos para el analizador principal y el analizador
   secundario que fue seleccionado por la línea de comandos (y no
   cualquier otro analizador secundario). Así que en el ejemplo
   anterior, cuando se especifica el comando "a", sólo están presentes
   los atributos "foo" y "bar", y cuando se especifica el
   comando``b``, sólo están presentes los atributos "foo" y "baz".

   Del mismo modo, cuando se solicita un mensaje de ayuda de un
   analizador secundario, sólo se imprimirá la ayuda para ese
   analizador en particular. El mensaje de ayuda no incluirá mensajes
   del analizador principal o de analizadores relacionados. (Sin
   embargo, se puede dar un mensaje de ayuda para cada comando del
   analizador secundario suministrando el argumento "help=" a
   "add_parser()" como se ha indicado anteriormente).

      >>> parser.parse_args(['--help'])
      usage: PROG [-h] [--foo] {a,b} ...

      positional arguments:
        {a,b}   sub-command help
          a     a help
          b     b help

      optional arguments:
        -h, --help  show this help message and exit
        --foo   foo help

      >>> parser.parse_args(['a', '--help'])
      usage: PROG a [-h] bar

      positional arguments:
        bar     bar help

      optional arguments:
        -h, --help  show this help message and exit

      >>> parser.parse_args(['b', '--help'])
      usage: PROG b [-h] [--baz {X,Y,Z}]

      optional arguments:
        -h, --help     show this help message and exit
        --baz {X,Y,Z}  baz help

   El método "add_subparsers()" también soporta los argumentos de
   palabra clave``title`` y "description". Cuando cualquiera de los
   dos esté presente, los comandos del analizador secundario
   aparecerán en su propio grupo en la salida de la ayuda. Por
   ejemplo:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(title='subcommands',
      ...                                    description='valid subcommands',
      ...                                    help='additional help')
      >>> subparsers.add_parser('foo')
      >>> subparsers.add_parser('bar')
      >>> parser.parse_args(['-h'])
      usage:  [-h] {foo,bar} ...

      optional arguments:
        -h, --help  show this help message and exit

      subcommands:
        valid subcommands

        {foo,bar}   additional help

   Además, "add_parser" soporta un argumento adicional "aliases", que
   permite que múltiples cadenas se refieran al mismo analizador
   secundario. Este ejemplo, algo del estilo``svn``, alias "co" como
   abreviatura para "checkout":

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers()
      >>> checkout = subparsers.add_parser('checkout', aliases=['co'])
      >>> checkout.add_argument('foo')
      >>> parser.parse_args(['co', 'bar'])
      Namespace(foo='bar')

   Una forma particularmente efectiva de manejar los sub-comandos es
   combinar el uso del método "add_subparsers()" con llamadas a
   "set_defaults()" para que cada analizador secundario sepa qué
   función de Python debe ejecutar. Por ejemplo:

      >>> # sub-command functions
      >>> def foo(args):
      ...     print(args.x * args.y)
      ...
      >>> def bar(args):
      ...     print('((%s))' % args.z)
      ...
      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers()
      >>>
      >>> # create the parser for the "foo" command
      >>> parser_foo = subparsers.add_parser('foo')
      >>> parser_foo.add_argument('-x', type=int, default=1)
      >>> parser_foo.add_argument('y', type=float)
      >>> parser_foo.set_defaults(func=foo)
      >>>
      >>> # create the parser for the "bar" command
      >>> parser_bar = subparsers.add_parser('bar')
      >>> parser_bar.add_argument('z')
      >>> parser_bar.set_defaults(func=bar)
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('foo 1 -x 2'.split())
      >>> args.func(args)
      2.0
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('bar XYZYX'.split())
      >>> args.func(args)
      ((XYZYX))

   De esta manera, puedes dejar que "parse_args()" haga el trabajo de
   llamar a la función apropiada después de que el análisis de los
   argumentos se haya completado. Asociar funciones con acciones como
   esta es típicamente la forma más fácil de manejar las diferentes
   acciones para cada uno de tus analizadores secundarios. Sin
   embargo, si es necesario comprobar el nombre del analizador
   secundario que se ha invocado, el argumento de palabra clave "dest"
   a la llamada "add_subparsers()" hará el trabajo:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(dest='subparser_name')
      >>> subparser1 = subparsers.add_parser('1')
      >>> subparser1.add_argument('-x')
      >>> subparser2 = subparsers.add_parser('2')
      >>> subparser2.add_argument('y')
      >>> parser.parse_args(['2', 'frobble'])
      Namespace(subparser_name='2', y='frobble')

   Distinto en la versión 3.7: Nuevo argumento de palabra clave
   *required*.


Objetos *FileType*
------------------

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)

   El generador "FileType" crea objetos que pueden ser transferidos al
   argumento tipo de "ArgumentParser.add_argument()". Los argumentos
   que tienen objetos "FileType" como su tipo abrirán los argumentos
   de líneas de comandos como archivos con los modos, tamaños de
   búfer, codificaciones y manejo de errores solicitados (véase la
   función "open()" para más detalles):

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
      >>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
      >>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
      Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

   Los objetos *FileType* entienden el pseudo-argumento "'-'" y lo
   convierten automáticamente en "sys.stdin" para objetos de lectura
   "FileType" y "sys.stdout" para objetos de escritura "FileType":

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('infile', type=argparse.FileType('r'))
      >>> parser.parse_args(['-'])
      Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

   Nuevo en la versión 3.4: Los argumentos de palabra clave
   *encodings* y *errors*.


Grupos de argumentos
--------------------

ArgumentParser.add_argument_group(title=None, description=None)

   Por defecto, "ArgumentParser" agrupa los argumentos de la línea de
   comandos en "argumentos de posición" y "argumentos opcionales" al
   mostrar los mensajes de ayuda. Cuando hay una mejor agrupación
   conceptual de argumentos que esta predeterminada, se pueden crear
   grupos apropiados usando el método "add_argument_group()":

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group = parser.add_argument_group('group')
      >>> group.add_argument('--foo', help='foo help')
      >>> group.add_argument('bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--foo FOO] bar

      group:
        bar    bar help
        --foo FOO  foo help

   El método "add_argument_group()" retorna un objeto de grupo de
   argumentos que tiene un método "add_argument()" igual que un
   "ArgumentParser" convencional. Cuando se añade un argumento al
   grupo, el analizador lo trata como un argumento cualquiera, pero
   presenta el argumento en un grupo aparte para los mensajes de
   ayuda. El método "add_argument_group()" acepta los argumentos
   *title* y *description* que pueden ser usados para personalizar
   esta presentación:

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group1 = parser.add_argument_group('group1', 'group1 description')
      >>> group1.add_argument('foo', help='foo help')
      >>> group2 = parser.add_argument_group('group2', 'group2 description')
      >>> group2.add_argument('--bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--bar BAR] foo

      group1:
        group1 description

        foo    foo help

      group2:
        group2 description

        --bar BAR  bar help

   Ten en cuenta que cualquier argumento que no esté en los grupos
   definidos por el usuario terminará en las secciones habituales de
   "argumentos de posición" y "argumentos opcionales".


Exclusión mutua
---------------

ArgumentParser.add_mutually_exclusive_group(required=False)

   Crear un grupo de exclusividad mutua. "argparse" se asegurará de
   que sólo uno de los argumentos del grupo de exclusividad mutua esté
   presente en la línea de comandos:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group()
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args(['--foo'])
      Namespace(bar=True, foo=True)
      >>> parser.parse_args(['--bar'])
      Namespace(bar=False, foo=False)
      >>> parser.parse_args(['--foo', '--bar'])
      usage: PROG [-h] [--foo | --bar]
      PROG: error: argument --bar: not allowed with argument --foo

   El método "add_mutually_exclusive_group()" también acepta un
   argumento *required*, para indicar que se requiere al menos uno de
   los argumentos mutuamente exclusivos:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group(required=True)
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args([])
      usage: PROG [-h] (--foo | --bar)
      PROG: error: one of the arguments --foo --bar is required

   Ten en cuenta que actualmente los grupos de argumentos mutuamente
   exclusivos no admiten los argumentos *title* y *description* de
   "add_argument_group()".


Valores por defecto del analizador
----------------------------------

ArgumentParser.set_defaults(**kwargs)

   La mayoría de las veces, los atributos del objeto retornado por
   "parse_args()" se determinarán completamente inspeccionando los
   argumentos de la línea de comandos y las acciones de los
   argumentos. "set_defaults()" permite que se añadan algunos
   atributos adicionales que se determinan sin ninguna inspección de
   la línea de comandos:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('foo', type=int)
      >>> parser.set_defaults(bar=42, baz='badger')
      >>> parser.parse_args(['736'])
      Namespace(bar=42, baz='badger', foo=736)

   Ten en cuenta que los valores por defecto a nivel analizador
   siempre prevalecen sobre los valores por defecto a nivel argumento:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='bar')
      >>> parser.set_defaults(foo='spam')
      >>> parser.parse_args([])
      Namespace(foo='spam')

   Los valores por defecto a nivel analizador pueden ser muy útiles
   cuando se trabaja con varios analizadores. Consulta el método
   "add_subparsers()" para ver un ejemplo de este tipo.

ArgumentParser.get_default(dest)

   Obtiene el valor por defecto para un atributo del espacio de
   nombres (*namespace*), establecido ya sea por "add_argument()" o
   por "set_defaults()":

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='badger')
      >>> parser.get_default('foo')
      'badger'


Mostrando la ayuda
------------------

En la mayoría de las aplicaciones típicas, "parse_args()" se encargará
de dar formato y mostrar cualquier mensaje de uso o de error. Sin
embargo, hay varios métodos para dar formato disponibles:

ArgumentParser.print_usage(file=None)

   Muestra una breve descripción de cómo se debe invocar el
   "ArgumentParser" en la línea de comandos. Si *file* es "None", se
   asume "sys.stdout".

ArgumentParser.print_help(file=None)

   Muestra un mensaje de ayuda, incluyendo el uso del programa e
   información sobre los argumentos registrados en el
   "ArgumentParser". Si *file* es "None", se asume "sys.stdout".

También hay variantes de estos métodos que simplemente retornan una
cadena de caracteres en lugar de mostrarla:

ArgumentParser.format_usage()

   Retorna una cadena de caracteres que contiene una breve descripción
   de cómo se debe invocar el "ArgumentParser" en la línea de
   comandos.

ArgumentParser.format_help()

   Retorna una cadena de caracteres que contiene un mensaje de ayuda,
   incluyendo el uso del programa e información sobre los argumentos
   registrados en el "ArgumentParser".


Análisis parcial
----------------

ArgumentParser.parse_known_args(args=None, namespace=None)

A veces una secuencia de comandos (*script*) sólo puede analizar
algunos de los argumentos de la línea de comandos, pasando el resto de
los argumentos a otra secuencia o programa. En estos casos, el método
"parse_known_args()" puede ser útil. Funciona de forma muy parecida a
"parse_args()" excepto que no produce un error cuando hay argumentos
extra presentes. En lugar de ello, retorna una tupla de dos elementos
que contiene el espacio de nombres ocupado y la lista de argumentos de
cadena de caracteres restantes.

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action='store_true')
   >>> parser.add_argument('bar')
   >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
   (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

Advertencia:

  Coincidencia de prefijos las reglas se aplican a
  "parse_known_args()". El analizador puede consumir una opción aunque
  sea sólo un prefijo de una de sus opciones conocidas, en lugar de
  dejarla en la lista de argumentos restantes.


Personalizando el análisis de archivos
--------------------------------------

ArgumentParser.convert_arg_line_to_args(arg_line)

   Los argumentos que se leen de un archivo (mira el argumento de
   palabra clave *fromfile_prefix_chars* para el constructor
   "ArgumentParser") se leen uno por línea.
   "convert_arg_line_to_args()" puede ser invalidado para una lectura
   más elegante.

   Este método utiliza un sólo argumento *arg_line* que es una cadena
   de caracteres leída desde el archivo de argumentos. Retorna una
   lista de argumentos analizados a partir de esta cadena de
   caracteres. El método se llama una vez por línea leída del fichero
   de argumentos, en orden.

   Una alternativa útil de este método es la que trata cada palabra
   separada por un espacio como un argumento. El siguiente ejemplo
   demuestra cómo hacerlo:

      class MyArgumentParser(argparse.ArgumentParser):
          def convert_arg_line_to_args(self, arg_line):
              return arg_line.split()


Métodos de salida
-----------------

ArgumentParser.exit(status=0, message=None)

   Este método finaliza el programa, saliendo con el *status*
   especificado y, si corresponde, muestra un *message* antes de eso.
   El usuario puede anular este método para manejar estos pasos de
   manera diferente:

      class ErrorCatchingArgumentParser(argparse.ArgumentParser):
          def exit(self, status=0, message=None):
              if status:
                  raise Exception(f'Exiting because of an error: {message}')
              exit(status)

ArgumentParser.error(message)

   Este método imprime un mensaje de uso incluyendo el *message* para
   error estándar y finaliza el programa con código de estado 2.


Análisis entremezclado
----------------------

ArgumentParser.parse_intermixed_args(args=None, namespace=None)

ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)

Una serie de comandos *Unix* permiten al usuario mezclar argumentos
opcionales con argumentos de posición. Los métodos
"parse_intermixed_args()" y "parse_known_intermixed_args()" soportan
este modo de análisis.

Estos analizadores no soportan todas las capacidades de *argparse*, y
generarán excepciones si se utilizan capacidades no soportadas. En
particular, los analizadores secundarios, "argparse.REMAINDER", y los
grupos mutuamente exclusivos que incluyen tanto opcionales como de
posición no están soportados.

El siguiente ejemplo muestra la diferencia entre "parse_known_args()"
y "parse_intermixed_args()": el primero retorna "['2', '3']" como
argumentos sin procesar, mientras que el segundo recoge todos los de
posición en "rest".

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('cmd')
   >>> parser.add_argument('rest', nargs='*', type=int)
   >>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
   (Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
   >>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
   Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

"parse_known_intermixed_args()" retorna una tupla de dos elementos que
contiene el espacio de nombres poblado y la lista de los restantes
argumentos de cadenas de caracteres. "parse_intermixed_args()" arroja
un error si quedan argumentos de cadenas de caracteres sin procesar.

Nuevo en la versión 3.7.


Actualizar el código de *optparse*
==================================

Originalmente, el módulo "argparse" había intentado mantener la
compatibilidad con "optparse". Sin embargo, "optparse" era difícil de
extender de forma transparente, particularmente con los cambios
necesarios para soportar los nuevos especificadores "nargs=" y los
mensajes de uso mejorados. Cuando casi todo en "optparse" había sido
copiado y pegado o *monkey-patched*, ya no parecía práctico tratar de
mantener la retro-compatibilidad.

El módulo "argparse" mejora la biblioteca estándar del módulo
"optparse" de varias maneras, incluyendo:

* Manejando argumentos de posición.

* Soportando sub-comandos.

* Permitiendo prefijos de opción alternativos como "+" y "/".

* Manejando argumentos de estilo cero o más y uno o más.

* Generando mensajes de uso más informativos.

* Proporcionando una interfaz mucho más simple para "type" y "action"
  personalizadas.

Una manera de actualizar parcialmente de "optparse" a "argparse":

* Reemplaza todas las llamadas "optparse.OptionParser.add_option()"
  con llamadas "ArgumentParser.add_argument()".

* Reemplaza "(options, args) = parser.parse_args()" con "args =
  parser.parse_args()" y agrega las llamadas adicionales
  "ArgumentParser.add_argument()" para los argumentos de posición. Ten
  en cuenta que lo que antes se llamaba "options", ahora en el
  contexto "argparse" se llama "args".

* Reemplaza "optparse.OptionParser.disable_interspersed_args()" por
  "parse_intermixed_args()" en lugar de "parse_args()".

* Reemplaza las acciones de respuesta y los argumentos de palabra
  clave "callback_*" con argumentos de "type" o "action".

* Reemplaza los nombres de cadena de caracteres por argumentos de
  palabra clave "type" con los correspondientes objetos tipo (por
  ejemplo, *int*, *float*, *complex*, etc).

* Reemplaza "optparse.Values" por "Namespace" y "optparse.OptionError"
  y "optparse.OptionValueError" por "ArgumentError".

* Reemplaza las cadenas de caracteres con argumentos implícitos como
  "%default" o "%prog" por la sintaxis estándar de Python y usa
  diccionarios para dar formato a cadenas de caracteres, es decir,
  "%(default)s" y "%(prog)s".

* Reemplaza el argumento "version" del constructor *OptionParser* por
  una llamada a "parser.add_argument('--version', action='version',
  version='<the version>')".
