Generate a third-party package for PyODPS - MaxCompute: Central de Documentação do Alibaba Cloud

Pré-requisitos

Antes de começar, verifique se você possui:

PyODPS V0.11.3 ou versão posterior instalada
Docker instalado e em execução (necessário para o modo Docker, que é o padrão)
Python 3 (recomendado; o empacotamento com Python 2 pode falhar em projetos novos)

Visão geral dos cenários de empacotamento

Consulte esta tabela para identificar o comando adequado ao seu cenário e siga as instruções detalhadas nas seções abaixo.

Cenário	Comando
Empacotar um pacote do PyPI (modo Docker)	`pyodps-pack pandas`
Empacotar um pacote do PyPI (modo sem Docker)	`pyodps-pack --without-docker pandas`
Empacotar uma versão específica	`pyodps-pack pandas==1.2.5`
Empacotar para Python 2.7 no MaxCompute	`pyodps-pack --mcpy27 pandas`
Empacotar para Python 2.7 no DataWorks	`pyodps-pack --dwpy27 pandas`
Empacotar código local personalizado	`pyodps-pack /<path_to_package>/test_package_root`
Empacotar a partir de um repositório git	`pyodps-pack git+https://github.com/aliyun/aliyun-odps-python-sdk.git`
Empacotar com dependências binárias	`pyodps-pack --run-before install-gdal.sh gdal==3.6.0`

Como funciona

O pyodps-pack é instalado automaticamente junto com o PyODPS. Em sistemas Linux e macOS, o executável fica no diretório bin, dentro do caminho de instalação do Python. No Windows, ele está localizado no diretório Scripts. Execute os comandos do pyodps-pack na CLI do Windows, no Terminal do macOS ou no Shell do Linux. Não os execute no console do DataWorks, no cliente do MaxCompute (odpscmd) nem na CLI do Python.

Se o diretório bin ou Scripts já estiver na variável de ambiente PATH (definida durante a instalação do Python ou ativação do ambiente virtual), nenhuma configuração adicional será necessária. Caso contrário, navegue manualmente até o diretório ou adicione-o à variável PATH.

Após a conclusão do empacotamento, o pyodps-pack exibe todas as versões das dependências resolvidas e grava o arquivo packages.tar.gz no diretório atual.

Escolher um modo de empacotamento

O pyodps-pack oferece suporte a dois modos:

Modo	Quando usar	Como ativar
Modo Docker (padrão)	Sempre que o Docker estiver disponível. Gera os pacotes com maior compatibilidade.	Instale o Docker; nenhum sinalizador extra é necessário
Modo sem Docker	Apenas quando o Docker não estiver disponível no seu ambiente	Adicione `--without-docker`

Aviso

Pacotes criados no modo sem Docker podem não funcionar no MaxCompute ou no DataWorks. Utilize o modo Docker sempre que possível.

Configurar o Docker

O pyodps-pack invoca o Docker automaticamente e baixa as imagens necessárias, eliminando a necessidade de gerenciar imagens manualmente.

Linux: Consulte Install Docker Engine.

macOS ou Windows:

Desenvolvedores individuais: use o Docker Desktop.
Usuários corporativos impossibilitados de usar o Docker Desktop: use o Rancher Desktop (código aberto).

Nota

O pyodps-pack não foi testado em outros ambientes Docker, como o minikube. A disponibilidade nesses ambientes não é garantida.

Observações específicas para Windows:

O serviço do Docker pode exigir o Windows Server para iniciar, mas muitas organizações desativam o Windows Server por motivos de segurança. Se o Docker não conseguir iniciar, mude para Linux ou tente ativar o Windows Server.
No Windows 10 com Rancher Desktop, o containerd pode não funcionar como mecanismo de contêiner. Use o dockerd em seu lugar. Consulte Container Engine para obter as etapas de configuração.

Configurar o modo sem Docker

Nota

Utilize o modo sem Docker apenas quando o Docker não estiver disponível. Se ocorrerem erros ou se o pacote gerado não funcionar, mude para o modo Docker.

Adicione --without-docker a qualquer comando do pyodps-pack. Antes de usar este modo:

Certifique-se de que o pip esteja instalado no seu ambiente Python.
No Windows, instale o Git Bash (incluído no Git for Windows).

Empacotar dependências do PyPI

Nota

Alguns pacotes possuem dependências opcionais que o pyodps-pack não inclui automaticamente. Por exemplo, o pandas exige o openpyxl ao utilizar o método to_excel. Verifique a documentação do pacote de terceiros e adicione explicitamente quaisquer dependências opcionais ao comando.

Observações de uso:

Utilize Python 3 para novos projetos do MaxCompute. O empacotamento com Python 2 pode falhar.
Migre projetos existentes em Python 2 para Python 3 a fim de simplificar a manutenção.
No Linux, prefixe os comandos do pyodps-pack com sudo para garantir que o Docker tenha as permissões necessárias.
No macOS, não utilize sudo com o pyodps-pack, pois isso pode causar erros de permissão.

Modo Docker:

pyodps-pack pandas

Modo sem Docker:

pyodps-pack --without-docker pandas

Versão específica:

pyodps-pack pandas==1.2.5

Após o empacotamento, o pyodps-pack exibe as versões resolvidas de todos os pacotes incluídos:

Package         Version
--------------- -------
numpy           1.21.6
pandas          1.2.5
python-dateutil 2.8.2
pytz            2022.6
six             1.16.0

O arquivo de saída packages.tar.gz é gravado no diretório atual.

Empacotar para Python 2.7

Caso precise de um pacote para Python 2.7, o comando varia conforme o local de execução do pacote. Consulte PyODPS DataFrame para mais contexto.

Para o MaxCompute:

pyodps-pack --mcpy27 pandas

Para o DataWorks:

pyodps-pack --dwpy27 pandas

Empacotar código personalizado

O pyodps-pack empacota projetos Python personalizados construídos com setup.py ou pyproject.toml. Consulte Build System Interface para obter detalhes.

O exemplo a seguir empacota um projeto baseado em pyproject.toml com esta estrutura de diretórios:

test_package_root
├── test_package
│   ├── __init__.py
│   ├── mod1.py
│   └── subpackage
│       ├── __init__.py
│       └── mod2.py
└── pyproject.toml

Exemplo de pyproject.toml:

[project]
name = "test_package"
description = "pyodps-pack example package"
version = "0.1.0"
dependencies = [
    "pandas>=1.0.5"
]

Execute o comando abaixo, substituindo <path_to_package> pelo diretório pai de test_package_root:

pyodps-pack /<path_to_package>/test_package_root

Esse processo compacta o projeto e todas as suas dependências no arquivo packages.tar.gz.

Empacotar código de um repositório git

Informe a URL do git diretamente:

pyodps-pack git+https://github.com/aliyun/aliyun-odps-python-sdk.git

Para empacotar uma branch ou tag específica:

pyodps-pack git+https://github.com/aliyun/aliyun-odps-python-sdk.git@v0.11.2.2

Se o processo de empacotamento exigir dependências de compilação (como Cython), especifique-as com --install-requires. Essas dependências são utilizadas durante o empacotamento, mas não são necessariamente incluídas no arquivo de saída.

pyodps-pack \
    --install-requires cython \
    git+https://github.com/aliyun/aliyun-odps-python-sdk.git@v0.11.2.2

Alternativamente, liste as dependências de compilação em um arquivo que siga o formato requirements.txt e passe-o com --install-requires-file:

cython>0.29

pyodps-pack \
    --install-requires-file install-requires.txt \
    git+https://github.com/aliyun/aliyun-odps-python-sdk.git@v0.11.2.2

Empacotar dependências binárias

Alguns pacotes incluem componentes binários — como bibliotecas de vínculo dinâmico — que precisam ser compilados antes do empacotamento. Utilize --run-before para executar um script Bash que instale esses componentes binários antes da execução do pyodps-pack.

O exemplo a seguir empacota o GDAL 3.6.0, que requer libgdal (versão > 3.6.0) e PROJ (versão 6.0 ou posterior), ambos compilados com CMake.

Crie um script chamado install-gdal.sh que compile e instale o PROJ e o GDAL:

#!/bin/bash
set -e

cd /tmp
curl -o proj-6.3.2.tar.gz https://download.osgeo.org/proj/proj-6.3.2.tar.gz
tar xzf proj-6.3.2.tar.gz
cd proj-6.3.2
mkdir build && cd build
cmake ..
cmake --build .
cmake --build . --target install

cd /tmp
curl -o gdal-3.6.0.tar.gz http://download.osgeo.org/gdal/3.6.0/gdal-3.6.0.tar.gz
tar xzf gdal-3.6.0.tar.gz
cd gdal-3.6.0
mkdir build && cd build
cmake ..
cmake --build .
cmake --build . --target install

Execute o pyodps-pack com o script e a dependência de compilação oldest-supported-numpy:

pyodps-pack --install-requires oldest-supported-numpy --run-before install-gdal.sh gdal==3.6.0

Parâmetros

Parâmetro	Descrição
`-r`, `--requirement <file>`	Arquivo de dependências necessário para o empacotamento. Pode ser especificado várias vezes.
`-o`, `--output <file>`	Nome do arquivo de saída. Padrão: `packages.tar.gz`.
`--install-requires <item>`	Dependência do PyPI necessária no momento do empacotamento (não necessariamente incluída no arquivo de saída). Pode ser especificada várias vezes.
`--install-requires-file <file>`	Arquivo que lista dependências do PyPI necessárias no momento do empacotamento, no formato `requirements.txt`. Pode ser especificado várias vezes.
`--run-before <script-file>`	Script Bash a ser executado antes do empacotamento. Geralmente usado para instalar dependências binárias.
`-x`, `--exclude <dependency>`	Dependência do PyPI a ser excluída do arquivo de saída. Pode ser especificada várias vezes.
`--no-deps`	Exclui dependências transitivas do arquivo de saída.
`-i`, `--index-url <index-url>`	URL do índice PyPI. O padrão é `global.index-url` obtido de `pip config list`, configurado em `pip.conf`.
`--trusted-host <host>`	Host HTTPS cujos erros de certificado devem ser ignorados durante o empacotamento.
`-l`, `--legacy-image`	Usa uma imagem CentOS 5 para empacotamento. Garante compatibilidade com ambientes mais antigos, como versões anteriores do Apsara Stack.
`--mcpy27`	Gera um pacote para Python 2.7 no MaxCompute. Ativa `--legacy-image` por padrão.
`--dwpy27`	Gera um pacote para Python 2.7 no DataWorks. Ativa `--legacy-image` por padrão.
`--prefer-binary`	Prefere distribuições binárias mais antigas no PyPI em vez de distribuições mais recentes apenas com código-fonte.
`--docker-args <args>`	Argumentos adicionais a serem passados para o Docker. Coloque vários argumentos entre aspas duplas, por exemplo: `--docker-args "--ip 192.168.1.10"`.
`--without-docker`	Executa o `pyodps-pack` no modo sem Docker. Pacotes com dependências binárias podem falhar ou gerar saídas inutilizáveis.
`--without-merge`	Mantém os arquivos `.whl` em vez de mesclá-los em um arquivo `.tar.gz`.
`--debug`	Exibe detalhes da execução do comando para solução de problemas.

Solucionar falhas de empacotamento

Sintoma	Causa provável	Resolução
Pacote gerado no modo sem Docker não funciona no MaxCompute ou DataWorks	O modo sem Docker não possui o ambiente de SO correspondente	Mude para o modo Docker: remova `--without-docker`
Falha ao iniciar o Docker no Windows	O Windows Server está desativado pela sua organização	Mude para Linux ou tente ativar o Windows Server
Erro de `containerd` com Rancher Desktop no Windows 10	Mecanismo de contêiner incompatível	Alterne para `dockerd` nas configurações do Container Engine do Rancher Desktop
Falha no empacotamento com Python 2	O empacotamento com Python 2 pode falhar para pacotes mais recentes	Use Python 3; se Python 2.7 for obrigatório, utilize `--mcpy27` (MaxCompute) ou `--dwpy27` (DataWorks)
Dependência opcional ausente em tempo de execução	O `pyodps-pack` não inclui dependências opcionais automaticamente	Adicione a dependência opcional explicitamente ao comando, por exemplo: `pyodps-pack pandas openpyxl`
Falha na compilação de dependência binária	Bibliotecas de sistema ou ferramentas de compilação ausentes	Use `--run-before` para instalar as bibliotecas de sistema necessárias antes do empacotamento; adicione `--debug` para obter saída detalhada

Próximos passos

Após gerar o pacote, faça upload dele no MaxCompute como um recurso de arquivo e referencie-o no seu nó PyODPS. Consulte Referenciar um pacote de terceiros em um nó PyODPS.