Tipos embutidos¶
As seções a seguir descrevem os tipos padrão que são embutidos ao interpretador.
Os principais tipos embutidos são numéricos, sequências, mapeamentos, classes, instâncias e exceções.
Algumas classes de coleção são mutáveis. Os métodos que adicionam, subtraem ou reorganizam seus membros no lugar, e não retornam um item específico, nunca retornam a instância da coleção propriamente dita, mas um None
.
Algumas operações são suportadas por vários tipos de objetos; em particular, praticamente todos os objetos podem ser comparados em termos de igualdade, testados quanto ao valor verdade e convertidos em uma string (com a função repr()
ou a função ligeiramente diferente str()
). A última função é implicitamente usada quando um objeto é escrito pela função print()
.
Teste do valor verdade¶
Qualquer objeto pode ser testado quanto ao valor verdade, para uso em uma condição if
ou while
ou como operando das operações booleanas abaixo.
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 __len__()
que retorna zero, quando chamado com o objeto. 1 Aqui estão a maioria dos objetos embutidos considerados falsos:
constantes definidas para serem falsas:
None
eFalse
.zero de qualquer tipo numérico:
0
,0.0
,0j
,Decimal(0)
,Fraction(0, 1)
sequências e coleções vazias:
''
,()
,[]
,{}
,set()
,range(0)
Operações e funções embutidas que têm um resultado Booleano retornam 0
ou False
para falso e 1
ou True
para verdadeiro, salvo indicações ao contrário. (Exceção importante: as operações Booleanas or
e and
sempre retornam um de seus operandos.)
Operações booleanas — and
, or
, not
¶
Esses são as operações booleanas, ordenados por prioridade ascendente:
Operação |
Resultado |
Notas |
---|---|---|
|
se x é falso, então y, do contrário x |
(1) |
|
se x é falso, então x, do contrário y |
(2) |
|
se x é falso, então |
(3) |
Notas:
Esse é um operador de curto-circuito, por isso só avalia o segundo argumento se o primeiro é falso.
Este é um operador de curto-circuito, por isso só avalia o segundo argumento se o primeiro é verdadeiro.
not
tem uma prioridade mais baixa do que operadores não booleanos, entãonot a == b
é interpretado comonot (a == b)
ea == not b
é um erro de sintaxe.
Comparações¶
Há oito operadores comparativos no Python. Todos eles possuem a mesma prioridade (que é maior do que aquela das operações Booleanas). Comparações podem ser encadeadas arbitrariamente; por exemplo, x < y <= z
é equivalente a x < y and y <= z
, exceto que y é avaliado apenas uma vez (porém em ambos os casos z não é avaliado de todo quando x < y
é sabido ser falso).
Esta tabela resume as operações de comparação:
Operação |
Significado |
---|---|
|
estritamente menor que |
|
menor que ou igual |
|
estritamente maior que |
|
maior que ou igual |
|
igual |
|
não é igual |
|
identidade do objeto |
|
identidade de objeto negada |
Objetos de tipos diferentes, exceto tipos numéricos diferentes, nunca comparam iguais. O operador ==
é sempre definido, mas para alguns tipos de objetos (por exemplo, objetos de classe) é equivalente a is
. Os operadores <
, <=
, >
e >=
são definidos apenas onde fazem sentido; por exemplo, eles levantam uma exceção TypeError
quando um dos argumentos é um número complexo.
Instâncias não idênticas de uma classe normalmente comparam-se como desiguais ao menos que a classe defina o método __eq__()
.
Instâncias de uma classe não podem ser ordenadas com respeito a outras instâncias da mesma classe, ou outros tipos de objeto, ao menos que a classe defina o suficiente dos métodos __lt__()
, __le__()
, __gt__()
e __ge__()
(no geral, __lt__()
e __eq__()
são suficientes, se você quiser o significado convencional dos operadores de comparação).
O comportamento dos operadores is
e is not
não pode ser personalizado; além disso eles podem ser aplicados a quaisquer dois objetos e nunca levantam uma exceção.
Mais duas operações com a mesma prioridade sintática, in
e not in
, são suportadas por tipos que são iteráveis ou implementam o método __contains__()
.
Tipos numéricos — int
, float
, complex
¶
Existem três tipos numéricos distintos: inteiros, números de ponto flutuante e números complexos. Além disso, os booleanos são um subtipo de números inteiros. Inteiros têm precisão ilimitada. Números de ponto flutuante são geralmente implementados usando double
em C; informações sobre a precisão e representação interna dos números de ponto flutuante para a máquina na qual seu programa está sendo executado estão disponíveis em sys.float_info
. Números complexos têm uma parte real e imaginária, cada um com um número de ponto flutuante. Para extrair essas partes de um número complexo z, use z.real
e z.imag
. (A biblioteca padrão inclui os tipos numéricos adicionais fractions.Fraction
, para racionais, e decimal.Decimal
, para números de ponto flutuante com precisão definida pelo usuário.)
Números são criados por literais numéricos ou como resultado de operadores e funções embutidas. Integrais literais planos (incluindo números hexadecimais, octais e binários) culminam em integrais. Literais numéricos contendo um ponto decimal ou um sinal exponencial resultam em números de ponto flutuante. Anexando 'j'
ou 'J'
para um literal numérico resulta em um número imaginário (um número complexo com uma parte real zero) com a qual você pode adicionar a um integral ou flutuante para receber um número complexo com partes reais e imaginárias.
Python suporta completamente aritmética mista: quando um operador de aritmética binária tem operandos de tipos numéricos diferentes, o operando com o tipo “mais estreito” é ampliado para o tipo do outro operando, onde um inteiro é mais estreito do que um ponto flutuante, que por sua vez é mais estreito que um número complexo. Uma comparação entre números de diferentes tipos se comporta como se os valores exatos desses números estivessem sendo comparados. 2
Os construtores int()
, float()
, e complex()
podem ser usados para produzir números de um tipo específico.
Todos os tipos numéricos (exceto complexos) suportam as seguintes operações (para prioridades das operações, consulte Precedência de operadores):
Operação |
Resultado |
Notas |
Documentação completa |
---|---|---|---|
|
soma de x e y |
||
|
diferença de x e y |
||
|
produto de x e y |
||
|
quociente de x e y |
||
|
piso do quociente de x e y |
(1) |
|
|
restante de |
(2) |
|
|
x negado |
||
|
x inalterado |
||
|
valor absoluto ou magnitude de x |
||
|
x convertido em inteiro |
(3)(6) |
|
|
x convertido em ponto flutuante |
(4)(6) |
|
|
um número complexo com parte real re, parte imaginária im. im tem como padrão zero. |
(6) |
|
|
conjugado do número complexo c |
||
|
o par |
(2) |
|
|
x elevado a y |
(5) |
|
|
x elevado a y |
(5) |
Notas:
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
.Não para números complexos. Ao invés disso, converte para pontos flutuantes usando
abs()
se for apropriado.Conversão de ponto flutuante para inteiro pode arredondar ou truncar como ocorre em C; veja as funções
math.floor()
emath.ceil()
para conversões bem definidas.ponto flutuante também aceita a string “nan” e “inf” com um prefixo opcional “+” ou “-” a Não é um Número (NaN) e infinidade positiva ou negativa.
Python define
pow(0, 0)
e0 ** 0
sendo1
, como é comum para linguagens de programação.Os literais numéricos aceitos incluem os dígitos de
0
a9
ou qualquer equivalente Unicode (pontos de código com a propriedadeNd
).Veja https://www.unicode.org/Public/13.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
e float
) também incluem as seguintes operações.
Operação |
Resultado |
---|---|
x truncado para |
|
x arredondado para n dígitos, arredondando metade para igualar. Se n é omitido, ele toma o padrão de 0. |
|
o maior |
|
pelo menos |
Para operações numéricas adicionais, consulte os módulos math
e cmath
.
Operações de bits em tipos inteiros¶
Operações bit a bit só fazem sentido para números inteiros. O resultado de operações bit a bit é calculado como se fosse realizado no complemento de dois com um número infinito de bits de sinal.
As prioridades das operações bit a bit binárias são todas menores do que as operações numéricas e maiores que as comparações; a operação unária ~
tem a mesma prioridade que as outras operações numéricas unárias (+
e -
).
Esta tabela lista as operações de bits classificadas em prioridade ascendente:
Operação |
Resultado |
Notas |
---|---|---|
|
ou bit a bit de x e y |
(4) |
|
ou exclusivo bit a bit de x e y |
(4) |
|
e bit a bit de x e y |
(4) |
|
x deslocado para a esquerda por n bits |
(1)(2) |
|
x deslocado para a direita por n bits |
(1)(3) |
|
os bits de x invertidos |
Notas:
Contagens de deslocamento negativo são ilegais e levantam uma
ValueError
.Um deslocamento à esquerda por n bits é equivalente à multiplicação por
pow(2, n)
.Um deslocamento à direita por n bits é equivalente à divisão pelo piso por
pow(2, n)
.Executar esses cálculos com pelo menos um bit extra de extensão de sinal na representação de complemento de dois finitos (uma largura de bit de trabalho
1 + max(x.bit_length(), y.bit_length())
ou mais) é suficiente para obter o mesmo resultado como se houvesse um número infinito de bits de sinal.
Métodos adicionais em tipos inteiros¶
O tipo int implementa a classe base abstrata numbers.Integral
. Além disso, ele provê mais alguns métodos:
-
int.
bit_length
()¶ Retorna o número de bits necessários para representar um inteiro em binário, excluindo o sinal e entrelinha zeros:
>>> n = -37 >>> bin(n) '-0b100101' >>> n.bit_length() 6
Mais precisamente, se
x
for diferente de zero, entãox.bit_length()
é o único positivo inteirok
tal que2**(k-1) <= abs(x) < 2**k
. Equivalentemente, quandoabs(x)
for pequeno o suficiente para ter um logaritmo corretamente arrendondado, entãok = 1 + int(log(abs(x), 2))
. Sex
é zero, entãox.bit_length()
retorna0
.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 vetor de bytes representando um inteiro.
>>> (1024).to_bytes(2, byteorder='big') b'\x04\x00' >>> (1024).to_bytes(10, byteorder='big') b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00' >>> (-1024).to_bytes(10, byteorder='big', signed=True) b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00' >>> x = 1000 >>> x.to_bytes((x.bit_length() + 7) // 8, byteorder='little') b'\xe8\x03'
O inteiro é representado usando length bytes. Uma
OverflowError
é levantada se um inteiro não é representável com o dado número de bytes.O argumento byteorder determina a ordem de bytes usada para representar um inteiro. Se o byteorder é
"big"
, o byte mais significativo está no início do vetor de byte. Se byteorder é"little"
, o byte mais significativo está no final do vetor de byte. Para requisitar a ordem nativa de byte do sistema hospedeiro, usesys.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, umaOverflowError
é levantada. 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 vetor de bytes dado.
>>> int.from_bytes(b'\x00\x10', byteorder='big') 16 >>> int.from_bytes(b'\x00\x10', byteorder='little') 4096 >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True) -1024 >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False) 64512 >>> int.from_bytes([255, 0, 0], byteorder='big') 16711680
O argumento bytes precisa ou ser um objeto byte ou similar 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 significativo está no início do vetor de byte. Se byteorder é"little"
, o byte mais significativo está no final do vetor de byte. Para requisitar a ordem nativa de byte do sistema hospedeiro, usesys.byteorder
como o valor da ordem de byte.O argumento signed indica quando o complemento de dois é usado para representar o inteiro.
Novo na versão 3.2.
-
int.
as_integer_ratio
()¶ Retorna um par de números inteiros cuja razão é exatamente igual ao número inteiro original e com um denominador positivo. A proporção inteira de números inteiros (números inteiros) é sempre o número inteiro como numerador e
1
como denominador.Novo na versão 3.8.
Métodos adicionais em ponto flutuante¶
O tipo float implementa a classe base abstrata numbers.Real
. float também possui os seguintes métodos adicionais.
-
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 umValueError
em NaNs.
-
float.
is_integer
()¶ Retorna
True
se a instância do float for finita com o valor integral eFalse
, caso contrário:>>> (-2.0).is_integer() True >>> (3.2).is_integer() False
Dois métodos suportam conversão para e de strings hexadecimais. Uma vez que os pontos flutuantes do Python são armazenados internamente como números binários, a conversão de um ponto flutuante para ou de uma string decimal geralmente envolve um pequeno erro de arredondamento. Em contraste, as strings hexadecimais permitem a representação exata e a especificação de números de ponto flutuante. Isso pode ser útil na depuração e no trabalho numérico.
-
float.
hex
()¶ Retorna a representação de um número de ponto flutuante como uma string hexadecimal. Para números de ponto flutuante finitos, essa representação vai sempre incluir um
0x
inicial e ump
final e expoente.
-
classmethod
float.
fromhex
(s)¶ Método de classe para retornar um ponto flutuante representado por uma string hexadecimal s. A string s pode ter espaços em branco iniciais e finais.
Note que float.hex()
é um método de instância, enquanto float.fromhex()
é um método de classe.
Uma string hexadecimal toma a forma:
[sign] ['0x'] integer ['.' fraction] ['p' exponent]
onde o sinal opcional sign
pode ser tanto +
or -
, integer
e fraction
são strings de dígitos hexadecimais, e exponent
é um inteiro decimal com um sinal opcional no início. Maiúsculo ou minúsculo não é significativo, e deve haver ao menos um dígito hexadecimal tanto no inteiro ou na fração. Essa sintaxe é similar à sintaxe especificada na seção 6.4.4.2 do padrão C99, e também do da sintaxe usada no Java 1.5 em diante. Em particular, a saída de float.hex()
é usável como um literal hexadecimal de ponto flutuante em código C ou Java, e strings hexadecimais produzidas pelo formato do caractere %a
do C ou Double.toHexString
do Java são aceitos pelo float.fromhex()
.
Note que o expoente é escrito em decimal ao invés de hexadecimal, e que ele dá a potência de 2 pela qual se multiplica o coeficiente. Por exemplo, a string hexadecimal 0x3.a7p10
representa o número de ponto flutuante (3 + 10./16 + 7./16**2) * 2.0**10
ou 3740.0
:
>>> float.fromhex('0x3.a7p10')
3740.0
Aplicando a conversão inversa a 3740.0
retorna uma string hexadecimal diferente representada pelo mesmo número:
>>> float.hex(3740.0)
'0x1.d380000000000p+11'
Hashing de tipos numéricos¶
Para números x
e y
, possivelmente de diferentes tipos, é um requisito que hash(x) == hash(y)
sempre que x == y
(veja a documentação do método __hash__()
para mais detalhes). Para facilitar a implementação e eficiência através de uma variedade de tipos numéricos (incluindo int
, float
, decimal.Decimal
e fractions.Fraction
), o hash do Python para tipos numéricos é baseado em uma única função matemática que é definida para qualquer número racional e, portanto, se aplica para todas as instâncias de int
e fractions.Fraction
, e todas as instâncias finitas das classes float
e decimal.Decimal
. Essencialmente, essa função é dada pelo módulo de redução P
para um primo fixado P
. O valor de P
é disponibilizado ao Python como um atributo modulus
do sys.hash_info
.
CPython implementation detail: Atualmente, o primo usado é P = 2**31 - 1
em máquinas com longos de 32 bits do C e P = 2**61 - 1
em máquinas com longos de 64 bits do C.
Aqui estão as regras em detalhe:
Se
x = m / n
é um número racional não negativo en
não é divisível porP
, definehash(x)
comom * invmod(n, P) % P
, ondeinvmod(n, P)
retorna o inverso do módulo den
comP
.Se
x = m / n
é um número racional não negativo en
é divisível porP
(porémm
não é) entãon
não possui moduloP
inverso e a regra acima não se aplica; nesse caso definahash(x)
para ser o valor constantesys.hash_info.inf
.Se
x = m / n
é um número racional negativo, definahash(x)
como-hash(-x)
. Se a hash resultante é-1
, a substituo com-2
.Os valores particulares
sys.hash_info.inf
,-sys.hash_info.inf
esys.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 número
complex
z
, o valor da hash do número real partes imaginárias são combinados calculandohash(z.real) + sys.hash_info.imag * hash(z.imag)
, módulo reduzido2**sys.hash_info.width
de modo que isto permaneça emrange(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1))
. Novamente, se o resultado é-1
, ele é substituído por-2
.
Para esclarecer as regras acima, aqui estão alguns exemplos de código em Python, equivalentes ao hash embutido, para calcular o hash de números racionais, float
ou complex
:
import sys, math
def hash_fraction(m, n):
"""Compute the hash of a rational number m / n.
Assumes m and n are integers, with n positive.
Equivalent to hash(fractions.Fraction(m, n)).
"""
P = sys.hash_info.modulus
# Remove common factors of P. (Unnecessary if m and n already coprime.)
while m % P == n % P == 0:
m, n = m // P, n // P
if n % P == 0:
hash_value = sys.hash_info.inf
else:
# Fermat's Little Theorem: pow(n, P-1, P) is 1, so
# pow(n, P-2, P) gives the inverse of n modulo P.
hash_value = (abs(m) % P) * pow(n, P - 2, P) % P
if m < 0:
hash_value = -hash_value
if hash_value == -1:
hash_value = -2
return hash_value
def hash_float(x):
"""Compute the hash of a float x."""
if math.isnan(x):
return sys.hash_info.nan
elif math.isinf(x):
return sys.hash_info.inf if x > 0 else -sys.hash_info.inf
else:
return hash_fraction(*x.as_integer_ratio())
def hash_complex(z):
"""Compute the hash of a complex number z."""
hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
# do a signed reduction modulo 2**sys.hash_info.width
M = 2**(sys.hash_info.width - 1)
hash_value = (hash_value & (M - 1)) - (hash_value & M)
if hash_value == -1:
hash_value = -2
return hash_value
Tipos iteradores¶
Python suporta o conceito de iteração por contêineres. Isso é implementado usando dois métodos distintos; estes são usados para permitir classes definidas pelo usuário suportem iteração. Sequências, descritas abaixo em mais detalhes, sempre suportam os métodos de iteração.
Um método necessita ser definido para objetos contêineres afim destes proverem suporte a iteração:
-
container.
__iter__
()¶ Retorna um objeto iterador. O objeto deve suportar o protocolo iterador descrito abaixo. Se um contêiner suporta diferentes tipos de iterador, métodos adicionais podem ser providenciados para requisitar especificamente iteradores para aqueles tipos de iterações. (Um exemplo de um objeto suportando múltiplas formas de iteração seria uma estrutura em árvore a qual suporta ambas travessias de travessia em largura e em profundidade.) Esse método corresponde ao slot
tp_iter
da estrutura de tipos para objetos Python na API Python/C.
Os próprios objetos iteradores são obrigados a suportarem os dois métodos a seguir, que juntos formam o protocolo iterador:
-
iterator.
__iter__
()¶ Retorna o próprio objeto iterador Isso é necessário para permitir que ambos os contêineres e iteradores sejam usados com as instruções
for
ein
. Este método corresponde ao slottp_iter
da estrutura de tipos para objetos Python na API Python/C.
-
iterator.
__next__
()¶ Retorna o próximo item do contêiner. Se não houver itens além, a exceção
StopIteration
é levantada. Esse método corresponde ao slottp_iternext
da estrutura de tipos para objetos Python na API Python/C.
Python define diversos objetos iteradores para suportar iterações sobre tipos de sequências gerais e específicas, dicionários, e outras formas mais especializadas. Os tipos específicos não são importantes além de sua implementação do protocolo iterador.
Uma vez que o método __next__()
do iterador levantou StopIteration
, ele deve continuar fazendo isso em chamadas subsequentes. Implementações que não obedecem essa propriedade são consideradas quebradas.
Tipos geradores¶
Os geradores do Python proveem uma maneira conveniente para implementar o protocolo iterador. Se o método __iter__()
de um objeto contêiner é implementado como um gerador, ele irá automaticamente retornar um objeto iterador (tecnicamente, um objeto gerador) fornecendo os métodos __iter__()
e __next__()
. Mais informações sobre geradores podem ser encontradas na documentação para a expressão yield.
Tipos sequências — list
, tuple
, range
¶
Existem três tipos básicos de sequência: listas, tuplas e objetos range. Tipos de sequência adicionais adaptados para o processamento de dados binários e strings de texto são descritos em seções dedicadas.
Operações comuns de sequências¶
As operações nas seguintes tabelas são suportadas pela maioria dos tipos sequências, ambos mutáveis e imutáveis. A classe ABC collections.abc.Sequence
é fornecida para tornar fácil a correta implementação desses operadores em tipos sequências personalizados.
Essa tabela lista as operações de sequência ordenadas em prioridade ascendente. Na tabela, s e t são sequências do mesmo tipo, n, i, j e k são inteiros e x é um objeto arbitrário que atende a qualquer restrição de valor e tipo imposta por s.
As operações in
e not in
têm as mesmas prioridades que as operações de comparação. As operações +
(concatenação) e *
(repetição) têm a mesma prioridade que as operações numéricas correspondentes. 3
Operação |
Resultado |
Notas |
---|---|---|
|
|
(1) |
|
|
(1) |
|
a concatenação de s e t |
(6)(7) |
|
equivalente a adicionar s a si mesmo n vezes |
(2)(7) |
|
i-ésimo item de s, origem 0 |
(3) |
|
fatia de s de i até j |
(3)(4) |
|
fatia de s de i até j com passo k |
(3)(5) |
|
comprimento de s |
|
|
menor item de s |
|
|
maior item de s |
|
|
índice da primeira ocorrência de x em s (no ou após o índice i, e antes do índice j) |
(8) |
|
numero total de ocorrência de x em s |
Sequências do mesmo tipo 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 possuírem o mesmo comprimento. (Para detalhes completos, veja Comparações na referência da linguagem.)
Notas:
Enquanto as operações
in
enot in
são usadas somente para testes de contenção simples em modo geral, algumas sequências especializadas (tais comostr
,bytes
ebytearray
) também usam-nas para testes de subsequências:>>> "gg" in "eggs" True
Os valores de n menos
0
são tratados como0
(o que produz uma sequência vazia do mesmo tipo que s). Observe que os itens na sequência s não são copiados; eles são referenciados várias vezes. Isso frequentemente assombra novos programadores Python; considere então que:>>> lists = [[]] * 3 >>> lists [[], [], []] >>> lists[0].append(3) >>> lists [[3], [3], [3]]
O que aconteceu é que
[[]]
é uma lista de um elemento contendo uma lista vazia, então todos os três elementos de[[]] * 3
são referências a esta única lista vazia. Modificar qualquer um dos elementos delists
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 no FAQ Como faço para criar uma lista multidimensional?.
Se i ou j for negativo, o índice será relativo ao fim da sequência s:
len(s) + i
oulen(s) + j
será substituído. Mas note que-0
ainda será0
.A fatia s de i até j é definida como a sequência de itens com índice k tal que
i <= k < j
. Se i ou j foi maior do quelen(s)
, usalen(s)
. Se i for omitido ouNone
, use0
. Se j for omitido ouNone
, usalen(s)
. Se i for maior ou igual a j, a fatia é vazia.A fatia s de i até j com passo k é definida como sendo a sequência de itens com índice
x = i + n*k
tal que0 <= n < (j-i)/k
. Em outras palavras, os índices sãoi
,i+k
,i+2*k
,i+3*k
e assim por diante, parando quando j for atingido (mas nunca incluindo j). Quando k for positivo, i e j serão reduzidos alen(s)
se forem maiores. Quando k for negativo, i e j são reduzidos paralen(s) - 1
se forem maiores. Se i ou j forem omitidos ouNone
, eles se tornam valores “finais” (cujo final depende de k). Nota: k não pode ser zero. Se k forNone
, o mesmo será tratado como sendo igual a1
.Concatenar sequências imutáveis sempre resulta em um novo objeto. Isso significa que a criação de uma sequência por concatenação repetida terá um custo quadrático de tempo de execução no comprimento total da sequência. Para obter um custo de tempo de execução linear, devemos alternar para uma das alternativas abaixo:
Se estiver concatenando objetos
str
, você pode criar uma lista e usarstr.join()
no final ou então escrever numa instância deio.StringIO
e recuperar o seu valor ao finalSe estiver concatenando objetos
bytes
, você também pode usar o métodobytes.join()
ouio.BytesIO
, ou você pode fazer concatenação interna com um objetobytearray
. A classebytearray
são objetos mutáveis e possuem um eficiente mecanismo de superalocaçãoSe estiver concatenando objetos
tuple
, estenda a classelist
em vez dissopara outros tipos, busque na documentação relevante da classe
Alguns tipos sequências (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.index
levantaValueError
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 usars[i:j].index(x)
, apenas sem copiar nenhum dado e com o índice retornado sendo relativo ao início da sequência e não ao início da fatia.
Tipos sequência imutáveis¶
A única operação que os tipos sequências imutáveis geralmente implementam que também não é implementada pelos tipos sequências mutáveis é suporte para a função embutida hash()
.
Esse suporte permite sequências imutáveis, tais como instâncias da classe tuple
, serem usadas como chaves de dicionários dict
e armazenados em instâncias de set
e de frozenset
.
A tentativa de obter um hash de uma sequência imutável que contém valores desnecessários resultará em um erro TypeError
.
Tipos sequências mutáveis¶
As operações na tabela a seguir são definidas em tipos sequência mutáveis. A ABC collections.abc.MutableSequence
é fornecida para tornar mais fácil a implementação correta dessas operações em tipos sequências personalizados.
Na tabela s é uma instância de um tipo de sequência mutável, t é qualquer objeto iterável e x é um objeto arbitrário que atende a qualquer restrição de tipo e valor imposto por s (por exemplo bytearray
só aceita inteiros que atendam a restrição de valor 0 <= x <= 255
).
Operação |
Resultado |
Notas |
---|---|---|
|
item i de s é substituído por x |
|
|
fatias de s de i até j são substituídas pelo conteúdo do iterável t |
|
|
o mesmo que |
|
|
os elementos de |
(1) |
|
remove os elementos de |
|
|
adiciona x no final da sequência (igual a |
|
|
remove todos os itens de s (mesmo que |
(5) |
|
cria uma cópia rasa de s (mesmo que |
(5) |
|
estende s com o conteúdo de t (na maior parte do mesmo |
|
|
atualiza s com o seu conteúdo por n vezes |
(6) |
|
insere x dentro de s no índice dado por i (igual a |
|
|
retorna o item em i e também remove-o de s |
(2) |
|
remove o primeiro item de s sendo |
(3) |
|
inverte os itens de s in-place |
(4) |
Notas:
t deve ter o mesmo comprimento que a fatia a qual ele está substituindo.
O argumento opcional i tem como padrão
-1
, de modo que, por padrão, o último item é removido e retornado.remove()
levantaValueError
quando x não é encontrado em s.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.clear()
ecopy()
estão incluídos para consistência com as interfaces de contêineres mutáveis que não suportam operações de fatiamento (comodict
eset
).copy()
não faz parte da ABC decollections.abc.MutableSequence
, mas a maioria das classes concretas de sequências mutáveis fornece isso.Novo na versão 3.3: Métodos
clear()
ecopy()
.O valor n é um inteiro, ou um objeto implementando
__index__()
. Valores zero e negativos de n limparão a sequência. Os itens na sequência não são copiados; eles são referenciados várias vezes, como explicado paras * n
em Operações comuns de sequências.
Listas¶
As listas são sequências mutáveis, normalmente usadas para armazenar coleções de itens homogêneos (onde o grau preciso de similaridade variará de acordo com a aplicação).
-
class
list
([iterable])¶ As listas podem ser construídas de várias maneiras:
Usando um par de colchetes para denotar uma lista vazia:
[]
Usando colchetes, separando itens por vírgulas:
[a]
,[a, b, c]
Usando uma compreensão de lista:
[x for x in iterable]
Usando o construtor de tipo:
list()
oulist(iterable)
O construtor produz uma lista cujos itens são iguais e na mesma ordem que os itens de iterable. iterable pode ser uma sequência, um contêiner que suporte iteração ou um objeto iterador. Se iterable já for uma lista, uma cópia será feita e retornada, semelhante a
iterable[:]
. Por exemplo,list('abc')
retorna['a', 'b', 'c']
elist( (1, 2, 3) )
retorna[1, 2, 3]
. Se nenhum argumento for dado, o construtor criará uma nova lista vazia[]
.Muitas outras operações também produzem listas, incluindo a função embutida
sorted()
.Listas implementam todas as operações de sequências comuns e mutáveis. As listas também fornecem o seguinte método adicional:
-
sort
(*, key=None, reverse=False)¶ Esse método classifica a lista in-place, usando apenas comparações
<
entre itens. As exceções não são suprimidas – se qualquer operação de comparação falhar, toda a operação de ordenação falhará (e a lista provavelmente será deixada em um estado parcialmente modificado).sort()
aceita 2 argumentos que só podem ser passados como argumentos somente-nomeados:key especifica uma função de um argumento que é usado para extrair uma chave de comparação de cada elemento da lista (por exemplo,
key=str.lower
). A chave correspondente a cada item na lista é calculada uma vez e depois usada para todo o processo de classificação. O valor padrãoNone
significa que os itens da lista são classificados diretamente sem calcular um valor de chave separado.A função utilitária
functools.cmp_to_key()
está disponível para converter a função cmp no estilo 2.x para uma função key.reverse é um valor booleano. Se definido igual a
True
, então os elementos da lista são classificados como se cada comparação estivesse invertida.Este método modifica a sequência in-place para economizar espaço ao classificar uma sequência grande. Para lembrar aos usuários que os mesmos operam por efeito colateral, ele não retorna a sequência ordenada (utilize a função
sorted()
para solicitar explicitamente uma nova instância da lista ordenada).O método
sort()
é garantido como sendo estável. Uma classificação é estável se ela garantir não alterar a ordem relativa de elementos que comparam igual – isso é útil para classificar em várias passagens (por exemplo, classificar por departamento, depois por nota salarial).Para exemplos de classificação e um breve tutorial de classificação, veja HowTo - Ordenação.
CPython implementation detail: No momento em que uma lista está sendo ordenada, o efeito de tentar alterar, ou mesmo inspecionar, a lista é indefinida. A implementação C do Python faz com que a lista apareça vazia durante o tempo de processamento, e levanta a exceção
ValueError
se puder detectar que a lista foi alterada durante uma ordenação.
Tuplas¶
Tuplas são sequências imutáveis, tipicamente usadas para armazenar coleções de dados heterogêneos (como as tuplas de 2 elementos produzidas pelo função embutida enumerate()
). Tuplas também são usadas para casos em que seja necessária uma sequência imutável de dados homogêneos (como permitir o armazenamento em uma instância set
ou dict
).
-
class
tuple
([iterable])¶ As tuplas podem ser construídas de várias maneiras:
Usando um par de parênteses para denotar a tupla vazia:
()
Usando uma vírgula à direita para uma tupla singleton:
a,
ou(a,)
Separando os itens com vírgulas:
a, b, c
ou(a, b, c)
Usando a função embutida
tuple()
:tuple()
outuple(iterable)
O construtor constrói uma tupla cujos itens são iguais e na mesma ordem dos itens de iterable. iterable pode ser uma sequência, um contêiner que suporta iteração ou um objeto iterador. Se iterable já for uma tupla, este será retornado inalterado. Por exemplo,
tuple('abc')
retorna('a', 'b', 'c')
etuple( [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 quef((a, b, c))
é uma chamada de função com uma tupla de 3 elementos com um único argumento.As tuplas implementam todas as operações comuns de sequência.
Para coleções heterogêneas de dados onde o acesso pelo nome é mais claro do que o acesso pelo índice, collections.namedtuple()
pode ser uma escolha mais apropriada do que um objeto tupla simples.
Intervalos¶
O tipo range
representa uma sequência imutável de números e é comumente usado para percorrer um número determinado de vezes em um laço for
.
-
class
range
(stop)¶ -
class
range
(start, stop[, step]) Os argumentos para o construtor de intervalo devem ser inteiros (
int
embutido ou qualquer objeto que implemente o método especial__index__()
). Se o argumento step for omitido, será usado o padrão1
. Se o argumento start for omitido, será usado o padrão0
. Se step for zero, uma exceçãoValueError
será levantada.Para um step positivo, o conteúdo de um intervalo
r
será determinado pela fórmular[i] = start + step*i
ondei >= 0
er[i] < stop
.Para um step negativo, o conteúdo do intervalo ainda será determinado pela fórmula
r[i] = start + step*i
, mas as restrições serãoi >= 0
er[i] > stop
.Um objeto intervalo estará vazio se
r[0]
não atender à restrição de valor. Intervalos suportam índices negativos, mas estes são interpretados como indexadores partindo do final da sequência determinada pelos índices positivos.Intervalos contendo valores absolutos maiores que
sys.maxsize
são permitidos, mas alguns recursos (comolen()
) podem levantarOverflowError
.Exemplos de intervalos:
>>> list(range(10)) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> list(range(1, 11)) [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> list(range(0, 30, 5)) [0, 5, 10, 15, 20, 25] >>> list(range(0, 10, 3)) [0, 3, 6, 9] >>> list(range(0, -10, -1)) [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] >>> list(range(0)) [] >>> list(range(1, 0)) []
Ranges implementam todas as operações comuns de sequência, exceto a concatenação e a repetição (devido ao fato de que os objetos intervalos só podem representar sequências que seguem um padrão rígido. e a repetição e a concatenação geralmente vão violar esse padrão).
-
start
¶ O valor do parâmetro start (ou
0
se o parâmetro não for fornecido)
-
stop
¶ O valor do parâmetro stop
-
step
¶ O valor do parâmetro step (ou
1
se o parâmetro não for fornecido)
-
A vantagem do tipo range
sobre um list
ou tuple
regular é que um objeto range
sempre terá a mesma quantidade (pequena) de memória, não importa o tamanho do intervalo o mesmo esteja representando (como ele apenas armazena os valores start
, stop
e step
, calculando itens individuais e subintervalos conforme necessário).
Objetos intervalos implementam a ABC collections.abc.Sequence
, e fornecem recursos como testes de contenção, pesquisa de índice de elemento, fatiamento e suporte a índices negativos (veja Tipos sequências — list, tuple, range):
>>> r = range(0, 20, 2)
>>> r
range(0, 20, 2)
>>> 11 in r
False
>>> 10 in r
True
>>> r.index(10)
5
>>> r[5]
10
>>> r[:5]
range(0, 10, 2)
>>> r[-1]
18
Testar objetos intervalos por igualdade com ==
e !=
os compara como sequências. Ou seja, dois objetos intervalos são considerados iguais se representarem a mesma sequência de valores. (Observe que dois objetos intervalos considerados iguais podem ter diferentes atributos start
, stop
e step
, por exemplo range(0) == range(2, 1, 3)
ou range(0, 3, 2) == range(0, 4, 2)
.)
Alterado na versão 3.2: Implementa a ABC Sequence. Suporte a fatiamento e a índices negativos. Testa objetos int
para associação em tempo constante em vez de iterar através de todos os itens.
Alterado na versão 3.3: Define ‘==’ e ‘!=’ para comparar objetos intervalos com base na sequência de valores que eles definem (em vez de comparar com base na identidade do objeto).
Ver também
A receita de linspace mostra como implementar uma versão preguiçosa de um intervalo adequado para aplicações de ponto flutuante.
Tipo sequência de texto — str
¶
Os dados textuais em Python são tratados com objetos str
, ou strings. Strings são sequências imutáveis de pontos de código Unicode. As strings literais são escritas de diversas maneiras:
Aspas simples:
'permitem aspas "duplas" internas'
Aspas duplas:
"permitem aspas 'simples' internas"
Aspas triplas:
'''Três aspas simples'''
,"""Três aspas duplas"""
Strings de aspas triplas podem expandir por várias linhas – todos os espaços em branco associados serão incluídos em literal string.
Os literais strings que fazem parte de uma única expressão e têm apenas espaços em branco entre eles serão implicitamente convertidos em um único literal string. Isso é, ("spam " "eggs") == "spam eggs"
.
Veja Literais de string e bytes para mais informações sobre as várias formas de literal de string, incluindo o suporte a strings de 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 string não vazia s, s[0] == s[0:1]
.
Também não existe um tipo string mutável, mas o método str.join()
ou a classe io.StringIO
podem ser usados para construir strings de forma eficiente a partir de vários partes distintas.
Alterado na versão 3.3: Para a compatibilidade com versões anteriores do Python 2, o prefixo u
foi mais uma vez permitido em literais strings. Não possui quaisquer efeito sobre o significado de literais strings e não pode ser combinado com o prefixo r
.
-
class
str
(object='')¶ -
class
str
(object=b'', encoding='utf-8', errors='strict') Retorna uma versão string de object. Se object não é fornecido, retorna uma string vazia. Caso contrário, o comportamento de
str()
dependerá se o encoding ou errors são fornecidos, da seguinte forma.Se nem o encoding nem os errors forem dados,
str(object)
retorna o métodotype(object).__str__(object)
, que é a representação de string “informal” ou que pode ser facilmente imprimível de object. Para objetos string, esta é a própria string. Se object não tiver um método__str__()
, então a funçãostr()
retornarárepr(object)
.Se pelo menos um de encoding ou errors for fornecido, object deve ser um objeto byte ou similar (por exemplo,
bytes
oubytearray
). Nesse caso, se object for um objetobytes
(oubytearray
), entãostr(bytes, encoding, errors)
será equivalente abytes.decode(encoding, errors)
. Caso contrário, o objeto byte subjacente ao objeto buffer é obtido antes de chamarbytes.decode()
. Veja Tipos de Sequência Binária — bytes, bytearray, memoryview e Protocolo de Buffer para obter informações sobre objetos buffer.Passando um objeto
bytes
parastr()
sem os argumentos encoding ou errors se enquadra no primeiro caso de retornar a representação informal de strings (consulte também a opção de linha de comando-b
para Python). Por exemplo:>>> str(b'Zoot!') "b'Zoot!'"
Para mais informações sobre a classe
str
e seus métodos, veja Tipo sequência de texto — str e a seção String Methods 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.
String Methods¶
Strings implementam todas as operações comuns de sequências, juntamente com os métodos adicionais descritos abaixo.
Strings também possuem suporte para duas formas de formatação de string, uma fornecendo uma ampla gama de flexibilidade e customização (veja str.format()
, Sintaxe das strings de formato e Formatação personalizada de strings) e a outra baseada no estilo de formatação printf
da linguagem C, que lida com uma gama menor de tipos e é levemente mais difícil de utilizar corretamente, mas é frequentemente mais rápida para os casos na qual ela consegue manipular (Formatação de String no Formato no estilo printf).
A seção Serviços de Processamento de Texto da biblioteca padrão cobre um número de diversos outros módulos que fornecem vários utilitários relacionados a texto (incluindo suporte a expressões regulares no módulo re
).
-
str.
capitalize
()¶ Retorna uma cópia da string com o seu primeiro caractere em maiúsculo e o restante em minúsculo.
Alterado na versão 3.8: O primeiro caractere agora é colocado em titlecase ao invés de letras maiúsculas. Isso significa que caracteres como dígrafos apenas terão sua primeira letra alterada para maiúscula, ao invés de todos os caracteres.
-
str.
casefold
()¶ Retorna uma cópia da string em casefolded. Strings em casefold podem ser usadas para corresponder letras sem importar se são minúsculas ou maiúsculas.
Casefolding é similar a mudar para letras minúsculas, mas mais agressivo porque destina-se a 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étodolower()
não irá fazer nada para'ß'
; já o métodocasefold()
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")¶ Retorna uma versão codificada da string como um objeto bytes. A codificação padrão é
'utf-8'
. errors 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 levantam uma exceçãoUnicodeError
. Outros valores possíveis são'ignore'
,'replace'
,'xmlcharrefreplace'
,'backslashreplace'
e qualquer outro nome registrado viacodecs.register_error()
, veja a seção Error Handlers. Para obter uma lista das possíveis codificações, consulte a seção Standard Encodings.Por padrão, o argumento errors não é verificado para obter os melhores desempenhos, mas apenas usado no primeiro erro de codificação. Habilite o Modo de Desenvolvimento do Python ou use uma construção de depuração para verificar errors.
Alterado na versão 3.1: Adicionado suporte para argumentos nomeados.
Alterado na versão 3.9: Os errors agora são verificados no modo de desenvolvimento e no modo de depuração.
-
str.
endswith
(suffix[, start[, end]])¶ Retorna
True
se a string terminar com o suffix especificado, caso contrário retornaFalse
. suffix também pode ser uma tupla de sufixos para procurar. Com o parâmetro opcional start, começamos a testar a partir daquela posição. Com o parâmetro opcional end, devemos parar de comparar na posição especificada.
-
str.
expandtabs
(tabsize=8)¶ Retorna uma cópia da string onde todos os caracteres de tabulação são substituídos por um ou mais espaços, dependendo da coluna atual e do tamanho fornecido para a tabulação. Posições de tabulação ocorrem a cada tabsize caracteres (o padrão é 8, dada as posições de tabulação nas colunas 0, 8, 16 e assim por diante). Para expandir a string, a coluna atual é definida como zero e a string é examinada caractere por caractere. Se o caractere é uma tabulação (
\t
), um ou mais caracteres de espaço são inseridos no resultado até que a coluna atual seja igual a próxima posição de tabulação. (O caractere de tabulação em si não é copiado.) Se o caractere é um caractere de nova linha (\n
) ou de retorno (\r
), ele é copiado e a coluna atual é redefinida para zero. Qualquer outro caractere é copiado sem ser modificado e a coluna atual é incrementada em uma unidade independentemente de como o caractere é representado quando é impresso.>>> '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]
. Argumentos opcionais como start e end são interpretados como na notação de fatiamento. Retorna-1
se sub não for localizado.
-
str.
format
(*args, **kwargs)¶ Executa uma operação de formatação de string. A string na qual este método é chamado pode conter texto literal ou campos para substituição delimitados por chaves
{}
. Cada campo de substituição contém um índice numérico de um argumento posicional ou o nome de um argumento nomeado. Retorna a cópia da string onde cada campo para substituição é substituído com o valor da string do argumento correspondente.>>> "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 uma strings de formato.
Nota
Ao formatar um número (
int
,float
,complex
,decimal.Decimal
e sub-classes) com o tipon
(ex:'{:n}'.format(1234)
), a função define temporariamente a localidadeLC_CTYPE
para a localidadeLC_NUMERIC
a fim de decodificar camposdecimal_point
ethousands_sep
delocaleconv()
se eles são caracteres não-ASCII ou maiores que 1 byte, e a localidadeLC_NUMERIC
é diferente da localidadeLC_CTYPE
. Esta mudança temporária afeta outras threads.Alterado na versão 3.7: Ao formatar um número com o tipo
n
, a função define temporariamente a localidadeLC_CTYPE
para a localidadeLC_NUMERIC
em alguns casos.
-
str.
format_map
(mapping)¶ Semelhante a
str.format(**mapping)
, exceto pelo fato de quemapping
é usado diretamente e não copiado para uma classedict
. 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]])¶ Senelhante a
find()
, mas levantaValueError
quando a substring não é encontrada.
-
str.
isalnum
()¶ Retorna
True
se todos os caracteres na string são alfanuméricos e existe pelo menos um caractere, ouFalse
caso contrário. Um caracterec
é alfanumérico se um dos seguintes retornaTrue
:c.isalpha()
,c.isdecimal()
,c.isdigit()
, ouc.isnumeric()
.
-
str.
isalpha
()¶ Retorna
True
se todos os caracteres na string são alfabéticos e existe pelo menos um caractere,False
caso contrário. Caracteres alfabéticos são aqueles caracteres definidos na base de dados de caracteres Unicode como “Letra”, isto é, aqueles cuja propriedade na categoria geral é um destes: “Lm”, “Lt”, “Lu”, “Ll” ou “Lo”. Perceba que isso é diferente da propriedade “Alfabética” definida no Unicode padrão.
-
str.
isascii
()¶ Retorna
True
se a string é vazia ou se todos os caracteres na string são ASCII,False
caso contrário. Caracteres ASCII têm pontos de código no intervalo U+0000-U+007F.Novo na versão 3.7.
-
str.
isdecimal
()¶ Retorna
True
se todos os caracteres na string são caracteres decimais e existe pelo menos um caractere,False
caso contrário. Caracteres decimais são aqueles que podem ser usados para formar números na base 10, exemplo U+0660, ou dígito zero para arábico-índico. Formalmente, um caractere decimal é um caractere em Unicode cuja categoria geral é “Nd”.
-
str.
isdigit
()¶ Retorna
True
se todos os caracteres na string são dígitos e existe pelo menos um caractere,False
caso contrário. Dígitos incluem caracteres decimais e dígitos que precisam de tratamento especial, tal como a compatibilidade com dígitos sobre-escritos. Isso inclui dígitos que não podem ser usados para formar números na base 10, como por exemplo os números de Kharosthi. Formalmente, um dígito é um caractere que tem a propriedade com valor Numeric_Type=Digit ou Numeric_Type=Decimal.
-
str.
isidentifier
()¶ Retorna
True
se a string é um identificador válido conforme a definição da linguagem, seção Identificadores e palavras-chave.Chame
keyword.iskeyword()
para testar se a strings
é uma palavra reservada, tal comodef
eclass
.Exemplo:
>>> from keyword import iskeyword >>> 'hello'.isidentifier(), iskeyword('hello') (True, False) >>> 'def'.isidentifier(), iskeyword('def') (True, True)
-
str.
islower
()¶ Retorna
True
se todos os caracteres em caixa (que possuem maiúsculo e minúsculo) 4 na string são minúsculos e existe pelo menos um caractere em caixa,False
caso contrário.
-
str.
isnumeric
()¶ Retorna
True
se todos os caracteres na string são caracteres numéricos, e existe pelo menos um caractere,False
caso contrário. Caracteres numéricos incluem dígitos, e todos os caracteres que têm a propriedade com valor numérico Unicode, isto é: U+2155, um quinto de fração vulgar. Formalmente, caracteres numéricos são aqueles que possuem propriedades com valor Numeric_Type=Digit, Numeric_Type=Decimal ou Numeric_Type=Numeric.
-
str.
isprintable
()¶ Retorna
True
se todos os caracteres na string podem ser impressos ou se a string é vazia,False
caso contrário. Caracteres que não podem ser impressos são aqueles que estão definidos no banco de dados de caracteres Unicode como “Outros” ou “Separadores”, exceto o caractere ASCII que representa o espaço (0x20), o qual é impresso. (Perceba que caracteres que podem ser impressos, neste contexto, são aqueles que não devem ser escapados quandorepr()
é invocada sobre uma string. Ela não tem sentido no tratamento de strings escritas usandosys.stdout
ousys.stderr
.)
-
str.
isspace
()¶ Retorna
True
se existem apenas caracteres de espaço em branco na string e existe pelo menos um caractere,False
caso contrário.Um caractere é espaço em branco se no banco de dados de caracteres Unicode (veja
unicodedata
), ou pertence a categoria geralZs
(“Separador, espaço”), ou sua classe bidirecional éWS
,B
ouS
.
-
str.
istitle
()¶ Retorna
True
se a string é titlecased e existe pelo menos um caractere, por exemplo caracteres maiúsculos somente podem proceder caracteres que não diferenciam maiúsculas/minúsculas, e caracteres minúsculos somente podem proceder caracteres que permitem ambos. RetornaFalse
caso contrário.
-
str.
isupper
()¶ Retorna
True
se todos os caracteres que permitem maiúsculas ou minúsculas 4 na string estão com letras maiúsculas, e existe pelo menos um caractere maiúsculo,False
caso contrário.>>> 'BANANA'.isupper() True >>> 'banana'.isupper() False >>> 'baNana'.isupper() False >>> ' '.isupper() False
-
str.
join
(iterable)¶ Retorna a string que é a concatenação das strings no iterável. Uma
TypeError
será levantada se existirem quaisquer valores que não sejam strings no iterável, incluindo objetosbytes
. O separador entre elementos é 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'
Consulte
str.removeprefix()
para um método que removerá uma única string de prefixo em vez de todo um conjunto de caracteres. Por exemplo:>>> 'Arthur: three!'.lstrip('Arthur: ') 'ee!' >>> 'Arthur: three!'.removeprefix('Arthur: ') 'three!'
-
static
str.
maketrans
(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 comprimento, 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 separador, e a parte após o separador. Se o separador não for encontrado, retorna uma tupla com 3 elementos contendo a string, seguido de duas strings vazias.
-
str.
removeprefix
(prefix, /)¶ Se a string começar com a string prefix, retorna
string[len(prefix):]
. Caso contrário, retorna uma cópia da string original:>>> 'TestHook'.removeprefix('Test') 'Hook' >>> 'BaseTestCase'.removeprefix('Test') 'BaseTestCase'
Novo na versão 3.9.
-
str.
removesuffix
(suffix, /)¶ Se a string terminar com a string suffix e a suffix não estiver vazia, retorna
string[:-len(suffix)]
. Caso contrário, retorna uma cópia da string original:>>> 'MiscTests'.removesuffix('Tests') 'Misc' >>> 'TmpDirMixin'.removesuffix('Tests') 'TmpDirMixin'
Novo na versão 3.9.
-
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 umValueError
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 separador, e a parte após o separador. Se o separador não for encontrado, retorna uma tupla com 3 elementos contendo duas strings vazias, seguido da própria string original.
-
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 comosplit()
, 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'
Consulte
str.removesuffix()
para um método que removerá uma única string de sufixo em vez de todo um conjunto de caracteres. Por exemplo:>>> 'Monty Python'.rstrip(' Python') 'M' >>> 'Monty Python'.removesuffix(' Python') 'Monty'
-
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 separadorNone
, 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=False)¶ Retorna uma lista das linhas na string, quebrando a mesma nas fronteiras de cada linha. Quebras de linhas não são incluídas na lista resultante a não ser que keepends seja fornecido e seja verdadeiro.
Este método divide nos seguintes limites das linhas. Em particular, os limites são um superconjunto de novas linhas universais.
Representação
Descrição
\n
Feed de linha
\r
Retorno de Carro
\r\n
Retorno do Carro + Feed da Linha
\v
ou\x0b
Tabulação de Linha
\f
ou\x0c
Formulário de Feed
\x1c
Separador de Arquivos
\x1d
Separador de Grupo
\x1e
Separador de Registro
\x85
Próxima Linha (C1 Control Code)
\u2028
Separador de Linha
\u2029
Separador de Parágrafo
Alterado na versão 3.2:
\v
e\f
adicionado à lista de limites de linha.Por exemplo:
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines() ['ab c', '', 'de fg', 'kl'] >>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True) ['ab c\n', '\n', 'de fg\r', 'kl\r\n']
Ao contrário do método
split()
quando um delimitador de String sep é fornecido, este método retorna uma lista vazia para a uma String vazia e uma quebra de linha de terminal não resulta numa linha extra:>>> "".splitlines() [] >>> "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, retornaFalse
. 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"
A função
string.capwords()
não tem esse problema, pois ela divide palavras apenas em espaços.Alternativamente, uma solução alternativa para os apóstrofes pode ser construída usando expressões regulares:
>>> import re >>> def titlecase(s): ... return re.sub(r"[A-Za-z]+('[A-Za-z]+)?", ... lambda mo: mo.group(0).capitalize(), ... s) ... >>> titlecase("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; retornarNone
, para deletar o caractere da string de retorno; ou levantar uma exceçãoLookupError
, 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 caractere customizado.
-
str.
upper
()¶ Retorna uma cópia da string com todos os caracteres que permitem maiúsculo e minúsculo 4 convertidos para letras maiúsculas. Perceba que
s.upper().isupper()
pode serFalse
ses
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 alen(s)
.Por exemplo:
>>> "42".zfill(5) '00042' >>> "-42".zfill(5) '-0042'
Formatação de String no Formato no estilo printf
¶
Nota
As operações de formatação descritas aqui exibem uma variedade de peculiaridades que levam a diversos erros comuns (tais como não conseguir exibir tuplas e dicionários corretamente). Usar o novo formatador de string literal (f-strings), a interface str.format()
, ou templates de strings pode ajudar a evitar esses erros. Cada uma dessas alternativas fornece seus próprios custos e benefícios de simplicidade, flexibilidade, e/ou extensibilidade.
Os objetos string possuem um único operador embutido: o operador %
(módulo). O mesmo também é conhecido como o operador de formatação ou interpolação. Dado format % values
(onde format é uma string), as especificações de conversão %
em format são substituídas por zero ou mais elementos de values. O efeito é semelhante ao uso da função sprintf()
na linguagem C.
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:
O caractere
'%'
, que determina o início do especificador.Mapeamento de Chaves (opcional), consistindo de uma sequência entre parênteses de caracteres (por exemplo,
(algumnome)
).Flags de conversão (opcional), que afetam o resultado de alguns tipos de conversão.
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.Precisão (opcional), fornecido como uma
'.'
(ponto) seguido pela precisão. Se determinado como um'*'
(um asterisco), a precisão real será lida a partir do próximo elemento da tupla em values, e o valor a converter virá após a precisão.Modificador de Comprimento(opcional).
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:
Sinalizador |
Significado |
---|---|
|
A conversão de valor usará o “formulário alternativo” (em que definimos abaixo). |
|
A conversão será preenchida por zeros para valores numéricos. |
|
O valor convertido será ajustado à esquerda (substitui a conversão |
|
(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 ( |
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 |
---|---|---|
|
Número decimal inteiro sinalizador. |
|
|
Número decimal inteiro sinalizador. |
|
|
Valor octal sinalizador. |
(1) |
|
Tipo obsoleto – é idêntico a |
(6) |
|
Sinalizador hexadecimal (minúsculas). |
(2) |
|
Sinalizador hexadecimal (maiúscula). |
(2) |
|
Formato exponencial de ponto flutuante (minúsculas). |
(3) |
|
Formato exponencial de ponto flutuante (maiúscula). |
(3) |
|
Formato decimal de ponto flutuante. |
(3) |
|
Formato decimal de ponto flutuante. |
(3) |
|
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) |
|
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) |
|
Caráter único (aceita inteiro ou um único caractere String). |
|
|
String (converte qualquer objeto Python usando a função |
(5) |
|
String (converte qualquer objeto Python usando a função |
(5) |
|
String (converte qualquer objeto Python usando a função |
(5) |
|
Nenhum argumento é convertido, resultando um caractere |
Notas:
A forma alternativa faz com que um especificador octal principal (
'0o'
) seja inserido antes do primeiro dígito.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.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.
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.
Se a precisão for
N
, a saída será truncada em caracteresN
.Veja PEP 237.
Como as Strings do Python possuem comprimento explícito, %s
as conversões não presumem que '\0'
é o fim da string.
Alterado na versão 3.1: %f
as conversões para números cujo valor absoluto é superior a 1e50 não são mais substituídas pela conversão %g
.
Tipos de Sequência Binária — bytes
, bytearray
, memoryview
¶
Os principais tipos embutidos para manipular dados binários são bytes
e bytearray
. Eles são suportados por memoryview
a qual usa o buffer protocol para acessar a memória de outros objetos binários sem precisar fazer uma cópia.
O módulo array
suporta armazenamento eficiente de tipos de dados básicos como inteiros de 32 bits e valores de ponto-flutuante com precisão dupla IEEE754.
Objetos Bytes¶
Objetos bytes são sequências imutáveis de bytes simples. Como muitos protocolos binários importantes são baseados em codificação ASCII de texto, objetos bytes oferecem diversos métodos que são válidos apenas quando trabalhamos com dados compatíveis com ASCII, e são proximamente relacionados com objetos string em uma variedade de outros sentidos.
-
class
bytes
([source[, encoding[, errors]]])¶ Em primeiro lugar, a sintaxe para literais de bytes é em grande parte a mesma para literais de String, exceto que um prefixo
b
é adicionado:Aspas simples:
b'still allows embedded "double" quotes'
Aspas duplas:
b"still allows embedded 'single' quotes"
Aspas triplas:
b'''3 single quotes'''
,b"""3 double quotes"""
Apenas caracteres ASCII são permitidos em literais de bytes (independentemente da codificação declarada). Qualquer valor binário superior a 127 deverá ser inserido em literais de bytes usando a sequência de escape apropriada.
Assim como string literais, bytes literais também podem usar um prefixo
r
para desabilitar o processamento de sequências de escape. Veja Literais de string e bytes para mais sobre as várias formas de bytes literais, incluindo suporte a sequências de escape.Enquanto bytes literais e representações são baseados em texto ASCII, objetos bytes na verdade se comportam como sequências imutáveis de inteiros, com cada valor na sequência restrito aos limites
0 <= x < 256
(tentativas de violar essa restrição irão dispararValueError
). Isto é feito deliberadamente para enfatizar que enquanto muitos formatos binários incluem elementos baseados em ASCII e podem ser utilmente manipulados com alguns algoritmos orientados a texto, esse não é geralmente o caso para dados binários arbitrários (aplicar algoritmos de processamento de texto cegamente em formatos de dados binários que não são compatíveis com ASCII irá usualmente resultar em dados corrompidos).Além das formas literais, os objetos bytes podem ser criados de várias outras maneiras:
Um bytes preenchido com objetos zero com um comprimento especificado:
bytes(10)
De um iterável de inteiros:
bytes(range(20))
Copiando dados binários existentes através do protocolo de Buffer:
bytes(obj)
Veja também os embutidos bytes.
Como 2 dígitos hexadecimais correspondem precisamente a apenas um byte, números hexadecimais são um formato comumente usado para descrever dados binários. Portanto, o tipo bytes tem um método de classe adicional para ler dados nesse formato:
-
classmethod
fromhex
(string)¶ Este método de classe da classe
bytes
retorna um objeto bytes, decodificando o objeto string fornecido. A string deve conter dois dígitos hexadecimais por byte, com espaço em branco ASCII sendo ignorado.>>> bytes.fromhex('2Ef0 F1f2 ') b'.\xf0\xf1\xf2'
Alterado na versão 3.7:
bytes.fromhex()
agora ignora todos os espaços em branco em ASCII na string, não apenas espaços.
Uma função de conversão reversa existe para transformar um objeto bytes na sua representação hexadecimal.
-
hex
([sep[, bytes_per_sep]])¶ Retorna um objeto string contendo dois dígitos hexadecimais para cada byte na instância.
>>> b'\xf0\xf1\xf2'.hex() 'f0f1f2'
Se você quiser tornar a string hexadecimal mais fácil de ler, você pode especificar um caractere separador através do parâmetro sep, que será incluído no resultado. Por padrão entre cada byte. Um segundo parâmetro opcional bytes_per_sep controla o espaçamento. Valores positivos calculam a posição do separador a partir da direita, valores negativos calculam a partir da esquerda.
>>> value = b'\xf0\xf1\xf2' >>> value.hex('-') 'f0-f1-f2' >>> value.hex('_', 2) 'f0_f1f2' >>> b'UUDDLRLRAB'.hex(' ', -4) '55554444 4c524c52 4142'
Novo na versão 3.5.
Alterado na versão 3.8:
bytes.hex()
agora suporta os parâmetros opcionais sep e bytes_per_sep para inserir separadores entre bytes na saída hexadecimal.
Como objetos bytes são sequências de inteiros (certo parentesco a uma tupla), para um objeto bytes b, b[0]
será um inteiro, enquanto b[0:1]
será um objeto bytes de comprimento 1. (Isso contrasta com strings de texto, onde tanto o uso por índice quanto por fatiamento irão produzir uma string de comprimento 1)
A representação de objetos bytes utiliza o formato literal (b'...'
), uma vez que ela é frequentemente mais útil do que, por exemplo, bytes([46, 46, 46])
. Você sempre pode converter um objeto bytes em uma lista de inteiros usando list(b)
.
Objetos Bytearray¶
Objetos bytearray
são mutáveis, em contrapartida a objetos bytes
.
-
class
bytearray
([source[, 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 sequência mutable além das operações comuns de bytes e bytearray descritas em Operações com Bytes e Bytearray.
Veja também o tipo embutido bytearray.
Uma vez que 2 dígitos hexadecimais correspondem precisamente a um único byte, os números hexadecimais são um formato comumente usado para descrever dados binários. Consequentemente, o tipo de bytearray tem um método de classe adicional para ler dados nesse formato:
-
classmethod
fromhex
(string)¶ Este método de classe da classe
bytearray
retorna um objeto bytearray, decodificando o objeto string fornecido. A string deve conter dois dígitos hexadecimais por byte, com espaços em branco ASCII sendo ignorados.>>> bytearray.fromhex('2Ef0 F1f2 ') bytearray(b'.\xf0\xf1\xf2')
Alterado na versão 3.7:
bytearray.fromhex()
agora ignora todos os espaços em branco em ASCII na string, não apenas espaços.
Existe uma função de conversão reversa para transformar um objeto bytearray em sua representação hexadecimal.
-
hex
([sep[, bytes_per_sep]])¶ 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.
Alterado na versão 3.8: Similar a
bytes.hex()
,bytearray.hex()
agora suporta os parâmetros opcionais sep e bytes_per_sep para inserir separadores entre bytes na saída hexadecimal.
Como os objetos bytearray são sequências de inteiros (semelhante a uma lista), para um objeto bytearray b, b[0]
será um inteiro, enquanto que b[0:1]
será um objeto bytearray de comprimento 1. (Isso contrasta com as Strings de texto, onde tanto a indexação como o fatiamento produzirão sequências de comprimento 1)
A representação de objetos bytearray utiliza o formato literal bytes (bytearray(b'...')
), uma vez que muitas vezes é mais útil do que, por exemplo, bytearray([46, 46, 46])
. Você sempre pode converter um objeto bytearray em uma lista de inteiros usando list(b)
.
Operações com Bytes e Bytearray¶
Ambos os tipos, bytes e os objetos bytearray suportam as operações de sequências comuns. Os mesmo interagem não apenas com operandos do mesmo tipo, mas com qualquer objeto byte ou similar. Devido a esta flexibilidade, os mesmos podem ser misturados livremente em operações sem causar erros. No entanto, o tipo de retorno do resultado pode depender da ordem dos operandos.
Nota
Os métodos em bytes e objetos Bytearray não aceitam Strings como argumentos, assim como os métodos de Strings não aceitam bytes como argumentos. Por exemplo, devemos escrever:
a = "abc"
b = a.replace("a", "f")
e:
a = b"abc"
b = a.replace(b"a", b"f")
Alguns operações com bytes e bytearray presumem o uso de formatos binários compatíveis com ASCII e, portanto, devem ser evitados ao trabalhar com dados binários arbitrários. Essas restrições são abordadas a seguir.
Nota
O uso dessas operações baseadas em ASCII para manipular dados binários que não são armazenados num formato baseado em ASCII poderá resultar na corrupção de dados.
Os métodos a seguir em Bytes e Bytearray podem ser usados com dados binários arbitrários.
-
bytes.
count
(sub[, start[, end]])¶ -
bytearray.
count
(sub[, start[, end]])¶ Retorna o número de ocorrências não sobrepostas de subsequência sub no intervalo [start, end]. Os argumentos opcionais start e end são interpretados como na notação de fatiamento.
A subsequência a ser procurada poderá ser qualquer objeto byte ou similar ou um inteiro no intervalo de 0 a 255.
Alterado na versão 3.3: Também aceita um número inteiro no intervalo de 0 a 255 como subsequência.
-
bytes.
removeprefix
(prefix, /)¶ -
bytearray.
removeprefix
(prefix, /)¶ Se os dados binários começarem com a string prefix, retorna
bytes[len(prefix):]
. Caso contrário, retorna uma cópia dos dados binários originais:>>> b'TestHook'.removeprefix(b'Test') b'Hook' >>> b'BaseTestCase'.removeprefix(b'Test') b'BaseTestCase'
O prefix pode ser qualquer objeto 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.
Novo na versão 3.9.
-
bytes.
removesuffix
(suffix, /)¶ -
bytearray.
removesuffix
(suffix, /)¶ Se os dados binários terminarem com a string suffix e a suffix não estiver vazia, retorna
bytes[:-len(suffix)]
. Caso contrário, retorna uma cópia dos dados binários originais:>>> b'MiscTests'.removesuffix(b'Tests') b'Misc' >>> b'TmpDirMixin'.removesuffix(b'Tests') b'TmpDirMixin'
O suffix pode ser qualquer objeto 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.
Novo na versão 3.9.
-
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'`
. errors pode ser fornecido para definir um esquema de tratamento de erros diferente. O padrão de errors é'strict'
, o que significa que os erros de codificação levantam uma exceçãoUnicodeError
. Outros valores possíveis são'ignore'`
,'replace'
e qualquer outro nome registrado pela funçãocodecs.register_error()
, veja a seção Error Handlers. Para obter uma lista dos possíveis codificações, veja a seção Standard Encodings.Por padrão, o argumento errors não é verificado para obter os melhores desempenhos, mas apenas usado no primeiro erro de decodificação. Habilite o Modo de Desenvolvimento do Python ou use uma construção de depuração para verificar errors.
Nota
Passando o argumento encoding para a classe
str
permite decodificar qualquer objeto byte ou similar diretamente, sem precisar ter bytes temporário ou um objeto bytearray.Alterado na versão 3.1: Adicionado suporte para argumentos nomeados.
Alterado na versão 3.9: Os errors agora são verificados no modo de desenvolvimento e no modo de depuração.
-
bytes.
endswith
(suffix[, start[, end]])¶ -
bytearray.
endswith
(suffix[, start[, end]])¶ Retorna
True
se os dados binários encerra com o parâmetro suffix especificado, caso contrário retornaFalse
. suffix também pode ser uma tupla de sufixos para averiguar. Com o parâmetro opcional start, a procura começa naquela posição. Com o parâmetro opcional end, o método encerra a comparação na posição fornecida.O sufixo(es) para buscas pode ser qualquer termos objeto byte ou similar.
-
bytes.
find
(sub[, start[, end]])¶ -
bytearray.
find
(sub[, start[, end]])¶ Retorna o índice mais baixo nos dados onde a sub-sequência sub é encontrada, tal que sub está contida na fatia
s[start:end]
. Argumentos opcionais start e end são interpretados como na notação de fatiamento. Retorna-1
se sub não for localizada.A subsequência a ser procurada poderá ser qualquer objeto byte ou similar ou um inteiro no intervalo de 0 a 255.
Nota
O método
find()
deve ser usado apenas se você precisa saber a posição de sub. Para verificar se sub é uma substring ou não, use o operadorin
:>>> 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çãoValueError
quando a subsequência não for encontrada.A subsequência a ser procurada poderá ser qualquer objeto byte ou similar ou um inteiro no intervalo de 0 a 255.
Alterado na versão 3.3: Também aceita um número inteiro no intervalo de 0 a 255 como subsequência.
-
bytes.
join
(iterable)¶ -
bytearray.
join
(iterable)¶ Retorna um objeto bytes ou bytearray que é a concatenação das sequências de dados binários no iterável. Um
TypeError
será levantado se existirem quaisquer valores que não sejam objeto byte ou similar, no iterável, incluindo objetosstr
. 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 separador, e a parte após o separador. Se o separador não for encontrado, retorna uma tupla com 3 elementos contendo uma cópia da sequência original, seguido de dois bytes ou objetos bytearray vazios.
O separador para buscar pode ser qualquer termos objeto byte ou similar.
-
bytes.
replace
(old, new[, count])¶ -
bytearray.
replace
(old, new[, count])¶ Retornar uma cópia da sequê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 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.
rfind
(sub[, start[, end]])¶ -
bytearray.
rfind
(sub[, start[, end]])¶ Retorna o índice mais alto na sequência onde a subsequência sub foi encontrada, de modo que sub esteja contido dentro de
s[start:end]
. Os argumentos opcionais start e end são interpretados como na notação de fatiamento. Caso ocorra algum problema será retornado-1
.A subsequência a ser procurada poderá ser qualquer objeto byte ou similar ou um inteiro no intervalo de 0 a 255.
Alterado na versão 3.3: Também aceita um número inteiro no intervalo de 0 a 255 como subsequência.
-
bytes.
rindex
(sub[, start[, end]])¶ -
bytearray.
rindex
(sub[, start[, end]])¶ Semelhante a
rfind()
mas levantaValueError
quando a subsequência sub não é encontrada.A subsequência a ser procurada poderá ser qualquer objeto byte ou similar ou um inteiro no intervalo de 0 a 255.
Alterado na versão 3.3: Também aceita um número inteiro no intervalo de 0 a 255 como subsequência.
-
bytes.
rpartition
(sep)¶ -
bytearray.
rpartition
(sep)¶ Quebra a sequência na primeira ocorrência de sep, e retorna uma tupla com 3 elementos contendo a parte antes do separador, o próprio separador, e a parte após o separador. Se o separador não for encontrado, retorna uma tupla com 3 elementos contendo dois bytes ou objetos bytearray vazios, seguido por uma cópia da sequência original.
O separador para buscar pode ser qualquer termos objeto byte ou similar.
-
bytes.
startswith
(prefix[, start[, end]])¶ -
bytearray.
startswith
(prefix[, start[, end]])¶ Retorna
True
se os dados binários começam com o prefix especificado, caso contrário retornaFalse
. prefix também pode ser uma tupla de prefixos para procurar. Com o parâmetro opcional start, começa a procura na posição indicada. Com o parâmetro opcional end, encerra a procura na posição indicada.Os prefixos para pesquisar podem ser qualquer objeto 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.
Você pode usar o método
bytes.maketrans()
para criar uma tabela de tradução.Define o argumento table como
None
para traduções que excluem apenas caracteres:>>> b'read this short text'.translate(None, b'aeiou') b'rd ths shrt txt'
Alterado na versão 3.6: delete agora é suportado como um argumento nomeado.
Os seguintes métodos de objetos bytes e bytearray tem comportamentos padrões que presumem o uso de formatos binários compatíveis com ASCII, mas ainda podem ser usados com dados binários arbitrários através da passagem argumentos apropriados. Perceba que todos os métodos de bytearray nesta seção não alteram os argumentos, e ao invés disso produzem novos objetos.
-
bytes.
center
(width[, fillbyte])¶ -
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 alen(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 alen(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 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 objeto byte ou similar. Consulte
removeprefix()
para um método que removerá uma única string de prefixo em vez de todo um conjunto de caracteres. Por exemplo:>>> b'Arthur: three!'.lstrip(b'Arthur: ') b'ee!' >>> b'Arthur: three!'.removeprefix(b'Arthur: ') b'three!'
Nota
A versão Bytearray deste método não opera no local – o mesmo sempre produz um novo objeto, mesmo que não tenha sido feitas alterações.
-
bytes.
rjust
(width[, fillbyte])¶ -
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 alen(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 comosplit()
, 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 objeto byte ou similar. Consulte
removesuffix()
para um método que removerá uma única string de sufixo em vez de todo um conjunto de caracteres. Por exemplo:>>> b'Monty Python'.rstrip(b' Python') b'M' >>> b'Monty Python'.removesuffix(b' Python') b'Monty'
Nota
A versão Bytearray deste método não opera no local – o mesmo sempre produz um novo objeto, mesmo que não tenha sido feitas alterações.
-
bytes.
split
(sep=None, maxsplit=-1)¶ -
bytearray.
split
(sep=None, maxsplit=-1)¶ Divide a sequência binária em subsequências do mesmo tipo, usando sep como o delimitador de string. Se maxsplit é fornecido e não-negativo, no máximo maxsplit divisões são feitas (logo, a lista terá no máximo
maxsplit+1
elementos). Se maxsplit não é especificado ou é-1
, então não existe limite no número de divisões (todas as divisões possíveis são feitas).Se sep é fornecido, delimitadores consecutivos não são agrupados juntos e eles são destinados para delimitar strings vazias (por exemplo
b'1,,2'.split(b',')
retorna[b'1', b'', b'2']
). O argumento sep pode consistir de uma sequência de múltiplos bytes (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 objeto byte ou similar.Por exemplo:
>>> b'1,2,3'.split(b',') [b'1', b'2', b'3'] >>> b'1,2,3'.split(b',', maxsplit=1) [b'1', b'2,3'] >>> b'1,2,,3,'.split(b',') [b'1', b'2', b'', b'3', b'']
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 presumem o uso de formatos binários compatíveis com ASCII e não devem ser aplicados a dados binários arbitrários. Perceba que todos os métodos de bytearray nesta seção não alteram os argumentos, e ao invés disso produzem novos objetos.
-
bytes.
capitalize
()¶ -
bytearray.
capitalize
()¶ Retorna uma cópia da sequência com cada byte interpretado como um caractere ASCII, e o primeiro byte em letra maiúscula e o resto em letras minúsculas. Valores de bytes que não são ASCII são passados adiante sem mudanças.
Nota
A versão Bytearray deste método não opera no local – o mesmo sempre produz um novo objeto, mesmo que não tenha sido feitas alterações.
-
bytes.
expandtabs
(tabsize=8)¶ -
bytearray.
expandtabs
(tabsize=8)¶ Retorna uma cópia da sequência onde todos os caracteres de tabulação ASCII são substituídos por um ou mais espaços ASCII, dependendo da coluna atual e do tamanho fornecido para a tabulação. Posições de tabulação ocorrem a cada tabsize bytes (o padrão é 8, dada as posições de tabulação nas colunas 0, 8, 16 e assim por diante). Para expandir a sequência, a coluna atual é definida como zero e a sequência é examinada byte por byte. Se o byte é um caractere ASCII de tabulação (
b'\t'
), um ou mais caracteres de espaço são inseridos no resultado até que a coluna atual seja igual a próxima posição de tabulação. (O caractere de tabulação em si não é copiado.) Se o byte atual é um caractere ASCII de nova linha (b'\n'
) ou de retorno (b'\r'
), ele é copiado e a coluna atual é redefinida para zero. Qualquer outro byte é copiado sem ser modificado e a coluna atual é incrementada em uma unidade independentemente de como o byte é representado quanto é impresso:>>> b'01\t012\t0123\t01234'.expandtabs() b'01 012 0123 01234' >>> b'01\t012\t0123\t01234'.expandtabs(4) b'01 012 0123 01234'
Nota
A versão Bytearray deste método não opera no local – o mesmo sempre produz um novo objeto, mesmo que não tenha sido feitas alterações.
-
bytes.
isalnum
()¶ -
bytearray.
isalnum
()¶ Retorna
True
se todos os bytes na sequência são caracteres alfabéticos ASCII ou dígitos decimais ASCII e a sequência não é vazia,False
caso contrário. Caracteres alfabéticos ASCII são aqueles valores de byte na sequênciab'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
. Dígitos decimais ASCII são aqueles valores de byte na sequênciab'0123456789'
.Por exemplo:
>>> b'ABCabc1'.isalnum() True >>> b'ABC abc1'.isalnum() False
-
bytes.
isalpha
()¶ -
bytearray.
isalpha
()¶ Retorna
True
se todos os bytes na sequência são caracteres alfabéticos ASCII e a sequência não é vazia,False
caso contrário. Caracteres alfabéticos ASCII são aqueles cujo valor dos bytes estão na sequênciab'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
.Por exemplo:
>>> b'ABCabc'.isalpha() True >>> b'ABCabc1'.isalpha() False
-
bytes.
isascii
()¶ -
bytearray.
isascii
()¶ Retorna
True
se a sequência é vazia ou todos os bytes na sequência são ASCII,False
caso contrário. Bytes ASCII estão no intervalo 0-0x7F.Novo na versão 3.7.
-
bytes.
isdigit
()¶ -
bytearray.
isdigit
()¶ Retorna
True
se todos os bytes na sequência são dígitos decimais ASCII e a sequência não é vazia,False
caso contrário. Dígitos decimais ASCII são aqueles cujos valores dos bytes estão na sequênciab'0123456789'
.Por exemplo:
>>> b'1234'.isdigit() True >>> b'1.23'.isdigit() False
-
bytes.
islower
()¶ -
bytearray.
islower
()¶ Retorna
True
se existe pelo menos um caractere minúsculo ASCII na sequência e nenhum caractere maiúsculo ASCII,False
caso contrário.Por exemplo:
>>> b'hello world'.islower() True >>> b'Hello world'.islower() False
Caracteres minúsculos ASCII são aqueles cujos valores de bytes estão na sequência
b'abcdefghijklmnopqrstuvwxyz'
. Caracteres maiúsculos ASCII são aqueles cujos valores de bytes estão na sequênciab'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
.
-
bytes.
isspace
()¶ -
bytearray.
isspace
()¶ Retorna
True
se todos os bytes na sequência são espaço em branco ASCII e a sequência não é vazia,False
caso contrário. Caracteres de espaço em branco ASCII são aqueles cujos valores de bytes estão na sequênciab' \t\n\r\x0b\f'
(espaço, tabulação, nova linha, retorno do cursor, tabulação vertical, formulário de entrada).
-
bytes.
istitle
()¶ -
bytearray.
istitle
()¶ Retorna
True
se a sequência é titlecased ASCII e a sequência não é vazia,False
caso contrário. Vejabytes.title()
para mais detalhes sobre a definição de “titlecased”.Por exemplo:
>>> b'Hello World'.istitle() True >>> b'Hello world'.istitle() False
-
bytes.
isupper
()¶ -
bytearray.
isupper
()¶ Retorna
True
se existe pelo menos um caractere maiúsculo alfabético ASCII na sequência e nenhum caractere minúsculo ASCII,False
caso contrário.Por exemplo:
>>> b'HELLO WORLD'.isupper() True >>> b'Hello world'.isupper() False
Caracteres minúsculos ASCII são aqueles cujos valores de bytes estão na sequência
b'abcdefghijklmnopqrstuvwxyz'
. Caracteres maiúsculos ASCII são aqueles cujos valores de bytes estão na sequênciab'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ênciab'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
.Nota
A versão Bytearray deste método não opera no local – o mesmo sempre produz um novo objeto, mesmo que não tenha sido feitas alterações.
-
bytes.
splitlines
(keepends=False)¶ -
bytearray.
splitlines
(keepends=False)¶ Retorna uma lista das linhas na sequência binária, quebrando nos limites ASCII das linhas. Este método usa a abordagem de novas linhas universais para separar as linhas. Quebras de linhas não são incluídas na lista resultante a não ser que keepends seja fornecido e verdadeiro.
Por exemplo:
>>> b'ab c\n\nde fg\rkl\r\n'.splitlines() [b'ab c', b'', b'de fg', b'kl'] >>> b'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True) [b'ab c\n', b'\n', b'de fg\r', b'kl\r\n']
Ao contrário de
split()
, quando uma string delimitadora sep é fornecida, este método retorna uma lista vazia para a string vazia, e uma quebra de linha terminal não resulta em uma linha extra:>>> b"".split(b'\n'), b"Two lines\n".split(b'\n') ([b''], [b'Two lines', b'']) >>> b"".splitlines(), b"One line\n".splitlines() ([], [b'One line'])
-
bytes.
swapcase
()¶ -
bytearray.
swapcase
()¶ Retorna uma cópia da sequência com todos os caracteres minúsculos ASCII convertidos para caracteres maiúsculos correspondentes, e vice-versa.
Por exemplo:
>>> b'Hello World'.swapcase() b'hELLO wORLD'
Caracteres minúsculos ASCII são aqueles cujos valores de bytes estão na sequência
b'abcdefghijklmnopqrstuvwxyz'
. Caracteres maiúsculos ASCII são aqueles cujos valores de bytes estão na sequênciab'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
.Ao contrário de
str.swapcase()
, é sempre fato quebin.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ênciab'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ênciab'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 objetosbytes
, a sequência original é retornada se width é menor que ou igual alen(seq)
.Por exemplo:
>>> b"42".zfill(5) b'00042' >>> b"-42".zfill(5) b'-0042'
Nota
A versão Bytearray deste método não opera no local – o mesmo sempre produz um novo objeto, mesmo que não tenha sido feitas alterações.
Estilo de Formatação de bytes printf
-style¶
Nota
As operações de formatação descritas aqui exibem uma variedade de peculiaridades que levam a uma série de erros comuns (como a falha na exibição de Tuplas e Dicionários corretamente). Se o valor que está sendo impresso puder ser uma tupla ou dicionário, envolva-o numa tupla.
Objetos Bytes (bytes
/bytearray
) possuem uma operação integrada exclusiva: o operador %
(modulo). Isso também é conhecido como o bytes de formatação ou o operador de interpolação. Dado format % values
(onde format é um objeto bytes), as especificações de conversão %
em format são substituídas por zero ou mais elementos de values. O efeito é semelhante ao uso da função sprintf()
na linguagem C.
Se format requer um único argumento, values poderá ser um único objeto não-tuple. 5 Caso contrário, values deverá ser uma tupla com exatamente o número de itens especificados pelo objeto de formatação de Bytes, ou um único objeto de mapeamento (por exemplo, um dicionário).
Um especificador de conversão contém dois ou mais caracteres e tem os seguintes componentes, que devem aparecer nesta ordem:
O caractere
'%'
, que determina o início do especificador.Mapeamento de Chaves (opcional), consistindo de uma sequência entre parênteses de caracteres (por exemplo,
(algumnome)
).Flags de conversão (opcional), que afetam o resultado de alguns tipos de conversão.
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.Precisão (opcional), fornecido como uma
'.'
(ponto) seguido pela precisão. Se determinado como um'*'
(um asterisco), a precisão real será lida a partir do próximo elemento da tupla em values, e o valor a converter virá após a precisão.Modificador de Comprimento(opcional).
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:
Sinalizador |
Significado |
---|---|
|
A conversão de valor usará o “formulário alternativo” (em que definimos abaixo). |
|
A conversão será preenchida por zeros para valores numéricos. |
|
O valor convertido será ajustado à esquerda (substitui a conversão |
|
(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 ( |
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 |
---|---|---|
|
Número decimal inteiro sinalizador. |
|
|
Número decimal inteiro sinalizador. |
|
|
Valor octal sinalizador. |
(1) |
|
Tipo obsoleto – é idêntico a |
(8) |
|
Sinalizador hexadecimal (minúsculas). |
(2) |
|
Sinalizador hexadecimal (maiúscula). |
(2) |
|
Formato exponencial de ponto flutuante (minúsculas). |
(3) |
|
Formato exponencial de ponto flutuante (maiúscula). |
(3) |
|
Formato decimal de ponto flutuante. |
(3) |
|
Formato decimal de ponto flutuante. |
(3) |
|
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) |
|
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) |
|
Byte simples (aceita objetos inteiros ou de byte único). |
|
|
Bytes (qualquer objeto que segue o buffer protocol o que possui |
(5) |
|
|
(6) |
|
Bytes (converte qualquer objeto Python usando |
(5) |
|
|
(7) |
|
Nenhum argumento é convertido, resultando um caractere |
Notas:
A forma alternativa faz com que um especificador octal principal (
'0o'
) seja inserido antes do primeiro dígito.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.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.
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.
Se a precisão for
N
, a saída será truncada em caracteresN
.b'%s'
está descontinuado, mas não será removido durante a versão 3.x.b'%r'
entrou em desuso, mas não serão removidos na versão 3.x.Veja PEP 237.
Nota
A versão Bytearray deste método não opera no local – o mesmo sempre produz um novo objeto, mesmo que não tenha sido feitas alterações.
Ver também
PEP 461 - Adicionar formatação % para to bytes e bytearray
Novo na versão 3.5.
Memory Views¶
O objeto memoryview
permite que o código Python acesse os dados internos de um objeto que suporte o buffer protocol sem copiá-lo.
-
class
memoryview
(object)¶ Cria uma
memoryview
que referencia object. object deve ter suporte ao protocolo de buffer. Objetos embutidos que suportam o protocolo de buffer incluembytes
ebytearray
.Uma
memoryview
tem a noção de um elemento, o qual é a unidade de memória atômica manipulada pelo objeto de origem object. Para muitos tipos simples tais comobytes
ebytearray
, um elemento é um byte único, mas outros tipos tais comoarray.array
podem ter elementos maiores.len(view)
é igual ao comprimento detolist
. Seview.ndim = 0
, o comprimento é 1. Seview.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 atributoitemsize
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ódulostruct
, 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 (somente leitura) com formatos ‘B’, ‘b’ ou ‘c’ também são hasheáveis. O hash é definido como
hash(m) == hash(m.tobytes())
:>>> v = memoryview(b'abcefg') >>> hash(v) == hash(b'abcefg') True >>> hash(v[2:4]) == hash(b'ce') True >>> hash(v[::-2]) == hash(b'abcefg'[::-2]) True
Alterado na versão 3.3: 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 portolist()
,v
ew
são iguais sev.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 emv == w
para objetos memoryview.Alterado na versão 3.3: Versões anteriores comparavam a memória bruta desconsiderando o formato do item e estrutura lógica do array.
-
tobytes
(order=None)¶ 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ódulostruct
.Novo na versão 3.8: order pode ser {‘C’, ‘F’, ‘A’}. Quando order é ‘C’ ou ‘F’, os dados do array original são convertidos para a ordem de C our Fortran. Para views contígua, ‘A’ retorna uma cópia exata da memória física. Em particular, ordem de Fortran em memória é preservada. Para views não contígua, os dados são convertidos primeiro para C. order=None é o mesmo que order=’C’.
-
hex
([sep[, bytes_per_sep]])¶ 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.
Alterado na versão 3.8: Similar a
bytes.hex()
,memoryview.hex()
agora suporta os parâmetros opcionais sep e bytes_per_sep para inserir separadores entre bytes na saída hexadecimal.
-
tolist
()¶ Retorna os dados no buffer como uma lista de elementos.
>>> memoryview(b'abc').tolist() [97, 98, 99] >>> import array >>> a = array.array('d', [1.1, 2.2, 3.3]) >>> m = memoryview(a) >>> m.tolist() [1.1, 2.2, 3.3]
-
toreadonly
()¶ Retorna uma versão somente leitura do objeto memoryview. O objeto memoryview original não é alterado.
>>> m = memoryview(bytearray(b'abc')) >>> mm = m.toreadonly() >>> mm.tolist() [89, 98, 99] >>> mm[0] = 42 Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: cannot modify read-only memory >>> m[0] = 43 >>> mm.tolist() [43, 98, 99]
Novo na versão 3.8.
-
release
()¶ Libera o buffer subjacente exposto pelo objeto memoryview. Muitos objetos aceitam ações especiais quando a view é mantida com eles (por exemplo, um
bytearray
iria temporariamente proibir o redimensionamento); portanto, chamar release() é útil para remover essas restrições (e liberar quaisquer recursos pendurados) o mais breve possível.Depois que este método foi chamado, qualquer operação posterior na visão levanta um
ValueError
(excetorelease()
, 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 visão resultante será unidimensional. O valor de retorno é uma nova memoryview, mas o buffer por si mesmo não é copiado. Conversões suportadas são 1D -> C-contíguo r C-contíguo -> 1D.O formato de destino é restrito a um elemento em formato nativo na sintaxe
struct
. Um dos formatos deve ser um formato de byte (‘B’, ‘b’ ou ‘c’). O comprimento de bytes do resultado deve ser o mesmo que o comprimento original.Converte de 1D/long para 1D/unsigned bytes:
>>> import array >>> a = array.array('l', [1,2,3]) >>> x = memoryview(a) >>> x.format 'l' >>> x.itemsize 8 >>> len(x) 3 >>> x.nbytes 24 >>> y = x.cast('B') >>> y.format 'B' >>> y.itemsize 1 >>> len(y) 24 >>> y.nbytes 24
Converte de 1D/unsigned bytes para 1D/char:
>>> b = bytearray(b'zyz') >>> x = memoryview(b) >>> x[0] = b'a' Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: memoryview: invalid value for format "B" >>> y = x.cast('c') >>> y[0] = b'a' >>> b bytearray(b'ayz')
Converte de 1D/bytes para 3D/ints para 1D/signed char:
>>> import struct >>> buf = struct.pack("i"*12, *list(range(12))) >>> x = memoryview(buf) >>> y = x.cast('i', shape=[2,2,3]) >>> y.tolist() [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]] >>> y.format 'i' >>> y.itemsize 4 >>> len(y) 2 >>> y.nbytes 48 >>> z = y.cast('b') >>> z.format 'b' >>> z.itemsize 1 >>> len(z) 48 >>> z.nbytes 48
Converte 1D/unsigned long para 2D/unsigned long:
>>> buf = struct.pack("L"*6, *list(range(6))) >>> x = memoryview(buf) >>> y = x.cast('L', shape=[2,3]) >>> len(y) 2 >>> y.nbytes 48 >>> y.tolist() [[0, 1, 2], [3, 4, 5]]
Novo na versão 3.3.
Alterado na versão 3.5: O formato fonte não é mais restrito ao converter para uma visão de byte.
Existem também diversos atributos somente leitura disponíveis:
-
obj
¶ O objeto subjacente da memoryview:
>>> b = bytearray(b'xyz') >>> m = memoryview(b) >>> m.obj is b True
Novo na versão 3.3.
-
nbytes
¶ nbytes == product(shape) * itemsize == len(m.tobytes())
. Este é a quantidade de espaço em bytes que o array deve usar em uma representação contígua. Ela não é necessariamente igual alen(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 quememoryview(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.
-
Tipo conjuntos — set
, frozenset
¶
Um objeto conjunto é uma coleção não ordenada de objetos hasheáveis distintos. Usos comuns incluem testes de associação, remover duplicatas de uma sequência e computar operações matemáticas tais como interseção, união, diferença e diferença simétrica. (Para outros tipos de contêineres veja as classes embutidas dict
, list
e tuple
, e o módulo collections
.)
Assim como outras coleções, conjuntos suportam x in set
, len(set)
e for x in set
. Sendo uma coleção não ordenada, conjuntos não armazenam posição de elementos ou ordem de inserção. Portanto, conjuntos não suportam indexação, fatiamento ou outros comportamentos de sequências ou similares.
Existem atualmente dois tipos de conjuntos embutidos, set
e frozenset
. O tipo set
é mutável – o conteúdo pode ser alterado usando métodos como add()
e remove()
. Como ele é mutável, ele não tem valor hash e não pode ser usado como chave de dicionário ou um elemento de um outro conjunto. O tipo frozenset
é imutável e hasheável – seu conteúdo não pode ser alterado depois de ter sido criado; ele pode então ser usado como chave de dicionário ou como um elemento de outro conjunto.
Conjuntos não vazios (que não sejam frozensets) podem ser criados posicionando uma lista de elementos separados por vírgula dentro de chaves, por exemplo: {'jack', 'sjoerd'}
, além do construtor set
.
Os construtores de ambas as classes funcionam da mesma forma:
-
class
set
([iterable])¶ -
class
frozenset
([iterable])¶ Retorna um novo objeto set ou frozenset, cujos elementos são obtidos a partir de um iterable. Os elementos de um conjunto devem ser hasheável. Para representar conjuntos de sets, os sets internos devem ser objetos
frozenset
. Se iterable não for especificado, um novo conjunto vazio é retornado.Conjuntos podem ser criados de várias formas:
Usar uma lista de elementos separados por vírgulas entre chaves:
{'jack', 'sjoerd'}
Usar uma compreensão de conjunto:
{c for c in 'abracadabra' if c not in 'abc'}
Usar o construtor de tipo:
set()
,set('foobar')
,set(['a', 'b', 'foo'])
Instâncias de
set
efrozenset
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 conjunto não tem elementos em comum com other. Conjuntos são disjuntos se e somente se a sua interseção é o conjunto vazio.
-
issubset
(other)¶ -
set <= other
Testa se cada elemento do conjunto está contido em other.
-
set < other
Testa se o conjunto é um subconjunto próprio de other, isto é,
set <= other and set != other
.
-
issuperset
(other)¶ -
set >= other
Testa se cada elemento em other está contido no conjunto.
-
set > other
Testa se o conjunto é um superconjunto próprio de other, isto é,
set >= other and set != other
.
-
union
(*others)¶ -
set | other | ...
Retorna um novo conjunto com elementos do conjunto e de todos os outros.
-
intersection
(*others)¶ -
set & other & ...
Retorna um novo conjunto com elementos comuns do conjunto e de todos os outros.
-
difference
(*others)¶ -
set - other - ...
Retorna um novo conjunto com elementos no conjunto que não estão nos outros.
-
symmetric_difference
(other)¶ -
set ^ other
Retorna um novo conjunto com elementos estejam ou no conjunto ou em other, mas não em ambos.
-
copy
()¶ Retorna uma cópia rasa do conjunto.
Observe que, as versões não-operador dos métodos
union()
,intersection()
,difference()
esymmetric_difference()
,issubset()
, eissuperset()
irão aceitar qualquer iterável como um argumento. Em contraste, suas contrapartes baseadas em operadores exigem que seus argumentos sejam conjuntos. Isso impede construções suscetíveis a erros comoset('abc') & 'cbs'
e favorece a forma mais legívelset('abc').intersection('cbs')
.Tanto
set
quantofrozenset
suportam comparar um conjunto com outro. Dois conjuntos são iguais se, e somente se, cada elemento de cada conjunto está contido no outro conjunto (cada um é um subconjunto do outro). Um conjunto é menor que outro se, e somente se, o primeiro conjunto é um subconjunto adequado do segundo (é um subconjunto, mas não é igual). Um conjunto é maior que outro conjunto se, e somente se, o primeiro conjunto é um superconjunto próprio do segundo conjunto (é um superconjunto, mas não é igual).Instâncias de
set
são comparadas a instâncias defrozenset
baseados nos seus membros. Por exemplo,set('abc') == frozenset('abc')
retornaTrue
e assim comoset('abc') in set([frozenset('abc')])
.O subconjunto e comparações de igualdade não generalizam para a função de ordenamento total. Por exemplo, quaisquer dois conjuntos deslocados não vazios, não são iguais e não são subconjuntos um do outro, então todos os seguintes retornam
False
:a<b
,a==b
oua>b
.Como conjuntos apenas definem ordenamento parcial (subconjunto de relacionamentos), a saída do método
list.sort()
é indefinida para listas e conjuntos.Elementos de conjuntos, assim como chaves de dicionário, devem ser hasheáveis.
Operações binárias que misturam instâncias de
set
comfrozenset
retornam o tipo do primeiro operando. Por exemplo:frozenset('ab') | set('bc')
retorna uma instância defrozenset
.A seguinte tabela lista operações disponíveis para
set
que não se aplicam para instâncias imutáveis defrozenset
:-
update
(*others)¶ -
set |= other | ...
Atualiza o conjunto, adicionando elementos dos outros.
-
intersection_update
(*others)¶ -
set &= other & ...
Atualiza o conjunto, mantendo somente elementos encontrados nele e em outros.
-
difference_update
(*others)¶ -
set -= other | ...
Atualiza o conjunto, removendo elementos encontrados em outros.
-
symmetric_difference_update
(other)¶ -
set ^= other
Atualiza o conjunto, mantendo somente elementos encontrados em qualquer conjunto, mas não em ambos.
-
add
(elem)¶ Adiciona o elemento elem ao conjunto.
-
remove
(elem)¶ Remove o elemento elem do conjunto. Levanta
KeyError
se elem não estiver contido no conjunto.
-
discard
(elem)¶ Remove o elemento elem do conjunto se ele estiver presente.
-
pop
()¶ Remove e retorna um elemento arbitrário do conjunto. Levanta
KeyError
se o conjunto estiver vazio.
-
clear
()¶ Remove todos os elementos do conjunto.
Perceba, as versões sem operador dos métodos
update()
,intersection_update()
,difference_update()
esymmetric_difference_update()
irão aceitar qualquer iterável como um argumento.Perceba, o argumento elem para os métodos
__contains__()
,remove()
ediscard()
pode ser um conjunto. Para suportar pesquisas por um frozenset equivalente, um frozenset temporário é criado a partir de elem.
Tipo mapeamento — dict
¶
Um objeto 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 contêineres, 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.)
-
class
dict
(**kwargs)¶ -
class
dict
(mapping, **kwargs) -
class
dict
(iterable, **kwargs) Retorna um novo dicionário inicializado a partir de um argumento posicional opcional, e um conjunto de argumentos nomeados possivelmente vazio.
Os dicionários podem ser criados de várias formas:
Usar uma lista de pares
key: value
separados por vírgula com chaves:{'jack': 4098, 'sjoerd': 4127}
ou{4098: 'jack', 4127: 'sjoerd'}
Usar uma compreensão de dicionário:
{}
,{x: x ** 2 for x in range(10)}
Usar o construtor de tipo:
dict()
,dict([('foo', 100), ('bar', 200)])
,dict(foo=100, bar=200)
Se nenhum argumento posicional é fornecido, um dicionário vazio é criado. Se um argumento posicional é fornecido e é 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}) >>> f = dict({'one': 1, 'three': 3}, two=2) >>> a == b == c == d == e == f True
Fornecer argumentos nomeados conforme no primeiro exemplo somente funciona para chaves que são identificadores válidos no Python. Caso contrário, quaisquer chaves válidas podem ser usadas.
Estas são as operações que dicionários suportam (e portanto, tipos de mapeamento personalizados devem suportar também):
-
list(d)
Retorna uma lista de todas as chaves usadas no dicionário d.
-
len(d)
Retorna o número de itens no dicionário d.
-
d[key]
Retorna o item de d com a chave key. Levanta um
KeyError
se key não estiver no mapeamento.Se uma subclasse de um dict define um método
__missing__()
e key não estiver presente, a operaçãod[key]
chama aquele método com a chave key como argumento. A operaçãod[key]
então retorna ou levanta o que é retornado ou levantado pela chamada de__missing__(key)
. Nenhuma operação ou métodos invocam__missing__()
. Se__missing__()
não for definido, entãoKeyError
é 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 paracollections.defaultdict
.
-
d[key] = value
Define
d[key]
para value.
-
del d[key]
Remove
d[key]
do d. Levanta uma exceçãoKeyError
se key não estiver no mapeamento.
-
key in d
Retorna
True
se d tiver uma chave key, caso contrárioFalse
.
-
key not in d
Equivalente a
not key in d
.
-
iter(d)
Retorna um iterador para as chaves do dicionário. Isso é um atalho para
iter(d.keys())
.
-
clear
()¶ Remove todos os itens do dicionário.
-
copy
()¶ Retorna uma cópia superficial do dicionário.
-
classmethod
fromkeys
(iterable[, value])¶ Cria um novo dicionário com chaves provenientes de iterable e valores definidos como value.
fromkeys()
é um método de classe que retorna um novo dicionário. value tem como valor padrãoNone
. Todos os valores referem-se a apenas uma única instância, então geralmente não faz sentido que value seja um objeto mutável tal como uma lista vazia. Para obter valores distintos, use uma compreensão de dicionário ao invés.
-
get
(key[, default])¶ 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 umKeyError
.
-
items
()¶ Retorna uma nova visão dos itens do dicionário (pares de
(key, value)
). Veja a documentação de objetos de visão de dicionário.
-
keys
()¶ Retorna uma nova visão das chaves do dicionário. Veja a documentação de objetos de visão de dicionário.
-
pop
(key[, default])¶ Se key está no dicionário, remove a mesma e retorna o seu valor, caso contrário retorna default. Se default não foi fornecido e key não está no dicionário, um
KeyError
é levantado.
-
popitem
()¶ Remove e retorna um par
(key, value)
do dicionário. Pares são retornados como uma pilha, ou seja em ordem LIFO.popitem()
é útil para destrutivamente iterar sobre um dicionário, algo comumente usado em algoritmos de conjunto. Se o dicionário estiver vazio, chamarpopitem()
levanta umKeyError
.Alterado na versão 3.7: Ordem LIFO agora é garantida. Em versões anteriores,
popitem()
iria retornar um par chave/valor arbitrário.
-
reversed(d)
Retorna um iterador revertido sobre as chaves do dicionário. Isso é um atalho para
reversed(d.keys())
.Novo na versão 3.8.
-
setdefault
(key[, default])¶ Se key está no dicionário, retorna o seu valor. Se não, insere key com o valor default e retorna default. default por padrão usa o valor
None
.
-
update
([other])¶ Atualiza o dicionário com os pares chave/valor existente em other, sobrescrevendo chaves existentes. Retorna
None
.update()
aceita ou outro objeto dicionário, ou um iterável de pares de chave/valor (como tuplas ou outros iteráveis de comprimento dois). Se argumentos nomeados são especificados, o dicionário é então atualizado com esses pares de chave/valor:d.update(red=1, blue=2)
.
-
values
()¶ Retorna uma nova visão dos valores do dicionário. Veja a documentação de objetos de visão de dicionário.
Uma comparação de igualdade entre uma visão de
dict.values()
e outra, sempre irá retornarFalse
. Isso também se aplica ao comparardict.values()
entre si:>>> d = {'a': 1} >>> d.values() == d.values() False
-
d | other
Cria um novo dicionário com as chaves e os valores mesclados de d e other, que devem ser dicionários. Os valores de other têm prioridade quando d e other compartilham chaves.
Novo na versão 3.9.
-
d |= other
Atualiza o dicionário d com chaves e valores de other, que podem ser a mapeamento ou um iterável dos pares chave/valor. Os valores de other têm prioridade quando d e other compartilham chaves.
Novo na versão 3.9.
Dicionários são iguais se e somente se eles os mesmos pares
(key, value)
(independente de ordem). Comparações de ordem (‘<’, ‘<=’, ‘>=’, ‘>’) levantamTypeError
.Dicionários preservam a ordem de inserção. Perceba que atualizar a chave não afeta a ordem. Chaves adicionadas após a deleção são inseridas no final.
>>> d = {"one": 1, "two": 2, "three": 3, "four": 4} >>> d {'one': 1, 'two': 2, 'three': 3, 'four': 4} >>> list(d) ['one', 'two', 'three', 'four'] >>> list(d.values()) [1, 2, 3, 4] >>> d["one"] = 42 >>> d {'one': 42, 'two': 2, 'three': 3, 'four': 4} >>> del d["two"] >>> d["two"] = None >>> d {'one': 42, 'three': 3, 'four': 4, 'two': None}
Alterado na versão 3.7: Ordem do dicionário é garantida conforme a ordem de inserção. Este comportamento era um detalhe de implementação do CPython a partir da versão 3.6.
Dicionários e visões de dicionários são reversíveis.
>>> d = {"one": 1, "two": 2, "three": 3, "four": 4} >>> d {'one': 1, 'two': 2, 'three': 3, 'four': 4} >>> list(reversed(d)) ['four', 'three', 'two', 'one'] >>> list(reversed(d.values())) [4, 3, 2, 1] >>> list(reversed(d.items())) [('four', 4), ('three', 3), ('two', 2), ('one', 1)]
Alterado na versão 3.8: Dicionários agora são reversíveis.
Ver também
types.MappingProxyType
podem ser usados para criar uma visão somente leitura de um dict
.
Objetos de visão de dicionário¶
Os objetos retornados por dict.keys()
, dict.values()
e dict.items()
são objetos de visão. Eles fornecem uma visão dinâmica das entradas do dicionário, o que significa que quando o dicionário muda, a visão reflete essas mudanças.
Visões de dicionários podem ser iteradas para apresentar seus respectivos dados, e suportar testes de existência:
-
len(dictview)
Retorna o número de entradas no dicionário.
-
iter(dictview)
Retorna um iterador sobre as chaves, valores ou itens (representados como tuplas de
(key, value)
) no dicionário.Chaves e valores são iterados em ordem de inserção. Isso permite a criação de pares
(value, key)
usandozip()
:pairs = zip(d.values(), d.keys())
. Outra maneira de criar a mesma lista épairs = [(v, k) for (k, v) in d.items()]
.Iterar sobre visões enquanto adiciona ou deleta entradas no dicionário pode levantar um
RuntimeError
ou falhar a iteração sobre todas as entradas.Alterado na versão 3.7: Ordem do dicionário é garantida como a ordem de inserção.
-
x in dictview
Retorna
True
se x está nas chaves, valores ou itens do dicionário subjacente (no último caso, x deve ser uma tupla de(key, value)
).
-
reversed(dictview)
Retorna um iterador reverso sobre as chaves, valores ou itens do dicionário. A visão será iterada na ordem reversa de inserção.
Alterado na versão 3.8: Visões de dicionário agora são reversíveis.
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 (key, value)
são únicos e hasheáveis, então a visão dos itens também é um similar a conjunto. (Visões de valores não são tratadas de como similar a conjunto, pois as entradas geralmente não são únicas.) Para visões similares a conjunto, todas as operações definidas para a classe base abstrata collections.abc.Set
estão disponíveis (por exemplo, ==
, <
, ou ^
).
Um exemplo da utilização da visualização de dicionário:
>>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
>>> keys = dishes.keys()
>>> values = dishes.values()
>>> # iteration
>>> n = 0
>>> for val in values:
... n += val
>>> print(n)
504
>>> # keys and values are iterated over in the same order (insertion order)
>>> list(keys)
['eggs', 'sausage', 'bacon', 'spam']
>>> list(values)
[2, 1, 1, 500]
>>> # view objects are dynamic and reflect dict changes
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['bacon', 'spam']
>>> # set operations
>>> keys & {'eggs', 'bacon', 'salad'}
{'bacon'}
>>> keys ^ {'sausage', 'juice'}
{'juice', 'sausage', 'bacon', 'spam'}
Tipos de Gerenciador de Contexto¶
A instrução with
do Python suporta o conceito de um contexto em tempo de execução definido por um gerenciador de contexto. Isto é implementado usando um par de métodos, que permitem que classes definidas pelo usuário especifiquem um contexto em tempo de execução, o qual é inicializado antes da execução das instruções, e encerrado quando as instruções terminam:
-
contextmanager.
__enter__
()¶ Entra no contexto em tempo de execução e retorna este objeto ou outro objeto relacionado ao contexto em tempo de execução. O valor retornado por este método é ligado ao identificador na cláusula
as
das instruçõeswith
usando este gerenciador de contexto.Um exemplo de gerenciador de contexto que retorna a si mesmo é um objeto arquivo. Objeto arquivos retornam a si mesmos do método __enter__() para permitir que
open()
seja usado como a expressão de contexto em uma instruçãowith
.Um exemplo de gerenciador de contexto que retorna um objeto relacionado é aquele retornado por
decimal.localcontext()
. Esses gerenciadores definem o contexto decimal ativo para uma cópia do contexto decimal original, e então retornam a cópia. Isso permite que mudanças sejam feitas no contexto decimal atual, no corpo contido na instruçãowith
, sem afetar o código fora da instruçãowith
.
-
contextmanager.
__exit__
(exc_type, exc_val, exc_tb)¶ Sai do contexto em tempo de execução e retorna um sinalizador booleano indicando se qualquer exceção que ocorreu deve ser suprimida. Se uma exceção ocorreu enquanto era executado o corpo da instrução
with
, os argumentos contêm o tipo da exceção, valor e informação da traceback (situação da pilha de execução). Caso contrário, os três argumentos sãoNone
.Retornar um valor verdadeiro deste método fará com que a instrução
with
suprima a exceção e continue a execução com a instrução imediatamente após a instruçãowith
. Caso contrário a exceção continuará propagando após este método ter encerrado sua execução. Exceções que ocorrerem durante a execução deste método irão substituir qualquer exceção que tenha ocorrido dentro do corpo da instruçãowith
.A exceção passada nunca deve ser re-levantada explicitamente - ao invés disso, este método deve retornar um valor falso para indicar que o método completou sua execução com sucesso, e não quer suprimir a exceção levantada. Isso permite ao código do gerenciador de contexto facilmente detectar se um método
__exit__()
realmente falhou ou não.
Python define diversos gerenciadores de contexto para suportar facilmente sincronização de threads, solicita o fechamento de arquivos ou outros objetos, e manipula de forma simples o contexto ativo de aritmética decimal. Os tipos especificados não são tratados de forma especial além da sua implementação e do protocolo do gerenciador de contexto. Veja o módulo contextlib
para alguns exemplos.
Os geradores do Python e o decorador contextlib.contextmanager
fornecem uma maneira conveniente de implementar esses protocolos. Se uma função geradora for decorada com o decorador contextlib.contextmanager
, ela retornará um gerenciador de contexto implementando os métodos necessários __enter__()
e __exit__()
, em vez de o iterador produzido por uma função geradora não decorada.
Observe que não existe nenhum slot específico para qualquer um desses métodos na estrutura de tipos para objetos Python na API Python/C. Tipos de extensão que desejam definir estes métodos devem fornecê-los como um método acessível normal do Python. Comparado com a sobrecarga de configurar o contexto em tempo de execução, a sobrecarga na pesquisa de dicionário em uma única classe é negligenciável.
Tipo Generic Alias¶
Objetos GenericAlias
são geralmente criados subscrevendo uma classe. Eles são mais usados com classes contêineres, como list
ou dict
. Por exemplo, list[int]
é um objeto GenericAlias
criado pela subscrição da classe list
com o argumento int
. Objetos GenericAlias
são destinados principalmente para uso com anotações de tipo.
Nota
Geralmente só é possível subscrever uma classe se a classe implementar o método especial __class_getitem__()
.
Um objeto GenericAlias
atua como um proxy para um tipo genérico, implementando genéricos parametrizados.
Para uma classe contêiner, o(s) argumento(s) fornecido(s) para uma subscrição da classe pode indicar o(s) tipo(s) dos elementos que um objeto contém. Por exemplo, set[bytes]
pode ser usado em anotações de tipo para significar um set
em que todos os elementos são do tipo bytes
.
Para uma classe que define __class_getitem__()
, mas não é um contêiner, o(s) argumento(s) fornecido(s) para uma subscrição da classe geralmente indicará o(s) tipo(s) de retorno de um ou mais métodos definidos em um objeto. Por exemplo, expressões regulares
podem ser usadas tanto no tipo de dados str
quanto no tipo de dados bytes
:
Se
x = re.search('foo', 'foo')
,x
será um objeto re.Match onde os valores de retorno dex.group(0)
ex[0]
serão ambos do tipostr
. Podemos representar este tipo de objeto em anotações de tipo com oGenericAlias
re.Match[str]
.Se
y = re.search(b'bar', b'bar')
(observe ob
parabytes
),y
também será uma instância dere.Match
, mas os valores de retorno dey.group(0)
ey[0]
serão ambos do tipobytes
. Em anotações de tipo, representaríamos esta variedade de objetos re.Match comre.Match[bytes]
.
Objetos GenericAlias
são instâncias da classe types.GenericAlias
, que também podem ser usadas para criar objetos GenericAlias
diretamente.
-
T[X, Y, ...]
Cria um
GenericAlias
representando um tipoT
parametrizado por tipos X, Y e mais, dependendo doT
usados. Por exemplo, uma função esperando umalist
contendo elementosfloat
:def average(values: list[float]) -> float: return sum(values) / len(values)
Outro exemplo para mapeamento de objetos, usando um
dict
, o qual é um tipo genérico esperando 2 tipos de parâmetros representando o tipo da chave e o tipo do valor. Neste exemplo, a função espera umdict
com chaves do tipostr
e valores do tipoint
:def send_post_request(url: str, body: dict[str, int]) -> None: ...
As funções embutidas isinstance()
e issubclass()
não aceitam tipos GenericAlias
para o seu segundo argumento:
>>> isinstance([1, 2], list[str])
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot be a parameterized generic
O runtime Python não obriga anotações de tipo. Isso se aplica a tipos genéricos e seus parâmetros tipados. Ao criar um objeto contêiner a partir de um GenericAlias
, os elementos no contêiner não são verificados pelo seu tipo. Por exemplo, o seguinte código é desencorajado, mas irá executar sem erros:
>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]
Além disso, genéricos parametrizados removem parâmetros tipados durante a criação do objeto:
>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>
>>> l = t()
>>> type(l)
<class 'list'>
Chamar repr()
ou str()
sobre um genérico mostra o tipo parametrizado:
>>> repr(list[int])
'list[int]'
>>> str(list[int])
'list[int]'
O método __getitem__()
de contêineres genéricos irá levantar uma exceção para não permitir erros como dict[str][str]
:
>>> dict[str][str]
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: There are no type variables left in dict[str]
Entretanto, tais expressões são válidas quando type variáveis são usadas. O índice deve ter tantos elementos quantos forem os itens de variável de tipo no objeto GenericAlias
__args__
.
>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]
Classes genéricas padrão¶
As seguintes classes de biblioteca padrão oferecem suporte a genéricos parametrizados. Esta lista não é exaustiva.
Atributos especiais de objetos GenericAlias
¶
Todos os genéricos parametrizados implementam atributos especiais somente leitura.
-
genericalias.
__origin__
¶ Este atributo aponta para a classe genérica não parametrizada:
>>> list[int].__origin__ <class 'list'>
-
genericalias.
__args__
¶ Este atributo é uma
tuple
(possivelmente de comprimento 1) de tipos genéricos passado para o método__class_getitem__()
original da classe genérica:>>> dict[str, list[int]].__args__ (<class 'str'>, list[int])
-
genericalias.
__parameters__
¶ O atributo é uma tupla computada preguiçosamente (possivelmente vazia) de variáveis de tipo único encontradas em
__args__
:>>> from typing import TypeVar >>> T = TypeVar('T') >>> list[T].__parameters__ (~T,)
Ver também
- PEP 484 - Dicas de tipo
Apresentando a estrutura do Python para anotações de tipo.
- PEP 585 - Sugestão de tipo para Genéricos em coleções padrão
Apresentando a capacidade de parametrizar nativamente as classes da biblioteca padrão, desde que implementem o método de classe especial
__class_getitem__()
.- Genéricos, genéricos definidos pelo usuário e
typing.Generic
Documentação sobre como implementar classes genéricas que podem ser parametrizadas em tempo de execução e compreendidas por verificadores de tipo estático.
Novo na versão 3.9.
Outros tipos embutidos¶
O interpretador suporta diversos outros tipos de objetos. Maior parte desses, suporta apenas uma ou duas operações.
Módulos¶
A única operação especial em um módulo é o acesso a um atributo: m.name
, onde m é um módulo e name acessa o nome defino na tabela de símbolos de m. Atributos de módulo podem receber atribuição. (Perceba que a instrução import
não é, estritamente falando, uma operação em um objeto do módulo; import foo
não requer que um objeto do módulo chamado foo exista, ao invés disso requer uma definição (externa) de um módulo chamado foo em algum lugar.)
Um atributo especial de cada módulo é __dict__
. Este é o dicionário contendo a tabela de símbolos do modulo. Modificar este dicionário vai na verdade modificar a tabela de símbolos do módulo, mas atribuição direta para o atributo __dict__
não é possível (você pode escrever m.__dict__['a'] = 1
, o qual define m.a
para ser 1
, mas você não consegue escrever m.__dict__ = {}
). Modificar __dict__
diretamente não é recomendado.
Módulos embutidos no interpretador são escritos desta forma: <module 'sys' (built-in)>
. Se carregados a partir de um arquivo, eles são escritos como <module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>
.
Classes e Instâncias de Classes¶
Veja Objetos, valores e tipos e Definições de classe para estes.
Funções¶
Objetos função são criados através da definição de funções. A única operação que pode ser feita em um objeto função é chamá-la: func(lista-de-argumentos)
.
Existem na verdade duas possibilidades de objetos função: funções embutidas e funções definidas pelo usuário. Ambas suportam a mesma operação (chamar a função), mas a implementação é diferente, portanto os diferentes tipos de objetos.
Veja a função Definições de função para mais informações.
Métodos¶
Métodos são funções que são chamadas usando a notação de atributo. Existem duas opções: métodos embutidos (tal como append()
em listas) e métodos de instância de classe. Métodos embutidos são descritos com os tipos que 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 com método vinculado (também chamado de método de instância). Quando chamado, ele irá adicionar o argumento self
para a lista de argumentos. Métodos vinculados tem dois atributos somente leitura especiais: m.__self__
é o objeto no qual o método opera, e m.__func__
é a função que implementa o método. Chamar m(arg-1, arg-2, ..., arg-n)
é completamente equivalente a chamar m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)
.
Assim como objetos função, objetos de métodos vinculados tem suporte para receber atributos arbitrários. Entretanto, como atributos de método na verdade são armazenados no objeto função subjacente (meth.__func__
), definir atributos de método em métodos vinculados não é permitido. Tentar definir um atributo em um método resulta em um AttributeError
sendo levantado. A fim de definir um atributo de método, você precisa definir explicitamente ele no objeto função subjacente:
>>> class C:
... def method(self):
... pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method' # can't set on the method
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'
Veja o tipo A hierarquia de tipos padrão para maiores informações.
Objetos código¶
Objetos código são usados pela implementação para representar código Python executável “pseudo-compilado”, tal como corpo de uma função. Eles são diferentes de objetos função porque eles não contém uma referência para os seus ambientes de execução global. Objetos código são retornados pela função embutida compile()
e podem ser extraídos de objetos função através do seu atributo __code__
. Veja também o módulo code
.
Acessar __code__
levanta um evento de auditoria object.__getattr__
com argumentos obj
e "__code__"
.
Um objeto de código pode ser executado ou avaliado passando-o (ao invés da string fonte) para as funções embutidas exec()
ou eval()
.
Veja o tipo A hierarquia de tipos padrão para maiores informações.
Objetos tipo¶
Objetos de tipos representam os vários tipos de objetos. Um tipo de um objeto é acessado pela função embutida type()
. Não existem operações especiais sobre tipos. O módulo padrão types
define nomes para todos os tipos padrão embutidos.
Tipos são escritos como isto: <class 'int'>
.
O objeto nulo¶
Este objeto é retornado por funções que não retornam um valor explicitamente. Ele não suporta operações especiais. Existe exatamente um objeto nulo, chamado de None
(um nome embutido). type(None)()
produz o mesmo singleton.
Ele é escrito como None
.
O Objeto Ellipsis¶
Este objeto é comumente usado através de fatiamento (veja Fatiamentos). Ela não suporta operações especiais. Existe exatamente um objeto ellipsis, nomeado Ellipsis
(um nome embutido). type(Ellipsis)()
produz o singleton Ellipsis
.
Está escrito com Ellipsis
ou ...
.
O Objeto NotImplemented¶
Este objeto é retornado a partir de comparações e operações binárias quando elas são solicitadas para operar em tipos nos quais eles não suportam. Veja Comparações para mais informações. Existe exatamente um objeto NotImplemented
. type(NotImplemented)()
produz o mesmo valor.
Está escrito como NotImplemented
.
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 operador 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 booleano, se o valor puder ser interpretado como um valor verdadeiro (veja a seção Teste do valor verdade acima).
Eles são escritos como False
e True
, respectivamente.
Objetos Internos¶
Veja A hierarquia de tipos padrão para esta informação. Ela descreve objetos de stack frame, objetos de traceback, e fatias de objetos.
Atributos Especiais¶
A implementação adiciona alguns atributos especiais somente leitura para diversos tipos de objetos, onde eles são relevantes. Alguns desses não são reportados pela função embutida dir()
.
-
object.
__dict__
¶ Um dicionário ou outro objeto de mapeamento usado para armazenar os atributos (graváveis) de um objeto.
-
instance.
__class__
¶ A classe à qual pertence uma instância de classe.
-
class.
__bases__
¶ A tupla de classes base de um objeto classe.
-
definition.
__name__
¶ O nome da classe, função, método, descritor, ou instância geradora.
-
definition.
__qualname__
¶ O nome qualificado da classe, função, método, descritor, ou instância geradora.
Novo na versão 3.3.
-
class.
__mro__
¶ Este atributo é uma tupla de classes que são consideradas ao procurar por classes bases durante resolução de métodos.
-
class.
mro
()¶ Este método pode ser substituído por uma metaclasse para customizar a ordem de resolução de métodos para suas instâncias. Ele é chamado na instanciação da classe, e o seu resultado é armazenado em
__mro__
.
-
class.
__subclasses__
()¶ Cada classe mantém uma lista de referências fracas para suas subclasses imediatas. Este método retorna uma lista de todas essas referências ainda vivas. A lista está na ordem que são definidas. Exemplo:
>>> int.__subclasses__() [<class 'bool'>]
Limitação de comprimento de string na conversão para inteiro¶
CPython tem um limite global para conversão entre int
e str
para mitigar ataques de negação de serviço. Esse limite somente se aplica a bases numéricas decimais ou outras que não sejam potência de dois. As conversões hexadecimais, octais e binárias são ilimitadas. O limite pode ser configurado.
O tipo int
no CPython é um número de comprimento arbitrário armazenado em formato binário (comumente conhecido como “bignum”). Não existe nenhum algoritmo que possa converter uma string em um inteiro binário ou um inteiro binário em uma string em tempo linear, a menos que a base seja uma potência de 2. Mesmo os algoritmos mais conhecidos para a base 10 têm complexidade subquadrática. Converter um valor grande como int('1' * 500_000)
pode levar mais de um segundo em uma CPU rápida.
A limitação do tamanho da conversão oferece uma maneira prática de evitar CVE-2020-10735.
O limite é aplicado ao número de caracteres de dígitos na string de entrada ou saída quando um algoritmo de conversão não linear estiver envolvido. Sublinhados e o sinal não são contados para o limite.
Quando uma operação excede o limite, uma exceção ValueError
é levantada:
>>> import sys
>>> sys.set_int_max_str_digits(4300) # Illustrative, this is the default.
>>> _ = int('2' * 5432)
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300) for integer string conversion: value has 5432 digits; use sys.set_int_max_str_digits() to increase the limit.
>>> i = int('2' * 4300)
>>> len(str(i))
4300
>>> i_squared = i*i
>>> len(str(i_squared))
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300) for integer string conversion: value has 8599 digits; use sys.set_int_max_str_digits() to increase the limit.
>>> len(hex(i_squared))
7144
>>> assert int(hex(i_squared), base=16) == i*i # Hexadecimal is unlimited.
O limite padrão é de 4300 dígitos conforme fornecido em sys.int_info.default_max_str_digits
. O limite mínimo que pode ser configurado é de 640 dígitos conforme fornecido em sys.int_info.str_digits_check_threshold
.
Verificação:
>>> import sys
>>> assert sys.int_info.default_max_str_digits == 4300, sys.int_info
>>> assert sys.int_info.str_digits_check_threshold == 640, sys.int_info
>>> msg = int('578966293710682886880994035146873798396722250538762761564'
... '9252925514383915483333812743580549779436104706260696366600'
... '571186405732').to_bytes(53, 'big')
...
Novo na versão 3.9.14.
APIs afetadas¶
A limitação só se aplica a conversões potencialmente lentas entre int
e str
ou bytes
:
int(string)
com padrão sendo base 10.int(string, base)
para todas as bases que não são uma potência de 2.str(integer)
.repr(integer)
.qualquer outra conversão de string para base 10 como, por exemplo,
f"{integer}"
,"{}".format(integer)
oub"%d" % integer
.
As limitações não se aplicam a funções com um algoritmo linear:
int(string, base)
com base 2, 4, 8, 16 ou 32.Minilinguagem de especificação de formato para números hexa, octal e binários
str
paradecimal.Decimal
.
Configurando o limiter¶
Antes de iniciar o Python, você pode usar uma variável de ambiente ou um sinalizador de linha de comando do interpretador para configurar o limite:
PYTHONINTMAXSTRDIGITS
, por exemploPYTHONINTMAXSTRDIGITS=640 python3
para definir o limite para 640 ouPYTHONINTMAXSTRDIGITS=0 python3
para desabilitar a limitação.-X int_max_str_digits
, por exemplopython3 -X int_max_str_digits=640
sys.flags.int_max_str_digits
contém o valor dePYTHONINTMAXSTRDIGITS
ou-X int_max_str_digits
. Se a variável env e a opção-X
estiverem definidas, a opção-X
terá precedência. Um valor de -1 indica que ambos não foram definidos, portanto, um valor desys.int_info.default_max_str_digits
foi usado durante a inicialização.
A partir do código, você pode inspecionar o limite atual e definir um novo usando estas APIs sys
:
sys.get_int_max_str_digits()
esys.set_int_max_str_digits()
são um getter e um setter para o limite de todo o interpretador. Os subinterpretadores têm seu próprio limite.
Informações sobre o padrão e o mínimo podem ser encontradas em sys.int_info
:
sys.int_info.default_max_str_digits
é o limite padrão compilado.sys.int_info.str_digits_check_threshold
é o menor valor aceito para o limite (diferente de 0 que o desabilita).
Novo na versão 3.9.14.
Cuidado
Definir um limite baixo pode levar a problemas. Embora raro, existe um código que contém constantes inteiras em decimal em sua origem que excedem o limite mínimo. Uma consequência de definir o limite é que o código-fonte do Python contendo literais inteiros decimais maiores que o limite encontrará um erro durante a análise, geralmente no momento da inicialização ou no momento da importação ou até mesmo no momento da instalação – sempre que um .pyc
atualizado ainda não existe para o código. Uma solução alternativa para source que contém tais constantes grandes é convertê-las para a forma hexadecimal 0x
, pois não há limite.
Teste sua aplicação completamente se você usar um limite baixo. Certifique-se de que seus testes sejam executados com o limite definido anteriormente por meio do ambiente ou sinalizador para que ele seja aplicado durante a inicialização e até mesmo durante qualquer etapa de instalação que possa invocar o Python para pré-compilar fontes .py
para arquivos .pyc
.
Configuração recomendada¶
Espera-se que o padrão sys.int_info.default_max_str_digits
seja razoável para a maioria das aplicações. Se sua aplicação exigir um limite diferente, defina-o em seu ponto de entrada principal usando código agnóstico de versão Python, pois essas APIs foram adicionadas em lançamentos de patch de segurança em versões anteriores a 3.11.
Exemplo:
>>> import sys
>>> if hasattr(sys, "set_int_max_str_digits"):
... upper_bound = 68000
... lower_bound = 4004
... current_limit = sys.get_int_max_str_digits()
... if current_limit == 0 or current_limit > upper_bound:
... sys.set_int_max_str_digits(upper_bound)
... elif current_limit < lower_bound:
... sys.set_int_max_str_digits(lower_bound)
Se você precisar desativá-lo totalmente, defina-o como 0
.
Notas de rodapé
- 1
Informações adicionais sobre esses métodos especiais podem ser encontradas no Manual de Referência do Python (Personalizaçã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 com apenas um elemento, que é a tupla a ser formatada.