4. Construindo extensões C e C++¶
Uma extensão C para CPython é uma biblioteca compartilhada (por exemplo, um arquivo .so no Linux, .pyd no Windows), que exporta uma função de inicialização.
Para ser importável, a biblioteca compartilhada deve estar disponível em PYTHONPATH, e deve ser nomeada após o nome do módulo, com uma extensão apropriada. Ao usar distutils, o nome do arquivo correto é gerado automaticamente.
A função de inicialização tem a assinatura:
Ela retorna um módulo totalmente inicializado ou uma instância de PyModuleDef. Veja Inicializando módulos C para detalhes.
Para módulos com nomes somente ASCII, a função deve ser nomeada PyInit_<nomemódulo>, com <nomemódulo> substituído pelo nome do módulo. Ao usar Inicialização multifásica, nomes de módulos não ASCII são permitidos. Neste caso, o nome da função de inicialização é PyInitU_<nomemódulo>, com <nomemódulo> codificado usando a codificação punycode do Python com hifenes substituídos por sublinhados. Em Python:
def initfunc_name(name):
try:
suffix = b'_' + name.encode('ascii')
except UnicodeEncodeError:
suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
return b'PyInit' + suffix
É possível exportar vários módulos de uma única biblioteca compartilhada, definindo várias funções de inicialização. No entanto, importá-los requer o uso de links simbólicos ou um importador personalizado, porque por padrão apenas a função correspondente ao nome do arquivo é encontrada. Veja a seção “Multiple modules in one library” na PEP 489 para detalhes.
4.1. Construindo extensões C e C ++ com distutils¶
Módulos de extensão podem ser construídos usando distutils, que está incluído no Python. Visto que distutils também suporta a criação de pacotes binários, os usuários não precisam necessariamente de um compilador e distutils para instalar a extensão.
Um pacote distutils contém um script guia setup.py. Este é um arquivo Python simples, que, no caso mais simples, pode ter a seguinte aparência:
from distutils.core import setup, Extension
module1 = Extension('demo',
sources = ['demo.c'])
setup (name = 'PackageName',
version = '1.0',
description = 'This is a demo package',
ext_modules = [module1])
Com este setup.py e um arquivo demo.c, executando
python setup.py build
vai compilar demo.c, e produzir um módulo de extensão chamado demo no diretório build. Dependendo do sistema, o arquivo do módulo vai terminar em um subdiretório build/lib.system, e pode ter um nome como demo.so ou demo.pyd.
No setup.py, toda a execução é realizada chamando a função setup. Isso leva um número variável de argumentos nomeados, dos quais o exemplo acima usa apenas um subconjunto. Especificamente, o exemplo especifica meta-informação para construir pacotes e especifica o conteúdo do pacote. Normalmente, um pacote conterá módulos adicionais, como módulos-fonte Python, documentação, subpacotes etc. Consulte a documentação do distutils em Distribuindo Módulos Python (Versão legada) para aprender mais sobre os recursos do distutils; esta seção explica apenas a construção de módulos de extensão.
É comum pré-computar argumentos para setup(), para melhor estruturar o script guia. No exemplo acima, o argumento ext_modules para setup() é uma lista de módulos de extensão, cada um dos quais é uma instância de Extension. No exemplo, a instância define uma extensão chamada demo que é construída compilando um único arquivo fonte, demo.c.
Em muitos casos, construir uma extensão é mais complexo, uma vez que definições de pré-processador adicionais e bibliotecas podem ser necessárias. Isso é demonstrado no exemplo abaixo.
from distutils.core import setup, Extension
module1 = Extension('demo',
define_macros = [('MAJOR_VERSION', '1'),
('MINOR_VERSION', '0')],
include_dirs = ['/usr/local/include'],
libraries = ['tcl83'],
library_dirs = ['/usr/local/lib'],
sources = ['demo.c'])
setup (name = 'PackageName',
version = '1.0',
description = 'This is a demo package',
author = 'Martin v. Loewis',
author_email = 'martin@v.loewis.de',
url = 'https://docs.python.org/extending/building',
long_description = '''
This is really just a demo package.
''',
ext_modules = [module1])
Neste exemplo, setup() é chamado com meta-informação adicional, o que é recomendado quando os pacotes de distribuição precisam ser construídos. Para a extensão em si, especifica definições de pré-processador, diretórios de inclusão, diretórios de biblioteca e bibliotecas. Dependendo do compilador, distutils passa essas informações de maneiras diferentes para o compilador. Por exemplo, no Unix, isso pode resultar nos comandos de compilação
gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o
gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
Essas linhas são apenas para fins de demonstração; Os usuários de distutils devem confiar que distutils acertará as invocações.
4.2. Distribuindo seus módulos de extensão¶
Quando uma extensão é construída com sucesso, há três maneiras de usá-la.
Os usuários finais normalmente desejam instalar o módulo, eles fazem isso executando
python setup.py install
Os mantenedores do módulo devem produzir pacotes fonte; para fazer isso, eles executam:
python setup.py sdist
Em alguns casos, arquivos adicionais precisam ser incluídos em uma distribuição fonte; isso é feito através de um arquivo MANIFEST.in; veja Specifying the files to distribute para detalhes.
Se a distribuição fonte foi construída com sucesso, os mantenedores também podem criar distribuições binárias. Dependendo da plataforma, um dos seguintes comandos pode ser usado para fazer isso.
python setup.py bdist_wininst
python setup.py bdist_rpm
python setup.py bdist_dumb