Difference between revisions of "Python package guidelines (Português)"

From ArchWiki
Jump to: navigation, search
(Create page)
 
(Fonte: remove pre-2016 scheme and clarify current situation)
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:Package development]]
+
[[Category:Package development (Português)]]
 +
[[en:Python package guidelines]]
 
[[it:Python package guidelines]]
 
[[it:Python package guidelines]]
 
[[ja:Python パッケージガイドライン]]
 
[[ja:Python パッケージガイドライン]]
 
[[zh-hans:Python package guidelines]]
 
[[zh-hans:Python package guidelines]]
{{Package guidelines}}
+
{{Diretrizes de pacotes}}
This document covers standards and guidelines on writing [[PKGBUILD]]s for [[Python]] software.
+
Esse documento cobre padrões e diretrizes na escrita de [[PKGBUILD (Português)|PKGBUILD]]s para softwares [[Python]].
  
== Package naming ==
+
== Nome do pacote ==
  
For Python 3 libraries use {{Ic|python-''modulename''}}. Also use the prefix if the package provides a program that is strongly coupled to the Python ecosystem (e.g. pip or tox). For other applications, use only the program name. In either case, the package name should be entirely lowercase.
+
Para módulos de biblioteca do [[Python#Python 3|Python 3]], use {{ic|python-''nomemódulo''}}. Também use o prefixo se o pacote fornece um programa fortemente atrelado ao ecossistema do Python (p. ex. ''pip'' or ''tox''). Para outros aplicativos, use apenas o nome do programa.
  
The same applies to Python 2 only that the prefix (if needed) is {{Ic|python2-}}.
+
O mesmo se aplica para Python 2, exceto que o prefixo (se necessário) é {{ic|python2-}}.
  
===Versioned packages===
+
{{Nota|O nome do pacote deve estar todo em minúsculo.}}
  
If you need to add a versioned package then use {{Ic|python-''modulename''-''version''}}, e.g. {{Ic|python-colorama-0.2.5}}. So python dependency {{Ic|colorama==0.2.5}} will turn into {{Ic|python-colorama-0.2.5}} Arch package.
+
=== Fonte ===
  
== Installation methods ==
+
As URLs de download vinculadas do site do PyPI incluem um hash imprevisível que precisa ser obtido no site do PyPI sempre que um pacote precisar ser atualizado. Isso os torna inadequados para uso em um PKGBUILD. PyPI [https://github.com/pypa/pypi-legacy/issues/438#issuecomment-226940730 fornece] um esquema estável alternativo: matriz [[PKGBUILD (Português)#source]] {{ic|1=source=()}} deve usar os seguintes modelos de URL:
  
Python packages are generally installed using language-specific tools, such as [https://pip.pypa.io/ pip] or [https://setuptools.readthedocs.io/en/latest/easy_install.html easy_install], which are comparable to dedicated package managers in that they are designed to fetch the source files from an online repository (usually [https://pypi.python.org/ PyPI], the Python Package Index) and track the relevant files (for a detailed comparison between the two, see [https://packaging.python.org/pip_easy_install/#pip-vs-easy-install pip vs easy_install]).
+
;Pacote fonte:
 +
:{{ic|<nowiki>https://files.pythonhosted.org/packages/source/${_name::1}/${_name}/${_name}-${pkgver}.tar.gz</nowiki>}}
 +
;Pacote wheel bilingual (compatível com Python 2 e Python 3)
 +
:{{ic|<nowiki>https://files.pythonhosted.org/packages/py2.py3/${_name::1}/$_name/$_name-$pkgver-py2.py3-none-any.whl</nowiki>}}
 +
;Pacote wheel específico para arquitetura
 +
:neste exemplo para {{ic|1=source_x86_64=('...')}}. Também {{ic|1=_py=py36}} pode ser usado para não repetir a versão do python:
 +
:{{ic|<nowiki>https://files.pythonhosted.org/packages/$_py/${_name::1}/$_name/$_name-$pkgver-$_py-${_py}m-manylinux1_x86_64.whl</nowiki>}}
 +
 
 +
Note que uma variável personalizada {{ic|'''$_name'''}} é usada em vez de {{ic|pkgname}} já que nomes de pacotes python são geralmente prefixados com {{ic|python-}}. Essa variável pode ser definida genericamente da seguinte forma:
 +
_name=${pkgname#python-}
 +
 
 +
== Métodos de instalação ==
 +
 
 +
Os pacotes Python geralmente são instalados usando ferramentas específicas da linguagem, como [https://pip.pypa.io/ pip] ou [https://setuptools.readthedocs.io/en/latest/easy_install.html easy_install], que são comparáveis aos gerenciadores de pacotes dedicados na medida em que foram projetados para buscar os arquivos fonte de um repositório online (geralmente [https://pypi.org/ PyPI], o Python Package Index) e rastrear o arquivos relevantes (para uma comparação detalhada entre os dois, veja [https://packaging.python.org/pip_easy_install/#pip-vs-easy-install pip vs easy_install]).
  
However, for managing Python packages from within PKGBUILDs, the standard-provided [http://docs.python.org/library/distutils.html distutils] proves to be the most convenient solution since it uses the downloaded source package's {{ic|setup.py}} and easily installs files under {{ic|''$pkgdir''/usr/lib/python''<python version>''/site-packages/''$pkgname''}} directory.
+
No entanto, para gerenciar pacotes Python dentro de PKGBUILDs, o [http://docs.python.org/library/distutils.html distutils] fornecido de forma padrão é a solução mais conveniente, pois usa o {{ic|setup.py}} do pacote fonte baixado e instala facilmente arquivos no diretório {{ic|''$pkgdir''/usr/lib/python''<versão python>''/site-packages/''$pkgname''}}.
  
 
=== distutils ===
 
=== distutils ===
  
A ''distutils'' example PKGBUILD can be found [https://projects.archlinux.org/abs.git/tree/prototypes/PKGBUILD-python.proto here]. It follows the form:
+
Um PKGBUILD de ''distutils'' é geralmente bem simples:
  
  ''<python version>'' setup.py install --root="$pkgdir/" --optimize=1
+
  build() {
 +
  ''python'' setup.py build
 +
}
 +
 +
package() {
 +
  ''python'' setup.py install --root="$pkgdir/" --optimize=1 --skip-build
 +
}
  
where:
+
sendo que:
  
* ''<python version>'' is replaced with the proper binary, {{ic|python}} or {{ic|python2}}
+
* ''python'' é substituído com o binário correto, {{ic|python}} ou {{ic|python2}}
* {{ic|1=--root="$pkgdir/" }} prevents trying to directly install in the host system instead of inside the package file, which would result in a permission error
+
* {{ic|1=--root="$pkgdir/" }} evita a tentativa de instalar diretamente  no sistema hospedeiro em vez do arquivo de pacote, que resultaria em um erro de permissão
* {{ic|1=--optimize=1}} compiles {{ic|.pyo}} files so they can be tracked by [[pacman]].
+
* {{ic|1=--optimize=1}} compila arquivos bytecode otimizados ({{ic|.pyo}} para Python 2, {{ic|opt-1.pyc}} para Python 3) de forma que eles possam ser rastreados pelo [[pacman (Português)|pacman]].
 +
* {{ic|1=--skip-build}} otimiza, evitando tentativas desnecessárias de reexecutar as etapas de compilação já executadas na função {{ic|build()}}.
  
 
=== setuptools ===
 
=== setuptools ===
  
The Python packaging scene has largely migrated from ''distutils'' to ''setuptools'', which is actively developed and functions as a drop-in replacement import in {{ic|setup.py}}. The main difference for packagers is that ''setuptools'' is packaged separately from Python itself, and must be specified as a {{ic|makedepends}}.
+
A cena de empacotamento de Python migrou em grande parte do ''distutils'' para o ''setuptools'', que está ativamente desenvolvido e funciona como uma importação de substituição ao {{ic|setup.py}}. A principal diferença para os empacotadores é que ''setuptools'' é empacotado separadamente do próprio Python e deve ser especificado como um {{ic|makedepends}}.
  
If the resulting package includes executables which [https://setuptools.readthedocs.io/en/latest/setuptools.html#automatic-script-creation import the {{ic|pkg_resources}} module], then ''setuptools'' must be additionally specified as a {{ic|depends}} in the split {{ic|package_*()}} functions; alternatively, if the PKGBUILD only installs the Python package for a single version of Python, ''setuptools'' should be moved from {{ic|makedepends}} to {{ic|depends}}.
+
Se o pacote resultante incluir executáveis que [https://setuptools.readthedocs.io/en/latest/setuptools.html#automatic-script-creation importam o módulo {{ic|pkg_resources}}], os ''setuptools'' devem ser adicionalmente especificados como {{ic|depends}} das funções de {{ic|package_*()}} divididas; alternativamente, se o PKGBUILD apenas instalar o pacote Python para uma única versão do Python, ''setuptools'' deve ser movido de {{ic|makedepends}} para {{ic|depends}}.
  
 
=== pip ===
 
=== pip ===
  
If you need to use ''pip'' (provided by {{Pkg|python-pip}} and {{Pkg|python2-pip}}), ''e.g.'' for installing [https://bitbucket.org/pypa/wheel/ wheel] packages, remember to pass the following flags:
+
Se você precisar usar o ''pip'' (fornecido por {{Pkg|python-pip}} e {{Pkg|python2-pip}}) para, por exemplo, instalar pacotes [https://github.com/pypa/wheel wheel], lembre-se de passar as seguintes opções:
  
 
  PIP_CONFIG_FILE=/dev/null pip install --isolated --root="$pkgdir" --ignore-installed --no-deps *.whl
 
  PIP_CONFIG_FILE=/dev/null pip install --isolated --root="$pkgdir" --ignore-installed --no-deps *.whl
  
* {{ic|PIP_CONFIG_FILE&#61;/dev/null}} ignores {{ic|{/etc,~/.config}/pip.conf}} that may be appending arbitrary flags to '''pip'''.
+
* {{ic|PIP_CONFIG_FILE&#61;/dev/null}} ignora {{ic|{/etc,~/.config}/pip.conf}}, o qual pode estar anexando sinalizadores arbitrários ao '''pip'''.
* {{ic|--isolated}} ignores environment variables (and again {{ic|{/etc,~/.config}/pip/pip.conf}}) that may otherwise also be appending arbitrary flags to '''pip'''.
+
* {{ic|--isolated}} ignora variáveis de ambiente (e, novamente, {{ic|{/etc,~/.config}/pip/pip.conf}}) que, do contrário, poderia também estar anexando sinalizadores arbitrários ao '''pip'''.
* {{ic|--ignore-installed}} is necessary until https://github.com/pypa/pip/issues/3063 is resolved (otherwise '''pip''' skips the install in the presence of an earlier {{ic|--user}} install).
+
* {{ic|--ignore-installed}} é necessário até https://github.com/pypa/pip/issues/3063 estar resolvido (do contrário, '''pip''' ignora a instalação na presença de uma instalação {{ic|--user}} anterior).
* {{ic|--no-deps}} ensures, that dependencies do not get packaged together with the main package.
+
* {{ic|--no-deps}} assegura que dependências não sejam empacotadas junto com pacote principal.
 
 
''pip'' doesn't know how to generate {{ic|.pyo}} files (see https://github.com/pypa/pip/issues/2209). In order to generate them manually after ''pip'' has installed the module, run:
 
  
python -O -m compileall "${pkgdir}/path/to/module
+
''pip'' não sabe como gerar arquivos {{ic|.pyo}} (veja https://github.com/pypa/pip/issues/2209). Para gerá-los manualmente após ''pip'' ter instalado o módulo, execute:
  
== Notes ==
+
python -O -m compileall "${pkgdir}/caminho/para/o/módulo"
  
In most cases, you should put {{Ic|any}} in the {{Ic|arch}} array since most Python packages are architecture independent.
+
{{Atenção|O uso de pacotes ''pip'' e/ou de wheel é desencorajado em favor dos pacotes fonte setuptools, e deve ser usado somente quando o último não é uma opção viável (por exemplo, pacotes que '''somente''' vêm com roda fontes e, portanto, não pode ser instalado usando setuptools).}}
  
Please do not install a directory named just {{Ic|tests}}, as it easily conflicts with other Python packages (for example, {{Ic|/usr/lib/python2.7/site-packages/tests/}}).
 
  
=== PyPI download URLs ===
+
== Notas ==
  
PyPI URLs of the form {{ic|<nowiki>https://pypi.python.org/packages/source/${_name:0:1}/${_name}/${_name}-${pkgver}.tar.gz</nowiki>}}<footnote> were silently abandoned for new package versions in the course of 2016, replaced by a scheme using an unpredictable hash that needs to be fetched from the PyPI website each time a package must be updated[https://bitbucket.org/pypa/pypi/issues/438/backwards-compatible-un-hashed-package#comment-27230605].
+
Na maioria dos casos, você deve colocar {{Ic|any}} no vetor {{Ic|arch}}, já que a maioria dos pacotes Python são independentes da arquitetura.
  
As downstream packagers voiced their concerns to PyPI maintainers[https://bitbucket.org/pypa/pypi/issues/438/backwards-compatible-un-hashed-package], a new stable scheme was provided[https://bitbucket.org/pypa/pypi/issues/438/backwards-compatible-un-hashed-package#comment-27606213]: [[PKGBUILD#source]] {{ic|1=source=()}} array should now use the following URL templates.
+
Não instale um diretório chamado apenas {{Ic|tests}}, pois ele facilmente entra em conflito com outros pacotes Python (por exemplo, {{Ic|/usr/lib/python2.7/site-packages/tests/}}).
 
 
Note that a custom {{ic|$_name}} variable is used instead of {{ic|$pkgname}} since python packages are generally named {{ic|python-$_name}}
 
 
 
;Source package:
 
:{{ic|<nowiki>https://files.pythonhosted.org/packages/source/${_name::1}/${_name}/${_name}-${pkgver}.tar.gz</nowiki>}}
 
;Bilingual wheel package (Python 2 and Python 3 compatible)
 
:{{ic|<nowiki>https://files.pythonhosted.org/packages/py2.py3/${_name::1}/$_name/$_name-$pkgver-$_name-$pkgver-py2.py3-none-any.whl</nowiki>}}
 
;Arch specific wheel package
 
:in this example for {{ic|1=source_x86_64=('...')}}. Also {{ic|1=_py=py36}} can be used to not repeat the python version:
 
:{{ic|<nowiki>https://files.pythonhosted.org/packages/$_py/${_name::1}/$_name/$_name-$pkgver-$_py-${_py}m-manylinux1_x86_64.whl</nowiki>}}
 

Latest revision as of 21:34, 16 June 2018

Diretrizes de criação de pacotes

CLRCrossEclipseFree PascalGNOMEGoHaskellJavaKDEKernelLispMinGWNode.jsNonfreeOCamlPerlPHPPythonRRubyVCSWebWine

Esse documento cobre padrões e diretrizes na escrita de PKGBUILDs para softwares Python.

Nome do pacote

Para módulos de biblioteca do Python 3, use python-nomemódulo. Também use o prefixo se o pacote fornece um programa fortemente atrelado ao ecossistema do Python (p. ex. pip or tox). Para outros aplicativos, use apenas o nome do programa.

O mesmo se aplica para Python 2, exceto que o prefixo (se necessário) é python2-.

Nota: O nome do pacote deve estar todo em minúsculo.

Fonte

As URLs de download vinculadas do site do PyPI incluem um hash imprevisível que precisa ser obtido no site do PyPI sempre que um pacote precisar ser atualizado. Isso os torna inadequados para uso em um PKGBUILD. PyPI fornece um esquema estável alternativo: matriz PKGBUILD (Português)#source source=() deve usar os seguintes modelos de URL:

Pacote fonte
https://files.pythonhosted.org/packages/source/${_name::1}/${_name}/${_name}-${pkgver}.tar.gz
Pacote wheel bilingual (compatível com Python 2 e Python 3)
https://files.pythonhosted.org/packages/py2.py3/${_name::1}/$_name/$_name-$pkgver-py2.py3-none-any.whl
Pacote wheel específico para arquitetura
neste exemplo para source_x86_64=('...'). Também _py=py36 pode ser usado para não repetir a versão do python:
https://files.pythonhosted.org/packages/$_py/${_name::1}/$_name/$_name-$pkgver-$_py-${_py}m-manylinux1_x86_64.whl

Note que uma variável personalizada $_name é usada em vez de pkgname já que nomes de pacotes python são geralmente prefixados com python-. Essa variável pode ser definida genericamente da seguinte forma:

_name=${pkgname#python-}

Métodos de instalação

Os pacotes Python geralmente são instalados usando ferramentas específicas da linguagem, como pip ou easy_install, que são comparáveis aos gerenciadores de pacotes dedicados na medida em que foram projetados para buscar os arquivos fonte de um repositório online (geralmente PyPI, o Python Package Index) e rastrear o arquivos relevantes (para uma comparação detalhada entre os dois, veja pip vs easy_install).

No entanto, para gerenciar pacotes Python dentro de PKGBUILDs, o distutils fornecido de forma padrão é a solução mais conveniente, pois usa o setup.py do pacote fonte baixado e instala facilmente arquivos no diretório $pkgdir/usr/lib/python<versão python>/site-packages/$pkgname.

distutils

Um PKGBUILD de distutils é geralmente bem simples:

build() {
  python setup.py build
}

package() {
  python setup.py install --root="$pkgdir/" --optimize=1 --skip-build
}

sendo que:

  • python é substituído com o binário correto, python ou python2
  • --root="$pkgdir/" evita a tentativa de instalar diretamente no sistema hospedeiro em vez do arquivo de pacote, que resultaria em um erro de permissão
  • --optimize=1 compila arquivos bytecode otimizados (.pyo para Python 2, opt-1.pyc para Python 3) de forma que eles possam ser rastreados pelo pacman.
  • --skip-build otimiza, evitando tentativas desnecessárias de reexecutar as etapas de compilação já executadas na função build().

setuptools

A cena de empacotamento de Python migrou em grande parte do distutils para o setuptools, que está ativamente desenvolvido e funciona como uma importação de substituição ao setup.py. A principal diferença para os empacotadores é que setuptools é empacotado separadamente do próprio Python e deve ser especificado como um makedepends.

Se o pacote resultante incluir executáveis que importam o módulo pkg_resources, os setuptools devem ser adicionalmente especificados como depends das funções de package_*() divididas; alternativamente, se o PKGBUILD apenas instalar o pacote Python para uma única versão do Python, setuptools deve ser movido de makedepends para depends.

pip

Se você precisar usar o pip (fornecido por python-pip e python2-pip) para, por exemplo, instalar pacotes wheel, lembre-se de passar as seguintes opções:

PIP_CONFIG_FILE=/dev/null pip install --isolated --root="$pkgdir" --ignore-installed --no-deps *.whl
  • PIP_CONFIG_FILE=/dev/null ignora {/etc,~/.config}/pip.conf, o qual pode estar anexando sinalizadores arbitrários ao pip.
  • --isolated ignora variáveis de ambiente (e, novamente, {/etc,~/.config}/pip/pip.conf) que, do contrário, poderia também estar anexando sinalizadores arbitrários ao pip.
  • --ignore-installed é necessário até https://github.com/pypa/pip/issues/3063 estar resolvido (do contrário, pip ignora a instalação na presença de uma instalação --user anterior).
  • --no-deps assegura que dependências não sejam empacotadas junto com pacote principal.

pip não sabe como gerar arquivos .pyo (veja https://github.com/pypa/pip/issues/2209). Para gerá-los manualmente após pip ter instalado o módulo, execute:

python -O -m compileall "${pkgdir}/caminho/para/o/módulo"
Atenção: O uso de pacotes pip e/ou de wheel é desencorajado em favor dos pacotes fonte setuptools, e deve ser usado somente quando o último não é uma opção viável (por exemplo, pacotes que somente vêm com roda fontes e, portanto, não pode ser instalado usando setuptools).


Notas

Na maioria dos casos, você deve colocar any no vetor arch, já que a maioria dos pacotes Python são independentes da arquitetura.

Não instale um diretório chamado apenas tests, pois ele facilmente entra em conflito com outros pacotes Python (por exemplo, /usr/lib/python2.7/site-packages/tests/).