Introdução à programação orientada a objetos em Python

Você já usou objetos sempre que trabalhou com um número, uma string, uma lista ou um dicionário. Um objeto tem um tipo, um valor ou estado e operações que aceita. Até funções e None são objetos. Escrever sua própria classe amplia esse sistema familiar.

Encontre o tipo e os métodos de um objeto

type("hello") retorna <class 'str'>; type([1, 2]) retorna <class 'list'>. As palavras tipo e classe descrevem o mesmo papel aqui. isinstance(3.5, float) é True, enquanto isinstance("3.5", float) é False: o segundo valor é texto, embora pareça numérico.

Um método é uma função fornecida por um tipo. Em "ada lovelace".title(), a string antes do ponto é o objeto, title é o método e os parênteses o chamam. O resultado é "Ada Lovelace". dir(value) lista os nomes oferecidos por um objeto; nomes como __len__ são métodos especiais que ligam objetos a operações do Python como len(value).

Acompanhe o resultado e o original

Uma chamada de método pode retornar um resultado, alterar um objeto ou fazer ambos. Verifique o comportamento do método antes de decidir o que atribuir.

word = "level"
print(word.count("l"))  # 2
print(word.upper())     # LEVEL
print(word)             # level

nums = [3, 1, 2]
result = nums.sort()
print(nums)             # [1, 2, 3]
print(result)           # None

Strings são imutáveis: seu conteúdo não pode mudar. upper() retorna outra string, então word mantém seu valor original. Para manter o resultado em maiúsculas sob esse nome, escreva word = word.upper().

Listas são mutáveis. sort() altera a própria lista e retorna None. Escrever nums = nums.sort() perde a referência à lista armazenada em nums e atribui None. Use nums.sort() em uma linha própria ou nums = sorted(nums) para obter uma nova lista ordenada. Para um dicionário, {"a": 1}.get("b", 0) retorna 0 porque a chave solicitada está ausente.

Parênteses também importam. word.upper é um objeto de método; word.upper() o executa. O mesmo comportamento pode ser oferecido por muitos objetos: "cat".upper() e "dog".upper() usam um mesmo tipo de método com dados de string diferentes.

Distinga igualdade de identidade

Igualdade verifica se os valores correspondem. Identidade verifica se dois nomes se referem a um mesmo objeto.

a = [1, 2]
b = [1, 2]
c = a
print(a == b)  # True
print(a is b)  # False
print(c is a)  # True
c.append(3)
print(a)       # [1, 2, 3]
print(b)       # [1, 2]

a e b começam com conteúdos iguais, mas são listas separadas. c = a cria uma referência alternativa, outro nome para a mesma lista. Adicionar um item por meio de c altera o objeto ao qual a também se refere. Isso não altera a lista separada armazenada em b. Ao rastrear um programa, desenhe uma caixa por objeto e uma seta de cada nome até sua caixa.

Uma classe define um tipo que você pode usar em seu próprio programa. Cada objeto criado a partir dela é uma instância. Uma classe descreve o tipo de coisa; as instâncias armazenam os dados de coisas específicas. Um formulário em branco e suas cópias preenchidas são uma comparação útil.

Escreva uma classe e chame-a

Uma instrução de classe tem a palavra reservada class, um nome, dois-pontos e um corpo indentado. pass fornece um corpo vazio enquanto você experimenta a estrutura.

class Book:
    pass

b1 = Book()
b2 = Book()
print(b1 is b2)           # False
print(isinstance(b1, Book))  # True

Cada chamada Book() cria uma instância separada. Em um script, type(b1) mostra <class '__main__.Book'>. A instrução de classe deve ser executada antes que o código tente usar Book. Você também pode definir uma classe em um módulo e importá-la com from library import Book, depois criar instâncias no programa chamador.

Siga as convenções de nomenclatura do Python: Book, BankAccount e ShoppingCart usam CapWords, com cada palavra iniciada por maiúscula. Variáveis e métodos usam palavras minúsculas separadas por sublinhados, como book_count e add_item. Use quatro espaços para cada nível de indentação.

Armazene dados em cada instância

Um atributo é um valor nomeado acessado com um ponto. Atribuir um atributo o armazena; ler o mesmo nome recupera seu valor.

b1.title = "Dune"
b2.title = "Emma"
b1.pages = 412
print(b1.title)  # Dune
print(b2.title)  # Emma
print(b1.pages)  # 412

Os dados pertencem à instância selecionada. Dar a b1 um atributo pages não dá um a b2. Ler b2.pages agora provoca AttributeError, pois esse objeto não tem um atributo chamado pages.

Atribuições podem criar novos nomes sem verificar sua intenção. Depois de b1.titel = "X", o b1.title original ainda armazena "Dune"; o objeto ganhou um segundo atributo com um nome escrito incorretamente. Se um valor parecer não mudar, compare a escrita no ponto em que ele foi atribuído e no ponto em que foi lido.

Mantenha a classe e suas instâncias distintas

b = Book dá outro nome à classe. Isso não cria um livro. Se os títulos foram definidos apenas nas instâncias, pedir Book.title provoca AttributeError; não há um único título compartilhado pelo tipo.

Dê a todo objeto um início confiável

Definir atributos de fora é possível, mas deixa a configuração espalhada pelo programa. Um livro pode receber um título e uma contagem de páginas, enquanto outro recebe apenas um título. O código posterior não pode pressupor com segurança que ambos têm pages.

Um método de configuração chamado __init__ coloca as atribuições iniciais dentro da classe. Cada chamada de criação segue então o mesmo processo de configuração. A classe pode exigir um título e criar outros atributos com valores iniciais adequados, para que o código chamador não precise lembrar uma sequência separada de atribuições.

Toda conta recém-criada precisa de um titular e de um saldo inicial. Colocar essa configuração em __init__ dá a cada objeto os atributos que os métodos posteriores esperam. O Python cria a instância primeiro e depois chama __init__ para inicializá-la.

Conecte argumentos a atributos

class BankAccount:
    def __init__(self, owner, balance=0):
        self.owner = owner
        self.balance = balance
        self.transactions = []

acct = BankAccount("Maya", 50)
other = BankAccount("Leo")

Na primeira chamada, o Python passa a nova conta como self, "Maya" como owner e 50 como balance. As atribuições fazem acct.owner ser igual a "Maya" e acct.balance ser igual a 50. A segunda chamada usa o saldo padrão, então other.balance é 0.

self é o parâmetro que recebe o objeto atual. É uma convenção, não uma palavra reservada do Python. Use esse nome para que os leitores reconheçam o objeto imediatamente. O código chamador o deixa de fora: BankAccount("Maya", 50) fornece dois argumentos, não três.

Mantenha nomes locais e dados armazenados separados

Em self.owner = owner, o nome à direita é um parâmetro local. O nome à esquerda é um atributo armazenado no objeto. Quando a inicialização termina, outros métodos ainda podem usar self.owner.

Escrever balance = balance apenas reatribui o nome local. Isso não cria um atributo, então ler acct.balance depois falha. Coloque self. antes de cada atributo que deve permanecer como parte do objeto.

Planeje a inicialização listando o que cada instância precisa. Valores obrigatórios tornam-se parâmetros após self; valores opcionais podem ter padrões. Valores que sempre começam da mesma forma podem ser atribuídos no corpo, como self.visits = 0. Uma lista criada por self.transactions = [] é criada novamente em cada chamada.

Evite uma lista padrão compartilhada

Um argumento padrão é avaliado quando o Python define o método. Com def __init__(self, items=[]), chamadas que omitem items recebem a mesma lista. Se o inicializador armazenar essa lista diretamente, alterar os itens de um objeto altera os itens vistos por outro.

Use None como padrão e crie uma nova lista durante cada chamada:

class Cart:
    def __init__(self, items=None):
        self.items = [] if items is None else list(items)

a = Cart()
b = Cart()
a.items.append("pen")
print(b.items)  # []

list(items) também cria uma nova lista externa quando o código chamador fornece uma. Os objetos dentro dessa lista ainda são referências compartilhadas; criar a lista não recria cada item.

Leia erros de configuração

Em BankAccount() falta o argumento obrigatório owner, o que provoca TypeError. Compare a chamada com os parâmetros após self.

A grafia __init__ tem dois sublinhados de cada lado. _init_ é um nome de método comum e não realiza essa configuração automaticamente. __init__ deve retornar None, então normalmente deixe de fora uma instrução de retorno. Retornar um saldo provoca TypeError; a própria chamada da classe fornece a nova instância ao código chamador.

Alguns valores descrevem um objeto; outros descrevem o tipo como um todo. O tamanho de uma pizza pertence àquela pizza. Um limite de ingredientes ou uma contagem de pizzas criadas pode pertencer à classe. O local de uma atribuição determina que tipo de atributo ela cria.

Coloque o valor no lugar certo

class Pizza:
    MAX_TOPPINGS = 5
    count = 0

    def __init__(self, size):
        self.size = size
        self.toppings = []
        Pizza.count += 1

p1 = Pizza("large")
p2 = Pizza("small")

size e toppings são atributos de instância, definidos em self. Cada pizza tem seus próprios valores. MAX_TOPPINGS e count são atributos de classe, atribuídos no corpo da classe fora de um método. Letras maiúsculas indicam um valor destinado a ser uma constante; elas não impedem a reatribuição.

Após essas chamadas, Pizza.count é 2. Cada inicializador atualiza o mesmo atributo de classe. p1.size é "large", enquanto p2.size é "small".

Rastreie a busca e o sombreamento

Para atributos de dados comuns como esses, a leitura de p1.MAX_TOPPINGS verifica primeiro a instância e depois a classe. Como nenhum valor está armazenado em p1, o Python encontra Pizza.MAX_TOPPINGS, que é 5.

Uma atribuição por meio de uma instância tem outro efeito:

p1.MAX_TOPPINGS = 8
Pizza.MAX_TOPPINGS = 6
print(p1.MAX_TOPPINGS)     # 8
print(p2.MAX_TOPPINGS)     # 6
print(Pizza.MAX_TOPPINGS)  # 6

A primeira linha cria um atributo de instância em p1. Ele sombreia o valor de classe para esse objeto. Alterar o valor de classe depois alcança p2, que ainda lê da classe, mas não substitui o valor próprio de p1.

Observe duas formas de compartilhamento acidental

Se o inicializador usasse self.count += 1, o Python leria o 0 da classe, somaria um e armazenaria um atributo de instância. Cada nova pizza receberia seu próprio count de 1, enquanto Pizza.count permaneceria em 0. Use o nome da classe ao atualizar um contador de toda a classe.

Uma lista no corpo da classe causa um problema diferente. Com toppings = [], as instâncias que não têm um atributo separado para ingredientes encontram todas a mesma lista. p1.toppings.append("olives") altera essa lista compartilhada; não atribui um novo atributo de instância. Coloque self.toppings = [] em __init__ quando cada pizza precisar de seus próprios ingredientes.

Inspecione os dados próprios de um objeto

Para a p2 original, vars(p2) fornece {'size': 'small', 'toppings': []}. Os valores de classe estão ausentes porque ficam em Pizza. Isso é útil ao depurar uma busca com resultado inesperado: verifique se a instância tem um valor próprio e depois inspecione o valor da classe. Uma configuração compartilhada pertence à classe; um nome, tamanho, saldo ou coleção individual pertence à instância.

Um objeto deve começar em um estado que seus métodos possam usar. Um retângulo com largura negativa não pode representar a forma pretendida. Uma regra que deve permanecer verdadeira para todos os objetos de uma classe é uma invariante. A validação verifica essas regras antes de aceitar dados.

Verifique antes de armazenar

class Rectangle:
    def __init__(self, width, height):
        if width <= 0:
            raise ValueError("width must be positive")
        if height <= 0:
            raise ValueError("height must be positive")
        self.width = width
        self.height = height

Rectangle(3, 4) passa pelas duas verificações e retorna um objeto inicializado. Rectangle(-2, 4) provoca ValueError na primeira verificação. As atribuições posteriores não são executadas. Se o programa não capturar essa exceção, a execução para nesse ponto.

Suponha que r já se refira a um retângulo válido. Em r = Rectangle(-2, 4), a chamada à direita falha antes da atribuição. r mantém seu valor anterior. Se r não tinha valor antes da chamada que falhou, a atribuição não cria um.

Escolha uma exceção útil

Uma largura numérica negativa é um erro de valor. Um texto fornecido onde se exige um número é um erro de tipo. A comparação com 0 neste exemplo já provoca TypeError para texto. Uma classe também pode verificar um tipo explicitamente com isinstance quando precisa de uma mensagem mais clara.

Escreva mensagens que nomeiem a regra, como "width must be positive". Uma mensagem que diz apenas "bad input" deixa o código chamador sem saber qual valor precisa ser corrigido.

Deixe o código chamador tratar a recuperação

while True:
    try:
        width = float(input("Width: "))
        room = Rectangle(width, 3)
        break
    except ValueError as error:
        print("Try again:", error)

Digitar abc falha durante float; digitar -2 passa pela conversão, mas falha em Rectangle. Ambos provocam ValueError, então esse laço trata os dois casos. A classe estabelece sua regra de dados, enquanto o código chamador decide solicitar a entrada novamente.

Imprimir um aviso dentro de __init__ não rejeita a chamada. Se a execução continuar, o programa pode receber um objeto inválido e falhar mais tarde ao usá-lo. Lançar uma exceção interrompe a configuração malsucedida onde o problema ocorre.

Ajuste dados deliberadamente e mantenha a regra

Um ajuste documentado pode ser útil. self.name = name.strip() remove espaços das extremidades; valide o nome ajustado se nomes em branco forem proibidos. self.items = list(items) cria uma lista externa separada, então adicionar um item à lista do código chamador não o adiciona a esta lista. Alterar uma largura inválida para seu valor absoluto mudaria o significado pretendido pelo código chamador, então isso exige uma regra de projeto explícita.

As verificações de inicialização ocorrem no momento da criação. Uma atribuição comum como r.width = -5 ainda as ignora depois. Métodos que alteram uma largura devem verificá-la novamente. Uma propriedade pode colocar uma verificação na própria atribuição ao atributo, permitindo que a mesma regra seja executada durante a configuração e em atualizações posteriores.

Um método de instância é uma função definida dentro de uma classe que trabalha com o objeto passado como self. O objeto fornece seus dados armazenados; parâmetros extras fornecem as informações adicionais necessárias para a ação.

Leia atributos por meio de self

Adicione estes métodos dentro da classe Rectangle validada, no mesmo nível de indentação de __init__:

    def area(self):
        return self.width * self.height

    def perimeter(self):
        return 2 * (self.width + self.height)

    def is_square(self):
        return self.width == self.height

Com r = Rectangle(3, 4), r.area() retorna 12, r.perimeter() retorna 14 e r.is_square() retorna False. Cada método lê os atributos do mesmo objeto. Um segundo retângulo usa as mesmas definições de método com sua própria largura e altura.

Dentro de um método, self.width nomeia um atributo. width sozinho nomeia uma variável local ou outra variável acessível; o Python não a procura automaticamente no objeto atual. Se essa variável não existir, return width * height provoca NameError. Escrever self. explicita a quem pertencem os dados pretendidos.

Acompanhe a chamada

Para essa classe, r.area() funciona como Rectangle.area(r). O Python encontra a função na classe e fornece r como seu primeiro argumento. Uma referência a método como r.area é um método vinculado: ela guarda a função e esse retângulo. Adicionar () realiza a chamada.

Se um método for definido como def resize(self, factor), chame-o como r.resize(2). r preenche self, e 2 preenche factor. Você não passa r novamente. Se um método de instância for escrito acidentalmente como def area():, uma chamada em r provoca TypeError porque o Python ainda fornece o objeto a uma função que não aceita argumentos.

Um método pode usar outro por meio de self:

    def double_area(self):
        return self.area() * 2

Aqui self.area() calcula usando o mesmo retângulo. Deixar self. de fora pediria uma função separada chamada area, não o método do objeto.

Retorne resultados ao código chamador

Um método de cálculo normalmente deve retornar seu resultado. O retorno dá ao código chamador um valor para armazenar, combinar, testar ou exibir:

r1 = Rectangle(3, 4)
r2 = Rectangle(2, 5)
total = r1.area() + r2.area()
print(total)  # 22

Se area apenas imprimisse sua resposta, cada chamada retornaria None. A adição então falharia com TypeError, embora dois números tivessem aparecido na tela. Imprimir é uma ação; retornar fornece um valor à expressão que contém a chamada.

Use nomes de métodos que mostrem a tarefa. deposit e resize nomeiam ações; is_square e has_room sugerem verificações booleanas. Um método não precisa de parâmetros para dados já armazenados em seu objeto. Ele precisa de parâmetros para novas entradas, como um fator de redimensionamento ou um valor de depósito.

O estado de um objeto é o conjunto atual de valores de seus atributos. Um método de acesso informa esse estado. Um método de alteração o modifica. Um método de alteração útil verifica suas entradas e mantém todos os atributos relacionados, para que o código chamador não precise coordenar várias atualizações.

Valide toda a alteração primeiro

Adicione estes métodos dentro da classe BankAccount, com seu titular, saldo e lista de transações:

    def deposit(self, amount):
        if amount <= 0:
            raise ValueError("deposit must be positive")
        self.balance += amount
        self.transactions.append(("deposit", amount))

    def withdraw(self, amount):
        if amount <= 0:
            raise ValueError("withdrawal must be positive")
        if amount > self.balance:
            raise ValueError("insufficient funds")
        self.balance -= amount
        self.transactions.append(("withdraw", amount))

Um depósito altera o saldo e registra o evento. Um saque verifica tanto o sinal do valor quanto o saldo disponível antes de subtrair. Essas verificações impedem que um saque rejeitado altere o saldo ou seu histórico.

Começando com BankAccount("Maya", 50), depositar 25 resulta em 75, e sacar 30 resulta em 45. Uma tentativa posterior de sacar 100 provoca ValueError; ela deixa o saldo em 45 e não adiciona nenhuma transação. Colocar a subtração antes da verificação de saldo alteraria o estado mesmo em caso de falha.

Distinga uma alteração de um valor retornado

Esses métodos de alteração não têm instrução de retorno, então retornam None. Depois de new_balance = acct.deposit(25), o depósito foi realizado, mas new_balance é None. Leia acct.balance depois para obter o número atualizado.

Uma classe pode oferecer outro tipo de método que retorna um novo objeto. resize sugere alterar um retângulo; resized pode ser escolhido para um método que retorna um novo retângulo e deixa o original intacto. Leia o contrato do método: o nome ajuda, mas sua definição determina o comportamento.

Rastreie referências compartilhadas

a = BankAccount("Maya", 50)
b = a
b.deposit(10)
print(a.balance)  # 60
print(a is b)     # True

A atribuição associa um nome a um objeto; ela não copia esse objeto. Ambos os nomes acessam a conta cujo saldo mudou. Passar a a uma função também permite acesso a esse objeto. Uma função que chama account.withdraw(5) pode, portanto, alterar a conta vista pelo código chamador.

Para uma conta independente com o mesmo titular e saldo, crie BankAccount(a.owner, a.balance). Esse construtor também fornece um novo histórico vazio. É uma nova conta, não uma cópia completa do histórico.

copy.copy(a) cria um novo objeto externo, mas mantém referências aos mesmos objetos internos, incluindo a lista de transações. copy.deepcopy(a) também copia objetos aninhados. Quando a independência importa, verifique os objetos dentro dos atributos, além da instância externa.

Atribuir diretamente acct.balance = -500 ignora as verificações dos dois métodos. Convenções para atributos internos e propriedades ajudam a deixar claro o caminho previsto para atualizações e a manter a validação próxima das mudanças de estado.

O código chamador precisa de uma forma clara de ler e alterar um objeto. O encapsulamento mantém as regras dos dados junto aos métodos que os gerenciam. O Python usa convenções e propriedades para expressar essa interface.

Marque o armazenamento interno

Um sublinhado inicial em _balance indica um atributo interno. O código chamador deve usar os métodos da conta, mas o Python ainda permite acesso direto. Não há uma palavra reservada private que bloqueie o acesso ao valor.

Um nome como __balance, com dois sublinhados iniciais e sem dois sublinhados finais, aciona a transformação de nome. Dentro de class Acc, self.__balance é armazenado como _Acc__balance. Fora da classe, obj.__balance falha, mas obj._Acc__balance ainda pode funcionar. A transformação evita conflitos de nomes; ela não protege dados sensíveis.

Execute um método pela sintaxe de atributo

Uma propriedade faz um método ser executado quando um atributo é lido. A linha @property é um decorador: ela altera como o Python disponibiliza o método. Uma propriedade sem método de definição permite a leitura, mas rejeita a atribuição.

class Account:
    def __init__(self, owner, balance=0):
        self.owner = owner
        self._balance = balance

    @property
    def balance(self):
        return self._balance

Depois de acct = Account("Maya", 50), leia acct.balance sem parênteses. Atribuir acct.balance = 10 provoca AttributeError porque essa propriedade não tem método de definição. Um método de depósito dentro da classe poderia atualizar _balance após suas verificações.

Verifique atribuições com um método de definição

class Student:
    def __init__(self, name, score):
        self.name = name
        self.score = score

    @property
    def score(self):
        return self._score

    @score.setter
    def score(self, value):
        if not 0 <= value <= 100:
            raise ValueError("score must be between 0 and 100")
        self._score = value

O método de leitura e o método de definição compartilham o nome score; o valor armazenado usa _score. Na criação, self.score = score executa o método de definição.

Para s = Student("Ana", 88), atribuir s.score = 92 armazena 92. Atribuir s.score = -1 provoca ValueError antes do armazenamento, então a nota continua sendo 92. Student("Ana", 105) falha durante a inicialização.

Dentro do método de definição, self.score = value chamaria esse método novamente, repetindo até ocorrer RecursionError. O método de leitura tem o mesmo risco se retornar self.score. Use o nome de armazenamento separado _score em ambos os corpos.

Calcule valores quando forem lidos

Uma propriedade pode calcular um valor a partir de outros atributos:

    @property
    def area(self):
        return self.width * self.height

Colocada dentro de uma classe de retângulo, ela permite r.area. Para largura 3 e altura 4, o valor é 12. Alterar a largura para 5 faz a próxima leitura retornar 20. Armazenar uma área uma vez durante a inicialização deixaria um valor antigo após uma alteração da largura.

Comece com um atributo comum quando o armazenamento simples atender à necessidade.

Um objeto é mais fácil de inspecionar quando pode descrever seus próprios dados. Métodos especiais permitem que o Python solicite essa descrição por meio de ações familiares como print, str e repr. Seus nomes começam e terminam com dois sublinhados e são frequentemente chamados de nomes dunder.

Escolha textos para dois públicos

__str__ fornece texto legível para os usuários de um programa. __repr__ fornece uma descrição precisa para programadores. Ambos retornam strings; nenhum deles deve imprimir seu resultado em lugar de retorná-lo.

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

    def __str__(self):
        return f"({self.x}, {self.y})"

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

p = Point(3, 4)
print(p)        # (3, 4)
print(repr(p))  # Point(3, 4)

str(p) retorna a string "(3, 4)". repr(p) retorna "Point(3, 4)". Quando possível, uma representação se parece com uma chamada de classe que recriaria o valor. Ela continua sendo texto: chamar repr não cria, por si só, outro ponto.

Sem uma representação personalizada, uma instância comum geralmente exibe um nome de classe e um identificador semelhante a um endereço. Isso ajuda a distinguir objetos, mas não mostra seus dados úteis. Você raramente chama esses métodos especiais diretamente; defina-os uma vez e use as operações comuns de exibição do Python.

Preveja o que um contêiner exibe

Com a classe acima, print([Point(3, 4), Point(0, 0)]) mostra [Point(3, 4), Point(0, 0)]. A lista usa as representações de seus elementos, embora cada elemento também tenha __str__.

Se você definir apenas __repr__, o __str__ padrão também o usará. Definir apenas __str__ não altera repr nem a exibição de contêineres. Portanto, ao adicionar apenas um método de exibição, __repr__ atende a mais contextos de inspeção.

Torne os campos de string inequívocos

Para um livro que já armazena title, author e year, estes métodos oferecem diferentes formas úteis de exibição:

    def __str__(self):
        return f"{self.title} by {self.author} ({self.year})"

    def __repr__(self):
        return f"Book({self.title!r}, {self.author!r}, {self.year})"

Para o livro com título "Dune", autor "Frank Herbert" e ano 1965, o primeiro método fornece "Dune by Frank Herbert (1965)". O segundo fornece "Book('Dune', 'Frank Herbert', 1965)". !r solicita as representações dos campos de string, incluindo aspas.

Um corpo que contém apenas print(self.x) retorna None, então str(p) falha com TypeError. Retornar um número inteiro também falha. Construa o texto necessário e depois retorne essa string.

Métodos especiais conectam uma classe a operadores e funções embutidas. Defina apenas operações com significado claro para esse tipo: somar vetores é compreensível; adicionar um jogador a um time fica mais claro como team.add_player(player).

Compare valores e mantenha os hashes seguros

Duas instâncias comuns e separadas são consideradas diferentes por padrão. Acrescente igualdade de valores a uma classe de ponto com:

    def __eq__(self, other):
        if not isinstance(other, Point):
            return NotImplemented
        return self.x == other.x and self.y == other.y

Agora dois pontos em (3, 4) são considerados iguais, embora suas identidades sejam diferentes. in, count, index e remove em listas podem encontrar esses valores iguais. O resultado usual de != decorre de __eq__.

NotImplemented é um valor de retorno que permite ao Python tentar o outro operando ou uma alternativa. Não é uma exceção a ser lançada. Quando nenhum dos operandos permite comparar valores, == recorre à identidade; um ponto e a string "3,4" são considerados diferentes.

Definir __eq__ sem __hash__ torna as instâncias não hasháveis. Assim, elas não podem ser elementos de conjuntos nem chaves de dicionários. Objetos iguais devem ter hashes iguais, e o hash de uma chave deve permanecer estável. Se os atributos comparados nunca mudarem, um hash correspondente pode retornar hash((self.x, self.y)). Mantenha objetos de valor mutáveis como não hasháveis quando seus campos de igualdade puderem mudar.

Defina uma ordenação

__lt__ fornece <. Uma classe de aluno pode comparar notas com return self.score < other.score. As notas 88, 72 e 95 são então ordenadas como 72, 88, 95. min escolhe a menor; max escolhe a maior usando > e sua comparação refletida <.

Com apenas __lt__, a > b pode usar b < a. O Python não infere <= ou >= dessa definição; eles precisam de seus próprios métodos. Se uma ordem for útil apenas para uma tarefa, passe uma função de chave:

def by_score(student):
    return student.score

ordered = sorted(students, key=by_score)

Retorne novos resultados de operações aritméticas

Dentro de uma classe de vetor com atributos x e y:

    def __add__(self, other):
        if not isinstance(other, Vector):
            return NotImplemented
        return Vector(self.x + other.x, self.y + other.y)

    def __mul__(self, factor):
        if not isinstance(factor, (int, float)):
            return NotImplemented
        return Vector(self.x * factor, self.y * factor)

    def __rmul__(self, factor):
        return self * factor

Vector(1, 2) + Vector(3, 4) produz um novo vetor (4, 6). Multiplicar o primeiro vetor por 3 produz (3, 6), deixando-o inalterado. __mul__ trata o vetor à esquerda; __rmul__ aceita um número à esquerda. O Python não presume que as duas ordens tenham o mesmo significado.

Forneça um comprimento significativo

Para uma lista de reprodução que armazena self.songs, defina __len__ para retornar len(self.songs). O resultado deve ser um número inteiro não negativo. len(playlist) então conta as músicas. Nessa classe, comprimento zero também faz if playlist: ser falso; um __bool__ personalizado teria prioridade sobre o comprimento ao testar o valor lógico.

Os atributos de um objeto podem se referir a outros objetos. Um carrinho contém itens, uma biblioteca contém livros e um curso tem alunos. A composição constrói um objeto maior a partir de objetos menores por meio dessa relação de posse.

Dê a cada objeto sua própria responsabilidade

class Item:
    def __init__(self, name, price, quantity):
        self.name = name
        self.price = price
        self.quantity = quantity

    def subtotal(self):
        return self.price * self.quantity

class ShoppingCart:
    def __init__(self):
        self.items = []

    def add(self, item):
        if not isinstance(item, Item):
            raise TypeError("a cart holds Item objects")
        self.items.append(item)

    def total(self):
        total = 0
        for item in self.items:
            total += item.subtotal()
        return total

O carrinho tem uma lista separada criada durante a inicialização. Seu método add verifica o objeto recebido antes de adicioná-lo. cart.add("pen") provoca TypeError em vez de armazenar texto que falhará quando um subtotal for solicitado.

Crie os itens antes ou durante as chamadas:

cart = ShoppingCart()
cart.add(Item("notebook", 2.50, 4))
cart.add(Item("pen", 1.25, 3))
print(cart.total())         # 13.75
print(cart.items[0].name)   # notebook

Os subtotais são 10.0 e 3.75; o carrinho os soma para obter 13.75. A cadeia cart.items[0].name acessa primeiro a lista do carrinho, depois seu primeiro objeto e, por fim, o nome desse objeto.

Delegue o trabalho ao objeto que sabe realizá-lo

O carrinho pede subtotal() a cada item. Isso é delegação: um objeto chama o método de outro objeto para realizar parte de uma tarefa. Se um desconto por quantidade mudar a forma de calcular um subtotal, essa regra pertence a Item.subtotal. O carrinho pode continuar somando os subtotais retornados sem duplicar as regras de preço.

Passar Item em vez de Item(...) passa a classe, não um item comprado. A verificação de tipo rejeita esse objeto de classe. Faça todas as adições pelo caminho verificado; o acesso direto a cart.items.append(...) ignoraria add.

Busque um objeto

Adicione este método dentro de ShoppingCart:

    def find(self, name):
        for item in self.items:
            if item.name == name:
                return item
        return None

A primeira correspondência retorna o item existente. Se não houver correspondência, retorna None. Verifique found is None antes de usar found.name; None não tem esse atributo. Um método __len__ que retorna len(self.items) também poderia fazer len(cart) contar os objetos de item armazenados, enquanto __str__ poderia unir as linhas dos itens em um recibo.

Acompanhe referências dentro de coleções

Uma lista armazena referências, então colocar o mesmo item em dois carrinhos não o copia. Atualizar o preço desse item afeta o próximo total calculado por ambos os carrinhos. Listas separadas para os carrinhos evitam o compartilhamento acidental da lista, mas não tornam independentes os objetos dentro delas. Crie itens separados quando os carrinhos precisarem armazenar dados independentes.

Objetos podem ser argumentos e valores de retorno de métodos, assim como números ou strings. Acompanhe separadamente o receptor, os argumentos e o resultado: um método pode alterar um objeto existente, retornar um novo objeto ou apenas informar um valor.

Use outro objeto como entrada

Dentro de uma classe de ponto com x e y, um método pode ler ambos os pontos:

    def midpoint(self, other):
        return Point((self.x + other.x) / 2,
                     (self.y + other.y) / 2)

Para p = Point(3, 4) e q = Point(1, 0), middle = p.midpoint(q) cria um terceiro ponto em (2.0, 2.0). Durante a chamada, self se refere a p e other se refere a q. O método calcula coordenadas e constrói um novo ponto; ele não atribui nada a nenhum dos originais.

Com import math, um método de distância pode retornar math.hypot(self.x - other.x, self.y - other.y). Point(0, 0).distance_to(Point(3, 4)) então fornece 5.0. Essa chamada retorna um número, enquanto midpoint retorna um objeto.

Deixe cada receptor gerenciar suas alterações

Dentro de uma classe de conta com métodos withdraw e deposit que fazem verificações:

    def transfer_to(self, other, amount):
        self.withdraw(amount)
        other.deposit(amount)

Se Maya tem 100 e Leo tem 20, maya.transfer_to(leo, 30) primeiro saca da conta de Maya, deixando 70, e depois deposita na conta de Leo, resultando em 50. Na primeira chamada, self é a conta de Maya. Na chamada de depósito, seu próprio self é a conta de Leo.

Uma transferência posterior de 500 falha em withdraw porque Maya tem apenas 70. A execução para antes de deposit, então ambos os saldos mantêm seus valores anteriores. A ordem das chamadas importa. O Python não desfaz uma mudança de estado anterior se uma chamada posterior lançar uma exceção; esse método curto depende de a conta receptora poder aceitar o valor do depósito.

Chamar other.deposit(amount) executa as regras da conta receptora em um único lugar. Alterar diretamente other.balance as ignoraria.

Rastreie os objetos, não apenas os nomes das variáveis

Desenhe cada instância como uma caixa que contém seus atributos. Desenhe uma seta de cada variável até sua caixa. Em uma chamada, identifique qual caixa é recebida como self e quais caixas são passadas como argumentos. Atualize a caixa afetada após cada linha bem-sucedida que altera o estado. Duas setas para uma caixa significam que uma alteração por qualquer um dos nomes alcança o mesmo objeto.

Uma função comum também pode trabalhar com vários objetos. total_balance(accounts) pode percorrer contas e somar seus saldos. Esse cálculo sobre a lista inteira não precisa pertencer a uma única conta.

Represente uma relação ausente

Um livro pode começar com self.borrower = None e depois armazenar um objeto de membro. Antes de ler um atributo do membro, verifique a relação:

if book.borrower is not None:
    print(book.borrower.name)

Caso contrário, book.borrower.name falha quando o livro não tem uma pessoa que o tomou emprestado. Classes podem ser definidas acima de uma função main() que cria e conecta os objetos. Chamar main() sob if __name__ == "__main__": impede que essas ações sejam executadas quando as classes são importadas.

Uma classe justifica seu uso quando dados relacionados e operações repetidas ficam mais fáceis de entender juntos. Você não precisa transformar toda função ou registro em uma classe. Escolha a estrutura que deixa claras as responsabilidades do programa.

Procure dados e comportamentos que andam juntos

Classes ajudam quando várias funções recebem repetidamente o mesmo grupo de valores, muitos registros compartilham uma estrutura e mudanças de estado devem seguir regras comuns. Várias contas que aceitam depósitos e saques são um bom caso. Um único cálculo pode continuar sendo uma função. Um registro fixo e somente leitura pode continuar sendo uma tupla ou um dicionário.

Uma classe com apenas configuração e uma operação única muitas vezes acrescenta mais formalidade do que estrutura útil. Pergunte o que uma instância representa e quais ações repetidas pertencem a ela. Se você não conseguir responder a essas perguntas de forma simples, reconsidere o projeto.

Mova uma operação para junto de seus dados

Uma conta baseada em dicionário pode começar assim:

account = {"owner": "Maya", "balance": 50}

def deposit(account, amount):
    account["balance"] += amount

A versão com classe pode colocar a mesma operação ao lado de seu estado e de suas regras:

class BankAccount:
    def __init__(self, owner, balance=0):
        self.owner = owner
        self.balance = balance

    def deposit(self, amount):
        if amount <= 0:
            raise ValueError("deposit must be positive")
        self.balance += amount

    def __repr__(self):
        return f"BankAccount({self.owner!r}, {self.balance})"

Depois de acct = BankAccount("Maya", 50) e acct.deposit(25), sua representação é BankAccount('Maya', 75). A regra de depósito positivo agora é executada sempre que o código chamador usa esse método. Ler account["balence"] provocaria KeyError; ler acct.balence provoca AttributeError. Uma classe não elimina erros de escrita, mas dá aos dados e a suas operações um lugar com nome.

Planeje a partir de uma breve descrição

Para “Uma biblioteca empresta livros a seus membros. Um membro pode pegar emprestados no máximo 3 livros”, os substantivos sugerem Book, Member e Library. Os verbos sugerem métodos de empréstimo e devolução.

1. Liste o que cada instância sabe: título, autor e pessoa que tomou o livro emprestado; nome e livros emprestados de um membro; livros e membros de uma biblioteca.
2. Identifique regras: um livro não pode já estar emprestado, e um membro não pode exceder MAX_LOANS = 3.
3. Coloque cada regra na operação que altera a relação, como Library.check_out(book, member).
4. Escreva a inicialização e uma representação útil, depois adicione e teste uma ação por vez.

Títulos diferentes precisam de instâncias diferentes de Book, não de classes separadas com o nome de cada título. Use substantivos no singular para objetos individuais, como Book; nomeie uma coleção de acordo com a coleção, como Library. Mantenha a função de cada classe clara o bastante para ser descrita em uma frase.

Teste o comportamento observável

acct = BankAccount("Maya", 50)
acct.deposit(25)
assert acct.balance == 75

assert provoca AssertionError se sua condição for falsa. Teste também ações rejeitadas: capture a exceção esperada e verifique se o estado não mudou. Use validação explícita com raise para entradas do código chamador; asserções são verificações durante o desenvolvimento e podem ser desativadas quando o Python é executado com otimização.