functools.Placeholder é uma novidade do Python 3.14 criada para tornar functools.partial() e functools.partialmethod() muito mais flexíveis. Antes desse recurso, uma função parcial conseguia fixar argumentos apenas a partir da esquerda. Isso funcionava bem quando os primeiros parâmetros eram conhecidos antecipadamente, mas obrigava o desenvolvedor a criar lambdas ou funções auxiliares quando precisava deixar aberto um argumento intermediário.
Com Placeholder, qualquer posição de argumento posicional pode ser reservada para preenchimento futuro. O recurso melhora a composição de funções, reduz wrappers triviais e deixa explícito quais valores estão fixos e quais ainda serão recebidos.
O problema resolvido
Considere uma função de formatação com três argumentos posicionais:
def formatar(prefixo, mensagem, sufixo):
return f"{prefixo}{mensagem}{sufixo}"
Com o partial() tradicional, era fácil fixar apenas o primeiro argumento. Porém, para fixar prefixo e sufixo e manter a mensagem em aberto, era comum recorrer a uma lambda. O código funcionava, mas perdia parte da clareza declarativa de uma função parcial e adicionava um wrapper que existia apenas para reposicionar argumentos.
Uso básico
No Python 3.14, importe Placeholder e, se desejar, crie um alias curto:
from functools import partial, Placeholder as _
aviso = partial(formatar, "[AVISO] ", _, "!")
print(aviso("Disco quase cheio"))
O argumento fornecido na chamada ocupa a posição marcada pelo Placeholder. O objeto retornado continua sendo uma função parcial real e preserva o comportamento esperado do módulo functools.
Vários placeholders
Uma chamada parcial pode conter vários espaços reservados. Eles são preenchidos da esquerda para a direita pelos argumentos posicionais recebidos:
def registrar(nivel, usuario, acao, recurso):
return f"{nivel}: {usuario} {acao} {recurso}"
auditoria = partial(registrar, "AUDIT", _, _, "arquivo")
print(auditoria("ana", "alterou"))
O primeiro valor substitui o primeiro Placeholder e o segundo valor substitui o segundo. Se a chamada fornecer menos valores do que o número de espaços reservados, o Python gera TypeError. Se houver valores adicionais, eles são encaminhados depois dos argumentos já montados, desde que a função original os aceite.
Composição de funções parciais
Uma partial que contém Placeholder pode servir de base para outra partial. Isso permite preencher parte dos espaços em uma etapa e manter outros para uma etapa seguinte:
base = partial(formatar, _, _, "!")
aviso = partial(base, "[AVISO] ")
print(aviso("Atenção"))
Essa composição é útil para criar famílias de chamadas especializadas. Ainda assim, evite camadas demais. Quando a sequência de partials fica difícil de acompanhar, uma função normal com nome e documentação costuma ser melhor.
Placeholder e argumentos nomeados
Placeholder atua somente em argumentos posicionais. Ele não deve ser usado como valor de um argumento nomeado para indicar preenchimento futuro. Para parâmetros nomeados, deixe o valor ausente na criação da partial ou forneça outro valor posteriormente, quando a assinatura permitir.
Essa regra mantém a semântica previsível. O Placeholder representa uma posição, não um nome de parâmetro. Em APIs com muitos argumentos nomeados, uma função auxiliar explícita pode oferecer uma interface mais clara.
Uso com partialmethod
O mesmo mecanismo funciona com partialmethod(), especialmente útil em classes:
from functools import partialmethod, Placeholder as _
class ClienteAPI:
def requisicao(self, metodo, caminho, dados=None):
return metodo, caminho, dados
obter = partialmethod(requisicao, "GET", _)
criar = partialmethod(requisicao, "POST", _, _)
O método obter() recebe apenas o caminho, enquanto criar() recebe caminho e dados. O descritor mantém corretamente a ligação de self, tornando o resultado mais natural do que wrappers improvisados.
Casos práticos
O recurso é útil em validações, callbacks, adaptadores de API, pipelines e comandos parametrizados. Uma função de faixa pode ser transformada em um validador especializado:
def dentro(valor, minimo, maximo):
return minimo <= valor <= maximo
percentual_valido = partial(dentro, _, 0, 100)
Também é possível adaptar uma função de persistência mantendo o objeto em aberto:
def salvar(destino, objeto, *, indentacao=2):
pass
salvar_config = partial(salvar, "config.json", _)
Em ambos os exemplos, a intenção fica visível: alguns argumentos são fixos e outros serão fornecidos depois.
Quando preferir def
Placeholder não substitui funções normais. Use def quando houver validação, tratamento de exceções, transformação condicional, documentação própria ou uma assinatura pública importante. A partial é melhor para adaptação curta e declarativa. Uma função nomeada é melhor quando existe comportamento real além de preencher argumentos.
Compatibilidade
O recurso exige Python 3.14 ou superior. Bibliotecas que também atendem versões antigas devem proteger a importação e manter uma implementação alternativa:
try:
from functools import Placeholder
except ImportError:
Placeholder = None
Um objeto sentinela comum não reproduz automaticamente o comportamento, pois a interpretação especial ocorre dentro de partial(). Em versões anteriores, use lambda ou uma função auxiliar.
Testes e erros comuns
Teste a função parcial como qualquer unidade de código. Cubra os valores válidos, limites, argumentos ausentes e casos inválidos. Os erros mais frequentes são fornecer menos argumentos que o necessário, tentar usar Placeholder em keyword arguments, criar composições profundas e empregar o recurso onde uma função simples seria mais legível.
Também é importante observar a assinatura original. A partial reduz repetição, mas não adiciona validação de tipos ou regras de domínio. Use type checking e testes quando o wrapper atravessar limites importantes do sistema.
Boas práticas
Dê nomes descritivos às funções parciais, mantenha-as perto do contexto de uso, documente o requisito do Python 3.14 e evite aliases obscuros em módulos grandes. Use o alias _ somente quando o significado estiver claro. Prefira uma camada pequena de adaptação e preserve a legibilidade para quem revisará o código depois.
Para continuar estudando recursos modernos, veja t-strings no Python, contextvars.Token no Python, shared_memory track no Python e compression.zstd no Python.
A referência principal é a documentação oficial de functools. Consulte também as novidades do Python 3.14 para entender o contexto da adição.
Conclusão
functools.Placeholder elimina uma limitação histórica de partial(). Agora você pode reservar posições intermediárias, criar adaptadores mais claros e reduzir lambdas triviais. O recurso é pequeno, mas melhora bastante a expressividade de código funcional e orientado a objetos. Use-o em adaptações simples, mantenha funções explícitas para lógica complexa e trate a compatibilidade com versões anteriores de maneira consciente.
