Funções embutidas

O interpretador do Python possui várias funções e tipos embutidos que sempre estão disponíveis. A seguir listamos todas as funções em ordem alfabética.

Funções embutidas

abs(x)

Retorna o valor absoluto de um número. O argumento pode ser um inteiro, um número de ponto flutuante ou um objeto implementando __abs__(). Se o argumento é um número complexo, sua magnitude é retornada.

aiter(async_iterable)

Return an asynchronous iterator for an asynchronous iterable. Equivalent to calling x.__aiter__().

aiter(x) itself has an __aiter__() method that returns x, so aiter(aiter(x)) is the same as aiter(x).

Note: Unlike iter(), aiter() has no 2-argument variant.

Novo na versão 3.10.

all(iterable)

Retorna True se todos os elementos de iterable são verdadeiros (ou se iterable estiver vazio). Equivalente a:

def all(iterable):
    for element in iterable:
        if not element:
            return False
    return True
awaitable anext(async_iterator[, default])

When awaited, return the next item from the given asynchronous iterator, or default if given and the iterator is exhausted.

This is the async variant of the next() builtin, and behaves similarly.

This calls the __anext__() method of async_iterator, returning an awaitable. Awaiting this returns the next value of the iterator. If default is given, it is returned if the iterator is exhausted, otherwise StopAsyncIteration is raised.

Novo na versão 3.10.

any(iterable)

Retorna True se algum elemento de iterable for verdadeiro. Se iterable estiver vazio, retorna False. Equivalente a:

def any(iterable):
    for element in iterable:
        if element:
            return True
    return False
ascii(object)

As repr(), return a string containing a printable representation of an object, but escape the non-ASCII characters in the string returned by repr() using \x, \u, or \U escapes. This generates a string similar to that returned by repr() in Python 2.

bin(x)

Converte um número inteiro para uma string de binários prefixada com “0b”. O resultado é uma expressão Python válida. Se x não é um objeto Python int, ele tem que definir um método __index__() que devolve um inteiro. Alguns exemplos:

>>> bin(3)
'0b11'
>>> bin(-10)
'-0b1010'

If the prefix “0b” is desired or not, you can use either of the following ways.

>>> format(14, '#b'), format(14, 'b')
('0b1110', '1110')
>>> f'{14:#b}', f'{14:b}'
('0b1110', '1110')

Veja também format() para mais informações.

class bool([x])

Return a Boolean value, i.e. one of True or False. x is converted using the standard truth testing procedure. If x is false or omitted, this returns False; otherwise, it returns True. The bool class is a subclass of int (see Tipos numéricos — int, float, complex). It cannot be subclassed further. Its only instances are False and True (see Valores Booleanos).

Alterado na versão 3.7: x é agora um parâmetro somente posicional.

breakpoint(*args, **kws)

Esta função coloca você no depurador no local da chamada. Especificamente, ela chama sys.breakpointhook(), passando args e kws diretamente. Por padrão, sys.breakpointhook() chama pdb.set_trace() não esperando nenhum argumento. Neste caso, isso é puramente uma função de conveniência para você não precisar importar pdb explicitamente ou digitar mais código para entrar no depurador. Contudo, sys.breakpointhook() pode ser configurado para alguma outra função e breakpoint() irá automaticamente chamá-la, permitindo você ir para o depurador de sua escolha.

Levanta um evento de auditoria builtins.breakpoint com argumento breakpointhook.

Novo na versão 3.7.

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

Retorna um novo vetor de bytes. A classe bytearray é uma sequência mutável de inteiros no intervalo 0 <= x < 256. Ela tem a maior parte dos métodos mais comuns de sequências mutáveis, descritas em Tipos sequências mutáveis, assim como a maior parte dos métodos que o tipo bytes tem, veja Operações com Bytes e Bytearray.

O parâmetro opcional source pode ser usado para inicializar o vetor de algumas maneiras diferentes:

  • Se é uma string, você deve informar o parâmetro encoding (e opcionalmente, errors); bytearray() então converte a string para bytes usando str.encode().

  • Se é um inteiro, o vetor terá esse tamanho e será inicializado com bytes nulos.

  • Se é um objeto em conformidade com a interface de buffer, um buffer somente leitura do objeto será usado para inicializar o vetor de bytes.

  • Se é um iterável, deve ser um iterável de inteiros no intervalo 0 <= x < 256, que serão usados como o conteúdo inicial do vetor.

Sem nenhum argumento, um vetor de tamanho 0 é criado.

Veja também Tipos de Sequência Binária — bytes, bytearray, memoryview e Bytearray Objects.

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

Return a new “bytes” object which is an immutable sequence of integers in the range 0 <= x < 256. bytes is an immutable version of bytearray – it has the same non-mutating methods and the same indexing and slicing behavior.

Consequentemente, argumentos do construtor são interpretados como os de bytearray().

Objetos bytes também podem ser criados com literais, veja Literais de string e bytes.

Veja também Tipos de Sequência Binária — bytes, bytearray, memoryview, Objetos Bytes, e Operações com Bytes e Bytearray.

callable(object)

Devolve True se o argumento object parece ser chamável, False caso contrário. Se devolve True, ainda é possível que a chamada falhe, mas se é False, chamar object nunca será bem sucedido. Note que classes são chamáveis (chamar uma classe devolve uma nova instância); instâncias são chamáveis se suas classes possuem um método __call__().

Novo na versão 3.2: Esta função foi removida na versão 3.0, mas retornou no Python 3.2.

chr(i)

Retorna o caractere que é apontado pelo inteiro i no código Unicode. Por exemplo, chr(97) retorna a string 'a', enquanto chr(8364) retorna a string '€'. É o inverso de ord().

O intervalo válido para o argumento vai de 0 até 1.114.111 (0x10FFFF na base 16). Será lançada uma exceção ValueError se i estiver fora desse intervalo.

@classmethod

Transforma um método em um método de classe.

A class method receives the class as an implicit first argument, just like an instance method receives the instance. To declare a class method, use this idiom:

class C:
    @classmethod
    def f(cls, arg1, arg2, ...): ...

O termo @classmethod é uma função decoradora – veja Definições de função para detalhes.

Um método de classe pode ser chamado tanto da classe (como em C.f()) quanto da instância (como em C().f()). A instância é ignorada, exceto por sua classe. Se um método de classe é chamado por uma classe derivada, o objeto da classe derivada é passado como primeiro argumento implícito.

Métodos de classe são diferentes de métodos estáticos em C++ ou Java. Se você quer saber desses, veja staticmethod() nesta seção. Para mais informações sobre métodos de classe, consulte A hierarquia de tipos padrão.

Alterado na versão 3.9: Métodos de classe agora podem envolver outros descritores tal como property().

Alterado na versão 3.10: Class methods now inherit the method attributes (__module__, __name__, __qualname__, __doc__ and __annotations__) and have a new __wrapped__ attribute.

compile(source, filename, mode, flags=0, dont_inherit=False, optimize=- 1)

Compila o argumento source em código ou objeto AST. Objetos código podem ser executados por exec() ou eval(). source pode ser uma string normal, uma string byte, ou um objeto AST. Consulte a documentação do módulo ast para saber como trabalhar com objetos AST.

O argumento filename deve ser o arquivo de onde o código será lido; passe algum valor reconhecível se isso não foi lido de um arquivo ('<string>' é comumente usado).

O argumento mode especifica qual o tipo de código deve ser compilado; pode ser 'exec' se source consiste em uma sequência de instruções, 'eval' se consiste de uma única expressão, ou 'single' se consiste de uma única instrução interativa (neste último caso, instruções que são avaliadas para alguma coisa diferente de None serão exibidas).

Os argumentos opcionais flags e dont_inherit controlam quais opções do compilador devem ser ativadas e quais recursos futuros devem ser permitidos. Se nenhum estiver presente (ou ambos forem zero), o código é compilado com os mesmos sinalizadores que afetam o código que está chamando compile(). Se o argumento flags for fornecido e dont_inherit não for (ou for zero), as opções do compilador e as instruções futuras especificadas pelo argumento flags são usadas além daquelas que seriam usadas de qualquer maneira. Se dont_inherit for um inteiro diferente de zero, então o argumento flags é – os sinalizadores (recursos futuros e opções do compilador) no código circundante são ignorados.

Opções de compilador e instruções futuras são especificadas por bits, assim pode ocorrer uma operação OU bit a bit para especificar múltiplas instruções. O sinalizador necessário para especificar um dado recurso futuro pode ser encontrado no atributo compiler_flag na instância _Feature do módulo __future__. Sinalizadores de compilador podem ser encontrados no módulo ast, com o prefixo PyCF_.

O argumento optimize especifica o nível de otimização do compilador; o valor padrão de -1 seleciona o nível de otimização do interpretador dado pela opção -O. Níveis explícitos são 0 (nenhuma otimização; __debug__ é verdadeiro), 1 (instruções assert são removidas, __debug__ é falso) ou 2 (strings de documentação também são removidas).

Essa função levanta SyntaxError se o código para compilar é inválido, e ValueError se o código contém bytes nulos.

Se você quer analisar código Python em sua representação AST, veja ast.parse().

Levanta um evento de auditoria compile com argumentos source, filename.

Nota

Quando compilando uma string com código multi-linhas em modo 'single' ou 'eval', entrada deve ser terminada por ao menos um caractere de nova linhas. Isso é para facilitar a detecção de instruções completas e incompletas no módulo code.

Aviso

É possível quebrar o interpretador Python com uma string suficiente grande/complexa quando compilando para uma objeto AST, devido limitações do tamanho da pilha no compilador AST do Python.

Alterado na versão 3.2: Allowed use of Windows and Mac newlines. Also, input in 'exec' mode does not have to end in a newline anymore. Added the optimize parameter.

Alterado na versão 3.5: Anteriormente, TypeError era levantada quando havia bytes nulos em source.

Novo na versão 3.8: ast.PyCF_ALLOW_TOP_LEVEL_AWAIT agora pode ser passado em flags para habilitar o suporte em nível superior a await, async for, e async with.

class complex([real[, imag]])

Retorna um número completo com o valor real + imag*1j ou converte uma string ou número para um número complexo. Se o primeiro parâmetro é uma string, ele será interpretado como um número complexo e a função deve ser chamada sem um segundo parâmetro. O segundo parâmetro nunca deve ser uma string. Cada argumento pode ser qualquer tipo numérico (incluindo complexo). Se imag é omitido, seu valor padrão é zero e a construção funciona como uma conversão numérica, similar a int e float. Se os dois argumentos são omitidos, retorna 0j.

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

Nota

Quando convertendo a partir de uma string, a string não pode conter espaços em branco em torno + central ou do operador -. Por exemplo, complex('1+2j') funciona, mas complex('1 + 2j') levanta ValueError.

O tipo complexo está descrito em Tipos numéricos — int, float, complex.

Alterado na versão 3.6: Agrupar dígitos com sublinhados como em literais de código é permitido.

Alterado na versão 3.8: Chamadas para __index__() se __complex__() e __float__() não estão definidas.

delattr(object, name)

Essa função está relacionada com setattr(). Os argumentos são um objeto e uma string. A string deve ser o nome de um dos atributos do objeto. A função remove o atributo indicado, desde que o objeto permita. Por exemplo, delattr(x, 'foobar') é equivalente a del x.foobar.

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

Cria um novo dicionário. O objeto dict é a classe do dicionário. Veja dict e Tipo mapeamento — dict para documentação sobre esta classe.

Para outros contêineres, consulte as classes embutidas list, set e tuple, bem como o módulo collections.

dir([object])

Sem argumentos, devolve a lista de nomes no escopo local atual. Com um argumento, tentará devolver uma lista de atributos válidos para esse objeto.

Se o objeto tiver um método chamado __dir__(), esse método será chamado e deve devolver a lista de atributos. Isso permite que objetos que implementam uma função personalizada __getattr__() ou __getattribute__() personalizem a maneira como dir() relata seus atributos.

If the object does not provide __dir__(), the function tries its best to gather information from the object’s __dict__ attribute, if defined, and from its type object. The resulting list is not necessarily complete and may be inaccurate when the object has a custom __getattr__().

O mecanismo padrão dir() se comporta de maneira diferente com diferentes tipos de objetos, pois tenta produzir as informações mais relevantes e não completas:

  • Se o objeto for um objeto de módulo, a lista conterá os nomes dos atributos do módulo.

  • Se o objeto for um objeto de tipo ou classe, a lista conterá os nomes de seus atributos e recursivamente os atributos de suas bases.

  • Caso contrário, a lista conterá os nomes dos atributos do objeto, os nomes dos atributos da classe e recursivamente os atributos das classes base da classe.

A lista resultante é alfabeticamente ordenada. Por exemplo:

>>> import struct
>>> dir()   # show the names in the module namespace  
['__builtins__', '__name__', 'struct']
>>> dir(struct)   # show the names in the struct module 
['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__',
 '__initializing__', '__loader__', '__name__', '__package__',
 '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
 'unpack', 'unpack_from']
>>> class Shape:
...     def __dir__(self):
...         return ['area', 'perimeter', 'location']
>>> s = Shape()
>>> dir(s)
['area', 'location', 'perimeter']

Nota

Como dir() é fornecido principalmente como uma conveniência para uso em um prompt interativo, ele tenta fornecer um conjunto interessante de nomes mais do que tenta fornecer um conjunto de nomes definido de forma rigorosa ou consistente, e seu comportamento detalhado pode mudar nos lançamentos. Por exemplo, os atributos de metaclasse não estão na lista de resultados quando o argumento é uma classe.

divmod(a, b)

Take two (non-complex) numbers as arguments and return a pair of numbers consisting of their quotient and remainder when using integer division. With mixed operand types, the rules for binary arithmetic operators apply. For integers, the result is the same as (a // b, a % b). For floating point numbers the result is (q, a % b), where q is usually math.floor(a / b) but may be 1 less than that. In any case q * b + a % b is very close to a, if a % b is non-zero it has the same sign as b, and 0 <= abs(a % b) < abs(b).

enumerate(iterable, start=0)

Devolve um objeto enumerado. iterable deve ser uma sequência, um iterador ou algum outro objeto que suporte a iteração. O método __next__() do iterador retornado por enumerate() devolve uma tupla contendo uma contagem (a partir de start, cujo padrão é 0) e os valores obtidos na iteração sobre iterable.

>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
>>> list(enumerate(seasons))
[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
>>> list(enumerate(seasons, start=1))
[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]

Equivalente a:

def enumerate(sequence, start=0):
    n = start
    for elem in sequence:
        yield n, elem
        n += 1
eval(expression[, globals[, locals]])

Os argumentos são uma sequência de caracteres e globais e locais opcionais. Se fornecido, globals deve ser um dicionário. Se fornecido, locals pode ser qualquer objeto de mapeamento.

The expression argument is parsed and evaluated as a Python expression (technically speaking, a condition list) using the globals and locals dictionaries as global and local namespace. If the globals dictionary is present and does not contain a value for the key __builtins__, a reference to the dictionary of the built-in module builtins is inserted under that key before expression is parsed. That way you can control what builtins are available to the executed code by inserting your own __builtins__ dictionary into globals before passing it to eval(). If the locals dictionary is omitted it defaults to the globals dictionary. If both dictionaries are omitted, the expression is executed with the globals and locals in the environment where eval() is called. Note, eval() does not have access to the nested scopes (non-locals) in the enclosing environment.

O valor de retorno é o resultado da expressão avaliada. Erros de sintaxe são relatados como exceções. Exemplo:

>>> x = 1
>>> eval('x+1')
2

This function can also be used to execute arbitrary code objects (such as those created by compile()). In this case, pass a code object instead of a string. If the code object has been compiled with 'exec' as the mode argument, eval()'s return value will be None.

Hints: dynamic execution of statements is supported by the exec() function. The globals() and locals() functions return the current global and local dictionary, respectively, which may be useful to pass around for use by eval() or exec().

If the given source is a string, then leading and trailing spaces and tabs are stripped.

Veja ast.literal_eval() para uma função que pode avaliar com segurança strings com expressões contendo apenas literais.

Levanta um evento de auditoria exec com argumento code_object.

exec(object[, globals[, locals]])

Esta função tem suporte a execução dinâmica de código Python. O parâmetro object deve ser ou uma string ou um objeto código. Se for uma string, a mesma é analisada como um conjunto de instruções Python, o qual é então executado (exceto caso um erro de sintaxe ocorra). 1 Se for um objeto código, ele é simplesmente executado. Em todos os casos, espera-se que o código a ser executado seja válido como um arquivo de entrada (veja a seção “Arquivo de Entrada” no Manual de Referência). Tenha cuidado que as instruções nonlocal, yield, and return não podem ser usadas fora das definições de funções mesmo dentro do contexto do código passado para a função exec() . O valor de retorno é sempre None.

In all cases, if the optional parts are omitted, the code is executed in the current scope. If only globals is provided, it must be a dictionary (and not a subclass of dictionary), which will be used for both the global and the local variables. If globals and locals are given, they are used for the global and local variables, respectively. If provided, locals can be any mapping object. Remember that at the module level, globals and locals are the same dictionary. If exec gets two separate objects as globals and locals, the code will be executed as if it were embedded in a class definition.

Se o dicionário globals não contém um valor para a chave __builtins__, a referência para o dicionário do módulo embutido builtins é inserido com essa chave. A maneira que você pode controlar quais embutidos estão disponíveis para o código executado é inserindo seu próprio __builtins__ dicionário em globals antes de passar para exec().

Levanta um evento de auditoria exec com argumento code_object.

Nota

As funções embutidas globals() e locals() devolvem o dicionário global e local, respectivamente, o que pode ser útil para passar adiante e usar como segundo ou terceiro argumento para exec().

Nota

locals padrão atua como descrito pela função locals() abaixo: modificações para o dicionário locals padrão não deveriam ser feitas. Se você precisa ver efeitos do código em locals depois da função exec() retornar passe um dicionário locals explícito.

filter(function, iterable)

Constrói um iterador a partir dos elementos de iterable para os quais function retorna verdadeiro. iterable pode ser uma sequência, um contêiner que com suporte a iteração, ou um iterador. Se function for None, a função identidade será usada, isto é, todos os elementos de iterable que são falsos são removidos.

Note que filter(function, iterable) é equivalente a expressão geradora (item for item in iterable if function(item)) se function não for None e (item for item in iterable if item) se function for None.

Veja itertools.filterfalse() para a função complementar que devolve elementos de iterable para os quais function devolve falso.

class float([x])

Devolve um número de ponto flutuante construído a partir de um número ou string x.

If the argument is a string, it should contain a decimal number, optionally preceded by a sign, and optionally embedded in whitespace. The optional sign may be '+' or '-'; a '+' sign has no effect on the value produced. The argument may also be a string representing a NaN (not-a-number), or positive or negative infinity. More precisely, the input must conform to the following grammar after leading and trailing whitespace characters are removed:

sign           ::=  "+" | "-"
infinity       ::=  "Infinity" | "inf"
nan            ::=  "nan"
numeric_value  ::=  floatnumber | infinity | nan
numeric_string ::=  [sign] numeric_value

Here floatnumber is the form of a Python floating-point literal, described in Literais de Ponto Flutuante. Case is not significant, so, for example, “inf”, “Inf”, “INFINITY”, and “iNfINity” are all acceptable spellings for positive infinity.

Caso contrário, se o argumento é um inteiro ou um número de ponto flutuante, um número de ponto flutuante com o mesmo valor (com a precisão de ponto flutuante de Python) é devolvido. Se o argumento está fora do intervalo de um ponto flutuante Python, uma exceção OverflowError será lançada.

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

Se nenhum argumento for fornecido, será retornado 0.0.

Exemplos:

>>> float('+1.23')
1.23
>>> float('   -12345\n')
-12345.0
>>> float('1e-003')
0.001
>>> float('+1E6')
1000000.0
>>> float('-Infinity')
-inf

O tipo float é descrito em Tipos numéricos — int, float, complex.

Alterado na versão 3.6: Agrupar dígitos com sublinhados como em literais de código é permitido.

Alterado na versão 3.7: x é agora um parâmetro somente posicional.

Alterado na versão 3.8: Chamada para __index__() se __float__() não está definido.

format(value[, format_spec])

Convert a value to a “formatted” representation, as controlled by format_spec. The interpretation of format_spec will depend on the type of the value argument; however, there is a standard formatting syntax that is used by most built-in types: Minilinguagem de especificação de formato.

O format_spec padrão é uma string vazia que geralmente produz o mesmo efeito que chamar str(value).

Uma chamada de format(value, format_spec) é convertida em type(value).__format__(value, format_spec), que ignora o dicionário da instância ao pesquisar o método __format__() de value. Uma exceção TypeError é levantada se a pesquisa do método atingir object e o format_spec não estiver vazio, ou se o format_spec ou o valor de retorno não forem strings.

Alterado na versão 3.4: object().__format__(format_spec) levanta um TypeError se format_spec não for uma string vazia.

class frozenset([iterable])

Devolve um novo objeto frozenset, opcionalmente com elementos obtidos de iterable. frozenset é uma classe embutida. Veja frozenset e Tipo conjuntos — set, frozenset para documentação sobre essas classes.

Para outros contêineres veja as classes embutidas set, list, tuple, e dict, assim como o módulo collections.

getattr(object, name[, default])

Devolve o valor do atributo name de object. name deve ser uma string. Se a string é o nome de um dos atributos do objeto, o resultado é o valor de tal atributo. Por exemplo, getattr(x, 'foobar') é equivalente a x.foobar. Se o atributo não existir, default é devolvido se tiver sido fornecido, caso contrário a exceção AttributeError é levantada.

Nota

Since private name mangling happens at compilation time, one must manually mangle a private attribute’s (attributes with two leading underscores) name in order to retrieve it with getattr().

globals()

Devolve um dicionário representando a tabela de símbolos global atual. É sempre o dicionário do módulo atual (dentro de uma função ou método, é o módulo onde está definido, não o módulo do qual é chamado).

hasattr(object, name)

Os argumentos são um objeto e uma string. O resultado é True se a string é o nome de um dos atributos do objeto, e False se ela não for. (Isto é implementado chamando getattr(object, name) e vendo se levanta um AttributeError ou não.)

hash(object)

Retorna o valor hash de um objeto (se houver um). Valores hash são números inteiros. Eles são usados para rapidamente comparar chaves de dicionários durante uma pesquisa em um dicionário. Valores numéricos que ao serem comparados são iguais, possuem o mesmo valor hash (mesmo que eles sejam de tipos diferentes, como é o caso de 1 e 1.0).

Nota

Para objetos com métodos __hash__() personalizados, fique atento que hash() trunca o valor devolvido baseado no comprimento de bits da máquina hospedeira. Veja __hash__() para mais detalhes.

help([object])

Invoca o sistema de ajuda embutido. (Esta função é destinada para uso interativo.) Se nenhum argumento é passado, o sistema interativo de ajuda inicia no interpretador do console. Se o argumento é uma string, então a string é pesquisada como o nome de um módulo, função, classe, método, palavra-chave, ou tópico de documentação, e a página de ajuda é exibida no console. Se o argumento é qualquer outro tipo de objeto, uma página de ajuda para o objeto é gerada.

Note that if a slash(/) appears in the parameter list of a function when invoking help(), it means that the parameters prior to the slash are positional-only. For more info, see the FAQ entry on positional-only parameters.

Esta função é adicionada ao espaço de nomes embutido pelo módulo site.

Alterado na versão 3.4: Mudanças em pydoc e inspect significam que as assinaturas reportadas para chamáveis agora são mais compreensíveis e consistentes.

hex(x)

Converte um número inteiro para uma string hexadecimal em letras minúsculas pré-fixada com “0x”. Se x não é um objeto int do Python, ele tem que definir um método __index__() que retorne um inteiro. Alguns exemplos:

>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'

Se você quer converter um número inteiro para uma string hexadecimal em letras maiúsculas ou minúsculas, com prefixo ou sem, você pode usar qualquer uma das seguintes maneiras:

>>> '%#x' % 255, '%x' % 255, '%X' % 255
('0xff', 'ff', 'FF')
>>> format(255, '#x'), format(255, 'x'), format(255, 'X')
('0xff', 'ff', 'FF')
>>> f'{255:#x}', f'{255:x}', f'{255:X}'
('0xff', 'ff', 'FF')

Veja também format() para mais informações.

Veja também int() para converter uma string hexadecimal para um inteiro usando a base 16.

Nota

Para obter uma string hexadecimal de um ponto flutuante, use o método float.hex().

id(object)

Devolve a “identidade” de um objeto. Ele é um inteiro, o qual é garantido que será único e constante para este objeto durante todo o seu ciclo de vida. Dois objetos com ciclos de vida não sobrepostos podem ter o mesmo valor para id().

CPython implementation detail: This is the address of the object in memory.

Levanta um evento de auditoria builtins.id com o argumento id.

input([prompt])

Se o argumento prompt estiver presente, escreve na saída padrão sem uma nova linha ao final. A função então lê uma linha da fonte de entrada, converte a mesma para uma string (removendo o caractere de nova linha ao final), e devolve isso. Quando o final do arquivo (EOF / end-of-file) é encontrado, um erro EOFError é levantado. Exemplo:

>>> s = input('--> ')  
--> Monty Python's Flying Circus
>>> s  
"Monty Python's Flying Circus"

Se o módulo readline foi carregado, então input() usará ele para prover edição de linhas elaboradas e funcionalidades de histórico.

Levanta um evento de auditoria builtins.input com argumento prompt.

Levanta um evento de auditoria builtins.input/result com argumento result.

class int([x])
class int(x, base=10)

Devolve um objeto inteiro construído a partir de um número ou string x, ou devolve 0 se nenhum argumento foi fornecido. Se x definir um método __int__(), então int(x) retorna x.__int__(). Se x definir um método __index__(), então ele retorna x.__index__(). Se x definir um método __trunc__(), então ele retorna x.__trunc__(). Para números de ponto flutuante, isto trunca o número na direção do zero.

Se x não é um número ou se base é fornecida, então x deve ser uma string, instância de bytes ou bytearray representando um inteiro literal em base base. Opcionalmente, o literal pode ser precedido por + ou - (sem espaço entre eles) e cercado por espaços em branco. Um literal base-n consiste de dígitos de 0 até n-1, com a até z (ou A até Z) com valores de 10 até 35. A base padrão é 10. Os valores permitidos são 0 e 2–36. Literais em base-2, -8, e -16 podem ser opcionalmente prefixado com 0b/0B, 0o/0O, ou 0x/0X, assim como literais inteiros. Base 0 significa que será interpretado exatamente como um literal, ou seja, as bases são, na verdade, 2, 8, 10, ou 16, e que int('010', 0) não é legal, enquanto int('010') é, assim como int('010', 8).

O tipo inteiro está descrito em Tipos numéricos — int, float, complex.

Alterado na versão 3.4: Se base não é uma instância de int e o objeto base tem um método base.__index__, então esse método é chamado para obter um inteiro para a base. Versões anteriores usavam base.__int__ ao invés de base.__index__.

Alterado na versão 3.6: Agrupar dígitos com sublinhados como em literais de código é permitido.

Alterado na versão 3.7: x é agora um parâmetro somente posicional.

Alterado na versão 3.8: Utiliza __index__() caso __int__() não seja definido.

isinstance(object, classinfo)

Return True if the object argument is an instance of the classinfo argument, or of a (direct, indirect, or virtual) subclass thereof. If object is not an object of the given type, the function always returns False. If classinfo is a tuple of type objects (or recursively, other such tuples) or a Tipo União of multiple types, return True if object is an instance of any of the types. If classinfo is not a type or tuple of types and such tuples, a TypeError exception is raised.

Alterado na versão 3.10: classinfo can be a Tipo União.

issubclass(class, classinfo)

Return True if class is a subclass (direct, indirect, or virtual) of classinfo. A class is considered a subclass of itself. classinfo may be a tuple of class objects or a Tipo União, in which case return True if class is a subclass of any entry in classinfo. In any other case, a TypeError exception is raised.

Alterado na versão 3.10: classinfo can be a Tipo União.

iter(object[, sentinel])

Devolve um objeto iterador. O primeiro argumento é interpretado muito diferentemente dependendo da presença do segundo argumento. Sem um segundo argumento, object deve ser uma coleção de objetos com suporte ao protocolo de iteração (o método __iter__()), ou ele deve ter suporte ao protocolo de sequência (o método __getitem__() com argumentos inteiros começando em 0). Se ele não tem suporte nenhum desses protocolos, um TypeError é levantado. Se o segundo argumento, sentinel, é fornecido, então object deve ser um objeto chamável. O iterador criado neste caso irá chamar object sem nenhum argumento para cada chamada para o seu método __next__(); se o valor devolvido é igual a sentinel, então StopIteration será levantado, caso contrário o valor será devolvido.

Veja também Tipos iteradores.

Uma aplicação útil da segunda forma de iter() é para construir um bloco de leitura. Por exemplo, ler blocos de comprimento fixo de um arquivo binário de banco de dados até que o final do arquivo seja atingido:

from functools import partial
with open('mydata.db', 'rb') as f:
    for block in iter(partial(f.read, 64), b''):
        process_block(block)
len(s)

Devolve o comprimento (o número de itens) de um objeto. O argumento pode ser uma sequência (tal como uma string, bytes, tupla, lista, ou um intervalo) ou uma coleção (tal como um dicionário, conjunto, ou conjunto imutável).

CPython implementation detail: len levanta OverflowError em tamanhos maiores que sys.maxsize, tal como range(2 ** 100).

class list([iterable])

Ao invés de ser uma função, list é na verdade um tipo de sequência mutável, conforme documentado em Listas e Tipos sequências — list, tuple, range.

locals()

Atualiza e devolve um dicionário representando a tabela de símbolos locais atual. Variáveis livres são devolvidas por locals() quando ele é chamado em blocos de função, mas não em blocos de classes. Perceba que no nível dos módulos, locals() e globals() são o mesmo dicionário.

Nota

O conteúdo deste dicionário não deve ser modificado; as alterações podem não afetar os valores das variáveis ​​locais e livres usadas pelo interpretador.

map(function, iterable, ...)

Devolve um iterador que aplica function para cada item de iterable, gerando os resultados. Se argumentos iterable adicionais são passados, function deve ter a mesma quantidade de argumentos e ela é aplicada aos itens de todos os iteráveis em paralelo. Com múltiplos iteráveis, o iterador para quando o iterador mais curto é encontrado. Para casos onde os parâmetros de entrada da função já estão organizados em tuplas, veja itertools.starmap().

max(iterable, *[, key, default])
max(arg1, arg2, *args[, key])

Devolve o maior item em um iterável ou o maior de dois ou mais argumentos.

Se um argumento posicional é fornecido, ele deve ser um iterável. O maior item no iterável é retornado. Se dois ou mais argumentos posicionais são fornecidos, o maior dos argumentos posicionais é devolvido.

Existem dois parâmetros somente-nomeados opcionais. O parâmetro key especifica uma função de ordenamento de um argumento, como aquelas usadas por list.sort(). O parâmetro default especifica um objeto a ser devolvido se o iterável fornecido estiver vazio. Se o iterável estiver vazio, e default não foi fornecido, uma exceção ValueError é levantada.

Se múltiplos itens são máximos, a função devolve o primeiro encontrado. Isto é consistente com outras ferramentas de ordenamento que preservam a estabilidade, tais como sorted(iterable, key=keyfunc, reverse=True)[0] e heapq.nlargest(1, iterable, key=keyfunc).

Novo na versão 3.4: O parâmetro somente-nomeado default.

Alterado na versão 3.8: O valor de key pode ser None.

class memoryview(object)

Devolve um objeto de “visão da memória” criado a partir do argumento fornecido. Veja Memory Views para mais informações.

min(iterable, *[, key, default])
min(arg1, arg2, *args[, key])

Devolve o menor item de um iterável ou o menor de dois ou mais argumentos.

Se um argumento posicional é fornecido, ele deve ser um iterável. O menor item no iterável é devolvido. Se dois ou mais argumentos posicionais são fornecidos, o menor dos argumentos posicionais é devolvido.

Existem dois parâmetros somente-nomeados opcionais. O parâmetro key especifica uma função de ordenamento de um argumento, como aquelas usadas por list.sort(). O parâmetro default especifica um objeto a ser devolvido se o iterável fornecido estiver vazio. Se o iterável estiver vazio, e default não foi fornecido, uma exceção ValueError é levantada.

Se múltiplos itens são mínimos, a função devolve o primeiro encontrado. Isto é consistente com outras ferramentas de ordenamento que preservam a estabilidade, tais como sorted(iterable, key=keyfunc)[0] e heapq.nsmallest(1, iterable, key=keyfunc).

Novo na versão 3.4: O parâmetro somente-nomeado default.

Alterado na versão 3.8: O valor de key pode ser None.

next(iterator[, default])

Recupera o próximo item do iterator chamando o seu método __next__(). Se default foi fornecido, ele é devolvido caso o iterável tenha sido percorrido por completo, caso contrário StopIteration é levantada.

class object

Return a new featureless object. object is a base for all classes. It has methods that are common to all instances of Python classes. This function does not accept any arguments.

Nota

object não tem um atributo __dict__, então você não consegue definir atributos arbitrários para uma instância da classe object.

oct(x)

Converte um número inteiro para uma string em base octal, pré-fixada com “0o”. O resultado é uma expressão Python válida. Se x não for um objeto int Python, ele tem que definir um método __index__() que devolve um inteiro. Por exemplo:

>>> oct(8)
'0o10'
>>> oct(-56)
'-0o70'

If you want to convert an integer number to an octal string either with the prefix “0o” or not, you can use either of the following ways.

>>> '%#o' % 10, '%o' % 10
('0o12', '12')
>>> format(10, '#o'), format(10, 'o')
('0o12', '12')
>>> f'{10:#o}', f'{10:o}'
('0o12', '12')

Veja também format() para mais informações.

open(file, mode='r', buffering=- 1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Abre file e retorna um objeto arquivo correspondente. Se o arquivo não puder ser aberto, uma OSError é levantada. Veja Leitura e escrita de arquivos para mais exemplos de como usar esta função.

file is a path-like object giving the pathname (absolute or relative to the current working directory) of the file to be opened or an integer file descriptor of the file to be wrapped. (If a file descriptor is given, it is closed when the returned I/O object is closed unless closefd is set to False.)

mode is an optional string that specifies the mode in which the file is opened. It defaults to 'r' which means open for reading in text mode. Other common values are 'w' for writing (truncating the file if it already exists), 'x' for exclusive creation, and 'a' for appending (which on some Unix systems, means that all writes append to the end of the file regardless of the current seek position). In text mode, if encoding is not specified the encoding used is platform-dependent: locale.getpreferredencoding(False) is called to get the current locale encoding. (For reading and writing raw bytes use binary mode and leave encoding unspecified.) The available modes are:

Caractere

Significado

'r'

abre para leitura (padrão)

'w'

abre para escrita, truncando o arquivo primeiro (removendo tudo o que estiver contido no mesmo)

'x'

abre para criação exclusiva, falhando caso o arquivo exista

'a'

open for writing, appending to the end of file if it exists

'b'

binary mode

't'

modo texto (padrão)

'+'

aberto para atualização (leitura e escrita)

The default mode is 'r' (open for reading text, a synonym of 'rt'). Modes 'w+' and 'w+b' open and truncate the file. Modes 'r+' and 'r+b' open the file with no truncation.

Conforme mencionado em Visão Geral, Python diferencia entre entrada/saída binária e de texto. Arquivos abertos em modo binário (incluindo 'b' no parâmetro mode) retornam o conteúdo como objetos bytes sem usar nenhuma decodificação. No modo texto (o padrão, ou quando 't' é incluído no parâmetro mode), o conteúdo do arquivo é retornado como str, sendo os bytes primeiramente decodificados usando uma codificação dependente da plataforma, ou usando a codificação definida em encoding se fornecida.

There is an additional mode character permitted, 'U', which no longer has any effect, and is considered deprecated. It previously enabled universal newlines in text mode, which became the default behavior in Python 3.0. Refer to the documentation of the newline parameter for further details.

Nota

Python não depende da noção básica do sistema operacional sobre arquivos de texto; todo processamento é feito pelo próprio Python, e é então independente de plataforma.

buffering é um inteiro opcional usado para definir a política de buffering. Passe o valor 0 para desativar o buffering (permitido somente em modo binário), passe 1 para selecionar buffering de linha (permitido somente em modo texto), e um inteiro > 1 para indicar o tamanho em bytes de um buffer com tamanho fixo. Quando nenhum valor é fornecido no argumento buffering, a política de buffering padrão funciona conforme as seguintes regras:

  • Arquivos binários são armazenados em pedaços de tamanho fixo; o tamanho do buffer é escolhido usando uma heurística que tenta determinar o “tamanho de bloco” subjacente do dispositivo, e usa io.DEFAULT_BUFFER_SIZE caso não consiga. Em muitos sistemas, o buffer possuirá tipicamente 4096 ou 8192 bytes de comprimento.

  • Arquivos de texto “interativos” (arquivos para os quais isatty() retornam True) usam buffering de linha. Outros arquivos de texto usam a política descrita acima para arquivos binários.

encoding é o nome da codificação usada para codificar ou decodificar o arquivo. Isto deve ser usado apenas no modo texto. A codificação padrão depende da plataforma (seja qual valor locale.getpreferredencoding() retornar), mas qualquer codificador de texto suportado pelo Python pode ser usada. Veja o módulo codecs para a lista de codificações suportadas.

errors é uma string opcional que especifica como erros de codificação e de decodificação devem ser tratados — isso não pode ser utilizado no modo binário. Uma variedade de tratadores de erro padrão estão disponíveis (listados em Error Handlers), apesar que qualquer nome para tratamento de erro registrado com codecs.register_error() também é válido. Os nomes padrões incluem:

  • 'strict' para levantar uma exceção ValueError se existir um erro de codificação. O valor padrão None tem o mesmo efeito.

  • 'ignore' ignora erros. Note que ignorar erros de código pode levar à perda de dados.

  • 'replace' faz um marcador de substituição (tal como '?') ser inserido onde existem dados malformados.

  • 'surrogateescape' will represent any incorrect bytes as low surrogate code units ranging from U+DC80 to U+DCFF. These surrogate code units will then be turned back into the same bytes when the surrogateescape error handler is used when writing data. This is useful for processing files in an unknown encoding.

  • 'xmlcharrefreplace' é suportado apenas ao gravar em um arquivo. Os caracteres não suportados pela codificação são substituídos pela referência de caracteres XML apropriada &#nnn;.

  • 'backslashreplace' substitui dados malformados pela sequência de escape utilizando contrabarra do Python.

  • 'namereplace' (também é suportado somente quando estiver escrevendo) substitui caractere não suportados com sequências de escape \N{...}.

newline controla como o modo de novas linhas universais funciona (se aplica apenas ao modo texto). Ele pode ser None, '', '\n', '\r' e '\r\n'. Ele funciona da seguinte forma:

  • Ao ler a entrada do fluxo, se newline for None, o modo universal de novas linhas será ativado. As linhas na entrada podem terminar em '\n', '\r' ou '\r\n', e são traduzidas para '\n' antes de retornar ao chamador. Se for '', o modo de novas linhas universais será ativado, mas as terminações de linha serão retornadas ao chamador sem tradução. Se houver algum dos outros valores legais, as linhas de entrada são finalizadas apenas pela string especificada e a finalização da linha é retornada ao chamador sem tradução.

  • Ao gravar a saída no fluxo, se newline for None, quaisquer caracteres '\n' gravados serão traduzidos para o separador de linhas padrão do sistema, os.linesep. Se newline for '' ou '\n', nenhuma tradução ocorrerá. Se newline for um dos outros valores legais, qualquer caractere '\n' escrito será traduzido para a string especificada.

If closefd is False and a file descriptor rather than a filename was given, the underlying file descriptor will be kept open when the file is closed. If a filename is given closefd must be True (the default); otherwise, an error will be raised.

Um abridor personalizado pode ser usado passando um chamável como opener. O descritor de arquivo subjacente para o objeto arquivo é obtido chamando opener com (file, flags). opener deve retornar um descritor de arquivo aberto (passando os.open como opener resulta em funcionalidade semelhante à passagem de None).

O arquivo recém-criado é non-inheritable.

O exemplo a seguir usa o parâmetro dir_fd da função os.open() para abrir um arquivo relativo a um determinado diretório:

>>> import os
>>> dir_fd = os.open('somedir', os.O_RDONLY)
>>> def opener(path, flags):
...     return os.open(path, flags, dir_fd=dir_fd)
...
>>> with open('spamspam.txt', 'w', opener=opener) as f:
...     print('This will be written to somedir/spamspam.txt', file=f)
...
>>> os.close(dir_fd)  # don't leak a file descriptor

O tipo de objeto arquivo retornado pela função open() depende do modo. Quando open() é usado para abrir um arquivo no modo texto ('w', 'r', 'wt', 'rt', etc.), retorna uma subclasse de io.TextIOBase (especificamente io.TextIOWrapper). Quando usada para abrir um arquivo em modo binário com buffer, a classe retornada é uma subclasse de io.BufferedIOBase. A classe exata varia: no modo binário de leitura, ele retorna uma io.BufferedReader; nos modos binário de gravação e binário anexado, ele retorna um io.BufferedWriter e, no modo leitura/gravação, retorna um io.BufferedRandom. Quando o buffer está desativado, o fluxo bruto, uma subclasse de io.RawIOBase, io.FileIO, é retornado.

See also the file handling modules, such as fileinput, io (where open() is declared), os, os.path, tempfile, and shutil.

Levanta um auditing event open com os argumentos file, mode, flags.

Os argumentos mode e flags podem ter sido modificados ou inferidos a partir da chamada original.

Alterado na versão 3.3:
  • O parâmetro opener foi adicionado.

  • O modo 'x' foi adicionado.

  • IOError costumava ser levantado, agora ele é um codinome para OSError.

  • FileExistsError agora é levantado se o arquivo aberto no modo de criação exclusivo ('x') já existir.

Alterado na versão 3.4:
  • O arquivo agora é não herdável.

Deprecated since version 3.4, removed in version 3.10: O modo 'U'.

Alterado na versão 3.5:
  • Se a chamada de sistema é interrompida e o tratador de sinal não levanta uma exceção, a função agora tenta novamente a chamada de sistema em vez de levantar uma exceção InterruptedError (consulte PEP 475 para entender a lógica).

  • O tratador de erros 'namereplace' foi adicionado.

Alterado na versão 3.6:
  • Suporte adicionado para aceitar objetos implementados os.PathLike.

  • No Windows, a abertura de um buffer do console pode retornar uma subclasse de io.RawIOBase que não seja io.FileIO.

ord(c)

Dada uma string que representa um caractere Unicode, retorna um número inteiro representando o ponto de código Unicode desse caractere. Por exemplo, ord('a') retorna o número inteiro 97 e ord('€') (sinal do Euro) retorna 8364. Este é o inverso de chr().

pow(base, exp[, mod])

Retorna base à potência de exp; se mod estiver presente, retorna base à potência exp, módulo mod (calculado com mais eficiência do que pow(base, exp) % mod). A forma de dois argumentos pow(base, exp) é equivalente a usar o operador de potência: base**exp.

The arguments must have numeric types. With mixed operand types, the coercion rules for binary arithmetic operators apply. For int operands, the result has the same type as the operands (after coercion) unless the second argument is negative; in that case, all arguments are converted to float and a float result is delivered. For example, pow(10, 2) returns 100, but pow(10, -2) returns 0.01. For a negative base of type int or float and a non-integral exponent, a complex result is delivered. For example, pow(-9, 0.5) returns a value close to 3j.

Para operandos int base e exp, se mod estiver presente, mod também deve ser do tipo inteiro e mod deve ser diferente de zero. Se mod estiver presente e exp for negativo, base deve ser relativamente primo para mod. Nesse caso, pow(inv_base, -exp, mod) é retornado, onde inv_base é um inverso ao base módulo mod.

Aqui está um exemplo de computação de um inverso para 38 módulo 97:

>>> pow(38, -1, mod=97)
23
>>> 23 * 38 % 97 == 1
True

Alterado na versão 3.8: Para operandos int, a forma de três argumentos de pow agora permite que o segundo argumento seja negativo, permitindo o cálculo de inversos modulares.

Alterado na versão 3.8: Permite argumentos de palavra reservada. Anteriormente, apenas argumentos posicionais eram suportados.

print(*objects, sep=' ', end='\n', file=sys.stdout, flush=False)

Print objects to the text stream file, separated by sep and followed by end. sep, end, file, and flush, if present, must be given as keyword arguments.

Todos os argumentos que não são nomeados são convertidos em strings como str() faz e gravados no fluxo, separados por sep e seguidos por end. sep e end devem ser strings; eles também podem ser None, o que significa usar os valores padrão. Se nenhum object for fornecido, print() escreverá apenas end.

O argumento file deve ser um objeto com um método write(string); se ele não estiver presente ou None, então sys.stdout será usado. Como argumentos exibidos no console são convertidos para strings de texto, print() não pode ser usado com objetos de arquivo em modo binário. Para esses casos, use file.write(...) ao invés.

Whether the output is buffered is usually determined by file, but if the flush keyword argument is true, the stream is forcibly flushed.

Alterado na versão 3.3: Adicionado o argumento nomeado flush.

class property(fget=None, fset=None, fdel=None, doc=None)

Retorna um atributo de propriedade.

fget é uma função para obter o valor de um atributo. fset é uma função para definir um valor para um atributo. fdel é uma função para deletar um valor de um atributo. E doc cria um docstring para um atributo.

Um uso comum é para definir um atributo gerenciável x:

class C:
    def __init__(self):
        self._x = None

    def getx(self):
        return self._x

    def setx(self, value):
        self._x = value

    def delx(self):
        del self._x

    x = property(getx, setx, delx, "I'm the 'x' property.")

If c is an instance of C, c.x will invoke the getter, c.x = value will invoke the setter, and del c.x the deleter.

Se fornecido, doc será a docstring do atributo definido por property. Caso contrário, a property copiará a docstring de fget (se ela existir). Isso torna possível criar facilmente propriedades apenas para leitura usando property() como um decorador:

class Parrot:
    def __init__(self):
        self._voltage = 100000

    @property
    def voltage(self):
        """Get the current voltage."""
        return self._voltage

O decorador @property transforma o método voltage() em um “getter” para um atributo somente leitura com o mesmo nome, e define a docstring de voltage para “Get the current voltage.”

Um objeto property possui métodos getter, setter, e deleter usáveis como decoradores, que criam uma cópia da property com o assessor correspondente a função definida para a função com decorador. Isso é explicado melhor com um exemplo:

class C:
    def __init__(self):
        self._x = None

    @property
    def x(self):
        """I'm the 'x' property."""
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

Esse código é exatamente equivalente ao primeiro exemplo. Tenha certeza de nas funções adicionais usar o mesmo nome que a property original (x neste caso).

O objeto property retornado também tem os atributos fget, fset, e fdel correspondendo aos argumentos do construtor.

Alterado na versão 3.5: Agora é possível escrever nas docstrings de objetos property.

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

Em vez de ser uma função, range é realmente um tipo de sequência imutável, conforme documentado em Intervalos e Tipos sequências — list, tuple, range.

repr(object)

Return a string containing a printable representation of an object. For many types, this function makes an attempt to return a string that would yield an object with the same value when passed to eval(); otherwise, the representation is a string enclosed in angle brackets that contains the name of the type of the object together with additional information often including the name and address of the object. A class can control what this function returns for its instances by defining a __repr__() method.

reversed(seq)

Retorna um iterador reverso. seq deve ser um objeto que possui o método __reversed__() ou suporta o protocolo de sequência (o método __len__() e o método __getitem__() com argumentos inteiros começando em 0).

round(number[, ndigits])

Retorna number arredondado para ndigits precisão após o ponto decimal. Se ndigits for omitido ou for None, ele retornará o número inteiro mais próximo de sua entrada.

For the built-in types supporting round(), values are rounded to the closest multiple of 10 to the power minus ndigits; if two multiples are equally close, rounding is done toward the even choice (so, for example, both round(0.5) and round(-0.5) are 0, and round(1.5) is 2). Any integer value is valid for ndigits (positive, zero, or negative). The return value is an integer if ndigits is omitted or None. Otherwise, the return value has the same type as number.

Para um objeto Python geral number, round delega para number.__round__.

Nota

O comportamento de round() para pontos flutuantes pode ser surpreendente: por exemplo, round(2.675, 2) fornece 2.67 em vez do esperado 2.68. Isso não é um bug: é resultado do fato de que a maioria das frações decimais não pode ser representada exatamente como um ponto flutuante. Veja Aritmética de ponto flutuante: problemas e limitações para mais informações.

class set([iterable])

Retorna um novo objeto set, opcionalmente com elementos retirados de iterable. set é uma classe embutida. Veja set e Tipo conjuntos — set, frozenset para documentação sobre esta classe.

Para outros contêineres, consulte as classes embutidas frozenset, list, tuple e dict, bem como o módulo collections.

setattr(object, name, value)

This is the counterpart of getattr(). The arguments are an object, a string, and an arbitrary value. The string may name an existing attribute or a new attribute. The function assigns the value to the attribute, provided the object allows it. For example, setattr(x, 'foobar', 123) is equivalent to x.foobar = 123.

Nota

Since private name mangling happens at compilation time, one must manually mangle a private attribute’s (attributes with two leading underscores) name in order to set it with setattr().

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

Return a slice object representing the set of indices specified by range(start, stop, step). The start and step arguments default to None. Slice objects have read-only data attributes start, stop, and step which merely return the argument values (or their default). They have no other explicit functionality; however, they are used by NumPy and other third-party packages. Slice objects are also generated when extended indexing syntax is used. For example: a[start:stop:step] or a[start:stop, i]. See itertools.islice() for an alternate version that returns an iterator.

sorted(iterable, *, key=None, reverse=False)

Retorna uma nova lista classificada dos itens em iterable.

Possui dois argumentos opcionais que devem ser especificados como argumentos nomeados.

key especifica a função de um argumento usado para extrair uma chave de comparação de cada elemento em iterable (por exemplo, key=str.lower). O valor padrão é None (compara os elementos diretamente).

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.

Usa functools.cmp_to_key() para converter a função das antigas cmp para uma função key.

A função embutida sorted() é garantida como estável. Uma ordenação é estável se garantir não alterar a ordem relativa dos elementos que se comparam da mesma forma — isso é útil para ordenar em várias passagens (por exemplo, ordenar por departamento e depois por nível de salário).

The sort algorithm uses only < comparisons between items. While defining an __lt__() method will suffice for sorting, PEP 8 recommends that all six rich comparisons be implemented. This will help avoid bugs when using the same data with other ordering tools such as max() that rely on a different underlying method. Implementing all six comparisons also helps avoid confusion for mixed type comparisons which can call reflected the __gt__() method.

Para exemplos de classificação e um breve tutorial de classificação, veja HowTo - Ordenação.

@staticmethod

Transforma um método em método estático.

Um método estático não recebe um primeiro argumento implícito. Para declarar um método estático, use este idioma:

class C:
    @staticmethod
    def f(arg1, arg2, ...): ...

A forma @staticmethod é uma função de decorador – veja Definições de função para detalhes.

A static method can be called either on the class (such as C.f()) or on an instance (such as C().f()). Moreover, they can be called as regular functions (such as f()).

Static methods in Python are similar to those found in Java or C++. Also, see classmethod() for a variant that is useful for creating alternate class constructors.

Como todos os decoradores, também é possível chamar staticmethod como uma função regular e fazer algo com seu resultado. Isso é necessário em alguns casos em que você precisa de uma referência para uma função de um corpo de classe e deseja evitar a transformação automática em método de instância. Para esses casos, use este idioma:

def regular_function():
    ...

class C:
    method = staticmethod(regular_function)

Para mais informações sobre métodos estáticos, consulte A hierarquia de tipos padrão.

Alterado na versão 3.10: Static methods now inherit the method attributes (__module__, __name__, __qualname__, __doc__ and __annotations__), have a new __wrapped__ attribute, and are now callable as regular functions.

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

Retorna uma versão str de object. Consulte str() para detalhes.

str é uma classe de string embutida. Para informações gerais sobre strings, consulte Tipo sequência de texto — str.

sum(iterable, /, start=0)

Soma start e os itens de um iterable da esquerda para a direita e retornam o total. Os itens do iterable são normalmente números e o valor inicial não pode ser uma string.

Para alguns casos de uso, existem boas alternativas para sum(). A maneira rápida e preferida de concatenar uma sequência de strings é chamando ''.join(sequence). Para adicionar valores de ponto flutuante com precisão estendida, consulte math.fsum(). Para concatenar uma série de iteráveis, considere usar itertools.chain().

Alterado na versão 3.8: O parâmetro start pode ser especificado como um argumento nomeado.

class super([type[, object-or-type]])

Retorna um objeto proxy que delega chamadas de método a uma classe pai ou irmão do type. Isso é útil para acessar métodos herdados que foram substituídos em uma classe.

O object-or-type determina a ordem de resolução de métodos a ser pesquisada. A pesquisa inicia a partir da classe logo após o type.

Por exemplo, se __mro__ de object-or-type é D -> B -> C -> A -> object e o valor de type é B, então super() procura por C -> A -> object.

O atributo __mro__ do object-or-type lista a ordem de pesquisa de resolução de método usada por getattr() e super(). O atributo é dinâmico e pode mudar sempre que a hierarquia da herança é atualizada.

Se o segundo argumento for omitido, o objeto super retornado é desacoplado. Se o segundo argumento é um objeto, isinstance(obj, type) deve ser verdadeiro. Se o segundo argumento é um tipo, issubclass(type2, type) deve ser verdadeiro (isto é útil para classmethods).

Existem dois casos de uso típicos para super. Em uma hierarquia de classes com herança única, super pode ser usado para se referir a classes-pai sem nomeá-las explicitamente, tornando o código mais sustentável. Esse uso é paralelo ao uso de super em outras linguagens de programação.

O segundo caso de uso é oferecer suporte à herança múltipla cooperativa em um ambiente de execução dinâmica. Esse caso de uso é exclusivo do Python e não é encontrado em idiomas ou linguagens compiladas estaticamente que suportam apenas herança única. Isso torna possível implementar “diagramas em losango”, onde várias classes base implementam o mesmo método. Um bom design exige que tais implementações tenham a mesma assinatura de chamada em todos os casos (porque a ordem das chamadas é determinada em tempo de execução, porque essa ordem se adapta às alterações na hierarquia de classes e porque essa ordem pode incluir classes de irmãos desconhecidas antes do tempo de execução).

Nos dois casos de uso, uma chamada típica de superclasse se parece com isso:

class C(B):
    def method(self, arg):
        super().method(arg)    # This does the same thing as:
                               # super(C, self).method(arg)

Além das pesquisas de método, super() também funciona para pesquisas de atributo. Um possível caso de uso para isso é chamar descritores em uma classe pai ou irmã.

Observe que super() é implementada como parte do processo de vinculação para procura explícita de atributos com ponto, tal como super().__getitem__(nome). Ela faz isso implementando seu próprio método __getattribute__() para pesquisar classes em uma ordem predizível que possui suporte a herança múltipla cooperativa. Logo, super() não é definida para procuras implícitas usando instruções ou operadores como super()[name].

Observe também que, além da forma de argumento zero, super() não se limita ao uso de métodos internos. O formulário de dois argumentos especifica exatamente os argumentos e faz as referências apropriadas. O formulário de argumento zero funciona apenas dentro de uma definição de classe, pois o compilador preenche os detalhes necessários para recuperar corretamente a classe que está sendo definida, além de acessar a instância atual para métodos comuns.

Para sugestões práticas sobre como projetar classes cooperativas usando super(), consulte o guia para uso de super().

class tuple([iterable])

Ao invés de ser uma função, tuple é na verdade um tipo de sequência imutável, conforme documentado em Tuplas e Tipos sequências — list, tuple, range.

class type(object)
class type(name, bases, dict, **kwds)

Com um argumento, retorna o tipo de um object. O valor de retorno é um tipo de objeto e geralmente o mesmo objeto retornado por object.__class__.

A função embutida isinstance() é recomendada para testar o tipo de um objeto, porque ela leva sub-classes em consideração.

Com três argumentos, retorna um novo objeto type. Esta é essencialmente a forma dinâmica da instrução class. A string name é o nome da classe e se torna o atributo __name__. A tupla bases contém as classes bases e se torna o atributo __bases__; se vazio, object, a base final de todas as classes é adicionada. O dicionário dict contém definições de atributo e método para o corpo da classe; ele pode ser copiado ou envolto antes de se tornar o atributo __dict__. As duas instruções a seguir criam objetos type idênticos:

>>> class X:
...     a = 1
...
>>> X = type('X', (), dict(a=1))

Veja também Objetos tipo.

Argumentos nomeados fornecidos para a forma de três argumentos são passados para a máquina metaclasse apropriada (geralmente __init_subclass__()) da mesma forma que palavras-chave em uma definição de classe (além de metaclasse) fariam.

Veja também Personalizando a criação de classe.

Alterado na versão 3.6: Sub-classes de type que não fazem sobrecarga de type.__new__ não podem mais usar a forma com apenas um argumento para obter o tipo de um objeto.

vars([object])

Retorna o atributo __dict__ para um módulo, classe, instância, or qualquer outro objeto com um atributo __dict__.

Objetos como modelos e instâncias têm um atributo atualizável __dict__; porém, outros projetos podem ter restrições de escrita em seus atributos __dict__ (por exemplo, classes usam um types.MappingProxyType para prevenir atualizações diretas a dicionário).

Sem um argumento, vars() funciona como locals(). Perceba que, o dicionário locals é apenas útil para leitura, pelo fato de alterações no dicionário locals serem ignoradas.

Uma exceção TypeError é levantada se um objeto é especificado, mas ela não tem um atributo __dict__ (por exemplo, se sua classe define o atributo __slots__).

zip(*iterables, strict=False)

Iterate over several iterables in parallel, producing tuples with an item from each one.

Exemplo:

>>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):
...     print(item)
...
(1, 'sugar')
(2, 'spice')
(3, 'everything nice')

More formally: zip() returns an iterator of tuples, where the i-th tuple contains the i-th element from each of the argument iterables.

Another way to think of zip() is that it turns rows into columns, and columns into rows. This is similar to transposing a matrix.

zip() is lazy: The elements won’t be processed until the iterable is iterated on, e.g. by a for loop or by wrapping in a list.

One thing to consider is that the iterables passed to zip() could have different lengths; sometimes by design, and sometimes because of a bug in the code that prepared these iterables. Python offers three different approaches to dealing with this issue:

  • By default, zip() stops when the shortest iterable is exhausted. It will ignore the remaining items in the longer iterables, cutting off the result to the length of the shortest iterable:

    >>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))
    [(0, 'fee'), (1, 'fi'), (2, 'fo')]
    
  • zip() is often used in cases where the iterables are assumed to be of equal length. In such cases, it’s recommended to use the strict=True option. Its output is the same as regular zip():

    >>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))
    [('a', 1), ('b', 2), ('c', 3)]
    

    Unlike the default behavior, it checks that the lengths of iterables are identical, raising a ValueError if they aren’t:

    >>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True))
    Traceback (most recent call last):
      ...
    ValueError: zip() argument 2 is longer than argument 1
    

    Without the strict=True argument, any bug that results in iterables of different lengths will be silenced, possibly manifesting as a hard-to-find bug in another part of the program.

  • Shorter iterables can be padded with a constant value to make all the iterables have the same length. This is done by itertools.zip_longest().

Edge cases: With a single iterable argument, zip() returns an iterator of 1-tuples. With no arguments, it returns an empty iterator.

Tips and tricks:

  • The left-to-right evaluation order of the iterables is guaranteed. This makes possible an idiom for clustering a data series into n-length groups using zip(*[iter(s)]*n, strict=True). This repeats the same iterator n times so that each output tuple has the result of n calls to the iterator. This has the effect of dividing the input into n-length chunks.

  • zip() em conjunto com o operador * pode ser usado para descompactar uma lista:

    >>> x = [1, 2, 3]
    >>> y = [4, 5, 6]
    >>> list(zip(x, y))
    [(1, 4), (2, 5), (3, 6)]
    >>> x2, y2 = zip(*zip(x, y))
    >>> x == list(x2) and y == list(y2)
    True
    

Alterado na versão 3.10: Added the strict argument.

__import__(name, globals=None, locals=None, fromlist=(), level=0)

Nota

Esta é uma função avançada que não é necessária na programação diária do Python, ao contrário de importlib.import_module().

Esta função é chamada pela instrução import. Ela pode ser substituída (importando o módulo builtins e atribuindo a builtins.__import__) para alterar a semântica da instrução import, mas isso é fortemente desencorajado, pois geralmente é mais simples usar ganchos de importação (consulte PEP 302) para atingir os mesmos objetivos e não causa problemas com o código que pressupõe que a implementação de importação padrão esteja em uso. O uso direto de __import__() também é desencorajado em favor de importlib.import_module().

The function imports the module name, potentially using the given globals and locals to determine how to interpret the name in a package context. The fromlist gives the names of objects or submodules that should be imported from the module given by name. The standard implementation does not use its locals argument at all and uses its globals only to determine the package context of the import statement.

level especifica se é necessário usar importações absolutas ou relativas. 0 (o padrão) significa apenas realizar importações absolutas. Valores positivos para level indicam o número de diretórios pai a serem pesquisados em relação ao diretório do módulo que chama __import__() (consulte PEP 328 para obter detalhes).

Quando a variável name está no formato package.module, normalmente, o pacote de nível superior (o nome até o primeiro ponto) é retornado, não o módulo nomeado por name. No entanto, quando um argumento fromlist não vazio é fornecido, o módulo nomeado por name é retornado.

Por exemplo, a instrução importar spam resulta em bytecode semelhante ao seguinte código:

spam = __import__('spam', globals(), locals(), [], 0)

A instrução import spam.ham resulta nesta chamada:

spam = __import__('spam.ham', globals(), locals(), [], 0)

Observe como __import__() retorna o módulo de nível superior aqui, porque este é o objeto vinculado a um nome pela instrução import.

Por outro lado, a instrução from spam.ham import eggs, sausage as saus resulta em

_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
eggs = _temp.eggs
saus = _temp.sausage

Aqui, o módulo spam.ham é retornado de __import__(). A partir desse objeto, os nomes a serem importados são recuperados e atribuídos aos seus respectivos nomes.

Se você simplesmente deseja importar um módulo (potencialmente dentro de um pacote) pelo nome, use importlib.import_module().

Alterado na versão 3.3: Valores negativos para level não são mais suportados (o que também altera o valor padrão para 0).

Alterado na versão 3.9: Quando as opções de linha de comando -E ou -I estão sendo usadas, a variável de ambiente PYTHONCASEOK é agora ignorada.

Notas de rodapé

1

Observe que o analisador sintático aceita apenas a convenção de fim de linha no estilo Unix. Se você estiver lendo o código de um arquivo, use o modo de conversão de nova linha para converter novas linhas no estilo Windows ou Mac.