Tipos internos
**************

As seções a seguir descrevem os tipos padrão que são incorporados ao
interpretador.

Os principais tipos internos são numéricos, sequências, mapeamentos,
classes, instâncias e exceções.

Algumas classes coletadas são mutáveis. Os métodos que adicionam,
subtraem, ou reorganizam seus membros no lugar, e não retornam um item
específico, nunca retornam a instância da coleção propriamente dita,
mas um "None".

Alguns operadores são suportados por diversos tipos de objeto; em
particular, praticamente todos os objetos podem ser comparados,
testados para o valor verdade, e convertidos para uma string (com a
função "repr()" ou a função ligeiramente diferente "str()" ). A última
função nesse caso é implicitamente usada quando um objeto é escrito
pela função "print()".


Teste do Valor Verdade
======================

Qualquer objeto pode ser testado quanto ao valor de verdade, para uso
em uma condição "if" ou "while" ou como operando das operações
booleanas abaixo.

Por padrão, um objeto é considerado verdadeiro, a menos que sua a
classe defina um método "__bool__()" que retorne "False" ou um método
método :meth:` __len__` que retorna zero, quando chamado com o objeto.
[1] Aqui estão a maioria dos objetos built-ins considerados falsos:

* constantes definidas como False: "None" e "False".

* zero de qualquer tipo numérico: "0", "0.0", "0j", "Decimal(0)",
  "Fraction(0, 1)"

* sequências vazias e coleções: "''", "()", "[]", "{}", "set()",
  "range(0)"

Operações e funções embutidas que têm um resultado Booleano retornam
"0" ou "False" para falso e "1" ou "True" para verdadeiro, salvo
indicações ao contrário. (Exceção importante: as operações Booleanas
"or" e "and" sempre retornam um de seus operandos.)


Operações booleanas --- "and", "or", "not"
==========================================

Esses são as operações Booleanas, ordenados por prioridade ascendente:

+---------------+-----------------------------------+---------+
| Operação      | Resultado                         | Notas   |
|===============|===================================|=========|
| "x or y"      | se *x* é falso, então *y*, do     | (1)     |
|               | contrário *x*                     |         |
+---------------+-----------------------------------+---------+
| "x and y"     | se *x* é falso, então *x*, do     | (2)     |
|               | contrário *y*                     |         |
+---------------+-----------------------------------+---------+
| "not x"       | se *x* é falso, então "True",     | (3)     |
|               | caso contrário "False"            |         |
+---------------+-----------------------------------+---------+

Notas:

1. Esse é um operador de curto-circuito, por isso só avalia o segundo
   argumento se o primeiro é falso.

2. Este é um operador de curto-circuito, por isso só avalia o segundo
   argumento se o primeiro é verdadeiro.

3. "not" tem uma baixa prioridade do que operadores não-Booleanos,
   então "not a == b" é interpretado como "not (a == b)", e "a == not
   b" é um erro de sintaxe.


Comparações
===========

Há oito operadores comparativos no Python. Todos eles possuem a mesma
prioridade (que é maior do que aquela das operações Booleanas).
Comparações podem ser acorrentadas arbitrariamente; por exemplo, "x <
y <= z" é equivalente a "x < y and y <= z", exceto que *y* é avaliado
apenas uma vez (porém em ambos os casos *z* não é avaliado de todo
quando "x < y" é sabido ser falso).

Esta tabela resume as operações de comparação:

+--------------+---------------------------+
| Operação     | Significado               |
|==============|===========================|
| "<"          | estritamente menor que    |
+--------------+---------------------------+
| "<="         | menor que ou igual        |
+--------------+---------------------------+
| ">"          | estritamente maior que    |
+--------------+---------------------------+
| ">="         | maior que ou igual        |
+--------------+---------------------------+
| "=="         | igual                     |
+--------------+---------------------------+
| "!="         | não é igual               |
+--------------+---------------------------+
| "is"         | identidade do objeto      |
+--------------+---------------------------+
| "is not"     | identidade de objeto      |
|              | negada                    |
+--------------+---------------------------+

Objetos de tipos diferentes, exceto tipos diferentes numéricos, nunca
comparam igual. Além disso, alguns tipos (por exemplo, objetos função)
suportam apenas uma noção degenerada de comparação onde dois objetos
desse tipo são desiguais. O operador "<", "<=", ">" e ">=" irá elencar
a exceção "TypeError" quando comparando um número complexo com outro
tipo numérico embutido, quando os objetos são de diferentes tipos que
não podem ser comparados, ou em outros casos quando não há ordem
definida.

Instâncias não idênticas de uma classe normalmente comparam-se como
desiguais ao menos que a classe defina o método "__eq__()".

Instâncias de uma classe não podem ser ordenadas com respeito a outras
instâncias da mesma classe, ou outros tipos de objeto, ao menos que a
classe defina o suficiente de métodos "__lt__()", "__le__()",
"__gt__()", e "__ge__()" (no geral, "__lt__()" e "__eq__()" são
suficientes, se você quiser o significado convencional dos operadores
de comparação).

O comportamento dos operadores de palavra chave "is" e "is not" não
podem ser personalizados; além disso eles podem ser aplicados a
qualquer objeto e nunca criam uma exceção.

Mais duas operações com a mesma prioridade sintática, "in" e "not in",
são suportadas por tipos que são *iterable* ou implementam o método
"__contains__()".


Tipos Numéricos --- "int", "float", "complex"
=============================================

Há três tipos numéricos distintos: *integers*, *floating point
numbers*, e *complex numbers*. Além do mais, Booleanos são um subtipo
dos integrais. Integrais possuem precisão ilimitada. Números de ponto
flutuante são usualmente implementados usando "double" em C;
informação sobre a precisão e representação interna de números com
ponto flutuante para a máquina na qual o seu programa está rodando é
disponibilizada em "sys.float_info". Números complexos possuem uma
parte real e imaginária, no qual cada uma é um número de ponto
flutuante. Para extrair essas partes de um número complexo *z*, use
"z.real" e "z.imag". (A biblioteca padrão inclui tipos numéricos
adicionais, "fractions" que possuem racionais, e "decimal" que possuem
números de ponto flutuante com precisão definida pelo usuário).

Números são criados por literais numéricos ou como resultado de
funções embarcadas e operadoras. Integrais literais planos (incluindo
números hexadecimais, octais e binários) culminam em integrais.
Literais numéricos contendo um ponto decimal ou um sinal exponencial
resultam em números de ponto flutuante. Anexando "'j'" ou
>>``<<'J'>>``<<para um literal numérico resulta em um número
imaginário (um número complexo com uma parte real zero) com a qual
você pode adicionar a um integral ou flutuante para receber um número
complexo com partes reais e imaginárias.

Python suporta completamente aritmética mista: quando um operador de
aritmética binária tem operandos de tipos numéricos diferentes, o
operando com o tipo mais "estreito" é ampliado para o tipo do outro
operando, onde um inteiro é mais estreito do que um ponto flutuante,
que por sua vez é mais estreito que um número complexo. Uma comparação
entre números de diferentes tipos se comporta como se os valores
exatos desses números estivessem sendo comparados. [2]

Os construtores "int()", "float()", e "complex()" podem ser usados
para produzir números de um tipo específico.

Todos os tipos numéricos (exceto complexos) suportam as seguintes
operações (para prioridades das operações, consulte Operator
precedence):

+-----------------------+-----------------------------------+-----------+----------------------+
| Operação              | Resultado                         | Notas     | Documentação         |
|                       |                                   |           | completa             |
|=======================|===================================|===========|======================|
| "x + y"               | soma de *x* e *y*                 |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "x - y"               | diferença de * x * e * y *        |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "x * y"               | produto de * x * e * y *          |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "x / y"               | quociente de *x* e *y*            |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "x // y"              | quociente flutuante of *x* and    | (1)       |                      |
|                       | *y*                               |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "x % y"               | restante de "x / y"               | (2)       |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "-x"                  | *x* negado                        |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "+x"                  | *x* inalterado                    |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "abs(x)"              | valor absoluto ou magnitude de    |           | "abs()"              |
|                       | *x*                               |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "int(x)"              | *x* convertido em inteiro         | (3)(6)    | "int()"              |
+-----------------------+-----------------------------------+-----------+----------------------+
| "float(x)"            | *x* convertido em ponto flutuante | (4)(6)    | "float()"            |
+-----------------------+-----------------------------------+-----------+----------------------+
| "complex(re, im)"     | um número complexo com parte real | (6)       | "complex()"          |
|                       | *re*, parte imaginária *im*. *im* |           |                      |
|                       | acarreta em zero.                 |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "c.conjugate()"       | conjugado do número complexo *c*  |           |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "divmod(x, y)"        | o par "(x // y, x % y)"           | (2)       | "divmod()"           |
+-----------------------+-----------------------------------+-----------+----------------------+
| "pow(x, y)"           | *x* elevado a *y*                 | (5)       | "pow()"              |
+-----------------------+-----------------------------------+-----------+----------------------+
| "x ** y"              | *x* elevado a *y*                 | (5)       |                      |
+-----------------------+-----------------------------------+-----------+----------------------+

Notas:

1. Também referido como uma divisão inteira. O valor resultante é um
   integral inteiro, embora o tipo oriundo do resultado não seja
   necessariamente int. O resultado é sempre arredondado para menos
   infinito:  "1//2" é "0", "(-1)//2" é "-1", "1//(-2)" é "-1", e
   "(-1)//(-2)" é "0".

2. Não para números complexos. Ao invés disso converte para flutuantes
   usando "abs()" se for apropriado.

3. Conversão de ponto flutuante para inteiro pode arredondar ou
   truncar como ocorre em C; veja as funções "math.floor()" e
   "math.ceil()" para conversões bem definidas.

4. ponto flutuante também aceita a string "nan" e "inf" com um prefixo
   opcional "+" ou "-" para Não é um Número (NaN) e infinidade
   positiva ou negativa.

5. Python define "pow(0, 0)" e "0 ** 0" sendo "1", como é comum para
   linguagens de programação.

6. Os literais numéricos aceitados incluem os dígitos de "0" a "9" ou
   qualquer equivalente Unicode (pontos de código com a propriedade
   "Nd").

   See http://www.unicode.org/Public/10.0.0/ucd/extracted/DerivedNume
   ricType.txt for a complete list of code points with the "Nd"
   property.

Todos os tipos "numbers.Real" ("int" and "float") também incluem as
seguintes operações.

+----------------------+-----------------------------------------------+
| Operação             | Resultado                                     |
|======================|===============================================|
| "math.trunc(x)"      | *x* truncado para "Integral"                  |
+----------------------+-----------------------------------------------+
| :func:>>`<<round(x[, | *x* arredondado para *n* dígitos,             |
| n]) 1`<round>        | arredondando metade para igualar. Se *n* é    |
|                      | omitido, ele toma o padrão de 0.              |
+----------------------+-----------------------------------------------+
| "math.floor(x)"      | o maior "Integral" <= *x*                     |
+----------------------+-----------------------------------------------+
| "math.ceil(x)"       | pelo menos "Integral" >= *x*                  |
+----------------------+-----------------------------------------------+

Para operações numéricas adicionais, consulte os módulos "math" e
"cmath".


Operações de bits em tipos inteiros
-----------------------------------

Operações bit a bit só fazem sentido para números inteiros. O
resultado de operações bit a bit é calculado como se fosse realizado
no complemento de dois com um número infinito de bits de sinal.

As prioridades das operações bitwise binárias são todas menores do que
as operações numéricas e maiores que as comparações; a operação unária
"~" tem a mesma prioridade que as outras operações numéricas unárias
("+" e "-").

Esta tabela lista as operações de bits classificadas em prioridade
ascendente:

+--------------+----------------------------------+------------+
| Operação     | Resultado                        | Notas      |
|==============|==================================|============|
| "x | y"      | bitwise *or* de *x* e *y*        | (4)        |
+--------------+----------------------------------+------------+
| "x ^ y"      | bitwise *exclusive or* de *x* e  | (4)        |
|              | *y*                              |            |
+--------------+----------------------------------+------------+
| "x & y"      | bitwise *and* de *x* e *y*       | (4)        |
+--------------+----------------------------------+------------+
| "x << n"     | *x* deslocado para a esquerda    | (1)(2)     |
|              | pelos bits *n*                   |            |
+--------------+----------------------------------+------------+
| "x >> n"     | *x* deslocado para a direita     | (1)(3)     |
|              | pelos bits *n*                   |            |
+--------------+----------------------------------+------------+
| "~x"         | os bits de *x* invertidos        |            |
+--------------+----------------------------------+------------+

Notas:

1. Contagens de deslocamento negativo são ilegais e causam o
   acionamento de um "ValueError" .

2. A left shift by *n* bits is equivalent to multiplication by "pow(2,
   n)".

3. A right shift by *n* bits is equivalent to floor division by
   "pow(2, n)".

4. Executar esses cálculos com pelo menos um bit de extensão de sinal
   extra na representação de complemento de dois finitos (uma largura
   de bit de trabalho "1+max(x.bit_length(), y.bit_length())" ou mais)
   é suficiente para obter o mesmo resultado como se houvesse um
   número infinito de bits de sinal.


Métodos adicionais em tipos inteiros
------------------------------------

O tipo int implementa a classe "numbers.Integral" *abstract base
class*. Além disso, ele provê mais alguns métodos:

int.bit_length()

   Retornar o número de bits necessários para representar um inteiro
   em binário, excluindo o sinal e entrelinha zeros:

      >>> n = -37
      >>> bin(n)
      '-0b100101'
      >>> n.bit_length()
      6

   Mais precisamente, se "x" for diferente de zero, então
   "x.bit_length()" é o único integral positivo "k" tal que``2**(k-1)
   <= abs(x) < 2**k``. Equvalentemente, quando "abs(x)" for menor o
   suficiente para ter um arredondamento algorítmicamente correto,
   então "k = 1 + int(log(abs(x), 2))". Se "x" é zero, então
   "x.bit_length()" retorna "0".

   Equivalente a:

      def bit_length(self):
          s = bin(self)       # binary representation:  bin(-37) --> '-0b100101'
          s = s.lstrip('-0b') # remove leading zeros and minus sign
          return len(s)       # len('100101') --> 6

   Novo na versão 3.1.

int.to_bytes(length, byteorder, *, signed=False)

   Retorna um array de bytes representando um inteiro.

   >>> (1024).to_bytes(2, byteorder='big')
   b'\x04\x00'
   >>> (1024).to_bytes(10, byteorder='big')
   b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00'
   >>> (-1024).to_bytes(10, byteorder='big', signed=True)
   b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00'
   >>> x = 1000
   >>> x.to_bytes((x.bit_length() + 7) // 8, byteorder='little')
   b'\xe8\x03'

   O inteiro é representado usando *length* bytes. Um "OverflowError"
   é elencado se um inteiro não é representável com o dado número de
   bytes.

   O argumento *byteorder* determina a ordem de bytes usada para
   representar um inteiro. Se o *byteorder* é ""big"", o byte mais
   significante está no início do array de byte. Se *byteorder* é
   ""little"", o byte mais significante está no final do array de
   byte. Para requisitar a ordem nativa de byte do sistema hospedeiro,
   use "sys.byteorder"  como o valor da ordem de byte.

   O argumento *signed* determina aonde o modo de complemento de dois
   é usado para representar o inteiro. Se *signed* é "False" e um
   inteiro negativo é dado, um "OverflowError" é disparado. O valor
   padrão para *signed* é "False".

   Novo na versão 3.2.

classmethod int.from_bytes(bytes, byteorder, *, signed=False)

   Retorna o inteiro representado pelo dado array de bytes.

   >>> int.from_bytes(b'\x00\x10', byteorder='big')
   16
   >>> int.from_bytes(b'\x00\x10', byteorder='little')
   4096
   >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True)
   -1024
   >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False)
   64512
   >>> int.from_bytes([255, 0, 0], byteorder='big')
   16711680

   O argumento *bytes* precisa ou ser um *bytes-like object* ou um
   iterador produzindo bytes.

   O argumento *byteorder* determina a ordem de bytes usada para
   representar um inteiro. Se o *byteorder* é ""big"", o byte mais
   significante está no início do array de byte. Se *byteorder* é
   ""little"", o byte mais significante está no final do array de
   byte. Para requisitar a ordem nativa de byte do sistema hospedeiro,
   use "sys.byteorder"  como o valor da ordem de byte.

   O arguemento *signed* indica quando o complemento de dois é usado
   para representar o inteiro.

   Novo na versão 3.2.


Métodos Adicionais em Ponto Flutuante
-------------------------------------

O tipo float implementa "numbers.Real" *abstract base class*. float
também possui os seguintes métodos adicionais.

float.as_integer_ratio()

   Retorna um par de inteiros dos quais a proporção é exatamente igual
   ao float original e com um denominador positivo. Levanta um
   "OverflowError" em infinidades e um "ValueError" em NaNs.

float.is_integer()

   Retornar "True" se a instância do float for finita com o valor
   integral e "False", caso contrário:

      >>> (-2.0).is_integer()
      True
      >>> (3.2).is_integer()
      False

Dois métodos suportam conversão para e de cadeias hexadecimais. Uma
vez que os flutuadores do Python são armazenados internamente como
números binários, a conversão de um flutuador para ou de uma seqüência
*decimal* geralmente envolve um pequeno erro de arredondamento. Em
contraste, as frases hexadecimais permitem a representação exata e a
especificação de números de ponto flutuante. Isso pode ser útil na
depuração e no trabalho numérico.

float.hex()

   Retorna a representação de um número de ponto-flutuante como uma
   string hexadecimal. Para números de ponto-flutuante finitos, essa
   representação vai sempre incluir um "0x" inicial e um "p" final e
   expoente.

classmethod float.fromhex(s)

   Método de classe para retornar um float representado por uma string
   hexadecimal *s*. A string *s* pode ter espaços em branco iniciais e
   finais.

Note que "float.hex()" é um método de instância, enquanto
"float.fromhex()" é um método de classe.

Uma string hexadecimal toma a forma:

   [sign] ['0x'] integer ['.' fraction] ['p' exponent]

aonde o sinal "sign" opcional pode ser tanto "+" or "-", "integer" e
"fraction" são strings de dígitos hexadecimais, e "exponent" é um
inteiro decimal com um símbolo precedente opcional. Case não é
significante, e deve haver ao menos um dígito hexadecimal tanto no
inteiro ou na fração. Essa síntaxe é similar à síntaxe especificada na
seção 6.4.4.2 do padrão C99, e também do da síntaxe usada no Java 1.5
em diante. Em particular, a saída de "float.hex()" é usável como um
literal hexadecimal de ponto-flutuante em código C ou Java, e
hexadecimal strings produzidas pelo formato do caráctere do C's
"%a``ou ``Double.toHexString" do Java são aceitos pelo
"float.fromhex()".

Note que o expoente é escrito em decimal ao invés de hexadecimal, e
que ele dá a potência de 2 pela qual se multiplica o coeficiente.  Por
exemplo, a string hexadecimal "0x3.a7p10" representa o número de
ponto-flutuante "(3 + 10./16 + 7./16**2) * 2.0**10", ou "3740.0":

   >>> float.fromhex('0x3.a7p10')
   3740.0

Aplicando a conversão reversa a "3740.0" retorna uma string
hexadecimal diferente representada pelo mesmo número:

   >>> float.hex(3740.0)
   '0x1.d380000000000p+11'


Hashing de tipos numéricos
--------------------------

Para números "x" e "y", possivelmente de diferentes tipos, é um
requerimento que "hash(x) == hash(y)" sempre que "x == y" (veja o
método: meth:*__hash__*  e sua documentação para mais detalhes). Para
facilitar a implementação e eficiência através de uma varidade de
tipos numéricos (incluindo: class:*int*, "float", "decimal.Decimal" e
"fractions.Fraction"), o hash do Python para tipos numéricos é baseado
em uma única funcão matemática que é definida para qualquer número
racional, e portanto se aplica para todas as instâncias de "int" e
"fractions.Fraction", e todas as instâncias finitas das classes
"float" e "decimal.Decimal". Essencialmente, essa função é dada pelo
modulo de redução "P" para um primo fixado "P". O valor de "P" é
disponibilizado ao Python como um atributo "modulus" do
"sys.hash_info".

**CPython implementation detail:** Atualmente, o primo usado é "P =
2**31 - 1" em máquinas com 32-bit e inteiros C longos e "P = 2**61 -
1" em máquinas com longs C de 64-bit.

Aqui estão as regras em detalhe:

* Se "x = m / n" é um número racional não negativo e "n" não é
  divisível por "P", defina "hash(x)" como "m * invmod(n, P) % P",
  aonde "invmod(n, P)" retorna o inverso de "n" modulo "P".

* Se "x = m / n" é um número racional não negativo e "n" é divisível
  por "P" (porém "m" não é) então "n" não possui modulo "P" inverso e
  a regra acima não se aplica; nesse caso defina "hash(x)" para ser o
  valor constante "sys.hash_info.inf".

* Se "x = m / n" é um número racional negativo, defina "hash(x)" como
  "-hash(-x)". Se a hash resultante é "-1", substitua ela com "-2".

* Os valores particulares "sys.hash_info.inf", "-sys.hash_info.inf" e
  "sys.hash_info.nan" são usados como valores de hash para infinidade
  positiva, infinidade negativa, ou nans (respectivamente). (Todos os
  nans "hasheáveis" possuem o mesmo valor de hash.)

* Para "complex" número "z", o valor da hash do número real partes
  imaginárias são combinados computando "hash(z.real) +
  sys.hash_info.imag * hash(z.imag)", modulo reduzido
  "2**sys.hash_info.width" de modo que isto permaneça em
  "range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width -
  1))". Novamente, se os resultados são "-1", eles são substituídos
  com "-2".

Para clarificar as regras acima, aqui estão alguns exemplos de código
em Python, equivalentes às hash's embutidas, para computar a hash de
números racionais, "float", ou "complex":

   import sys, math

   def hash_fraction(m, n):
       """Compute the hash of a rational number m / n.

       Assumes m and n are integers, with n positive.
       Equivalent to hash(fractions.Fraction(m, n)).

       """
       P = sys.hash_info.modulus
       # Remove common factors of P.  (Unnecessary if m and n already coprime.)
       while m % P == n % P == 0:
           m, n = m // P, n // P

       if n % P == 0:
           hash_value = sys.hash_info.inf
       else:
           # Fermat's Little Theorem: pow(n, P-1, P) is 1, so
           # pow(n, P-2, P) gives the inverse of n modulo P.
           hash_value = (abs(m) % P) * pow(n, P - 2, P) % P
       if m < 0:
           hash_value = -hash_value
       if hash_value == -1:
           hash_value = -2
       return hash_value

   def hash_float(x):
       """Compute the hash of a float x."""

       if math.isnan(x):
           return sys.hash_info.nan
       elif math.isinf(x):
           return sys.hash_info.inf if x > 0 else -sys.hash_info.inf
       else:
           return hash_fraction(*x.as_integer_ratio())

   def hash_complex(z):
       """Compute the hash of a complex number z."""

       hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
       # do a signed reduction modulo 2**sys.hash_info.width
       M = 2**(sys.hash_info.width - 1)
       hash_value = (hash_value & (M - 1)) - (hash_value & M)
       if hash_value == -1:
           hash_value = -2
       return hash_value


Tipos de Iteradores
===================

Python suporta o conceito de iteração sobre conteineres. Isso é
implementado usando dois métodos distintos; estes são usados para
permitir classes definidas pelo usuário suportem iteração. Sequências,
descritas abaixo em mais detalhes, sempre suportam os métodos de
iteração.

Um método necessita ser definido para objetos conteineres afim destes
proverem suporte a iteração:

container.__iter__()

   Retorna um objeto iterador. O objeto é requerido suportar o
   protocolo iterador descrito abaixo. Se um conteiner suporta
   diferentes tipos de iterador, métodos adicionais podem ser
   providenciados para requisitar especificamente iteradores para
   aqueles tipos de iterações.  (Um exemplo de um object suportando
   múltiplas formas de iteração seria uma estrutura em árvore a qual
   suporta ambas travessias de breadth-first e depth-first.) Esse
   method corresponde ao slot "tp_iter" do type de estrutura para
   objetos em Python na API Python/C.

Os objetos iterator por eles mesmos são requeridos que suportem os
dois seguintes métodos, que juntos formam o *iterator protocol*:

iterator.__iter__()

   Retorna o próprio iterator object. Isso é necessário para permitir
   que ambos os conteineres e iteradores sejam usados com as
   declarações  "for" e "in". Esse method corresponde ao slot
   "tp_iter" da estrutura type para objetos do Python na API Python/C.

iterator.__next__()

   Retorna o próximo item do conteiner. Se não houver itens além, a
   exceção "StopIteration" é levantada. Esse method corresponde ao
   slot "tp_iternext" do type de estrutura para objetos Python na API
   Python/C.

Python define diversos objetos iterator para suportar iterações sobre
tipos de sequências gerais e específicas, dicionários, e outras formas
mais especializadas. Os tipos específicos não são importantes além de
sua implementação do protocolo iterator.

Uma vez que o método iterador "__next__()" levantou "StopIteration",
ele deve continuar fazendo isso em chamadas subsequentes.
Implementações que não obedecem essa propriedade são consideradas
quebradas.


Tipos de Geradores
------------------

Python's  *generator*s provê uma maneira conveniente para implementar
o protocolo iterator. Se um object conteiner de method "__iter__()" é
implementado como um gerador, ele irá automaticamente retornar um
object iterator (tecnicamente, um generator object) suprindo os
métodos "__iter__()" e "__next__()" . Mais informações sobre geradores
podem ser encontradas em a documentação para a expressão yield.


Tipos de Sequências --- "list", "tuple", "range"
================================================

Existem três tipos básicos de seqüência: listas, tuplas e objetos
range. Tipos de sequência adicionais adaptados para o processamento de
binary data e text strings são descritos em seções dedicadas.


Operações de Sequências Comuns
------------------------------

As operações nas seguintes tabelas são suportadas pela maioria das
sequências de tipos, ambos mutáveis e imutáveis. A classe
"collections.abc.Sequence" ABC é fornecida para tornar fácil a correta
implementação desses operadores em sequências de tipos customizáveis.

Essa tabela lista as operações de sequência listadas em prioridade
ascendente. Na tabela, *s* e *t* são sequências do mesmo type, *n*,
*i*, *j* e *k* são inteiros e *x* é um object arbitrário que atende a
qualquer restrição de valor e type impostas por *s*.

As operações "in" e "not in" têm as mesmas prioridades que as
operações de comparação. As operações "+" (concatenação) e "*"
(repetição) têm a mesma prioridade que as operações numéricas
correspondentes. [3]

+----------------------------+----------------------------------+------------+
| Operação                   | Resultado                        | Notas      |
|============================|==================================|============|
| "x in s"                   | "True" caso um item de *s* seja  | (1)        |
|                            | igual a *x*, senão "False"       |            |
+----------------------------+----------------------------------+------------+
| "x not in s"               | "False" caso um item de *s* for  | (1)        |
|                            | igual a *x*, senão "True"        |            |
+----------------------------+----------------------------------+------------+
| "s + t"                    | a concatenão de *s* e *t*        | (6)(7)     |
+----------------------------+----------------------------------+------------+
| "s * n" ou "n * s"         | equivalente a adicionar *s* a si | (2)(7)     |
|                            | mesmo *n* vezes                  |            |
+----------------------------+----------------------------------+------------+
| "s[i]"                     | *i*enésimo item de *s*, origem 0 | (3)        |
+----------------------------+----------------------------------+------------+
| "s[i:j]"                   | fatia de *s* desde *i* para *j*  | (3)(4)     |
+----------------------------+----------------------------------+------------+
| "s[i:j:k]"                 | fatia de *s* desde *i* para *j*  | (3)(5)     |
|                            | com passo *k*                    |            |
+----------------------------+----------------------------------+------------+
| "len(s)"                   | comprimento de *s*               |            |
+----------------------------+----------------------------------+------------+
| "min(s)"                   | menor item de *s*                |            |
+----------------------------+----------------------------------+------------+
| "max(s)"                   | maior item de *s*                |            |
+----------------------------+----------------------------------+------------+
| "s.index(x[, i[, j]])"     | índice da primeira ocorrência de | (8)        |
|                            | *x* em *s* (no índice *i* e      |            |
|                            | antes do índice *j*)             |            |
+----------------------------+----------------------------------+------------+
| "s.count(x)"               | numero total de ocorrência de    |            |
|                            | *x* em *s*                       |            |
+----------------------------+----------------------------------+------------+

Sequências do mesmo type também suportam comparações. Em particular,
tuplas e listas são comparadas lexicograficamente pela comparação de
elementos correspondentes. Isso significa que para comparar
igualmente, cada elemento deve comparar igual e as duas sequências
devem ser do mesmo tipo e possuirem o mesmo comprimento. (Para
detalhes completos veja Comparações na referência da linguagem.)

Notas:

1. Enquanto as operações "in" e "not in" são usadas somente para
   ensaios de contenção simples em modo geral, algumas sequências
   especializadas (tais como "str", "bytes" e "bytearray") também usam
   eles para testing:: subsequentes.

      >>> "gg" in "eggs"
      True

2. Os valores de *n* menos "0" são tratados como "0" (o que produz uma
   seqüência vazia do mesmo tipo que *s*). Observe que os itens na
   seqüência *s* não são copiados; eles são referenciados várias
   vezes. Isso freqüentemente assombra novos programadores Python;
   considere então que:

      >>> lists = [[]] * 3
      >>> lists
      [[], [], []]
      >>> lists[0].append(3)
      >>> lists
      [[3], [3], [3]]

   O que aconteceu é que "[[]] `` é uma lista de um elemento contendo
   uma lista vazia, então todos os três elementos de ``[[]] * 3" são
   referências a esta única lista vazia. Modificar qualquer um dos
   elementos de "lists" modifica a lista vazia. Podemos criar uma
   lista de listas diferentes dessa maneira:

      >>> lists = [[] for i in range(3)]
      >>> lists[0].append(3)
      >>> lists[1].append(5)
      >>> lists[2].append(7)
      >>> lists
      [[3], [5], [7]]

   Outra explicação está disponível em FAQ Como faço para criar uma
   lista multidimensional?.

3. Se *i* ou *j* forem negativo, o índice será relativo ao fim da
   seqüência *s*: `` len(s) + i`` ou "len(s) + j" será substituído.
   Mas note que "-0" ainda será "0".

4. A fatia *s* de *i* para *j* é definida como a seqüência de itens
   com índice *k* tal que "i <= k <j". Se *i* ou *j* forem maior do
   que "len(s)", use "len(s)". Se *i* for omitido ou for igual a
   "None", use "0". Se *j* for omitido ou "None", use "len(s)". Se *i*
   for maior ou igual a *j*, a fatia está vazia.

5. A fatia *s* de *i* para *j* com passo *k* é definida como sendo a
   seqüência de itens com índice "x = i + n * k" tal que "0 <= n
   <(j-i)/k". Em outras palavras, os índices são "i", "i+k", "i+2*k",
   "i+3*k" e assim por diante, parando quando *j* for atingiu (mas
   nunca incluindo *j*). Quando *k* for positivo, *i* e *j* serão
   reduzidos a "len(s)" se forem maiores. Quando *k* for negativo, *i*
   e *j* são reduzidos para "len(s)-1" se forem maiores. Se *i* ou *j*
   forem omitidos ou `` None`, eles se tornam valores "finais" (cujo
   final depende de *k*). Nota: *k* não pode ser zero. Se *k* for
   "None", o mesmo será tratado como sendo igual a "1`".

6. Concatenar sequências imutáveis sempre resulta em um novo objeto.
   Isso significa que a criação de uma sequência por concatenação
   repetida terá um custo quadrático de tempo de execução no
   comprimento total da seqüência. Para obter um custo de tempo de
   execução linear, devemos alternar para uma das alternativas abaixo:

   * Se concatenar objetos  "str", podemos criar uma lista e usar
     "str.join()" no final ou então escrever numa instância de
     "io.StringIO" e recuperar o seu valor ao final

   * se concatenarmos objetos "bytes", também poderemos usar o método
     "bytes.join()" ou "io.BytesIO", ou poderemos fazer concatenação
     in-place com um objeto "bytearray". A classe "bytearray" são
     objetos mutáveis e possuem um eficiente mecanismo de
     overallocation

   * se concatenar o objeto "tuple", estenda a classe "list" em vez
     disso

   * Para outros tipos, busque na documentação relevante da classe

7. Alguns tipos de sequência (como "range") apenas suportam sequências
   de itens que seguem padrões específicos e, portanto, não suportam
   concatenação ou repetição de sequência.

8. "index" levanta "ValueError" quando *x* não é encontrado em *s*.
   Nem todas as implementações suportam a passagem dos argumentos
   adicionais *i* e *j*. Esses argumentos permitem a pesquisa
   eficiente de subseções da sequência. Passar os argumentos extras é
   aproximadamente equivalente a usar "s[i:j].index(x)", apenas sem
   copiar nenhum dado e com o índice retornado relativo ao início da
   sequência e não ao início da fatia.


Tipos de Sequência Imutáveis
----------------------------

A única operação que os tipos de sequência imutáveis geralmente
implementam que também não são implementada pelos tipos de sequência
mutable é suporte para a função built-in "hash()".

Esse suporte permite sequências imutáveis, tais como instâncias da
classe "tuple", para serem usadas como chaves de dicionários "dict" e
armazenados em sets "set" e instâncias de "frozenset".

A tentativa de obter um hash de uma sequência imutável que contém
valores desnecessários resultará em um erro "TypeError".


Tipos de Sequências Mutáveis
----------------------------

As operações na tabela a seguir são definidas em tipos de sequência
mutáveis. A ABC "collections.abc.MutableSequence" é fornecido para
tornar mais fácil a implementação correta dessas operações em tipos de
sequências personalizados.

Na tabela *s* há uma instância de um tipo de sequência mutáveis, *t* é
qualquer objeto iterável e *x* é um objeto arbitrário que atende a
qualquer restrição de tipo e valor imposto por *s* (por exemplo
"bytearray" só aceita inteiros que atendam a restrição de valor "0 <=
x <= 255").

+--------------------------------+----------------------------------+-----------------------+
| Operação                       | Resultado                        | Notas                 |
|================================|==================================|=======================|
| "s[i] = x"                     | item *i* de *s* é substituído    |                       |
|                                | por *x*                          |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s[i:j] = t"                   | fatias de *s* de *i* para *j*    |                       |
|                                | são substituídas pelo conteúdo   |                       |
|                                | do iterável *t*                  |                       |
+--------------------------------+----------------------------------+-----------------------+
| "del s[i:j]"                   | o mesmo que "s[i:j] = []"        |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s[i:j:k] = t"                 | os elementos de "s[i:j:k]" são   | (1)                   |
|                                | substituídos por aqueles de *t*  |                       |
+--------------------------------+----------------------------------+-----------------------+
| "del s[i:j:k]"                 | remove os elementos de           |                       |
|                                | "s[i:j:k]" desde a listas        |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s.append(x)"                  | adiciona *x* no final da         |                       |
|                                | sequência (igual a               |                       |
|                                | "s[len(s):len(s)] = [x]")        |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s.clear()"                    | remove todos os itens de *s*     | (5)                   |
|                                | (mesmo que "del s[:]")           |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s.copy()"                     | cria uma cópia rasa de *s*       | (5)                   |
|                                | (mesmo que "s[:]")               |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s.extend(t)" ou "s += t"      | estende *s* com o conteúdo de    |                       |
|                                | *t* (na maior parte do mesmo     |                       |
|                                | "s[len(s):len(s)] = t")          |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s *= n"                       | atualiza *s* com o seu conteúdo  | (6)                   |
|                                | por *n* vezes                    |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s.insert(i, x)"               | Insere *x* dentro de *s* na      |                       |
|                                | posição dada por index *i*       |                       |
|                                | (igual a "s[i:i] = [x]")         |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s.pop([i])"                   | retorna o item em *i* e também   | (2)                   |
|                                | remove-o de *s*                  |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s.remove(x)"                  | remove o primeiro item de *s*    | (3)                   |
|                                | sendo "s[i]" igual a *x*         |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s.reverse()"                  | inverte os itens de *s* in-place | (4)                   |
+--------------------------------+----------------------------------+-----------------------+

Notas:

1. *t* deve ter o mesmo comprimento que a fatia que está sendo
   substituindo.

2. O argumento opcional *i* é padrão para "-1", de modo que, por
   padrão, o último item é removido e retornado.

3. "remove" levanta a exceção "ValueError" quando *x* não for
   encontrado em *s*.

4. O método "reverse()" modifica a sequência no lugar para economizar
   espaço ao reverter uma grande sequência. Para lembrar os usuários
   que isso ocorre como sendo um efeito colateral, o mesmo não retorna
   a sequência invertida.

5. "clear()" e "copy()" são incluídos para consistência com as
   interfaces dos contêiners  mutáveis que não suportam operações de
   fatiamento (tais como "dict" e "set")

   Novo na versão 3.3: métodos "clear()" e "copy()".

6. O valor *n* é um inteiro, ou um objeto implementado "__index__()".
   Valores zero e negativos de *n* limparão a sequência.  Os itens na
   sequência não são copiados; eles são referenciados várias vezes,
   como explicado para "s * n" sobre Operações de Sequências Comuns.


Listas
------

As listas são sequências mutáveis, normalmente usadas para armazenar
coleções de itens homogêneos (onde o grau preciso de similaridade
variará de acordo com a aplicação).

class list([iterable])

   As listas podem ser construídas de várias maneiras:

   * Usando um par de colchetes para denotar uma lista vazia: "[]"

   * Usando suportes a colchetes, separando itens por vírgulas: "[a]",
     "[a, b, c]"

   * Usando uma list comprehension: "[x for x in iterable]"

   * Usando o construtor de tipo: "list()" ou "list(iterable)"

   O construtor produz uma lista cujos itens são iguais e na mesma
   ordem que os itens *iterable*'s. Os *iterable* podem ser uma
   sequência, um contêiner que suporte iteração ou um objeto iterador.
   Se *iterable* já for uma lista, uma cópia será feita e retornada,
   semelhante a *iterable [:]* *. Por exemplo,  ``iterable[:]`*. Por
   exemplo, "list('abc')" retorna "['a', 'b', 'c']" e "list( (1, 2, 3)
   )" retorna "[1, 2, 3]".  Se nenhum argumento for dado, o construtor
   criará uma nova lista vazia "[]".

   Muitas outras operações também produzem listas, incluindo a função
   built-in "sorted()".

   As listas implementam todo o common e a mutable operações de
   sequência. As listas também fornecem o seguinte método adicional:

   sort(*, key=None, reverse=False)

      Esse método classifica a lista in-place, usando apenas "<"
      comparações entre itens. As exceções não são suprimidas - se
      qualquer operação de comparação falhar, toda a operação de
      ordenação falhará (e a lista provavelmente será deixada num
      estado parcialmente modificado).

      "sort()" aceita 2 argumetnos que só podem ser passados como
      keywords (keyword-only arguments):

      A *key* especifica uma função de um argumento que é usado para
      extrair uma chave de comparação de cada elemento de lista (por
      exemplo, "key=str.lower"). A chave correspondente a cada item na
      lista é calculada uma vez e depois usada para todo o processo de
      classificação. O valor padrão "None" significa que os itens da
      lista são classificados diretamente sem calcular um valor de
      chave separado.

      A função utilitária "functools.cmp_to_key()" está disponível
      para converter a função *cmp* no estilo 2.x para uma função
      *key*.

      *reverse* é um valor booleano.  Se definido igual a "True",
      então os elementos da lista são classificados como se cada
      comparação fosse reversa.

      Este método modifica a seqüência in-place para a economizar
      espaço ao classificar uma grande sequência. Para lembrar aos
      usuários que os mesmos operam por efeito colateral, ele não
      retorna a seqüência ordenada (utilize a função "sorted()" para
      solicitar explicitamente uma nova instância da lista ordenada).

      O método "sort()" é garantido para ser estável.  Um tipo é
      estável se garante que não alterar a ordem relativa de elementos
      que comparam igual - isso é útil para classificar em várias
      passagens (por exemplo, classificar por departamento, depois por
      nota salarial).

      **CPython implementation detail:** No momento em que uma lista
      está sendo ordenada, o efeito de tentar alterar, ou mesmo
      inspecionar, a lista é indefinida. A implementação C do Python
      faz com que a lista apareça vazia durante o tempo de
      processamento, e levanta a exceção "ValueError" se puder
      detectar que a lista foi alterada durante uma ordenação.


Tuplas
------

As Tuples são sequências imutáveis, tipicamente usadas para armazenar
coleções de dados heterogêneos (como as 2-tuplas produzidas pelo
função built-in "enumerate()"). As Tuples também são usadas para casos
em que seja necessária uma seqüência imutável de dados homogêneos
(como permitir o armazenamento em uma instância "set" ou "dict").

class tuple([iterable])

   As Tuples podem ser construídos de várias maneiras:

   * Usando um par de parênteses para denotar que a tupla está vazia:
     "()"

   * Usando uma vírgula à direita para uma tupla contendo um único
     elemento: "a," ou "(a,)"

   * Separando os itens por vírgula: "a, b, c" ou "(a, b, c)"

   * Usando a função built-in "tuple()": "tuple()" ou
     "tuple(iterable)"

   O construtor produz uma tupla cujos itens são iguais e na mesma
   ordem que os elementos *iteráveis*. Os *iterable* poderão ser uma
   sequência, um contêiner que suporta iteração ou um objeto iterable.
   Se *iterable* já for uma tupla, o mesmo será retornado inalterado.
   Por exemplo, "tupla('abc')" retorna "('a', 'b', 'c')" e "tupla([1,
   2, 3])" retorna "(1, 2, 3)". Se nenhum argumento for dado, o
   construtor criará uma tupla vazia, "()".

   Observe que na verdade é a vírgula que faz uma tupla, e não os
   parênteses. Os parênteses são opcionais, exceto no caso de tupla
   vazia, ou quando são necessários para evitar ambiguidades
   sintáticas. Por exemplo, "f(a, b, c)" é uma chamada da função com
   três argumentos, enquanto que "f((a, b, c))" é uma chamada de
   função com uma 3-tupla com um única argumento.

   As tuplas implementam todas as operações de sequência common.

Para coleções heterogêneas de dados onde o acesso pelo nome é mais
claro do que o acesso pelo índice, "collections.namedtuple()" pode ser
uma escolha mais apropriada do que um simples objeto tupla.


Ranges
------

O tipo da classe "range" representa uma sequência imutável de números
e é comumente usada para fazer um looping um número determinado de
vezes por "for".

class range(stop)
class range(start, stop[, step])

   Os argumentos para o construtor de intervalo devem ser inteiros
   (built-ins "int" ou qualquer objeto que implemente o método
   especial "__index__"). Se o argumento *step* for omitido, será
   usado o padrão "1". Se o argumento *start* for omitido, será usado
   o  padrão "0". Se *step* for zero, uma exceção :exc: *ValueError*
   será levantada.

   Para um *step* positivo, o conteúdo de um intervalo "r" será
   determinado pela fórmula "r[i] = start + step*i" onde "i >= 0" and
   "r[i] < stop".

   Para um *passo*, o conteúdo do intervalo ainda será determinado
   pela fórmula "r[i] = start + step*i", mas as restrições serão "i >=
   0" and "r[i] > stop".

   Um objeto range estará vazio se "r[0]" não atender a restrição de
   valor. Os Ranges suportam índices negativos, mas estes são
   interpretados como indexadores partindo do final da seqüência
   determinada pelos índices positivos.

   Ranges contendo valores absolutos maiores do que "sys.maxsize" são
   permitidos, mas alguns recursos (como "len()") podem levantar uma
   exceção "OverflowError".

   Range de exemplos:

      >>> list(range(10))
      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
      >>> list(range(1, 11))
      [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
      >>> list(range(0, 30, 5))
      [0, 5, 10, 15, 20, 25]
      >>> list(range(0, 10, 3))
      [0, 3, 6, 9]
      >>> list(range(0, -10, -1))
      [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
      >>> list(range(0))
      []
      >>> list(range(1, 0))
      []

   Os Ranges todas as operações de sequência common exceto a
   concatenção e a repetição (devido ao fato de que os objetos Range
   só podem representar sequências que seguem um padrão rígido e a
   repetição e a concatenação geralmente violam esse padrão).

   start

      O valor do parâmetro *start* (ou "0" se o parâmetro não for
      fornecido)

   stop

      O valor do parâmetro *stop*

   step

      O valor do parâmetro *step* (ou "1" se o parâmetro não for
      fornecido)

A vantagem da classe "range" sobre o tipo regular "list" ou o "tuple"
é que um objeto "range" sempre terá a mesma quantidade (pequena) de
memória, não importa o tamanho do intervalo o mesmo esteja
representando (como ele apenas armazena os valores "start", "stop" e
"step", calculando todos os demais itens individualmente e gerando os
subranges conforme necessário).

Objetos Range implementam a classe "collections.abc.Sequence" ABC, e
fornecem recursos como testes de contenção, pesquisa de índice de
elemento, fatiamento e suporte a índices negativos (veja Tipos de
Sequências --- list, tuple, range):

>>> r = range(0, 20, 2)
>>> r
range(0, 20, 2)
>>> 11 in r
False
>>> 10 in r
True
>>> r.index(10)
5
>>> r[5]
10
>>> r[:5]
range(0, 10, 2)
>>> r[-1]
18

Testar objetos Range com o sinal de igualdade "==" e "!=" os compara
como sequências. Ou seja, dois objetos de intervalo são considerados
iguais se representarem a mesma sequência de valores. (observe que
dois objetos Range que comparam igual podem ter diferentes atributos
"start", "stop" and "step", por exemplo "range(0) == range(2, 1, 3)"
ou "range(0, 3, 2) == range(0, 4, 2)".)

Alterado na versão 3.2: Implementar a Sequencia ABC. Suporte a
fatiamento e a índices negativos. Testa objetos "int" para associação
em tempo constante em vez de iterar através de todos os itens.

Alterado na versão 3.3: Determina '==' e '!=' para comparar objetos
Range com base na sequência de valores que eles definem (em vez de
comparar com base na identidade do objeto).

Novo na versão 3.3: Os atributos "start", "stop" e "step".

Ver também:

  * A receita de linspace mostra como implementar uma versão
    preguiçosa de um intervalo adequado para aplicações de ponto
    flutuante.


Tipo de Sequência de Texto --- "str"
====================================

Os dados textuais em Python são tratados com objetos "str", ou
*strings*. Strings são imutáveis sequences de códigos Unicode. As
Strings literais são escritas de diversas maneiras:

* Aspas Simples: "'allows embedded "double" quotes'"

* Aspas Duplas: ""allows embedded 'single' quotes"".

* Aspas Triplas: "'''Three single quotes'''", """"Three double
  quotes""""

Aspas triplas são Strings de várias linhas - todos os espaços em
branco associados serão incluídos na String literal.

Os literais Strings que fazem parte de uma única expressão e têm
apenas espaços em branco entre eles serão implicitamente convertidos
em um único literal String. Isso é, "("spam " "eggs") == "spam eggs"".

Veja String e Bytes literais para mais informações sobre as várias
formas de cadeia de literais, incluindo o suporte a Strings escape, e
o prefixo "r" ("raw") que desabilita a maioria dos processos de
escape.

As Strings também podem ser criadas a partir de outros objetos usando
o construtor "str".

Uma vez que não há nenhum tipo de "caractere" separador, indexar uma
String produz Strings de comprimento 1. Ou seja, para uma Strings não
vazia *s*,  "s[0] == s[0:1]".

Também não existe um tipo de String mutável, mas o método "str.join()"
ou a classe :class:` io.StringIO` podem ser usado para construir
Strings de forma eficiente a partir de vários partes distintas.

Alterado na versão 3.3: Para a compatibilidade com versões anteriores
do Python 2, o prefixo "u" for mais uma vez permitido em literais
Strings. Não possui quaisquer efeito sobre o significado de literais
Strings e não pode ser combinado com o prefixo "r".

class str(object='')
class str(object=b'', encoding='utf-8', errors='strict')

   Retorna uma string  versão do *object*.  Se o *object* não é
   fornecido, retorna uma String vazia. Caso contrário, o
   comportamento de "str()" dependerá se o *encoding* ou *erros* são
   fornecidos, da seguinte forma.

   Se nem o *encoding* nem os *errors* forem dados,  a "str(object)"
   retorna o método "object .__ str __ ()", que é a representação de
   seqüência "informal" ou que pode ser facilmente imprimível de
   *objeto*. Para objetos String, esta é a própria String. Se o
   *objeto* não tiver um método "__ str__()", então a função "str()"
   retornará "repr(object)()".

   Se pelo menos um de *encoding* ou *errors* for fornecido, *object*
   deve ser um *bytes-like object* (por exemplo. "bytes" ou
   "bytearray"). Nesse caso, se *object* for um objeto "bytes" (ou
   "bytearray"), então "str(bytes, encoding, errors)" será equivalente
   a "bytes.decode (encoding, errors)". Caso contrário, o objeto bytes
   subjacente ao objeto buffer é obtido antes de chamar
   "bytes.decode()". Veja Tipos de Sequência Binária --- bytes,
   bytearray, memoryview e Protocolo de Buffer para obter informações
   sobre objetos buffer.

   Passa um objeto "bytes" para "str()" sem os argumentos *encoding*
   ou *errors* se enquadra no primeiro caso de retornar a
   representação informal de strings (consulte também a opção de linha
   >>:option:command:`-b`<< para Python). Por exemplo:

      >>> str(b'Zoot!')
      "b'Zoot!'"

   Para mais informações sobre a classe "str" e seus métodos, veja
   Tipo de Sequência de Texto --- str e a seção Métodos de String
   abaixo.  Para gerar strings formatadas, veja as seções Literais de
   string formatados e Sintaxe das strings de formato. Além disso,
   veja a seção Serviços de Processamento de Texto.


Métodos de String
-----------------

Strings implementam todas as operações de sequência common, juntamente
com os métodos adicionais descritos abaixo.

Strings também suportam duas formas de formatação de string, uma
fornecendo uma ampla gama de flexibilidade e customização (veja
"str.format()", Sintaxe das strings de formato e Formatação
personalizada de strings) e a outra baseada no estilo de formatação
"printf" da linguagem C, que lida com uma possibilidade menor de tipos
e é levemente mais difícil de utilizar corretamente, mas é
frequentemente mais rápida para os casos na qual ela consegue lidar
(Formatação de String no Formato printf-style).

A seção Serviços de Processamento de Texto da biblioteca padrão cobre
um número de diversos outros módulos que fornecem vários utilitários
relacionados a texto (incluindo suporte a expressões regulares no
módulo "re").

str.capitalize()

   Retorna uma cópia da String com o seu primeiro caractere em
   maiúsculo e o restantes em minúsculo.

str.casefold()

   Retorna uma cópia da string em casefolded. Strings em casefold
   podem ser usadas para corresponder letras sem importar se são
   minúsculas/maiúsculas.

   Casefolding é similar a mudar para letras minúsculas, mas mais
   agressivo porque ele é pretendido para remover todas as diferenças
   maiúsculas/minúsculas em uma string. Por exemplo, a letra minúscula
   alemã "'ß'" é equivalente a ""ss"". Como ela já é uma minúscula, o
   método "lower()" não irá fazer nada para "'ß'"; já o método
   "casefold()" converte a letra para ""ss"".

   O algoritmo casefolding é descrito na seção 3.13 do Padrão Unicode.

   Novo na versão 3.3.

str.center(width[, fillchar])

   Retorna um texto centralizado em uma string de comprimento *width*.
   Preenchimento é feito usando o parâmetro *fillchar* especificado
   (padrão é o caractere de espaço ASCII). A string original é
   retornada se *width* é menor ou igual que "len(s)".

str.count(sub[, start[, end]])

   Retorna o número de ocorrências da sub-string *sub* que não se
   sobrepõem no intervalo [*start*, *end*]. Argumentos opcionais
   *start* e *end* são interpretados como na notação de fatias.

str.encode(encoding="utf-8", errors="strict")

   Retornar uma versão codificada da String como um objeto bytes. A
   codificação padrão é "'utf-8'". *erros* podem ser levantados para
   definir um esquema de tratamento de erros diferente. O padrão para
   *erros* é "'strict'", o que significa que os erros de codificação
   levantam uma exceção "UnicodeError". Outros valores possíveis são
   "'ignore'", "'replace'", "'xmlcharrefreplace'",
   "'backslashreplace'" e qualquer outro nome registrado via
   "codecs.register_error()", veja a seção Error Handlers. Para obter
   uma lista das possíveis codificações, consulte a seção Standard
   Encodings.

   Alterado na versão 3.1: Suporte para argumentos que possuem keyword
   adicionados.

str.endswith(suffix[, start[, end]])

   Retorna "True" se a string terminar com o *suffix* especificado,
   caso contrário retorna "False".  *suffix* também pode ser uma tupla
   de sufixos para procurar. Com o parâmetro opcional *start*,
   começamos a testart a partir daquela posição. Com o parâmetro
   opcional *end*, devemos parar de comparar na posição especificada.

str.expandtabs(tabsize=8)

   Devolve uma cópia da string onde todos os caracteres de tabulação
   são substituídos por um ou mais espaços, dependendo da coluna atual
   e do tamanho fornecido para a tabulação. Posições de tabulação
   ocorrem a cada *tabsize* caracteres (o padrão é 8, dada as posições
   de tabulação nas colunas 0, 8, 16 e assim por diante). Para
   expandir a string, a coluna atual é definida como zero e a string é
   examinada caracter por caracter. Se o caracter é uma tabulação
   ("\t"), um ou mais caracteres de espaço são inseridos no resultado
   até que a coluna atual seja igual a próxima posição de tabulação.
   (O caracter de tabulação em si não é copiado.) Se o caracter é um
   caracter de nova linha ("\n") ou de retorno ("\r"), ele é copiado e
   a coluna atual é resetada para zero. Qualquer outro caracter é
   copiado sem ser modificado e a coluna atual é incrementada em uma
   unidate independentemente de como o caracter é representado quanto
   é impresso.

   >>> '01\t012\t0123\t01234'.expandtabs()
   '01      012     0123    01234'
   >>> '01\t012\t0123\t01234'.expandtabs(4)
   '01  012 0123    01234'

str.find(sub[, start[, end]])

   Retorna o índice mais baixo na String onde a substring *sub* é
   encontrado dentro da fatia "s[start:end]".  Argumntos opcionais
   como *start* e *end* são interpretados como umanotação de
   fatiamento.  Retorna "-1" se *sub* não for localizado.

   Nota:

     O método "find()" deve ser usado apenas se precisarmos conhecer a
     posição de *sub*. Para verificar se *sub* é ou não uma substring,
     use o operador "in":

        >>> 'Py' in 'Python'
        True

str.format(*args, **kwargs)

   Executa uma operação de formatação de string. A string na qual este
   método é chamado pode conter texto literal ou campos para
   substituição delimitados por chaves "{}". Cada campo de
   substituição contém ou um índice numérico de um argumento
   posicional, ou o nome de um argumento palavra-chave. Retorna a
   cópia da string onde cada campo para substituição é substituído com
   o valor da string do argumento correspondente.

   >>> "The sum of 1 + 2 is {0}".format(1+2)
   'The sum of 1 + 2 is 3'

   Veja Sintaxe das strings de formato para uma descrição das várias
   opções de formatação que podem ser especificadas em um formato
   Strings.

   Nota:

     Ao formatar um número ("int", "float", "complex",
     "decimal.Decimal" e sub-classes) com o tipo "n" (ex:
     "'{:n}'.format(1234)"), a função define temporariamente a
     localidade "LC_CTYPE" para a localidade "LC_NUMERIC" a fim de
     decodificar campos "decimal_point" e "thousands_sep" de
     "localeconv()" se eles são caracteres não-ASCII ou maiores que 1
     byte, e a localidade "LC_NUMERIC" é diferente da localidade
     "LC_CTYPE". Esta mudança temporária afeta outras threads.

   Alterado na versão 3.7: Ao formatar um número com o tipo "n", a
   função define temporatiamente a localidade "LC_CTYPE" para
   "LC_NUMERIC" em alguns casos.

str.format_map(mapping)

   Semelhante a "str.format(**mapping)", exceto pelo fato "mapping" de
   que é usado indiretamente e não copiado para uma classe "dict".
   Isso é útil se, por exemplo, >>``<<mapping'' é uma subclasse de
   dict:

   >>> class Default(dict):
   ...     def __missing__(self, key):
   ...         return key
   ...
   >>> '{name} was born in {country}'.format_map(Default(name='Guido'))
   'Guido was born in country'

   Novo na versão 3.2.

str.index(sub[, start[, end]])

   Similar a "find()", mas levanta "ValueError" quando a sub-string
   não é encontrada.

str.isalnum()

   Retorna "True" se todos os caracteres na string são alfanuméricos e
   existe pelo menos um caractere, ou "False" caso contrário. Um
   caractere "c" é alfanumérico se um dos seguintes retorna "True":
   "c.isalpha()", "c.isdecimal()", "c.isdigit()", ou "c.isnumeric()".

str.isalpha()

   Retorna "True" se todos os caracteres na string são alfabéticos e
   existe pelo menos um caractere, "False" caso contrário. Caracteres
   alfabéticos são aqueles caracteres definidos na base de dados de
   caracteres Unicode como "Letra", isto é, aqueles cuja propriedade
   na categoria geral é um destes: "Lm", "Lt", "Lu", "Ll", ou "Lo".
   Perceba que isso é diferente da propriedade "Alfabética" definida
   no Unicode padrão.

str.isascii()

   Retorna "True" se a string é vazia ou se todos os caracteres na
   string são ASCII, "False" caso contrário. Caracteres ASCII tem
   códigos inteiros no intervalo U+0000-U+007F.

   Novo na versão 3.7.

str.isdecimal()

   Retorna "True" se todos os caracteres na string são caracteres
   decimais e existe pelo menos um caractere, "False" caso contrário.
   Caracteres decimais são aqueles que podem ser usados para formar
   números na base 10, exemplo U+0660, ou dígito zero para arábico-
   índico. Formalmente, um caractere decimal é um caractere em Unicode
   cuja categoria geral é "Nd".

str.isdigit()

   Retorna "True" se todos os caracteres na string são dígitos e
   existe pelo menos um caractere, "False" caso contrário. Dígitos
   incluem caracteres decimais e dígitos que precisam de tratamento
   especial, tal como a compatibilidade com dígitos sobre-escritos.
   Isso inclui dígitos que não podem ser usados para formar números na
   base 10, como por exemplo os números de Kharosthi. Formalmente, um
   dígito é um caractere que tem a propriedade com valor
   Numeric_Type=Digit ou Numeric_Type=Decimal.

str.isidentifier()

   Retorna "True" se a string é um identificador válido conforme a
   definição da linguagem, seção Identificadores e Keywords.

   Use "keyword.iskeyword()" to test for reserved identifiers such as
   "def" and "class".

str.islower()

   Retorna "True" se todos os caracteres em caixa [4] na string são
   minúsculos e existe pelo menos um caracter em caixa, "False" caso
   contrário.

str.isnumeric()

   Retorna "True" se todos os caracteres na string são caracteres
   numéricos, e existe pelo menos um caractere, "False" caso
   contrário. Caracteres numéricos incluem dígitos, e todos os
   caracteres que tem a propriedade/valor numérica Unicode, isto é:
   U+2155, um quinto de fração vulgar. Formalmente, caracteres
   numéricos são aqueles que possuem propriedades com valor
   Numeric_Type=Digit, Numeric_Type=Decimal ou Numeric_Type=Numeric.

str.isprintable()

   Retorna "True" se todos os caracteres na string podem ser impressos
   ou se a string é vazia, "False" caso contrário. Caracteres que não
   podem ser impressos são aqueles que estão definidos no banco de
   dados Unicode como "Outros" ou "Separadores", exceto o caractere
   ASCII que representa o espaço (0x20), o qual é impresso. (Perceba
   que caracteres que podem ser impressos, neste contexto, são aqueles
   que não devem ser escapados quando "repr()" é invocada sobre uma
   string. Ela não tem sentido no tratamento de strings escritas
   usando "sys.stdout" ou "sys.stderr".)

str.isspace()

   Retorna "True" se existem apenas caracteres em branco na string e
   existe pelo menos caractere, "False" caso contrário.

   Um caracter é *espaço em branco* se no banco de dados de caracteres
   Unicode (veja "unicodedata"), ou pertence a categoria geral "Zs"
   ("Separador, espaço"), ou dua classe bidirecional  é "WS", "B", ou
   "S".

str.istitle()

   Retorna "True" se a string é titlecased e existe pelo menos um
   caractere, por exemplo caracteres maiúsculos somente podem proceder
   caracteres que não diferenciam maiúsculas/minúsculas, e caracteres
   minúsculos somente podem proceder caracteres que permitem ambos.
   Retorna "False" caso contrário.

str.isupper()

   Retorna "True" se todos os caracteres que permitem maiúsculas ou
   minúsculas [4] na string estão com letras maiúsculas, e existe pelo
   menos um caractere maiúsculo, "False" caso contrário.

str.join(iterable)

   Retorna a string que é a concatenação das strings no *iterável*. Um
   "TypeError" será levantado se existirem quaisquer valores que não
   sejam strings no *iterável*, incluindo objetos "bytes". O separador
   entre elementos na é a string que está fornecendo este método.

str.ljust(width[, fillchar])

   Retorna a string alinhada a esquerda em uma string de comprimento
   *width*. Preenchimento é feito usando *fillchar* que for
   especificado (o padrão é o caractere ASCII de espaço). A string
   original é retornada se *width* é menor ou igual que "len(s)".

str.lower()

   Retorna uma cópia da string com todos os caracteres que permitem
   maiúsculo E minúsculo [4] convertidos para letras minúsculas.

   O algoritmo usado para letras minúsculas é descrito na seção 3.13
   do Padrão Unicode.

str.lstrip([chars])

   Retorna uma cópia da string com caracteres iniciais removidos. O
   argumento *chars* é uma string que especifica o conjunto de
   caracteres a serem removidos. Se for omitido ou se for "None", o
   argumento *chars* será considerado como espaço em branco por padrão
   para a remoção. O argumento *chars* não é um prefixo; ao invés
   disso, todas as combinações dos seus valores são retirados:

      >>> '   spacious   '.lstrip()
      'spacious   '
      >>> 'www.example.com'.lstrip('cmowz.')
      'example.com'

static str.maketrans(x[, y[, z]])

   Este método estático retorna uma tabela de tradução usável para
   "str.translate()".

   Se existe apenas um argumento, ele deve ser um dicionário mapeando
   números Unicode (inteiros) ou caracteres (strings de comprimento 1)
   para números Unicode, strings (de comprimento arbitrário) ou
   "None". Caracteres chave serão então convertidos para números
   ordinais.

   Se existirem dois argumentos, eles devem ser strings de igual
   tamanho, e no dicionário resultante, cada caractere em x será
   mapeado para o caractere na mesma posição em y. Se existir um
   terceiro argumento, ele deve ser uma string, cujos caracteres serão
   mapeados para "None" no resultado.

str.partition(sep)

   Quebra a string na primeira ocorrência de *sep*, e retorna uma
   tupla com 3 elementos contendo a parte antes do separador, o
   próprio separator, e a parte após o separador. Se o separador não
   for encontrado, retorna uma tupla com 3 elementos contendo a
   string, seguido de duas strings vazias.

str.replace(old, new[, count])

   Retorna uma cópia da string com todas as ocorrências da substring
   *old* substituídas por *new*. Se o argumento opcional *count* é
   fornecido, apenas as primeiras *count* ocorrências são
   substituídas.

str.rfind(sub[, start[, end]])

   Retorna o maior índice onde a substring *sub* foi encontrada dentro
   da string, onde *sub* está contida dentro do intervalo
   "s[start:end]". Argumentos opcionais *start* e *end* são
   interpretados usando a notação slice. Retorna "-1" em caso de
   falha.

str.rindex(sub[, start[, end]])

   Similar a "rfind()" mas levanta um "ValueError" quando a substring
   *sub* não é encontrada.

str.rjust(width[, fillchar])

   Retorna a string alinhada à direita em uma string de comprimento
   *width*. Preenchimento é feito usando o caractere *fillchar*
   especificado (o padrão é um caractere de espaço ASCII). A string
   original é retornada se *width* é menor que ou igual a "len(s)".

str.rpartition(sep)

   Quebra a string na última ocorrência de *sep*, e retorna uma tupla
   com 3 elementos contendo a parte antes do separador, o próprio
   separator, e a parte após o separador. Se o separador não for
   encontrado, retorna uma tupla com 3 elementos contendo duas strings
   vazias, seguido da própria string original.

str.rsplit(sep=None, maxsplit=-1)

   Retorna uma lista de palavras na string, usando *sep* como a string
   delimitadora. Se *maxsplit* é fornecido, no máximo *maxsplit*
   cortes são feitos, sendo estes mais *à direita*. Se *sep* não foi
   especificado ou "None" foi informado, qualquer string de espaço em
   branco é um separador. Exceto pelo fato de separar pela direita,
   "rsplit()" se comporta como "split()", o qual é descrito em
   detalhes abaixo.

str.rstrip([chars])

   Retorna uma cópia da string com caracteres no final removidos. O
   argumento *chars* é uma string que especifica o conjunto de
   caracteres para serem removidos. Se omitidos ou tiver o valor
   "None", o argumento *chars* considera como padrão a remoção dos
   espaços em branco. O argumento *chars* não é um sufixo; ao invés
   disso, todas as combinações dos seus valores são removidos:

      >>> '   spacious   '.rstrip()
      '   spacious'
      >>> 'mississippi'.rstrip('ipz')
      'mississ'

str.split(sep=None, maxsplit=-1)

   Retorna uma lista de palavras na string, usando *sep* como a string
   delimitadora. Se *maxsplit* é fornecido, no máximo *maxsplit*
   cortes são feitos (portando, a lista terá no máximo "maxsplit+1"
   elementos). Se *maxsplit* não foi especificado ou "-1" foi
   informado, então não existe limite no número de cortes (todos os
   cortes possíveis são realizados).

   Se *sep* é fornecido, delimitadores consecutivos não são agrupados
   juntos e eles são destinados para delimitar strings vazias (por
   exemplo "'1,,2'.split(',')" retorna "['1', '', '2']"). O argumento
   *sep* pode consistir de múltiplos caracteres (por exemplo,
   "'1<>2<>3'.split('<>')" retorna "['1', '2', '3']"). Separar uma
   string vazia com um separador especificado retorna "['']".

   Por exemplo:

      >>> '1,2,3'.split(',')
      ['1', '2', '3']
      >>> '1,2,3'.split(',', maxsplit=1)
      ['1', '2,3']
      >>> '1,2,,3,'.split(',')
      ['1', '2', '', '3', '']

   Se *sep* não for especificado ou for "None", um algoritmo diferente
   de separação é aplicado: ocorrências consecutivas de espaços em
   branco são consideradas como um separador único, e o resultado não
   conterá strings vazias no início ou no final, se a string tiver
   espaços em branco no início ou no final. Consequentemente, separar
   uma string vazia ou uma string que consiste apenas de espaços em
   branco com o separador "None", retorna "[]".

   Por exemplo:

      >>> '1 2 3'.split()
      ['1', '2', '3']
      >>> '1 2 3'.split(maxsplit=1)
      ['1', '2 3']
      >>> '   1   2   3   '.split()
      ['1', '2', '3']

str.splitlines([keepends])

   Retorna uma lista das linhas na string, quebrando a mesma nas
   fronteiras de cada linha. Quebras de linhas não são incluídas na
   lista resultante a não ser que *keepends* seja fornecido e seja
   verdadeiro.

   Este método divide nos seguintes limites das linhas. Em particular,
   os limites são um superconjunto de *universal newlines*.

   +-------------------------+-------------------------------+
   | Representação           | Description (descrição)       |
   |=========================|===============================|
   | "\n"                    | Feed de linha                 |
   +-------------------------+-------------------------------+
   | "\r"                    | Retorno de Carro              |
   +-------------------------+-------------------------------+
   | "\r\n"                  | Retorno do Carro + Feed da    |
   |                         | Linha                         |
   +-------------------------+-------------------------------+
   | "\v" ou "\x0b"          | Tabulação de Linha            |
   +-------------------------+-------------------------------+
   | "\f" ou "\x0c"          | Formulário de Feed            |
   +-------------------------+-------------------------------+
   | "\x1c"                  | Separador de Arquivos         |
   +-------------------------+-------------------------------+
   | "\x1d"                  | Separador de Grupo            |
   +-------------------------+-------------------------------+
   | "\x1e"                  | Separador de Registro         |
   +-------------------------+-------------------------------+
   | "\x85"                  | Próxima Linha (C1 Control     |
   |                         | Code)                         |
   +-------------------------+-------------------------------+
   | "\u2028"                | Separador de Linha            |
   +-------------------------+-------------------------------+
   | "\u2029"                | Parágrafo Separador           |
   +-------------------------+-------------------------------+

   Alterado na versão 3.2: "\v" e "\f" adicionado à lista de limites
   de linha.

   Por exemplo:

      >>> 'ab c\n\nde fg\rkl\r\n'.splitlines()
      ['ab c', '', 'de fg', 'kl']
      >>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
      ['ab c\n', '\n', 'de fg\r', 'kl\r\n']

   Ao contrário do método "split()" quando um delimitador de String
   *sep* é fornecido, este método retorna uma lista vazia para a uma
   String vazia e uma quebra de linha de terminal não resulta numa
   linha extra:

      >>> "".splitlines()
      []
      >>> "One line\n".splitlines()
      ['One line']

   Para comparação, temos "split('\n')":

      >>> ''.split('\n')
      ['']
      >>> 'Two lines\n'.split('\n')
      ['Two lines', '']

str.startswith(prefix[, start[, end]])

   Retorne "True" se a String começar com o *prefixo*, caso contrário,
   retorna "False". *prefixo* também pode ser uma tupla de prefixos a
   serem procurados. Com *start* opcional, a String de teste começa
   nessa posição. Com *fim* opcional, interrompe a comparação de
   String nessa posição.

str.strip([chars])

   Retorna uma cópia da string com caracteres no início e no final
   removidos. O argumento *chars* é uma string que especifica o
   conjunto de caracteres a serem removidos. Se for omitido ou for
   "None", o argumento *chars* irá remover por padrão os caracteres em
   branco. O argumento *chars* não é um prefixo, nem um sufixo; ao
   contrário disso, todas as combinações dos seus seus valores são
   removidas:

      >>> '   spacious   '.strip()
      'spacious'
      >>> 'www.example.com'.strip('cmowz.')
      'example'

   Os valores do argumento *chars* são removidos dos extremos inicial
   e final da string. Caracteres são removidos do extremo inicial até
   atingir um caractere da string que não está contido no conjunto de
   caracteres em *chars*. Uma ação similar acontece no extremo final
   da string. Por exemplo:

      >>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
      >>> comment_string.strip('.#! ')
      'Section 3.2.1 Issue #32'

str.swapcase()

   Retorna uma cópia da string com caracteres maiúsculos convertidos
   para minúsculos e vice-versa. Perceba que não é necessariamente
   verdade que "s.swapcase().swapcase() == s".

str.title()

   Retorna uma versão titlecased da string, onde palavras iniciam com
   um caractere com letra maiúscula e os caracteres restantes são em
   letras minúsculas.

   Por exemplo:

      >>> 'Hello world'.title()
      'Hello World'

   O algoritmo usa uma definição simples independente de idioma para
   uma palavra, como grupos de letras consecutivas. A definição
   funciona em muitos contextos, mas isso significa que apóstrofes em
   contradições e possessivos formam limites de palavras, os quais
   podem não ser o resultado desejado:

      >>> "they're bill's friends from the UK".title()
      "They'Re Bill'S Friends From The Uk"

   Uma solução alternativa para os apóstrofes pode ser construída
   usando expressões regulares:

      >>> import re
      >>> def titlecase(s):
      ...     return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
      ...                   lambda mo: mo.group(0)[0].upper() +
      ...                              mo.group(0)[1:].lower(),
      ...                   s)
      ...
      >>> titlecase("they're bill's friends.")
      "They're Bill's Friends."

str.translate(table)

   Retorna uma cópia da string na qual cada caractere foi mapeado
   através da tabela de tradução fornecida. A tabela deve ser um
   objeto que implementa indexação através de "__getitem__()",
   tipicamente um *mapeamento* ou uma *sequência*. Quando indexada por
   um ordinal unicode (um inteiro), o objeto tabela pode fazer
   qualquer uma das seguintes ações: retornar um ordinal unicode ou
   uma string, para mapear o caractere para um ou mais caracteres;
   retornar "None", para deletar o caractere da string de retorno; ou
   levantar uma exceção "LookupError", para mapear o caractere para si
   mesmo.

   Você pode usar "str.maketrans()" para criar um mapa de tradução com
   mapeamentos caractere para caractere em diferentes formatos.

   Veja também o módulo "codecs" para uma abordagem mais flexível para
   mapeamento de caracter customizado.

str.upper()

   Retorna uma cópia da string com todos os caracteres que permitem
   maiúsculo e minúsculo [4] convertidos para letras maiúsculas.
   Perceba que "s.upper().isupper()" pode ser "False" se "s" contiver
   caracteres que não possuem maiúsculas e minúsculas, ou se a
   categoria Unicode do(s) caractere(s) resultante(s) não for "Lu"
   (Letra maiúscula), mas por ex "Lt" (Letra em titlecase).

   O algoritmo de maiúsculas utilizado é descrito na seção 3.13 do
   Padrão Unicode.

str.zfill(width)

   Retorna uma cópia da String deixada preenchida com dígitos ASCII
   "'0'" para fazer uma string de comprimento *width*. Um prefixo
   sinalizador principal  ("'+'"/"'-'") será tratado inserindo o
   preenchimento *após* o caractere de sinal em vez de antes. A String
   original será retornada se o *width* for menor ou igual a "len(s)".

   Por exemplo:

      >>> "42".zfill(5)
      '00042'
      >>> "-42".zfill(5)
      '-0042'


Formatação de String no Formato "printf"-style
----------------------------------------------

Nota:

  As operações de formatação descritas aqui exibem uma variedade de
  peculiaridades que levam a diversos erros comuns (tais como não
  conseguir exibir tuplas e dicionários corretamente). Usar o novo
  formatador de strings literais (f-strings), a interface
  "str.format()", ou templates de strings pode ajudar a evitar esses
  erros. Cada uma dessas alternativas fornece seus próprios custos e
  benefícios de simplicidade, flexibilidade, e/ou extensibilidade.

Os objetos String possuem um única operador built-in: o operador "% ``
(modulo). O mesmo também é conhecido como o *formatador* de String ou
como operador *interpolador*. Dado  ``format % values" (onde *format*
é uma String), as especificações de conversão "%" em *format* são
substituídas por zero ou mais elementos de *valores*. O efeito é
semelhante ao uso da função "sprintf()" na linguagem C.

Se *format* precisar de um único operador, *valores* podem ser objetos
simples ou que não sejam uma tupla. [5]  Caso contrário, *valores*
precisarão ser uma tupla com exatamente o número de itens
especificados pela string de formatação, ou um único mapa de objetos
(por exemplo, um dicionário).

Um especificador de conversão contém dois ou mais caracteres e tem os
seguintes componentes, que devem aparecer nesta ordem:

1. O caractere "'%'", que determina o início do especificador.

2. Mapeamento de Chaves (opcional), consistindo de uma sequência entre
   parênteses de caracteres (por exemplo, "(algumnome)").

3. Flags de conversão (opcional), que afetam o resultado de alguns
   tipos de conversão.

4. Largura mínima do Campo(opcional). Se for especificado por "'*'"
   (asterisco), a largura real será lida a partir do próximo elemento
   da tupla em *values* e o objeto a converter virá após a largura
   mínima do campo e a precisão que é opcional.

5. Precisão (opcional), fornecido como uma "'.'" (ponto) seguido pela
   precisação.  Se determinado como um "'*'" (um asterisco), a
   precisão real será lida a partir do próximo elemento da tupla em
   *values*, e o valor a converter virá após a precisão.

6. Modificador de Comprimento(opcional).

7. Tipos de Conversão

Quando o argumento certo for um dicionário (ou outro tipo de
mapeamento), então os formatos na string *deverão* incluir uma chave
de mapeamento entre parênteses nesse dicionário inserido imediatamente
após o caractere "'%'". A key de mapeamento seleciona o valor a ser
formatado a partir do mapeamento. Por exemplo:

>>> print('%(language)s has %(number)03d quote types.' %
...       {'language': "Python", "number": 2})
Python has 002 quote types.

Nesse caso, nenhum especificador "*" poderá ocorrer num formato (uma
vez que eles exigem uma lista de parâmetros sequenciais).

Os caracteres flags de conversão são:

+-----------+-----------------------------------------------------------------------+
| Flag      | Significado                                                           |
|===========|=======================================================================|
| "'#'"     | A conversão de valor usará o "formulário alternativo" (em que         |
|           | definimos abaixo).                                                    |
+-----------+-----------------------------------------------------------------------+
| "'0'"     | A conversão será preenchida por zeros para valores numéricos.         |
+-----------+-----------------------------------------------------------------------+
| "'-'"     | O valor convertido será ajustado à esquerda (substitui a conversão    |
|           | "'0'" se ambos forem fornecidos).                                     |
+-----------+-----------------------------------------------------------------------+
| "' '"     | (um espaço) Um espaço em branco deverá ser deixado antes de um número |
|           | positivo (ou uma String vazia) produzido por uma conversão assinada.  |
+-----------+-----------------------------------------------------------------------+
| "'+'"     | Um sinal de caractere ("'+'" ou "'-'") precedera a conversão          |
|           | (substituindo o sinalizador "space").                                 |
+-----------+-----------------------------------------------------------------------+

Um modificador de comprimento ("h", "l", ou "L") pode estar presente,
mas será ignorado, pois o mesmo não é necessário para o Python --
então por exemplo "%ld" é idêntico a "%d".

Os tipos de conversão são:

+--------------+-------------------------------------------------------+---------+
| Conversão    | Significado                                           | Notas   |
|==============|=======================================================|=========|
| "'d'"        | Número decimal inteiro sinalizador.                   |         |
+--------------+-------------------------------------------------------+---------+
| "'i'"        | Número decimal inteiro sinalizador.                   |         |
+--------------+-------------------------------------------------------+---------+
| "'o'"        | Valor octal sinalizador.                              | (1)     |
+--------------+-------------------------------------------------------+---------+
| "'u'"        | Tipo obsoleto - é idêntico a "'d'".                   | (6)     |
+--------------+-------------------------------------------------------+---------+
| "'x'"        | Sinalizador hexadecimal (minúsculas).                 | (2)     |
+--------------+-------------------------------------------------------+---------+
| "'X'"        | Sinalizador hexadecimal (maiúscula).                  | (2)     |
+--------------+-------------------------------------------------------+---------+
| "'e'"        | Formato exponencial de ponto flutuante (minúsculas).  | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'E'"        | Formato exponencial de ponto flutuante (maiúscula).   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'f'"        | Formato decimal de ponto flutuante.                   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'F'"        | Formato decimal de ponto flutuante.                   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'g'"        | O formato de ponto flutuante. Usa o formato           | (4)     |
|              | exponencial em minúsculas se o expoente for inferior  |         |
|              | a -4 ou não inferior a precisão, formato decimal,     |         |
|              | caso contrário.                                       |         |
+--------------+-------------------------------------------------------+---------+
| "'G'"        | Formato de ponto flutuante. Usa o formato exponencial | (4)     |
|              | em maiúsculas se o expoente for inferior a -4 ou não  |         |
|              | inferior que a precisão, formato decimal, caso        |         |
|              | contrário.                                            |         |
+--------------+-------------------------------------------------------+---------+
| "'c'"        | Caráter único (aceita inteiro ou um único caractere   |         |
|              | String).                                              |         |
+--------------+-------------------------------------------------------+---------+
| "'r'"        | String (converte qualquer objeto Python usando a      | (5)     |
|              | função "repr()").                                     |         |
+--------------+-------------------------------------------------------+---------+
| "'s'"        | String (converte qualquer objeto Python usando a      | (5)     |
|              | função "str()").                                      |         |
+--------------+-------------------------------------------------------+---------+
| "'a'"        | String (converte qualquer objeto Python usando a      | (5)     |
|              | função "ascii()").                                    |         |
+--------------+-------------------------------------------------------+---------+
| "'%'"        | Nenhum argumento é convertido, resultando um          |         |
|              | caractere "''%'" no resultado.                        |         |
+--------------+-------------------------------------------------------+---------+

Notas:

1. A forma alternativa faz com que um especificador octal principal
   ("'0o'") seja inserido antes do primeiro dígito.

2. O formato alternativo produz um "'0x'" ou "'0X'"  (dependendo se o
   formato  "'x'" or "'X'" foi usado) para ser inserido antes do
   primeiro dígito.

3. A forma alternativa faz com que o resultado sempre contenha um
   ponto decimal, mesmo que nenhum dígito o siga.

   A precisão determina o número de dígitos após o ponto decimal e o
   padrão é 6.

4. A forma alternativa faz com que o resultado sempre contenha um
   ponto decimal e os zeros à direita não sejam removidos, como de
   outra forma seriam.

   A precisão determina o número de dígitos significativos antes e
   depois do ponto decimal e o padrão é 6.

5. Se a precisão for "N", a saída será truncada em caracteres "N".

6. Veja **PEP 237**.

Como as Strings do Python possuem comprimento explícito, "%s" as
conversões não assumem que "'\0'" é o fim da string.

Alterado na versão 3.1: "%f" as conversões para números cujo valor
absoluto é superior a 1e50 não são mais substituídas pela conversão
"%g".


Tipos de Sequência Binária --- "bytes", "bytearray", "memoryview"
=================================================================

Os principais tipos embutidos para manipular dados binários são
"bytes" e "bytearray". Eles são suportados por "memoryview" a qual usa
o buffer protocol para acessar a memória de outros objetos binários
sem precisar fazer uma cópia.

O módulo "array" suporta armazenamento eficiente de tipos de dados
básicos como inteiros de 32 bits e valores de ponto-flutuante com
precisão dupla IEEE754.


Objetos Bytes
-------------

Objetos bytes são sequências imutáveis de bytes simples. Como muitos
protocolos binários importantes são baseados em codificação ASCII de
texto, objetos bytes oferecem diversos métodos que são válidos apenas
quando trabalhamos com dados compatíveis com ASCII, e são proximamente
relacionados com objetos string em uma variedade de outros sentidos.

class bytes([source[, encoding[, errors]]])

   Em primeiro lugar, a sintaxe para literais de bytes é em grande
   parte a mesma para literais de String, exceto que um prefixo "b" é
   adicionado:

   * Aspas simples: "b'still allows embedded "double" quotes'"

   * Aspas duplas: "b"still allows embedded 'single' quotes"".

   * Aspas triplas: "b'''3 single quotes'''", "b"""3 double quotes""""

   Apenas caracteres ASCII são permitidos em literais de bytes
   (independentemente do encoding declarado). Qualquer valor binário
   superior a 127 deverá ser inserido em bytes literais usando o
   Escape Sequence apropriada.

   Assim como string literais, bytes literais também podem usar um
   prefixo "r" para desabilitar o processamento de sequências de
   escape. Veja String e Bytes literais para mais sobre as várias
   formas de bytes literais, incluindo suporte a sequências de escape.

   Enquanto bytes literais e representações são baseados em texto
   ASCII, objetos bytes na verdade se comportam como sequências
   imutáveis de inteiros, com cada valor na sequência restrito aos
   limites "0 <= x < 256" (tentativas de violar essa restrição irão
   disparar "ValueError"). Isto é feito deliberadamente para enfatizar
   que enquanto muitos formatos binários incluem elementos baseados em
   ASCII e podem ser utilmente manipulados com alguns algoritmos
   orientados a texto, esse não é geralmente o caso para dados
   binários arbitrários (aplicar algoritmos de processamento de texto
   cegamente em formatos de dados binários que não são compatíveis com
   ASCII irá usualmente resultar em dados corrompidos).

   Além das formas literais, os objetos bytes podem ser criados de
   várias outras maneiras:

   * Um bytes preenchido com objetos zero com um comprimento
     especificado: "bytes(10)"

   * De um iterável de inteiros: "bytes(range(20))"

   * Copiando dados binários existentes através do protocolo de
     Buffer: "bytes(obj)"

   Veja também os bult-ins bytes.

   Como 2 dígitos hexadecimais correspondem precisamente a apenas um
   byte, números hexadecimais são um formato comumente usado para
   descrever dados binários. Portanto, o tipo bytes tem um método de
   classe adicional para ler dados nesse formato:

   classmethod fromhex(string)

      Este método de classe da classe "bytes" retorna um objeto bytes,
      decodificando o objeto string fornecido. A string deve conter
      dois dígitos hexadecimais por byte, com espaço em branco ASCII
      sendo ignorado.

      >>> bytes.fromhex('2Ef0 F1f2  ')
      b'.\xf0\xf1\xf2'

      Alterado na versão 3.7: "bytes.fromhex()" agora ignora todos os
      espaços em branco em ASCII na string, não apenas espaços.

   Uma função de conversão reversa existe para transformar um objeto
   bytes na sua representação hexadecimal.

   hex()

      Retorna um objeto string contendo dois dígitos hexadecimais para
      cada byte na instância.

      >>> b'\xf0\xf1\xf2'.hex()
      'f0f1f2'

      Novo na versão 3.5.

Como objetos bytes são sequências de inteiros (certo parentesto a uma
tupla), para um objeto bytes *b*, "b[0]" será um inteiro, enquanto
"b[0:1]" será um objeto bytes de comprimento 1. (Isso contrasta com
strings de texto, onde tanto o uso por índice quanto por fatiamento
irão produzir uma string de comprimento 1)

A representação de objetos bytes utiliza o formato literal ("b'...'"),
uma vez que ela é frequentemente mais útil do que, por exemplo,
"bytes([46, 46, 46])". Você sempre pode converter um objeto bytes em
uma lista de inteiros usando "list(b)".

Nota:

  Para usuários do Python 2.x: nas séries do Python 2.x, uma variedade
  de conversões implícitas entre strings de 8-bits (a coisa mais
  próxima a um tipo de dados binário embutido que o 2.x oferece) e
  Unicode strings era permitida. Isso era uma solução de contorno para
  compatibilidade retroativa para contabilizar o fato que o Python
  originalmente apenas suportava texto de 8-bits, e texto Unicode foi
  adicionado mais tarde. No Python 3.x, essas conversões implícitas se
  foram - conversões entre dados binários de 8-bits e texto Unicode
  devem ser explícitas, e bytes e objetos string irão sempre comparar
  como diferentes.


Bytearray Objects
-----------------

Objetos "bytearray" são mutáveis, em contrapartida a objetos "bytes".

class bytearray([source[, encoding[, errors]]])

   Não existe sintaxe literal dedicada para objetos de bytearray, ao
   invés disso eles sempre são criados através da chamada do
   construtor:

   * Criando uma instância vazia: "bytearray()"

   * Criando uma instância cheia de zero com um determinado
     comprimento: "bytearray(10)"

   * A partir de inteiros iteráveis: "bytearray(range(20))"

   * Copiando dados binários existentes através do protocolo de
     buffer: "bytearray(b'Hi!')"

   Como os objetos bytearray são mutáveis, os mesmos suportam as
   operações de seqüência mutable  além das operações comuns de bytes
   e bytearray descritas em Operações com Bytes e Bytearray.

   Veja também o tipo built-in bytearray.

   Uma vez que 2 dígitos hexadecimais correspondem precisamente a um
   único byte, os números hexadecimais são um formato comumente usado
   para descrever dados binários. Consequentemente, o tipo de
   bytearray tem um método de classe adicional para ler dados nesse
   formato:

   classmethod fromhex(string)

      Este método de classe da classe "bytearray" retorna um objeto
      bytearray, decodificando o objeto string fornecido. A string
      deve conter dois dígitos hexadecimais por byte, com espaços em
      branco ASCII sendo ignorados.

      >>> bytearray.fromhex('2Ef0 F1f2  ')
      bytearray(b'.\xf0\xf1\xf2')

      Alterado na versão 3.7: "bytearray.fromhex()" agora ignora todos
      os espaços em branco em ASCII na string, não apenas espaços.

   Existe uma função de conversão reversa para transformar um objeto
   bytearray em sua representação hexadecimal.

   hex()

      Retorna um objeto string contendo dois dígitos hexadecimais para
      cada byte na instância.

      >>> bytearray(b'\xf0\xf1\xf2').hex()
      'f0f1f2'

      Novo na versão 3.5.

Como os objetos bytearray são sequências de inteiros (semelhante a uma
lista), para um objeto bytearray *b*, "b[0]" será um inteiro, enquanto
que "b[0:1]" será um objeto bytearray de comprimento 1. (Isso
contrasta com as Strings de texto, onde tanto a indexação como o
fatiamento produzirão seqüências de comprimento 1)

A representação de objetos bytearray utiliza o formato literal bytes
("bytearray(b'...')"), uma vez que muitas vezes é mais útil do que,
por exemplo, "bytearray([46, 46, 46])". Você sempre pode converter um
objeto bytearray em uma lista de inteiros usando "list(b)".


Operações com Bytes e Bytearray
-------------------------------

Ambos os tipos, bytes e os objetos bytearray suportam as operações de
sequência *common 1*. Os mesmo interagem não apenas com operandos do
mesmo tipo, mas com qualquer *bytes-like object*. Devido a esta
flexibilidade, os mesmos podem ser misturados livremente em operações
sem causar erros. No entanto, o tipo de retorno do resultado pode
depender da ordem dos operandos.

Nota:

  Os métodos em bytes e objetos Bytearray não aceitam Strings como
  argumentos, assim como os métodos de Strings não aceitam bytes como
  argumentos. Por exemplo, devemos escrever:

     a = "abc"
     b = a.replace("a", "f")

  e:

     a = b"abc"
     b = a.replace(b"a", b"f")

Alguns operações com bytes e bytearray assumem o uso de formatos
binários compatíveis com ASCII e, portanto, devem ser evitados ao
trabalhar com dados binários arbitrários. Essas restrições são
abordadas a seguir.

Nota:

  O uso dessas operações baseadas em ASCII para manipular dados
  binários que não são armazenados num formato baseado em ASCII poderá
  resultar na corrupção de dados.

Os métodos a seguir em Bytes e Bytearray podem ser usados com dados
binários arbitrários.

bytes.count(sub[, start[, end]])
bytearray.count(sub[, start[, end]])

   Retorna o número de ocorrências não sobrepostas de subsequência
   *sub* no intervalo [*start*, *end*]. Os argumentos opcionais
   *start* e *end* são interpretados como na notação de fatiamento.

   A subsequência a ser procurada poderá ser qualquer *bytes-like
   object* ou um inteiro no intervalo de 0 a 255.

   Alterado na versão 3.3: Também aceita um número inteiro no
   intervalo de 0 a 255 como subsequência.

bytes.decode(encoding="utf-8", errors="strict")
bytearray.decode(encoding="utf-8", errors="strict")

   Retorna uma String decodificada dos bytes fornecidos. A codificação
   padrão é "'utf-8'`". Os *erros* podem ser fornecidos para definir
   um esquema de tratamento de erros diferente. O padrão para *errors*
   é "'strict'", o que significa que os erros de codificação geram uma
   exceção "UnicodeError". Outros valores possíveis são "'ignore'`",
   "'replace'" e qualquer outro nome registrado pela função
   "codecs.register_error()", veja a seção Error Handlers. Para obter
   uma lista dos possíveis encoding, veja a seção Standard Encodings.

   Nota:

     Passando o argumento *encoding* para a classe "str" permite
     decodificar qualquer *bytes-like object* diretamente, sem
     precisar ter bytes temporário ou um objeto bytearray.

   Alterado na versão 3.1: Adicionado suporte para argumentos keyword
   arguments.

bytes.endswith(suffix[, start[, end]])
bytearray.endswith(suffix[, start[, end]])

   Retorna "True" se os dados binários encerra com o parâmetro
   *suffix* especificado, caso contrário retorna "False". *suffix*
   também pode ser uma tupla de sufixos para averiguar. Com o
   parâmetro opcional *start*, a procura começa naquela posição. Com o
   parâmetro opcional *end*, o método encerra a comparação na posição
   fornecida.

   O sufixo(es) para buscas pode ser qualquer termos *bytes-like
   object*.

bytes.find(sub[, start[, end]])
bytearray.find(sub[, start[, end]])

   Retorna o índice mais baixo nos dados onde a sub-sequência *sub* é
   encontrada, tal que *sub* está contida na fatia "s[start:end]".
   Argumentos opcionais *start* e *end* são interpretados como na
   notação de fatiamento. Retorna "-1" se *sub* não for localizada.

   A subsequência a ser procurada poderá ser qualquer *bytes-like
   object* ou um inteiro no intervalo de 0 a 255.

   Nota:

     O método "find()" deve ser usado apenas se você precisa saber a
     posição de *sub*. Para verificar se *sub* é uma substring ou não,
     use o operador "in":

        >>> b'Py' in b'Python'
        True

   Alterado na versão 3.3: Também aceita um número inteiro no
   intervalo de 0 a 255 como subsequência.

bytes.index(sub[, start[, end]])
bytearray.index(sub[, start[, end]])

   Como "find()", mas levanta a exceção "ValueError" quando a
   subsequência não for encontrada.

   A subsequência a ser procurada poderá ser qualquer *bytes-like
   object* ou um inteiro no intervalo de 0 a 255.

   Alterado na versão 3.3: Também aceita um número inteiro no
   intervalo de 0 a 255 como subsequência.

bytes.join(iterable)
bytearray.join(iterable)

   Retorna um objeto bytes ou bytearray que é a concatenação das
   sequências de dados binários no *iterável*. Um "TypeError" será
   levantado se existirem quaisquer valores que não sejam *objeto byte
   ou similar*, no *iterável*, incluindo objetos "str". O separador
   entre elementos é o conteúdo do objeto bytes ou bytearray que está
   fornecendo este método.

static bytes.maketrans(from, to)
static bytearray.maketrans(from, to)

   Este método estático retorna uma tabela de tradução usável para
   "bytes.translate()", que irá mapear cada caractere em *from* no
   caractere na mesma posição em *to*; *from* e *to* devem ambos ser
   *objeto byte ou similar* e ter o mesmo comprimento.

   Novo na versão 3.1.

bytes.partition(sep)
bytearray.partition(sep)

   Quebra a sequência na primeira ocorrência de *sep*, e retorna uma
   tupla com 3 elementos contendo a parte antes do separador, o
   próprio separator, e a parte após o separador. Se o separador não
   for encontrado, retorna uma tupla com 3 elementos contendo uma
   cópia da sequência original, seguido de dois bytes ou objetos
   bytearray vazios.

   O separador para buscar pode ser qualquer termos *bytes-like
   object*.

bytes.replace(old, new[, count])
bytearray.replace(old, new[, count])

   Retornar uma cópia da seqüência com todas as ocorrências de
   subsequências *antigas* substituídas por *novo*. Se o argumento
   opcional *count* for fornecido, apenas as primeiras ocorrências de
   *count* serão substituídas.

   A subsequência para buscar e substituição pode ser qualquer termos
   *bytes-like object*.

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.rfind(sub[, start[, end]])
bytearray.rfind(sub[, start[, end]])

   Retorna o índice mais alto na seqüência onde a subsequência *sub*
   foi encontrada, de modo que *sub* esteja contido dentro de
   "s[start:end]". Os argumentos opcionais *start* e *end* são
   interpretados como na notação de fatiamento. Caso ocorra algum
   problema será retorando "-1".

   A subsequência a ser procurada poderá ser qualquer *bytes-like
   object* ou um inteiro no intervalo de 0 a 255.

   Alterado na versão 3.3: Também aceita um número inteiro no
   intervalo de 0 a 255 como subsequência.

bytes.rindex(sub[, start[, end]])
bytearray.rindex(sub[, start[, end]])

   Semelhante a "rfind()" mas levanta "ValueError" quando a
   subsequência *sub* não é encontrada.

   A subsequência a ser procurada poderá ser qualquer *bytes-like
   object* ou um inteiro no intervalo de 0 a 255.

   Alterado na versão 3.3: Também aceita um número inteiro no
   intervalo de 0 a 255 como subsequência.

bytes.rpartition(sep)
bytearray.rpartition(sep)

   Quebra a sequência na primeira ocorrência de *sep*, e retorna uma
   tupla com 3 elementos contendo a parte antes do separador, o
   próprio separator, e a parte após o separador. Se o separador não
   for encontrado, retorna uma tupla com 3 elementos contendo dois
   bytes ou objetos bytearray vazios, seguido por uma cópia da
   sequência original.

   O separador para buscar pode ser qualquer termos *bytes-like
   object*.

bytes.startswith(prefix[, start[, end]])
bytearray.startswith(prefix[, start[, end]])

   Retorna "True" se os dados binários começam com o *prefix*
   especificado, caso contrário retorna "False". *prefix* também pode
   ser uma tupla de prefixos para procurar. Com o parâmetro opcional
   *start*, começa a procura na posição indicada. Com o parâmetro
   opcional *end*, encerra a procura na posição indicada.

   Os prefix(os) para pesquisar podem ser qualquer *objeto-byte ou
   similar*.

bytes.translate(table, delete=b'')
bytearray.translate(table, delete=b'')

   Retorna uma cópia dos bytes ou objeto bytearray, onde todas as
   ocorrências de bytes do argumento opcional *delete* são removidas,
   e os bytes restantes foram mapeados através da tabela de tradução
   fornecida, a qual deve ser um objeto bytes de comprimento 256.

   Voce pode usar o método "bytes.maketrans()" para criar uma tabela
   de tradução.

   Define o argumento *table* como "None" para traduções que excluem
   apenas caracteres:

      >>> b'read this short text'.translate(None, b'aeiou')
      b'rd ths shrt txt'

   Alterado na versão 3.6: *delete* agora é suportado como um keyword
   argument.

Os seguintes métodos de objetos bytes e bytearray tem comportamentos
padrões que assumem o uso de formatos binários compatíveis com ASCII,
mas ainda podem ser usados com dados binários arbitrários através da
passagem argumentos apropriados. Perceba que todos os métodos de
bytearray nesta seção *não* alteram os argumentos, e ao invés disso
produzem novos objetos.

bytes.center(width[, fillbyte])
bytearray.center(width[, fillbyte])

   Retorna uma cópia do objeto centralizado em uma sequência de
   comprimento *width*. Preenchimento  é feito usando o *fillbyte*
   especificado (o padrão é um espaço ASCII). Para objetos "bytes", a
   sequência original é retornada se *width* é menor que ou igual a
   "len(s)".

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.ljust(width[, fillbyte])
bytearray.ljust(width[, fillbyte])

   Retorna uma cópia do objeto alinhado a esquerda em uma sequência de
   comprimento *width*. Preenchimento é feito usando o *fillbyte*
   especificado (o padrão é um espaço ASCII). Para objetos "bytes", a
   sequência original é retornada se *width* é menor que ou igual a
   "len(s)".

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.lstrip([chars])
bytearray.lstrip([chars])

   Retorna uma cópia da sequência com bytes especificados no início e
   no final removidos. O argumento *chars* é uma sequência binária que
   especifica o conjunto de bytes a serem removidos - o nome refere-se
   ao fato de este método é usualmente utilizado com caracteres ASCII.
   Se for omitido ou for "None", o argumento *chars* irá remover por
   padrão os espaços em branco ASCII. O argumento *chars* não é um
   prefixo; ao contrário disso, todas as combinações dos seus seus
   valores são removidas:

      >>> b'   spacious   '.lstrip()
      b'spacious   '
      >>> b'www.example.com'.lstrip(b'cmowz.')
      b'example.com'

   A sequência binária de valores de bytes a serem removidos pode ser
   qualquer *objeto byte ou similar*.

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.rjust(width[, fillbyte])
bytearray.rjust(width[, fillbyte])

   Retorna uma cópia do objeto alinhado a direita em uma sequência de
   comprimento *width*. Preenchimento é feito usando o *fillbyte*
   especificado (o padrão é um espaço ASCII). Para objetos "bytes", a
   sequência original é retornada se *width* é menor que ou igual a
   "len(s)".

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.rsplit(sep=None, maxsplit=-1)
bytearray.rsplit(sep=None, maxsplit=-1)

   Divide a sequência binária em subsequência do mesmo tipo, usando
   *sep* como um delimitador de string. Se *maxsplit* é fornecido, no
   máximo *maxsplit* divisões são feitas, aquelas que estão *mais à
   direita*. Se *sep* não é especificado ou é "None", qualquer
   subsequência consistindo unicamente de espaço em branco ASCII é um
   separador. Exceto por dividir pela direita, "rsplit()" comporta-se
   como "split()", o qual é descrito em detalhes abaixo.

bytes.rstrip([chars])
bytearray.rstrip([chars])

   Retorna uma cópia da sequência com bytes especificados no final
   removidos. O argumento *chars* é uma sequência binária que
   especifica o conjunto de bytes a serem removidos - o nome refere-se
   ao fato de este método é usualmente utilizado com caracteres ASCII.
   Se for omitido ou for "None", o argumento *chars* irá remover por
   padrão os espaços em branco ASCII. O argumento *chars* não é um
   sufixo; ao contrário disso, todas as combinações dos seus seus
   valores são removidas:

      >>> b'   spacious   '.rstrip()
      b'   spacious'
      >>> b'mississippi'.rstrip(b'ipz')
      b'mississ'

   A sequência binária de valores de bytes a serem removidos pode ser
   qualquer *objeto byte ou similar*.

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.split(sep=None, maxsplit=-1)
bytearray.split(sep=None, maxsplit=-1)

   Divide a sequência binária em subsequências do mesmo tipo, usando
   *sep* como o delimitador de string. Se *maxsplit* é fornecido e
   não-negativo, no máximo *maxsplit* divisões são feitas (logo, a
   lista terá no máximo "maxsplit+1" elementos). Se *maxsplit* não é
   especificado ou é "-1", então não existe limite no número de
   divisões (todas as divisões possíveis são feitas).

   Se *sep* é fornecido, delimitadores consecutivos não são agrupados
   juntos e eles são destinados para delimitar strings vazias (por
   exemplo "b'1,,2'.split(b',')" retorna "[b'1', b'', b'2']"). O
   argumento *sep* pode consistir de uma sequência de múltiplos bytes
   (por exemplo, "b'1<>2<>3'.split(b'<>')" retorna "[b'1', b'2',
   b'3']"). Separar uma sequência vazia com um separador especificado
   retorna "[b'']" ou "[bytearray(b'')]" dependendo do tipo do objeto
   que está sendo separado. O argumento *sep* pode ser qualquer
   *bytes-like object*.

   Por exemplo:

      >>> b'1,2,3'.split(b',')
      [b'1', b'2', b'3']
      >>> b'1,2,3'.split(b',', maxsplit=1)
      [b'1', b'2,3']
      >>> b'1,2,,3,'.split(b',')
      [b'1', b'2', b'', b'3', b'']

   Se *sep* não for especificado ou for "None", um algoritmo diferente
   de separação é aplicado: ocorrências consecutivas de espaços em
   branco ASCII são consideradas como um separador único, e o
   resultado não conterá strings vazias no início ou no final, se a
   sequência tiver espaços em branco no início ou no final.
   Consequentemente, separar uma sequência vazia ou uma sequência que
   consiste apenas de espaços em branco ASCII sem um separador
   especificado, retorna "[]".

   Por exemplo:

      >>> b'1 2 3'.split()
      [b'1', b'2', b'3']
      >>> b'1 2 3'.split(maxsplit=1)
      [b'1', b'2 3']
      >>> b'   1   2   3   '.split()
      [b'1', b'2', b'3']

bytes.strip([chars])
bytearray.strip([chars])

   Retorna uma cópia da sequência com os bytes especificados no início
   e no final removidos. O argumento *chars* é uma sequência binária
   que especifica o conjunto de bytes a serem removidos - o nome
   refere-se ao fato que este método é normalmente utilizado com
   caracteres ASCII. Se for omitido ou for "None", o argumento *chars*
   irá remover por padrão os espaços em branco ASCII. O argumento
   *chars* não é um prefixo, nem um sufixo; ao contrário disso, todas
   as combinações dos seus seus valores são removidas:

      >>> b'   spacious   '.strip()
      b'spacious'
      >>> b'www.example.com'.strip(b'cmowz.')
      b'example'

   A sequência binária de valores de bytes a serem removidos pode ser
   qualquer *objeto byte ou similar*.

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

O seguintes métodos de bytes e objetos bytearray assumem o uso de
formatos binários compatíveis com ASCII e não devem ser aplicados a
dados binários arbitrários. Perceba que todos os métodos de bytearray
nesta seção *não* operam in place, e ao invés disso produzem novos
objetos.

bytes.capitalize()
bytearray.capitalize()

   Retorna uma cópia da sequência com cada byte interpretado como um
   caractere ASCII, e o primeiro byte em letra maiúscula e o resto em
   letras minúsculas. Valores de bytes que não são ASCII são passados
   adiante sem mudanças.

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.expandtabs(tabsize=8)
bytearray.expandtabs(tabsize=8)

   Retorna uma cópia da sequência onde todos os caracteres de
   tabulação ASCII são substituídos por um ou mais espaços ASCII,
   dependendo da coluna atual e do tamanho fornecido para a tabulação.
   Posições de tabulação ocorrem a cada *tabsize* bytes (o padrão é 8,
   dada as posições de tabulação nas colunas 0, 8, 16 e assim por
   diante). Para expandir a sequência, a coluna atual é definida como
   zero e a sequência é examinada byte por byte. Se o byte é um
   caractere ASCII de tabulação ("b'\t'"), um ou mais caracteres de
   espaço são inseridos no resultado até que a coluna atual seja igual
   a próxima posição de tabulação. (O caractere de tabulação em si não
   é copiado.) Se o byte atual é um caractere ASCII de nova linha
   ("b'\n'") ou de retorno ("b'\r'"), ele é copiado e a coluna atual é
   resetada para zero. Qualquer outro byte é copiado sem ser
   modificado e a coluna atual é incrementada em uma unidade
   independentemente de como o byte é representado quanto é impresso:

      >>> b'01\t012\t0123\t01234'.expandtabs()
      b'01      012     0123    01234'
      >>> b'01\t012\t0123\t01234'.expandtabs(4)
      b'01  012 0123    01234'

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.isalnum()
bytearray.isalnum()

   Retorna "True" se todos os bytes na sequência são caracteres
   alfabéticos ASCII ou dígitos decimais ASCII e a sequência não é
   vazia, "False" caso contrário. Caracteres alfabéticos ASCII são
   aqueles valores de byte na sequência
   "b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'". Dígitos
   decimais ASCII são aqueles valores de byte na sequência
   "b'0123456789'".

   Por exemplo:

      >>> b'ABCabc1'.isalnum()
      True
      >>> b'ABC abc1'.isalnum()
      False

bytes.isalpha()
bytearray.isalpha()

   Retorna "True" se todos os bytes na sequência são caracteres
   alfabéticos ASCII e a sequência não é vazia, "False" caso
   contrário. Caracteres alfabéticos ASCII são aqueles cujo valor dos
   bytes estão na sequência
   "b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'".

   Por exemplo:

      >>> b'ABCabc'.isalpha()
      True
      >>> b'ABCabc1'.isalpha()
      False

bytes.isascii()
bytearray.isascii()

   Retorna "True" se a sequência é vazia ou todos os bytes na
   sequência são ASCII, "False" caso contrário. Bytes ASCII estão no
   intervalo 0-0x7F.

   Novo na versão 3.7.

bytes.isdigit()
bytearray.isdigit()

   Retorna "True" se todos os bytes na sequência são dígitos decimais
   ASCII e a sequência não é vazia, "False" caso contrário. Dígitos
   decimais ASCII são aqueles cujos valores dos bytes estão na
   sequência "b'0123456789'".

   Por exemplo:

      >>> b'1234'.isdigit()
      True
      >>> b'1.23'.isdigit()
      False

bytes.islower()
bytearray.islower()

   Retorna "True" se existe pelo menos um caractere minúsculo ASCII na
   sequência e nenhum caractere maiúsculo ASCII, "False" caso
   contrário.

   Por exemplo:

      >>> b'hello world'.islower()
      True
      >>> b'Hello world'.islower()
      False

   Caracteres minúsculos ASCII são aqueles cujos valores de bytes
   estão na sequência "b'abcdefghijklmnopqrstuvwxyz'". Caracteres
   maiúsculos ASCII são aqueles cujos valores de bytes estão na
   sequência "b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'".

bytes.isspace()
bytearray.isspace()

   Retorna "True" se todos os bytes na sequência são espaço em branco
   ASCII e a sequência não é vazia, "False" caso contrário. Caracteres
   de espaço em branco ASCII são aqueles cujos valores de bytes estão
   na sequência "b' \t\n\r\x0b\f'" (espaço, tabulação, nova linha,
   retorno do cursor, tabulação vertical, formulário de entrada).

bytes.istitle()
bytearray.istitle()

   Retorna "True" se a sequência é titlecased ASCII e a sequência não
   é vazia, "False" caso contrário. Veja "bytes.title()" para mais
   detalhes sobre a definição de "titlecased".

   Por exemplo:

      >>> b'Hello World'.istitle()
      True
      >>> b'Hello world'.istitle()
      False

bytes.isupper()
bytearray.isupper()

   Retorna "True" se existe pelo menos um caractere maiúsculo
   alfabético ASCII na sequência e nenhum caractere minúsculo ASCII,
   "False" caso contrário.

   Por exemplo:

      >>> b'HELLO WORLD'.isupper()
      True
      >>> b'Hello world'.isupper()
      False

   Caracteres minúsculos ASCII são aqueles cujos valores de bytes
   estão na sequência "b'abcdefghijklmnopqrstuvwxyz'". Caracteres
   maiúsculos ASCII são aqueles cujos valores de bytes estão na
   sequência "b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'".

bytes.lower()
bytearray.lower()

   Retorna uma cópia da sequência com todos os caracteres maiúsculos
   ASCII convertidos para os seus correspondentes caracteres
   minúsculos.

   Por exemplo:

      >>> b'Hello World'.lower()
      b'hello world'

   Caracteres minúsculos ASCII são aqueles cujos valores de bytes
   estão na sequência "b'abcdefghijklmnopqrstuvwxyz'". Caracteres
   maiúsculos ASCII são aqueles cujos valores de bytes estão na
   sequência "b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'".

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.splitlines(keepends=False)
bytearray.splitlines(keepends=False)

   Retorna uma lista das linhas na sequência binária, quebrando nos
   limites ASCII das linhas. Este método usa a abordagem de *novas
   linhas universais* para separar as linhas. Quebras de linhas não
   são incluídas nas listas resultantes a não ser que *keepends* seja
   fornecido e verdadeiro.

   Por exemplo:

      >>> b'ab c\n\nde fg\rkl\r\n'.splitlines()
      [b'ab c', b'', b'de fg', b'kl']
      >>> b'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
      [b'ab c\n', b'\n', b'de fg\r', b'kl\r\n']

   Ao contrário de "split()", quando uma string delimitadora *sep* é
   fornecida, este método retorna uma lista vazia para a string vazia,
   e uma quebra de linha terminal não resulta em uma linha extra:

      >>> b"".split(b'\n'), b"Two lines\n".split(b'\n')
      ([b''], [b'Two lines', b''])
      >>> b"".splitlines(), b"One line\n".splitlines()
      ([], [b'One line'])

bytes.swapcase()
bytearray.swapcase()

   Retorna uma cópia da sequência com todos os caracteres minúsculos
   ASCII convertidos para caracteres maiúsculos correspondentes, e
   vice-versa.

   Por exemplo:

      >>> b'Hello World'.swapcase()
      b'hELLO wORLD'

   Caracteres minúsculos ASCII são aqueles cujos valores de bytes
   estão na sequência "b'abcdefghijklmnopqrstuvwxyz'". Caracteres
   maiúsculos ASCII são aqueles cujos valores de bytes estão na
   sequência "b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'".

   Ao contrário de "str.swapcase()", é sempre fato que
   "bin.swapcase().swapcase() == bin" para as versões binárias.
   Conversões maiúsculas/minúsculas são simétricas em ASCII, apesar
   que isso não é geralmente verdade para pontos de codificação
   arbitrários Unicode.

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.title()
bytearray.title()

   Retorna uma versão titlecased da sequência binária, onde palavras
   iniciam com um caractere ASCII com letra maiúscula e os caracteres
   restantes são em letras minúsculas. Bytes quem não possuem
   diferença entre maiúscula/minúscula não são alterados.

   Por exemplo:

      >>> b'Hello world'.title()
      b'Hello World'

   Caracteres minúsculos ASCII são aqueles cujos valores de byte estão
   na sequência "b'abcdefghijklmnopqrstuvwxyz'". Caracteres maiúsculos
   ASCII são aqueles cujos valores de byte estão na
   sequência``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'>>``<<. Todos os outros
   valores de bytes ignoram maiúsculas/minúsculas.

   O algoritmo usa uma definição simples independente de idioma para
   uma palavra, como grupos de letras consecutivas. A definição
   funciona em muitos contextos, mas isso significa que apóstrofes em
   contradições e possessivos formam limites de palavras, os quais
   podem não ser o resultado desejado:

      >>> b"they're bill's friends from the UK".title()
      b"They'Re Bill'S Friends From The Uk"

   Uma solução alternativa para os apóstrofes pode ser construída
   usando expressões regulares:

      >>> import re
      >>> def titlecase(s):
      ...     return re.sub(rb"[A-Za-z]+('[A-Za-z]+)?",
      ...                   lambda mo: mo.group(0)[0:1].upper() +
      ...                              mo.group(0)[1:].lower(),
      ...                   s)
      ...
      >>> titlecase(b"they're bill's friends.")
      b"They're Bill's Friends."

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.upper()
bytearray.upper()

   Retorna uma cópia da sequência com todos os caracteres minúsculos
   ASCII convertidos para sua contraparte maiúscula correspondente.

   Por exemplo:

      >>> b'Hello World'.upper()
      b'HELLO WORLD'

   Caracteres minúsculos ASCII são aqueles cujos valores de bytes
   estão na sequência "b'abcdefghijklmnopqrstuvwxyz'". Caracteres
   maiúsculos ASCII são aqueles cujos valores de bytes estão na
   sequência "b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'".

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.

bytes.zfill(width)
bytearray.zfill(width)

   Retorna uma cópia da sequência preenchida a esquerda com dígitos
   "b'0'" ASCII para produzir uma sequência se comprimento *width*. Um
   sinal de prefixo inicial ("b'+'"/ "b'-'") é controlado através da
   inserção de preenchimento *depois* do caractere de sinal, ao invés
   de antes. Para objetos "bytes", a sequência original é retornada se
   *width* é menor que ou igual a "len(seq)".

   Por exemplo:

      >>> b"42".zfill(5)
      b'00042'
      >>> b"-42".zfill(5)
      b'-0042'

   Nota:

     A versão Bytearray deste método *não* opera no local - o mesmo
     sempre produz um novo objeto, mesmo que não tenha sido feitas
     alterações.


Estilo de Formatação de bytes "printf"-style
--------------------------------------------

Nota:

  As operações de formatação descritas aqui exibem uma variedade de
  peculiaridades que levam a uma série de erros comuns (como a falha
  na exibição de Tuplas e Dicionários corretamente). Se o valor que
  está sendo impresso puder ser uma tupla ou dicionário, envolva-o
  numa tupla.

Objetos Bytes ("bytes"/"bytearray") possuem uma operação integrada
exclusiva: o operador "%" (modulo). Isso também é conhecido como o
bytes de *formatação* ou o operador de *interpolação*. Dado "format %
values" (onde *format* é um objeto bytes), as especificações de
conversão "%" em *format* são substituídas por zero ou mais elementos
de *values*. O efeito é semelhante ao uso da função "sprintf()" na
linguagem C.

Se *format* requer um único argumento, *values* poderá ser um único
objeto não-tuple. [5] Caso contrário, *values* deverá ser uma tupla
com exatamente o número de itens especificados pelo objeto de
formatação de Bytes, ou um único objeto de mapeamento (por exemplo, um
dicionário).

Um especificador de conversão contém dois ou mais caracteres e tem os
seguintes componentes, que devem aparecer nesta ordem:

1. O caractere "'%'", que determina o início do especificador.

2. Mapeamento de Chaves (opcional), consistindo de uma sequência entre
   parênteses de caracteres (por exemplo, "(algumnome)").

3. Flags de conversão (opcional), que afetam o resultado de alguns
   tipos de conversão.

4. Largura mínima do Campo(opcional). Se for especificado por "'*'"
   (asterisco), a largura real será lida a partir do próximo elemento
   da tupla em *values* e o objeto a converter virá após a largura
   mínima do campo e a precisão que é opcional.

5. Precisão (opcional), fornecido como uma "'.'" (ponto) seguido pela
   precisação.  Se determinado como um "'*'" (um asterisco), a
   precisão real será lida a partir do próximo elemento da tupla em
   *values*, e o valor a converter virá após a precisão.

6. Modificador de Comprimento(opcional).

7. Tipos de Conversão

Quando o argumento a direita é um dicionário (ou outro tipo de
mapeamento), então o formato no objeto bytes *deve* incluir um
mapeamento de chaves entre parêntesis neste dicionário inserido
imediatamente após o caractere "'%'". O mapeamento de chaves seleciona
o valor a ser formatado a partir do mapeamento. Por exemplo:

>>> print(b'%(language)s has %(number)03d quote types.' %
...       {b'language': b"Python", b"number": 2})
b'Python has 002 quote types.'

Nesse caso, nenhum especificador "*" poderá ocorrer num formato (uma
vez que eles exigem uma lista de parâmetros sequenciais).

Os caracteres flags de conversão são:

+-----------+-----------------------------------------------------------------------+
| Flag      | Significado                                                           |
|===========|=======================================================================|
| "'#'"     | A conversão de valor usará o "formulário alternativo" (em que         |
|           | definimos abaixo).                                                    |
+-----------+-----------------------------------------------------------------------+
| "'0'"     | A conversão será preenchida por zeros para valores numéricos.         |
+-----------+-----------------------------------------------------------------------+
| "'-'"     | O valor convertido será ajustado à esquerda (substitui a conversão    |
|           | "'0'" se ambos forem fornecidos).                                     |
+-----------+-----------------------------------------------------------------------+
| "' '"     | (um espaço) Um espaço em branco deverá ser deixado antes de um número |
|           | positivo (ou uma String vazia) produzido por uma conversão assinada.  |
+-----------+-----------------------------------------------------------------------+
| "'+'"     | Um sinal de caractere ("'+'" ou "'-'") precedera a conversão          |
|           | (substituindo o sinalizador "space").                                 |
+-----------+-----------------------------------------------------------------------+

Um modificador de comprimento ("h", "l", ou "L") pode estar presente,
mas será ignorado, pois o mesmo não é necessário para o Python --
então por exemplo "%ld" é idêntico a "%d".

Os tipos de conversão são:

+--------------+-------------------------------------------------------+---------+
| Conversão    | Significado                                           | Notas   |
|==============|=======================================================|=========|
| "'d'"        | Número decimal inteiro sinalizador.                   |         |
+--------------+-------------------------------------------------------+---------+
| "'i'"        | Número decimal inteiro sinalizador.                   |         |
+--------------+-------------------------------------------------------+---------+
| "'o'"        | Valor octal sinalizador.                              | (1)     |
+--------------+-------------------------------------------------------+---------+
| "'u'"        | Tipo obsoleto - é idêntico a "'d'".                   | (8)     |
+--------------+-------------------------------------------------------+---------+
| "'x'"        | Sinalizador hexadecimal (minúsculas).                 | (2)     |
+--------------+-------------------------------------------------------+---------+
| "'X'"        | Sinalizador hexadecimal (maiúscula).                  | (2)     |
+--------------+-------------------------------------------------------+---------+
| "'e'"        | Formato exponencial de ponto flutuante (minúsculas).  | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'E'"        | Formato exponencial de ponto flutuante (maiúscula).   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'f'"        | Formato decimal de ponto flutuante.                   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'F'"        | Formato decimal de ponto flutuante.                   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'g'"        | O formato de ponto flutuante. Usa o formato           | (4)     |
|              | exponencial em minúsculas se o expoente for inferior  |         |
|              | a -4 ou não inferior a precisão, formato decimal,     |         |
|              | caso contrário.                                       |         |
+--------------+-------------------------------------------------------+---------+
| "'G'"        | Formato de ponto flutuante. Usa o formato exponencial | (4)     |
|              | em maiúsculas se o expoente for inferior a -4 ou não  |         |
|              | inferior que a precisão, formato decimal, caso        |         |
|              | contrário.                                            |         |
+--------------+-------------------------------------------------------+---------+
| "'c'"        | Byte simples (aceita objetos inteiros ou de byte      |         |
|              | único).                                               |         |
+--------------+-------------------------------------------------------+---------+
| "'b'"        | Bytes (qualquer objeto que segue o buffer protocol o  | (5)     |
|              | que possui "__bytes__()").                            |         |
+--------------+-------------------------------------------------------+---------+
| "'s'"        | "'s'" é um alias para "'b'" e só deve ser usado para  | (6)     |
|              | bases de código Python2/3.                            |         |
+--------------+-------------------------------------------------------+---------+
| "'a'"        | Bytes (converte qualquer objeto Python usando         | (5)     |
|              | "repr(obj).encode('ascii','backslashreplace)").       |         |
+--------------+-------------------------------------------------------+---------+
| "'r'"        | "'r'" é um alias para "'a'" e só deve ser usado para  | (7)     |
|              | bases de código Python2/3.                            |         |
+--------------+-------------------------------------------------------+---------+
| "'%'"        | Nenhum argumento é convertido, resultando um          |         |
|              | caractere "''%'" no resultado.                        |         |
+--------------+-------------------------------------------------------+---------+

Notas:

1. A forma alternativa faz com que um especificador octal principal
   ("'0o'") seja inserido antes do primeiro dígito.

2. O formato alternativo produz um "'0x'" ou "'0X'"  (dependendo se o
   formato  "'x'" or "'X'" foi usado) para ser inserido antes do
   primeiro dígito.

3. A forma alternativa faz com que o resultado sempre contenha um
   ponto decimal, mesmo que nenhum dígito o siga.

   A precisão determina o número de dígitos após o ponto decimal e o
   padrão é 6.

4. A forma alternativa faz com que o resultado sempre contenha um
   ponto decimal e os zeros à direita não sejam removidos, como de
   outra forma seriam.

   A precisão determina o número de dígitos significativos antes e
   depois do ponto decimal e o padrão é 6.

5. Se a precisão for "N", a saída será truncada em caracteres "N".

6. "b'%s'" está obsoleto, mas não será removido durante a versão 3.x.

7. "b'%r'" entrou em desuso, mas não serão removidos na versão 3.x.

8. Veja **PEP 237**.

Nota:

  A versão Bytearray deste método *não* opera no local - o mesmo
  sempre produz um novo objeto, mesmo que não tenha sido feitas
  alterações.

Ver também:

  **PEP 461** - Adicionar formatação % para to bytes e bytearray

Novo na versão 3.5.


Memory Views
------------

O objeto "memoryview" permite que o código Python acesse os dados
internos de um objeto que suporte o :ref: >>`<<buffer protocol 1' sem
copia-lo.

class memoryview(obj)

   Cria uma "memoryview" que referencia *obj*. *obj* deve suportar o
   protocolo de buffer. Objetos embutidos que suportam o protocolo de
   buffer incluem "bytes" e "bytearray".

   Uma "memoryview" tem a noção de um *elemento*, o qual é a unidade
   de memória atômica manipulada pelo objeto de origem *obj*. Para
   muitos tipos simples tais como "bytes" e "bytearray", um elemento é
   um byte único, mas outros tipos tais como "array.array" podem ter
   elementos maiores.

   "len(view)" é igual ao comprimento de "tolist". Se "view.ndim = 0",
   o comprimento é 1. Se "view.ndim = 1", o comprimento é igual ao
   número de elementos na view. Para dimensões maiores, o comprimento
   é igual ao comprimento da representação de lista aninhada da view.
   O atributo "itemsize" irá lhe dar o número de bytes em um elemento
   individual.

   Um "memoryview" suporta fatiamento e indexação para expor seus
   dados. Fatiamento unidimensional irá resultar em uma subview:

      >>> v = memoryview(b'abcefg')
      >>> v[1]
      98
      >>> v[-1]
      103
      >>> v[1:4]
      <memory at 0x7f3ddc9f4350>
      >>> bytes(v[1:4])
      b'bce'

   Se "format" é um dos especificadores de formatação nativos do
   módulo "struct", indexar com um inteiro ou uma tupla de inteiros
   também é suportado, e retorna um *element* único com o tipo
   correto. Memoryviews unidimensionais podem ser indexadas com um
   inteiro ou uma tupla contendo um inteiro. Memoryviews multi-
   dimensionais podem ser indexadas com tuplas de exatamente *ndim*
   inteiros, onde *ndim* é o número de dimensões. Memoryviews zero-
   dimensionais podem ser indexadas com uma tupla vazia.

   Aqui temos um exemplo usando um formato não-byte:

      >>> import array
      >>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444])
      >>> m = memoryview(a)
      >>> m[0]
      -11111111
      >>> m[-1]
      44444444
      >>> m[::2].tolist()
      [-11111111, -33333333]

   Se o objeto subjacente é gravável, a memoryview suporta atribuição
   de fatias unidimensionais. Redimensionamento não é permitido:

      >>> data = bytearray(b'abcefg')
      >>> v = memoryview(data)
      >>> v.readonly
      False
      >>> v[0] = ord(b'z')
      >>> data
      bytearray(b'zbcefg')
      >>> v[1:4] = b'123'
      >>> data
      bytearray(b'z123fg')
      >>> v[2:3] = b'spam'
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
      ValueError: memoryview assignment: lvalue and rvalue have different structures
      >>> v[2:6] = b'spam'
      >>> data
      bytearray(b'z1spam')

   Memoryviews unidimensionais de tipos hasheáveis (apenas leitura)
   com formatos 'B', 'b' ou 'c' também são hasheáveis. O hash é
   definido como "hash(m) == hash(m.tobytes())":

      >>> v = memoryview(b'abcefg')
      >>> hash(v) == hash(b'abcefg')
      True
      >>> hash(v[2:4]) == hash(b'ce')
      True
      >>> hash(v[::-2]) == hash(b'abcefg'[::-2])
      True

   Alterado na versão 3.3: Memoryviews unidimensionais agora podem ser
   fatiadas. Memoryviews unidimensionais com formatos 'B', 'b' ou 'c'
   agora são hasheáveis.

   Alterado na versão 3.4: O memoryview agora é registrado
   automaticamente como uma classe "collections.abc.Sequence"

   Alterado na versão 3.5: Atualmente, os memoryvies podem ser
   indexadas com uma tupla de números inteiros.

   "memoryview" possui vários métodos:

   __eq__(exporter)

      Uma memoryview e um exportador **PEP 3118** são iguais se as
      suas formas são equivalentes e se todos os valores
      correspondentes são iguais quando os códigos de formatação dos
      respectivos operadores são interpretados usando a sintaxe
      "struct".

      Para o subconjunto  "struct" a formatação de Strings atualmente
      suportadas por "tolist()", "v" e "w" são iguais se "v.tolist()
      == w.tolist()":

         >>> import array
         >>> a = array.array('I', [1, 2, 3, 4, 5])
         >>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0])
         >>> c = array.array('b', [5, 3, 1])
         >>> x = memoryview(a)
         >>> y = memoryview(b)
         >>> x == a == y == b
         True
         >>> x.tolist() == a.tolist() == y.tolist() == b.tolist()
         True
         >>> z = y[::-2]
         >>> z == c
         True
         >>> z.tolist() == c.tolist()
         True

      Se qualquer string de formatação não for suportada pelo módulo
      "struct", então os objetos irão sempre comparar como diferentes
      (mesmo se as strings de formatação e o conteúdo do buffer são
      idênticos):

         >>> from ctypes import BigEndianStructure, c_long
         >>> class BEPoint(BigEndianStructure):
         ...     _fields_ = [("x", c_long), ("y", c_long)]
         ...
         >>> point = BEPoint(100, 200)
         >>> a = memoryview(point)
         >>> b = memoryview(point)
         >>> a == point
         False
         >>> a == b
         False

      Perceba que, assim como com números de ponto flutuante, "v is w"
      *não* implica em "v == w" para objetos memoryview.

      Alterado na versão 3.3: Versões anteriores comparavam a memória
      bruta desconsiderando o formato do item e estrutura lógica do
      array.

   tobytes()

      Retorna os dados no buffer como um bytestring. Isso é
      equivalente a chamar o construtor de "bytes" na memoryview.

         >>> m = memoryview(b"abc")
         >>> m.tobytes()
         b'abc'
         >>> bytes(m)
         b'abc'

      Para arrays não contíguos, o resultado é igual a representação
      de lista achatada com todos os elementos convertidos para bytes.
      "tobytes()" suporta todos os formatos de strings, incluindo
      aqueles que não estão na sintaxe do módulo "struct".

   hex()

      Retorna um objeto string contendo dois dígitos hexadecimais para
      cada byte no buffer.

         >>> m = memoryview(b"abc")
         >>> m.hex()
         '616263'

      Novo na versão 3.5.

   tolist()

      Retorna os dados no buffer como uma lista de elementos.

         >>> memoryview(b'abc').tolist()
         [97, 98, 99]
         >>> import array
         >>> a = array.array('d', [1.1, 2.2, 3.3])
         >>> m = memoryview(a)
         >>> m.tolist()
         [1.1, 2.2, 3.3]

      Alterado na versão 3.3: "tolist()" agora suporta todos os
      formatos nativos de caracteres únicos na sintaxe do módulo
      "struct", assim como representações multi-dimensionais.

   release()

      Libera o buffer subjacente exposto pelo objeto memoryview.
      Muitos objetos aceitam ações especiais quando a view é mantida
      com eles (por exemplo, um "bytearray" iria temporariamente
      proibir o redimensionamento); portanto, chamar release() é útil
      para remover essas restrições (e liberar quaisquer recursos
      pendurados) o mais breve possível.

      Depois que este método foi chamado, qualquer operação posterior
      na visão levanta um "ValueError" (exceto "release()", o qual
      pode ser chamado múltiplas vezes):

         >>> m = memoryview(b'abc')
         >>> m.release()
         >>> m[0]
         Traceback (most recent call last):
           File "<stdin>", line 1, in <module>
         ValueError: operation forbidden on released memoryview object

      O protocolo de gerenciamento de contexto pode ser usado para
      efeitos similares, usando a instrução "with":

         >>> with memoryview(b'abc') as m:
         ...     m[0]
         ...
         97
         >>> m[0]
         Traceback (most recent call last):
           File "<stdin>", line 1, in <module>
         ValueError: operation forbidden on released memoryview object

      Novo na versão 3.2.

   cast(format[, shape])

      Converte uma memoryview para um novo formato ou forma. *shape*
      por padrão é "[byte_length//new_itemsize]", o que significa que
      a view resultante será unidimensional. O valor de retorno é uma
      nova memoryview, mas o buffer por si mesmo não é copiado.
      Conversões suportadas são 1D -> C-*contíguo* r C-contíguo -> 1D.

      O formato de destino é restrito a um elemento em formato nativo
      na sintaxe "struct". Um dos formatos deve ser um formato de byte
      ('B', 'b' ou 'c'). O comprimento de bytes do resultado deve ser
      o mesmo que o comprimento original.

      Converte de 1D/long para 1D/unsigned bytes:

         >>> import array
         >>> a = array.array('l', [1,2,3])
         >>> x = memoryview(a)
         >>> x.format
         'l'
         >>> x.itemsize
         8
         >>> len(x)
         3
         >>> x.nbytes
         24
         >>> y = x.cast('B')
         >>> y.format
         'B'
         >>> y.itemsize
         1
         >>> len(y)
         24
         >>> y.nbytes
         24

      Converte de 1D/unsigned bytes para 1D/char:

         >>> b = bytearray(b'zyz')
         >>> x = memoryview(b)
         >>> x[0] = b'a'
         Traceback (most recent call last):
           File "<stdin>", line 1, in <module>
         ValueError: memoryview: invalid value for format "B"
         >>> y = x.cast('c')
         >>> y[0] = b'a'
         >>> b
         bytearray(b'ayz')

      Converte de 1D/bytes para 3D/ints para 1D/signed char:

         >>> import struct
         >>> buf = struct.pack("i"*12, *list(range(12)))
         >>> x = memoryview(buf)
         >>> y = x.cast('i', shape=[2,2,3])
         >>> y.tolist()
         [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
         >>> y.format
         'i'
         >>> y.itemsize
         4
         >>> len(y)
         2
         >>> y.nbytes
         48
         >>> z = y.cast('b')
         >>> z.format
         'b'
         >>> z.itemsize
         1
         >>> len(z)
         48
         >>> z.nbytes
         48

      Converte 1D/unsigned long para 2D/unsigned long:

         >>> buf = struct.pack("L"*6, *list(range(6)))
         >>> x = memoryview(buf)
         >>> y = x.cast('L', shape=[2,3])
         >>> len(y)
         2
         >>> y.nbytes
         48
         >>> y.tolist()
         [[0, 1, 2], [3, 4, 5]]

      Novo na versão 3.3.

      Alterado na versão 3.5: O formato fonte não é mais restrito ao
      converter para uma visão de byte.

   Existem também diversos atributos somente leitura disponíveis:

   obj

      O objeto subjacente da memoryview:

         >>> b  = bytearray(b'xyz')
         >>> m = memoryview(b)
         >>> m.obj is b
         True

      Novo na versão 3.3.

   nbytes

      "nbytes == product(shape) * itemsize == len(m.tobytes())". Este
      é a quantidade de espaço em bytes que o array deve usar em uma
      representação contígua. Ela não é necessariamente igual a
      "len(m)":

         >>> import array
         >>> a = array.array('i', [1,2,3,4,5])
         >>> m = memoryview(a)
         >>> len(m)
         5
         >>> m.nbytes
         20
         >>> y = m[::2]
         >>> len(y)
         3
         >>> y.nbytes
         12
         >>> len(y.tobytes())
         12

      Arrays Multi-dimensional:

         >>> import struct
         >>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)])
         >>> x = memoryview(buf)
         >>> y = x.cast('d', shape=[3,4])
         >>> y.tolist()
         [[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]]
         >>> len(y)
         3
         >>> y.nbytes
         96

      Novo na versão 3.3.

   readonly

      Um bool que indica se a memória é somente leitura.

   format

      Uma string contendo o formato (no estilo do módulo "struct")
      para cada elemento na visão. Uma memoryview pode ser criada a
      partir de exportadores com strings de formato arbitrário, mas
      alguns métodos (ex: "tolist()") são restritos a formatos de
      elementos nativos.

      Alterado na versão 3.3: formato "'B'" agora é tratado de acordo
      com a sintaxe do módulo struct. Isso significa que
      "memoryview(b'abc')[0] == b'abc'[0] == 97".

   itemsize

      O tamanho em Bytes de cada elemento do memoryview:

         >>> import array, struct
         >>> m = memoryview(array.array('H', [32000, 32001, 32002]))
         >>> m.itemsize
         2
         >>> m[0]
         32000
         >>> struct.calcsize('H') == m.itemsize
         True

   ndim

      Um número inteiro que indica quantas dimensões de uma matriz
      multidimensional a memória representa.

   shape

      Uma tupla de inteiros de comprimento "ndim" dando a forma da
      memória como uma matriz N-dimensional.

      Alterado na versão 3.3: Uma tupla vazia ao invés de "None"
      quando ndim = 0.

   strides

      Uma tupla de inteiros de comprimento de "ndim" dando o tamanho
      em bytes para acessar cada elemento de cada dimensão da matriz.

      Alterado na versão 3.3: Uma tupla vazia ao invés de "None"
      quando ndim = 0.

   suboffsets

      Usado internamente para estilos de Arrays PIL. O valor é apenas
      informativo.

   c_contiguous

      Um bool que indica se a memória é  C-*contiguous*.

      Novo na versão 3.3.

   f_contiguous

      Um bool que indica se a memória é Fortran *contiguous*.

      Novo na versão 3.3.

   contiguous

      Um bool que indica se a memória é *contiguous*.

      Novo na versão 3.3.


Tipo Set --- "set", "frozenset"
===============================

Um objeto *set* é uma coleção não ordenada de objetos *hasheáveis*
distintos. Usos comuns incluem testes de associação, remover
duplicatas de uma sequência, e computar operações matemáticas tais
como interseção, união, diferença, e diferença simétrica. (Para outros
tipos de containers veja os tipos embutidos "dict", "list", e a classe
"tuple", e o módulo "collections".)

Assim como outras coleções, sets suportam "x in set", "len(set)", e
"for x in set". Sendo uma coleção não ordenada, sets não armazenam
posição de elementos ou ordem de inserção. Portanto, sets não suportam
indexação, slicing, ou outros comportamentos similares de sequências.

Existem atualmente dois tipos de set embutidos, "set" e "frozenset". O
tipo "set" é mutável --- o conteúdo pode ser alterado usando métodos
como "add()" e "remove()". Como ele é mutável, ele não tem valor hash
e não pode ser usado como chave de dicionário ou um elemento de um
outro set. O tipo "frozenset" é imutável e *hasheável* --- seu
conteúdo não pode ser alterado depois de ter sido criado; ele pode
então ser usado como chave de dicionário ou como um elemento de outro
set.

Sets não vazios (que não sejam frozensets) podem ser criados
posicionando uma lista de elementos separados por vírgula dentro de
chaves, por exemplo: "{'jack', 'sjoerd'}", além do construtor "set".

Os construtores de ambas as classes funcionam da mesma forma:

class set([iterable])
class frozenset([iterable])

   Retorna um novo objeto set ou frozenset, cujos elementos são
   obtidos a partir de um *iterable*. Os elementos de um set devem ser
   *hasheável*. Para representar sets de sets, os sets internos devem
   ser objetos "frozenset". Se *iterable* não for especificado, um
   novo set vazio é retornado.

   Instâncias de "set" e "frozenset" fornecem as seguintes operações:

   len(s)

      Retorna o número de elementos no set *s* (cardinalidade de *s*).

   x in s

      Testa se *x* pertence a *s*.

   x not in s

      Testa se *x* não pertence a *s*.

   isdisjoint(other)

      Retorna "True" se o set não tem elementos em comum com *other*.
      Sets são deslocados (disjoint) se e somente se a sua interseção
      é o conjunto vazio.

   issubset(other)
   set <= other

      Testa se cada elemento do set está contido em *other*.

   set < other

      Testa se o set é um subconjunto próprio de *other*, isto é, "set
      <= other and set != other".

   issuperset(other)
   set >= other

      Testa se cada elemento em *other* está contido no set.

   set > other

      Testa se o set é um superconjunto próprio de *other*, isto é,
      "set >= other and set != other".

   union(*others)
   set | other | ...

      Retorna um novo set com elementos do set e de todos que estão em
      others.

   intersection(*others)
   set & other & ...

      Retorna um novo set com elementos comuns ao set e todos que
      estão em others.

   difference(*others)
   set - other - ...

      Retorna um novo set com elementos no set que não estão em
      others.

   symmetric_difference(other)
   set ^ other

      Retorna um novo set com elementos estejam ou no set ou em
      *other*, mas não em ambos.

   copy()

      Retorna uma cópia rasa do set.

   Perceba que, as versões não-operador dos métodos "union()",
   "intersection()", "difference()", e "symmetric_difference()",
   "issubset()", e "issuperset()" irão aceitar qualquer iterável como
   um argumento. Em contraste, suas contrapartes baseadas em
   operadores exigem que seus argumentos sejam conjuntos. Isso impede
   construções sucetíveis a erros como "set('abc') & 'cbs'" e favorece
   a forma mais legível "set('abc').intersection('cbs')".

   Tanto "set" quanto "frozenset" suportam comparar um set contra
   outro set. Dois sets são iguais se e somente se, cada elemento de
   cada set está contido no outro set (cada um é um subconjunto do
   outro). Um set é menor que outro set se e somente se, o primeiro
   set é um subconjunto próprio do segundo set (é um subconjunto, mas
   não é igual). Um set é maior que outro set se e somente se, o
   primeiro set é um superconjunto próprio do segundo set (é um
   superconjunto, mas não é igual).

   Instâncias de "set" são comparadas a instâncias de "frozenset"
   baseados nos seus membros. Por exemplo, "set('abc') ==
   frozenset('abc')" retorna "True" e assim como "set('abc') in
   set([frozenset('abc')])".

   O subset e comparações de igualdade não generalizam para a função
   de ordenamento total. Por exemplo, quaisquer dois sets deslocados
   não vazios, não são iguais e não são subsets um do outro, então
   *todos* os seguintes retornam "False": "a<b", "a==b", ou "a>b".

   Como sets apenas definem ordenamento parcial (subset de
   relacionamentos), a saída do método "list.sort()" é indefinida para
   listas e sets.

   Elementos set, assim como chaves de dicionário, devem ser
   *hasheáveis*.

   Operações binárias que misturam instâncias de "set" com "frozenset"
   retornam o tipo do primeiro operando. Por exemplo: "frozenset('ab')
   | set('bc')" retorna uma instância de "frozenset".

   A seguinte tabela lista operações disponíveis para "set" que não se
   aplicam para instâncias imutáveis de "frozenset":

   update(*others)
   set |= other | ...

      Atualiza o set, adicionando elementos de others.

   intersection_update(*others)
   set &= other & ...

      Atualiza o set, mantendo somente elementos encontrados nele e em
      others.

   difference_update(*others)
   set -= other | ...

      Atualiza o set, removendo elementos encontrados em others.

   symmetric_difference_update(other)
   set ^= other

      Atualiza o set, mantendo somente elementos encontrados em
      qualquer set, mas não em ambos.

   add(elem)

      Adiciona o elemento *elem* ao set.

   remove(elem)

      Remove o elemento *elem* do set. Levanta "KeyError" se *elem*
      não estiver contido no set.

   discard(elem)

      Remove o elemento *elem* do set se ele estiver presente.

   pop()

      Remove e retorna um elemento arbitrário do set. Levanta
      "KeyError" se o set estiver vazio.

   clear()

      Remove todos os elementos do set.

   Perceba, as versões sem operator dos métodos "update()",
   "intersection_update()", "difference_update()", e
   "symmetric_difference_update()" irão aceitar qualquer iterável como
   um argumento.

   Perceba, o argumento *elem* para os métodos "__contains__()",
   "remove()", e "discard()" pode ser um set. Para suportar pesquisas
   por um frozenset equivalente, um frozenset temporário é criado a
   partir de *elem*.


Tipo de Mapeamento --- "dict"
=============================

Um objeto de *mapeamento* mapeia valores *hasheáveis* para objetos
arbitrários. Mapeamentos são objetos mutáveis. Existe no momento
apenas um tipo de mapeamento padrão, o *dicionário*. (Para outros
containers, veja as classes embutidas "list", "set", e "tuple", e o
módulo "collections".)

As chaves de um dicionário são *quase* valores arbitrários. Valores
que não são *hasheáveis*, isto é, valores contendo listas, dicionários
ou outros tipos mutáveis (que são comparados por valor ao invés de por
identidade do objeto) não devem ser usados como chaves. Tipos
numéricos usados para chaves obedecem as regras normais para
comparação numérica: se dois números comparados são iguais (tal como
"1" e "1.0"), então eles podem ser usados intercambiavelmente para
indexar a mesma entrada no dicionário. (Perceba entretanto, que como
computadores armazenam números de ponto flutuante como aproximações,
usualmente não é uma boa ideia utilizá-los como chaves para
dicionários.)

Dicionários podem ser criados posicionando uma lista de pares "key:
value" separados por vírgula dentro de chaves, por exemplo: "{'jack':
4098, 'sjoerd': 4127}" ou "{4098: 'jack', 4127: 'sjoerd'}", ou usando
o construtor de "dict".

class dict(**kwarg)
class dict(mapping, **kwarg)
class dict(iterable, **kwarg)

   Retorna um novo dicionário inicializado a partir de um argumento
   posicional opcional, e um set de argumentos nomeados possivelmente
   vazio.

   Se nenhum argumento posicional é fornecido, um dicionário vazio é
   criado. Se um argumento posicional é fornecido e é um objeto de
   mapeamento, um dicionário é criado com os mesmos pares de chave-
   valor que o objeto de mapeamento. Caso contrário, o argumento
   posicional deve ser um objeto *iterável*. Cada item no iterável
   deve ser por si mesmo um iterável com exatamente dois objetos. O
   primeiro objeto de cada item torna-se a chave no novo dicionário, e
   o segundo objeto, o valor correspondente. Se a chave ocorrer mais
   do que uma vez, o último valor para aquela chave torna-se o valor
   correspondente no novo dicionário.

   Se argumentos nomeados são fornecidos, os argumentos nomeados e
   seus valores são adicionados ao dicionário criado a partir do
   argumento posicional. Se uma chave sendo adicionada já está
   presente, o valor do argumento nomeado substitui o valor do
   argumento posicional.

   Para ilustrar, os seguintes exemplos todos retornam um dicionário
   igual a "{"one": 1, "two": 2, "three": 3}":

      >>> a = dict(one=1, two=2, three=3)
      >>> b = {'one': 1, 'two': 2, 'three': 3}
      >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
      >>> d = dict([('two', 2), ('one', 1), ('three', 3)])
      >>> e = dict({'three': 3, 'one': 1, 'two': 2})
      >>> a == b == c == d == e
      True

   Fornecer argumentos nomeados conforme no primeiro exemplo somente
   funciona para chaves que são identificadores válidos no Python.
   Caso contrário, quaisquer chaves válidas podem ser usadas.

   Estas são as operações que dicionários suportam (e portanto, tipos
   de mapeamento personalizados devem suportar também):

   list(d)

      Retorna uma lista de todas as chaves usadas no dicionário *d*.

   len(d)

      Retorna o número de items no dicionário *d*.

   d[key]

      Retorna o item de *d* com a chave *key*. Levanta um "KeyError"
      se *key* não estiver no mapeamento.

      Se uma subclasse de um dict define um método "__missing__()" e
      *key* não estiver presente, a operação "d[key]" chama aquele
      método com a chave *key* como argumento. A operação "d[key]"
      então retorna ou levanta o que é retornado ou levantado pela
      chamada de "__missing__(key)". Nenhuma operação ou método invoca
      "__missing__()". Se "__missing__()" não for definido, então
      "KeyError" é levantado. "__missing__()" deve ser um método; ele
      não pode ser uma variável de instância:

         >>> class Counter(dict):
         ...     def __missing__(self, key):
         ...         return 0
         >>> c = Counter()
         >>> c['red']
         0
         >>> c['red'] += 1
         >>> c['red']
         1

      O exemplo acima mostra parte da implementação de
      "collections.Counter". Um método "__missing__" diferente é usado
      para "collections.defaultdict".

   d[key] = value

      Define "d[key]" para *value*.

   del d[key]

      Remove "d[key]" desde o *d*.  Levanta uma exceção "KeyError" se
      *key* não estiver em map.

   key in d

      Retorna "True" se *d* tiver uma chave *key*, senão "False".

   key not in d

      Equivalente a "not key in d".

   iter(d)

      Retorna um iterador para as chaves do dicionário. Isso é um
      atalho para "iter(d.keys())".

   clear()

      Remove todos os itens do dicionário.

   copy()

      Retorna uma cópia superficial do dicionário.

   classmethod fromkeys(iterable[, value])

      Cria um novo dicionário com chaves provenientes de *iterable* e
      valores definidos como *value*.

      "fromkeys()" is a class method that returns a new dictionary.
      *value* defaults to "None".

   get(key[, default])

      Retorna o valor para *key* se *key* está no dicionário, caso
      contrário *default*. Se *default* não é fornecido, será usado o
      valor padrão "None", de tal forma que este método nunca levanta
      um "KeyError".

   items()

      Retorna uma nova visão dos items do dicionário (pares de "(key,
      value)"). Veja a documentação de objetos de visão de dicionário.

   keys()

      Retorna uma nova visão das chaves do dicionário. Veja a
      documentação de objetos de visão de dicionário.

   pop(key[, default])

      Se *key* está no dicionário, remove a mesma e retorna o seu
      valor, caso contrário retorna *default*. Se *default* não foi
      fornecido e *key* não está no dicionário, um "KeyError" é
      levantado.

   popitem()

      Remove e retorna um par "(key, value)" do dicionário. Pares são
      retornados como uma pilha, ou seja em ordem LIFO (last-in,
      first-out).

      "popitem()" é útil para destrutivamente iterar sobre um
      dicionário, algo comumente usado em algoritmos de set. Se o
      dicionário estiver vazio, chamar "popitem()" levanta um
      "KeyError".

      Alterado na versão 3.7: Ordem LIFO agora é garantida. Em versões
      anteriores, "popitem()" iria retornar um par chave/valor
      arbitrário.

   setdefault(key[, default])

      Se *key* está no dicionário, retorna o seu valor. Se não, insere
      *key* com o valor *default* e retorna *default*.  *default* por
      padrão usa o valor "None".

   update([other])

      Atualiza o dicionário com os pares chave/valor existente em
      *other*, sobrescrevendo chaves existentes. Retorna "None".

      "update()" aceita ou outro objeto dicionário, ou um iterável de
      pares de chave/valor (como tuplas ou outros iteráveis de
      comprimento dois). Se argumentos nomeados são especificados, o
      dicionário é então atualizado com esses pares de chave/valor:
      "d.update(red=1, blue=2)".

   values()

      Retorna uma nova visão dos valores do dicionário. Veja a
      documentação de objetos de visão de dicionário.

      Uma comparação de igualdade entre uma visão de "dict.values()" e
      outra, sempre irá retornar "False". Isso também se aplica ao
      comparar "dict.values()" entre si:

         >>> d = {'a': 1}
         >>> d.values() == d.values()
         False

   Dicionários são iguais se e somente se eles os mesmos pares "(key,
   value)" (independente de ordem). Comparações de ordem ('<', '<=',
   '>=', '>') levantam "TypeError".

   Dicionários preservam a ordem de inserção. Perceba que atualizar a
   chave não afeta a ordem. Chaves adicionadas após a deleção são
   inseridas no final.

      >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
      >>> d
      {'one': 1, 'two': 2, 'three': 3, 'four': 4}
      >>> list(d)
      ['one', 'two', 'three', 'four']
      >>> list(d.values())
      [1, 2, 3, 4]
      >>> d["one"] = 42
      >>> d
      {'one': 42, 'two': 2, 'three': 3, 'four': 4}
      >>> del d["two"]
      >>> d["two"] = None
      >>> d
      {'one': 42, 'three': 3, 'four': 4, 'two': None}

   Alterado na versão 3.7: Ordem do dicionário é garantida conforme a
   ordem de inserção. Este comportamento era um detalhe de
   implementação do CPython a partir da versão 3.6.

Ver também:

  "types.MappingProxyType" podem ser usados para criar uma visão
  somente-leitura de um "dict".


Objetos de visão de dicionário
------------------------------

Os objetos retornados por "dict.keys()", "dict.values()" e
"dict.items()" são *objetos de visão*. Eles fornecem uma visão
dinâmica das entradas do dicionário, o que significa que quando o
dicionário muda, a visão reflete essas mudanças.

Visões de dicionários podem ser iteradas para apresentar seus
respectivos dados, e suportar testes de existência:

len(dictview)

   Retorna o número de entradas no dicionário.

iter(dictview)

   Retorna um iterador sobre as chaves, valores ou items
   (representados como tuplas de "(key, value)") no dicionário.

   Chaves e valores são iterados em ordem de inserção. Isso permite a
   criação de pares "(value, key)" usando "zip()": "pairs =
   zip(d.values(), d.keys())". Outra maneira de criar a mesma lista é
   "pairs = [(v, k) for (k, v) in d.items()]".

   Iterar sobre visões enquanto adiciona ou deleta entradas no
   dicionário pode levantar um "RuntimeError" ou falhar a iteração
   sobre todas as entradas.

   Alterado na versão 3.7: Ordem do dicionário é garantida como a
   ordem de inserção.

x in dictview

   Retorna "True" se *x* está nas chaves, valores ou items do
   dicionário subjacente (no último caso, *x* deve ser uma tupla de
   "(key, value)").

Visões chave são similar a conjunto, como suas entradas são únicas e
hasheáveis. Se todos os valores são hasheáveis, de tal forma que os
pares "(chave, valor)" são únicos e hasheáveis, então a visão dos
items também é um similar a conjunto. (Visões de valores não são
tratadas de como similar a conjunto, pois as entradas geralmente não
são únicas.) Para visões similares a conjunto, todas as operações
definidas para a classe base abstrata "collections.abc.Set" estão
disponíveis (por exemplo, "==", "<", ou "^").

Um exemplo da utilização da visualização de dicionário:

   >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
   >>> keys = dishes.keys()
   >>> values = dishes.values()

   >>> # iteration
   >>> n = 0
   >>> for val in values:
   ...     n += val
   >>> print(n)
   504

   >>> # keys and values are iterated over in the same order (insertion order)
   >>> list(keys)
   ['eggs', 'sausage', 'bacon', 'spam']
   >>> list(values)
   [2, 1, 1, 500]

   >>> # view objects are dynamic and reflect dict changes
   >>> del dishes['eggs']
   >>> del dishes['sausage']
   >>> list(keys)
   ['bacon', 'spam']

   >>> # set operations
   >>> keys & {'eggs', 'bacon', 'salad'}
   {'bacon'}
   >>> keys ^ {'sausage', 'juice'}
   {'juice', 'sausage', 'bacon', 'spam'}


Tipos de Gerenciador de Contexto
================================

A instrução "with" do Python suporta o conceito de um contexto em
tempo de execução definido por um gerenciador de contexto. Isto é
implementado usando um par de métodos, que permitem que classes
definidas pelo usuário especifiquem um contexto em tempo de execução,
o qual é inicializado antes da execução das instruções, e encerrado
quando as instruções terminam:

contextmanager.__enter__()

   Entra no contexto em tempo de execução e retorna este objeto ou
   outro objeto relacionado ao contexto em tempo de execução. O valor
   retornado por este método é ligado ao identificador na cláusula
   "as" da instrução "with" usando este gerenciador de contexto.

   Um exmplo de gerenciador de contexto que retorna a si mesmo é um
   *objeto arquivo*. Objeto arquivos retornam a si mesmos do método
   __enter__() para permitir que "open()" seja usado como a expressão
   de contexto em uma instrução "with".

   Um exemplo de gerenciador de contexto que retorna um objeto
   relacionado é aquele retornado por "decimal.localcontext()". Esses
   gerenciadores definem o contexto decimal ativo para uma cópia do
   contexto decimal original, e então retornam a cópia. Isso permite
   que mudanças sejam feitas no contexto decimal atual, no corpo
   contido na instrução "with", sem afetar o código fora da instrução
   "with".

contextmanager.__exit__(exc_type, exc_val, exc_tb)

   Sai do contexto em tempo de execução e retorna um flag Booleano
   indicando se qualquer exceção que ocorreu deve ser suprimida. Se
   uma exceção ocorreu enquanto era executado o corpo da instrução
   "with", os argumentos contém o tipo da exceção, valor e informação
   da pilha de execução. Caso contrário, os tres argumentos são
   "None".

   Retornar um valor verdadeiro deste método fará com que a instrução
   "with" suprima a exceção e continue a execução com a instrução
   imediatamente após a instrução "with". Caso contrário a exceção
   continuará propagando após este método ter encerrado sua execução.
   Exceções que ocorrerem durante a execução deste método irão
   substituir qualquer exceção que tenha ocorrido dentro do corpo da
   instrução "with".

   A exceção passada nunca deve ser re-levantada explicitamente - ao
   invés disso, este método deve retornar um valor falso para indicar
   que o método completou sua execução com sucesso, e não quer
   suprimir a exceção levantada. Isso permite ao código do gerenciador
   de contexto facilmente detectar se um método "__exit__()" realmente
   falhou ou não.

Python define diversos genreciadores de contexto para suportar
facilmente sincronização de threads, solicita fechamento de arquivos
ou outros objectos, e manipulação simples do contexto ativo de
aritmética decimal. Os tipos especificados não são tratados
especialmente além da sua implementação do protocolo do gerenciador de
contexto. Veja o módulo "contextlib" para alguns exemplos.

Os *geradores* do python e o decorador "contextlib.contextmanager"
fornecem um modo conveniente de implementar estes protocolos. Se uma
função geradora é decorada com o decorador
"contextlib.contextmanager", ela irá retornar um gerenciador de
contexto que implementa os métodos "__enter__()" e "__exit__()"
necessários, ao invés do iterador produzido por uma função geradora
não decorada.

Perceba que não existe nenhum slot específico para qualquer um desses
métodos no tipo structure para objetos Python na API do Python/C.
Tipos de extensão que desejam definir estes métodos devem fornecê-los
como um método acessível normal do Python. Comparado com a sobrecarga
de configurar o contexto em tempo de execução, a sobrecarga na
pesquisa de dicionário em uma única classe é negligenciável.


Outros tipos embutidos
======================

O interpretador suporta diversos outros tipos de objetos. Maior parte
desses, suporta apenas uma ou duas operações.


Módulos
-------

A única operação especial em um módulo é o acesso a um atributo:
"m.nome", onde *m* é um módulo e *nome* acessa o nome defino na tabela
de símbolos de *m*. Atributos de módulo podem receber atribuição.
(Perceba que a instrução "import" não é, estritamente falando, uma
operação em um objeto do módulo; "import foo" não requer que um objeto
do módulo chamado *foo* exista, ao invés disso requer uma *definição*
(externa) de um módulo chamado *foo* em algum lugar.)

Um atributo especial de cada módulo é "__dict__". Este é o dicionário
contendo a tabela de símbolos do modulo. Modificar este dicionário vai
na verdade modificar a tabela de símbolos do módulo, mas atribuição
direta para o atributo "__dict__" não é possível (você pode escrever
"m.__dict__['a'] = 1", o qual define "m.a" para ser "1", mas você não
consegue escrever "m.__dict__ = {}"). Modificar "__dict__" diretamente
não é recomendado.

Módulos embutidos no interpretador são escritos desta forma: "<module
'sys' (built-in)>". Se carregados a partir de um arquivo, eles são
escritos como "<module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>".


Classes e Instâncias de Classes
-------------------------------

Veja Objetos, valores e tipos e Definições de classe para estes.


Funções
-------

Objetos de funções são criados através da definição de funções. A
única operação que pode ser feita em um objeto de função é chamá-la:
"func(lista-de-argumentos)".

Existem na verdade duas possibilidades de objetos de função: funções
embutidas e funções definidas pelo usuário. Ambas suportam a mesma
operação (chamar a função), mas a implementação é diferente, portanto
os diferentes tipos de objetos.

Veja a funçao Definições de função para maiores informações.


Métodos
-------

Métodos são funções que são chamadas usando a notação de atributo.
Existem duas opções: métodos embutidos (tal como "append()" em listas)
e métodos de instância de classe. Métodos embutidos são descritos com
os tipos que suportam eles.

Se você acessar um método (uma função definida em um espaço de nomes
de uma classe) através de uma instância, você obtém um objeto
especial: um objeto *bound method* (também chamado de *método de
instância*). Quando chamado, ele irá adicionar o argumento "self" para
a lista de argumentos. Bound methods tem dois atributos somente
leitura especiais: "m.__self__" é o objeto no qual o método opera, e
"m.__func__" é a função que implementa o método. Chamar "m(arg-1,
arg-2, ..., arg-n)" é completamente equivalente a chamar
"m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".

Assim como objetos função, objetos de métodos vinculados tem suporte
para receber atributos arbitrários. Entretanto, como atributos de
métodos na verdade são armazenados no objeto função subjacente
("meth.__func__"), definir atributos de métodos em métodos vinculados
não é permitido. Tentar definir um atributo em um método resulta em um
"AttributeError" sendo levantado. A fim de definir um atributo de
método, você precisa definir explicitamente ele no objeto função
subjacente:

   >>> class C:
   ...     def method(self):
   ...         pass
   ...
   >>> c = C()
   >>> c.method.whoami = 'my name is method'  # can't set on the method
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   AttributeError: 'method' object has no attribute 'whoami'
   >>> c.method.__func__.whoami = 'my name is method'
   >>> c.method.whoami
   'my name is method'

Veja o tipo A hierarquia de tipos padrão para maiores informações.


Objetos de Código
-----------------

Objetos de código são usados pela implementação para representar
código Python executável "pseudo-compilado", tal como corpo de uma
função. Eles são diferentes de objetos de função porque eles não
contém uma referência para os seus ambientes de execução global.
Objetos de código são retornados pela função embutida "compile()" e
podem ser extraídos de objetos de função através do seu atributo
"__code__". Veja também o módulo "code".

Um objeto de código pode ser executado ou avaliado passando-o (ao
invés da string fonte) para as funções embutidas "exec()" ou "eval()".

Veja o tipo A hierarquia de tipos padrão para maiores informações.


Objetos de tipo
---------------

Objetos de tipos representam os vários tipos de objetos. Um tipo de um
objeto é acessado pela função embutida "type()". Não existem operações
especiais sobre tipos. O módulo padrão "types" define nomes para todos
os tipos padrão embutidos.

Tipos são escritos como isto: "<class 'int'>".


O objeto Null
-------------

Este objeto é retornado por funções que não retornam um valor
explicitamente. Ele não suporta operações especiais. Existe exatamente
um objeto null, chamado "None" (um nome embutido). "type(None)()"
produz o mesmo valor.

Ele é escrito como "None".


O Objeto Ellipsis
-----------------

Este objeto é comumente usado através de fatiamento (veja Slicings).
Ela não suporta operações especiais. Existe exatamente um objeto
ellipsis, nomeado "Ellipsis" (um nome embutido). "type(Ellipsis)()"
produz novamente "Ellipsis".

Está escrito com "Ellipsis" ou "...".


O Objeto NotImplemented
-----------------------

Este objeto é retornado a partir de comparações e operações binárias
quando elas são solicitadas para operar em tipos nos quais eles não
suportam. Veja Comparações para mais informações. Existe exatamente um
objeto "NotImplemented". "type(NotImplemented)()" produz a instância
singleton.

Está escrito como "NotImplemented".


Valores Booleanos
-----------------

Valores Booleanos são os dois objetos constantes "False" e "True".
Eles são usados para representar valores verdadeiros (apesar que
outros valores também podem ser considerados falso ou verdadeiro). Em
contextos numéricos (por exemplo quando usados como argumentos para um
operator aritmético), eles se comportam como os inteiros 0 e 1,
respectivamente. A função embutida "bool()" pode ser usada para
converter qualquer valor para um Boolean, se o valor puder ser
interpretado como um valor verdadeiro (veja a seção Teste do Valor
Verdade acima).

Eles são escritos como "False" e "True", respectivamente.


Objetos Internos
----------------

Veja A hierarquia de tipos padrão para esta informação. Ela descreve
objetos de stack frame, objetos de traceback, e fatias de objetos.


Atributos Especiais
===================

A implementação adiciona alguns atributos especiais somente-leitura
para diversos tipos de objetos, onde eles são relevantes. Alguns
desses não são reportados pela função embutida "dir()".

object.__dict__

   Um dicionário ou outro objeto de mapeamento usado para armazenar os
   atributos (graváveis) de um objeto.

instance.__class__

   A classe à qual pertence uma instância de classe.

class.__bases__

   A tupla de classes base de um objeto classe.

definition.__name__

   O nome da classe, função, método, descritor, ou instância geradora.

definition.__qualname__

   O *nome qualificado* da classe, função, método, descritor, ou
   instância geradora.

   Novo na versão 3.3.

class.__mro__

   Este atributo é uma tupla de classes que são consideradas ao
   procurar por classes bases durante resolução de métodos.

class.mro()

   Este método pode ser substituído por uma metaclasse para customizar
   a ordem de resolução de métodos para suas instâncias. Ele é chamado
   na instanciação da classe, e o seu resultado é armazenado em
   "__mro__".

class.__subclasses__()

   Cada classe mantém uma lista de referências fracas para suas
   subclasses imediatas. Este método retorna uma lista de todas essas
   referências que ainda estão vivas. Exemplo:

      >>> int.__subclasses__()
      [<class 'bool'>]


Integer string conversion length limitation
===========================================

CPython has a global limit for converting between "int" and "str" to
mitigate denial of service attacks. This limit *only* applies to
decimal or other non-power-of-two number bases. Hexadecimal, octal,
and binary conversions are unlimited. The limit can be configured.

The "int" type in CPython is an arbitrary length number stored in
binary form (commonly known as a "bignum"). There exists no algorithm
that can convert a string to a binary integer or a binary integer to a
string in linear time, *unless* the base is a power of 2. Even the
best known algorithms for base 10 have sub-quadratic complexity.
Converting a large value such as "int('1' * 500_000)" can take over a
second on a fast CPU.

Limiting conversion size offers a practical way to avoid
CVE-2020-10735.

The limit is applied to the number of digit characters in the input or
output string when a non-linear conversion algorithm would be
involved.  Underscores and the sign are not counted towards the limit.

When an operation would exceed the limit, a "ValueError" is raised:

   >>> import sys
   >>> sys.set_int_max_str_digits(4300)  # Illustrative, this is the default.
   >>> _ = int('2' * 5432)
   Traceback (most recent call last):
   ...
   ValueError: Exceeds the limit (4300) for integer string conversion: value has 5432 digits; use sys.set_int_max_str_digits() to increase the limit.
   >>> i = int('2' * 4300)
   >>> len(str(i))
   4300
   >>> i_squared = i*i
   >>> len(str(i_squared))
   Traceback (most recent call last):
   ...
   ValueError: Exceeds the limit (4300) for integer string conversion: value has 8599 digits; use sys.set_int_max_str_digits() to increase the limit.
   >>> len(hex(i_squared))
   7144
   >>> assert int(hex(i_squared), base=16) == i*i  # Hexadecimal is unlimited.

The default limit is 4300 digits as provided in
"sys.int_info.default_max_str_digits". The lowest limit that can be
configured is 640 digits as provided in
"sys.int_info.str_digits_check_threshold".

Verification:

   >>> import sys
   >>> assert sys.int_info.default_max_str_digits == 4300, sys.int_info
   >>> assert sys.int_info.str_digits_check_threshold == 640, sys.int_info
   >>> msg = int('578966293710682886880994035146873798396722250538762761564'
   ...           '9252925514383915483333812743580549779436104706260696366600'
   ...           '571186405732').to_bytes(53, 'big')
   ...

Novo na versão 3.7.14.


Affected APIs
-------------

The limitation only applies to potentially slow conversions between
"int" and "str" or "bytes":

* "int(string)" with default base 10.

* "int(string, base)" for all bases that are not a power of 2.

* "str(integer)".

* "repr(integer)".

* any other string conversion to base 10, for example "f"{integer}"",
  ""{}".format(integer)", or "b"%d" % integer".

The limitations do not apply to functions with a linear algorithm:

* "int(string, base)" with base 2, 4, 8, 16, or 32.

* "int.from_bytes()" and "int.to_bytes()".

* "hex()", "oct()", "bin()".

* Minilinguagem de especificação de formato for hex, octal, and binary
  numbers.

* "str" to "float".

* "str" to "decimal.Decimal".


Configuring the limit
---------------------

Before Python starts up you can use an environment variable or an
interpreter command line flag to configure the limit:

* "PYTHONINTMAXSTRDIGITS", e.g. "PYTHONINTMAXSTRDIGITS=640 python3" to
  set the limit to 640 or "PYTHONINTMAXSTRDIGITS=0 python3" to disable
  the limitation.

* "-X int_max_str_digits", e.g. "python3 -X int_max_str_digits=640"

* "sys.flags.int_max_str_digits" contains the value of
  "PYTHONINTMAXSTRDIGITS" or "-X int_max_str_digits". If both the env
  var and the "-X" option are set, the "-X" option takes precedence. A
  value of *-1* indicates that both were unset, thus a value of
  "sys.int_info.default_max_str_digits" was used during
  initialization.

From code, you can inspect the current limit and set a new one using
these "sys" APIs:

* "sys.get_int_max_str_digits()" and "sys.set_int_max_str_digits()"
  are a getter and setter for the interpreter-wide limit.
  Subinterpreters have their own limit.

Information about the default and minimum can be found in
"sys.int_info":

* "sys.int_info.default_max_str_digits" is the compiled-in default
  limit.

* "sys.int_info.str_digits_check_threshold" is the lowest accepted
  value for the limit (other than 0 which disables it).

Novo na versão 3.7.14.

Cuidado:

  Setting a low limit *can* lead to problems. While rare, code exists
  that contains integer constants in decimal in their source that
  exceed the minimum threshold. A consequence of setting the limit is
  that Python source code containing decimal integer literals longer
  than the limit will encounter an error during parsing, usually at
  startup time or import time or even at installation time - anytime
  an up to date ".pyc" does not already exist for the code. A
  workaround for source that contains such large constants is to
  convert them to "0x" hexadecimal form as it has no limit.Test your
  application thoroughly if you use a low limit. Ensure your tests run
  with the limit set early via the environment or flag so that it
  applies during startup and even during any installation step that
  may invoke Python to precompile ".py" sources to ".pyc" files.


Recommended configuration
-------------------------

The default "sys.int_info.default_max_str_digits" is expected to be
reasonable for most applications. If your application requires a
different limit, set it from your main entry point using Python
version agnostic code as these APIs were added in security patch
releases in versions before 3.11.

Example:

   >>> import sys
   >>> if hasattr(sys, "set_int_max_str_digits"):
   ...     upper_bound = 68000
   ...     lower_bound = 4004
   ...     current_limit = sys.get_int_max_str_digits()
   ...     if current_limit == 0 or current_limit > upper_bound:
   ...         sys.set_int_max_str_digits(upper_bound)
   ...     elif current_limit < lower_bound:
   ...         sys.set_int_max_str_digits(lower_bound)

If you need to disable it entirely, set it to "0".

-[ Notas de rodapé ]-

[1] Informações adicionais sobre esses métodos especiais podem ser
    encontradas no Manual de Referência do Python (Customização
    básica).

[2] Como uma consequência, a lista "[1, 2]" é considerada igual a
    "[1.0, 2.0]", e similarmente para tuplas.

[3] Eles precisam ter, já que o analisador sintático não consegue
    dizer o tipo dos operandos.

[4] Caracteres que possuem maiúsculo e minúsculo são aqueles com a
    propriedade de categoria geral igual a "Lu" (Letra, maiúscula),
    "Ll" (Letra, minúscula), ou "Lt" (Letra, em formato de título).

[5] Para formatar apenas uma tupla, você deve portanto fornecer uma
    tupla singleton, cujo único elemento é a tupla a ser formatada.
