pybind11

pybind11 — Operabilidade perfeita entre C++11 e Python

Exemplo de Setuptools • Exemplo de Scikit-build • Exemplo de CMake

pybind11 é uma biblioteca leve somente de cabeçalho que expõe tipos C++ em Python e vice-versa, principalmente para criar ligações Python de código C++ existente. Seus objetivos e sintaxe são semelhantes aos da excelente biblioteca Boost.Python de David Abrahams: minimizar o código padrão em módulos de extensão tradicionais, inferindo informações de tipo usando introspecção em tempo de compilação.

O principal problema do Boost.Python – e o motivo para criar um projeto tão semelhante – é o Boost. Boost é um conjunto enorme e complexo de bibliotecas utilitárias que funciona com quase todos os compiladores C++ existentes. Essa compatibilidade tem seu custo: truques misteriosos e soluções alternativas são necessários para suportar os espécimes de compilador mais antigos e com mais bugs. Agora que os compiladores compatíveis com C++ 11 estão amplamente disponíveis, esse maquinário pesado tornou-se uma dependência excessivamente grande e desnecessária.

Pense nesta biblioteca como uma pequena versão independente do Boost.Python com tudo removido que não é relevante para a geração de ligação. Sem comentários, os arquivos de cabeçalho principais requerem apenas cerca de 4K linhas de código e dependem do Python (3.8+ ou PyPy) e da biblioteca padrão C++. Esta implementação compacta foi possível graças a alguns recursos da linguagem C++ 11 (especificamente: tuplas, funções lambda e modelos variados). Desde a sua criação, esta biblioteca cresceu além do Boost.Python de várias maneiras, levando a um código de ligação dramaticamente mais simples em muitas situações comuns.

O tutorial e a documentação de referência são fornecidos em pybind11.readthedocs.io. Uma versão em PDF do manual está disponível aqui. E o código-fonte está sempre disponível em github.com/pybind/pybind11.

Recursos principais

pybind11 pode mapear os seguintes recursos principais do C++ para Python:

• Funções que aceitam e retornam estruturas de dados personalizadas por valor, referência ou ponteiro
• Métodos de instância e métodos estáticos
• Funções sobrecarregadas
• Atributos de instância e atributos estáticos
• Tipos de exceção arbitrárias
• Enumerações
• Retornos de chamada
• Iteradores e intervalos
• Operadores personalizados
• Herança única e múltipla
• Estruturas de dados STL
• Ponteiros inteligentes com contagem de referência como std::shared_ptr
• Referências internas com contagem correta de referências
• Classes C++ com métodos virtuais (e virtuais puros) podem ser estendidas em Python
• Suporte NumPy integrado (NumPy 2 requer pybind11 2.12+)

Guloseimas

Além da funcionalidade principal, o pybind11 oferece algumas vantagens extras:

• Python 3.8+ e PyPy3 7.3 são suportados com uma interface independente de implementação (pybind11 2.9 foi a última versão a suportar Python 2 e 3.5).
• É possível vincular funções lambda do C++ 11 com variáveis ​​capturadas. Os dados de captura lambda são armazenados dentro do objeto de função Python resultante.
• pybind11 usa construtores de movimentação C++11 e operadores de atribuição de movimentação sempre que possível para transferir com eficiência tipos de dados personalizados.
• É fácil expor o armazenamento interno de tipos de dados personalizados por meio dos protocolos de buffer do Pythons. Isso é útil, por exemplo, para conversão rápida entre classes de matrizes C++ como Eigen e NumPy sem operações de cópia caras.
• pybind11 pode vetorizar funções automaticamente para que sejam aplicadas de forma transparente a todas as entradas de um ou mais argumentos da matriz NumPy.
• As operações de acesso e atribuição baseadas em fatias do Python podem ser suportadas com apenas algumas linhas de código.
• Tudo está contido em apenas alguns arquivos de cabeçalho; não há necessidade de vincular nenhuma biblioteca adicional.
• Os binários são geralmente menores por um fator de pelo menos 2 em comparação com ligações equivalentes geradas pelo Boost.Python. Uma recente conversão pybind11 do PyRosetta, um enorme projeto de vinculação Boost.Python, relatou uma redução no tamanho binário de 5,4x e uma redução no tempo de compilação em 5,8x .
• As assinaturas de funções são pré-computadas em tempo de compilação (usando constexpr ), levando a binários menores.
• Com pouco esforço extra, os tipos C++ podem ser selecionados e removidos de maneira semelhante aos objetos regulares do Python.

Compiladores suportados

1. Clang/LLVM 3.3 ou mais recente (para clang do Apple Xcode, é 5.0.0 ou mais recente)
2. GCC 4.8 ou mais recente
3. Microsoft Visual Studio 2017 ou mais recente
4. Compilador Intel Classic C++ 18 ou mais recente (ICC 20.2 testado em CI)
5. Cygwin/GCC (testado anteriormente em 2.5.1)
6. NVCC (CUDA 11.0 testado em CI)
7. NVIDIA PGI (20.9 testado em CI)

Sobre

Este projeto foi criado por Wenzel Jakob. Recursos e/ou melhorias significativas no código foram contribuídos por Jonas Adler, Lori A. Burns, Sylvain Corlay, Eric Cousineau, Aaron Gokaslan, Ralf Grosse-Kunstleve, Trent Houliston, Axel Huebl, @hulucc, Yannick Jadoul, Sergey Lyskov, Johan Mabille, Tomasz Miąsko, Dean Moldovan, Ben Pritchard, Jason Rhinelander, Boris Schäling, Pim Schelart, Henry Schreiner, Ivan Smirnov, Boris Staletic e Patrick Stewart.

Agradecemos ao Google pela generosa contribuição financeira para a infraestrutura de integração contínua utilizada neste projeto.

Contribuindo

Consulte o guia de contribuição para obter informações sobre como construir e contribuir para o pybind11.

Licença

pybind11 é fornecido sob uma licença estilo BSD que pode ser encontrada no arquivo LICENSE. Ao usar, distribuir ou contribuir para este projeto, você concorda com os termos e condições desta licença.