HOWTO · Python

Sobrecarregar um construtor em Python

Este tutorial demonstra como sobrecarregar um construtor em Python

Nesta página

Python não escolhe entre vários métodos __init__ comparando seus parâmetros. Se uma classe define __init__ mais de uma vez, a definição posterior substitui a anterior; assim, somente ela fica disponível quando uma instância é criada. Para oferecer várias formas de inicializar um objeto, reúna as opções em um único inicializador, exponha métodos de fábrica com nomes distintos ou use valores padrão úteis nos parâmetros do inicializador.

O que significa sobrecarga de construtores em Python

Em linguagens com sobrecarga de construtores baseada em assinaturas, o ambiente de execução pode escolher um construtor pelo tipo ou pela quantidade de parâmetros. Python não faz isso com definições repetidas de __init__. Um único __init__ pode aceitar argumentos flexíveis e tomar uma decisão deliberada, mas isso é uma escolha feita dentro de um método, não uma sobrecarga nativa. Deixe explícitas as formas aceitas para que quem chama saiba quais valores a classe suporta.

Use *args para decidir pelo tipo ou pela quantidade de argumentos

O parâmetro *args reúne os argumentos posicionais em uma tupla. Você pode verificar seu tamanho ou os tipos dos valores e, então, inicializar a instância de acordo com eles. Confira se o argumento existe antes de acessá-lo e defina o que a classe deve fazer quando uma forma de entrada não for aceita. O exemplo executável a seguir aceita um inteiro ou uma string e informa o valor escolhido. As mensagens e os rótulos exibidos pelos exemplos desta seção permanecem em inglês.

Execute este exemplo:

class Greeting:
    def __init__(self, *args):
        if len(args) != 1:
            self.message = "Pass one integer or string"
        else:
            value = args[0]
            if isinstance(value, int):
                self.message = str(value)
            elif isinstance(value, str):
                self.message = "Hello from " + value
            else:
                self.message = "Pass an integer or string"


print(Greeting("Delft").message)

Verificar a quantidade de argumentos antes de acessar args[0] permite tratar com segurança uma chamada sem argumentos posicionais. Essa verificação também rejeita argumentos extras. Em Python, bool é uma subclasse de int; por isso, isinstance(True, int) retorna verdadeiro. Se valores booleanos não devem ser aceitos como inteiros, use uma verificação de tipo exata.

A escolha pela quantidade é útil quando cada número de argumentos posicionais tem um significado claro. Este inicializador aceita exatamente zero, um ou dois argumentos: sem argumentos, usa o intervalo padrão; com um, o argumento define o limite final; com dois, eles definem os limites inicial e final. Qualquer outra quantidade gera uma mensagem clara. Cada ramo verifica a quantidade antes de acessar args, evitando tentar ler um valor inexistente tanto quando não há argumentos quanto quando a quantidade não é aceita. As mensagens exibidas neste exemplo também permanecem em inglês.

Execute este exemplo:

class RangeSpec:
    def __init__(self, *args):
        if len(args) == 0:
            self.start, self.stop = 0, 10
        elif len(args) == 1:
            self.start, self.stop = 0, args[0]
        elif len(args) == 2:
            self.start, self.stop = args
        else:
            self.start, self.stop = None, None
            self.message = "Pass zero, one, or two values"

    def describe(self):
        if self.start is None:
            return self.message
        return f"Range from {self.start} to {self.stop}"


for spec in (RangeSpec(), RangeSpec(5), RangeSpec(2, 5), RangeSpec(1, 2, 3)):
    print(spec.describe())

As quatro chamadas percorrem todas as quantidades aceitas e também uma quantidade acima do limite. Se houver muitas formas de chamada, prefira parâmetros nomeados ou métodos de fábrica, para que quem chama não precise memorizar o significado de cada quantidade de argumentos posicionais.

Use métodos de fábrica com @classmethod como construtores alternativos

Um @classmethod recebe a classe como primeiro argumento, convencionalmente chamado de cls. Um método de fábrica pode converter outra representação nos valores exigidos pelo inicializador habitual e, então, retornar cls(...). Isso cria uma instância e também funciona naturalmente com subclasses, pois cls se refere à classe pela qual o método foi chamado. Métodos de fábrica são caminhos nomeados para criar objetos; eles não acrescentam sobrecargas a __init__.

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    @classmethod
    def from_pair(cls, pair):
        return cls(pair[0], pair[1])


point = Point.from_pair((3, 4))
print(point.x, point.y)

Use fábricas separadas quando os formatos de entrada tiverem nomes significativos, como from_file, from_row ou from_coordinates. Valide ou normalize os dados na fábrica quando essa responsabilidade fizer parte da conversão. Mantenha o inicializador principal como o único lugar que estabelece o estado necessário do objeto.

Use argumentos padrão para padrões de inicialização opcionais

Valores padrão funcionam bem quando os parâmetros são realmente opcionais e seu significado continua claro. Eles permitem que quem chama omita valores sem acrescentar lógica de escolha. Prefira valores imutáveis, como números, strings ou None; um valor mutável, como uma lista, geralmente deve ser criado dentro do método para evitar que as instâncias o compartilhem por acidente. O exemplo mantém o nome padrão Guest em inglês.

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

class Profile:
    def __init__(self, name="Guest", score=0):
        self.name = name
        self.score = score


for profile in (Profile(), Profile("Mina"), Profile("Mina", 7)):
    print(profile.name, profile.score)

Neste caso, quem chama pode omitir ambos os valores opcionais, informar apenas um nome ou fornecer os dois valores. Valores padrão são menos adequados quando a omissão tem vários significados, quando os parâmetros dependem uns dos outros ou quando muitas combinações posicionais ficam difíceis de memorizar. Nesses casos, parâmetros somente nomeados ou métodos de fábrica com nomes claros podem tornar as chamadas mais compreensíveis.

Escolha o padrão de construtor adequado

Use valores padrão para um pequeno conjunto de valores opcionais comuns. Use um método de fábrica quando a criação começa a partir de outra representação ou quando o caminho de criação merece um nome descritivo. Use a decisão com *args somente quando um conjunto compacto e estável de formas posicionais fizer parte da API pretendida; verifique quantidades e tipos antes de usar os valores. Para validações complexas, ramos explícitos e mensagens de erro úteis são mais fáceis de manter do que truques engenhosos com tipos.

É possível combinar essas técnicas: fábricas podem validar os dados e depois chamar o mesmo inicializador, enquanto valores padrão tratam campos opcionais. Escolha a interface mais simples que torne evidentes as chamadas válidas e previsíveis as chamadas não aceitas. A regra essencial é que cada classe tem uma única definição efetiva de __init__; a flexibilidade vem da lógica e das alternativas nomeadas que você oferece ao redor dela.