Tipos embutidos
***************

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

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

Algumas classes de coleção 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".

Algumas operações são suportadas por vários tipos de objetos; em
particular, praticamente todos os objetos podem ser comparados em
termos de igualdade, testados quanto ao valor verdade e convertidos em
uma string (com a função "repr()" ou a função ligeiramente diferente
"str()"). A última função é implicitamente usada quando um objeto é
escrito pela função "print()".


Teste do valor verdade
======================

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

By default, an object is considered true unless its class defines
either a "__bool__()" method that returns "False" or a "__len__()"
method that returns zero, when called with the object. [1] If one of
the methods raises an exception when called, the exception is
propagated and the object does not have a truth value (for example,
"NotImplemented"). Here are most of the built-in objects considered
false:

* constantes definidas para serem falsas: "None" e "False"

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

* sequências e coleções vazias: "''", "()", "[]", "{}", "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* é true, então *x*, do      | (1)     |
|               | contrário *y*                     |         |
+---------------+-----------------------------------+---------+
| "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 prioridade mais baixa 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 encadeadas 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                    |
+--------------+---------------------------+

Unless stated otherwise, objects of different types never compare
equal. The "==" operator is always defined but for some object types
(for example, class objects) is equivalent to "is". The "<", "<=", ">"
and ">=" operators are only defined where they make sense; for
example, they raise a "TypeError" exception when one of the arguments
is a complex number.

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 dos 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 "is" e "is not" não pode ser
personalizado; além disso eles podem ser aplicados a quaisquer dois
objetos e nunca levantam 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 *iteráveis* ou implementam o método
"__contains__()".


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

Existem três tipos numéricos distintos: *inteiros*, *números de ponto
flutuante* e *números complexos*. Além disso, os booleanos são um
subtipo de números inteiros. Inteiros têm precisão ilimitada. Números
de ponto flutuante são geralmente implementados usando double em C;
informações sobre a precisão e representação interna dos números de
ponto flutuante para a máquina na qual seu programa está sendo
executado estão disponíveis em "sys.float_info". Números complexos têm
uma parte real e imaginária, cada um com 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 os tipos numéricos adicionais
"fractions.Fraction", para racionais, e "decimal.Decimal", para
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
operadores e funções embutidas. 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.

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

Python fully supports mixed arithmetic: when a binary arithmetic
operator has operands of different built-in numeric types, the operand
with the "narrower" type is widened to that of the other:

* Se ambos os argumentos forem números complexos, nenhuma conversão
  será realizada;

* se qualquer argumento for um número complexo ou de ponto flutuante,
  o outro será convertido em um número de ponto flutuante;

* caso contrário, ambos devem ser inteiros e nenhuma conversão é
  necessária.

Arithmetic with complex and real operands is defined by the usual
mathematical formula, for example:

   x + complex(u, v) = complex(x + u, v)
   x * complex(u, v) = complex(x * u, x * v)

Uma comparação entre números de tipos diferentes se comporta como se
os valores exatos desses números estivessem sendo comparados. [2]

Todos os tipos numéricos (exceto complexos) suportam as seguintes
operações (para prioridades das operações, consulte Precedência de
operadores):

+-----------------------+-----------------------------------+-----------+----------------------+
| 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"              | piso do quociente de *x* e *y*    | (1)(2)    |                      |
+-----------------------+-----------------------------------+-----------+----------------------+
| "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* |           |                      |
|                       | tem como padrão 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. Para operandos do tipo
   "int", o resultado tem o tipo "int"; Para operandos do tipo
   "float", o resultado tem o tipo "float". Em geral o resultado é
   inteiro como todo, apesar do tipo do resultado não necessariamente
   ser "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 pontos
   flutuantes usando "abs()" se for apropriado.

3. Conversão de "float" para "int" trunca, descartando a parte
   fracionária. Veja as funções "math.floor()" e "math.ceil()" para
   conversões alternativas.

4. ponto flutuante também aceita a string "nan" e "inf" com um prefixo
   opcional "+" ou "-" a 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 aceitos incluem os dígitos de "0" a "9" ou
   qualquer equivalente Unicode (pontos de código com a propriedade
   "Nd").

   Veja o Unicode Standard para obter uma lista completa de pontos de
   código com a propriedade "Nd".

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

+----------------------+-----------------------------------------------+
| Operação             | Resultado                                     |
|======================|===============================================|
| "math.trunc(x)"      | *x* truncado para "Integral"                  |
+----------------------+-----------------------------------------------+
| "round(x[, n])"      | *x* arredondado para *n* dígitos,             |
|                      | 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 bit a bit 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"      | *ou* bit a bit de *x* e *y*      | (4)        |
+--------------+----------------------------------+------------+
| "x ^ y"      | *ou exclusivo* bit a bit de *x*  | (4)        |
|              | e *y*                            |            |
+--------------+----------------------------------+------------+
| "x & y"      | *e* bit a bit de *x* e *y*       | (4)        |
+--------------+----------------------------------+------------+
| "x << n"     | *x* deslocado para a esquerda    | (1)(2)     |
|              | por *n* bits                     |            |
+--------------+----------------------------------+------------+
| "x >> n"     | *x* deslocado para a direita por | (1)(3)     |
|              | *n* bits                         |            |
+--------------+----------------------------------+------------+
| "~x"         | os bits de *x* invertidos        |            |
+--------------+----------------------------------+------------+

Notas:

1. Contagens de deslocamento negativo são ilegais e levantam uma
   "ValueError" .

2. Um deslocamento à esquerda por *n* bits é equivalente à
   multiplicação por "pow(2, n)".

3. Um deslocamento à direita por *n* bits é equivalente à divisão pelo
   piso por "pow(2, n)".

4. Executar esses cálculos com pelo menos um bit extra de extensão de
   sinal 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 base abstrata* "numbers.Integral".
Além disso, ele provê mais alguns métodos:

int.bit_length()

   Retorna 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 positivo inteiro "k" tal que "2**(k-1)
   <= abs(x) < 2**k". Equivalentemente, quando "abs(x)" for pequeno o
   suficiente para ter um logaritmo corretamente arrendondado, 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)       # representação binária:  bin(-37) --> '-0b100101'
          s = s.lstrip('-0b') # remove zeros no início e sinal negativo
          return len(s)       # len('100101') --> 6

   Adicionado na versão 3.1.

int.bit_count()

   Retorna o número de unidades na representação binária do valor
   absoluto do inteiro. Isso também é conhecido como contagem da
   população. Exemplo:

      >>> n = 19
      >>> bin(n)
      '0b10011'
      >>> n.bit_count()
      3
      >>> (-n).bit_count()
      3

   Equivalente a:

      def bit_count(self):
          return bin(self).count("1")

   Adicionado na versão 3.10.

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

   Retorna um vetor 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, e o padrão é 1. Uma
   "OverflowError" é levantada 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, e o padrão é ""big"". Se o *byteorder* é
   ""big"", o byte mais significativo está no início do vetor de byte.
   Se *byteorder* é ""little"", o byte mais significativo está no
   final do vetor 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, uma "OverflowError" é levantada. O valor
   padrão para *signed* é "False".

   Os valores padrão podem ser usados para transformar
   convenientemente um inteiro em um objeto de byte único:

      >>> (65).to_bytes()
      b'A'

   No entanto, ao usar os argumentos padrão, não tente converter um
   valor maior que 255 ou você obterá um "OverflowError".

   Equivalente a:

      def to_bytes(n, length=1, byteorder='big', signed=False):
          if byteorder == 'little':
              order = range(length)
          elif byteorder == 'big':
              order = reversed(range(length))
          else:
              raise ValueError("byteorder must be either 'little' or 'big'")

          return bytes((n >> i*8) & 0xff for i in order)

   Adicionado na versão 3.2.

   Alterado na versão 3.11: Adicionados valores de argumento padrão
   para "length" e "byteorder".

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

   Retorna o inteiro representado pelo vetor de bytes dado.

   >>> 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 *objeto bytes ou similar* ou
   um iterador produzindo bytes.

   O argumento *byteorder* determina a ordem de bytes usada para
   representar um inteiro, e o padrão é ""big"". Se o *byteorder* é
   ""big"", o byte mais significativo está no início do vetor de byte.
   Se *byteorder* é ""little"", o byte mais significativo está no
   final do vetor 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* indica quando o complemento de dois é usado
   para representar o inteiro.

   Equivalente a:

      def from_bytes(bytes, byteorder='big', signed=False):
          if byteorder == 'little':
              little_ordered = list(bytes)
          elif byteorder == 'big':
              little_ordered = list(reversed(bytes))
          else:
              raise ValueError("byteorder must be either 'little' or 'big'")

          n = sum(b << i*8 for i, b in enumerate(little_ordered))
          if signed and little_ordered and (little_ordered[-1] & 0x80):
              n -= 1 << 8*len(little_ordered)

          return n

   Adicionado na versão 3.2.

   Alterado na versão 3.11: Adicionado valor de argumento padrão para
   "byteorder".

int.as_integer_ratio()

   Retorna um par de números inteiros cuja razão é igual ao número
   inteiro original e tem um denominador positivo. A proporção inteira
   de números inteiros (números inteiros) é sempre o número inteiro
   como numerador e "1" como denominador.

   Adicionado na versão 3.8.

int.is_integer()

   Retorna "True". Existe para compatibilidade com tipo pato com
   "float.is_integer()".

   Adicionado na versão 3.12.


Métodos adicionais em ponto flutuante
-------------------------------------

O tipo float implementa a *classe base abstrata* "numbers.Real". float
também possui os seguintes métodos adicionais.

classmethod float.from_number(x)

   Método de classe para retornar um número de ponto flutuante
   construído a partir de um número *x*.

   Se o argumento é um inteiro ou um número de ponto flutuante, um
   número de ponto flutuante com o mesmo valor (com a precisão de
   ponto flutuante de Python) é retornado. Se o argumento está fora do
   intervalo de um ponto flutuante Python, uma exceção "OverflowError"
   será levantada.

   Para um objeto Python genérico "x", "float.from_number(x)" delega
   para o método "x.__float__()". Se "__float__()" não estiver
   definido, então ele delega para o método "__index__()".

   Adicionado na versão 3.14.

float.as_integer_ratio()

   Retorna um par de inteiros dos quais a proporção é exatamente igual
   ao float original.  A proporção está em seus termos mais baixos e
   tem um denominador positivo. Levanta um "OverflowError" em
   infinidades e um "ValueError" em NaNs.

float.is_integer()

   Retorna "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 strings hexadecimais. Uma
vez que os pontos flutuantes do Python são armazenados internamente
como números binários, a conversão de um ponto flutuante para ou de
uma string *decimal* geralmente envolve um pequeno erro de
arredondamento. Em contraste, as strings 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 ponto flutuante 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]

onde o sinal opcional "sign" pode ser tanto "+" or "-", "integer" e
"fraction" são strings de dígitos hexadecimais, e "exponent" é um
inteiro decimal com um sinal opcional no início. Maiúsculo ou
minúsculo não é significativo, e deve haver ao menos um dígito
hexadecimal tanto no inteiro ou na fração. Essa sintaxe é similar à
sintaxe especificada na seção 6.4.4.2 do padrão C99, e também do da
sintaxe 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 strings hexadecimais produzidas pelo formato do
caractere "%a" do C 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 inversa a "3740.0" retorna uma string
hexadecimal diferente representada pelo mesmo número:

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


Métodos adicionais em números complexos
---------------------------------------

O tipo "complex" implementa a *classe base abstrata*
"numbers.Complex". "complex" também possui os seguintes métodos
adicionais.

classmethod complex.from_number(x)

   Método de classe para converter um número para um número complexo.

   Para um objeto Python "x" qualquer, "complex.from_number(x)" delega
   para "x.__complex__()". Se "__complex__()" não está definido então
   a chamada é repassada para "__float__()". Se "__float__()" não está
   definido então a chamada é, novamente, repassada para
   "__index__()".

   Adicionado na versão 3.14.


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

Para números "x" e "y", possivelmente de diferentes tipos, é um
requisito que "hash(x) == hash(y)" sempre que "x == y" (veja a
documentação do método "__hash__()" para mais detalhes). Para
facilitar a implementação e eficiência através de uma variedade de
tipos numéricos (incluindo "int", "float", "decimal.Decimal" e
"fractions.Fraction"), o hash do Python para tipos numéricos é baseado
em uma única funçã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
módulo de redução "P" para um primo fixado "P". O valor de "P" é
disponibilizado ao Python como um atributo "modulus" do
"sys.hash_info".

Atualmente, o primo usado é "P = 2**31 - 1" em máquinas com longos de
32 bits do C e "P = 2**61 - 1" em máquinas com longos de 64 bits do C.

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", define "hash(x)" como "m * invmod(n, P) % P",
  onde "invmod(n, P)" retorna o inverso do módulo de "n" com "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", a substituo com "-2".

* Os valores particulares "sys.hash_info.inf" e "-sys.hash_info.inf"
  são usados como valores de hash para infinidade positiva ou
  infinidade negativa (respectivamente).

* Para número "complex" "z", o valor da hash do número real partes
  imaginárias são combinados calculando "hash(z.real) +
  sys.hash_info.imag * hash(z.imag)", módulo 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 o resultado é "-1", ele é substituído por "-2".

Para esclarecer as regras acima, aqui estão alguns exemplos de código
em Python, equivalentes ao hash embutido, para calcular o hash de
números racionais, "float" ou "complex":

   import sys, math

   def hash_fraction(m, n):
       """Calcula o hash de um número racional m / n.

       Presume que m e n são inteiros, com n positivo.
       Equivalente a hash(fractions.Fraction(m, n)).

       """
       P = sys.hash_info.modulus
       # Remove fatores comuns de P.  (Desnecessário se m e n são primos entre si.)
       while m % P == n % P == 0:
           m, n = m // P, n // P

       if n % P == 0:
           hash_value = sys.hash_info.inf
       else:
           # Pequeno teorema de Fermat: pow(n, P-1, P) é 1, então
           # pow(n, P-2, P) dá o inverso de n módulo 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):
       """Calcula o hash de um ponto flutuante x."""

       if math.isnan(x):
           return object.__hash__(x)
       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):
       """Calcula o hash de um número complexo z."""

       hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
       # faz um módulo para redução de sinal 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


Tipo booleano - "bool"
======================

Booleanos representam valores verdade. O tipo "bool" tem exatamente
duas instâncias constantes: "True" e "False".

A função embutida "bool()" converte qualquer valor em um booleano, se
o valor puder ser interpretado como um valor verdade (consultar seção
Teste do valor verdade acima).

Para operações lógicas, use operadores booleanos "and", "or" e "not".
Ao aplicar operadores bit a bit "&", "|", "^" a dois booleanos, o
resultado é um booleano equivalente às operações lógicas "e", "ou",
"xor". Entretanto, é preferível usar os operadores lógicos "and", "or"
e "!=" em relação aos "&", "|" e "^".

Descontinuado desde a versão 3.12: O uso do operador de inversão bit a
bit "~" foi descontinuado e levantará um erro no Python 3.16.

"bool" é uma subclasse "int" (veja Tipos numéricos --- int, float,
complex). Em diversos contextos numéricos, "False" e "True" se
comportam como 0 e 1, respectivamente. Entretanto, basear-se somente
nisso,  é desencorajado; ao invés disso, a conversão deve ser feita
explicitamente usando "int()".


Tipos iteradores
================

Python suporta o conceito de iteração por contêineres. 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 contêineres afim destes
proverem suporte a *iterável*:

container.__iter__()

   Retorna um objeto *iterador*. O objeto deve suportar o protocolo
   iterador descrito abaixo. Se um contêiner 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 objeto suportando múltiplas formas de
   iteração seria uma estrutura em árvore a qual suporta ambas
   travessias de travessia em largura e em profundidade.) Esse método
   corresponde ao slot "tp_iter" da estrutura de tipos para objetos
   Python na API Python/C.

Os próprios objetos iteradores são obrigados a suportarem os dois
métodos a seguir, que juntos formam o *protocolo iterador*:

iterator.__iter__()

   Retorna o próprio objeto *iterador* em si. Isso é necessário para
   permitir que ambos os contêineres e iteradores sejam usados com as
   instruções "for" e "in". Este método corresponde ao slot "tp_iter"
   da estrutura de tipos para objetos Python na API Python/C.

iterator.__next__()

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

Python define diversos objetos iteradores 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 iterador.

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


Tipos geradores
---------------

Os *geradores* do Python proveem uma maneira conveniente para
implementar o protocolo iterador. Se o método "__iter__()" de um
objeto contêiner é implementado como um gerador, ele irá
automaticamente retornar um objeto iterador (tecnicamente, um objeto
gerador) fornecendo os métodos "__iter__()" e "__next__()". Mais
informações sobre geradores podem ser encontradas na documentação para
a expressão yield.


Tipos sequências --- "list", "tuple", "range"
=============================================

Existem três tipos básicos de sequência: listas, tuplas e objetos
range. Tipos de sequência adicionais adaptados para o processamento de
dados binários e strings de texto são descritos em seções dedicadas.


Operações comuns de sequências
------------------------------

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

Essa tabela lista as operações de sequência ordenadas em prioridade
ascendente. Na tabela, *s* e *t* são sequências do mesmo tipo, *n*,
*i*, *j* e *k* são inteiros e *x* é um objeto arbitrário que atende a
qualquer restrição de valor e tipo imposta 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*, caso contrário      |            |
|                            | "False"                          |            |
+----------------------------+----------------------------------+------------+
| "x not in s"               | "False" caso um item de *s* for  | (1)        |
|                            | igual a *x*, caso contrário      |            |
|                            | "True"                           |            |
+----------------------------+----------------------------------+------------+
| "s + t"                    | a concatenaçã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*-ésimo item de *s*, origem 0  | (3)(8)     |
+----------------------------+----------------------------------+------------+
| "s[i:j]"                   | fatia de *s* de *i* até *j*      | (3)(4)     |
+----------------------------+----------------------------------+------------+
| "s[i:j:k]"                 | fatia de *s* de *i* até *j* com  | (3)(5)     |
|                            | passo *k*                        |            |
+----------------------------+----------------------------------+------------+
| "len(s)"                   | comprimento de *s*               |            |
+----------------------------+----------------------------------+------------+
| "min(s)"                   | menor item de *s*                |            |
+----------------------------+----------------------------------+------------+
| "max(s)"                   | maior item de *s*                |            |
+----------------------------+----------------------------------+------------+

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

Iteradores para frente e reversos sobre sequências mutáveis acessam
valores usando um índice. Esse índice continuará avançando (ou
retrocedendo) mesmo que a sequência subjacente seja alterada. O
iterador termina somente quando um "IndexError" ou um "StopIteration"
é encontrado (ou quando o índice cai abaixo de zero).

Notas:

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

      >>> "gg" in "eggs"
      True

2. Os valores de *n* menos "0" são tratados como "0" (o que produz uma
   sequência vazia do mesmo tipo que *s*). Observe que os itens na
   sequência *s* não são copiados; eles são referenciados várias
   vezes. Isso frequentemente 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]]

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

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

4. The slice of *s* from *i* to *j* is defined as the sequence of
   items with index *k* such that "i <= k < j".

   * If *i* is omitted or "None", use "0".

   * If *j* is omitted or "None", use "len(s)".

   * If *i* or *j* is less than "-len(s)", use "0".

   * If *i* or *j* is greater than "len(s)", use "len(s)".

   * If *i* is greater than or equal to *j*, the slice is empty.

5. A fatia *s* de *i* até *j* com passo *k* é definida como sendo a
   sequê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 atingido (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 sequência. Para obter um custo de tempo de
   execução linear, devemos alternar para uma das alternativas abaixo:

   * Se estiver concatenando objetos "str", você pode 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 estiver concatenando objetos "bytes", você também pode usar o
     método "bytes.join()" ou "io.BytesIO", ou você pode fazer
     concatenação interna com um objeto "bytearray". A classe
     "bytearray" são objetos mutáveis e possuem um eficiente mecanismo
     de superalocação

   * Se estiver concatenando objetos "tuple", estenda a classe "list"
     em vez disso

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

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

8. Uma "IndexError" é levantada se *i* estiver fora do intervalo da
   sequência.

-[ Métodos de sequência ]-

Tipos de sequência também oferecem suporte aos seguintes métodos:

sequence.count(value, /)

   Retorna o número total de ocorrências de *value* em *sequence*.

sequence.index(value[, start[, stop]])

   Retorna o índice da primeira ocorrência de *value* em *sequence*.

   Levanta "ValueError" se *value* não for encontrado em *sequence*.

   Os argumentos *start* ou *stop* permitem uma busca eficiente de
   subseções da sequência, começando em *start* e terminando em
   *stop*. Isso é aproximadamente equivalente a "start +
   sequence[start:stop].index(value)", só que sem copiar nenhum dado.

   Cuidado:

     Nem todos os tipos de sequência oferecem suporte a passagem dos
     argumentos *start* e *stop*.


Tipos sequência imutáveis
-------------------------

A única operação que os tipos sequências imutáveis geralmente
implementam que também não é implementada pelos tipos sequências
mutáveis é suporte para a função embutida "hash()".

Esse suporte permite sequências imutáveis, tais como instâncias da
classe "tuple", serem usadas como chaves de dicionários "dict" e
armazenados em instâncias de "set" e 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 sequências mutáveis
-------------------------

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

Na tabela *s* é uma instância de um tipo de sequência mutável, *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*                          |                       |
+--------------------------------+----------------------------------+-----------------------+
| "del s[i]"                     | remove o item *i* de *s*         |                       |
+--------------------------------+----------------------------------+-----------------------+
| "s[i:j] = t"                   | fatias de *s* de *i* até *j* são |                       |
|                                | substituídas pelo conteúdo do    |                       |
|                                | iterável *t*                     |                       |
+--------------------------------+----------------------------------+-----------------------+
| "del s[i:j]"                   | remove os elementos de "s[i:j]"  |                       |
|                                | da lista (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 += 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  | (2)                   |
|                                | por *n* vezes                    |                       |
+--------------------------------+----------------------------------+-----------------------+

Notas:

1. se *k* não for igual a "1", *t* deve ter o mesmo comprimento que a
   fatia a qual ele está substituindo.

2. O valor *n* é um inteiro, ou um objeto implementando "__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" em Operações comuns de sequências.

-[ Métodos de sequências mutáveis ]-

Tipos de sequências mutáveis também oferecem suporte aos seguintes
métodos:

sequence.append(value, /)

   Append *value* to the end of the sequence. This is equivalent to
   writing "seq[len(seq):len(seq)] = [value]".

sequence.clear()

   Adicionado na versão 3.3.

   Remove todos os itens de *sequence*. Isso equivale a escrever "del
   sequence[:]".

sequence.copy()

   Adicionado na versão 3.3.

   Cria uma cópia rasa de *sequence*. Isso equivale a escrever
   "sequence[:]".

   Dica:

     O método "copy()" não faz parte de "MutableSequence" "ABC", mas a
     maioria dos tipos de sequências mutáveis concretas o fornecem.

sequence.extend(iterable, /)

   Estende *sequence* com o conteúdo de *iterable*. Em geral, isso
   equivale a escrever "seq[len(seq):len(seq)] = iterable".

sequence.insert(index, value, /)

   Insire *value* em *sequence* no *index* fornecido. Isso equivale a
   escrever "sequence[index:index] = [value]".

sequence.pop(index=-1, /)

   Recupera o item em *index* e também o remove de *sequence*. Por
   padrão, o último item em *sequence* é removido e retornado.

sequence.remove(value, /)

   Remove o primeiro item de *sequence* onde "sequence[i] == value".

   Levanta "ValueError" se *value* não for encontrado em *sequence*.

sequence.reverse()

   Inverte os itens da *sequence* no lugar. Este método mantém a
   economia de espaço ao inverter uma sequência grande. Para lembrar
   aos usuários que ele opera por efeito colateral, ele retorna
   "None".


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 colchetes, separando itens por vírgulas: "[a]", "[a, b,
     c]"

   * Usando uma compreensão de lista: "[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 de *iterable*. *iterable* pode 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, "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
   embutida "sorted()".

   Listas implementam todas as operações de sequências comuns e
   mutáveis. 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 em um
      estado parcialmente modificado).

      "sort()" aceita 2 argumentos que só podem ser passados como
      argumentos somente-nomeados:

      *key* especifica uma função de um argumento que é usado para
      extrair uma chave de comparação de cada elemento da 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
      estivesse invertida.

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

      O método "sort()" é garantido como sendo estável. Uma
      classificação é estável se ela garantir 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).

      Para exemplos de classificação e um breve tutorial de
      classificação, veja Técnicas de ordenação.

      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.

Ver também:

  For detailed information on thread-safety guarantees for "list"
  objects, see Thread safety for list objects.


Tuplas
------

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

class tuple(iterable=(), /)

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

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

   * Usando uma vírgula à direita para uma tupla singleton: "a," ou
     "(a,)"

   * Separando os itens com vírgulas: "a, b, c" ou "(a, b, c)"

   * Usando a função embutida "tuple()": "tuple()" ou
     "tuple(iterable)"

   O construtor constrói uma tupla cujos itens são iguais e na mesma
   ordem dos itens de *iterable*. *iterable* pode ser uma sequência,
   um contêiner que suporta iteração ou um objeto iterador. Se
   *iterable* já for uma tupla, este será retornado inalterado. Por
   exemplo, "tuple('abc')" retorna "('a', 'b', 'c')" e "tuple( [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 tupla de 3 elementos com um único argumento.

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

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 objeto tupla simples.


Intervalos
----------

O tipo "range" representa uma sequência imutável de números e é
comumente usado para percorrer um número determinado de vezes em um
laço "for".

class range(stop, /)
class range(start, stop, step=1, /)

   Os argumentos para o construtor de intervalo devem ser inteiros
   ("int" embutido 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 "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" e
   "r[i] < stop".

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

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

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

   Exemplos de intervalos:

      >>> 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))
      []

   Ranges implementam todas as operações comuns de sequência, exceto a
   concatenação e a repetição (devido ao fato de que os objetos
   intervalos só podem representar sequências que seguem um padrão
   rígido. e a repetição e a concatenação geralmente vão violar 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 do tipo "range" sobre um "list" ou "tuple" regular é 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
itens individuais e subintervalos conforme necessário).

Objetos intervalos implementam a ABC "collections.abc.Sequence", e
fornecem recursos como testes de contenção, pesquisa de índice de
elemento, fatiamento e suporte a índices negativos (veja Tipos
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 intervalos por igualdade com "==" e "!=" os compara
como sequências. Ou seja, dois objetos intervalos são considerados
iguais se representarem a mesma sequência de valores. (Observe que
dois objetos intervalos considerados iguais podem ter diferentes
atributos "start", "stop" e "step", por exemplo "range(0) == range(2,
1, 3)" ou "range(0, 3, 2) == range(0, 4, 2)".)

Alterado na versão 3.2: Implementa a ABC Sequence. 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: Define '==' e '!=' para comparar objetos
intervalos com base na sequência de valores que eles definem (em vez
de comparar com base na identidade do objeto).Adicionados 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.


Resumo dos métodos de tipo de sequência binária e de texto
==========================================================

A tabela a seguir resume os métodos de tipos de sequência binária e de
texto por categoria.

+----------------------------+--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
| Categoria                  | Métodos "str"                                                         | Métodos "bytes" e "bytearray"                                                   |
|============================|====================|============|============|========================|======================|=============|=============|==============================|
| Formatação                 | "str.format()"                                                        |                                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.format_map()"                                                    |                                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | Literais de strings formatadas                                        |                                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | Formatação de string no estilo printf                                 | Estilo de Formatação de bytes printf-style                                      |
+----------------------------+--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
| Pesquisa e substituição    | "str.find()"       | "str.rfind()"                                    | "bytes.find()"       | "bytes.rfind()"                                          |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.index()"      | "str.rindex()"                                   | "bytes.index()"      | "bytes.rindex()"                                         |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.startswith()"                                                    | "bytes.startswith()"                                                            |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.endswith()"                                                      | "bytes.endswith()"                                                              |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.count()"                                                         | "bytes.count()"                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.replace()"                                                       | "bytes.replace()"                                                               |
+----------------------------+--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
| Divisão e união            | "str.split()"                   | "str.rsplit()"                      | "bytes.split()"                    | "bytes.rsplit()"                           |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.splitlines()"                                                    | "bytes.splitlines()"                                                            |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.partition()"                                                     | "bytes.partition()"                                                             |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.rpartition()"                                                    | "bytes.rpartition()"                                                            |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.join()"                                                          | "bytes.join()"                                                                  |
+----------------------------+--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
| String Classification      | "str.isalpha()"                                                       | "bytes.isalpha()"                                                               |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.isdecimal()"                                                     |                                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.isdigit()"                                                       | "bytes.isdigit()"                                                               |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.isnumeric()"                                                     |                                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.isalnum()"                                                       | "bytes.isalnum()"                                                               |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.isidentifier()"                                                  |                                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.islower()"                                                       | "bytes.islower()"                                                               |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.isupper()"                                                       | "bytes.isupper()"                                                               |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.istitle()"                                                       | "bytes.istitle()"                                                               |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.isspace()"                                                       | "bytes.isspace()"                                                               |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.isprintable()"                                                   |                                                                                 |
+----------------------------+--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
| Case Manipulation          | "str.lower()"                                                         | "bytes.lower()"                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.upper()"                                                         | "bytes.upper()"                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.casefold()"                                                      |                                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.capitalize()"                                                    | "bytes.capitalize()"                                                            |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.title()"                                                         | "bytes.title()"                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.swapcase()"                                                      | "bytes.swapcase()"                                                              |
+----------------------------+--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
| Preenchimento e remoção    | "str.ljust()"                   | "str.rjust()"                       | "bytes.ljust()"                    | "bytes.rjust()"                            |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.center()"                                                        | "bytes.center()"                                                                |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.expandtabs()"                                                    | "bytes.expandtabs()"                                                            |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.strip()"                                                         | "bytes.strip()"                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.lstrip()"                               | "str.rstrip()"         | "bytes.lstrip()"                                 | "bytes.rstrip()"             |
+----------------------------+--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
| Tradução e codificação     | "str.translate()"                                                     | "bytes.translate()"                                                             |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.maketrans()"                                                     | "bytes.maketrans()"                                                             |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            | "str.encode()"                                                        |                                                                                 |
|                            +--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+
|                            |                                                                       | "bytes.decode()"                                                                |
+----------------------------+--------------------+------------+------------+------------------------+----------------------+-------------+-------------+------------------------------+


Tipo sequência de texto --- "str"
=================================

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

* Aspas simples: "'permitem aspas "duplas" internas'"

* Aspas duplas: ""permitem aspas 'simples' internas""

* Aspas triplas: "'''Três aspas simples'''", """"Três aspas duplas""""

Strings de aspas triplas podem expandir por várias linhas -- todos os
espaços em branco associados serão incluídos em literal string.

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 Literais de string e bytes para mais informações sobre as várias
formas de literal de string, incluindo o suporte a sequêncis de
escape, e o prefixo "r" ("raw") que desabilita a maioria dos processos
de sequência 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 string não
vazia *s*, "s[0] == s[0:1]".

Também não existe um tipo string mutável, mas o método "str.join()" ou
a classe "io.StringIO" podem ser usados 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" foi 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(*, encoding='utf-8', errors='strict')
class str(object)
class str(object, encoding, errors='strict')
class str(object, *, errors)

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

   Se nem *encoding* nem *errors* for fornecido, "str(object)"
   retornará "type(object).__str__(object)", que é a representação da
   string "informal" ou que pode ser facilmente imprimível  de
   *object*. Para objetos string, esta é a própria string. Se *object*
   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 *objeto bytes ou similar* (por exemplo, "bytes" ou
   "bytearray"). Nesse caso, se *object* for um objeto "bytes" (ou
   "bytearray"), então "str(bytes, encoding, errors)" equivale 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.

   Passando 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
   de comando "-b" para Python). Por exemplo:

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

   Para mais informações sobre a classe "str" e seus métodos, veja
   Tipo sequência de texto --- str e a seção Métodos de string abaixo.
   Para gerar strings formatadas, veja as seções Literais de strings
   formatadas 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 comuns de sequências,
juntamente com os métodos adicionais descritos abaixo.

Strings também possuem suporte para 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 gama menor de tipos e é
levemente mais difícil de utilizar corretamente, mas é frequentemente
mais rápida para os casos na qual ela consegue manipular (Formatação
de string no estilo printf).

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 restante em minúsculo.

   Alterado na versão 3.8: O primeiro caractere agora é colocado em
   *titlecase* ao invés de letras maiúsculas. Isso significa que
   caracteres como dígrafos apenas terão sua primeira letra alterada
   para maiúscula, ao invés de todos os caracteres.

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 ou maiúsculas.

   Casefolding is similar to lowercasing but more aggressive because
   it is intended to remove all case distinctions in a string. For
   example, the German lowercase letter "'ß'" is equivalent to ""ss"".
   Since it is already lowercase, "lower()" would do nothing to "'ß'";
   "casefold()" converts it to ""ss"". For example:

      >>> 'straße'.lower()
      'straße'
      >>> 'straße'.casefold()
      'strasse'

   The casefolding algorithm is described in section 3.13.3 'Default
   Case Folding' of the Unicode Standard.

   Adicionado 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)". Por exemplo:

      >>> 'Python'.center(10)
      '  Python  '
      >>> 'Python'.center(10, '-')
      '--Python--'
      >>> 'Python'.center(4)
      'Python'

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.

   Se *sub* estiver vazio, retorna o número de strings vazias entre os
   caracteres, que é o comprimento da string mais um. Por exemplo:

      >>> 'spam, spam, spam'.count('spam')
      3
      >>> 'spam, spam, spam'.count('spam', 5)
      2
      >>> 'spam, spam, spam'.count('spam', 5, 10)
      1
      >>> 'spam, spam, spam'.count('eggs')
      0
      >>> 'spam, spam, spam'.count('')
      17

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

   Retorna a string codificada para "bytes".

   *encoding* tem como padrão "'utf-8'"; veja Standard Encodings para
   valores possíveis.

   *errors* controla como os erros de codificação são tratados. Se
   "'strict'" (o padrão), uma exceção "UnicodeError" é levantada.
   Outros valores possíveis são "'ignore'", "'replace'",
   "'xmlcharrefreplace'", "'backslashreplace'" e qualquer outro nome
   registrado via "codecs.register_error()". Veja Error Handlers para
   detalhes.

   Por motivos de desempenho, o valor de *errors* não é verificado
   quanto à validade, a menos que um erro de codificação realmente
   ocorra, Modo de Desenvolvimento do Python esteja ativado ou uma
   construção de depuração seja usada. Por exemplo:

      >>> encoded_str_to_bytes = 'Python'.encode()
      >>> type(encoded_str_to_bytes)
      <class 'bytes'>
      >>> encoded_str_to_bytes
      b'Python'

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

   Alterado na versão 3.9: O valor do argumento *errors* agora é
   verificado em Modo de Desenvolvimento do Python e no modo de
   depuração.

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 testar a partir daquela posição. Com o parâmetro
   opcional *end*, devemos parar de comparar na posição especificada.
   Usar *start* e *end* equivale a "str[start:end].endswith(suffix)".
   Por exemplo:

      >>> 'Python'.endswith('on')
      True
      >>> 'a tuple of suffixes'.endswith(('at', 'in'))
      False
      >>> 'a tuple of suffixes'.endswith(('at', 'es'))
      True
      >>> 'Python is amazing'.endswith('is', 0, 9)
      True

   Veja também "startswith()" e "removesuffix()".

str.expandtabs(tabsize=8)

   Retorna 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 caractere por caractere. Se o caractere é 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 caractere de tabulação em si não é copiado.) Se o caractere é um
   caractere de nova linha ("\n") ou de retorno ("\r"), ele é copiado
   e a coluna atual é redefinida para zero. Qualquer outro caractere é
   copiado sem ser modificado e a coluna atual é incrementada em uma
   unidade independentemente de como o caractere é representado quando
   é impresso. Por exemplo:

      >>> '01\t012\t0123\t01234'.expandtabs()
      '01      012     0123    01234'
      >>> '01\t012\t0123\t01234'.expandtabs(4)
      '01  012 0123    01234'
      >>> print('01\t012\n0123\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]". Argumentos opcionais
   como *start* e *end* são interpretados como na notação de
   fatiamento. Retorna "-1" se *sub* não for localizado. Por exemplo:

      >>> 'spam, spam, spam'.find('sp')
      0
      >>> 'spam, spam, spam'.find('sp', 5)
      6

   Veja também "rfind()" e "index()".

   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 um índice numérico de um argumento posicional
   ou o nome de um argumento nomeado. Retorna a cópia da string onde
   cada campo para substituição é substituído com o valor da string do
   argumento correspondente. Por exemplo:

      >>> "A soma de 1 + 2 é {0}".format(1+2)
      'A soma de 1 + 2 é 3'
      >>> "A soma de {a} + {b} é {answer}".format(answer=1+2, a=1, b=2)
      'A soma de 1 + 2 é 3'
      >>> "{1} espera a inquisição {0}!".format("espanhola", "Ninguém")
      'Ninguém espera a inquisição espanhola!'

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

   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 temporariamente a localidade "LC_CTYPE" para a
   localidade "LC_NUMERIC" em alguns casos.

str.format_map(mapping, /)

   Semelhante a "str.format(**mapping)", exceto pelo fato de que
   "mapping" é usado diretamente 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'

   Adicionado na versão 3.2.

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

   Like "find()", but raise "ValueError" when the substring is not
   found. For example:

      >>> 'spam, spam, spam'.index('spam')
      0
      >>> 'spam, spam, spam'.index('eggs')
      Traceback (most recent call last):
        File "<python-input-0>", line 1, in <module>
          'spam, spam, spam'.index('eggs')
          ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
      ValueError: substring not found

   See also "rindex()".

str.isalnum()

   Return "True" if all characters in the string are alphanumeric and
   there is at least one character, "False" otherwise.  A character
   "c" is alphanumeric if one of the following returns "True":
   "c.isalpha()", "c.isdecimal()", "c.isdigit()", or "c.isnumeric()".
   For example:

      >>> 'abc123'.isalnum()
      True
      >>> 'abc123!@#'.isalnum()
      False
      >>> ''.isalnum()
      False
      >>> ' '.isalnum()
      False

str.isalpha()

   Return "True" if all characters in the string are alphabetic and
   there is at least one character, "False" otherwise.  Alphabetic
   characters are those characters defined in the Unicode character
   database as "Letter", i.e., those with general category property
   being one of "Lm", "Lt", "Lu", "Ll", or "Lo".  Note that this is
   different from the Alphabetic property defined in the section 4.10
   'Letters, Alphabetic, and Ideographic' of the Unicode Standard. For
   example:

      >>> 'Letras e espaços'.isalpha()
      False
      >>> 'LetrasApenas'.isalpha()
      True
      >>> 'µ'.isalpha()  # Caracteres não-ASCII podem ser considerados alfabeticamente também
      True

   Consulte Propriedades Unicode.

str.isascii()

   Retorna "True" se a string é vazia ou se todos os caracteres na
   string são ASCII, "False" caso contrário. Caracteres ASCII têm
   pontos de código no intervalo U+0000-U+007F. Por exemplo:

      >>> 'Caracteres ASCII'.isascii()
      True
      >>> 'µ'.isascii()
      False

   Adicionado 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, tal como U+0660, ou dígito zero para arábico-
   índico. Formalmente, um caractere decimal é um caractere em Unicode
   cuja categoria geral é "Nd". Por exemplo:

      >>> '0123456789'.isdecimal()
      True
      >>> '٠١٢٣٤٥٦٧٨٩'.isdecimal()  # Dígitos árabe-índico zero até nove
      True
      >>> 'alfabético'.isdecimal()
      False

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 Nomes (identificadores e palavras
   reservadas).

   "keyword.iskeyword()" pode ser usada para testar se a string "s" é
   uma palavra reservada, tal como "def" e "class".

   Exemplo:

      >>> from keyword import iskeyword

      >>> 'olá.isidentifier(), iskeyword('olá')
      (True, False)
      >>> 'def'.isidentifier(), iskeyword('def')
      (True, True)

str.islower()

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

str.isnumeric()

   Return "True" if all characters in the string are numeric
   characters, and there is at least one character, "False" otherwise.
   Numeric characters include digit characters, and all characters
   that have the Unicode numeric value property, e.g. U+2155, VULGAR
   FRACTION ONE FIFTH.  Formally, numeric characters are those with
   the property value Numeric_Type=Digit, Numeric_Type=Decimal or
   Numeric_Type=Numeric. For example:

      >>> '0123456789'.isnumeric()
      True
      >>> '٠١٢٣٤٥٦٧٨٩'.isnumeric()  # Arabic-indic digit zero to nine
      True
      >>> '⅕'.isnumeric()  # Vulgar fraction one fifth
      True
      >>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
      (False, True, True)

   See also "isdecimal()" and "isdigit()". Numeric characters are a
   superset of decimal numbers.

str.isprintable()

   Retorna "True" se todos os caracteres na string forem imprimíveis,
   "False" se contiver pelo menos um caractere não imprimível.

   Aqui, "imprimíveis" significa que o caractere é adequado para
   "repr()" usar em sua saída; "não imprimível" significa que "repr()"
   em tipos embutidos fará o escape hexadecimal do caractere. Não tem
   relação com o tratamento de strings escritas em "sys.stdout" ou
   "sys.stderr".

   Os caracteres imprimíveis são aqueles que no banco de dados de
   caracteres Unicode (veja "unicodedata") têm uma categoria geral no
   grupo Letra, Marca, Número, Pontuação ou Símbolo (L, M, N, P ou S);
   mais o espaço ASCII 0x20. Caracteres não imprimíveis são aqueles no
   grupo Separador ou Outro (Z ou C), exceto o espaço ASCII.

   Por exemplo:

      >>> ''.isprintable(), ' '.isprintable()
      (True, True)
      >>> '\t'.isprintable(), '\n'.isprintable()
      (False, False)

   See also "isspace()".

str.isspace()

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

   Por exemplo:

      >>> ''.isspace()
      False
      >>> ' '.isspace()
      True
      >>> '\t\n'.isspace() # TAB and BREAK LINE
      True
      >>> '\u3000'.isspace() # IDEOGRAPHIC SPACE
      True

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

   See also "isprintable()".

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.

   Por exemplo:

      >>> 'Spam, Spam, Spam'.istitle()
      True
      >>> 'spam, spam, spam'.istitle()
      False
      >>> 'SPAM, SPAM, SPAM'.istitle()
      False

   Veja também "title()".

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.

   >>> 'BANANA'.isupper()
   True
   >>> 'banana'.isupper()
   False
   >>> 'baNana'.isupper()
   False
   >>> ' '.isupper()
   False

str.join(iterable, /)

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

      >>> ', '.join(['spam', 'spam', 'spam'])
      'spam, spam, spam'
      >>> '-'.join('Python')
      'P-y-t-h-o-n'

   Veja também "split()".

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)".

   Por exemplo:

      >>> 'Python'.ljust(10)
      'Python    '
      >>> 'Python'.ljust(10, '.')
      'Python....'
      >>> 'Monty Python'.ljust(10, '.')
      'Monty Python'

   See also "rjust()".

str.lower()

   Return a copy of the string with all the cased characters [4]
   converted to lowercase. For example:

      >>> 'Lower Method Example'.lower()
      'lower method example'

   The lowercasing algorithm used is described in section 3.13.2
   'Default Case Conversion' of the Unicode Standard.

str.lstrip(chars=None, /)

   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 removidas:

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

   Consulte "str.removeprefix()" para um método que removerá uma única
   string de prefixo em vez de todo um conjunto de caracteres. Por
   exemplo:

      >>> 'Arthur: three!'.lstrip('Arthur: ')
      'ee!'
      >>> 'Arthur: three!'.removeprefix('Arthur: ')
      'three!'

static str.maketrans(dict, /)
static str.maketrans(from, to, remove='', /)

   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
   comprimento, e no dicionário resultante, cada caractere em *from*
   será mapeado para o caractere na mesma posição em *to*. Se existir
   um terceiro argumento, ele deve ser uma string, cujos caracteres
   serão mapeados para "None" no resultado.

   Alterado na versão 3.15: *dict* can now be a "frozendict".

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 separador, 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.

   Por exemplo:

      >>> 'Monty Python'.partition(' ')
      ('Monty', ' ', 'Python')
      >>> "Monty Python's Flying Circus".partition(' ')
      ('Monty', ' ', "Python's Flying Circus")
      >>> 'Monty Python'.partition('-')
      ('Monty Python', '', '')

   See also "rpartition()".

str.removeprefix(prefix, /)

   If the string starts with the *prefix* string, return
   "string[len(prefix):]". Otherwise, return a copy of the original
   string:

      >>> 'TestHook'.removeprefix('Test')
      'Hook'
      >>> 'BaseTestCase'.removeprefix('Test')
      'BaseTestCase'

   Adicionado na versão 3.9.

   See also "removesuffix()" and "startswith()".

str.removesuffix(suffix, /)

   If the string ends with the *suffix* string and that *suffix* is
   not empty, return "string[:-len(suffix)]". Otherwise, return a copy
   of the original string:

      >>> 'MiscTests'.removesuffix('Tests')
      'Misc'
      >>> 'TmpDirMixin'.removesuffix('Tests')
      'TmpDirMixin'

   Adicionado na versão 3.9.

   See also "removeprefix()" and "endswith()".

str.replace(old, new, /, count=-1)

   Return a copy of the string with all occurrences of substring *old*
   replaced by *new*.  If *count* is given, only the first *count*
   occurrences are replaced. If *count* is not specified or "-1", then
   all occurrences are replaced. For example:

      >>> 'spam, spam, spam'.replace('spam', 'eggs')
      'eggs, eggs, eggs'
      >>> 'spam, spam, spam'.replace('spam', 'eggs', 1)
      'eggs, spam, spam'

   Alterado na versão 3.13: *count* agora é suportado como um
   argumento nomeado.

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

   Return the highest index in the string where substring *sub* is
   found, such that *sub* is contained within "s[start:end]".
   Optional arguments *start* and *end* are interpreted as in slice
   notation.  Return "-1" on failure. For example:

      >>> 'spam, spam, spam'.rfind('sp')
      12
      >>> 'spam, spam, spam'.rfind('sp', 0, 10)
      6

   See also "find()" and "rindex()".

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

   Like "rfind()" but raises "ValueError" when the substring *sub* is
   not found. For example:

      >>> 'spam, spam, spam'.rindex('spam')
      12
      >>> 'spam, spam, spam'.rindex('eggs')
      Traceback (most recent call last):
        File "<stdin-0>", line 1, in <module>
          'spam, spam, spam'.rindex('eggs')
          ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
      ValueError: substring not found

   See also "index()" and "find()".

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)".

   Por exemplo:

      >>> 'Python'.rjust(10)
      '    Python'
      >>> 'Python'.rjust(10, '.')
      '....Python'
      >>> 'Monty Python'.rjust(10, '.')
      'Monty Python'

   See also "ljust()" and "zfill()".

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
   separador, 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.

   Por exemplo:

      >>> 'Monty Python'.rpartition(' ')
      ('Monty', ' ', 'Python')
      >>> "Monty Python's Flying Circus".rpartition(' ')
      ("Monty Python's Flying", ' ', 'Circus')
      >>> 'Monty Python'.rpartition('-')
      ('', '', 'Monty Python')

   See also "partition()".

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=None, /)

   Return a copy of the string with trailing characters removed.  The
   *chars* argument is a string specifying the set of characters to be
   removed.  If omitted or "None", the *chars* argument defaults to
   removing whitespace.  The *chars* argument is not a suffix; rather,
   all combinations of its values are stripped. For example:

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

   See "removesuffix()" for a method that will remove a single suffix
   string rather than all of a set of characters.  For example:

      >>> 'Monty Python'.rstrip(' Python')
      'M'
      >>> 'Monty Python'.removesuffix(' Python')
      'Monty'

   See also "strip()".

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 em vários caracteres como um único delimitador
   (para separar com vários delimitadores, use "re.split()"). 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', '']
      >>> '1<>2<>3<4'.split('<>')
      ['1', '2', '3<4']

   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']

   Se *sep* não for especificado ou for "None" e *maxsplit* for "0",
   somente as sequências iniciais de espaços em branco consecutivos
   serão consideradas.

   Por exemplo:

      >>> "".split(None, 0)
      []
      >>> "   ".split(None, 0)
      []
      >>> "   foo   ".split(maxsplit=0)
      ['foo   ']

   Veja também "join()".

str.splitlines(keepends=False)

   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 *novas linhas universais*.

   +-------------------------+-------------------------------+
   | Representação           | 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"                | Separador de Parágrafo        |
   +-------------------------+-------------------------------+

   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()
      []
      >>> "Uma linha\n".splitlines()
      ['Uma linha']

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

      >>> ''.split('\n')
      ['']
      >>> 'Duas linhas\n'.split('\n')
      ['Duas linhas', '']

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.

   Por exemplo:

      >>> 'Python'.startswith('Py')
      True
      >>> 'a tuple of prefixes'.startswith(('at', 'a'))
      True
      >>> 'Python is amazing'.startswith('is', 7)
      True

   See also "endswith()" and "removeprefix()".

str.strip(chars=None, /)

   Return a copy of the string with the leading and trailing
   characters removed. The *chars* argument is a string specifying the
   set of characters to be removed. If omitted or "None", the *chars*
   argument defaults to removing whitespace. The *chars* argument is
   not a prefix or suffix; rather, all combinations of its values are
   stripped.

   Whitespace characters are defined by "str.isspace()".

   Por exemplo:

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

   The outermost leading and trailing *chars* argument values are
   stripped from the string. Characters are removed from the leading
   end until reaching a string character that is not contained in the
   set of characters in *chars*. A similar action takes place on the
   trailing end.

   Por exemplo:

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

   See also "rstrip()".

str.swapcase()

   Return a copy of the string with uppercase characters converted to
   lowercase and vice versa. For example:

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

   Note that it is not necessarily true that "s.swapcase().swapcase()
   == s". For example:

      >>> 'straße'.swapcase().swapcase()
      'strasse'

   See also "str.lower()" and "str.upper()".

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:

      >>> 'Olá mundo'.title()
      'Olá mundo'

   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
   contrações e possessivos formam limites de palavras, os quais podem
   não ser o resultado desejado:

      >>> "a caixa d'água do joe's bar está vazia".title()
      "A Caixa D'Água Do Joe'S Bar Está Vazia"

   A função "string.capwords()" não tem esse problema, pois ela divide
   palavras apenas em espaços.

   Alternativamente, 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).capitalize(),
      ...                   s)
      ...
      >>> titlecase("o joe's bar está aberto")
      "O Joe's Bar Está Aberto"

   Veja também "istitle()".

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.

   The following example uses a mapping to replace "'a'" with "'X'",
   "'b'" with "'Y'", and delete "'c'":

      >>> 'abc123'.translate({ord('a'): 'X', ord('b'): 'Y', ord('c'): None})
      'XY123'

   Veja também o módulo "codecs" para uma abordagem mais flexível para
   mapeamento de caractere 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).

   The uppercasing algorithm used is described in section 3.13.2
   'Default Case Conversion' of the Unicode Standard.

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'

   See also "rjust()".


Strings literais formatadas (f-strings)
---------------------------------------

Adicionado na versão 3.6.

Alterado na versão 3.7: "await" e "async for" podem ser usados em
expressões dentro de f-strings.

Alterado na versão 3.8: Adicionado o especificador de depuração ("=")

Alterado na versão 3.12: Muitas restrições a expressões dentro de
f-strings foram removidas. Notavelmente, strings aninhadas,
comentários e contrabarras agora são permitidos.

Uma *f-string* (formalmente uma *literal de string formatada*) é uma
literal de string prefixada com "f" ou "F". Esse tipo de literal de
string permite incorporar os resultados de expressões Python
arbitrárias dentro de *campos de substituição*, delimitados por chaves
("{}"). Cada campo de substituição deve conter uma expressão,
opcionalmente seguido por:

* um *especificador de depuração* -- um sinal de igual ("=");

* um *especificador de conversão* -- "!s", "!r" ou "!a"; e/ou

* um *especificador de format* prefixado com um caractere de dois
  pontos (":").

Veja a seção de análise léxica sobre f-strings para detalhes na
sintaxe desses campos.


Especificador de depuração
~~~~~~~~~~~~~~~~~~~~~~~~~~

Adicionado na versão 3.8.

Se um especificador de depuração — um sinal de igual ("=") — aparecer
após a expressão do campo de substituição, a f-string resultante
conterá a origem da expressão, o sinal de igual e o valor da
expressão. Isso costuma ser útil para depuração.

   >>> number = 14.3
   >>> f'{number=}'
   'number=14.3'

Espaços em branco antes, dentro e depois da expressão, bem como
espaços em branco após o sinal de igual, são significativos — eles são
mantidos no resultado.

   >>> f'{ number  -  4  = }'
   ' number  -  4  = 10.3'


Especificador de conversão
~~~~~~~~~~~~~~~~~~~~~~~~~~

Por padrão, o valor de uma expressão de campo de substituição é
convertido em uma string usando "str()":

   >>> from fractions import Fraction
   >>> one_third = Fraction(1, 3)
   >>> f'{one_third}'
   '1/3'

Quando um especificador de depuração é usado, mas nenhum especificador
de formato, a conversão padrão usa "repr()":

   >>> f'{one_third = }'
   'one_third = Fraction(1, 3)'

A conversão pode ser especificada explicitamente usando um destes
especificadores:

* "!s" para "str()"

* "!r" para "repr()"

* "!a" para "ascii()"

Por exemplo:

   >>> str(one_third)
   '1/3'
   >>> repr(one_third)
   'Fraction(1, 3)'

   >>> f'{one_third!s} is {one_third!r}'
   '1/3 is Fraction(1, 3)'

   >>> string = "¡kočka 😸!"
   >>> ascii(string)
   "'\\xa1ko\\u010dka \\U0001f638!'"

   >>> f'{string = !a}'
   "string = '\\xa1ko\\u010dka \\U0001f638!'"


Especificador de formatação
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Após a expressão ser avaliada e, possivelmente, convertida usando um
especificador de conversão explícito, ela é formatada usando a função
"format()". Se o campo de substituição incluir um *especificador de
formato* introduzido por dois pontos (":"), o especificador é passado
para "format()" como segundo argumento. O resultado de "format()" é
então usado como o valor final para o campo de substituição. Por
exemplo:

   >>> from fractions import Fraction
   >>> one_third = Fraction(1, 3)
   >>> f'{one_third:.6f}'
   '0.333333'
   >>> f'{one_third:_^+10}'
   '___+1/3___'
   >>> >>> f'{one_third!r:_^20}'
   '___Fraction(1, 3)___'
   >>> f'{one_third = :~>10}~'
   'one_third = ~~~~~~~1/3~'


literais de strings templates (t-strings)
-----------------------------------------

Uma *t-string* (formalmente um *literal de string template*) é uma
string literal que é prefixada com "t" ou "T".

Essas strings seguem a mesma sintaxe e regras de avaliação que
literais de strings formatadas, com as seguintes diferenças:

* Em vez de serem avaliados como um objeto "str", os literais de
  string template são avaliados como um objeto
  "string.templatelib.Template".

* O protocolo "format()" não é usado. Em vez disso, o especificador de
  formato e conversões (se houver alguma) são passados para um novo
  objeto "Interpolation" que é criado para cada expressão avaliada.
  Cabe ao código que processa o objeto "Template" resultante decidir
  como tratar especificadores de formato e conversões.

* Especificadores de formato contendo campos de substituição aninhados
  são executados imediatamente, antes de serem passados para o objeto
  "Interpolation". Por exemplo, uma interpolação da forma
  "{amount:.{precision}f}" vai executar a expressão interna
  "{precision}" para determinar o valor do atributo "format_spec". Se
  "precision" fosse "2", o especificador de formato resultante seria
  "'.2f'".

* Quando o sinal de igual "'='" aparece em uma expressão de
  interpolação, o texto da expressão é concatenado ao literal de
  string que antecede a interpolação relevante. Isso inclui o sinal de
  igual, e qualquer espaço em branco que o cerque. A instância de
  "Interpolation" para a expressão será criada normalmente, exceto que
  o "conversion" será definido como "r" ("repr()") por padrão. Se uma
  conversão ou especificador de formato explícito forem fornecidos,
  eles substituem esse comportamento padrão.


Formatação de string no estilo "printf"
---------------------------------------

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).O uso de literais
  de strings formatadas, a interface "str.format()" ou
  "string.Template" pode ajudar a evitar esses erros. Cada uma dessas
  alternativas oferece suas próprias vantagens e desvantagens de
  simplicidade, flexibilidade e/ou extensibilidade.

Os objetos string possuem um único operador embutido: o operador "%"
(módulo). O mesmo também é conhecido como o operador de *formatação*
ou *interpolação*. 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 *values*. O efeito é
semelhante ao uso da função "sprintf()" na linguagem C. Por exemplo:

   >>> print('%s tem %d tipos de aspas.' % ('Python', 2))
   Python tem 2 tipos de aspas.

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 como um
   "'*'" (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
   precisã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. Tipo 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:

+-----------+-----------------------------------------------------------------------+
| Sinaliza  | Significado                                                           |
| dor       |                                                                       |
|===========|=======================================================================|
| "'#'"     | A conversão de valor usará o "formulário alternativo" (conforme       |
|           | definido 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 "'-'") precederá a conversão          |
|           | (substituindo o sinalizador de "espaço").                             |
+-----------+-----------------------------------------------------------------------+

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'"        | Hexadecimal com sinal (minúsculo).                    | (2)     |
+--------------+-------------------------------------------------------+---------+
| "'X'"        | Hexadecimal com sinal (maiúsculo).                    | (2)     |
+--------------+-------------------------------------------------------+---------+
| "'e'"        | Formato exponencial de ponto flutuante (minúsculo).   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'E'"        | Formato exponencial de ponto flutuante (maiúsculo).   | (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úsculo 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úsculo se o expoente for inferior a -4 ou não   |         |
|              | inferior que a precisão, formato decimal, caso        |         |
|              | contrário.                                            |         |
+--------------+-------------------------------------------------------+---------+
| "'c'"        | Caractere ú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 em um       |         |
|              | caractere "'%'" no resultado.                         |         |
+--------------+-------------------------------------------------------+---------+

For floating-point formats, the result should be correctly rounded to
a given precision "p" of digits after the decimal point.  The rounding
mode matches that of the "round()" builtin.

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 seja 6.

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

6. Veja **PEP 237**.

Como as strings no Python possuem comprimento explícito, conversões de
"%s" não presumem que "'\0'" seja 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 protocolo buffer para acessar a memória de outros objetos binários
sem precisar fazer uma cópia.

O módulo "array" provê suporte a um 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=b'')
class bytes(source, encoding, errors='strict')

   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'ainda permite aspas "duplas" dentro'"

   * Aspas duplas: "b"ainda permite aspas 'simples' dentro""

   * Aspas triplas: "b'''3 aspas simples'''", "b"""3 aspas duplas""""

   Apenas caracteres ASCII são permitidos em literais de bytes
   (independentemente da codificação declarada no código-fonte).
   Qualquer valor binário superior a 127 deverá ser inserido em
   literais de bytes usando a sequência de escape apropriada.

   Assim como string literais, bytes literais também podem usar um
   prefixo "r" para desabilitar o processamento de sequências de
   escape. Veja Literais de string e bytes 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 embutidos 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.

      Alterado na versão 3.14: "bytes.fromhex()" agora aceita objetos
      "bytes" e *similares* ASCII como entrada.

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

   hex(*, bytes_per_sep=1)
   hex(sep, bytes_per_sep=1)

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

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

      Se você quiser tornar a string hexadecimal mais fácil de ler,
      você pode especificar um caractere separador através do
      parâmetro *sep*, que será incluído no resultado. Por padrão,
      este separador será incluído entre cada byte. Um segundo
      parâmetro opcional *bytes_per_sep* controla o espaçamento.
      Valores positivos calculam a posição do separador a partir da
      direita, valores negativos calculam a partir da esquerda.

      >>> value = b'\xf0\xf1\xf2'
      >>> value.hex('-')
      'f0-f1-f2'
      >>> value.hex('_', 2)
      'f0_f1f2'
      >>> b'UUDDLRLRAB'.hex(' ', -4)
      '55554444 4c524c52 4142'

      Adicionado na versão 3.5.

      Alterado na versão 3.8: "bytes.hex()" agora suporta os
      parâmetros opcionais *sep* e *bytes_per_sep* para inserir
      separadores entre bytes na saída hexadecimal.

Como objetos bytes são sequências de inteiros (certo parentesco 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)".


Objetos Bytearray
-----------------

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

class bytearray(source=b'')
class bytearray(source, encoding, errors='strict')

   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 sequê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 embutido 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.

      Alterado na versão 3.14: "bytearray.fromhex()" agora aceita
      objetos "bytes" e *similares* ASCII como entrada.

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

   hex(*, bytes_per_sep=1)
   hex(sep, bytes_per_sep=1)

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

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

      Adicionado na versão 3.5.

      Alterado na versão 3.8: Similar a "bytes.hex()",
      "bytearray.hex()" agora suporta os parâmetros opcionais *sep* e
      *bytes_per_sep* para inserir separadores entre bytes na saída
      hexadecimal.

   resize(size, /)

      Redimensiona "bytearray" para conter *size* bytes. *size* deve
      ser maior ou igual a 0.

      Se "bytearray" precisar ser reduzido, os bytes além de *size*
      serão truncados.

      Se "bytearray" precisar crescer, todos os novos bytes, aqueles
      além de *size*, serão definidos como bytes nulos.

      Isso equivale a:

      >>> def resize(ba, size):
      ...     if len(ba) > size:
      ...         del ba[size:]
      ...     else:
      ...         ba += b'\0' * (size - len(ba))

      Exemplos:

      >>> shrink = bytearray(b'abc')
      >>> shrink.resize(1)
      >>> (shrink, len(shrink))
      (bytearray(b'a'), 1)
      >>> grow = bytearray(b'abc')
      >>> grow.resize(5)
      >>> (grow, len(grow))
      (bytearray(b'abc\x00\x00'), 5)

      Adicionado na versão 3.14.

   take_bytes(n=None, /)

      Remove the first *n* bytes from the bytearray and return them as
      an immutable "bytes". By default (if *n* is "None"), return all
      bytes and clear the bytearray.

      If *n* is negative, index from the end and take the first
      "len()" plus *n* bytes. If *n* is out of bounds, raise
      "IndexError".

      Taking less than the full length will leave remaining bytes in
      the "bytearray", which requires a copy. If the remaining bytes
      should be discarded, use "resize()" or "del" to truncate then
      "take_bytes()" without a size.

      **Detalhes da implementação do CPython:** Taking all bytes is a
      zero-copy operation.

      Adicionado na versão 3.15: See the What's New entry for common
      code patterns which can be optimized with
      "bytearray.take_bytes()".

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 sequê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)".

Ver também:

  For detailed information on thread-safety guarantees for "bytearray"
  objects, see Thread safety for bytearray objects.


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

Ambos os tipos, bytes e objetos do tipo bytearray, aceitam as
operações de sequências comuns. Os mesmos interagem não apenas com
operandos do mesmo tipo, mas também com qualquer *objeto bytes ou
similar*. 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 presumem 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 *objeto bytes ou
   similar* ou um inteiro no intervalo de 0 a 255.

   Se *sub* estiver vazio, retorna o número de fatias vazias entre os
   caracteres, que é o comprimento do objeto bytes mais um.

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

bytes.removeprefix(prefix, /)
bytearray.removeprefix(prefix, /)

   Se os dados binários começarem com a string *prefix*, retorna
   "bytes[len(prefix):]". Caso contrário, retorna uma cópia dos dados
   binários originais:

      >>> b'TestHook'.removeprefix(b'Test')
      b'Hook'
      >>> b'BaseTestCase'.removeprefix(b'Test')
      b'BaseTestCase'

   O *prefix* pode ser qualquer *objeto bytes 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.

   Adicionado na versão 3.9.

bytes.removesuffix(suffix, /)
bytearray.removesuffix(suffix, /)

   Se os dados binários terminarem com a string *suffix* e a *suffix*
   não estiver vazia, retorna "bytes[:-len(suffix)]". Caso contrário,
   retorna uma cópia dos dados binários originais:

      >>> b'MiscTests'.removesuffix(b'Tests')
      b'Misc'
      >>> b'TmpDirMixin'.removesuffix(b'Tests')
      b'TmpDirMixin'

   O *suffix* pode ser qualquer *objeto bytes 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.

   Adicionado na versão 3.9.

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

   Retorna os bytes decodificados para uma "str".

   *encoding* tem como padrão "'utf-8'"; veja Standard Encodings para
   valores possíveis.

   *errors* controla como os erros de decodificação são tratados. Se
   "'strict'" (o padrão), uma exceção "UnicodeError" é levantada.
   Outros valores possíveis são "'ignore'", "'replace'" e qualquer
   outro nome registrado via "codecs.register_error()". Veja Error
   Handlers para detalhes.

   Por motivos de desempenho, o valor de *errors* não é verificado
   quanto à validade, a menos que um erro de decodificação realmente
   ocorra, Modo de Desenvolvimento do Python esteja ativado ou uma
   construção de depuração seja usada.

   Nota:

     Passar o argumento *encoding* para "str" permite decodificar
     qualquer objeto *objeto bytes ou similar* diretamente, sem a
     necessidade de criar um objeto "bytes" ou "bytearray" temporário.

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

   Alterado na versão 3.9: O valor do argumento *errors* agora é
   verificado em Modo de Desenvolvimento do Python e no modo de
   depuração.

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 *objeto bytes ou
   similar*.

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 *objeto bytes ou
   similar* 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 *objeto bytes ou
   similar* 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 *iterable*. Uma exceção
   "TypeError" será levantada se existirem quaisquer valores que não
   sejam *objeto bytes ou similar*, no *iterable*, 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
   *objetos bytes ou similares* e ter o mesmo comprimento.

   Adicionado 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 separador, 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 *objeto bytes ou
   similar*.

bytes.replace(old, new, /, count=-1)
bytearray.replace(old, new, /, count=-1)

   Return a copy of the sequence with all occurrences of subsequence
   *old* replaced by *new*.  If *count* is given, only the first
   *count* occurrences are replaced.  If *count* is not specified or
   "-1", then all occurrences are replaced.

   A subsequência para buscar e substituição pode ser qualquer termos
   *objeto bytes 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.

   Alterado na versão 3.15: *count* agora é suportado como um
   argumento nomeado.

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

   Retorna o índice mais alto na sequê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á retornado "-1".

   A subsequência a ser procurada poderá ser qualquer *objeto bytes ou
   similar* 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 *objeto bytes ou
   similar* 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 separador, 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 *objeto bytes ou
   similar*.

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 prefixos para pesquisar podem ser qualquer *objeto bytes 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.

   Você 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'leia este curto texto'.translate(None, b'aeiou')
      b'l st crt txt'

   Alterado na versão 3.6: *delete* agora é suportado como um
   argumento nomeado.

Os seguintes métodos de objetos bytes e bytearray tem comportamentos
padrões que presumem 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=b' ', /)
bytearray.center(width, fillbyte=b' ', /)

   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=b' ', /)
bytearray.ljust(width, fillbyte=b' ', /)

   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(bytes=None, /)
bytearray.lstrip(bytes=None, /)

   Retorna uma cópia da sequência com bytes iniciais especificados
   removidos. O argumento *bytes* é uma sequência binária que
   especifica o conjunto de valores de bytes a serem removidos. Se for
   omitido ou se for "None", o argumento *bytes* será considerado como
   espaço em branco ASCII por padrão para a remoção. O argumento
   *bytes* não é um prefixo; ao invés disso, todas as combinações dos
   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
   *objeto bytes ou similar*. Consulte "removeprefix()" para um método
   que removerá uma única string de prefixo em vez de todo um conjunto
   de caracteres. Por exemplo:

      >>> b'Arthur: three!'.lstrip(b'Arthur: ')
      b'ee!'
      >>> b'Arthur: three!'.removeprefix(b'Arthur: ')
      b'three!'

   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=b' ', /)
bytearray.rjust(width, fillbyte=b' ', /)

   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(bytes=None, /)
bytearray.rstrip(bytes=None, /)

   Retorna uma cópia da sequência com bytes finais especificados
   removidos. O argumento *bytes* é uma sequência binária que
   especifica o conjunto de valores de bytes a serem removidos. Se for
   omitido ou se for "None", o argumento *bytes* será considerado como
   espaço em branco ASCII por padrão para a remoção. O argumento
   *bytes* não é um sufixo; ao invés disso, todas as combinações dos
   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
   *objeto bytes ou similar*. Consulte "removesuffix()" para um método
   que removerá uma única string de sufixo em vez de todo um conjunto
   de caracteres. Por exemplo:

      >>> b'Monty Python'.rstrip(b' Python')
      b'M'
      >>> b'Monty Python'.removesuffix(b' Python')
      b'Monty'

   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
   como um único delimitador. 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 *objeto bytes ou similar*.

   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'']
      >>> b'1<>2<>3<4'.split(b'<>')
      [b'1', b'2', b'3<4']

   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(bytes=None, /)
bytearray.strip(bytes=None, /)

   Retorna uma cópia da sequência com bytes iniciais e finais
   especificados removidos. O argumento *bytes* é uma sequência
   binária que especifica o conjunto de valores de bytes a serem
   removidos. Se for omitido ou se for "None", o argumento *bytes*
   será considerado como espaço em branco ASCII por padrão para a
   remoção. O argumento *bytes* não é um prefixo ou sufixo; ao invés
   disso, todas as combinações dos 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 bytes 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 presumem 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* alteram os argumentos, 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 é
   redefinida 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.

   Adicionado 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 na lista resultante 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 código 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
   contraçõ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 como um
   "'*'" (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
   precisã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. Tipo 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:

+-----------+-----------------------------------------------------------------------+
| Sinaliza  | Significado                                                           |
| dor       |                                                                       |
|===========|=======================================================================|
| "'#'"     | A conversão de valor usará o "formulário alternativo" (conforme       |
|           | definido 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 "'-'") precederá a conversão          |
|           | (substituindo o sinalizador de "espaço").                             |
+-----------+-----------------------------------------------------------------------+

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'"        | Hexadecimal com sinal (minúsculo).                    | (2)     |
+--------------+-------------------------------------------------------+---------+
| "'X'"        | Hexadecimal com sinal (maiúsculo).                    | (2)     |
+--------------+-------------------------------------------------------+---------+
| "'e'"        | Formato exponencial de ponto flutuante (minúsculo).   | (3)     |
+--------------+-------------------------------------------------------+---------+
| "'E'"        | Formato exponencial de ponto flutuante (maiúsculo).   | (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úsculo 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úsculo 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 em 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 seja 6.

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

6. "b'%s'" está descontinuado, 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

Adicionado na versão 3.5.


Visões de memória
-----------------

Objetos "memoryview" permitem que código Python acesse os dados
internos de um objeto que implemente o protocolo buffer sem copiá-lo.

class memoryview(object)

   Cria uma "memoryview" que referencia *object*. *object* deve ter
   suporte ao protocolo de buffer. Objetos embutidos com suporte ao
   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 *object*. 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)" is equal to the length of "tolist()", which is the
   nested list representation of the view. If "view.ndim = 1", this is
   equal to the number of elements in the view.

   Alterado na versão 3.12: Se "view.ndim == 0", "len(view)" agora
   levanta "TypeError" em vez de retornar 1.

   O atributo "itemsize" vai lhe dar um número de bytes em um único
   elemento.

   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. Visões de memória unidimensionais podem ser indexadas por
   um inteiro ou por uma tupla contendo um inteiro. Visões de memória
   multidimensionais podem ser indexadas por tuplas de exatamente
   *ndim* inteiros, onde *ndim* é o número de dimensões. Visões de
   memória zero-dimensionais podem ser indexadas por 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')

   Visões de memória unidimensionais de tipos *hasheáveis* (somente
   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: Visões de memória unidimensionais agora
   podem ser fatiadas. Visões de memória 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.

   Alterado na versão 3.14: memoryview é agora um *tipo genérico*.

   "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(order='C')

      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".

      Adicionado na versão 3.8: *order* pode ser {'C', 'F', 'A'}.
      Quando *order* é 'C' ou 'F', os dados do array original são
      convertidos para a ordem de C our Fortran. Para views contígua,
      'A' retorna uma cópia exata da memória física. Em particular,
      ordem de Fortran em memória é preservada. Para views não
      contígua, os dados são convertidos primeiro para C. *order=None*
      é o mesmo que *order='C'*.

   hex(*, bytes_per_sep=1)
   hex(sep, bytes_per_sep=1)

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

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

      Adicionado na versão 3.5.

      Alterado na versão 3.8: Similar a "bytes.hex()",
      "memoryview.hex()" agora suporta os parâmetros opcionais *sep* e
      *bytes_per_sep* para inserir separadores entre bytes na saída
      hexadecimal.

   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.

   toreadonly()

      Retorna uma versão somente leitura do objeto memoryview. O
      objeto memoryview original não é alterado.

         >>> m = memoryview(bytearray(b'abc'))
         >>> mm = m.toreadonly()
         >>> mm.tolist()
         [97, 98, 99]
         >>> mm[0] = 42
         Traceback (most recent call last):
           File "<stdin>", line 1, in <module>
         TypeError: cannot modify read-only memory
         >>> m[0] = 43
         >>> mm.tolist()
         [43, 98, 99]

      Adicionado na versão 3.8.

   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

      Adicionado na versão 3.2.

   cast(format, /)
   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 visão 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. Observe que todos os
      comprimentos de bytes podem depender do sistema operacional.

      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):
           ...
         TypeError: memoryview: invalid type 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]]

      Adicionado 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.

   count(value, /)

      Conta o número de ocorrências de *value*.

      Adicionado na versão 3.14.

   index(value, start=0, stop=sys.maxsize, /)

      Retorna o índice da primeira ocorrência de *value* (no índice
      *index* ou depois dele e antes do índice *stop*).

      Levanta uma exceção "ValueError" se *value* não puder ser
      encontrado.

      Adicionado na versão 3.14.

   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

      Adicionado 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

      Adicionado 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 é *contígua* C.

      Adicionado na versão 3.3.

   f_contiguous

      Um bool que indica se a memória é *contígua* Fortran.

      Adicionado na versão 3.3.

   contiguous

      Um bool que indica se a memória é *contígua*.

      Adicionado na versão 3.3.

For information on the thread safety of "memoryview" objects in the
*free-threaded build*, see Thread safety for memoryview objects.


Tipo conjuntos --- "set", "frozenset"
=====================================

Um objeto *conjunto* é 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 contêineres veja as classes embutidas "dict", "list" e
"tuple", e o módulo "collections".)

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

Existem atualmente dois tipos de conjuntos 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 conjunto. 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 conjunto.

Conjuntos 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 conjunto
   devem ser *hasheáveis*. Para representar conjuntos de sets, os sets
   internos devem ser objetos "frozenset". Se *iterable* não for
   especificado, um novo conjunto vazio é retornado.

Conjuntos podem ser criados de várias formas:

* Usar uma lista de elementos separados por vírgulas entre chaves:
  "{'jack', 'sjoerd'}"

* Usar uma compreensão de conjunto: "{c for c in 'abracadabra' if c
  not in 'abc'}"

* Usar o construtor da classe: "set()", "set('foobar')", "set(['a',
  'b', 'foo'])"

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*.

frozenset.isdisjoint(other, /)
set.isdisjoint(other, /)

   Retorna "True" se o conjunto não tem elementos em comum com
   *other*. Conjuntos são disjuntos se e somente se a sua interseção é
   o conjunto vazio.

frozenset.issubset(other, /)
set.issubset(other, /)

set <= other

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

set < other

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

frozenset.issuperset(other, /)
set.issuperset(other, /)

set >= other

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

set > other

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

frozenset.union(*others)
set.union(*others)

set | other | ...

   Retorna um novo conjunto com elementos do conjunto e de todos os
   outros.

frozenset.intersection(*others)
set.intersection(*others)

set & other & ...

   Retorna um novo conjunto com elementos comuns do conjunto e de
   todos os outros.

frozenset.difference(*others)
set.difference(*others)

set - other - ...

   Retorna um novo conjunto com elementos no conjunto que não estão
   nos outros.

frozenset.symmetric_difference(other, /)
set.symmetric_difference(other, /)

set ^ other

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

frozenset.copy()
set.copy()

   Retorna uma cópia rasa do conjunto.

Observe que, as versões não-operador dos métodos "union()",
"intersection()", "difference()", "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
suscetíveis a erros como "set('abc') & 'cbs'" e favorece a forma mais
legível "set('abc').intersection('cbs')".

Tanto "set" quanto "frozenset" aceitam comparações entre conjuntos.
Dois conjuntos são iguais se e somente se cada elemento de um está
contido no outro (cada um é um subconjunto do outro). Um conjunto é
menor que outro se, e somente se, o primeiro conjunto é um subconjunto
adequado do segundo (é um subconjunto, mas não é igual). Um conjunto é
maior que outro conjunto se, e somente se, o primeiro conjunto é um
superconjunto próprio do segundo conjunto (é 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 subconjunto e comparações de igualdade não generalizam para a função
de ordenamento total. Por exemplo, quaisquer dois conjuntos deslocados
não vazios, não são iguais e não são subconjuntos um do outro, então
*todos* os seguintes retornam "False": "a<b", "a==b" ou "a>b".

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

Elementos de conjuntos, 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":

set.update(*others)

set |= other | ...

   Atualiza o conjunto, adicionando elementos dos outros.

set.intersection_update(*others)

set &= other & ...

   Atualiza o conjunto, mantendo somente elementos encontrados nele e
   em outros.

set.difference_update(*others)

set -= other | ...

   Atualiza o conjunto, removendo elementos encontrados em outros.

set.symmetric_difference_update(other, /)

set ^= other

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

set.add(elem, /)

   Adiciona o elemento *elem* ao conjunto.

set.remove(elem, /)

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

set.discard(elem, /)

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

set.pop()

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

set.clear()

   Remove todos os elementos do conjunto.

Perceba, as versões sem operador 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 conjunto. Para suportar pesquisas
por um frozenset equivalente, um frozenset temporário é criado a
partir de *elem*.

Ver também:

  For detailed information on thread-safety guarantees for "set"
  objects, see Thread safety for set objects.


Mapping types --- "dict", "frozendict"
======================================

A *mapping* object maps *hashable* values to arbitrary objects. There
are currently two standard mapping types, the *dictionary* and
"frozendict". (For other containers see the built-in "list", "set",
and "tuple" classes, and the "collections" module.)

As chaves de um dicionário são *quase* valores arbitrários. Valores
que não são *hasheáveis*, ou seja, valores contendo listas,
dicionários ou outros tipos mutáveis (que são comparados por valor e
não por identidade de objeto) não podem ser usados como chaves.
Valores que comparam iguais (como "1", "1.0" e "True") podem ser
usados alternadamente para indexar a mesma entrada do dicionário.

class dict(**kwargs)
class dict(mapping, /, **kwargs)
class dict(iterable, /, **kwargs)

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

   Os dicionários podem ser criados de várias formas:

   * Usar uma lista de pares "key: value" separados por vírgula com
     chaves: "{'jack': 4098, 'sjoerd': 4127}" ou "{4098: 'jack', 4127:
     'sjoerd'}"

   * Usar uma compreensão de dicionário: "{}", "{x: x ** 2 for x in
     range(10)}"

   * Usar o construtor de tipo: "dict()", "dict([('foo', 100), ('bar',
     200)])", "dict(foo=100, bar=200)"

   Se nenhum argumento posicional é fornecido, um dicionário vazio é
   criado. Se um argumento posicional é fornecido e ele define um
   método "keys()", um dicionário é criado chamando "__getitem__()" no
   argumento com cada chave retornada pelo método. 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
   elementos. O primeiro elemento de cada item torna-se a chave no
   novo dicionário, e o segundo elemento, 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.

   Dicionários são iguais se e somente se eles os mesmos pares "(key,
   value)" (independente de ordem). Comparações de ordem ('<', '<=',
   '>=', '>') levantam "TypeError". Para ilustrar a criação e
   igualdade de dicionários, os exemplos a seguir 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})
      >>> f = dict({'one': 1, 'three': 3}, two=2)
      >>> a == b == c == d == e == f
      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.

   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 = {"um": 1, "dois": 2, "três": 3, "quatro": 4}
      >>> d
      {'um': 1, 'dois': 2, 'três': 3, 'quatro': 4}
      >>> list(d)
      ['um', 'dois', 'três', 'quatro']
      >>> list(d.values())
      [1, 2, 3, 4]
      >>> d["um"] = 42
      >>> d
      {'um': 42, 'dois': 2, 'três': 3, 'quatro': 4}
      >>> del d["dois"]
      >>> d["dois"] = None
      >>> d
      {'um': 42, 'três': 3, 'quatro': 4, 'dois': 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.

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

   list(d)

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

   len(d)

      Retorna o número de itens 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étodos
      invocam "__missing__()". Se "__missing__()" não for definido,
      então "KeyError" é levantada. "__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]" do *d*. Levanta uma exceção "KeyError" se *key*
      não estiver no mapeamento.

   key in d

      Retorna "True" se *d* tiver uma chave *key*, caso contrário
      "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=None, /)

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

      "fromkeys()" é um método de classe que retorna um novo
      dicionário. *value* tem como valor padrão "None". Todos os
      valores referem-se a apenas uma única instância, então
      geralmente não faz sentido que *value* seja um objeto mutável
      tal como uma lista vazia. Para obter valores distintos, use uma
      compreensão de dicionário ao invés.

   get(key, default=None, /)

      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 itens 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, /)
   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 conjunto. 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.

   reversed(d)

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

      Adicionado na versão 3.8.

   setdefault(key, default=None, /)

      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(**kwargs)
   update(mapping, /, **kwargs)
   update(iterable, /, **kwargs)

      Atualiza o dicionário com os pares chave/valor de *mapping* ou
      *iterable* e *kwargs*, sobrescrevendo chaves existentes. Retorna
      "None".

      "update()" aceita ou outro objeto com um método "keys()" (em
      cada caso "__getitem__()" é chamado com cada chave retornada
      pelo método) 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

   d | other

      Cria um novo dicionário com as chaves e os valores mesclados de
      *d* e *other*, que devem ser dicionários. Os valores de *other*
      têm prioridade quando *d* e *other* compartilham chaves.

      Adicionado na versão 3.9.

   d |= other

      Atualiza o dicionário *d* com chaves e valores de *other*, que
      podem ser a *mapeamento* ou um *iterável* dos pares chave/valor.
      Os valores de *other* têm prioridade quando *d* e *other*
      compartilham chaves.

      Adicionado na versão 3.9.

   Dicionários e visões de dicionários são reversíveis.

      >>> d = {"um": 1, "dois": 2, "três": 3, "quatro": 4}
      >>> d
      {'um': 1, 'dois': 2, 'três': 3, 'quatro': 4}
      >>> list(reversed(d))
      ['quatro', 'três', 'dois', 'um']
      >>> list(reversed(d.values()))
      [4, 3, 2, 1]
      >>> list(reversed(d.items()))
      [('quatro', 4), ('três', 3), ('dois', 2), ('um', 1)]

   Alterado na versão 3.8: Dicionários agora são reversíveis.

   Ver também:

     "frozendict" and "types.MappingProxyType" can be used to create a
     read-only view of a "dict".

Ver também:

  For detailed information on thread-safety guarantees for "dict"
  objects, see Thread safety for dict objects.


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 itens
   (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 itens do
   dicionário subjacente (no último caso, *x* deve ser uma tupla de
   "(key, value)").

reversed(dictview)

   Retorna um iterador reverso sobre as chaves, valores ou itens do
   dicionário. A visão será iterada na ordem reversa de inserção.

   Alterado na versão 3.8: Visões de dicionário agora são reversíveis.

dictview.mapping

   Retorna um "types.MappingProxyType" que envolve o dicionário
   original ao qual a visão se refere.

   Adicionado na versão 3.10.

Visões chave são similar a conjunto, como suas entradas são únicas e
*hasheáveis*. As visões de itens também têm operações semelhantes a
conjuntos, uma vez que os pares (chave, valor) são únicos e as chaves
são hasheáveis. Se todos os valores em uma visão de itens também forem
hasheáveis, a visão de itens poderá interoperar com outros conjuntos.
(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
"^"). Ao usar operadores de conjunto, visões de conjunto ou similares
aceitam qualquer iterável como outro operando, ao contrário de
conjuntos que aceitam apenas conjuntos como entrada.

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

   >>> # a iteração sobre chaves e valores é feita na mesma ordem (ordem de inserção)
   >>> list(keys)
   ['eggs', 'sausage', 'bacon', 'spam']
   >>> list(values)
   [2, 1, 1, 500]

   >>> # objetos de visualização são dinâmicos e refletem mudanças no dicionário
   >>> del dishes['eggs']
   >>> del dishes['sausage']
   >>> list(keys)
   ['bacon', 'spam']

   >>> # operações de conjunto
   >>> keys & {'eggs', 'bacon', 'salad'}
   {'bacon'}
   >>> keys ^ {'sausage', 'juice'} == {'juice', 'sausage', 'bacon', 'spam'}
   True
   >>> keys | ['juice', 'juice', 'juice'] == {'bacon', 'spam', 'juice'}
   True

   >>> # recupera um proxy somente de leitura para o dicionário original
   >>> values.mapping
   mappingproxy({'bacon': 1, 'spam': 500})
   >>> values.mapping['spam']
   500


Frozen dictionaries
-------------------

class frozendict(**kwargs)
class frozendict(mapping, /, **kwargs)
class frozendict(iterable, /, **kwargs)

   Return a new frozen dictionary initialized from an optional
   positional argument and a possibly empty set of keyword arguments.

   A "frozendict" has a similar API to the "dict" API, with the
   following differences:

   * "dict" has more methods than "frozendict":

        * "__delitem__()"

        * "__setitem__()"

        * "clear()"

        * "pop()"

        * "popitem()"

        * "setdefault()"

        * "update()"

   * A "frozendict" can be hashed with "hash(frozendict)" if all keys
     and values can be hashed.

   * "frozendict |= other" does not modify the "frozendict" in-place
     but creates a new frozen dictionary.

   "frozendict" is not a "dict" subclass but inherits directly from
   "object".

   Adicionado na versão 3.15.


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" das instruções "with" usando este gerenciador de contexto.

   Um exemplo 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 sinalizador
   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 traceback (situação da pilha de execução). Caso
   contrário, os três argumentos são "None".

   Returning a true value from this method will cause the "with"
   statement to suppress the exception and continue execution with the
   statement immediately following the "with" statement. Otherwise the
   exception continues propagating after this method has finished
   executing.

   If this method raises an exception while handling an earlier
   exception from the "with" block, the new exception is raised, and
   the original exception is stored in its "__context__" attribute.

   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 gerenciadores de contexto para suportar
facilmente sincronização de threads, solicita o fechamento de arquivos
ou outros objetos, e manipula de forma simples o contexto ativo de
aritmética decimal. Os tipos especificados não são tratados de forma
especial além da sua implementação e do protocolo do gerenciador de
contexto. Veja o módulo "contextlib" para alguns exemplos.

Os *gerador*es do Python e o decorador "contextlib.contextmanager"
fornecem uma maneira conveniente de implementar esses protocolos. Se
uma função geradora for decorada com o decorador
"contextlib.contextmanager", ela retornará um gerenciador de contexto
implementando os métodos necessários "__enter__()" e "__exit__()", em
vez de o iterador produzido por uma função geradora não decorada.

Observe que não existe nenhum slot específico para qualquer um desses
métodos na estrutura de tipos para objetos Python na API 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.


Tipos de anotação de tipo --- Apelido genérico, União
=====================================================

Os principais tipos embutidos para *anotações de tipo* são Apelido
genérico e União.


Tipo Generic Alias
------------------

Objetos "GenericAlias" são geralmente criados subscrevendo uma classe.
Eles são mais usados com classes contêineres, como "list" ou "dict".
Por exemplo, "list[int]" é um objeto "GenericAlias" criado pela
subscrição da classe "list" com o argumento "int". Objetos
"GenericAlias" são destinados principalmente para uso com *anotações
de tipo*.

Nota:

  Geralmente só é possível subscrever uma classe se a classe
  implementar o método especial "__class_getitem__()".

Um objeto "GenericAlias" atua como um proxy para um *tipo genérico*,
implementando *genéricos parametrizados*.

Para uma classe contêiner, o(s) argumento(s) fornecido(s) para uma
subscrição da classe pode indicar o(s) tipo(s) dos elementos que um
objeto contém. Por exemplo, "set[bytes]" pode ser usado em anotações
de tipo para significar um "set" em que todos os elementos são do tipo
"bytes".

Para uma classe que define "__class_getitem__()", mas não é um
contêiner, o(s) argumento(s) fornecido(s) para uma subscrição da
classe geralmente indicará o(s) tipo(s) de retorno de um ou mais
métodos definidos em um objeto. Por exemplo, "expressões regulares"
podem ser usadas tanto no tipo de dados "str" quanto no tipo de dados
"bytes":

* Se "x = re.search('foo', 'foo')", "x" será um objeto re.Match onde
  os valores de retorno de "x.group(0)" e "x[0]" serão ambos do tipo
  "str". Podemos representar este tipo de objeto em anotações de tipo
  com o "GenericAlias" "re.Match[str]".

* Se "y = re.search(b'bar', b'bar')" (observe o "b" para "bytes"), "y"
  também será uma instância de "re.Match", mas os valores de retorno
  de "y.group(0)" e "y[0]" serão ambos do tipo "bytes". Em anotações
  de tipo, representaríamos esta variedade de objetos re.Match com
  "re.Match[bytes]".

"GenericAlias" objects are instances of the class
"types.GenericAlias", which can also be used to create "GenericAlias"
objects directly. Specializations of user-defined generic classes may
not be instances of "types.GenericAlias", but they provide similar
functionality.

T[X, Y, ...]

   Cria um "GenericAlias" representando um tipo "T" parametrizado por
   tipos *X*, *Y* e mais, dependendo do "T" usados. Por exemplo, uma
   função esperando uma "list" contendo elementos "float":

      def average(values: list[float]) -> float:
          return sum(values) / len(values)

   Outro exemplo para *mapeamento* de objetos, usando um "dict", o
   qual é um tipo genérico esperando 2 tipos de parâmetros
   representando o tipo da chave e o tipo do valor. Neste exemplo, a
   função espera um "dict" com chaves do tipo "str" e valores do tipo
   "int":

      def send_post_request(url: str, body: dict[str, int]) -> None:
          ...

As funções embutidas "isinstance()" e "issubclass()" não aceitam tipos
"GenericAlias" para o seu segundo argumento:

   >>> isinstance([1, 2], list[str])
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: isinstance() argument 2 cannot be a parameterized generic

O runtime Python não obriga *anotações de tipo*. Isso se aplica a
tipos genéricos e seus parâmetros tipados. Ao criar um objeto
contêiner a partir de um "GenericAlias", os elementos no contêiner não
são verificados pelo seu tipo. Por exemplo, o seguinte código é
desencorajado, mas irá executar sem erros:

   >>> t = list[str]
   >>> t([1, 2, 3])
   [1, 2, 3]

Além disso, genéricos parametrizados removem parâmetros tipados
durante a criação do objeto:

   >>> t = list[str]
   >>> type(t)
   <class 'types.GenericAlias'>

   >>> l = t()
   >>> type(l)
   <class 'list'>

Chamar "repr()" ou "str()" sobre um genérico mostra o tipo
parametrizado:

   >>> repr(list[int])
   'list[int]'

   >>> str(list[int])
   'list[int]'

O método "__getitem__()" de contêineres genéricos irá levantar uma
exceção para não permitir erros como "dict[str][str]":

   >>> dict[str][str]
   Traceback (most recent call last):
     ...
   TypeError: dict[str] is not a generic class

Entretanto, tais expressões são válidas quando type variáveis são
usadas. O índice deve ter tantos elementos quantos forem os itens de
variável de tipo no objeto "GenericAlias" "__args__".

   >>> from typing import TypeVar
   >>> Y = TypeVar('Y')
   >>> dict[str, Y][int]
   dict[str, int]


Classes genéricas padrão
~~~~~~~~~~~~~~~~~~~~~~~~

As seguintes classes de biblioteca padrão oferecem suporte a genéricos
parametrizados. Esta lista não é exaustiva.

* "tuple"

* "list"

* "dict"

* "set"

* "frozendict"

* "frozenset"

* "type"

* "asyncio.Future"

* "asyncio.Task"

* "collections.deque"

* "collections.defaultdict"

* "collections.OrderedDict"

* "collections.Counter"

* "collections.ChainMap"

* "collections.abc.Awaitable"

* "collections.abc.Coroutine"

* "collections.abc.AsyncIterable"

* "collections.abc.AsyncIterator"

* "collections.abc.AsyncGenerator"

* "collections.abc.Iterable"

* "collections.abc.Iterator"

* "collections.abc.Generator"

* "collections.abc.Reversible"

* "collections.abc.Container"

* "collections.abc.Collection"

* "collections.abc.Callable"

* "collections.abc.Set"

* "collections.abc.MutableSet"

* "collections.abc.Mapping"

* "collections.abc.MutableMapping"

* "collections.abc.Sequence"

* "collections.abc.MutableSequence"

* "collections.abc.ByteString"

* "collections.abc.MappingView"

* "collections.abc.KeysView"

* "collections.abc.ItemsView"

* "collections.abc.ValuesView"

* "contextlib.AbstractContextManager"

* "contextlib.AbstractAsyncContextManager"

* "dataclasses.Field"

* "functools.cached_property"

* "functools.partialmethod"

* "os.PathLike"

* "queue.LifoQueue"

* "queue.Queue"

* "queue.PriorityQueue"

* "queue.SimpleQueue"

* re.Pattern

* re.Match

* "shelve.BsdDbShelf"

* "shelve.DbfilenameShelf"

* "shelve.Shelf"

* "types.MappingProxyType"

* "weakref.WeakKeyDictionary"

* "weakref.WeakMethod"

* "weakref.WeakSet"

* "weakref.WeakValueDictionary"


Atributos especiais de objetos "GenericAlias"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Todos os genéricos parametrizados implementam atributos especiais
somente leitura.

genericalias.__origin__

   Este atributo aponta para a classe genérica não parametrizada:

      >>> list[int].__origin__
      <class 'list'>

genericalias.__args__

   Este atributo é uma "tuple" (possivelmente de comprimento 1) de
   tipos genéricos passado para o método "__class_getitem__()"
   original da classe genérica:

      >>> dict[str, list[int]].__args__
      (<class 'str'>, list[int])

genericalias.__parameters__

   O atributo é uma tupla computada preguiçosamente (possivelmente
   vazia) de variáveis de tipo único encontradas em "__args__":

      >>> from typing import TypeVar

      >>> T = TypeVar('T')
      >>> list[T].__parameters__
      (~T,)

   Nota:

     Um objeto "GenericAlias" com os parâmetros "typing.ParamSpec"
     pode não ter "__parameters__" correto após a substituição porque
     "typing.ParamSpec" se destina principalmente à verificação de
     tipo estático.

genericalias.__unpacked__

   Um booleano que é true se o apelido foi desempacotado usando o
   operador "*" (consulte "TypeVarTuple").

   Adicionado na versão 3.11.

Ver também:

  **PEP 484** - Dicas de tipo
     Apresentando a estrutura do Python para anotações de tipo.

  **PEP 585** - Sugestão de tipo para Genéricos em coleções padrão
     Apresentando a capacidade de parametrizar nativamente as classes
     da biblioteca padrão, desde que implementem o método de classe
     especial "__class_getitem__()".

  Genéricos, genéricos definidos pelo usuário e "typing.Generic"
     Documentação sobre como implementar classes genéricas que podem
     ser parametrizadas em tempo de execução e compreendidas por
     verificadores de tipo estático.

Adicionado na versão 3.9.


Tipo União
----------

Um objeto união contém o valor da operação "|" (bit a bit ou) em
vários objetos tipo. Esses tipos são destinados principalmente para
*anotações de tipos*. A expressão de tipo de união habilita a sintaxe
de sugestão de tipo mais limpo em comparação com subscrever
"typing.Union".

X | Y | ...

   Define um objeto união que contém os tipos *X*, *Y* e assim por
   diante. "X | Y" significa X ou Y. É equivalente a "typing.Union[X,
   Y]". Por exemplo, a seguinte função espera um argumento do tipo
   "int" ou "float":

      def square(number: int | float) -> int | float:
          return number ** 2

   Nota:

     O operando "|" não pode ser usado em tempo de execução para
     definir uniões onde um ou mais membros são uma referência direta.
     Por exemplo, "int | "Foo"", onde ""Foo"" é uma referência a uma
     classe ainda não definida, falhará em tempo de execução. Para
     uniões que incluem referências futuras, apresente a expressão
     inteira como uma string, por exemplo. ""int | Foo"".

union_object == other

   Os objetos união podem ser testados quanto à igualdade com outros
   objetos união. Detalhes:

   * Uniões de uniões são achatadas:

        (int | str) | float == int | str | float

   * Tipos redundantes são removidos:

        int | str | int == int | str

   * Ao comparar uniões, a ordem é ignorada:

        int | str == str | int

   * Cria instâncias de "typing.Union":

        int | str == typing.Union[int, str]
        type(int | str) is typing.Union

   * Tipos opcionais podem ser escritos como uma união com "None":

        str | None == typing.Optional[str]

isinstance(obj, union_object)

issubclass(obj, union_object)

   Chamadas para "isinstance()" e "issubclass()" também são suportados
   com um objeto união:

      >>> isinstance("", int | str)
      True

   No entanto, genéricos parametrizados em objetos de união não podem
   ser verificados:

      >>> isinstance(1, int | list[int])  # cálculo em curto-circuito
      True
      >>> isinstance([1], int | list[int])
      Traceback (most recent call last):
        ...
      TypeError: isinstance() argument 2 cannot be a parameterized generic

O tipo exposto ao usuário para o objeto união pode ser acessado a
partir de "typing.Union" e usado por verificações de "isinstance()":

   >>> import typing
   >>> isinstance(int | str, typing.Union)
   True
   >>> typing.Union()
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: cannot create 'typing.Union' instances

Nota:

  O método "__or__()" para objetos de tipo foi adicionado para
  suportar a sintaxe "X | Y". Se uma metaclasse implementa "__or__()",
  a União pode substituí-la:

     >>> class M(type):
     ...     def __or__(self, other):
     ...         return "Hello"
     ...
     >>> class C(metaclass=M):
     ...     pass
     ...
     >>> C | int
     'Hello'
     >>> int | C
     int | C

Ver também:

  **PEP 604** -- PEP propondo a sintaxe "X | Y" e o tipo União.

Adicionado na versão 3.10.

Alterado na versão 3.14: Objetos Union agora são instâncias de
"typing.Union". Anteriormente, eram instâncias de "types.UnionType",
que continua sendo um apelido para "typing.Union".


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.name", onde *m* é um módulo e *name* 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 função são criados através da definição de funções. A única
operação que pode ser feita em um objeto função é chamá-la: "func
(lista-de-argumentos)".

Existem na verdade duas possibilidades de objetos 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ção Definições de função para mais 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 os implementam.

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 com *método vinculado* (também chamado de método
de instância). Quando chamado, ele irá adicionar o argumento "self"
para a lista de argumentos. Métodos vinculados 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étodo na verdade são armazenados no objeto função subjacente
("method.__func__"), definir atributos de método 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'  # proibido atribuir diretamente no método
   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 Métodos de instância para mais informações.


Objetos código
--------------

Objetos 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 função porque eles não contém uma
referência para os seus ambientes de execução global. Objetos código
são retornados pela função embutida "compile()" e podem ser extraídos
de objetos função através do seu atributo "__code__". Veja também o
módulo "code".

Acessar "__code__" levanta um evento de auditoria "object.__getattr__"
com os argumentos "obj" e ""__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 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 nulo
-------------

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

Ele é escrito como "None".


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

Este objeto é comumente usado para indicar que algo foi omitido. Ela
não suporta operações especiais. Existe exatamente um objeto ellipsis,
nomeado "Ellipsis" (um nome embutido). "type(Ellipsis)()" produz o
singleton "Ellipsis".

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

No uso típico, "..." como o objeto "Ellipsis" aparece em alguns
lugares diferentes, por exemplo:

* Em anotações de tipo, como argumentos chamáveis ou elementos de
  tupla.

* Como o corpo de uma função em vez de uma instrução pass.

* Em bibliotecas de terceiros, como slicing e striding do Numpy.

Python também usa três pontos de maneiras que não são objetos
"Ellipsis", por exemplo:

* "ELLIPSIS" do doctest, como um padrão para conteúdo ausente.

* O prompt Python padrão do console *interativo* quando a entrada
  parcial está incompleta.

Por fim, a documentação do Python geralmente usa três pontos no uso
convencional do inglês para indicar conteúdo omitido, mesmo em
exemplos de código que também os usam como "Ellipsis".


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 o mesmo
valor.

Está escrito como "NotImplemented".


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

Veja A hierarquia de tipos padrão para esta informação. Descreve
objetos de quadro de pilha, objetos traceback (situação da pilha de
execução), e objetos fatia.


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()".

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.

   Adicionado na versão 3.3.

definition.__module__

   O nome do módulo no qual uma classe ou função foi definida.

definition.__doc__

   A string de documentação de uma classe ou função, ou "None" se não
   definida.

definition.__type_params__

   Os parâmetros de tipo de classes genéricas, funções e apelidos de
   tipo. Para classes e funções que não são genéricas, isso será uma
   tupla vazia.

   Adicionado na versão 3.12.


Limitação de comprimento de string na conversão para inteiro
============================================================

CPython tem um limite global para conversão entre "int" e "str" para
mitigar ataques de negação de serviço. Esse limite *somente* se aplica
a bases numéricas decimais ou outras que não sejam potência de dois.
As conversões hexadecimais, octais e binárias são ilimitadas. O limite
pode ser configurado.

O tipo "int" no CPython é um número de comprimento arbitrário
armazenado em formato binário (comumente conhecido como "bignum"). Não
existe nenhum algoritmo que possa converter uma string em um inteiro
binário ou um inteiro binário em uma string em tempo linear, *a menos
que* a base seja uma potência de 2. Mesmo os algoritmos mais
conhecidos para a base 10 têm complexidade subquadrática. Converter um
valor grande como "int('1' * 500_000)" pode levar mais de um segundo
em uma CPU rápida.

Limitar o tamanho da conversão oferece uma maneira prática de evitar
**CVE 2020-10735**.

O limite é aplicado ao número de caracteres de dígitos na string de
entrada ou saída quando um algoritmo de conversão não linear estiver
envolvido. Sublinhados e o sinal não são contados para o limite.

Quando uma operação excede o limite, uma exceção "ValueError" é
levantada:

   >>> import sys
   >>> sys.set_int_max_str_digits(4300)  # Illustrativo, este é o padrão.
   >>> _ = int('2' * 5432)
   Traceback (most recent call last):
   ...
   ValueError: Exceeds the limit (4300 digits) 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 digits) for integer string conversion; 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  # Conversão envolvendo hexadecimais é ilimitada.

O limite padrão é de 4300 dígitos conforme fornecido em
"sys.int_info.default_max_str_digits". O limite mínimo que pode ser
configurado é de 640 dígitos conforme fornecido em
"sys.int_info.str_digits_check_threshold".

Verificação:

   >>> 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')
   ...

Adicionado na versão 3.11.


APIs afetadas
-------------

A limitação só se aplica a conversões potencialmente lentas entre
"int" e "str" ou "bytes":

* "int(string)" com padrão sendo base 10.

* "int(string, base)" para todas as bases que não são uma potência de
  2.

* "str(integer)".

* "repr(integer)".

* qualquer outra conversão de string para base 10 como, por exemplo,
  "f"{integer}"", ""{}".format(integer)" ou "b"%d" % integer".

As limitações não se aplicam a funções com um algoritmo linear:

* "int(string, base)" com base 2, 4, 8, 16 ou 32.

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

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

* Minilinguagem de especificação de formato para números hexa, octal e
  binários

* "str" para "float".

* "str" para "decimal.Decimal".


Configurando o limiter
----------------------

Antes de iniciar o Python, você pode usar uma variável de ambiente ou
um sinalizador de linha de comando do interpretador para configurar o
limite:

* "PYTHONINTMAXSTRDIGITS", por exemplo "PYTHONINTMAXSTRDIGITS=640
  python3" para definir o limite para 640 ou "PYTHONINTMAXSTRDIGITS=0
  python3" para desabilitar a limitação.

* "-X int_max_str_digits", por exemplo "python3 -X
  int_max_str_digits=640"

* "sys.flags.int_max_str_digits" contém o valor de
  "PYTHONINTMAXSTRDIGITS" ou "-X int_max_str_digits". Se a variável
  env e a opção "-X" estiverem definidas, a opção "-X" terá
  precedência. Um valor de *-1* indica que ambos não foram definidos,
  portanto, um valor de "sys.int_info.default_max_str_digits" foi
  usado durante a inicialização.

A partir do código, você pode inspecionar o limite atual e definir um
novo usando estas APIs "sys":

* "sys.get_int_max_str_digits()" e "sys.set_int_max_str_digits()" são
  um getter e um setter para o limite de todo o interpretador. Os
  subinterpretadores têm seu próprio limite.

Informações sobre o padrão e o mínimo podem ser encontradas em
"sys.int_info":

* "sys.int_info.default_max_str_digits" é o limite padrão compilado.

* "sys.int_info.str_digits_check_threshold" é o menor valor aceito
  para o limite (diferente de 0 que o desabilita).

Adicionado na versão 3.11.

Cuidado:

  Definir um limite baixo *pode* levar a problemas. Embora raro,
  existe um código que contém constantes inteiras em decimal em sua
  origem que excedem o limite mínimo. Uma consequência de definir o
  limite é que o código-fonte do Python contendo literais inteiros
  decimais maiores que o limite encontrará um erro durante a análise,
  geralmente no momento da inicialização ou no momento da importação
  ou até mesmo no momento da instalação -- sempre que um ".pyc"
  atualizado ainda não existe para o código. Uma solução alternativa
  para source que contém tais constantes grandes é convertê-las para a
  forma hexadecimal "0x", pois não há limite.Teste sua aplicação
  completamente se você usar um limite baixo. Certifique-se de que
  seus testes sejam executados com o limite definido anteriormente por
  meio do ambiente ou sinalizador para que ele seja aplicado durante a
  inicialização e até mesmo durante qualquer etapa de instalação que
  possa invocar o Python para pré-compilar fontes ".py" para arquivos
  ".pyc".


Configuração recomendada
------------------------

Espera-se que o padrão "sys.int_info.default_max_str_digits" seja
razoável para a maioria das aplicações. Se sua aplicação exigir um
limite diferente, defina-o em seu ponto de entrada principal usando
código agnóstico de versão Python, pois essas APIs foram adicionadas
em lançamentos de patch de segurança em versões anteriores a 3.12.

Exemplo:

   >>> 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)

Se você precisar desativá-lo totalmente, defina-o como "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 com apenas um elemento, que é a tupla a ser formatada.
