pybind11: Criando Bindings Python para Código C++

pybind11 é uma biblioteca leve e exclusivamente de cabeçalhos para a linguagem C++, que permite criar bindings de alto desempenho entre código C++ e Python. Ela é uma alternativa moderna e mais conveniente à biblioteca Boost.Python. A ideia principal é escrever uma pequena camada de código "cola" em C++, usando macros e templates do pybind11, que é compilada em uma biblioteca dinâmica (arquivo .so ou .pyd). Esse arquivo pode então ser importado no Python como um módulo comum.

Por que isso é necessário? Em projetos reais, surge frequentemente a necessidade de combinar a alta performance e o controle de baixo nível do C++ com a flexibilidade e o rico ecossistema do Python. Você pode escrever código crítico para velocidade (algoritmos numéricos, processamento de imagens, controle de hardware) em C++ e depois usá-lo a partir do Python, mantendo a facilidade de prototipação e análise de dados. O pybind11 torna esse processo extremamente simples e intuitivo, lidando automaticamente com a conversão de tipos, gerenciamento de memória e chamadas de exceções.

Principais vantagens do pybind11: sobrecarga mínima (overhead) na chamada de funções, suporte completo ao C++ moderno (C++11 e superior), conversão automática de contêineres padrão (std::vector, std::map) para listas e dicionários Python, além de um sistema simples e expressivo para registro de classes, métodos e propriedades. A biblioteca é ativamente desenvolvida e usada em projetos de grande porte como PyTorch, TensorFlow e Open3D.

Instalação

pybind11 é uma biblioteca de cabeçalhos, portanto sua instalação se resume a copiar os arquivos de cabeçalho para o seu projeto. A maneira mais simples e recomendada é usar o gerenciador de pacotes pip, que instalará a biblioteca no sistema e fornecerá o utilitário pybind11-config para obter os caminhos de compilação:

pip install pybind11

Após a instalação, você pode verificar se tudo está funcionando executando o comando:

pybind11-config --includes

Ele exibirá as flags do compilador necessárias para incluir os cabeçalhos do pybind11. Para compilar o módulo, você também precisará de um compilador C++ (g++, clang, MSVC) e dos cabeçalhos do Python (geralmente instalados junto com o Python). Exemplo de compilação usando CMake ou diretamente com g++:

c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) exemplo.cpp -o exemplo$(python3-config --extension-suffix)

Início Rápido: Exemplo Mínimo Funcional

Crie um arquivo exemplo.cpp com o seguinte conteúdo:

#include <pybind11/pybind11.h>

namespace py = pybind11;

int somar(int a, int b) {
    return a + b;
}

PYBIND11_MODULE(exemplo, m) {
    m.doc() = "Plugin de exemplo pybind11";
    m.def("somar", &somar, "Uma função que soma dois números");
}

Compile-o (substitua python3 pelo seu interpretador):

c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) exemplo.cpp -o exemplo$(python3-config --extension-suffix)

Agora você pode usar o módulo a partir do Python:

import exemplo
resultado = exemplo.somar(3, 4)
print(resultado)  # Exibe: 7
print(exemplo.__doc__)  # Exibe: Plugin de exemplo pybind11

Principais Métodos e Classes do pybind11

Abaixo estão as principais funções e classes da biblioteca usadas para criar bindings.

1. PYBIND11_MODULE(nome, variavel)

Assinatura: PYBIND11_MODULE(nome, variavel) (macro)

O que faz: Define o ponto de entrada para o módulo Python. Cria uma função de inicialização que é chamada automaticamente quando o módulo é importado. O primeiro argumento é o nome do módulo (sem aspas), e o segundo é uma variável do tipo py::module_ que você usará para registrar funções, classes e constantes.