Métodos de Classe vs. Instância vs. Estáticos

Python oferece três tipos de métodos. Métodos de instância operam em objetos, métodos de classe na classe (frequentemente fábricas) e métodos estáticos como funções com namespace sem self ou cls implícitos.

Receita

class User:
    def __init__(self, email: str) -> None:
        self.email = email
 
    def domain(self) -> str:
        return self.email.split("@", 1)[1]
 
    @classmethod
    def from_row(cls, row: dict[str, str]) -> "User":
        return cls(row["email"])
 
    @staticmethod
    def is_valid_email(email: str) -> bool:
        return "@" in email and "." in email.split("@", 1)[-1]

Quando usar isso:

• Construtores alternativos (from_json, from_env)
• Utilitários logicamente agrupados com a classe, mas que não precisam de estado
• Métodos de fábrica herdados que respeitam o cls da subclasse
• Métodos de classe de enumeração/personalizados que modificam o estado da classe

Exemplo de Trabalho

from datetime import datetime, timezone
 
class Event:
    def __init__(self, name: str, ts: datetime) -> None:
        self.name = name
        self.ts = ts
 
    def age_seconds(self, now: datetime | None = None) -> float:
        now = now or datetime.now(timezone.utc)
        return (now - self.ts).total_seconds()
 
    @classmethod
    def now(cls, name: str) -> "Event":
        return cls(name, datetime.now(timezone.utc))
 
    @classmethod
    def from_iso(cls, name: str, iso: str) -> "Event":
        ts = datetime.fromisoformat(iso.replace("Z", "+00:00"))
        return cls(name, ts)
 
    @staticmethod
    def normalize_name(name: str) -> str:
        return name.strip().lower()
 
class AdminEvent(Event):
    pass
 
if __name__ == "__main__":
    base = Event.now("deploy")
    admin = AdminEvent.now("promote")
    print(type(base), type(admin))
    print(Event.is_valid_email("a@b.com"))

O que isso demonstra:

• O método de classe now é um construtor alternativo
• AdminEvent.now retorna AdminEvent porque cls é uma subclasse
• O método de instância age_seconds usa o estado do objeto
• O método estático normalize_name não precisa de self nem de cls

Mergulho Profundo

Como Funciona

• Métodos vinculados - Métodos de instância vinculam self no momento da chamada.
• Descritor de método de classe - Passa a classe como primeiro argumento automaticamente.
• Descritor de método estático - Nenhum argumento automático.
• Herança - cls em um método de classe é a classe real chamada (AdminEvent em vez de Event).
• Acesso - Métodos de classe podem acessar atributos de classe; métodos de instância, atributos de instância.

Quando Usar Cada Um

Notas do Python

# Padrão de método de classe estilo enum
class Money:
    def __init__(self, amount: int, currency: str) -> None:
        self.amount = amount
        self.currency = currency
 
    @classmethod
    def usd(cls, amount: int) -> "Money":
        return cls(amount, "USD")

Armadilhas

• staticmethod quando classmethod é necessário - Fábrica que retorna cls falha em subclasses com staticmethod. Correção: Use classmethod para construtores polimórficos.
• classmethod acessando estado da instância - self não está disponível. Correção: Passe a instância explicitamente ou use um método de instância.
• Confusão com função em nível de módulo - staticmethod que nunca toca na classe - poderia ser uma função de módulo. Correção: Use staticmethod apenas ao agrupar a API no namespace da classe.
• Ordem de classmethod abstrato - Empilhe @classmethod e @abstractmethod de acordo com a documentação da versão do Python.
• Chamando classmethod em uma instância - Permitido, mas incomum - ainda passa a classe real.

Alternativas

FAQs

Relacionado

• Propriedades e Descritores - descritores de método
• dataclasses - padrões de construção
• Herança e MRO - cls no contexto MRO
• Enums - métodos de classe de enumeração

Versões do Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.