"string" --- Operaciones comunes de cadena de caracteres
********************************************************

**Source code:** Lib/string.py

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

Ver también:

  Cadenas de caracteres --- str

  Métodos de las cadenas de caracteres


Constantes de cadenas
=====================

Las constantes definidas en este módulo son:

string.ascii_letters

   La concatenación de las constantes abajo descriptas
   "ascii_lowercase" y "ascii_uppercase".  Este valor es independiente
   de la configuración regional.

string.ascii_lowercase

   Las letras minúsculas "'abcdefghijklmnopqrstuvwxyz'".  Este valor
   es independiente de la configuración regional y no cambiará.

string.ascii_uppercase

   Las letras mayúsculas "'ABCDEFGHIJKLMNOPQRSTUVWXYZ'".  Este valor
   es independiente de la configuración regional y no cambiará.

string.digits

   La cadena "'0123456789'".

string.hexdigits

   La cadena "'0123456789abcdefABCDEF'".

string.octdigits

   La cadena de caracteres "'01234567'".

string.punctuation

   Cadena de caracteres ASCII que se consideran caracteres de
   puntuación en la configuración regional "C": "!"
   #$%&'()*+,-./:;<=>?@[\]^_`{|} ~".

string.printable

   Cadena de caracteres ASCII que se consideran imprimibles.  Esta es
   una combinación de "digits", "ascii_letters", "punctuation", y
   "whitespace".

string.whitespace

   Una cadena cuyos caracteres ASCII se consideran todos espacios en
   blanco. Esto incluye los caracteres espacio, tabulador, salto de
   línea, retorno, salto de página y tabulador vertical.


Formato de cadena de caracteres personalizado
=============================================

La clase cadena es una clase incorporada (*built-in*) que proporciona
la capacidad de realizar sustituciones complejas de variables y
formateo de valor a través del método "format()" descrito en **PEP
3101**.  La clase "Formatter" del módulo "string" permite crear y
personalizar sus propios comportamientos de formateo de cadena
utilizando la misma implementación que el método integrado "format()".

class string.Formatter

   La clase "Formatter" tiene los siguientes métodos públicos:

   format(format_string, /, *args, **kwargs)

      Método principal de la API.  Recibe una cadena de formato y
      argumentos posicionales y de palabra clave arbitrarios. Es sólo
      un envoltorio que llama a "vformat()".

      Distinto en la versión 3.7: Un argumento de cadena de formato
      ahora es solo posicional.

   vformat(format_string, args, kwargs)

      Esta función realiza es la que realmente hace el trabajo de
      formateo.  Se expone como una función independiente para los
      casos en los que desea pasar un diccionario predefinido de
      argumentos, en lugar de desempaquetar y volver a empaquetar el
      diccionario como argumentos individuales mediante la sintaxis
      "*args" y "**kwargs".  "vformat()" hace el trabajo de dividir la
      cadena de formato en datos de caracteres y campos de reemplazo.
      Llama a los diversos métodos descritos a continuación.

   Además de eso, la clase "Formatter" define varios métodos que se
   espera sean reemplazados por las subclases:

   parse(format_string)

      Itera sobre *format_string* y retorna un iterable de tuplas
      (*literal_text*, *field_name*, *format_spec*, *conversion*). Es
      usado por "vformat()" para dividir la cadena de caracteres en
      texto literal o en campos de reemplazo.

      Los valores en la tupla representan conceptualmente un intervalo
      de texto literal seguido por un único campo de reemplazo. Si no
      hay ningún texto literal (lo cual puede darse si dos campos de
      reemplazo ocurren consecutivamente), *literal_text* será una
      cadena de caracteres de longitud cero. Si no hay ningún campo de
      reemplazo, los valores de *field_name*, *format_spec* y
      *conversion* serán "None".

   get_field(field_name, args, kwargs)

      Dado un *field_name* retornado por "parse()" (véase arriba), el
      mismo es convertido a un objeto a formatear. retorna una tupla
      (*obj*, *used_key*). La versión por defecto toma cadenas de
      caracteres acorde a lo definido en **PEP 3101**, tales como
      "0[*name*]" o "*label.title*". *args* y *kwargs* se pasan al
      método "vformat()". El valor retornado *used_key* tiene el mismo
      significado que el parámetro *key* para "get_value()".

   get_value(key, args, kwargs)

      Recuperar un valor de campo determinado.  El argumento *key*
      será un entero o una cadena de caracteres.  Si es un entero,
      representa el índice del argumento posicional en *args*; si es
      una cadena, representa un argumento definido en *kwargs*.

      El parámetro *args* se establece como lista de argumentos
      posicionales en "vformat()", y el parámetro *kwargs* se
      establece como diccionario de argumentos de palabra clave.

      Para nombres de campo compuesto, estas funciones son únicamente
      llamadas para el primer componente del campo. Los componentes
      que le siguen son tratados a través de operaciones normales de
      atributo e indexación.

      Por ejemplo, la expresión de campo '0.name' haría que
      "get_value()" se llame con un argumento *key* igual a 0.  El
      atributo ''name'' se buscará después del retorno de
      "get_value()" llamando a la función incorporada "getattr()".

      Si el índice o la palabra clave hace referencia a un elemento
      que no existe, se debe generar un "IndexError" o un "KeyError".

   check_unused_args(used_args, args, kwargs)

      Implementa el chequeo de argumentos no utilizados si así se
      desea.  Los argumentos de esta función son el conjunto de todas
      las claves de argumento a las que se hizo referencia en la
      cadena de formato (enteros para argumentos posicionales y
      cadenas de caracteres para argumentos con nombre) y una
      referencia a los *args* y *kwargs* que se pasaron a *vformat*.
      El conjunto de *args* no utilizados se puede calcular a partir
      de estos parámetros. se asume que "check_unused_args()" genera
      una excepción si se produce un error en el chequeo.

   format_field(value, format_spec)

      "format_field()" simplemente llama a la función incorporada
      "format()".  El método se proporciona para que las subclases
      puedan sobrescribirlo.

   convert_field(value, conversion)

      Convierte el valor (retornado por "get_field()") dado un tipo de
      conversión (tal como la tupla retornada por el método
      "parse()"). La versión por defecto entiende los tipos de
      conversión 's' (str), 'r' (repr) y 'a' (ascii).


Sintaxis de formateo de cadena
==============================

El método "str.format()" y la clase "Formatter" comparten la misma
sintaxis para las cadenas de caracteres de formato (aunque en el caso
de "Formatter" las subclases pueden definir su propia sintaxis de
cadena de caracteres de formato).  La sintaxis es similar a la de
literales de cadena con formato pero hay algunas diferencias.

Las cadenas de caracteres de formato contienen "campos de reemplazo"
rodeados de llaves "{}". Todo lo que no está contenido entre llaves se
considera texto literal, que se copia sin cambios en la salida.  Si se
necesita incluir un carácter de llave en el texto literal, se puede
escapar duplicando: "{{" *and* "}}".

La gramática para un campo de reemplazo es la siguiente:

   replacement_field ::= "{" [field_name] ["!" conversion] [":" format_spec] "}"
   field_name        ::= arg_name ("." attribute_name | "[" element_index "]")*
   arg_name          ::= [identifier | digit+]
   attribute_name    ::= identifier
   element_index     ::= digit+ | index_string
   index_string      ::= <any source character except "]"> +
   conversion        ::= "r" | "s" | "a"
   format_spec       ::= format-spec:format_spec

En términos menos formales, el campo de reemplazo puede comenzar con
un *field_name* (nombre de campo) que especifica el objeto cuyo valor
se va a formatear e insertar en la salida en lugar del campo de
reemplazo. El nombre de campo (*field_name*) va seguido opcionalmente
de un campo *conversion* (conversión), que va precedido de un signo de
exclamación "'!'", y un *format_spec*, que va precedido de dos puntos
"':'".  Estos especifican un formato no predeterminado para el valor
de reemplazo.

Véase también la sección Especificación de formato Mini-Lenguaje.

The *field_name* itself begins with an *arg_name* that is either a
number or a keyword.  If it's a number, it refers to a positional
argument, and if it's a keyword, it refers to a named keyword
argument. An *arg_name* is treated as a number if a call to
"str.isdecimal()" on the string would return true. If the numerical
arg_names in a format string are 0, 1, 2, ... in sequence, they can
all be omitted (not just some) and the numbers 0, 1, 2, ... will be
automatically inserted in that order. Because *arg_name* is not quote-
delimited, it is not possible to specify arbitrary dictionary keys
(e.g., the strings "'10'" or "':-]'") within a format string. The
*arg_name* can be followed by any number of index or attribute
expressions. An expression of the form "'.name'" selects the named
attribute using "getattr()", while an expression of the form
"'[index]'" does an index lookup using "__getitem__()".

Distinto en la versión 3.1: Los especificadores de argumentos
posicionales pueden ser omitidos en "str.format()", así "'{}
{}'.format(a, b)" es equivalente a "'{0} {1}'.format(a, b)".

Distinto en la versión 3.4: Para la clase "Formatter", los
especificadores de argumento posicional pueden ser omitidos.

Algunos ejemplos simples de cadena de formato:

   "First, thou shalt count to {0}"  # References first positional argument
   "Bring me a {}"                   # Implicitly references the first positional argument
   "From {} to {}"                   # Same as "From {0} to {1}"
   "My quest is {name}"              # References keyword argument 'name'
   "Weight in tons {0.weight}"       # 'weight' attribute of first positional arg
   "Units destroyed: {players[0]}"   # First element of keyword argument 'players'.

El campo *conversion* causa una coerción de tipo antes del formateo.
Normalmente, el formateo es hecho el método "__format__()" del valor
mismo. Sin embargo, en algunos es deseable forzar el tipo a ser
formateado como una cadena de caracteres, sobrescribiendo su propia
definición de formateo. Cuando se convierte el valor a una cadena de
caracteres antes de llamar al método "__format__()", la lógica normal
de formateo es evitada.

Tres banderas de conversión son admitidas actualmente: "'!s'", que
llama a "str()" con el valor; "'!r'", que llama a "repr()"; y "'!a'"
que llama a "ascii()".

Algunos ejemplos:

   "Harold's a clever {0!s}"        # Calls str() on the argument first
   "Bring out the holy {name!r}"    # Calls repr() on the argument first
   "More {!a}"                      # Calls ascii() on the argument first

El campo *format_spec* contiene la especificación de cómo presentar el
valor, incluyendo detalles como ancho del campo, alineación, relleno,
precisión decimal, etc. Cada tipo de valor puede definir su propio
"mini lenguaje de formateo" o interpretación de *format_spec*.

La mayoría de los tipos integrados admiten un formateo común de mini-
idioma descrito en la siguiente sección.

Un campo *format_spec* también puede incluir campos de reemplazo
anidados dentro de él. Estos campos de reemplazo anidados pueden
contener un nombre de campo, una bandera de conversión y una
especificación de formato, pero no se permite anidamiento más
profundo.  Los campos de reemplazo dentro de *format_spec* se
sustituyen antes de que la cadena *format_spec* se interprete. Esto
permite especificar dinámicamente el formato de un valor.

Para más ejemplos, véase la sección Ejemplos de formateo.


Especificación de formato Mini-Lenguaje
---------------------------------------

Las "especificaciones de formato" son usadas dentro de campos de
reemplazo contenidos en una cadena de formateo para definir como se
presentan los valores individuales (véase Sintaxis de formateo de
cadena y f-strings). Los mismos pueden también ser pasados
directamente a la función incorporada "format()". Cada tipo
formateable puede definir cómo interpretar la especificación de
formato.

La mayoría de los tipos integrados implementan las siguientes opciones
para especificaciones de formato, aunque algunas de las opciones de
formateo sólo son posibles con los tipos numéricos.

Una convención general es que una especificación de formato vacía
produce el mismo resultado que llamar a la función "str()" con el
valor. Una especificación no vacía típicamente modifica el resultado.

La forma general de un *especificador estándar de formato* es:

   format_spec     ::= [[fill]align][sign]["z"]["#"]["0"][width][grouping_option]["." precision][type]
   fill            ::= <any character>
   align           ::= "<" | ">" | "=" | "^"
   sign            ::= "+" | "-" | " "
   width           ::= digit+
   grouping_option ::= "_" | ","
   precision       ::= digit+
   type            ::= "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"

Si se especifica un valor *align* válido, puede ir precedido por un
carácter *fill*, que puede ser cualquier carácter y cuyo valor
predeterminado es un espacio si se omite. No es posible utilizar una
llave literal (""{"" or ""}"") como el carácter *fill* en un formato
literal de cadena o cuando se utiliza el método "str.format()".  Sin
embargo, es posible insertar una llave con un campo de reemplazo
anidado.  Esta limitación no afecta a la función "format()".

El significado de las distintas opciones de alineación es el
siguiente:

+-----------+------------------------------------------------------------+
| Opción    | Significado                                                |
|===========|============================================================|
| "'<'"     | Fuerza el campo a ser alineado a la izquierda dentro del   |
|           | espacio disponible (éste es el comportamiento por defecto  |
|           | para la mayoría de los objetos).                           |
+-----------+------------------------------------------------------------+
| "'>'"     | Fuerza el campo a ser alineado a la derecha dentro del     |
|           | espacio disponible (éste es el comportamiento por defecto  |
|           | para números).                                             |
+-----------+------------------------------------------------------------+
| "'='"     | Fuerza el relleno a ser colocarlo después del signo (si    |
|           | existe) pero antes de los dígitos.  Esto se utiliza para   |
|           | imprimir campos con el formato '+000000120'. Esta opción   |
|           | de alineación solo es válida para tipos numéricos.  Se     |
|           | convierte en el valor predeterminado cuando '0' precede    |
|           | inmediatamente al ancho del campo.                         |
+-----------+------------------------------------------------------------+
| "'^'"     | Fuerza el centrado del campo dentro del espacio            |
|           | disponible.                                                |
+-----------+------------------------------------------------------------+

Notar que, a menos que se defina un ancho de campo mínimo, el ancho
del campo siempre tendrá el mismo tamaño que los datos para
rellenarlo, de modo que la opción de alineación no tiene ningún
significado en este caso.

La opción *sign* (signo) sólo es válida para los tipos numéricos y
puede ser una de las siguientes:

+-----------+------------------------------------------------------------+
| Opción    | Significado                                                |
|===========|============================================================|
| "'+'"     | indica que el signo debe ser usado tanto para los números  |
|           | positivos como negativos.                                  |
+-----------+------------------------------------------------------------+
| "'-'"     | indica que el signo debe ser usado sólo para números       |
|           | negativos (éste es el comportamiento por defecto).         |
+-----------+------------------------------------------------------------+
| espacio   | indica que el espacio inicial debe ser usado para números  |
|           | positivos y el signo menos para números negativos.         |
+-----------+------------------------------------------------------------+

La opción "'z'" convierte los valores de coma flotante de cero
negativos en cero positivos después de redondear al formato de
precisión. Esta opción solo es válida para los tipos de presentación
de coma flotante.

Distinto en la versión 3.11: Se agregó la opción "'z'" (véase también
**PEP 682**).

La opción "'#'" hace que la "forma alternativa" se utilice para la
conversión.  La forma alternativa se define de forma diferente para
diferentes tipos.  Esta opción solo es válida para los tipos entero,
flotante y complejo. Para los enteros, cuando se utiliza la salida
binaria, octal o hexadecimal, esta opción agrega el respectivo prefijo
"'0b'", "'0o'" o "'0x'" al valor de salida. Para los flotantes y
complejos, la forma alternativa hace que el resultado de la conversión
siempre contenga un carácter de punto decimal, incluso si no hay
dígitos que lo sigan. Normalmente, un carácter de punto decimal
aparece en el resultado de estas conversiones sólo si un dígito lo
sigue. Además, para las conversiones "'g'" y "'G'", los ceros finales
no se eliminan del resultado.

La opción "','" señala el uso de una coma como separador de miles. En
cambio, para un separador consciente de localización (*local aware*),
usar el tipo de presentación de enteros "'n'".

Distinto en la versión 3.1: Se agregó la opción "','" (véase también
**PEP 378**).

La opción "'_'" señaliza el uso del guión bajo como separador de miles
para tipos de presentación de punto flotante y para tipos de
presentación de enteros "'d'". Para los tipos de presentación de
enteros "'b'", "'o'", "'x'" y "'X'", el guión bajo se insertará cada 4
dígitos. Para otros tipos de presentación, especificar esta opción es
un error.

Distinto en la versión 3.6: Se agregó la opción "'_'" (véase también
**PEP 515**).

*width* es un entero decimal que define el ancho total de campo
mínimo, incluyendo prefijos, separadores y otros caracteres de
formateo. Si no se especifica, el ancho de campo será determinado por
el contenido.

Cuando no se proporciona ninguna alineación explícita, si el campo
*width* es precedido por un carácter cero ("'0'"), se habilita el
relleno cero con reconocimiento de signos para los tipos numéricos.
Esto equivale a un carácter *fill* de "'0'" con un tipo de *alignment*
de "'='".

Distinto en la versión 3.10: Anteponer el campo *width* por "'0'" ya
no afecta el alineamiento por defecto para cadenas de caracteres.

La *precisión* es un entero decimal que indica cuántos dígitos deben
mostrarse después del punto decimal para los tipos de presentación
"'f'" y "'F'", o antes y después del punto decimal para los tipos de
presentación "'g'" o "'G'". Para los tipos de presentación de cadena,
el campo indica el tamaño máximo del campo; en otras palabras, cuántos
caracteres se utilizarán del contenido del campo. La *precisión* no
está permitida para los tipos de presentación de enteros.

Finalmente, *type* (el tipo) determina como presentar los datos.

Los tipos de presentación cadena disponibles son:

   +-----------+------------------------------------------------------------+
   | Tipo      | Significado                                                |
   |===========|============================================================|
   | "'s'"     | Formato de cadena de caracteres. Éste es el tipo por       |
   |           | defecto y puede ser omitido.                               |
   +-----------+------------------------------------------------------------+
   | None      | Lo mismo que "'s'".                                        |
   +-----------+------------------------------------------------------------+

Los tipos disponibles para la presentación de enteros son:

   +-----------+------------------------------------------------------------+
   | Tipo      | Significado                                                |
   |===========|============================================================|
   | "'b'"     | Formato binario. retorna el número en base 2.              |
   +-----------+------------------------------------------------------------+
   | "'c'"     | Carácter. Convierte el entero en el carácter unicode       |
   |           | correspondiente antes de imprimirlo.                       |
   +-----------+------------------------------------------------------------+
   | "'d'"     | Decimal entero. retorna el número en base 10.              |
   +-----------+------------------------------------------------------------+
   | "'o'"     | Formato octal. retorna el número en base 8.                |
   +-----------+------------------------------------------------------------+
   | "'x'"     | Formato hexadecimal. retorna el número en base 16,         |
   |           | utilizando letras minúsculas para los dígitos superiores a |
   |           | 9.                                                         |
   +-----------+------------------------------------------------------------+
   | "'X'"     | Formato hexadecimal. retorna el número en base 16,         |
   |           | utilizando letras mayúsculas para los dígitos superiores a |
   |           | 9. En caso de que "'#'" se especifique, el prefijo "'0x'"  |
   |           | convertirá en "'0X'" también.                              |
   +-----------+------------------------------------------------------------+
   | "'n'"     | Número. Es lo mismo que "'d'", excepto que usa la          |
   |           | configuración regional actual para insertar el número      |
   |           | apropiado de caracteres separadores.                       |
   +-----------+------------------------------------------------------------+
   | None      | Lo mismo que "'d'".                                        |
   +-----------+------------------------------------------------------------+

Además de los tipos de presentación arriba expuestos, los enteros se
pueden formatear con los tipos de presentación de punto flotante
enumerados a continuación (excepto "'n'" y "None"). Al hacerlo,
"float()" se utiliza para convertir el entero en un número de punto
flotante antes de ser formateado.

Los tipos de presentación disponibles para valores  "float" y
"Decimal" son:

   +-----------+------------------------------------------------------------+
   | Tipo      | Significado                                                |
   |===========|============================================================|
   | "'e'"     | Notación científica. Para una precisión dada "p", formatea |
   |           | el número en notación científica con la letra "e"          |
   |           | separando el coeficiente del exponente. El coeficiente     |
   |           | tiene un dígito antes, y "p" dígitos después, del punto    |
   |           | decimal, para un total de "p + 1" dígitos significativos.  |
   |           | Cuando se no da una precisión, usa una precisión de "6"    |
   |           | dígitos después del punto decimal para "float", y muestra  |
   |           | todos los dígitos del coeficiente para "Decimal". Si no    |
   |           | hay dígitos después del punto decimal, el punto decimal    |
   |           | también es removido a no ser que se use la opción "#".     |
   +-----------+------------------------------------------------------------+
   | "'E'"     | Notación científica. Igual que "'e'" excepto que utiliza   |
   |           | una 'E' mayúscula como carácter separador.                 |
   +-----------+------------------------------------------------------------+
   | "'f'"     | Notación de punto fijo. Para una precisión dada "p",       |
   |           | formatea el número como un valor decimal con exactamente   |
   |           | "p" dígitos siguiendo el punto decimal. Cuando no se da    |
   |           | una precisión, usa una precisión de "6" dígitos después    |
   |           | del punto decimal para "float", y usa una precisión tan    |
   |           | grande como sea necesaria para mostrar todos los dígitos   |
   |           | del coeficiente para "Decimal". Si no hay dígitos después  |
   |           | del punto decimal, el punto decimal también es removido a  |
   |           | no ser que se use la opción "#".                           |
   +-----------+------------------------------------------------------------+
   | "'F'"     | Notación de punto fijo. Igual que "'f'", pero convierte    |
   |           | (nulos) "nan" a "NAN" e "inf" a "INF".                     |
   +-----------+------------------------------------------------------------+
   | "'g'"     | Formato general. Para una precisión dada "p >= 1",         |
   |           | redondea el número a "p" dígitos significativos y luego    |
   |           | formatea el resultado como formato de punto fijo o en      |
   |           | notación científica, dependiendo de su magnitud. Una       |
   |           | precisión de "0" es tratada como equivalente a una         |
   |           | precisión de "1".  Las reglas precisas son las siguientes: |
   |           | supongamos que el resultado formateado con el tipo de      |
   |           | presentación "'e'" y la precisión "p-1" tiene exponente    |
   |           | "exp".  Entonces, si "m <= exp < p", donde "m" es -4 para  |
   |           | *floats* y -6 para "Decimals", el número se formatea con   |
   |           | el tipo de presentación "'f'" y la precisión "p-1-exp".    |
   |           | De lo contrario, el número se formatea con el tipo de      |
   |           | presentación "'e'" y precisión "p-1". En ambos casos, los  |
   |           | ceros finales insignificantes se eliminan del significado, |
   |           | y el punto decimal también se elimina si no hay dígitos    |
   |           | restantes que lo sigan, a menos que se utilice la opción   |
   |           | "'#'".  Si no se da una precisión, usa una precisión de    |
   |           | "6" dígitos significativos para "float". Para "Decimal" el |
   |           | coeficiente del resultado se construye usando los dígitos  |
   |           | del coeficiente del valor; se usa notación científica para |
   |           | valores menores a "1e-6" en valor absoluto y valores donde |
   |           | el valor posicional del dígito menos significativo es      |
   |           | mayor a 1, de otra forma se usa notación de punto fijo.    |
   |           | Infinito positivo y negativo, cero positivo y negativo, y  |
   |           | nulos (*nans*) son respectivamente formateados como "inf", |
   |           | "-inf", "0", "-0" y "nan", independientemente de la        |
   |           | precisión.                                                 |
   +-----------+------------------------------------------------------------+
   | "'G'"     | Formato general. Igual que "'g'" excepto que cambia a      |
   |           | "'E'" si el número se vuelve muy grande. Las               |
   |           | representaciones de infinito y NaN también se convierten a |
   |           | mayúsculas.                                                |
   +-----------+------------------------------------------------------------+
   | "'n'"     | Número. Es lo mismo que "'g'", excepto que usa la          |
   |           | configuración local para insertar los caracteres           |
   |           | separadores de número apropiados.                          |
   +-----------+------------------------------------------------------------+
   | "'%'"     | Porcentaje. Multiplica el número por 100 y lo muestra en   |
   |           | formato fijo ("'f'") seguido del signo porcentaje.         |
   +-----------+------------------------------------------------------------+
   | None      | Para "float" esto es lo mismo que "'g'", excepto que       |
   |           | cuando se usa notación de punto fijo para formatear el     |
   |           | resultado, siempre incluye al menos un dígito pasado el    |
   |           | punto decimal. La precisión usada es tan larga como sea    |
   |           | necesaria para representar el valor dado fielmente.  Para  |
   |           | "Decimal", esto es lo mismo que "'g'" o "'G'" dependiendo  |
   |           | del valor de "context.capitals" para el contexto decimal   |
   |           | actual.  El efecto general es el de igualar la salida de   |
   |           | "str()" al ser alterada  por los otros modificadores de    |
   |           | formato.                                                   |
   +-----------+------------------------------------------------------------+


Ejemplos de formateo
--------------------

Esta sección contiene ejemplos de la sintaxis "str.format()" y
comparaciones con el antiguo método de formateo usando "%".

En la mayoría de los casos, la sintaxis es similar al antiguo formato
"%", con la adición de "{}" y con ":" utilizado en lugar de "%". Por
ejemplo, "'%03.2f'" puede ser traducido como "'{:03.2f}'".

La nueva sintaxis de formato también soporta opciones diferentes y
nuevas que se muestran en los ejemplos siguientes.

Accediendo argumentos por posición:

   >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
   'a, b, c'
   >>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ only
   'a, b, c'
   >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
   'c, b, a'
   >>> '{2}, {1}, {0}'.format(*'abc')      # unpacking argument sequence
   'c, b, a'
   >>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
   'abracadabra'

Accediendo argumentos por nombre:

   >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
   'Coordinates: 37.24N, -115.81W'
   >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
   >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
   'Coordinates: 37.24N, -115.81W'

Accediendo los atributos de los argumentos:

   >>> c = 3-5j
   >>> ('The complex number {0} is formed from the real part {0.real} '
   ...  'and the imaginary part {0.imag}.').format(c)
   'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
   >>> class Point:
   ...     def __init__(self, x, y):
   ...         self.x, self.y = x, y
   ...     def __str__(self):
   ...         return 'Point({self.x}, {self.y})'.format(self=self)
   ...
   >>> str(Point(4, 2))
   'Point(4, 2)'

Accediendo ítems de los argumentos:

   >>> coord = (3, 5)
   >>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
   'X: 3;  Y: 5'

Reemplazar "%s" y "%r":

   >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
   "repr() shows quotes: 'test1'; str() doesn't: test2"

Alinear el texto y especificar el ancho:

   >>> '{:<30}'.format('left aligned')
   'left aligned                  '
   >>> '{:>30}'.format('right aligned')
   '                 right aligned'
   >>> '{:^30}'.format('centered')
   '           centered           '
   >>> '{:*^30}'.format('centered')  # use '*' as a fill char
   '***********centered***********'

Reemplazar "%+f", "%-f", y "% f" y especificar el signo:

   >>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
   '+3.140000; -3.140000'
   >>> '{: f}; {: f}'.format(3.14, -3.14)  # show a space for positive numbers
   ' 3.140000; -3.140000'
   >>> '{:-f}; {:-f}'.format(3.14, -3.14)  # show only the minus -- same as '{:f}; {:f}'
   '3.140000; -3.140000'

Reemplazando "%x" y "%o" y convirtiendo el valor a diferentes bases:

   >>> # format also supports binary numbers
   >>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
   'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
   >>> # with 0x, 0o, or 0b as prefix:
   >>> "int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}".format(42)
   'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'

Usando la coma como separador de los miles:

   >>> '{:,}'.format(1234567890)
   '1,234,567,890'

Expresar un porcentaje:

   >>> points = 19
   >>> total = 22
   >>> 'Correct answers: {:.2%}'.format(points/total)
   'Correct answers: 86.36%'

Uso del formateo específico de tipo:

   >>> import datetime
   >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
   >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
   '2010-07-04 12:15:58'

Anidando argumentos y ejemplos más complejos:

   >>> for align, text in zip('<^>', ['left', 'center', 'right']):
   ...     '{0:{fill}{align}16}'.format(text, fill=align, align=align)
   ...
   'left<<<<<<<<<<<<'
   '^^^^^center^^^^^'
   '>>>>>>>>>>>right'
   >>>
   >>> octets = [192, 168, 0, 1]
   >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
   'C0A80001'
   >>> int(_, 16)
   3232235521
   >>>
   >>> width = 5
   >>> for num in range(5,12): 
   ...     for base in 'dXob':
   ...         print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
   ...     print()
   ...
       5     5     5   101
       6     6     6   110
       7     7     7   111
       8     8    10  1000
       9     9    11  1001
      10     A    12  1010
      11     B    13  1011


Cadenas de plantillas
=====================

Las cadenas de plantilla proporcionan sustituciones de cadenas de
caracteres más sencillas como se describe en **PEP 292**.  Un caso de
uso principal para las cadenas de plantilla es la internacionalización
(i18n) ya que en ese contexto, la sintaxis y la funcionalidad más
sencillas hacen la traducción más fácil que otras instalaciones de
formato de cadena de caracteres integradas en Python.  Como ejemplo de
una biblioteca creada sobre cadenas de plantilla para i18n, véase el
paquete flufl.i18n.

Las cadenas de caracteres de plantilla admiten sustituciones basadas
en "$" de acuerdo a las siguientes reglas:

* "$$" es un escape. Es reemplazado con un único "$".

* "$identifier" (identificador) nombra un comodín de sustitución que
  coincide con una clave de asignación de ""identifier""
  (identificador).  De forma predeterminada, ""identifier"" está
  restringido a cualquier cadena alfanumérica ASCII (insensible a
  mayúsculas/minúsculas e incluyendo los guiones bajos) que comience
  con un guión bajo o una letra ASCII.  El primer carácter no
  identificador después del carácter "$" termina esta especificación
  de comodín.

* "${identifier}" es equivalente a "$identifier". Es requerido cuando
  caracteres identificadores válidos siguen al comodín pero no son
  parte de él, por ejemplo ""${noun}ification"".

Cualquier otra aparición de "$" en la cadena de caracteres resultará
en una excepción "ValueError".

El módulo "string" provee una clase "Template" que implementa esas
reglas. Los métodos de "Template" son:

class string.Template(template)

   El constructor sólo lleva un argumento, la cadena plantilla.

   substitute(mapping={}, /, **kwds)

      Realiza la sustitución de plantilla y retorna una nueva cadena
      de caracteres. *mapping* (mapeo) es un objeto tipo diccionario
      con claves (*keys*) que coinciden con los *placeholders*
      (comodines) de la plantilla. Como alternativa, es posible pasar
      argumentos de palabra clave cuyas palabras clave son los
      *placeholders* (comodines). Cuando *mapping* y *kwds* son dados
      y hay elementos duplicados, los *placeholders* (comodines) de
      *kwds* tienen prioridad.

   safe_substitute(mapping={}, /, **kwds)

      Igual que "substitute()", excepto que si faltan comodines de
      *mapping* y *kwds*, en lugar de generar una excepción
      "KeyError", el comodín original aparecerá en la cadena de
      caracteres resultante intacta.  Además, a diferencia de
      "substitute()", cualquier otra aparición de "$" simplemente
      retornará "$" en lugar de generar "ValueError".

      Mientras que otras excepciones aún pueden ocurrir, este método
      es llamado "seguro" (*safe*) porque siempre intenta retornar una
      cadena de caracteres que pueda ser usada en lugar de levantar
      una excepción. Desde otro punto de vista, el método
      "safe_substitute()" es en realidad para nada seguro, dado que
      ignorará plantillas defectuosas con delimitadores colgados,
      llaves sin cerrar, o comodines que no son identificadores
      válidos en Python.

   is_valid()

      Retorna false si la plantilla tiene marcadores de posición no
      válidos que harán que "substitute()" lance "ValueError".

      Nuevo en la versión 3.11.

   get_identifiers()

      Retorna una lista de los identificadores válidos en la
      plantilla, en el orden en que aparecen por primera vez,
      ignorando cualquier identificador no válido.

      Nuevo en la versión 3.11.

   Las instancias de "Template" también proporcionan un atributo de
   datos públicos:

   template

      Éste es el objeto que se le pasa como argumento *template* al
      constructor. En general, no debería ser modificado, pero el
      acceso de sólo lectura (*read-only*) no es impuesto.

Aquí un ejemplo de cómo usar una plantilla (*Template*):

   >>> from string import Template
   >>> s = Template('$who likes $what')
   >>> s.substitute(who='tim', what='kung pao')
   'tim likes kung pao'
   >>> d = dict(who='tim')
   >>> Template('Give $who $100').substitute(d)
   Traceback (most recent call last):
   ...
   ValueError: Invalid placeholder in string: line 1, col 11
   >>> Template('$who likes $what').substitute(d)
   Traceback (most recent call last):
   ...
   KeyError: 'what'
   >>> Template('$who likes $what').safe_substitute(d)
   'tim likes $what'

Uso avanzado: es posible derivar subclases de "Template" para
personalizar la sintaxis de *placeholder*, caracteres de delimitación,
o bien la expresión regular entera usada para procesar cadenas de
plantillas. Para ello, es posible sobrescribir los siguientes
atributos de clase:

* *delimiter*: es la cadena de caracteres literal que describe al
  delimitador que introduce un comodín.  El valor predeterminado es
  "$".  Notar que esto *no debe* ser una expresión regular, ya que la
  implementación llamará a "re.escape()" en esta cadena de caracteres
  según sea necesario.  Tener en cuenta además, que se no puede
  cambiar el delimitador después haber creado la clase (es decir, se
  debe establecer un delimitador diferente en el espacio de nombres de
  la subclase).

* *idpattern* -- Esta es la expresión regular que describe el patrón
  para comodines fuera de las llaves.  El valor predeterminado es la
  expresión regular "(?a:[_a-z][_a-z0-9]*)".  Si se proporciona este
  argumento y *braceidpattern* es "None" este patrón también se
  aplicará a los comodines entre llaves.

  Nota:

    Dado que el valor predeterminado de *flags* es "re.IGNORECASE", el
    patrón "[a-z]" puede coincidir con algunos caracteres que no son
    ASCII. Por ello se utiliza aquí la bandera local "a".

  Distinto en la versión 3.7: *braceidpattern* puede ser usado para
  definir patrones separados, usados dentro y fuera de los corchetes.

* *braceidpattern* -- Es como *idpattern* pero describe el patrón para
  comodines entre llaves.  El valor por defecto es "None", lo que
  significa volver a *idpattern* (es decir, el mismo patrón se utiliza
  tanto dentro como fuera de las llaves). Si se proporciona, esto le
  permite definir diferentes patrones para comodines dentro y fuera de
  las llaves.

  Nuevo en la versión 3.7.

* *flags* -- Banderas de expresión regular que se aplicarán al
  compilar la expresión regular utilizada para reconocer
  sustituciones.  El valor por defecto es "re.IGNORECASE".  Téngase en
  cuenta que "re.VERBOSE" siempre se agregará a las banderas, por lo
  que *idpattern* (s) personalizado(s) debe(n) seguir las convenciones
  de expresiones regulares detalladas.

  Nuevo en la versión 3.2.

Como alternativa, se puede proporcionar el patrón de expresión regular
completo, reemplazando así el atributo de clase *pattern*.  Si eso
ocurre, el valor debe ser un objeto de expresión regular con cuatro
grupos de captura con nombre.  Los grupos de captura corresponden a
las reglas indicadas anteriormente, junto con la regla de marcador de
posición no válida:

* *escaped* -- Este grupo coincide con la secuencia de escape en el
  patrón predeterminado, por ejemplo, "$$".

* *named* -- Este grupo coincide con el nombre comodín fuera de las
  llaves. No debe incluir el delimitador del grupo de captura.

* *braced* -- Este grupo coincide con el nombre del comodín adjunto;
  no debe incluir ni el delimitador ni las llaves en el grupo de
  captura.

* *invalid* -- Este grupo se empareja con cualquier otro patrón de
  delimitación (usualmente un único carácter) y debe ser lo último en
  aparecer en la expresión regular.

Los métodos de esta clase generarán "ValueError" si el patrón coincide
con la plantilla sin que coincida uno de estos grupos nombrados.


Funciones de ayuda
==================

string.capwords(s, sep=None)

   Separa el argumento en dos palabras utilizando el método
   "str.split()", convierte a mayúsculas vía "str.capitalize()" y une
   las palabras en mayúscula con el método "str.join()". Si el segundo
   argumento opcional *sep* está ausente o es "None", los espacios en
   blanco se reemplazarán con un único espacio y los espacios en
   blanco iniciales y finales se eliminarán; caso contrario, *sep* se
   usa para separar y unir las palabras.
