4. Tipos internos

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

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

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

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

4.1. Teste do Valor Verdade

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

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

• constantes definidas como False: None e False.

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

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

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

4.2. Operações Booleanas — and, or, not

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

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

Notas:

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

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

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

4.3. Comparações

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

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

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

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

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

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

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

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

4.4. Tipos Numéricos — int, float, complex

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

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

O Python suporta completamente aritmética mista: quando um operador aritmético binário possui operandos de diferentes tipos numéricos, o operando com o tipo “mais estreito” é ampliado para aquele do outro, onde o integral é mais estreito do que o ponto flutuante, que é mais estreito que número complexo. Comparações entre números de tipos mistos usam a mesma regra. 2 Os construtores int(), float(), e complex() podem ser usados para produzir números de um tipo específico.

Todos os tipos numéricos (exceto complexos) suportam as seguintes operações, separadas por prioridade ascendente (todas as operações numéricas possuem uma alta prioridade do que operações de comparação):

Operação	Resultado	Notas	Documentação completa
x + y	soma de x e y
x - y	diferença de * x * e * y *
x * y	produto de * x * e * y *
x / y	quociente de x e y
x // y	quociente flutuante of x and y	(1)
x % y	restante de x / y	(2)
-x	x negado
+x	x inalterado
abs(x)	valor absoluto ou magnitude de x		abs()
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 re, parte imaginária im. im acarreta em zero.	(6)	complex()
c.conjugate()	conjugado do número complexo c
divmod(x, y)	o par (x // y, x % y)	(2)	divmod()
pow(x, y)	x elevado a y	(5)	pow()
x ** y	x elevado a y	(5)

Notas:

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

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

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

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

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

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

   Veja http://www.unicode.org/Public/9.0.0/ucd/extracted/DerivedNumericType.txt para obter uma lista completa de pontos de código com a propriedade Nd.

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

Operação	Resultado
math.trunc(x)	x truncado para Integral
:func:`round(x[, n]) 1`<round>	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.

4.4.1. Operações de bits em tipos inteiros

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

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

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

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

Notas:

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

2. Um deslocamento a esquerda por n bits é equivalente a multiplicação por pow(2, n) sem a checagem de overflow.

3. Um deslocamento a direita por n bits é equivalente a divisão por pow(2, n) sem a checagem de overflow.

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

4.4.2. Métodos adicionais em tipos inteiros

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

int.bit_length()

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

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

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

Equivalente a:

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

Novo na versão 3.1.

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

Retorna um array de bytes representando um inteiro.

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

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

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

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

Novo na versão 3.2.

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

Retorna o inteiro representado pelo dado array de bytes.

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

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

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

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

Novo na versão 3.2.

4.4.3. Métodos Adicionais em Ponto Flutuante

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

float.as_integer_ratio()

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

float.is_integer()

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

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

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

float.hex()

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

classmethod float.fromhex(s)

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

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

Uma string hexadecimal toma a forma:

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

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

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

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

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

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

4.4.4. Hashing de tipos numéricos

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

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

Aqui estão as regras em detalhe:

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

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

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

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

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

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

import sys, math

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

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

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

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

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

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

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

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

4.5. Tipos de Iteradores

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

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

container.__iter__()

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

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

iterator.__iter__()

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

iterator.__next__()

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

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

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

4.5.1. Tipos de Geradores

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

4.6. Tipos de Sequências — list, tuple, range

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

4.6.1. Operações de Sequências Comuns

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

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

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

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

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

Notas:

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

   >>> "gg" in "eggs"
   True
   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.6.2. Tipos de Sequência Imutáveis

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

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

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

4.6.3. Tipos de Sequências Mutáveis

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

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

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

Notas:

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

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

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

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

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

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

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

4.6.4. Listas

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

class list([iterable])

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

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

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

• Usando uma list comprehension: [x for x in iterable]

• Usando o construtor de tipo: list() ou list(iterable)

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

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

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

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

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

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

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

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

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

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

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

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

4.6.5. Tuplas

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

class tuple([iterable])

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

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

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

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

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

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

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

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

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

4.6.6. Ranges

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

class range(stop)

class range(start, stop[, step])

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

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

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

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

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

Range de exemplos:

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

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

start

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

stop

O valor do parâmetro stop

step

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

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

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

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

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

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

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

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

Ver também

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

4.7. Tipo de Sequência de Texto — str

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

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

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

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

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

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

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

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

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

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

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

class str(object='')

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

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

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

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

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

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

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

4.7.1. Métodos de String

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

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

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

str.capitalize()

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

str.casefold()

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

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

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

Novo na versão 3.3.

str.center(width[, fillchar])

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

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

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

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

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

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

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

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

str.expandtabs(tabsize=8)

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

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

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

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

Nota

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

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs)

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

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

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

Nota

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

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

str.format_map(mapping)

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

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

Novo na versão 3.2.

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

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

str.isalnum()

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

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 Unicode Standard.

str.isdecimal()

Return true if all characters in the string are decimal characters and there is at least one character, false otherwise. Decimal characters are those that can be used to form numbers in base 10, e.g. U+0660, ARABIC-INDIC DIGIT ZERO. Formally a decimal character is a character in the Unicode General Category “Nd”.

str.isdigit()

Return true if all characters in the string are digits and there is at least one character, false otherwise. Digits include decimal characters and digits that need special handling, such as the compatibility superscript digits. This covers digits which cannot be used to form numbers in base 10, like the Kharosthi numbers. Formally, a digit is a character that has the property value Numeric_Type=Digit or Numeric_Type=Decimal.

str.isidentifier()

Return true if the string is a valid identifier according to the language definition, section Identificadores e Keywords.

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

str.islower()

Return true if all cased characters 4 in the string are lowercase and there is at least one cased character, false otherwise.

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.

str.isprintable()

Return true if all characters in the string are printable or the string is empty, false otherwise. Nonprintable characters are those characters defined in the Unicode character database as “Other” or “Separator”, excepting the ASCII space (0x20) which is considered printable. (Note that printable characters in this context are those which should not be escaped when repr() is invoked on a string. It has no bearing on the handling of strings written to sys.stdout or sys.stderr.)

str.isspace()

Return true if there are only whitespace characters in the string and there is at least one character, false otherwise. Whitespace characters are those characters defined in the Unicode character database as “Other” or “Separator” and those with bidirectional property being one of “WS”, “B”, or “S”.

str.istitle()

Return true if the string is a titlecased string and there is at least one character, for example uppercase characters may only follow uncased characters and lowercase characters only cased ones. Return false otherwise.

str.isupper()

Return true if all cased characters 4 in the string are uppercase and there is at least one cased character, false otherwise.

str.join(iterable)

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

str.ljust(width[, fillchar])

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

str.lower()

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

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

str.lstrip([chars])

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

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

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

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

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

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

str.partition(sep)

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

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

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

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

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

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

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

str.rjust(width[, fillchar])

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

str.rpartition(sep)

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

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

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

str.rstrip([chars])

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

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

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

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

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

Por exemplo:

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

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

Por exemplo:

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

str.splitlines([keepends])

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

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

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

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

Por exemplo:

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

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

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

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

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

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

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

str.strip([chars])

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

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

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

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

str.swapcase()

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

str.title()

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

Por exemplo:

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

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

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

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

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

str.translate(table)

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

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

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

str.upper()

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

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

str.zfill(width)

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

Por exemplo:

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

4.7.2. Formatação de String no Formato printf-style

Nota

As operações de formatação descritas aqui exibem uma variedade de peculiaridades que levam a uma série de erros comuns (como falha na exibição de tuplas e dicionários corretamente). Usando o novo formatted string literals ou a interface str.format() nos ajuda a evitar esses problemas. Essas alternativas também oferecem abordagens mais poderosas, flexíveis e extensíveis para formatar textos.

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

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

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

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

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

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

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

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

6. Modificador de Comprimento(opcional).

7. Tipos de Conversão

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

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

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

Os caracteres flags de conversão são:

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

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

Os tipos de conversão são:

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

Notas:

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

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

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

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

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

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

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

6. Veja PEP 237.

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

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

4.8. Tipos de Sequência Binária — bytes, bytearray, memoryview

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

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

4.8.1. Objetos Bytes

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

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

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

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

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

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

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

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

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

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

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

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

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

Veja também os bult-ins bytes.

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

classmethod fromhex(string)

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

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

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

hex()

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

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

Novo na versão 3.5.

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

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

Nota

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

4.8.2. Bytearray Objects

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

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

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

• Criando uma instância vazia: bytearray()

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

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

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

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

Veja também o tipo built-in bytearray.

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

classmethod fromhex(string)

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

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

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

hex()

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

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

Novo na versão 3.5.

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

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

4.8.3. Operações com Bytes e Bytearray

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

Nota

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

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

e:

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

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

Nota

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

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

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

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

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

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

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

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

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

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

Nota

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

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

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

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

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

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

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

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

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

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

Nota

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

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

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

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

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

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

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

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

bytes.join(iterable)

bytearray.join(iterable)

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

static bytes.maketrans(from, to)

static bytearray.maketrans(from, to)

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

Novo na versão 3.1.

bytes.partition(sep)

bytearray.partition(sep)

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

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

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

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

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

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

Nota

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

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

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

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

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

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

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

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

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

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

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

bytes.rpartition(sep)

bytearray.rpartition(sep)

Split the sequence at the last occurrence of sep, and return a 3-tuple containing the part before the separator, the separator itself or its bytearray copy, and the part after the separator. If the separator is not found, return a 3-tuple containing a copy of the original sequence, followed by two empty bytes or bytearray objects.

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

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

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

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

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

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

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

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

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

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

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

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

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

bytes.center(width[, fillbyte])

bytearray.center(width[, fillbyte])

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

Nota

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

bytes.ljust(width[, fillbyte])

bytearray.ljust(width[, fillbyte])

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

Nota

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

bytes.lstrip([chars])

bytearray.lstrip([chars])

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

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

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

Nota

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

bytes.rjust(width[, fillbyte])

bytearray.rjust(width[, fillbyte])

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

Nota

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

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

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

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

bytes.rstrip([chars])

bytearray.rstrip([chars])

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

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

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

Nota

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

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

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

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

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

Por exemplo:

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

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

Por exemplo:

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

bytes.strip([chars])

bytearray.strip([chars])

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

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

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

Nota

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

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

bytes.capitalize()

bytearray.capitalize()

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

Nota

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

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

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

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

Nota

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

bytes.isalnum()

bytearray.isalnum()

Return true if all bytes in the sequence are alphabetical ASCII characters or ASCII decimal digits and the sequence is not empty, false otherwise. Alphabetic ASCII characters are those byte values in the sequence b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'. ASCII decimal digits are those byte values in the sequence 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 forem caracteres ASCII alfabéticos e a seqüência não esteja vazia, do contrário, retorna Falso. Os caracteres alfabéticos ASCII são os valores de bytes na seqüência b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'.

Por exemplo:

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

bytes.isdigit()

bytearray.isdigit()

Return true if all bytes in the sequence are ASCII decimal digits and the sequence is not empty, false otherwise. ASCII decimal digits are those byte values in the sequence b'0123456789'.

Por exemplo:

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

bytes.islower()

bytearray.islower()

Return true if there is at least one lowercase ASCII character in the sequence and no uppercase ASCII characters, false otherwise.

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

Return true if all bytes in the sequence are ASCII whitespace and the sequence is not empty, false otherwise. ASCII whitespace characters are those byte values in the sequence b' \t\n\r\x0b\f' (space, tab, newline, carriage return, vertical tab, form feed).

bytes.istitle()

bytearray.istitle()

Return true if the sequence is ASCII titlecase and the sequence is not empty, false otherwise. See bytes.title() for more details on the definition of “titlecase”.

Por exemplo:

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

bytes.isupper()

bytearray.isupper()

Return true if there is at least one uppercase alphabetic ASCII character in the sequence and no lowercase ASCII characters, false otherwise.

Por exemplo:

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

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

bytes.lower()

bytearray.lower()

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

Por exemplo:

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

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

Nota

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

bytes.splitlines(keepends=False)

bytearray.splitlines(keepends=False)

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

Por exemplo:

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

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

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

bytes.swapcase()

bytearray.swapcase()

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

Por exemplo:

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

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

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

Nota

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

bytes.title()

bytearray.title()

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

Por exemplo:

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

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

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

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

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

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

Nota

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

bytes.upper()

bytearray.upper()

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

Por exemplo:

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

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

Nota

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

bytes.zfill(width)

bytearray.zfill(width)

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

Por exemplo:

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

Nota

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

4.8.4. Estilo de Formatação de bytes printf-style

Nota

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

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

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

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

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

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

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

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

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

6. Modificador de Comprimento(opcional).

7. Tipos de Conversão

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

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

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

Os caracteres flags de conversão são:

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

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

Os tipos de conversão são:

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

Notas:

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

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

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

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

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

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

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

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

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

8. Veja PEP 237.

Nota

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

Ver também

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

Novo na versão 3.5.

4.8.5. Memory Views

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

class memoryview(obj)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

memoryview possui vários métodos:

__eq__(exporter)

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

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

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

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

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

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

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

tobytes()

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

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

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

hex()

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

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

Novo na versão 3.5.

tolist()

Retorna os dados no buffer como uma lista de elementos.

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

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

release()

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

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

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

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

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

Novo na versão 3.2.

cast(format[, shape])

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

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

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

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

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

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

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

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

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

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

Novo na versão 3.3.

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

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

obj

O objeto subjacente da memoryview:

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

Novo na versão 3.3.

nbytes

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

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

Arrays Multi-dimensional:

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

Novo na versão 3.3.

readonly

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

format

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

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

itemsize

O tamanho em Bytes de cada elemento do memoryview:

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

ndim

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

shape

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

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

strides

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

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

suboffsets

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

c_contiguous

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

Novo na versão 3.3.

f_contiguous

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

Novo na versão 3.3.

contiguous

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

Novo na versão 3.3.

4.9. Tipo Set — set, frozenset

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

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

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

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

Os construtores de ambas as classes funcionam da mesma forma:

class set([iterable])

class frozenset([iterable])

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

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

len(s)

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

x in s

Testa se x pertence a s.

x not in s

Testa se x não pertence a s.

isdisjoint(other)

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

issubset(other)

set <= other

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

set < other

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

issuperset(other)

set >= other

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

set > other

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

union(*others)

set | other | ...

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

intersection(*others)

set & other & ...

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

difference(*others)

set - other - ...

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

symmetric_difference(other)

set ^ other

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

copy()

Return a new set with a shallow copy of s.

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

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

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

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

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

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

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

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

update(*others)

set |= other | ...

Atualiza o set, adicionando elementos de others.

intersection_update(*others)

set &= other & ...

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

difference_update(*others)

set -= other | ...

Atualiza o set, removendo elementos encontrados em others.

symmetric_difference_update(other)

set ^= other

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

add(elem)

Adiciona o elemento elem ao set.

remove(elem)

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

discard(elem)

Remove o elemento elem do set se ele estiver presente.

pop()

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

clear()

Remove todos os elementos do set.

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

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

4.10. Tipo de Mapeamento — dict

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

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

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

class dict(**kwarg)

class dict(mapping, **kwarg)

class dict(iterable, **kwarg)

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

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

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

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

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

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

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

len(d)

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

d[key]

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

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

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

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

d[key] = value

Define d[key] para value.

del d[key]

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

key in d

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

key not in d

Equivalente a not key in d.

iter(d)

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

clear()

Remove todos os itens do dicionário.

copy()

Retorna uma cópia superficial do dicionário.

classmethod fromkeys(seq[, value])

Create a new dictionary with keys from seq and values set to value.

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

get(key[, default])

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

items()

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

keys()

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

pop(key[, default])

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

popitem()

Remove and return an arbitrary (key, value) pair from the dictionary.

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

setdefault(key[, default])

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

update([other])

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

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

values()

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

Dictionaries compare equal if and only if they have the same (key, value) pairs. Order comparisons (‘<’, ‘<=’, ‘>=’, ‘>’) raise TypeError.

Ver também

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

4.10.1. Objetos de visão de dicionário

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

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

len(dictview)

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

iter(dictview)

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

Keys and values are iterated over in an arbitrary order which is non-random, varies across Python implementations, and depends on the dictionary’s history of insertions and deletions. If keys, values and items views are iterated over with no intervening modifications to the dictionary, the order of items will directly correspond. This allows the creation of (value, key) pairs using zip(): pairs = zip(d.values(), d.keys()). Another way to create the same list is 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.

x in dictview

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

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

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

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

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

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

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

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

4.11. 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__()

Enter the runtime context and return either this object or another object related to the runtime context. The value returned by this method is bound to the identifier in the as clause of with statements using this context manager.

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

An example of a context manager that returns a related object is the one returned by decimal.localcontext(). These managers set the active decimal context to a copy of the original decimal context and then return the copy. This allows changes to be made to the current decimal context in the body of the with statement without affecting code outside the with statement.

contextmanager.__exit__(exc_type, exc_val, exc_tb)

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

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. Exceptions that occur during execution of this method will replace any exception that occurred in the body of the with statement.

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

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

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

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

4.12. Outros tipos embutidos

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

4.12.1. Módulos

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

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

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

4.12.2. Classes e Instâncias de Classes

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

4.12.3. Funções

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

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

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

4.12.4. Métodos

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

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

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

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

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

4.12.5. Objetos de Código

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

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

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

4.12.6. Objetos de tipo

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

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

4.12.7. O objeto Null

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

Ele é escrito como None.

4.12.8. O Objeto Ellipsis

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

Está escrito com Ellipsis ou ....

4.12.9. O Objeto NotImplemented

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

Está escrito como NotImplemented.

4.12.10. Valores Booleanos

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

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

4.12.11. Objetos Internos

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

4.13. Atributos Especiais

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

object.__dict__

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

instance.__class__

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

class.__bases__

A tupla de classes base de um objeto classe.

definition.__name__

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

definition.__qualname__

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

Novo na versão 3.3.

class.__mro__

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

class.mro()

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

class.__subclasses__()

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

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

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(1,2,3,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(1,2)

Para formatar apenas uma tupla, você deve portanto fornecer uma tupla singleton, cujo único elemento é a tupla a ser formatada.