diff options
| author |   Michał Górny <mgorny@gentoo.org> | 2022-01-27 21:11:58 +0100 |
|---|---|---|
| committer | Michał Górny <mgorny@gentoo.org> | 2022-01-27 21:11:58 +0100 |
| commit | 14070722c8111a273d3c76af27983a414f939ab1 (patch) | |
| tree | 976c7691c0ad9b4d8e9743cdb44af5f058d575bc | |
| parent | Update the feed list (diff) | |
| download | python-14070722c8111a273d3c76af27983a414f939ab1.tar.gz python-14070722c8111a273d3c76af27983a414f939ab1.tar.bz2 python-14070722c8111a273d3c76af27983a414f939ab1.zip | |
Import the current version of python-guide
Signed-off-by: Michał Górny <mgorny@gentoo.org>
62 files changed, 30692 insertions, 0 deletions
diff --git a/guide/.buildinfo b/guide/.buildinfo new file mode 100644 index 0000000..1465edc --- /dev/null +++ b/guide/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 902be6c3afff37cdd809b831d6a93de7 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/guide/_sources/any.rst.txt b/guide/_sources/any.rst.txt new file mode 100644 index 0000000..bc4b50f --- /dev/null +++ b/guide/_sources/any.rst.txt @@ -0,0 +1,274 @@ +===================================== +python-any-r1 — build-time dependency +===================================== + +.. highlight:: bash + +The ``python-any-r1`` eclass is used to enable Python support +in packages needing it purely at build time. + +Eclass reference: `python-any-r1.eclass(5)`_ + + +Basic use for unconditional Python +================================== +The defining feature of this eclass is that it defines a ``pkg_setup`` +phase. It normally calls ``python_setup`` function in order to find +a suitable Python interpreter, and set the global environment +appropriately. + +This means that a most trivial package using an autotools-compatible +build system that needs Python at build time could look like +the following: + +.. code-block:: bash + :emphasize-lines: 6,7,21 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{6..8} ) + inherit python-any-r1 + + DESCRIPTION="A repository of data files describing media player capabilities" + HOMEPAGE="https://cgit.freedesktop.org/media-player-info/" + SRC_URI="https://www.freedesktop.org/software/${PN}/${P}.tar.gz" + + LICENSE="BSD" + SLOT="0" + KEYWORDS="~alpha amd64 ~arm ~arm64 ~hppa ~ia64 ~mips ppc ppc64 ~sh ~sparc x86" + IUSE="" + + RDEPEND=">=virtual/udev-208" + DEPEND="${RDEPEND}" + BDEPEND=" + ${PYTHON_DEPS} + virtual/pkgconfig + " + +This ebuild demonstrates the absolute minimum working code. Only +the three highlighted lines are specific to Python eclasses, plus +the implicitly exported ``pkg_setup`` phase. + + +.. index:: python_gen_any_dep; python-any-r1 +.. index:: python_check_deps; python-any-r1 +.. index:: PYTHON_USEDEP; python-any-r1 + +Dependencies +============ +When depending on other Python packages, USE dependencies need to be +declared in order to ensure that the dependencies would be built against +the Python implementation used for the package. When Python +dependencies need to be specified, ``${PYTHON_DEPS}`` gets replaced +by a call to ``python_gen_any_dep`` generator and a matching +``python_check_deps()`` function. + +The ``python_gen_any_dep`` function accepts a template where literal +``${PYTHON_USEDEP}`` is substituted with appropriate USE dependency. +It generates an any-of (``||``) dependency that requires all +the packages to use the same Python interpreter, for at least one +of the supported implementations. + +The ``python_check_deps()`` function needs to be declared by ebuild +in order to test whether the implementation in question is suitable +for building the package. In particular, it needs to verify whether +the particular branch of the any-of was satisfied, or whether all +dependencies were installed for the current interpreter. For that +purpose, the function is called with ``PYTHON_USEDEP`` variable declared +to the USE dependency string for the currently tested implementation. + +This is best explained using an example: + +.. code-block:: bash + :emphasize-lines: 19-22,25-28 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + PYTHON_COMPAT=( python3_{6,7,8} ) + + inherit meson python-any-r1 + + DESCRIPTION="A file manager for Cinnamon, forked from Nautilus" + HOMEPAGE="http://developer.linuxmint.com/projects/cinnamon-projects.html" + SRC_URI="https://github.com/linuxmint/nemo/archive/${PV}.tar.gz -> ${P}.tar.gz" + + LICENSE="GPL-2+ LGPL-2+ FDL-1.1" + SLOT="0" + KEYWORDS="amd64 x86" + IUSE="" + + DEPEND=" + $(python_gen_any_dep ' + dev-python/polib[${PYTHON_USEDEP}] + dev-python/pygobject:3[${PYTHON_USEDEP}] + ') + " + + python_check_deps() { + has_version "dev-python/polib[${PYTHON_USEDEP}]" && + has_version "dev-python/pygobject:3[${PYTHON_USEDEP}]" + } + +This means that the package will work with Python 3.6, 3.7 or 3.8, +provided that its both dependencies have the same implementation +enabled. The generated ``||`` dep ensures that this is true for +at least one of them, while ``python_check_deps()`` verifies which +branch was satisfied. + +It is important to understand that this works correctly only if +``python_gen_any_dep`` and ``python_check_deps()`` match exactly. +Furthermore, for any USE flag combination ``python_gen_any_dep`` must be +called at most once. In particular, it is invalid to split the above +example into multiple ``python_gen_any_dep`` calls. + + +Conditional Python use +====================== +In some packages, Python is only necessary with specific USE flag +combinations. This is particularly common when Python is used for +the test suite. In that case, the dependencies and ``pkg_setup`` call +need to be wrapped in appropriate USE conditions: + +.. code-block:: bash + :emphasize-lines: 16,17,21-27,35 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{6,7} ) + inherit python-any-r1 + + DESCRIPTION="Programmable Completion for bash" + HOMEPAGE="https://github.com/scop/bash-completion" + SRC_URI="https://github.com/scop/bash-completion/releases/download/${PV}/${P}.tar.xz" + + LICENSE="GPL-2+" + SLOT="0" + KEYWORDS="~alpha amd64 arm ~arm64 ~hppa ia64 ~mips ppc ~ppc64 ~s390 ~sh sparc x86 ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos ~m68k-mint ~sparc-solaris ~sparc64-solaris" + IUSE="test" + RESTRICT="!test? ( test )" + + RDEPEND=">=app-shells/bash-4.3_p30-r1:0" + DEPEND=" + test? ( + ${RDEPEND} + $(python_gen_any_dep ' + dev-python/pexpect[${PYTHON_USEDEP}] + dev-python/pytest[${PYTHON_USEDEP}] + ') + )" + + python_check_deps() { + has_version -d "dev-python/pexpect[${PYTHON_USEDEP}]" && + has_version -d "dev-python/pytest[${PYTHON_USEDEP}]" + } + + pkg_setup() { + use test && python-any-r1_pkg_setup + } + + +Additional conditional dependencies +=================================== +Another possible case is that Python is required unconditionally +but some dependencies are required only conditionally to USE flags. +The simplest way to achieve that is to use ``${PYTHON_DEPS}`` globally +and ``python_gen_any_dep`` in USE-conditional block, then express +a similar condition in ``python_check_deps()``: + +.. code-block:: bash + :emphasize-lines: 16,19-24,27-30 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{6,7} ) + inherit python-any-r1 cmake + + DESCRIPTION="Qt bindings for the Telepathy D-Bus protocol" + HOMEPAGE="https://telepathy.freedesktop.org/" + SRC_URI="https://telepathy.freedesktop.org/releases/${PN}/${P}.tar.gz" + + LICENSE="LGPL-2.1" + SLOT="0" + KEYWORDS="amd64 ~arm arm64 x86" + IUSE="test" + RESTRICT="!test? ( test )" + + BDEPEND="${PYTHON_DEPS} + test? ( + $(python_gen_any_dep ' + dev-python/dbus-python[${PYTHON_USEDEP}] + ') + ) + " + + python_check_deps() { + use test || return 0 + has_version -b "dev-python/dbus-python[${PYTHON_USEDEP}]" + } + + +Multiple sets of conditional dependencies +========================================= +The hardest case for this eclass is to declare multiple Python +dependencies conditional to different USE flags. While there are +multiple possible ways of doing that, the least error-prone is to move +USE conditional blocks inside ``python_gen_any_dep``: + +.. code-block:: bash + :emphasize-lines: 15,21-27,30-36,39 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + PYTHON_COMPAT=( python3_6 ) + + inherit gnome2 python-any-r1 + + DESCRIPTION="GObject library for accessing the freedesktop.org Secret Service API" + HOMEPAGE="https://wiki.gnome.org/Projects/Libsecret" + + LICENSE="LGPL-2.1+ Apache-2.0" # Apache-2.0 license is used for tests only + SLOT="0" + KEYWORDS="~alpha amd64 arm arm64 ia64 ~mips ppc ppc64 sparc x86" + IUSE="+introspection test" + RESTRICT="!test? ( test )" + # Tests fail with USE=-introspection, https://bugs.gentoo.org/655482 + REQUIRED_USE="test? ( introspection )" + + DEPEND=" + test? ( + $(python_gen_any_dep ' + dev-python/mock[${PYTHON_USEDEP}] + dev-python/dbus-python[${PYTHON_USEDEP}] + introspection? ( dev-python/pygobject:3[${PYTHON_USEDEP}] ) + ') + ) + " + + python_check_deps() { + if use introspection; then + has_version --host-root "dev-python/pygobject:3[${PYTHON_USEDEP}]" || return 1 + fi + has_version --host-root "dev-python/mock[${PYTHON_USEDEP}]" && + has_version --host-root "dev-python/dbus-python[${PYTHON_USEDEP}]" + } + + pkg_setup() { + use test && python-any-r1_pkg_setup + } + + +.. _python-any-r1.eclass(5): + https://devmanual.gentoo.org/eclass-reference/python-any-r1.eclass/index.html diff --git a/guide/_sources/basic.rst.txt b/guide/_sources/basic.rst.txt new file mode 100644 index 0000000..ce042bf --- /dev/null +++ b/guide/_sources/basic.rst.txt @@ -0,0 +1,81 @@ +============= +Common basics +============= + +.. highlight:: bash + +The various eclasses in python-r1 try to follow a single design. You +will probably use more than one of them, so it is worthwhile to shortly +explain the common bits used by all of them, as well as the non-obvious +differences between them. + + +.. index:: PYTHON_COMPAT + +PYTHON_COMPAT +============= +The ``PYTHON_COMPAT`` variable is used by all Python eclasses, and must +be declared in all ebuilds before they are inherited. It specifies +the list of Python implementations supported by the package. + +The valid values are: + +- ``pythonX_Y`` for CPython X.Y +- ``pypy3`` for PyPy3. + +Typical use:: + + PYTHON_COMPAT=( python3_{6,7,8} pypy3 ) + inherit python-single-r1 + + +.. index:: PYTHON_DEPS +.. index:: PYTHON_REQUIRED_USE + +PYTHON_DEPS and PYTHON_REQUIRED_USE +=================================== +The ``python-any-r1``, ``python-single-r1`` and ``python-r1`` eclasses +all assume that the developer is responsible for explicitly putting +the dependency strings and USE requirements in correct variables. +This is meant to consistently cover packages that use Python +unconditionally and conditionally, at build time and at runtime. + +For ``python-single-r1`` and ``python-r1``, the most basic form to use +Python unconditionally is to define the following:: + + REQUIRED_USE=${PYTHON_REQUIRED_USE} + + RDEPEND=${PYTHON_DEPS} + BDEPEND=${RDEPEND} + +For ``python-any-r1``, only build-time dependencies are used:: + + BDEPEND=${PYTHON_DEPS} + +This does not apply to ``distutils-r1`` as it does the above assignment +by default. + + +.. index:: EPYTHON +.. index:: PYTHON + +Python environment +================== +The eclasses commonly use the concept of *Python environment*. This +means a state of environment enforcing a particular Python +implementation. Whenever the ebuild code is run inside this +environment, ``EPYTHON`` variable indicates which implementation +is being used (by its executable name, e.g. ``python3.8``). + +Additionally, ``PYTHON`` provides the absolute path to the interpreter +(however, using ``EPYTHON`` is preferable whenever possible). Wrappers +for ``python``, ``pythonN`` and some common tools are provided in PATH, +and ``/usr/bin/python`` etc. also enforce the specific implementation +via python-exec (for programs that hardcode full path). + +The environment can be either established in local scope, or globally. +The local scope generally applies to multi-impl packages, and is created +either by calls to ``python_foreach_impl`` from ``python-r1``, or inside +sub-phase functions in ``distutils-r1``. The global scope setup is done +via calling ``python_setup``, either directly or via default +``pkg_setup`` in ``python-any-r1`` and ``python-single-r1``. diff --git a/guide/_sources/buildsys.rst.txt b/guide/_sources/buildsys.rst.txt new file mode 100644 index 0000000..c89bca8 --- /dev/null +++ b/guide/_sources/buildsys.rst.txt @@ -0,0 +1,655 @@ +================================================ +Integration with build systems written in Python +================================================ + +Besides the build systems commonly used by Python packages there are +a few build systems written in Python and requiring the packages +to script them in Python. This makes it necessary to use a proper +Python eclass in order to declare their compatibility with Python +versions. + + +Meson +===== +Meson_ build system is a fairly recent addition. While it is written +in Python, its scripts use a custom Python-agnostic script language. +Hence, it can be treated as an arbitrary external tool and does not need +any Python eclass. + + +SCons +===== +SCons_ has gained Python 3 support quite recently. At the same time, +many old script files were written for Python 2 and fail when run +via Python 3 SCons. For this reason, it is necessary to use Python +eclass when using SCons. + +In the simplest case when the package has no other use for Python, +it is sufficient to declare ``PYTHON_COMPAT`` for the SCons scripts +in the package, and inherit ``python-any-r1`` prior to ``scons-utils`` +(this happens naturally when you sort includes by eclass name). +The latter eclass takes care of setting as much as possible. + +If the package has other Python components, it is necessary to account +for them and use an appropriate eclass as detailed in the eclass choice +chapter. + + +Build-time use with no extra dependencies +----------------------------------------- +If the package either has no other Python components than SCons, or all +of them are purely build-time and have no dependencies, it is sufficient +to inherit ``python-any-r1``. The eclass takes care of setting +``BDEPEND`` along with matching ``python_check_deps()``. + +.. code-block:: bash + :emphasize-lines: 6,7 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{6,7} ) + inherit python-any-r1 scons-utils toolchain-funcs + + COMMIT="6e5e8a57628095d8d0c8bbb38187afb0f3a42112" + DESCRIPTION="Userspace Xbox 360 Controller driver" + HOMEPAGE="https://xboxdrv.gitlab.io" + SRC_URI="https://github.com/chewi/xboxdrv/archive/${COMMIT}.tar.gz -> ${P}.tar.gz" + S="${WORKDIR}/${PN}-${COMMIT}" + + LICENSE="GPL-3" + SLOT="0" + KEYWORDS="~amd64 ~x86" + + RDEPEND=" + dev-libs/boost:= + dev-libs/dbus-glib + dev-libs/glib:2 + sys-apps/dbus + virtual/libudev:= + virtual/libusb:1 + x11-libs/libX11 + " + + DEPEND=" + ${RDEPEND} + " + + BDEPEND=" + dev-util/glib-utils + virtual/pkgconfig + " + + src_compile() { + escons \ + BUILD=custom \ + CXX="$(tc-getCXX)" \ + AR="$(tc-getAR)" \ + RANLIB="$(tc-getRANLIB)" \ + CXXFLAGS="-Wall ${CXXFLAGS}" \ + LINKFLAGS="${LDFLAGS}" + } + + src_install() { + dobin xboxdrv + doman doc/xboxdrv.1 + dodoc AUTHORS NEWS PROTOCOL README.md TODO + } + + +Build-time use with extra dependencies +-------------------------------------- +If the package has extra dependencies, you need to take care of *all* +dependencies yourself. This is because ``python_gen_any_dep`` cannot +be combined. + +.. code-block:: bash + :emphasize-lines: 6,7,35,51 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{6,7} ) + inherit python-any-r1 scons-utils toolchain-funcs + + MY_P=${PN}-src-r${PV/_rc/-rc} + DESCRIPTION="A high-performance, open source, schema-free document-oriented database" + HOMEPAGE="https://www.mongodb.com" + SRC_URI="https://fastdl.mongodb.org/src/${MY_P}.tar.gz" + S="${WORKDIR}/${MY_P}" + + LICENSE="Apache-2.0 SSPL-1" + SLOT="0" + KEYWORDS="~amd64" + IUSE="test +tools" + RESTRICT="!test? ( test )" + + RDEPEND="acct-group/mongodb + acct-user/mongodb + >=app-arch/snappy-1.1.3 + >=dev-cpp/yaml-cpp-0.6.2:= + >=dev-libs/boost-1.70:=[threads(+)] + >=dev-libs/libpcre-8.42[cxx] + app-arch/zstd + dev-libs/snowball-stemmer + net-libs/libpcap + >=sys-libs/zlib-1.2.11:=" + DEPEND="${RDEPEND} + ${PYTHON_DEPS} + $(python_gen_any_dep ' + test? ( dev-python/pymongo[${PYTHON_USEDEP}] ) + >=dev-util/scons-2.5.0[${PYTHON_USEDEP}] + dev-python/cheetah3[${PYTHON_USEDEP}] + dev-python/psutil[${PYTHON_USEDEP}] + dev-python/pyyaml[${PYTHON_USEDEP}] + virtual/python-typing[${PYTHON_USEDEP}] + ') + sys-libs/ncurses:0= + sys-libs/readline:0=" + PDEPEND="tools? ( >=app-admin/mongo-tools-${PV} )" + + python_check_deps() { + if use test; then + has_version "dev-python/pymongo[${PYTHON_USEDEP}]" || + return 1 + fi + + has_version ">=dev-util/scons-2.5.0[${PYTHON_USEDEP}]" && + has_version "dev-python/cheetah3[${PYTHON_USEDEP}]" && + has_version "dev-python/psutil[${PYTHON_USEDEP}]" && + has_version "dev-python/pyyaml[${PYTHON_USEDEP}]" && + has_version "virtual/python-typing[${PYTHON_USEDEP}]" + } + + src_configure() { + scons_opts=( + CC="$(tc-getCC)" + CXX="$(tc-getCXX)" + + --disable-warnings-as-errors + --use-system-boost + --use-system-pcre + --use-system-snappy + --use-system-stemmer + --use-system-yaml + --use-system-zlib + --use-system-zstd + ) + + default + } + + src_compile() { + escons "${scons_opts[@]}" core tools + } + + src_test() { + "${EPYTHON}" ./buildscripts/resmoke.py --dbpathPrefix=test \ + --suites core --jobs=$(makeopts_jobs) || die "Tests failed" + } + + src_install() { + escons "${scons_opts[@]}" --nostrip install --prefix="${ED}"/usr + } + + +Single-impl package +------------------- +If the package needs to install some Python components, and single-impl +install is appropriate, you need to combine ``python-single-r1`` +with ``scons-utils``. In this case, the eclass takes care of everything +needed for SCons, and you take care of everything needed for your +package. + +.. code-block:: bash + :emphasize-lines: 6,7,18 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=5 + + PYTHON_COMPAT=( python2_7 ) + inherit eutils python-single-r1 scons-utils toolchain-funcs + + DESCRIPTION="Molecular dynamics by NMR data analysis" + HOMEPAGE="https://www.nmr-relax.com/" + SRC_URI="http://download.gna.org/relax/${P}.src.tar.bz2" + + SLOT="0" + LICENSE="GPL-2" + KEYWORDS="~amd64 ~x86 ~amd64-linux ~x86-linux" + IUSE="test" + RESTRICT="!test? ( test )" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + RDEPEND=" + ${PYTHON_DEPS} + $(python_gen_cond_dep " + dev-python/Numdifftools[\${PYTHON_USEDEP}] + || ( + dev-python/matplotlib-python2[\${PYTHON_USEDEP}] + dev-python/matplotlib[\${PYTHON_USEDEP}] + ) + || ( + dev-python/numpy-python2[\${PYTHON_USEDEP}] + dev-python/numpy[\${PYTHON_USEDEP}] + ) + dev-python/wxpython:${WX_GTK_VER}[\${PYTHON_USEDEP}] + sci-chemistry/pymol[\${PYTHON_USEDEP}] + >=sci-libs/bmrblib-1.0.3[\${PYTHON_USEDEP}] + >=sci-libs/minfx-1.0.11[\${PYTHON_USEDEP}] + || ( + sci-libs/scipy-python2[\${PYTHON_USEDEP}] + sci-libs/scipy[\${PYTHON_USEDEP}] + ) + ") + sci-chemistry/molmol + sci-chemistry/vmd + sci-visualization/grace + sci-visualization/opendx" + DEPEND="${RDEPEND} + media-gfx/pngcrush + test? ( ${RDEPEND} ) + " + + src_compile() { + tc-export CC + escons + } + + src_install() { + python_moduleinto ${PN} + python_domodule * + + make_wrapper ${PN}-nmr "${EPYTHON} $(python_get_sitedir)/${PN}/${PN}.py $@" + } + + +Single-impl package with conditional Python install +--------------------------------------------------- +If the runtime part of the package uses Python only conditionally, +the use is similar to a package with unconditional build-time +and conditional runtime dependency on Python. That is, build-time +dependencies, ``REQUIRED_USE`` and ``pkg_setup`` must be called +unconditionally. + +.. code-block:: bash + :emphasize-lines: 6,11,23,50 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{6,7,8} ) + + FORTRAN_NEEDED=fortran + FORTRAN_STANDARD=90 + + inherit python-single-r1 scons-utils toolchain-funcs + + DESCRIPTION="Object-oriented tool suite for chemical kinetics, thermodynamics, and transport" + HOMEPAGE="https://www.cantera.org" + SRC_URI="https://github.com/Cantera/${PN}/archive/v${PV}.tar.gz -> ${P}.tar.gz" + + LICENSE="BSD" + SLOT="0" + KEYWORDS="amd64 ~x86" + IUSE="fortran pch +python" + + REQUIRED_USE=" + ${PYTHON_REQUIRED_USE} + " + + RDEPEND=" + python? ( + ${PYTHON_DEPS} + $(python_gen_cond_dep ' + dev-python/numpy[${PYTHON_USEDEP}] + ') + ) + <sci-libs/sundials-5.1.0:0= + " + + DEPEND=" + ${RDEPEND} + dev-cpp/eigen:3 + dev-libs/boost + dev-libs/libfmt + python? ( + $(python_gen_cond_dep ' + dev-python/cython[${PYTHON_USEDEP}] + ') + ) + " + + pkg_setup() { + fortran-2_pkg_setup + python-single-r1_pkg_setup + } + + src_configure() { + scons_vars=( + CC="$(tc-getCC)" + CXX="$(tc-getCXX)" + cc_flags="${CXXFLAGS}" + cxx_flags="-std=c++11" + debug="no" + FORTRAN="$(tc-getFC)" + FORTRANFLAGS="${CXXFLAGS}" + optimize_flags="-Wno-inline" + renamed_shared_libraries="no" + use_pch=$(usex pch) + system_fmt="y" + system_sundials="y" + system_eigen="y" + env_vars="all" + extra_inc_dirs="/usr/include/eigen3" + ) + + scons_targets=( + f90_interface=$(usex fortran y n) + python2_package="none" + ) + + if use python ; then + scons_targets+=( python3_package="full" python3_cmd="${EPYTHON}" ) + else + scons_targets+=( python3_package="none" ) + fi + } + + src_compile() { + escons build "${scons_vars[@]}" "${scons_targets[@]}" prefix="/usr" + } + + src_test() { + escons test + } + + src_install() { + escons install stage_dir="${D}" libdirname="$(get_libdir)" + python_optimize + } + + +Pure Python multi-impl package +------------------------------ +When you are dealing with a pure Python package using SCons, it makes +sense to use plain ``python-r1`` API. This means that SCons is going +to be called from a ``python_foreach_impl`` loop only. + +.. code-block:: bash + :emphasize-lines: 6,7,17,29,57,62 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 ) + inherit fortran-2 python-r1 scons-utils toolchain-funcs + + DESCRIPTION="Automated pipeline for performing Poisson-Boltzmann electrostatics calculations" + HOMEPAGE="https://www.poissonboltzmann.org/" + SRC_URI="https://github.com/Electrostatics/apbs-${PN}/releases/download/${P}/${PN}-src-${PV}.tar.gz" + + SLOT="0" + LICENSE="BSD" + KEYWORDS="amd64 x86 ~amd64-linux ~x86-linux" + IUSE="opal" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + RDEPEND="${PYTHON_DEPS} + || ( + dev-python/numpy-python2[${PYTHON_USEDEP}] + dev-python/numpy[${PYTHON_USEDEP}] + ) + sci-chemistry/openbabel-python[${PYTHON_USEDEP}] + opal? ( dev-python/zsi[${PYTHON_USEDEP}] ) + " + DEPEND="${RDEPEND} + dev-lang/swig:0 + dev-util/scons[${PYTHON_USEDEP}]" + + src_prepare() { + find -type f \( -name "*.pyc" -o -name "*.pyo" \) -delete || die + + eapply "${PATCHES[@]}" + eapply_user + rm -rf scons || die + + python_copy_sources + } + + python_configure() { + tc-export CXX + cat > "${BUILD_DIR}"/build_config.py <<-EOF || die + PREFIX="${D}/$(python_get_sitedir)/${PN}" + APBS="${EPREFIX}/usr/bin/apbs" + MAX_ATOMS=10000 + BUILD_PDB2PKA=False + REBUILD_SWIG=True + EOF + } + + src_configure() { + python_foreach_impl python_configure + } + + src_compile() { + python_foreach_impl run_in_build_dir escons + } + + python_install() { + cd "${BUILD_DIR}" || die + escons install + python_optimize + } + + src_install() { + python_foreach_impl python_install + } + + +Hybrid python-r1 + SCons package +-------------------------------- +Finally, let's consider a package that uses SCons as a build system +and installs Python components independently of it. This could be +e.g. a C/C++ program with separate Python bindings. + +Let's presume that the Python bindings need to be installed manually, +and they support a wider target range than the build system. In this +case, the any-r1 API is recommended. + +.. code-block:: bash + :emphasize-lines: 25,28-30,46 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 python3_6 ) + inherit python-r1 scons-utils toolchain-funcs + + DESCRIPTION="GPS daemon and library for USB/serial GPS devices and GPS/mapping clients" + HOMEPAGE="https://gpsd.gitlab.io/gpsd/" + SRC_URI="mirror://nongnu/${PN}/${P}.tar.gz" + + LICENSE="BSD" + SLOT="0/24" + KEYWORDS="~amd64 ~arm ~ppc ~ppc64 ~sparc ~x86" + + IUSE="python" + REQUIRED_USE=" + python? ( ${PYTHON_REQUIRED_USE} )" + + RDEPEND=" + >=net-misc/pps-tools-0.0.20120407 + python? ( ${PYTHON_DEPS} )" + DEPEND="${RDEPEND} + $(python_gen_any_dep '>=dev-util/scons-2.3.0[${PYTHON_USEDEP}]' -2) + virtual/pkgconfig" + + python_check_deps() { + has_version ">=dev-util/scons-2.3.0[${PYTHON_USEDEP}]" + } + + src_configure() { + myesconsargs=( + prefix="${EPREFIX}/usr" + libdir="\$prefix/$(get_libdir)" + udevdir="$(get_udevdir)" + chrpath=False + gpsd_user=gpsd + gpsd_group=uucp + nostrip=True + manbuild=False + $(use_scons python) + ) + + # SConstruct uses py2 constructs + python_setup -2 + } + + src_compile() { + export CHRPATH= + tc-export CC CXX PKG_CONFIG + export SHLINKFLAGS=${LDFLAGS} LINKFLAGS=${LDFLAGS} + escons + } + + src_install() { + DESTDIR="${D}" escons install + use python && python_foreach_impl python_domodule gps + } + + +waf +=== +The waf_ build system is written in Python and bundled with the packages +using it. Therefore, it is necessary to combine ``waf-utils`` eclass +with one of the Python eclasses. + +Since SCons does not have any dependencies beside the Python +interpreter, the integration is generally simple. You consider waf +like any other build-time script, and use the eclass implied by other +Python components in package. + +Furthermore, since waf requires threading support in the Python +interpreter, it is necessary to add ``PYTHON_REQ_USE='threads(+)'`` in +all waf packages (combined with individual package requirements if +applicable). + + +Build-time use +-------------- +If waf is the only build-time Python script in the package, it is only +necessary to add ``PYTHON_REQ_USE`` and ``${PYTHON_DEPS}`` to build-time +dependencies. If the package had other Python dependencies, you would +specify them instead. + +.. code-block:: bash + :emphasize-lines: 6,7,10,22 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 ) + PYTHON_REQ_USE='threads(+)' + NO_WAF_LIBDIR=yes + + inherit python-any-r1 waf-utils + + DESCRIPTION="C++ Template Unit Test Framework" + HOMEPAGE="http://mrzechonek.github.io/tut-framework/" + SRC_URI="https://github.com/mrzechonek/tut-framework/archive/${PV//./-}.tar.gz -> ${P}.tar.gz" + S="${WORKDIR}/tut-framework-${PV//./-}" + + LICENSE="BSD-2" + SLOT="0" + KEYWORDS="~amd64 ~x86" + IUSE="" + + BDEPEND=${PYTHON_DEPS} + + +Single-impl package +------------------- +The rules for integrating simple-impl package are roughly the same +as for pure ``python-single-r1`` use. Again, waf requires only plain +build-time ``${PYTHON_DEPS}`` and ``PYTHON_REQ_USE``. + +.. code-block:: bash + :emphasize-lines: 5,6,8,31,42 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + PYTHON_COMPAT=( python2_7 ) + PYTHON_REQ_USE="threads" + + inherit python-single-r1 waf-utils + + DESCRIPTION="An LDAP-like embedded database" + HOMEPAGE="https://ldb.samba.org/" + SRC_URI="https://www.samba.org/ftp/pub/${PN}/${P}.tar.gz" + + LICENSE="LGPL-3" + SLOT="0/${PV}" + KEYWORDS="~alpha amd64 arm ~arm64 ~hppa ia64 ~mips ppc ppc64 ~s390 ~sh sparc x86" + IUSE="+ldap python" + REQUIRED_USE="python? ( ${PYTHON_REQUIRED_USE} )" + + RDEPEND="!elibc_FreeBSD? ( dev-libs/libbsd ) + dev-libs/popt + >=sys-libs/talloc-2.1.8[python?] + >=sys-libs/tevent-0.9.31[python(+)?] + >=sys-libs/tdb-1.3.12[python?] + python? ( ${PYTHON_DEPS} ) + ldap? ( net-nds/openldap ) + " + + DEPEND="dev-libs/libxslt + virtual/pkgconfig + ${PYTHON_DEPS} + ${RDEPEND}" + + WAF_BINARY="${S}/buildtools/bin/waf" + + PATCHES=( + "${FILESDIR}"/${PN}-1.1.27-optional_packages.patch + "${FILESDIR}"/${P}-disable-python.patch + ) + + pkg_setup() { + python-single-r1_pkg_setup + } + + src_configure() { + local myconf=( + $(usex ldap '' --disable-ldap) + $(usex python '' '--disable-python') + --disable-rpath + --disable-rpath-install --bundled-libraries=NONE + --with-modulesdir="${EPREFIX}"/usr/$(get_libdir)/samba + --builtin-libraries=NONE + ) + waf-utils_src_configure "${myconf[@]}" + } + + +.. _Meson: https://mesonbuild.com/ + +.. _SCons: https://scons.org/ + +.. _waf: https://waf.io/ diff --git a/guide/_sources/concept.rst.txt b/guide/_sources/concept.rst.txt new file mode 100644 index 0000000..52704b8 --- /dev/null +++ b/guide/_sources/concept.rst.txt @@ -0,0 +1,217 @@ +================= +Advanced concepts +================= + +.. highlight:: python + +Namespace packages +================== + +Hierarchical package structure +------------------------------ +Traditionally, Python packages were organized into a hierarchical +structure with modules and subpackages being located inside the parent +package directory. When submodules are imported, they are represented +as attributes on the parent module. Consider the following session:: + + >>> import sphinx.addnodes + >>> sphinx + <module 'sphinx' from '/usr/lib/python3.8/site-packages/sphinx/__init__.py'> + >>> sphinx.addnodes + <module 'sphinx.addnodes' from '/usr/lib/python3.8/site-packages/sphinx/addnodes.py'> + +This works fine most of the time. However, it start being problematic +when multiple Gentoo packages install parts of the same top-level +package. This may happen e.g. with some plugin layouts where plugins +are installed inside the package. More commonly, it happens when +upstream wishes all their packages to start with a common component. + +This is the case with Zope framework. Different Zope packages share +common ``zope`` top-level package. ``dev-python/zope-interface`` +installs into ``zope.interface``, ``dev-python/zope-event`` +into ``zope.event``. For this to work using the hierarchical layout, +a common package has to install ``zope/__init__.py``, then other Zope +packages have to depend on it and install sub-packages inside that +directory. As far as installed packages are concerned, this is entirely +doable. + +The real problem happens when we wish to test a freshly built package +that depends on an installed package. In that case, Python imports +``zope`` from build directory that contains only ``zope.interface``. +It will not be able to import ``zope.event`` that is installed in system +package directory:: + + >>> import zope.interface + >>> zope + <module 'zope' from '/tmp/portage/dev-python/zope-interface-4.7.1/work/zope.interface-4.7.1-python3_8/lib/zope/__init__.py'> + >>> zope.interface + <module 'zope.interface' from '/tmp/portage/dev-python/zope-interface-4.7.1/work/zope.interface-4.7.1-python3_8/lib/zope/interface/__init__.py'> + >>> import zope.event + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + ModuleNotFoundError: No module named 'zope.event' + +Now, this could be worked around by copying all other subpackages back +to the build directory. However, there is a better solution. + + +Namespace package structure +--------------------------- +Unlike traditional packages, namespace packages act as a kind of proxy. +They are not strictly bound to the containing directory, and instead +permit loading subpackages from all directories found in module search +path. If we make ``zope`` a namespace package, we can import both +the locally built ``zope.interface`` and system ``zope.event`` +packages:: + + >>> import zope.interface + >>> import zope.event + >>> zope + <module 'zope' (namespace)> + >>> zope.interface + <module 'zope.interface' from '/tmp/portage/dev-python/zope-interface-4.7.1/work/zope.interface-4.7.1-python3_8/lib/zope/interface/__init__.py'> + >>> zope.event + <module 'zope.event' from '/usr/lib/python3.8/site-packages/zope/event/__init__.py'> + +There are three common methods of creating namespace packages: + +1. PEP-0420_ namespaces implemented in Python 3.3 and newer, + +2. Using pkgutil_ standard library module, + +3. Using `namespace package support in setuptools`_ (discouraged). + +PEP-0420 namespaces are created implicitly when a package directory +does not contain ``__init__.py`` file. While earlier versions +of Python (including Python 2.7) ignored such directories and did not +permit importing Python modules within them, Python 3.3 imports such +directories as namespace packages. + +pkgutil namespaces use ``__init__.py`` with the following content:: + + __path__ = __import__('pkgutil').extend_path(__path__, __name__) + +setuptools namespace can use ``__init__.py`` with the following +content:: + + __import__('pkg_resources').declare_namespace(__name__) + +Alternatively, setuptools normally installs a ``.pth`` file that is +automatically loaded by Python and implicitly injects the namespace +into Python. + +Both pkgutil and setuptools namespaces are portable to all versions +of Python. + +PEP-0420 and pkgutil namespaces are considered mutually compatible, +while setuptools namespaces are considered incompatible with them. +It is recommended not to mix different methods within a single +namespace. + +More general information on the topic can be found under `packaging +namespace packages`_ in Python Packaging User Guide. + + +Namespace packages in Python 3 +------------------------------ +Since all supported Python versions in Gentoo support PEP-0420 +namespaces, the other two methods are technically unnecessary. However, +the incompatibility between pkg_resources namespaces and the other two +methods makes removing them non-trivial. + +If all packages within the namespace are using only pkgutil-style +namespaces, you can safely remove the dependencies on the package +providing the namespace and the package itself. Even partial removal +should not cause any issues. However, if the package was explicitly +provided upstream, note that some packages may carry an explicit +dependency on it and that dependency would need to be removed or made +conditional to Python < 3.3. You will also need to strip colliding +``__init__.py`` files. + +If setuptools-style namespace are used, the namespace packages need +to remain as-is for the time being, as otherwise tests relying +on the namespaced packages are going to be broken. We have not yet +conceived a way forward for them. + + +Packaging pkgutil-style namespaces in Gentoo +-------------------------------------------- +Normally all packages using the same pkgutil-style namespace install +its ``__init__.py`` file causing package collisions. As having this +file is no longer necessary for Python 3.3 and newer, the recommended +solution is to strip it before installing the package. The presence +of this file is harmless during build and testing. + +.. code-block:: bash + + python_install() { + rm "${BUILD_DIR}"/lib/jaraco/__init__.py || die + distutils-r1_python_install + } + + +Packaging setuptools-style namespaces in Gentoo +----------------------------------------------- +Similar approach is used for setuptools-style namespace packages. +The only differences are in ``__init__.py`` code and removal method. + +The ``dev-python/namespace-<name>`` package for setuptools-style +namespace should use the following code: + +.. code-block:: bash + :emphasize-lines: 24-27,31 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + + PYTHON_COMPAT=( pypy3 python{2_7,3_{6,7,8}} ) + inherit python-r1 + + DESCRIPTION="Namespace package declaration for zope" + HOMEPAGE="https://wiki.gentoo.org/wiki/Project:Python/Namespace_packages" + SRC_URI="" + + LICENSE="public-domain" + SLOT="0" + KEYWORDS="~alpha amd64 arm arm64 hppa ia64 ~m68k ~mips ppc ppc64 s390 ~sh sparc x86 ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos ~sparc-solaris ~sparc64-solaris ~x64-solaris ~x86-solaris" + IUSE="" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + RDEPEND="dev-python/setuptools[${PYTHON_USEDEP}] + ${PYTHON_DEPS}" + DEPEND="${PYTHON_DEPS}" + + src_unpack() { + mkdir -p "${S}"/zope || die + cat > "${S}"/zope/__init__.py <<-EOF || die + __import__('pkg_resources').declare_namespace(__name__) + EOF + } + + src_install() { + python_foreach_impl python_domodule zope + } + +Setuptools normally do not install ``__init__.py`` files but ``*.pth`` +files that do not collide. It is therefore easy to miss them but they +can cause quite a mayhem. Therefore, remember to strip them: + +.. code-block:: bash + + python_install_all() { + distutils-r1_python_install_all + find "${D}" -name '*.pth' -delete || die + } + + +.. _PEP-0420: https://www.python.org/dev/peps/pep-0420/ + +.. _pkgutil: https://docs.python.org/3/library/pkgutil.html + +.. _namespace package support in setuptools: + https://setuptools.readthedocs.io/en/latest/setuptools.html#namespace-packages + +.. _packaging namespace packages: + https://packaging.python.org/guides/packaging-namespace-packages/ diff --git a/guide/_sources/depend.rst.txt b/guide/_sources/depend.rst.txt new file mode 100644 index 0000000..8b113d2 --- /dev/null +++ b/guide/_sources/depend.rst.txt @@ -0,0 +1,186 @@ +===================== +Advanced dependencies +===================== + +.. highlight:: bash + +.. index:: PYTHON_REQ_USE +.. index:: python_gen_impl_dep + +Requesting USE flags on the Python interpreter +============================================== +While the majority of Python standard library modules are available +unconditionally, a few are controlled by USE flags. For example, +the sqlite3_ module requires ``sqlite`` flag to be enabled +on the interpreter. If a package requires this module, it needs +to enforce the matching flag via a USE dependency. + +In order to create a USE dependency on the Python interpreter, set +``PYTHON_REQ_USE`` before inheriting the eclass. This will cause +the eclass to generate appropriate dependency string in ``PYTHON_DEPS``. + +.. code-block:: bash + :emphasize-lines: 7 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_6 ) + PYTHON_REQ_USE="sqlite" + inherit python-r1 gnome2-utils meson xdg-utils + + DESCRIPTION="Modern music player for GNOME" + HOMEPAGE="https://wiki.gnome.org/Apps/Lollypop" + SRC_URI="https://adishatz.org/${PN}/${P}.tar.xz" + KEYWORDS="~amd64" + + LICENSE="GPL-3" + SLOT="0" + REQUIRED_USE=${PYTHON_REQUIRED_USE} + + DEPEND="${PYTHON_DEPS} + ..." + +Full USE dependency syntax is permitted. For example, you can make +the dependency conditional to a flag on the package: + +.. code-block:: bash + :emphasize-lines: 7,17 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + + PYTHON_COMPAT=( python3_6 ) + PYTHON_REQ_USE="sqlite?" + inherit distutils-r1 + + DESCRIPTION="A lightweight password-manager with multiple database backends" + HOMEPAGE="https://pwman3.github.io/pwman3/" + SRC_URI="https://github.com/pwman3/pwman3/archive/v${PV}.tar.gz -> ${P}.tar.gz" + + LICENSE="GPL-3" + SLOT="0" + KEYWORDS="~amd64" + IUSE="mongodb mysql postgres +sqlite" + +Finally, there are cases when the problem cannot be fully solved using +a single USE dependency. Additional Python interpreter dependencies +with specific USE flags can be constructed using ``python_gen_impl_dep`` +helper then. For example, the following ebuild requires Python with +SQLite support when running tests: + +.. code-block:: bash + :emphasize-lines: 24 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + PYTHON_COMPAT=( python{2_7,3_{6,7,8}} pypy3 ) + + inherit distutils-r1 + + DESCRIPTION="Let your Python tests travel through time" + HOMEPAGE="https://github.com/spulec/freezegun" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + + LICENSE="Apache-2.0" + SLOT="0" + KEYWORDS="~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~x86 ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos" + + RDEPEND=" + >dev-python/python-dateutil-2.0[${PYTHON_USEDEP}] + dev-python/six[${PYTHON_USEDEP}] + " + DEPEND="${RDEPEND} + dev-python/setuptools[${PYTHON_USEDEP}] + test? ( + $(python_gen_impl_dep sqlite) + dev-python/mock[${PYTHON_USEDEP}] + dev-python/nose[${PYTHON_USEDEP}] + ) + " + + distutils_enable_tests pytest + + +.. index:: python_gen_cond_dep; for conditional deps + +Dependencies conditional to Python version +========================================== +When packaging software for multiple Python versions, it is quite likely +that you'll find yourself needing some packages only with some +of the versions, and not with others. This is the case with backports +and other compatibility packages. It also happens if some +of the optional dependencies do not support the full set +of implementations your package supports. + +A dependency that applies only to a subset of ``PYTHON_COMPAT`` can +be created using ``python_gen_cond_dep`` function (the same as used +in ``python-single-r1``). In addition to the dependency template, +it accepts an optional list of applicable implementations as arguments. + +For example, ``dev-python/importlib_metadata`` package is a backport +from Python 3.8. Therefore, the majority of its consumers require +it only with older versions of Python:: + + RDEPEND=" + $(python_gen_cond_dep ' + dev-python/importlib_metadata[${PYTHON_USEDEP}] + ' pypy3 python3_{6,7}) + " + +Please note that the first argument is a template containing literal +(escaped through use of single quotes) ``${PYTHON_USEDEP}`` that will +be substituted with partial USE dependency by the eclass function +(``${PYTHON_SINGLE_USEDEP}`` is also permitted when using +``python-single-r1``). It is followed by a list of implementations that +are *not* quoted. The example is using bash brace expansion to express +``python3_6 python3_7`` shorter. + +Since ``pypy3`` can refer to any version of PyPy3, the dependency will +eventually become outdated as PyPy3 upgrades to Python 3.8 +compatibility. This is a known limitation of the eclasses and currently +no solution is provided for it, besides updating dependencies once old +version of PyPy3 is removed. + +An important feature of ``python_gen_cond_dep`` is that it handles +removal of old implementations gracefully. When one of the listed +implementations is no longer supported, it silently ignores it. This +makes it possible to remove old implementations without having to update +all dependency strings immediately. + +For example, in the example below the dependency became empty when +Python 3.7 was removed. + +.. code-block:: + + RDEPEND=" + $(python_gen_cond_dep ' + dev-python/importlib_metadata[${PYTHON_USEDEP}] + ' python3_7)" + + +.. index:: cffi, greenlet + +Dependencies on CFFI and greenlet +================================= +The PyPy distribution includes special versions of the cffi_ +and greenlet_ packages. For this reason, packages using CFFI +and/or greenlet and supporting PyPy3 need to make the explicit +dependencies conditional to CPython:: + + RDEPEND=" + $(python_gen_cond_dep ' + >=dev-python/cffi-1.1.0:=[${PYTHON_USEDEP}] + ' 'python*') + " + + +.. _sqlite3: https://docs.python.org/3.8/library/sqlite3.html +.. _cffi: https://pypi.org/project/cffi/ +.. _greenlet: https://pypi.org/project/greenlet/ diff --git a/guide/_sources/distutils-legacy.rst.txt b/guide/_sources/distutils-legacy.rst.txt new file mode 100644 index 0000000..ad5f2dd --- /dev/null +++ b/guide/_sources/distutils-legacy.rst.txt @@ -0,0 +1,351 @@ +============================ +distutils-r1 legacy concepts +============================ + +.. highlight:: bash + +This section describes concepts specific to the legacy mode +of the ``distutils-r1`` eclass. When using the modern PEP 517 mode, +none of the features described here are available. + + +.. index:: DISTUTILS_USE_SETUPTOOLS + +Different build system variations +================================= +The commonly used build systems specific to Python packages can be +classified for eclass support into following groups: + +1. Plain distutils (built-in in Python). +2. Setuptools and its direct derivatives (e.g. pbr). +3. ``pyproject.toml``-based build systems (Flit, Poetry). + +The eclass supports the first two directly. Support for Flit and Poetry +is provided through the ``dev-python/pyproject2setuppy`` package that +converts the package's metadata to setuptools call. + +In addition to being a build system, setuptools provides runtime +facilities via the ``pkg_resources`` module. If these facilities +are used, the package needs to have a runtime dependency +on ``dev-python/setuptools``. Otherwise, a build-time dependency +is sufficient. + + +DISTUTILS_USE_SETUPTOOLS +------------------------ +The most common case right now is a package using setuptools as a build +system, and therefore needing a build-time dependency only. This +is the eclass' default. If your package does not fit this profile, +you can set ``DISTUTILS_USE_SETUPTOOLS`` variable to one +of the supported values: + +- ``no`` — pure distutils use (no extra dependencies). +- ``bdepend`` — build-time use of setuptools (``BDEPEND`` + on ``dev-python/setuptools``). +- ``rdepend`` — build- and runtime use of setuptools (``BDEPEND`` + and ``RDEPEND`` on ``dev-python/setuptools``). +- ``pyproject.toml`` — use of Flit or Poetry (``BDEPEND`` + on ``dev-python/pyproject2toml`` and ``dev-python/setuptools``). +- ``manual`` — special value indicating that the eclass logic misbehaves + and the dependency needs to be specified manually. Strongly + discouraged, please report a bug and/or fix the package instead. + +The cases for particular values are explained in subsequent sections. + +The Gentoo repository includes a post-install QA check that verifies +whether the value of ``DISTUTILS_USE_SETUPTOOLS`` is correct, +and reports if it is most likely incorrect. This is why it is important +to use the variable rather than specifying the dependency directly. +An example report is:: + + * DISTUTILS_USE_SETUPTOOLS value is probably incorrect + * have: DISTUTILS_USE_SETUPTOOLS=bdepend (or unset) + * expected: DISTUTILS_USE_SETUPTOOLS=rdepend + +The value needs to be set before inheriting the eclass: + +.. code-block:: bash + :emphasize-lines: 7 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 python3_{6,7,8} pypy3 ) + DISTUTILS_USE_SETUPTOOLS=rdepend + + inherit distutils-r1 + + DESCRIPTION="A configurable sidebar-enabled Sphinx theme" + HOMEPAGE="https://github.com/bitprophet/alabaster" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + + LICENSE="BSD" + KEYWORDS="~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~x86 ~x64-solaris" + SLOT="0" + + +distutils and setuptools build systems +-------------------------------------- +Distutils and setuptools are the two most common build systems +for Python packages right now. Their common feature is that they use +a ``setup.py`` script that interfaces with the build system. Generally, +you can determine which of the two build systems are being used +by looking at the imports in ``setup.py``, in particular from which +module the ``setup`` function is imported. + +Distutils-based packages (``DISTUTILS_USE_SETUPTOOLS=no``) use e.g.: + +.. code-block:: python + + from distutils import setup + +Setuptools-based package (``DISTUTILS_USE_SETUPTOOLS=bdepend``, unset +or possibly ``rdepend`` as indicated by the subsequent sections) use: + +.. code-block:: python + + from setuptools import setup + +In some cases, upstreams find it convenient to alternatively support +both setuptools and distutils. A commonly used snippet is: + +.. code-block:: python + + try: + from setuptools import setup + except ImportError: + from distutils import setup + +However, non-fixed build system choice can be problematic to Gentoo +users. This is because pure distutils installs egg-info data as a +single file, while setuptools install the same data as a directory +(using the same path). Therefore, if you rebuild the same version +of the package with a different build system than before, you end up +trying to replace a file with a directory or the other way around. +This is not permitted by the PMS and not handled cleanly by the package +managers. + +You must always ensure that a single build system will be used +unconditionally. In the case of the condition presented above, it is +sufficient to leave ``DISTUTILS_USE_SETUPTOOLS`` at its default value +as that will ensure that setuptools is installed and therefore +the fallback will never take place. However, patching ``setup.py`` may +be necessary if you want to force distutils (e.g. to enable clean +bootstrap) or the upstream condition requiers that. + + +Setuptools' entry points +------------------------ +.. Important:: + + With removal of Python 3.7, the correct ``DISTUTILS_USE_SETUPTOOLS`` + value for packages using entry points changed to ``bdepend``. + +*Entry points* provide the ability to expose some of the package's +Python functions to other packages. They are commonly used to implement +plugin systems and by setuptools themselves to implement wrapper scripts +for starting programs. + +Entry points are defined as ``entry_points`` argument to the ``setup()`` +function, or ``entry_points`` section in ``setup.cfg``. They are +installed in the package's egg-info as ``entry_points.txt``. In both +cases, they are grouped by entry point type, and defined as a dictionary +mapping entry points names to the relevant functions. + +For our purposes, we are only interested in entry points used to define +wrapper scripts, the ``console_scripts`` and ``gui_scripts`` groups, +as they are installed with the package itself. As for plugin systems, +it is reasonable to assume that the installed plugins are only +meaningful to the package using them, and therefore that the package +using them will depend on the appropriate metadata provider. + +Old versions of setuptools used to implement the script wrappers using +``pkg_resources`` package. Modern versions of setuptools use +the following logic: + +1. If ``importlib.metadata`` module is available (Python 3.8+), use it. + In this case, no external dependencies are necessary. + +2. If ``importlib_metadata`` backport is available, use it. It is + provided by ``dev-python/importlib_metadata``. + +3. Otherwise, fall back to ``pkg_resources``. It is provided + by ``dev-python/setuptools``. + +Since Python 3.7 is no longer present in Gentoo (we are not considering +PyPy3.7 correctness important for the time being), new ebuilds do not +need any additional dependencies for entry points and should use +the default value (i.e. remove ``DISTUTILS_USE_SETUPTOOLS``). + +For the time being, the QA check for incorrect values is accepting +both the new value and the old ``rdepend`` value. If you wish to be +reminded about the update, you can add the following variable to your +``make.conf``:: + + DISTUTILS_STRICT_ENTRY_POINTS=1 + +Please note that in some cases ``rdepend`` can still be the correct +value, if there are `other runtime uses of setuptools`_. In some cases +the QA check will also trigger the wrong value because of leftover +explicit dependencies on setuptools. + + +Other runtime uses of setuptools +-------------------------------- +Besides the generated wrapper scripts, the package code itself may use +the ``setuptools`` or ``pkg_resources`` packages. The common cases +for this include getting package metadata and resource files. This +could also be a case for plugin managers and derived build systems. + +As a rule of thumb, if any installed Python file imports ``setuptools`` +or ``pkg_resources``, the package needs to use the value of ``rdepend``. + +The QA check determines that this is the case by looking at the upstream +dependencies (``install_requires``) installed by the package. It is +quite common for packages to miss the dependency, or have a leftover +dependency. If ``install_requires`` does not match actual imports +in the installed modules, please submit a patch upstream. + + +pyproject.toml-based projects +----------------------------- +The newer build systems used for Python packages avoid supplying +``setup.py`` and instead declare package's metadata and build system +information in ``pyproject.toml``. Examples of these build systems +are Flit and Poetry. + +These build systems are generally very heavy and do not support plain +installation to a directory. For this reason, Gentoo is using +``dev-python/pyproject2setuppy`` to provide a thin wrapper for +installing these packages using setuptools. + +To enable the necessary eclass logic and add appropriate build-time +dependencies, specify the value of ``pyproject.toml`` +to ``DISTUTILS_USE_SETUPTOOLS``. + +Strictly speaking, both Flit and Poetry do support entry points, +and therefore some packages actually need a runtime dependency +on setuptools. This is a known limitation, and it will probably +not be addressed for the same reason as the logic for setuptools' entry +points is not updated. + + +.. index:: DISTUTILS_IN_SOURCE_BUILD + +In-source vs out-of-source builds +================================= +In the general definition, an *out-of-source build* is a build where +output files are placed in a directory separate from source files. +By default, distutils and its derivatives always do out-of-source builds +and place output files in subdirectories of ``build`` directory. + +Conversely, an *in-source build* happens when the output files are +interspersed with source files. The closest distutils equivalent +of an in-source build is the ``--inplace`` option of ``build_ext`` +that places compiled C extensions alongside Python module sources. + +``distutils-r1`` shifts this concept a little. When performing +an out-of-source build (the default), it creates a dedicated output +directory for every Python interpreter enabled, and then uses it +throughout all build and install steps. + +It should be noted that unlike build systems such as autotools or CMake, +out-of-source builds in distutils are not executed from the build +directory. Instead, the setup script is executed from source directory +and passed path to build directory. + +Sometimes out-of-source builds are incompatible with custom hacks used +upstream. This could be a case if the setup script is writing +implementation-specific changes to the source files (e.g. using ``2to3`` +to convert them to Python 3) or relying on specific build paths. +For better compatibility with those cases, the eclass provides +an in-source build mode enabled via ``DISTUTILS_IN_SOURCE_BUILD``. + +In this mode, the eclass creates a separate copy of the source directory +for each Python implementation, and then runs the build and install +steps inside that copy. As a result, any changes done to the source +files are contained within the copy used for the current interpreter. + +.. code-block:: bash + :emphasize-lines: 20 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + DISTUTILS_USE_SETUPTOOLS=no + PYTHON_COMPAT=( python3_{6,7,8} pypy3 ) + PYTHON_REQ_USE="xml(+)" + + inherit distutils-r1 + + DESCRIPTION="Collection of extensions to Distutils" + HOMEPAGE="https://github.com/pypa/setuptools https://pypi.org/project/setuptools/" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.zip" + + LICENSE="MIT" + SLOT="0" + KEYWORDS="~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~riscv ~s390 ~sh ~sparc ~x86 ~x64-cygwin ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos ~sparc-solaris ~sparc64-solaris ~x64-solaris ~x86-solaris" + + # Force in-source build because build system modifies sources. + DISTUTILS_IN_SOURCE_BUILD=1 + + +.. index:: distutils_install_for_testing + +Installing the package before testing +===================================== +The tests are executed in ``src_test`` phase, after ``src_compile`` +installed package files into the build directory. The eclass +automatically adds appropriate ``PYTHONPATH`` so that the installed +Python modules and extensions are used during testing. This works +for the majority of packages. + +However, some test suites will not work correctly unless the package +has been properly installed via ``setup.py install``. This may apply +specifically to packages calling their executables that are created +via entry points, various plugin systems or the use of package metadata. + +The ``distutils_install_for_testing`` function runs ``setup.py install`` +into a temporary directory, and adds the appropriate paths to ``PATH`` +and ``PYTHONPATH``. + +This function currently supports two install layouts: + +- the standard *root directory* layout that is enabled + via ``--via-root``, + +- a virtualenv-alike *venv* layout that is enabled via ``--via-venv``. + + +The eclass defaults to the root directory layout that is consistent +with the layout used for the actual install. This ensures that +the package's scripts are found on ``PATH``, and the package metadata +is found via ``importlib.metadata`` / ``pkg_resources``. It should +be sufficient to resolve the most common test problems. + +In some cases, particularly packages that do not preserve ``PYTHONPATH`` +correctly, the virtualenv-alike layout (``--via-venv``) is better. +Through wrapping the Python interpreter itself, it guarantees that +the packages installed in the test environment are found independently +of ``PYTHONPATH`` (just like a true venv). It should cover the few +extreme cases. + +In EAPIs prior to 8, an additional legacy ``--via-home`` layout used +to be supported. It historically used to be necessary to fix problems +with some packages. However, the underlying issues probably went away +along with old versions of Python, and the `removal of site.py hack`_ +has broken it for most of the consumers. + +.. code-block:: bash + + python_test() { + distutils_install_for_testing + epytest --no-network + } + + +.. _removal of site.py hack: + https://github.com/pypa/setuptools/commit/91213fb2e7eecde9f5d7582de485398f546e7aa8 diff --git a/guide/_sources/distutils.rst.txt b/guide/_sources/distutils.rst.txt new file mode 100644 index 0000000..e728a7b --- /dev/null +++ b/guide/_sources/distutils.rst.txt @@ -0,0 +1,1055 @@ +============================================ +distutils-r1 — standard Python build systems +============================================ + +.. highlight:: bash + +The ``distutils-r1`` eclass is used to facilitate build systems using +``setup.py`` (distutils and its derivatives, notably setuptools) +or ``pyproject.toml`` (flit, poetry). It is built on top +of ``python-r1`` and ``python-single-r1``, and therefore supports +efficiently building multi-impl and single-impl packages. + +Eclass reference: `distutils-r1.eclass(5)`_ + + +The PEP 517 and legacy modes +============================ +.. Warning:: + + The PEP 517 mode is still experimental and it is not guaranteed + to handle all packages correctly. When using it, please verify + that all necessary files are installed correctly. The hooks provided + by ``app-portage/iwdevtools`` can be helpful in checking for + regressions when migrating existing packages. + +The ``distutils-r1`` eclass has currently two modes of operation: +the PEP 517 mode and the legacy mode. The former mode should be +preferred for new ebuilds; the latter is provided for backwards +compatibility and packages that are not PEP 517-ready. + +The PEP 517 mode uses backends as defined by `PEP 517`_ to build +packages. It supports a greater number of Python build systems +at the cost of flexibility and performance. In the eclass +implementation, the PEP 517 backend is used to build a wheel (i.e. a zip +archive) with the package and then an installer tool is used to install +the wheel into a staging directory. The complete process is done +in compile phase, and the install phase merely moves the files into +the image directory. + +The legacy mode invokes the ``setup.py`` script directly. The build +command is invoked to populate the build directory in the compile phase, +then the install command is used in the install phase. Normally, this +mode works only for packages using backwards-compatible distutils +derivatives. Additionally, it supports flit and poetry through +pyproject2setuppy hack. This mode relies on deprecated features. + +The PEP 517 mode is enabled via declaring the ``DISTUTILS_USE_PEP517`` +variable. Otherwise, the legacy mode is used. + + +Basic use (PEP 517 mode) +======================== +By default, ``distutils-r1`` sets appropriate metadata variables +and exports a full set of phase functions necessary to install packages +using Python build systems. + +The ``DISTUTILS_USE_PEP517`` variable is used to enable the modern +PEP 517 mode and declare the build system used. The eclass +automatically generates a build-time dependency on the packages needed +for the build system. + +The simplest case of ebuild is: + +.. code-block:: bash + :emphasize-lines: 6-8 + + # Copyright 1999-2022 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=8 + + DISTUTILS_USE_PEP517=setuptools + PYTHON_COMPAT=( python3_{8..10} pypy3 ) + inherit distutils-r1 + + DESCRIPTION="Makes working with XML feel like you are working with JSON" + HOMEPAGE="https://github.com/martinblech/xmltodict/ https://pypi.org/project/xmltodict/" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + + LICENSE="MIT" + SLOT="0" + KEYWORDS="~amd64 ~arm ~arm64 ~x86" + + +Dependencies +============ +Dependencies on Python packages are declared using the same method +as the underlying eclass — that is, ``python-r1`` +or ``python-single-r1``. + +In packages using ``dev-python/setuptools``, dependencies are often +specified in ``setup.py`` or ``setup.cfg`` file. +The ``install_requires`` key specifies runtime dependencies, +``setup_requires`` pure build-time dependencies, ``extras_require`` +optional dependencies. Test dependencies are sometimes specified +as one of the 'extras', and sometimes as ``tests_require``. + +Setuptools strictly enforces ``setup_requires`` at build time, +and ``tests_require`` when running ``setup.py test``. Runtime +dependencies are enforced only when starting installed programs +via entry points. + +In other cases, dependencies are listed in additional files named +e.g. ``requirements.txt``. They could be also found in test runner +setup (``tox.ini``) or CI setup files (``.travis.yml``). Finally, you +can grep source code for ``import`` statements. + +In general, you should take special care when listing dependencies +of Python packages. Upstreams sometimes specify indirect dependencies, +often list packages that are not strictly relevant to Gentoo runs +but used on CI/CD setup, unnecessarily restrict version requirements. + +Most of the time, runtime dependencies do not need to be present +at build time. However, they do need to be copied there if the Python +modules needing them are imported at build time. Often this is the case +when running tests, hence the following logic is common in Python +ebuilds:: + + RDEPEND="..." + BDEPEND="test? ( ${RDEPEND} )" + +There are two different approaches used for optional runtime +dependencies. Some packages are installing them conditionally to USE +flags (this is generally acceptable as long as package builds quickly), +others list them in ``pkg_postinst()`` messages. It is recommended +that optional test dependencies are used unconditionally (to ensure +the widest test coverage, and avoid unpredictable test failures on users +who have more dependencies installed). + + +.. index:: DISTUTILS_SINGLE_IMPL + +python-single-r1 variant +======================== +Normally, ``distutils-r1`` uses ``python-r1`` to build multi-impl +packages, and this is the recommended mode. However, in some cases +you will need to use ``python-single-r1`` instead, especially if you +need to depend on other packages using that eclass. + +The single-impl mode can be enabled by setting ``DISTUTILS_SINGLE_IMPL`` +variable before inheriting the eclass. The eclass aims to provide +maximum compatibility between these two modes, so most of the existing +code will work with either. However, the functions specific to +the underlying eclass are not compatible — e.g. the dependencies need +to be rewritten. + +.. code-block:: bash + :emphasize-lines: 9 + + # Copyright 1999-2022 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{8..10} ) + PYTHON_REQ_USE="readline" + DISTUTILS_USE_PEP517=setuptools + DISTUTILS_SINGLE_IMPL=1 + + inherit distutils-r1 + + DESCRIPTION="Pythonic layer on top of the ROOT framework's PyROOT bindings" + HOMEPAGE="http://rootpy.org" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + + LICENSE="BSD" + SLOT="0" + KEYWORDS="~amd64 ~x86 ~amd64-linux ~x86-linux" + + RDEPEND=" + sci-physics/root:=[${PYTHON_SINGLE_USEDEP}] + dev-python/root_numpy[${PYTHON_SINGLE_USEDEP}] + $(python_gen_cond_dep ' + dev-python/matplotlib[${PYTHON_USEDEP}] + dev-python/pytables[${PYTHON_USEDEP}] + dev-python/termcolor[${PYTHON_USEDEP}] + ')" + + DEPEND=" + sci-physics/root[${PYTHON_SINGLE_USEDEP}]" + + +.. index:: DISTUTILS_USE_PEP517 + +PEP 517 build systems +===================== +The majority of examples in this guide assume using setuptools build +system. However, PEP 517 mode provides support for other build systems. + +In order to determine the correct build system used, read +the ``pyproject.toml`` file. An example file could start with: + +.. code-block:: toml + + [build-system] + requires = ["flit_core >=3.6.0,<4"] + build-backend = "flit_core.buildapi" + +The ``requires`` key indicates the packages required in order to run +the build system, while ``build-backend`` indicates the module +(and optionally the class) providing the build system backend. +The eclass maintains a mapping of backend paths to the respective +``DISTUTILS_USE_PEP517`` and automatically suggests the correct value. + +The following table summarizes supported backends. + +================== ====================== ================================ +USE_PEP517 value Provider package build-backend +================== ====================== ================================ +flit dev-python/flit_core flit_core.buildapi +pdm dev-python/pdm-pep517 pdm.pep517.api +poetry dev-python/poetry-core poetry.core.masonry.api +setuptools dev-python/setuptools setuptools.build_meta + setuptools.__legacy__.build_meta +standalone (none) (various) +================== ====================== ================================ + +The special value ``standalone`` is reserved for bootstrapping build +systems. It indicates that the package itself provides its own build +backend. + +Legacy packages that provide ``setup.py`` but no ``pyproject.toml`` +(or do not define a backend inside it) should be installed via +the ``setuptools`` backend (this applies to pure distutils packages +as well). The eclass automatically uses the legacy setuptools backend +for them. + + +Deprecated PEP 517 backends +=========================== + +flit.buildapi +------------- +Some packages are still found using the historical flit build backend. +Their ``pyproject.toml`` files contain a section similar +to the following: + +.. code-block:: toml + + [build-system] + requires = ["flit"] + build-backend = "flit.buildapi" + +This backend requires installing the complete flit package manager. +Instead, the package should be fixed upstream to use flit_core +per `flit build system section documentation`_ instead: + +.. code-block:: toml + + [build-system] + requires = ["flit_core"] + build-backend = "flit_core.buildapi" + +flit_core produces identical artifacts to flit. At the same time, it +reduces the build-time dependency footprint and therefore makes isolated +PEP 517 builds faster. + + +poetry.masonry.api +------------------ +A similar problem applies to the packages using poetry. The respective +``pyproject.toml`` files contain: + +.. code-block:: toml + + [build-system] + requires = ["poetry>=0.12"] + build-backend = "poetry.masonry.api" + +Instead, the lightweight poetry-core module should be used per `poetry +PEP-517 documentation`_: + +.. code-block:: toml + + [build-system] + requires = ["poetry_core>=1.0.0"] + build-backend = "poetry.core.masonry.api" + +poetry-core produces identical artifacts to poetry. It has smaller +dependency footprint and makes isolated builds much faster. + + +.. index:: SETUPTOOLS_SCM_PRETEND_VERSION + +setuptools_scm and snapshots +============================ +setuptools_scm_ is a package providing additional features for running +inside a VCS checkout, in particular the ability to determine version +from VCS tags. However, this works correctly only when the package +is built from VCS checkout or an ``sdist`` archive containing +pregenerated metadata. It does not work when building from a GitHub +snapshot:: + + Traceback (most recent call last): + File "/tmp/executing-0.5.2/setup.py", line 4, in <module> + setup() + File "/usr/lib/python3.9/site-packages/setuptools/__init__.py", line 143, in setup + _install_setup_requires(attrs) + File "/usr/lib/python3.9/site-packages/setuptools/__init__.py", line 131, in _install_setup_requires + dist = distutils.core.Distribution(dict( + File "/usr/lib/python3.9/site-packages/setuptools/dist.py", line 425, in __init__ + _Distribution.__init__(self, { + File "/usr/lib/python3.9/distutils/dist.py", line 292, in __init__ + self.finalize_options() + File "/usr/lib/python3.9/site-packages/setuptools/dist.py", line 717, in finalize_options + ep(self) + File "/usr/lib/python3.9/site-packages/setuptools_scm/integration.py", line 48, in infer_version + dist.metadata.version = _get_version(config) + File "/usr/lib/python3.9/site-packages/setuptools_scm/__init__.py", line 148, in _get_version + parsed_version = _do_parse(config) + File "/usr/lib/python3.9/site-packages/setuptools_scm/__init__.py", line 110, in _do_parse + raise LookupError( + LookupError: setuptools-scm was unable to detect version for '/tmp/executing-0.5.2'. + + Make sure you're either building from a fully intact git repository or PyPI tarballs. Most other sources (such as GitHub's tarballs, a git checkout without the .git folder) don't contain the necessary metadata and will not work. + + For example, if you're using pip, instead of https://github.com/user/proj/archive/master.zip use git+https://github.com/user/proj.git#egg=proj + +This problem can be resolved by providing the correct version externally +via ``SETUPTOOLS_SCM_PRETEND_VERSION``:: + + export SETUPTOOLS_SCM_PRETEND_VERSION=${PV} + +.. _setuptools_scm: https://pypi.org/project/setuptools-scm/ + + +Parallel build race conditions +============================== +The distutils build system has a major unresolved bug regarding race +conditions. If the same source file is used to build multiple Python +extensions, the build can start multiple simultaneous compiler processes +using the same output file. As a result, there is a race between +the compilers writing output file and link editors reading it. This +generally does not cause immediate build failures but results in broken +extensions causing cryptic issues in reverse dependencies. + +For example, a miscompilation of ``dev-python/pandas`` have recently +caused breakage in ``dev-python/dask``:: + + /usr/lib/python3.8/site-packages/pandas/__init__.py:29: in <module> + from pandas._libs import hashtable as _hashtable, lib as _lib, tslib as _tslib + /usr/lib/python3.8/site-packages/pandas/_libs/__init__.py:13: in <module> + from pandas._libs.interval import Interval + pandas/_libs/interval.pyx:1: in init pandas._libs.interval + ??? + pandas/_libs/hashtable.pyx:1: in init pandas._libs.hashtable + ??? + pandas/_libs/missing.pyx:1: in init pandas._libs.missing + ??? + /usr/lib/python3.8/site-packages/pandas/_libs/tslibs/__init__.py:30: in <module> + from .conversion import OutOfBoundsTimedelta, localize_pydatetime + E ImportError: /usr/lib/python3.8/site-packages/pandas/_libs/tslibs/conversion.cpython-38-x86_64-linux-gnu.so: undefined symbol: pandas_datetime_to_datetimestruct + +The easiest way to workaround the problem in ebuild is to append ``-j1`` +in python_compile_ sub-phase. + +The common way of working around the problem upstream is to create +additional .c files that ``#include`` the original file, and use unique +source files for every extension. + + +Sub-phase functions +=================== +Ebuilds define phase functions in order to conveniently override parts +of the build process. ``distutils-r1`` extends this concept +by introducing *sub-phases*. All ``src_*`` phases in ebuild are split +into two sub-phases: ``python_*`` sub-phases that are run in a loop +for all enabled interpreters, and ``python_*_all`` sub-phases that +comprise the common code to be run only once. + +Sub-phase functions behave similarly to phase functions. They are run +if defined by the ebuild. If they're not, the default implementation +is run (if any). The ebuild overrides can call the default +as ``distutils-r1_<sub-phase>``, the same way it can call eclass' phase +function defaults. + +There are 10 sub-phases corresponding to 5 phase functions. They are +run in the following order: + +1. ``python_prepare_all`` (for ``src_prepare``, has default) +2. ``python_prepare`` (for each impl.) +3. ``python_configure`` (for ``src_configure``, foreach impl.) +4. ``python_configure_all`` +5. ``python_compile`` (for ``src_compile``, for each impl., has default) +6. ``python_compile_all`` +7. ``python_test`` (for ``src_test``, for each impl.) +8. ``python_test_all`` +9. ``python_install`` (for ``src_install``, for each impl., has default) +10. ``python_install_all`` (has default) + +Note that normally all phases are run in the source directory, while +defining ``${BUILD_DIR}`` to a dedicated build directory for each +implementation. However, if in-source builds are enabled, all phases +are run in these build directories. + + +.. index:: python_prepare +.. index:: python_prepare_all + +python_prepare +-------------- + +``python_prepare_all`` is responsible for applying changes +to the package sources that are common to all Python implementations. +The default implementation performs the tasks of ``default_src_prepare`` +(applying patches), as well as eclass-specific tasks: removing +``ez_setup`` (method of bootstrapping setuptools used in old packages) +and handling ``pyproject.toml``. In the end, the function copies +sources to build dirs if in-source build is requested. + +If additional changes need to be done to the package, either this +sub-phase or ``src_prepare`` in general can be replaced. However, +you should always call the original implementation from your override. +For example, you could use it to strip extraneous dependencies or broken +tests:: + + python_prepare_all() { + # FIXME + rm tests/test_pytest_plugin.py || die + sed -i -e 's:test_testcase_no_app:_&:' tests/test_test_utils.py || die + + # remove pointless dep on pytest-cov + sed -i -e '/addopts/s/--cov=aiohttp//' pytest.ini || die + + distutils-r1_python_prepare_all + } + +``python_prepare`` is responsible for applying changes specific to one +interpreter. It has no default implementation. When defined, in-source +builds are enabled implicitly as sources need to be duplicated to apply +implementation-specific changes. + +In the following example, it is used to remove a CLI script whose +dependencies only support Python 3.8 and 3.9 at the moment. Naturally, +since this modification needs to be done on a subset of all Python +interpreters, the eclass needs to keep a separate copy of the sources +for every one of them. This is why ``python_prepare`` automatically +enables in-source builds. + +:: + + python_prepare() { + if ! use cli || ! has "${EPYTHON}" python3.{7..9}; then + sed -i -e '/console_scripts/d' setup.py || die + fi + } + + +.. index:: python_configure +.. index:: python_configure_all + +python_configure +---------------- + +``python_configure`` and ``python_configure_all`` have no default +functionality. The former is convenient for running additional +configuration steps if needed by the package, the latter for defining +global environment variables. + +:: + + python_configure() { + esetup.py configure $(usex mpi --mpi '') + } + +:: + + python_configure_all() { + DISTUTILS_ARGS=( + --resourcepath=/usr/share + --no-compress-manpages + ) + } + + +.. index:: python_compile +.. index:: python_compile_all + +python_compile +-------------- + +``python_compile`` normally builds the package. It is sometimes used +to pass additional arguments to the build step. For example, it can +be used to disable parallel extension builds in packages that are broken +with it:: + + python_compile() { + distutils-r1_python_compile -j1 + } + + +``python_compile_all`` +has no default implementation. It is convenient for performing +additional common build steps, in particular for building +the documentation (see ``distutils_enable_sphinx``). + +:: + + python_compile_all() { + use doc && emake -C docs html + } + + +.. index:: python_test +.. index:: python_test_all + +python_test +----------- + +``python_test`` is responsible for running tests. It has no default +implementation but you are strongly encouraged to provide one (either +directly or via ``distutils_enable_tests``). ``python_test_all`` +can be used to run additional testing code that is not specific +to Python. + +:: + + python_test() { + "${EPYTHON}" TestBitVector/Test.py || die "Tests fail with ${EPYTHON}" + } + + +.. index:: python_install +.. index:: python_install_all + +python_install +-------------- + +``python_install`` installs the package's Python part. It is usually +redefined in order to pass additional ``setup.py`` arguments +or to install additional Python modules. + +:: + + python_install() { + distutils-r1_python_install + + # ensure data files for tests are getting installed too + python_moduleinto collada/tests/ + python_domodule collada/tests/data + } + +``python_install_all`` installs documentation via ``einstalldocs``. +It is usually defined by ebuilds to install additional common files +such as bash completions or examples. + +:: + + python_install_all() { + if use examples; then + docinto examples + dodoc -r Sample_Code/. + docompress -x /usr/share/doc/${PF}/examples + fi + distutils-r1_python_install_all + } + + +Passing arguments to setup.py commands +====================================== +The PEP 517 mode does not support passing additional commands arguments +via ``DISTUTILS_ARGS`` anymore. Instead, the additional parameters +can be passed using the ``setup.cfg`` file. + +For example, Pillow provides for configuring available backends via +additional ``build_ext`` command flags:: + + setup.py build_ext --enable-tiff --disable-webp ... + +The respective options can be setup via the configuration file, where +sections represent the commands and individual keys — options. Note +that dashes need to be replaced by underscores, and flag-style options +take boolean arguments. In this case, the ebuild can use:: + + src_configure() { + cat >> setup.cfg <<-EOF + [build_ext] + disable_tiff = $(usex !tiff True False) + enable_tiff = $(usex tiff True False) + disable_webp = $(usex !webp True False) + enable_webp = $(usex webp True False) + #... + EOF + } + +Note that this method works only for arguments to specific commands. +Some packages use hacks to support global options, e.g. via manipulating +``sys.argv`` directly. This is no longer possible with PEP 517 builds +and the packages need to be fixed not to rely on it. The possible +alternatives include using environment variables or custom commands. + + +.. index:: esetup.py + +Calling custom setup.py commands +================================ +When working on packages using setuptools or modified distutils, you +sometimes need to manually invoke ``setup.py``. The eclass provides +a ``esetup.py`` helper that wraps it with additional checks, error +handling and ensures that the override configuration file is created +beforehand (much like ``econf`` or ``emake``). + +``esetup.py`` passes all its paremeters to ``./setup.py``. + +:: + + python_test() { + esetup.py check + } + + +Preventing test directory from being installed +============================================== +Many packages using the setuptools build system utilize the convenient +``find_packages()`` method to locate the Python sources. In some cases, +this method also wrongly grabs top-level test directories or other files +that were not intended to be installed. + +The eclass attempts to detect and report the most common mistakes: + +.. code-block:: console + + * Package installs 'tests' package which is forbidden and likely a bug in the build system. + +The correct fix for this problem is to add an ``exclude`` parameter +to the ``find_packages()`` call in ``setup.py``, e.g.: + +.. code-block:: python + + setup( + packages=find_packages(exclude=["tests", "tests.*"])) + +Note that if the top-level ``tests`` package has any subpackages, both +``tests`` and ``tests.*`` need to be listed. + +.. warning:: + + In order to test your fix properly, you need to remove the previous + build directory. Otherwise, the install command will install all + files found there, including the files that are now excluded. + +As an intermediate solution it is possible to strip the extra +directories in the install phase:: + + python_install() { + rm -r "${BUILD_DIR}"/lib/tests || die + distutils-r1_python_install + } + + +.. index:: distutils_enable_tests + +Enabling tests +============== +Since Python performs only minimal build-time (or more precisely, +import-time) checking of correctness, it is important to run tests +of Python packages in order to catch any problems early. This is +especially important for permitting others to verify support for new +Python implementations. + +Many Python packages use one of the standard test runners, and work fine +with the default ways of calling them. Note that upstreams sometimes +specify a test runner that's not strictly necessary — e.g. specify +``dev-python/pytest`` as a dependency while the tests do not use it +anywhere and work just fine with built-in modules. The best way +to determine the test runner to use is to grep the test sources. + + +Using distutils_enable_tests +---------------------------- +The simplest way of enabling tests is to call ``distutils_enable_tests`` +in global scope, passing the test runner name as the first argument. +This function takes care of declaring test phase, setting appropriate +dependencies and ``test`` USE flag if necessary. If called after +setting ``RDEPEND``, it also copies it to test dependencies. + +.. code-block:: bash + :emphasize-lines: 22 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 python3_{6,7,8} pypy3 ) + inherit distutils-r1 + + DESCRIPTION="An easy whitelist-based HTML-sanitizing tool" + HOMEPAGE="https://github.com/mozilla/bleach https://pypi.org/project/bleach/" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + + LICENSE="Apache-2.0" + SLOT="0" + KEYWORDS="~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~mips ~ppc ~ppc64 ~s390 ~sparc ~x86" + + RDEPEND=" + dev-python/six[${PYTHON_USEDEP}] + dev-python/webencodings[${PYTHON_USEDEP}] + " + + distutils_enable_tests pytest + +The valid values include: + +- ``nose`` for ``dev-python/nose`` +- ``pytest`` for ``dev-python/pytest`` +- ``setup.py`` to call ``setup.py test`` +- ``unittest`` to use built-in unittest discovery + + +Adding more test dependencies +----------------------------- +Additional test dependencies can be specified in ``test?`` conditional. +The flag normally does not need to be explicitly declared, +as ``distutils_enable_tests`` does that in the majority of cases. + +.. code-block:: bash + :emphasize-lines: 18,21 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + + PYTHON_COMPAT=( python2_7 python3_{6,7,8} pypy3 ) + inherit distutils-r1 + + DESCRIPTION="Universal encoding detector" + HOMEPAGE="https://github.com/chardet/chardet https://pypi.org/project/chardet/" + SRC_URI="https://github.com/chardet/chardet/archive/${PV}.tar.gz -> ${P}.tar.gz" + + LICENSE="LGPL-2.1" + SLOT="0" + KEYWORDS="~alpha amd64 arm arm64 hppa ia64 ~m68k ~mips ppc ppc64 s390 ~sh sparc x86 ~x64-cygwin ~amd64-linux ~x86-linux ~x64-macos ~x86-macos ~x64-solaris" + + DEPEND=" + test? ( dev-python/hypothesis[${PYTHON_USEDEP}] ) + " + + distutils_enable_tests pytest + +Note that ``distutils_enable_tests`` modifies variables directly +in the ebuild environment. This means that if you wish to change their +values, you need to append to them, i.e. the bottom part of that ebuild +can be rewritten as: + +.. code-block:: bash + :emphasize-lines: 3 + + distutils_enable_tests pytest + + DEPEND+=" + test? ( dev-python/hypothesis[${PYTHON_USEDEP}] ) + " + +Installing the package before running tests +------------------------------------------- +In PEP 517 mode, the eclass automatically exposes a venv-style install +tree to the test phase. No explicit action in necessary. + +In the legacy mode, ``distutils_enable_tests`` has an optional +``--install`` option that can be used to force performing an install +to a temporary directory. More information can be found in the legacy +section. + + +Undesirable test dependencies +----------------------------- +There is a number of packages that are frequently listed as test +dependencies upstream but have little to no value for Gentoo users. +It is recommended to skip those test dependencies whenever possible. +If tests fail to run without them, it is often preferable to strip +the dependencies and/or configuration values enforcing them. + +*Coverage testing* establishes how much of the package's code is covered +by the test suite. While this is useful statistic upstream, it has +no value for Gentoo users who just want to install the package. This +is often represented by dependencies on ``dev-python/coverage``, +``dev-python/pytest-cov``. In the latter case, you usually need +to strip ``--cov`` parameter from ``pytest.ini``. + +*PEP-8 testing* enforces standard coding style across Python programs. +Issues found by it are relevant to upstream but entirely irrelevant +to Gentoo users. If the package uses ``dev-python/pep8``, +``dev-python/pycodestyle``, ``dev-python/flake8``, strip that +dependency. + +``dev-python/pytest-runner`` is a thin wrapper to run pytest +from ``setup.py``. Do not use it, just call pytest directly. + +``dev-python/tox`` is a convenient wrapper to run tests for multiple +Python versions, in a virtualenv. The eclass already provides the logic +for the former, and an environment close enough to the latter. Do not +use tox in ebuilds. + + +Customizing the test phase +-------------------------- +If additional pre-/post-test phase actions need to be performed, +they can be easily injected via overriding ``src_test()`` and making +it call ``distutils-r1_src_test``: + +.. code-block:: bash + :emphasize-lines: 30-34 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{6,7,8} ) + inherit distutils-r1 virtualx + + DESCRIPTION="Extra features for standard library's cmd module" + HOMEPAGE="https://github.com/python-cmd2/cmd2" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + + LICENSE="MIT" + SLOT="0" + KEYWORDS="~amd64 ~arm ~arm64 ~ppc64 ~x86 ~amd64-linux ~x86-linux" + + RDEPEND=" + dev-python/attrs[${PYTHON_USEDEP}] + >=dev-python/colorama-0.3.7[${PYTHON_USEDEP}] + >=dev-python/pyperclip-1.6[${PYTHON_USEDEP}] + dev-python/six[${PYTHON_USEDEP}] + dev-python/wcwidth[${PYTHON_USEDEP}] + " + BDEPEND=" + dev-python/setuptools_scm[${PYTHON_USEDEP}] + " + + distutils_enable_tests pytest + + src_test() { + # tests rely on very specific text wrapping... + local -x COLUMNS=80 + distutils-r1_src_test + } + +If the actual test command needs to be customized, or a non-standard +test tool needs to be used, you can define a ``python_test()`` sub-phase +function. This function is called for every enabled Python target +by the default ``src_test`` implementation. This can either be combined +with ``distutils_enable_tests`` call, or used instead of it. In fact, +the former function simply defines a ``python_test()`` function as part +of its logic. + +.. code-block:: bash + :emphasize-lines: 16,17,26-31,33-35 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python{2_7,3_6,3_7,3_8} pypy3 ) + inherit distutils-r1 + + DESCRIPTION="Bash tab completion for argparse" + HOMEPAGE="https://pypi.org/project/argcomplete/" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + + LICENSE="Apache-2.0" + SLOT="0" + KEYWORDS="~amd64 ~arm ~arm64 ~hppa ~x86 ~amd64-linux ~x86-linux ~x64-macos" + IUSE="test" + RESTRICT="!test? ( test )" + + RDEPEND=" + $(python_gen_cond_dep ' + <dev-python/importlib_metadata-2[${PYTHON_USEDEP}] + ' -2 python3_{5,6,7} pypy3)" + # pip is called as an external tool + BDEPEND=" + dev-python/setuptools[${PYTHON_USEDEP}] + test? ( + app-shells/fish + app-shells/tcsh + dev-python/pexpect[${PYTHON_USEDEP}] + dev-python/pip + )" + + python_test() { + "${EPYTHON}" test/test.py -v || die + } + +Note that ``python_test`` is called by ``distutils-r1_src_test``, +so you must make sure to call it if you override ``src_test``. + + +.. index:: epytest + +Customizing the test phase for pytest +------------------------------------- +For the relatively frequent case of pytest-based packages needing +additional customization, a ``epytest`` helper is provided. The helper +runs ``pytest`` with a standard set of options and automatic handling +of test failures. + +For example, if upstream uses ``network`` marker to disable +network-based tests, you can override the test phase in the following +way:: + + distutils_enable_tests pytest + + python_test() { + epytest -m 'not network' + } + + +.. index:: distutils_enable_sphinx + +Building documentation via Sphinx +================================= +``dev-python/sphinx`` is commonly used to document Python packages. +It comes with a number of plugins and themes that make it convenient +to write and combine large text documents (such as this Guide!), +as well as automatically document Python code. + +Depending on the exact package, building documentation may range +from being trivial to very hard. Packages that do not use autodoc +(documenting of Python code) do not need to USE-depend on Sphinx at all. +Packages that do that need to use a supported Python implementation +for Sphinx, and packages that use plugins need to guarantee the same +implementation across all plugins. To cover all those use cases easily, +the ``distutils_enable_sphinx`` function is provided. + + +Basic documentation with autodoc +-------------------------------- +The most common case is a package that uses Sphinx along with autodoc. +It can be recognized by ``conf.py`` listing ``sphinx.ext.autodoc`` +in the extension list. In order to support building documentation, +call ``distutils_enable_sphinx`` and pass the path to the directory +containing Sphinx documentation: + +.. code-block:: bash + :emphasize-lines: 24 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{6,7,8} ) + DISTUTILS_USE_SETUPTOOLS=rdepend + + inherit distutils-r1 + + DESCRIPTION="Colored stream handler for the logging module" + HOMEPAGE=" + https://pypi.org/project/coloredlogs/ + https://github.com/xolox/python-coloredlogs + https://coloredlogs.readthedocs.io/en/latest/" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + + LICENSE="MIT" + SLOT="0" + KEYWORDS="~amd64 ~x86 ~amd64-linux ~x86-linux" + + RDEPEND="dev-python/humanfriendly[${PYTHON_USEDEP}]" + + distutils_enable_sphinx docs + +This call takes care of it all: it adds ``doc`` USE flag to control +building documentation, appropriate dependencies via the expert any-r1 +API making it sufficient for Sphinx to be installed with only one +of the supported implementations, and appropriate ``python_compile_all`` +implementation to build and install HTML documentation. + + +Additional Sphinx extensions +---------------------------- +It is not uncommon for packages to require additional third-party +extensions to Sphinx. Those include themes. In order to specify +dependencies on the additional packages, pass them as extra arguments +to ``distutils_enable_sphinx``. + +.. code-block:: bash + :emphasize-lines: 17-20 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( pypy3 python3_{6,7,8} ) + inherit distutils-r1 + + DESCRIPTION="Correctly inflect words and numbers" + HOMEPAGE="https://github.com/jazzband/inflect" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + + LICENSE="MIT" + SLOT="0" + KEYWORDS="~amd64 ~arm64 ~ia64 ~ppc ~ppc64 ~x86" + + distutils_enable_sphinx docs \ + '>=dev-python/jaraco-packaging-3.2' \ + '>=dev-python/rst-linker-1.9' \ + dev-python/alabaster + +In this case, the function uses the any-r1 API to request one +of the supported implementations to be enabled on *all* of those +packages. However, it does not have to be the one in ``PYTHON_TARGETS`` +for this package. + + +Sphinx without autodoc or extensions +------------------------------------ +Finally, there are packages that use Sphinx purely to build +documentation from text files, without inspecting Python code. +For those packages, the any-r1 API can be omitted entirely and plain +dependency on ``dev-python/sphinx`` is sufficient. In this case, +the ``--no-autodoc`` option can be specified instead of additional +packages. + +.. code-block:: bash + :emphasize-lines: 17 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 python3_{6,7,8} ) + inherit distutils-r1 + + DESCRIPTION="Python Serial Port extension" + HOMEPAGE="https://github.com/pyserial/pyserial https://pypi.org/project/pyserial/" + SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + + LICENSE="PSF-2" + SLOT="0" + KEYWORDS="~alpha amd64 ~arm arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~x86" + + distutils_enable_sphinx documentation --no-autodoc + +Note that this is valid only if no third-party extensions are used. +If additional packages need to be installed, the previous variant +must be used instead. + +The eclass tries to automatically determine whether ``--no-autodoc`` +should be used, and issue a warning if it's missing or incorrect. + + +.. _distutils-r1.eclass(5): + https://devmanual.gentoo.org/eclass-reference/distutils-r1.eclass/index.html +.. _PEP 517: + https://www.python.org/dev/peps/pep-0517/ +.. _flit build system section documentation: + https://flit.readthedocs.io/en/latest/pyproject_toml.html#build-system-section +.. _poetry PEP-517 documentation: + https://python-poetry.org/docs/pyproject/#poetry-and-pep-517 diff --git a/guide/_sources/eclass.rst.txt b/guide/_sources/eclass.rst.txt new file mode 100644 index 0000000..45dc186 --- /dev/null +++ b/guide/_sources/eclass.rst.txt @@ -0,0 +1,126 @@ +================================ +Choosing between Python eclasses +================================ + +Build-time vs runtime use +========================= +The first basis for choosing Python eclass is whether Python is used +merely at build-time or at runtime as well. + +A runtime use occurs if the package explicitly needs Python to be +installed along with it, in order for it to function correctly. This +generally happens if the package installs Python modules, extensions, +scripts, or executables calling the Python interpreter or linking +to libpython. This also applies to bash scripts or other executables +that call python inline. + +A build-time use occurs if the package calls the Python interpreter +or any kind of aforementioned executables during package's build +(or install) phases. + +If the package uses Python purely at build-time, the ``python-any-r1`` +eclass is appropriate. Otherwise, ``python-single-r1``, ``python-r1`` +or their derivatives are to be used. + +A specific exception to that rule is when the package is only calling +external Python scripts directly (i.e. not via ``python /usr/bin/foo``). +If the called executables can be considered fully contained +dependency-wise, there is no need to use an eclass. + +For example, when using ``dev-util/meson`` to build a package, there is +no need to use a Python eclass since Meson abstracts away its Pythonic +implementation details and works as a regular executable for your +packages. However, ``dev-util/scons`` requires Python eclass since it +loads Python code from the package and a compatible Python version must +be enforced. + + +Single-impl vs multi-impl +========================= +The second important basis for packages using Python at runtime is +whether the package in question should support multi-implementation +install or not. + +A *single-impl* package is a package requiring the user to choose +exactly one Python implementation to be built against. This means +that the scripts installed by that package will be run via specified +Python interpreter, and that the modules and extensions will be +importable from it only. The package's Python reverse dependencies will +also have to use the same implementation. Since the package can't +support having more than one implementation enabled, its reverse +dependencies have to be simple-impl as well. + +Single-impl packages use ``python-single-r1`` eclass. Writing ebuilds +for them is easier since it is generally sufficient to call setup +function early on, and the upstream build system generally takes care +of using selected Python version correctly. Making packages single-impl +is recommended when dealing with packages that are not purely written +for Python or have single-impl dependencies. + +A *multi-impl* package allows user to enable multiple (preferably +any number of) implementations. The modules, extensions and scripts +installed by the package are installed separately for each enabled +implementation, and can therefore be used from any of them. The package +can have reverse dependencies enabling only a subset of its +implementations. + +Multi-impl packages use ``python-r1`` eclass. Ebuilds are more complex +since they need to explicitly repeat build and install steps for each +enabled implementation. Using this model is recommended for packages +providing Python modules or extensions only, or having multi-impl +reverse dependencies. In some cases supporting multi-impl build +requires applying hacks, e.g. ``dev-libs/boost[python]`` uses +non-standard names to install ``libboost_python`` for multiple Python +versions. + +The implementation for single-impl packages is selected +via ``PYTHON_SINGLE_TARGET``, while multi-impl uses ``PYTHON_TARGETS``. +These USE flag sets can be set independently to provide greater +flexibility for developers and end users. + + +Distutils and related build systems +=================================== +The third basis for choosing an eclass is the build system used. +If the project uses one of Python-specific build systems, that is +distutils, setuptools, flit or poetry, the ``distutils-r1`` eclass +should be used instead of the other eclasses. As a rule of thumb, +this happens when either ``setup.py`` or ``pyproject.toml`` file exists +in the distribution. + +``distutils-r1`` builds on either ``python-r1`` or ``python-single-r1``, +therefore it can be used to create both multi-impl and single-impl +packages. It provides full set of default phase functions, making +writing ebuilds much easier. + + +A rule of thumb +=============== +As a rule of thumb, the following checklist can be used to determine +the eclass to use: + +1. If the package has ``setup.py`` or ``pyproject.toml`` file, + use ``distutils-r1``. + +2. If the package primarily installs Python modules or extensions + or has multi-impl reverse dependencies, use ``python-r1``. + +3. If the package (possibly conditionally) qualifies as using Python + at runtime, use ``python-single-r1``. + +4. If the package uses Python at build time only, use ``python-any-r1``. + + +python-utils-r1 +=============== +Besides the aforementioned eclasses, the suite includes a common utility +eclass ``python-utils-r1``. This eclass is inherited by all other +eclasses, and it is considered to be a part of their API. Therefore, +it must not be inherited directly if any other of the eclasses +is inherited. + +The only case for direct inherit of ``python-utils-r1`` is when you +are only using some of its utility functions without inheriting +any of the remaining eclasses. However, note that the majority of those +utility functions actually rely on mechanics provided by these eclasses +and are not suitable for being used otherwise. diff --git a/guide/_sources/expert-multi.rst.txt b/guide/_sources/expert-multi.rst.txt new file mode 100644 index 0000000..a0a1a70 --- /dev/null +++ b/guide/_sources/expert-multi.rst.txt @@ -0,0 +1,561 @@ +====================== +Expert python-r1 usage +====================== + +.. highlight:: bash + +The APIs described in this chapter are powerful but even harder to use +than those described in ``python-r1`` chapter. You should not consider +using them unless you have a proper ninja training. + + +.. index:: python_gen_useflags + +Partially restricting Python implementation +=========================================== +There are packages that have been ported to Python 3 only partially. +They may still have some optional dependencies that support Python 2 +only, they may have some components that do not support Python 3 yet. +The opposite is also possible — some of the features being available +only for Python 3. + +There are two approaches to this problem. You can either skip features +(ignore USE flags) if the necessary implementation is not enabled, +or you can use ``REQUIRED_USE`` to enforce at least one interpreter +having the requested feature. + +Skipping specific tasks can be done via investigating ``${EPYTHON}``. +If USE flags are involved, you will probably also need to use +``python_gen_cond_dep`` with additional parameters restricting +dependencies to available targets. + +.. code-block:: bash + :emphasize-lines: 37-43,49 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 python3_{6,7,8} pypy{,3} ) + PYTHON_REQ_USE="threads(+)" + inherit distutils-r1 + + DESCRIPTION="HTTP library for human beings" + HOMEPAGE="http://python-requests.org/" + SRC_URI="mirror://pypi/${P:0:1}/${PN}/${P}.tar.gz" + + LICENSE="Apache-2.0" + SLOT="0" + KEYWORDS="~amd64 ~arm ~arm64 ~sparc ~x86 ~amd64-linux ~x86-linux" + IUSE="socks5 +ssl test" + RESTRICT="!test? ( test )" + + RDEPEND=" + >=dev-python/certifi-2017.4.17[${PYTHON_USEDEP}] + >=dev-python/chardet-3.0.2[${PYTHON_USEDEP}] + <dev-python/chardet-4[${PYTHON_USEDEP}] + >=dev-python/idna-2.5[${PYTHON_USEDEP}] + <dev-python/idna-3[${PYTHON_USEDEP}] + <dev-python/urllib3-1.26[${PYTHON_USEDEP}] + socks5? ( >=dev-python/PySocks-1.5.6[${PYTHON_USEDEP}] ) + ssl? ( + >=dev-python/cryptography-1.3.4[${PYTHON_USEDEP}] + >=dev-python/pyopenssl-0.14[${PYTHON_USEDEP}] + ) + " + + BDEPEND=" + dev-python/setuptools[${PYTHON_USEDEP}] + test? ( + $(python_gen_cond_dep ' + ${RDEPEND} + dev-python/pytest[${PYTHON_USEDEP}] + dev-python/pytest-httpbin[${PYTHON_USEDEP}] + dev-python/pytest-mock[${PYTHON_USEDEP}] + >=dev-python/PySocks-1.5.6[${PYTHON_USEDEP}] + ' 'python*') + ) + " + + python_test() { + # tests hang with pypy & pypy3 + [[ ${EPYTHON} == pypy* ]] && continue + + epytest + } + +Enforcing implementations is done via putting ``||`` block with all +targets providing the feature in ``REQUIRED_USE``. The eclass provides +``python_gen_useflags`` function to print valid flag names for specified +implementation list. Please always use this function instead of listing +actual flag names as it handled phasing implementations out gracefully. +``python_gen_cond_dep`` should also be called with matching target +list. + +.. code-block:: bash + :emphasize-lines: 19,31-33 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{6,7,8} ) + PYTHON_REQ_USE="sqlite" + inherit distutils-r1 + + DESCRIPTION="Toolkit to convert between many translation formats" + HOMEPAGE="https://github.com/translate/translate" + SRC_URI="https://github.com/translate/translate/releases/download/${PV}/${P}.tar.gz" + + LICENSE="GPL-2" + SLOT="0" + KEYWORDS="amd64 arm64 x86 ~amd64-linux ~x86-linux" + IUSE="+subtitles" + REQUIRED_USE="${PYTHON_REQUIRED_USE} + subtitles? ( || ( $(python_gen_useflags python3_{6,7}) ) )" + + DEPEND=">=dev-python/six-1.10.0[${PYTHON_USEDEP}]" + RDEPEND="${DEPEND} + !dev-python/pydiff + app-text/iso-codes + >=dev-python/chardet-3.0.4[${PYTHON_USEDEP}] + >=dev-python/lxml-3.5[${PYTHON_USEDEP}] + >=dev-python/pycountry-18.5.26[${PYTHON_USEDEP}] + >=dev-python/python-levenshtein-0.12.0[${PYTHON_USEDEP}] + sys-devel/gettext + subtitles? ( + $(python_gen_cond_dep ' + media-video/gaupol[${PYTHON_USEDEP}] + ' python3_{6,7}) + ) + " + +.. index:: python_setup; with implementation parameter +.. index:: DISTUTILS_ALL_SUBPHASE_IMPLS + +Restricting interpreters for python_setup +========================================= +A specific case of the restriction described above is when the build +step supports a subset of Python targets for the runtime part. This +could happen e.g. if package's Python bindings have been ported +to Python 3 but the test suite or building tooling still requires +Python 2. + +To support this use case, ``python_setup`` can optionally take a list +of implementations. This list must be a subset of ``PYTHON_COMPAT``, +and only implementation on the list can be used by ``python_setup``. +Note that you also need to set matching ``REQUIRED_USE``, as otherwise +the function will fail if the user does not enable any of the supported +targets. + +.. code-block:: bash + :emphasize-lines: 19,27 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + + PYTHON_COMPAT=( python2_7 python3_{5,6,7} ) + + inherit python-r1 toolchain-funcs + + DESCRIPTION="Python extension module generator for C and C++ libraries" + HOMEPAGE="https://www.riverbankcomputing.com/software/sip/intro" + SRC_URI="https://www.riverbankcomputing.com/static/Downloads/${PN}/${PV}/${P}.tar.gz" + + # Sub-slot based on SIP_API_MAJOR_NR from siplib/sip.h + SLOT="0/12" + LICENSE="|| ( GPL-2 GPL-3 SIP )" + KEYWORDS="alpha amd64 arm arm64 ~hppa ia64 ppc ppc64 ~sparc x86 ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos" + REQUIRED_USE="${PYTHON_REQUIRED_USE} + || ( $(python_gen_useflags 'python2*') )" + + RDEPEND="${PYTHON_DEPS}" + DEPEND="${RDEPEND} + sys-devel/bison + sys-devel/flex + + src_prepare() { + python_setup 'python2*' + "${EPYTHON}" build.py prepare || die + default + } + + src_configure() { + configuration() { + local myconf=( + "${EPYTHON}" + "${S}"/configure.py + --bindir="${EPREFIX}/usr/bin" + --destdir="$(python_get_sitedir)" + --incdir="$(python_get_includedir)" + ) + echo "${myconf[@]}" + "${myconf[@]}" || die + } + python_foreach_impl run_in_build_dir configuration + } + + src_compile() { + python_foreach_impl run_in_build_dir default + } + + src_install() { + installation() { + emake DESTDIR="${D}" install + python_optimize + } + python_foreach_impl run_in_build_dir installation + + einstalldocs + } + +The ``distutils-r1`` equivalent of ``python_setup`` parameters is +the ``DISTUTILS_ALL_SUBPHASE_IMPLS`` variable. Alternatively to global +scope, it can be set in an early phase function (prior to any sub-phase +call). + +.. code-block:: bash + :emphasize-lines: 22,28-30,46 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=5 + + PYTHON_COMPAT=( + pypy + python3_5 python3_6 python3_7 + python2_7 + ) + PYTHON_REQ_USE='bzip2(+),ssl(+),threads(+)' + inherit distutils-r1 + + DESCRIPTION="Portage is the package management and distribution system for Gentoo" + HOMEPAGE="https://wiki.gentoo.org/wiki/Project:Portage" + SRC_URI="mirror://gentoo/${P}.tar.bz2" + + LICENSE="GPL-2" + KEYWORDS="~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~riscv ~s390 ~sh ~sparc ~x86" + SLOT="0" + IUSE="epydoc" + REQUIRED_USE="epydoc? ( $(python_gen_useflags 'python2*') )" + + DEPEND=" + >=app-arch/tar-1.27 + >=sys-apps/sed-4.0.5 sys-devel/patch + epydoc? ( + $(python_gen_cond_dep ' + >=dev-python/epydoc-2.0[${PYTHON_USEDEP}] + ' 'python2*') + )" + RDEPEND=" + >=app-arch/tar-1.27 + dev-lang/python-exec:2 + >=sys-apps/sed-4.0.5 + app-shells/bash:0[readline] + >=app-admin/eselect-1.2 + elibc_glibc? ( >=sys-apps/sandbox-2.2 ) + kernel_linux? ( sys-apps/util-linux ) + >=app-misc/pax-utils-0.1.17" + PDEPEND=" + >=net-misc/rsync-2.6.4 + userland_GNU? ( >=sys-apps/coreutils-6.4 )" + + pkg_setup() { + use epydoc && DISTUTILS_ALL_SUBPHASE_IMPLS=( python2.7 ) + } + + python_compile_all() { + if use epydoc; then + esetup.py epydoc + fi + } + +Note that when the restriction is caused by dependencies rather than +package's files, the any-r1 API described below is preferable to this. + + +.. index:: python_gen_any_dep; python-r1 +.. index:: python_check_deps; python-r1 + +Disjoint build dependencies (any-r1 API) +======================================== +Some packages have disjoint sets of runtime and pure build-time +dependencies. The former need to be built for all enabled +implementations, the latter only for one of them. The any-r1 API +in ``python-r1`` is specifically suited for expressing that. + +Let's consider an example package that uses Sphinx with a plugin +to build documentation. Naturally, you're going to build the documents +only once, not separately for every enabled target. + + +Using regular python-r1 API +--------------------------- +If you were using the regular API, you'd have to use +``${PYTHON_USEDEP}`` on the dependencies. The resulting code could look +like the following:: + + BDEPEND=" + doc? ( + dev-python/sphinx[${PYTHON_USEDEP}] + dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}] + )" + + src_compile() { + ... + + if use doc; then + python_setup + emake -C docs html + fi + } + +If your package is built with support for Python 3.6, 3.7 and 3.8, +then this dependency string will enforce the same targets for Sphinx +and the theme. However, in practice it will only be used through +Python 3.8. Normally, this is not such a big deal. + +Now imagine your package supports Python 2.7 as well, while Sphinx +does not anymore. This means that your package will force downgrade +to the old version of ``dev-python/sphinx`` even though it will not +be used via Python 2.7 at all. + + +Using any-r1 API with python-r1 +------------------------------- +As the name suggests, the any-r1 API resembles the API used +by ``python-any-r1`` eclass. The disjoint build-time dependencies +are declared using ``python_gen_any_dep``, and need to be tested +via ``python_check_deps()`` function. The presence of the latter +function activates the alternate behavior of ``python_setup``. Instead +of selecting one of the enabled targets, it will run it to verify +installed dependencies and use one having all dependencies satisfied. + +.. code-block:: bash + :emphasize-lines: 3-6,9-12,18 + + BDEPEND=" + doc? ( + $(python_gen_any_dep ' + dev-python/sphinx[${PYTHON_USEDEP}] + dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}] + ') + )" + + python_check_deps() { + has_version "dev-python/sphinx[${PYTHON_USEDEP}]" && + has_version "dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}]" + } + + src_compile() { + ... + + if use doc; then + python_setup + emake -C docs html + fi + } + +Note that ``python_setup`` may select an implementation that is not even +enabled via ``PYTHON_TARGETS``. The goal is to try hard to avoid +requiring user to change USE flags on dependencies if possible. + +An interesting side effect of that is that the supported targets +in the dependencies can be a subset of the one in package. For example, +we have used this API to add Python 3.8 support to packages before +``dev-python/sphinx`` supported it — the eclass implicitly forced using +another implementation for Sphinx. + + +Different sets of build-time dependencies +----------------------------------------- +Let's consider the case when Python is used at build-time for something +else still. In that case, we want ``python_setup`` to work +unconditionally but enforce dependencies only with ``doc`` flag enabled. + +.. code-block:: bash + :emphasize-lines: 9-13,16 + + BDEPEND=" + doc? ( + $(python_gen_any_dep ' + dev-python/sphinx[${PYTHON_USEDEP}] + dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}] + ') + )" + + python_check_deps() { + use doc || return 0 + has_version "dev-python/sphinx[${PYTHON_USEDEP}]" && + has_version "dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}]" + } + + src_compile() { + python_setup + + ... + + use doc && emake -C docs html + } + +Note that ``python_setup`` behaves according to the any-r1 API here. +While it will not enforce doc dependencies with ``doc`` flag disabled, +it will use *any* interpreter that is supported and installed, even +if it is not enabled explicitly in ``PYTHON_TARGETS``. + + +Using any-r1 API with distutils-r1 +---------------------------------- +The alternate build dependency API also integrates with ``distutils-r1`` +eclass. If ``python_check_deps()`` is declared, the ``python_*_all()`` +sub-phase functions are called with the interpreter selected according +to any-r1 rules. + +.. code-block:: bash + :emphasize-lines: 3-6,9-13 + + BDEPEND=" + doc? ( + $(python_gen_any_dep ' + dev-python/sphinx[${PYTHON_USEDEP}] + dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}] + ') + )" + + python_check_deps() { + use doc || return 0 + has_version "dev-python/sphinx[${PYTHON_USEDEP}]" && + has_version "dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}]" + } + + python_compile_all() { + use doc && emake -C docs html + } + +Note that ``distutils-r1`` calls ``python_setup`` unconditionally, +therefore ``python_check_deps()`` needs to account for that. + +Normally you won't have to use this API for Sphinx though — +``distutils_enable_sphinx`` does precisely that for you. + + +Combining any-r1 API with implementation restrictions +===================================================== +Both APIs described above can be combined. This can be used when +build-time scripts support a subset of implementations supported +by the package itself, and by its build-time dependencies. For example, +if the package uses ``dev-util/scons`` build system with ``SConstruct`` +files using Python 2 construct. + +There are two approaches to achieve that: either the build-time +implementation list needs to be passed to ``python_setup``, +or ``python_check_deps`` needs to explicitly reject unsupported targets. +In both cases, a matching implementation list needs to be passed +to ``python_gen_any_dep``. + +.. code-block:: bash + :emphasize-lines: 25,28-30,46 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 python3_6 ) + inherit python-r1 toolchain-funcs + + DESCRIPTION="GPS daemon and library for USB/serial GPS devices and GPS/mapping clients" + HOMEPAGE="https://gpsd.gitlab.io/gpsd/" + SRC_URI="mirror://nongnu/${PN}/${P}.tar.gz" + + LICENSE="BSD" + SLOT="0/24" + KEYWORDS="~amd64 ~arm ~ppc ~ppc64 ~sparc ~x86" + + IUSE="python" + REQUIRED_USE=" + python? ( ${PYTHON_REQUIRED_USE} )" + + RDEPEND=" + >=net-misc/pps-tools-0.0.20120407 + python? ( ${PYTHON_DEPS} )" + DEPEND="${RDEPEND} + $(python_gen_any_dep '>=dev-util/scons-2.3.0[${PYTHON_USEDEP}]' -2) + virtual/pkgconfig" + + python_check_deps() { + has_version ">=dev-util/scons-2.3.0[${PYTHON_USEDEP}]" + } + + src_configure() { + myesconsargs=( + prefix="${EPREFIX}/usr" + libdir="\$prefix/$(get_libdir)" + udevdir="$(get_udevdir)" + chrpath=False + gpsd_user=gpsd + gpsd_group=uucp + nostrip=True + manbuild=False + $(use_scons python) + ) + + # SConstruct uses py2 constructs + python_setup -2 + } + +.. code-block:: bash + :emphasize-lines: 25,28-31,46 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 python3_6 ) + inherit python-r1 toolchain-funcs + + DESCRIPTION="GPS daemon and library for USB/serial GPS devices and GPS/mapping clients" + HOMEPAGE="https://gpsd.gitlab.io/gpsd/" + SRC_URI="mirror://nongnu/${PN}/${P}.tar.gz" + + LICENSE="BSD" + SLOT="0/24" + KEYWORDS="~amd64 ~arm ~ppc ~ppc64 ~sparc ~x86" + + IUSE="python" + REQUIRED_USE=" + python? ( ${PYTHON_REQUIRED_USE} )" + + RDEPEND=" + >=net-misc/pps-tools-0.0.20120407 + python? ( ${PYTHON_DEPS} )" + DEPEND="${RDEPEND} + $(python_gen_any_dep '>=dev-util/scons-2.3.0[${PYTHON_USEDEP}]' -2) + virtual/pkgconfig" + + python_check_deps() { + python_is_python3 && return 1 + has_version ">=dev-util/scons-2.3.0[${PYTHON_USEDEP}]" + } + + src_configure() { + myesconsargs=( + prefix="${EPREFIX}/usr" + libdir="\$prefix/$(get_libdir)" + udevdir="$(get_udevdir)" + chrpath=False + gpsd_user=gpsd + gpsd_group=uucp + nostrip=True + manbuild=False + $(use_scons python) + ) + + python_setup + } diff --git a/guide/_sources/helper.rst.txt b/guide/_sources/helper.rst.txt new file mode 100644 index 0000000..bbd65a1 --- /dev/null +++ b/guide/_sources/helper.rst.txt @@ -0,0 +1,266 @@ +======================= +Common helper functions +======================= + +The functions described in this chapter are common to all three basic +eclasses. To facilitate code reuse, they are declared +in ``python-utils-r1.eclass``. However, you should not inherit this +eclass directly and instead assume the functions are provided as part +of the API of other eclasses. + +Eclass reference: `python-utils-r1.eclass(5)`_ + + +.. index:: python_doexe +.. index:: python_newexe +.. index:: python_doscript +.. index:: python_newscript +.. index:: python_domodule +.. index:: python_doheaders +.. index:: python_scriptinto +.. index:: python_moduleinto + +Install helpers +=============== +The install helpers are provided commonly for ``python-single-r1`` +and ``python-r1`` eclasses. Their main purpose is to facilitate +installing Python scripts, modules and extensions whenever the package +lacks a build system or the build system is not suited for installing +them. + +The API is consistent with the standard ``do*``, ``new*`` and ``*into`` +helpers. There are four kinds of functions provided: + +1. ``python_doexe`` and ``python_newexe`` that install executables + wrapping them via python-exec, +2. ``python_doscript`` and ``python_newscript`` that install Python + scripts, updating the shebangs and wrapping them via python-exec, +3. ``python_domodule`` that installs Python modules, or recursively + installs packages (directories), +4. ``python_doheader`` that installs header files to Python-specific + include directory. + +The install path for executables and scripts (1. and 2.) can be adjusted +by calling ``python_scriptinto``. Note that this actually affects only +the wrapper symlink install path; the actual scripts will be installed +in the standard python-exec script directories. This also implies that +no two executables can have the same name, even if final directory is +different. The default install path is ``/usr/bin``. + +The install path for modules and packages (3.) can be adjusted +by calling ``python_moduleinto``. This function accepts either absolute +path or Python parent module name that causes modules to be installed +in an appropriate subdirectory of the site-packages directory. +The default install path is top-level site-packages (equivalent +to ``python_moduleinto .``). + +The install path for headers (4.) cannot be adjusted. + +``python_doexe`` is generally used to install executables that reference +Python but are not Python scripts. This could be e.g. a bash script +that calls Python:: + + make_wrapper "${PN}.tmp" "${EPYTHON} $(python_get_sitedir)/${PN}/cropgtk.py" + python_newexe "${ED%/}/usr/bin/${PN}.tmp" "${PN}" + rm "${ED%/}/usr/bin/${PN}.tmp" || die + +Note that you need to ensure that the executable calls correct Python +interpreter itself. + +``python_doscript`` is generally used to install Python scripts +to binary directories:: + + python_scriptinto /usr/sbin + python_newscript pynslcd.py pynslcd + +It takes care of updating the shebang for you. + +``python_domodule`` is used to install Python modules, extensions, +packages, data files and in general anything that lands in site-packages +directory:: + + python_moduleinto ${PN} + python_domodule images application ${MY_PN}.py \ + AUTHORS CHANGES COPYING DEPENDS TODO __init__.py + +It is roughly equivalent to ``dodir -r``, except that it byte-compiles +all Python modules found inside it. + +``python_doheader`` is used in the very rare cases when Python packages +install additional header files that are used to compile other +extensions:: + + python_doheader src/libImaging/*.h + + +.. index:: python_fix_shebang + +Fixing shebangs on installed scripts +==================================== +If upstream build system installs Python scripts, it should also update +their shebangs to match the interpreter used for install. Otherwise, +the scripts could end up being run via another implementation, one +that possible does not have the necessary dependencies installed. +An example of correct shebang is:: + + #!/usr/bin/env python3.8 + +However, if the build system installs a script with ``python3`` or even +``python`` shebang, it needs to be updated. The ``python_fix_shebang`` +function is provided precisely for that purpose. It can be used to +update the shebang on an installed file:: + + src_install() { + default + python_fix_shebang "${D}"/usr/bin/sphinxtrain + } + +It can also be used in working directory to update a script that's used +at build time or before it is installed:: + + src_prepare() { + default + python_fix_shebang openvpn-vulnkey + } + +Finally, it can also be used on a directory to recursively update +shebangs in all Python scripts found inside it:: + + src_install() { + insinto /usr + doins -r linux-package/* + dobin linux-package/bin/kitty + python_fix_shebang "${ED}" + } + +Normally, ``python_fix_shebang`` errors out when the target interpreter +is not compatible with the original shebang, e.g. when you are trying +to install a script with ``python2`` shebang for Python 3. ``-f`` +(force) switch can be used to override that:: + + src_prepare() { + default + python_fix_shebang -f "${PN}.py" + } + + +.. index:: python_optimize + +Byte-compiling Python modules +============================= +Python modules are byte compiled in order to speed up their loading. +Byte-compilation is normally done by the build system when the modules +are installed. However, sometimes packages fail to compile them +entirely, or byte-compile them only partially. Nowadays, QA checks +detect and report that: + +.. code-block:: text + + * This package installs one or more Python modules that are not byte-compiled. + * The following files are missing: + * + * /usr/lib/pypy2.7/site-packages/_feedparser_sgmllib.pyc + * /usr/lib64/python2.7/site-packages/_feedparser_sgmllib.pyc + * /usr/lib64/python2.7/site-packages/_feedparser_sgmllib.pyo + * + * Please either fix the upstream build system to byte-compile Python modules + * correctly, or call python_optimize after installing them. For more + * information, see: + * https://wiki.gentoo.org/wiki/Project:Python/Byte_compiling + +The eclass provides a ``python_optimize`` function to byte-compile +modules. The most common way of using it is to call it after installing +the package to byte-compile all modules installed into site-packages:: + + src_install() { + cmake_src_install + python_optimize + } + +If Python scripts are installed to a non-standard directory, the path +to them can be passed to the function:: + + src_install() { + cd "${S}"/client || die + emake DESTDIR="${D}" LIBDIR="usr/lib" install + python_optimize "${D}/usr/lib/entropy/client" + } + + +.. index:: python_get_sitedir +.. index:: python_get_includedir +.. index:: python_get_scriptdir +.. index:: python_get_library_path +.. index:: python_get_CFLAGS +.. index:: python_get_LIBS +.. index:: python_get_PYTHON_CONFIG + +Querying the implementation information +======================================= +Most of the time, various build systems manage to detect and query +the Python implementation correctly for necessary build details. +Ocassionally, you need to provide those values or override bad detection +results. For this purpose, the eclasses provide a series of *getters*. + +The following generic getters are provided: + +- ``python_get_sitedir`` that outputs the absolute path to the target's + site-packages directory (where Python modules are installed). + +- ``python_get_includedir`` that outputs the absolute path + to the target-specific header directory. + +- ``python_get_scriptdir`` that outputs the absolute path + to the python-exec script directory for the implementation. + +The following getters are provided only for CPython targets: + +- ``python_get_library_path`` that outputs the absolute path + to the ``python`` library. + +- ``python_get_CFLAGS`` that outputs the C preprocessor flags + for linking against the Python library (equivalent to ``pkg-config + --cflags ...``). + +- ``python_get_LIBS`` that outputs the linker flags for linking + against the Python library (equivalent to ``pkg-config --libs ...``). + +- ``python_get_PYTHON_CONFIG`` that outputs the absolute path + to the ``python-config`` executable. + +Note that all paths provided by getters include the offset-prefix +(``${EPREFIX}``) already and they are not suitable to passing +to ``*into`` helpers. If you need to install something, use `install +helpers`_ instead. + +.. code-block:: bash + + src_configure() { + local mycmakeargs=( + ... + ) + use python && mycmakeargs+=( + -DPYTHON_DEST="$(python_get_sitedir)" + -DPYTHON_EXECUTABLE="${PYTHON}" + -DPYTHON_INCLUDE_DIR="$(python_get_includedir)" + -DPYTHON_LIBRARY="$(python_get_library_path)" + ) + + cmake_src_configure + } + + +.. code-block:: bash + + python_test() { + # prepare embedded executable + emake \ + CC="$(tc-getCC)" \ + PYINC="$(python_get_CFLAGS)" \ + PYLIB="$(python_get_LIBS)" \ + check + } + + +.. _python-utils-r1.eclass(5): + https://devmanual.gentoo.org/eclass-reference/python-utils-r1.eclass/index.html diff --git a/guide/_sources/index.rst.txt b/guide/_sources/index.rst.txt new file mode 100644 index 0000000..7b395b5 --- /dev/null +++ b/guide/_sources/index.rst.txt @@ -0,0 +1,40 @@ +=================== +Gentoo Python Guide +=================== +:Author: Michał Górny +:License: `Creative Commons Attribution 4.0 International`_ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + preface + interpreter + eclass + basic + any + single + multi + distutils + distutils-legacy + helper + depend + test + pytest + concept + expert-multi + buildsys + porting + migration + package-maintenance + interpreter-maintenance + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + +.. _Creative Commons Attribution 4.0 International: + https://creativecommons.org/licenses/by/4.0/ diff --git a/guide/_sources/interpreter-maintenance.rst.txt b/guide/_sources/interpreter-maintenance.rst.txt new file mode 100644 index 0000000..9c75c79 --- /dev/null +++ b/guide/_sources/interpreter-maintenance.rst.txt @@ -0,0 +1,286 @@ +===================================== +Maintenance of Python implementations +===================================== + +Life cycle of a Python implementation +===================================== +Every Python implementation (understood as a potential target) in Gentoo +follows roughly the following life cycle: + +1. The interpreter is added to ``~arch`` for initial testing. At this + point, packages can not declare support for the implementation yet. + +2. The new Python target is added. It is initially stable-masked, + so only ``~arch`` users can use it. At this point, packages start + being tested against the new target and its support starts being + declared in ``PYTHON_COMPAT``. + +3. When ready, the new interpreter is stabilized. The target is not yet + available for stable users, though. + +4. The stable-mask for the target is removed. For this to happen, + the inconsistencies in stable graph need to be addressed first + via stabilizing newer versions of packages. + +5. Over time, developers are repeatedly asked to push testing packages + for the new target forward and stabilize new versions supporting it. + Eventually, the final push for updates happens and packages + not supporting the new target start being removed. + +6. If applicable, the new target becomes the default. The developers + are required to test new packages against it. The support for old + target is slowly being discontinued. + +7. Eventually, the target becomes replaced by the next one. When it + nears end of life, the final packages requiring it are masked for + removal and the target flags are disabled. + +8. The compatibility declarations are cleaned up from ``PYTHON_COMPAT`` + and obsolete ebuild and eclass code is cleaned up. + +9. Finally, the interpreter is moved to `python repository`_ where it + lives for as long as it builds. + +For example, Python 3.9 is at stage 1 at the time of writing. It is +still in alpha stage, and upstream has not finalized its feature set, +therefore it is too early to declare package support for Python 3.9 +and there are no target flags. + +Python 3.8 is moving from stage 2 to stage 3 — it is being stabilized +by arch teams at this very moment. When that's done, we will work +on unmasking the flag on stable systems and it will become our next +default target. + +Python 3.7 is moving from stage 5 to stage 6. The vast majority +of packages have been ported to it, and we have already announced +the switch date. + +When the switch happens, Python 3.6 will move from stage 6 to stage 7. +We are going to support it for quite some time still but as things +progress, we will eventually decide to remove it. + +Python 3.5 and 3.4 are at stage 9. They live in the Python repository +but have no targets. You can still use them e.g. inside a virtualenv +to test your own software. + +Python 2.7 is currently somewhere between stages 6 and 7. It is still +enabled by default for backwards compatibility but we are aggressively +removing it. + +PyPy3 has recently reached stage 3. It is not clear if we are going +to pursue enabling the target on stable system though. PyPy2.7 is +at stage 8, as the targets were removed already and it is kept +as a dependency and testing target. + + +Notes specific to Python interpreters +===================================== +CPython patchsets +----------------- +Gentoo is maintaining patchsets for all CPython versions. These include +some non-upstreamable Gentoo patches and upstream backports. While it +is considered acceptable to add a new patch (e.g. a security bug fix) +to ``files/`` directory, it should be eventually moved into +the respective patchset. + +When adding a new version, it is fine to use an old patchset if it +applies cleanly. If it does not, you should regenerate the patchset +for new version. + +The origin for Gentoo patches are the ``gentoo-*`` tags the `Gentoo fork +of CPython repository`_. The recommended workflow is to clone +the upstream repository, then add Gentoo fork as a remote, e.g.:: + + git clone https://github.com/python/cpython + cd cpython + git remote add gentoo git@git.gentoo.org:fork/cpython.git + git fetch --tags gentoo + +In order to rebase the patchset, check out the tag corresponding +to the previous patchset version and rebase it against the upstream +release tag:: + + git checkout gentoo-3.7.4 + git rebase v3.7.6 + +You may also add additional changes via ``git cherry-pick``. Once +the new patches are ready, create the tarball and upload it, then +create the tag and push it:: + + mkdir python-gentoo-patches-3.7.6 + cd python-gentoo-patches-3.7.6 + git format-patch v3.7.6 + cd .. + tar -cf python-gentoo-patches-3.7.6.tar python-gentoo-patches-3.7.6 + xz -9 python-gentoo-patches-3.7.6.tar + scp python-gentoo-patches-3.7.6.tar.xz ... + git tag gentoo-3.7.6 + git push --tags gentoo + + +PyPy +---- +Due to high resource requirements and long build time, PyPy on Gentoo +is provided both in source and precompiled form. This creates a bit +unusual ebuild structure: + +- ``dev-python/pypy-exe`` provides the PyPy executable and generated + files built from source, +- ``dev-python/pypy-exe-bin`` does the same in precompiled binary form, +- ``dev-python/pypy`` combines the above with the common files. This + is the package that runs tests and satisfies the PyPy target. + +Matching ``dev-python/pypy3*`` exist for PyPy3. + +When bumping PyPy, ``pypy-exe`` needs to be updated first. Then it +should be used to build a binary package and bump ``pypy-exe-bin``. +Technically, ``pypy`` can be bumped after ``pypy-exe`` and used to test +it but it should not be pushed before ``pypy-exe-bin`` is ready, as it +would force all users to switch to source form implicitly. + +The binary packages are built using Docker_ nowadays, using +binpkg-docker_ scripts. To produce them, create a ``local.diff`` +containing changes related to PyPy bump and run ``amd64-pypy`` +(and/or ``amd64-pypy3``) and ``x86-pypy`` (and/or ``x86-pypy3``) make +targets:: + + git clone https://github.com/mgorny/binpkg-docker + cd binpkg-docker + (cd ~/git/gentoo && git diff origin) > local.diff + make amd64-pypy amd64-pypy3 x86-pypy x86-pypy3 + +The resulting binary packages will be placed in your home directory, +in ``~/binpkg/${arch}/pypy``. Upload them and use them to bump +``pypy-exe-bin``. + + +Adding a new Python implementation +================================== +Eclass and profile changes +-------------------------- +When adding a new Python target, please remember to perform all +the following tasks: + +- add the new target flags to ``profiles/desc/python_targets.desc`` + and ``python_single_target.desc``. + +- force the new implementation on ``dev-lang/python-exec`` + via ``profiles/base/package.use.force``. + +- mask the new target flags on stable profiles + via ``profiles/base/use.stable.mask``. + +- add the new target to ``_PYTHON_ALL_IMPLS`` and update the patterns + in ``_python_impl_supported()`` in ``python-utils-r1.eclass``. + +- add the new implementation to the list + in ``app-portage/gpyutils/files/implementations.txt``. + + +Porting initial packages +------------------------ +The initial porting is quite hard due to a number of circular +dependencies. To ease the process, some of the high profile packages +are ported first with tests and their dependencies disabled for the new +implementation, e.g.: + +.. code-block:: bash + :emphasize-lines: 3,15,20-21 + + BDEPEND=" + test? ( + $(python_gen_cond_dep ' + dev-python/jaraco-envs[${PYTHON_USEDEP}] + >=dev-python/jaraco-path-3.2.0[${PYTHON_USEDEP}] + dev-python/mock[${PYTHON_USEDEP}] + dev-python/pip[${PYTHON_USEDEP}] + dev-python/sphinx[${PYTHON_USEDEP}] + dev-python/pytest[${PYTHON_USEDEP}] + dev-python/pytest-fixture-config[${PYTHON_USEDEP}] + dev-python/pytest-virtualenv[${PYTHON_USEDEP}] + dev-python/pytest-xdist[${PYTHON_USEDEP}] + >=dev-python/virtualenv-20[${PYTHON_USEDEP}] + dev-python/wheel[${PYTHON_USEDEP}] + ' python3_{7..10} pypy3) + ) + " + + python_test() { + # keep in sync with python_gen_cond_dep above! + has "${EPYTHON}" python3.{7..10} pypy3 || continue + + distutils_install_for_testing + HOME="${PWD}" epytest setuptools + } + + +The recommended process is to, in order: + +1. Port ``dev-python/setuptools`` and ``dev-python/certifi`` with tests + disabled. Test it via ``tox`` in a git checkout. + +2. Port ``dev-python/nose`` with additional dependencies disabled + (tests skip missing dependencies gracefully). + +3. Port ``dev-python/pytest`` and its runtime dependencies with pytest's + tests disabled (but tests of the dependencies enabled). This should + yield around 20 packages. Test it via ``tox`` in a git checkout. + +4. Port ``dev-python/urllib3`` and its runtime dependencies with + urllib3's tests disabled (but tests of the dependencies enabled). + This should yield another 20 packages. Test it from a git checkout + (it uses nox, so you may want to write ``tox.ini`` yourself). + +Once these packages are done, you should be able to work towards +reenabling tests in them via porting their (deep) dependencies in groups +of around 10 packages without cyclic dependencies extending out +of the group. + + +Python build system bootstrap +============================= +Python build systems are often facing the bootstrap problem — that is, +the build system itself has some dependencies, while these dependencies +require the same build system to build. The common upstream way +(actually recommended in `PEP 517 build requirements`_ section) is +to bundle the necessary dependencies as part of the build system. +However, this goes against best Gentoo practices. + +The current Gentoo practice for bootstrap with dependency unbundling +is to: + +1. Install the dependencies of flit_core and the eclass PEP 517 logic + (installer, tomli) manually using ``python_domodule``. + +2. Install flit_core using the standalone PEP 517 backend. + +3. Install the dependencies of setuptools using flit (writing trivial + ``pyproject.toml`` within the ebuild if necessary). + +4. Install setuptools using the standalone PEP 517 backend. + +5. The dependencies of other build systems can be installed using + flit, setuptools or other previously unbundled build systems. + +Note that for the purpose of bootstrap only obligatory baseline +dependencies are considered significant. Non-obligatory dependencies +(i.e. ones that can be missing during the bootstrap process) can be +placed in ``PDEPEND``. Test suite dependencies can include cycles +with the package itself — running tests is not considered obligatory +during the bootstrap process. + +flit_core has been chosen as the base build system for unbundling since +it has the fewest external dependencies (i.e. only depends on tomli). +Its author indicates in the `flit_core vendoring README`_ that no other +dependencies will be added or vendored into flit_core. + + +.. _python repository: https://gitweb.gentoo.org/proj/python.git/ +.. _Gentoo fork of CPython repository: + https://gitweb.gentoo.org/fork/cpython.git/ +.. _Docker: https://www.docker.com/ +.. _binpkg-docker: https://github.com/mgorny/binpkg-docker +.. _PEP 517 build requirements: + https://www.python.org/dev/peps/pep-0517/#build-requirements +.. _flit_core vendoring README: + https://github.com/pypa/flit/blob/main/flit_core/flit_core/vendor/README diff --git a/guide/_sources/interpreter.rst.txt b/guide/_sources/interpreter.rst.txt new file mode 100644 index 0000000..81111a3 --- /dev/null +++ b/guide/_sources/interpreter.rst.txt @@ -0,0 +1,210 @@ +=================== +Python interpreters +=================== + +Versions of Python +================== +By a *version of Python* we usually mean the variant of Python language +and standard library interface as used by a specific version +of CPython_, the reference implementation of Python. + +Python versions are determined from the two first version components. +The major version is incremented when major incompatible changes are +introduced in the language, as was the case in Python 3. Along with +minor version changes, the new releases introduce new features +and remove deprecated APIs. The Python documentation generally +indicates when a particular API was added or deprecated, and when it +is planned to be removed. + +Practically speaking, this means that a program written purely +for Python 2 is unlikely to work on Python 3, and requires major changes +to achieve compatibility. On the other hand, a program written for +Python 3.7 is very likely to work with Python 3.8, and reasonably likely +to support Python 3.6 as well. If that is not the case, minor changes +are usually sufficient to fix that. + +For example, Python 3.7 introduced a new `importlib.resources`_ module. +If your program uses it, it will not work on Python 3.6 without +a backwards compatibility code. + +Python 3.8 removed the deprecated `platform.linux_distribution()`_ +function. If your program used it, it will not work on Python 3.8 +without changes. However, it was deprecated since Python 3.5, so if you +were targetting 3.7, you should not have been using it in the first +place. + +Gentoo supports building packages against Python 2.7 and a shifting +window of 3-4 versions of Python 3. They are provided as slots +of ``dev-lang/python``. + + +Alternative Python implementations +================================== +CPython is the reference and most commonly used Python implementation. +However, there are other interpreters that aim to maintain reasonable +compatibility with it. + +PyPy_ is an implementation of Python built using in-house RPython +language, using a Just-in-Time compiler to achieve better performance +(generally in long-running programs running a lot of Python code). +It maintains quite good compatibility with CPython, except when programs +rely on its implementation details or GC behavior. + +PyPy upstream provides PyPy variants compatible with Python 2.7 +and one version of Python 3. Gentoo supports building packages against +PyPy3. PyPy2.7 is provided as ``dev-python/pypy``, while PyPy3 is +provided as ``dev-python/pypy3``. + +Jython_ is an implementation of Python written in Java. Besides being +a stand-alone Python interpreter, it supports bidirectional interaction +between Python and Java libraries. + +Jython development is very slow paced, and it is currently bound +to Python 2.7. Gentoo does not support building packages for Jython +anymore. The interpreter is still provided as ``dev-java/jython``. + +IronPython_ is an implementation of Python for the .NET framework. +Alike Jython, it supports bidirectional interaction between Python +and .NET Framework. It is currently bound to Python 2.7. It is not +packaged in Gentoo. + +Brython_ is an implementation of Python 3 for client-side web +programming (in JavaScript). It provides a subset of Python 3 standard +library combined with access to DOM objects. It is packaged in Gentoo +as ``dev-python/brython``. + +MicroPython_ is an implementation of Python 3 aimed for microcontrollers +and embedded environments. It aims to maintain some compatibility +with CPython while providing stripped down standard library +and additional modules to interface with hardware. It is packaged +as ``dev-lang/micropython``. + +Tauthon_ is a fork of Python 2.7 that aims to backport new language +features and standard library modules while preserving backwards +compatibility with existing code. It is not packaged in Gentoo. + + +Support for multiple implementations +==================================== +The support for simultaneously using multiple Python implementations +is implemented primarily through USE flags. The packages installing +or using Python files define either ``PYTHON_TARGETS`` +or ``PYTHON_SINGLE_TARGET`` flags that permit user to choose which +implementations are used. + +Modules and extensions are installed separately for each interpreter, +in its specific site-packages directory. This means that a package +can run using a specific target correctly only if all its dependencies +were also installed for the same implementation. This is enforced +via USE dependencies. + +Additionally, ``dev-lang/python-exec`` provides a mechanism for +installing multiple variants of each Python script simultaneously. This +is necessary to support scripts that differ between Python versions +(particularly between Python 2 and Python 3) but it is also used +to prevent scripts from being called via unsupported interpreter +(i.e. one that does not have its accompanying modules or dependencies +installed). + +This also implies that all installed Python scripts must have their +shebangs adjusted to use a specific Python interpreter (not ``python`` +nor ``python3`` but e.g. ``python3.7``), and all other executables must +also be modified to call specific version of Python directly. + + +Backports +========= +A common method of improving compatibility with older versions of Python +is to backport new standard library modules or features. Packages doing +that are generally called *backports*. + +Ideally, backports copy the code from the standard library with minimal +changes, and provide a matching API. In some cases, new versions +of backports are released as the standard library changes, and their +usability extends from providing a missing module to extending older +version of the module. For example, the ``dev-python/funcsigs`` package +originally backported function signatures from Python 3.3 to older +versions, and afterwards was updated to backport new features from +Python 3.6, becoming useful to versions 3.3 through 3.5. + +Sometimes, the opposite happens. ``dev-python/mock`` started +as a stand-alone package, and was integrated into the standard library +as unittest.mock_ later on. Afterwards, the external package became +a backport of the standard library module. + +In some cases backports effectively replace external packages. Once +lzma_ module has been added to the standard library, its backport +``dev-python/backports-lzma`` has effectively replaced the competing +LZMA packages. + +Individual backports differ by the level of compatibility with +the standard library provided, and therefore on the amount of additional +code needed in your program. The exact kind of dependencies used +depends on that. + +``dev-python/ipaddress`` is a drop-in backport of the ipaddress_ module +from Python 3.3. It is using the same module name, so a code written +to use this module will work out-of-the-box on Python 2.7 if the package +is installed. As a side note, since Python always prefers built-in +modules over external packages, there is no point in enabling Python 3 +in this package as the installed module would never be used. +Appropriately, you should depend on this package only for the Python +versions needing it. + +``dev-python/mock`` is a compatible backport of the unittest.mock_ +module. It can't use the same name as the standard library module, +therefore the packages need to use it conditionally, e.g.:: + + try: + from unittest.mock import Mock + except ImportError: # py<3.3 + from mock import Mock + +or:: + + import sys + if sys.hexversion >= 0x03030000: + from unittest.mock import Mock + else: + from mock import Mock + +However, the actual API remains compatible, so the programs do not need +more compatibility code than that. In some cases, upstreams fail (or +even refuse) to use the external ``mock`` package conditionally — +in that case, you either need to depend on this package unconditionally, +or patch it. + +``dev-python/trollius`` aimed to provide a backport of asyncio_ +for Python 2. Since the asyncio framework relies on new Python syntax, +the backport cannot be API compatible and requires using a different +syntax than native asyncio code. + + +.. _CPython: https://www.python.org/ + +.. _importlib.resources: + https://docs.python.org/3.7/library/importlib.html#module-importlib.resources + +.. _platform.linux_distribution(): + https://docs.python.org/3.7/library/platform.html#platform.linux_distribution + +.. _PyPy: https://www.pypy.org/ + +.. _Jython: https://www.jython.org/ + +.. _IronPython: https://ironpython.net/ + +.. _Brython: https://www.brython.info/ + +.. _MicroPython: https://micropython.org/ + +.. _Tauthon: https://github.com/naftaliharris/tauthon + +.. _unittest.mock: + https://docs.python.org/3.3/library/unittest.mock.html + +.. _lzma: https://docs.python.org/3.3/library/lzma.html + +.. _ipaddress: https://docs.python.org/3.3/library/ipaddress.html + +.. _asyncio: https://docs.python.org/3.4/library/asyncio.html diff --git a/guide/_sources/migration.rst.txt b/guide/_sources/migration.rst.txt new file mode 100644 index 0000000..414e8ef --- /dev/null +++ b/guide/_sources/migration.rst.txt @@ -0,0 +1,206 @@ +================ +Migration guides +================ + + +.. index:: PYTHON_MULTI_USEDEP + +Migrating from old PYTHON_USEDEP syntax in python-single-r1 +=========================================================== +Prior to February 2020, ``python-single-r1`` used to provide a single +``PYTHON_USEDEP`` variable alike the two other eclasses. However, +getting it to work correctly both on single-impl and multi-impl packages +required a gross hack. + +The current eclass API requires using ``python_gen_cond_dep`` function +to generate multi-impl deps instead, with ``PYTHON_USEDEP`` serving +as a placeholder. Single-impl deps can be expressed with +``PYTHON_SINGLE_USEDEP`` that can be used either as placeholder, +or directly as a variable. + +During a transitional period, ``PYTHON_USEDEP`` was banned entirely +and ``PYTHON_MULTI_USEDEP`` was used instead. As of EAPI 8, +the opposite is true — ``PYTHON_USEDEP`` is to be used, +and ``PYTHON_MULTI_USEDEP`` was removed. + +The recommended rule of thumb for migrating old ebuilds is to: + +1. Replace all instances of ``${PYTHON_USEDEP}`` for simple-impl deps + with ``${PYTHON_SINGLE_USEDEP}``. If you don't know the type + of given dep, dependency check (repoman, pkgcheck) will tell you + if you chose wrong. + +2. Wrap the dependencies using ``${PYTHON_USEDEP}`` in a single + ``python_gen_cond_dep`` block (reordering may be desirable). + +3. Run ``pkgcheck scan`` or ``repoman full``. If you get syntax errors, + you probably missed ``python_gen_cond_dep`` or did not escape + the ``$`` in placeholder properly. If you get unmatched dependency, + you probably got single-impl vs. multi-impl wrong. + +This way, you can generally convert ebuilds using trial-and-error +method. + + +.. index:: EAPI 8 + +Migrating from EAPI 7 to EAPI 8 +=============================== +EAPI 8 has banned everything that's been deprecated in EAPI 7, as well +as some other obsolete stuff. The following table lists all banned +things along with their suggested replacements. + + +-------------------------------+------------------------------------+ + | Deprecated thing | Replacement | + +===============================+====================================+ + | Private eclass API | + +-------------------------------+------------------------------------+ + | python_export | python_setup / getters | + +-------------------------------+------------------------------------+ + | python_wrapper_setup | python_setup | + +-------------------------------+------------------------------------+ + | Obsolete API | + +-------------------------------+------------------------------------+ + | distutils_install_for_testing | no argument (``--via-root``) | + | ``--via-home`` | or ``--via-venv`` | + +-------------------------------+------------------------------------+ + | python_gen_usedep | python_gen_cond_dep | + +-------------------------------+------------------------------------+ + | PYTHON_MULTI_USEDEP | PYTHON_USEDEP | + +-------------------------------+------------------------------------+ + | mydistutilsargs rename | + +-------------------------------+------------------------------------+ + | mydistutilsargs | DISTUTILS_ARGS | + +-------------------------------+------------------------------------+ + | Post-Python 2 cleanup | + +-------------------------------+------------------------------------+ + | python_gen* -2 / python2 | remove entirely | + | / pypy | | + +-------------------------------+------------------------------------+ + | python_gen* -3 | make unconditional | + +-------------------------------+------------------------------------+ + | python_is_python3 | always assume true | + +-------------------------------+------------------------------------+ + +The changes can be split roughly into four groups: ban of now-private +eclass API, ban of obsolete API functions, mydistutilsargs rename +and bans related to post-Python 2 cleanup. + +The private eclass API part involves ``python_export`` +and ``python_wrapper_setup``. Both were deprecated in March 2020, +and they were never covered in this guide. The former was historically +used to get information about the Python interpreter (either the current +``${EPYTHON}`` or an arbitrary choice), the latter to create the wrapper +directory containing ``python`` and other executables. + +When the functions were used to establish a Python build environment, +the replacement for both is a single ``python_setup`` call. When +``python_export`` was used to grab additional details about the Python +interpreter, the various ``python_get*`` functions should be used +instead. + +.. code-block:: bash + + src_configure() { + # ... + + # OLD: + local PYTHON_INCLUDEDIR PYTHON_LIBPATH + python_export PYTHON_INCLUDEDIR PYTHON_LIBPATH + mycmakeargs+=( + -DPython3_INCLUDE_DIR="${PYTHON_INCLUDEDIR}" + -DPython3_LIBRARY="${PYTHON_LIBPATH}" + ) + + # NEW: + mycmakeargs+=( + -DPython3_INCLUDE_DIR="$(python_get_includedir)" + -DPython3_LIBRARY="$(python_get_library_path)" + ) + } + +The second group involves sundry API that were deprecated earlier. +These are: + +1. ``distutils_install_for_testing --via-home`` layout that stopped + working correctly at some point. The default ``--via-root`` should + work most of the time, and ``-via-venv`` replace the remaining cases + for the removed layout. + +2. ``python_gen_usedep`` function that was historically used to generate + partial USE dependencies, and was generally combined with + ``REQUIRED_USE`` to force specific (usually old) Python interpreters + for specific features. This was really ugly. Nowadays, you should + really use ``python_gen_cond_dep`` instead. + +3. ``PYTHON_MULTI_USEDEP`` placeholder that was temporarily used + in python-single-r1 ebuilds. ``PYTHON_USEDEP`` is equivalent now. + +The third group is a sole rename of ``mydistutilsargs`` variable. +Since you usually need to pass the same arguments in all phase +functions, this variable was not really used in local scope. It has +been renamed to uppercase ``DISTUTILS_ARGS`` to follow the common +pattern for global scope variables. + +Finally, the fourth group involves banning some of the features that +were specifically used in order to support distinguish between Python 2 +and Python 3. This is meant to force cleaning up old cruft from +ebuilds. It comes in three parts: + +1. Banning arguments to ``python_gen*`` that reference Python 2 + (e.g. ``-2``, ``python2*``, ``python2_7``, ``pypy``). Since Python 2 + is no longer supported in the relevant code paths, the relevant calls + should just be removed. + +2. Banning the ``-3`` short-hand to ``python_gen*``. Since all + supported interpreters are compatible with Python 3 now, the relevant + code should be made unconditional. Note that ``python3*`` is still + useful, as it distinguishes CPython from PyPy3. + +3. Banning the ``python_is_python3`` function. Since the removal + of Python 2 support, it always evaluated to true. + +All the aforementioned replacements are available in all EAPIs. + + +Migrating to PEP 517 builds +=========================== +As of January 2022, the ``distutils-r1`` can use PEP 517 build backends +instead of calling setuptools directly. The new mode is particularly +useful for: + +- packages using flit and poetry, as a better replacement for + the deprecated ``dev-python/pyproject2setuppy`` hack + +- packages using other PEP 517 build systems (such as pdm) that are not + supported in legacy mode at all + +- packages using setuptools without ``setup.py`` + +- packages using plain distutils, as the mode handles the switch from + deprecated stdlib distutils to the version vendored in setuptools + safely + +The PEP 517 mode provides the test phase with venv-style installed +package tree (alike ``distutils_install_for_testing --via-venv``) +that should make testing more streamlined. + +Unfortunately, the new mode can cause issues with customized distutils +and setuptools build systems. It is important to verify the installed +file list after the migration. Packages that require custom configure +phases or passing arguments are not supported at the moment. + +For simple packages, the migration consists of: + +1. Adding ``DISTUTILS_USE_PEP517`` above the inherit line. The value + indicates the build system used, e.g. ``flit``, ``poetry``, + ``setuptools`` (used also for distutils). + +2. Removing ``DISTUTILS_USE_SETUPTOOLS``. If the previous value was + ``rdepend`` (and indeed a runtime dependency is required), then + ``dev-python/setuptools`` needs to be explicitly added to + ``RDEPEND``. + +3. Removing ``distutils_install_for_testing`` and/or ``--install`` + option to ``distutils_enable_tests``. This should no longer be + necessary and tests should work out of the box. diff --git a/guide/_sources/multi.rst.txt b/guide/_sources/multi.rst.txt new file mode 100644 index 0000000..6e54595 --- /dev/null +++ b/guide/_sources/multi.rst.txt @@ -0,0 +1,379 @@ +=============================== +python-r1 — multi-impl packages +=============================== + +.. highlight:: bash + +The ``python-r1`` eclass is used to install multi-impl packages. +It is considered an expert eclass — when possible, you should prefer +using ``python-single-r1`` instead. For packages using distutils +or a similar Python build system, ``distutils-r1`` eclass should be used +instead. + +Eclass reference: `python-r1.eclass(5)`_ + + +.. index:: python_foreach_impl + +Manual install +============== +The simplest case of multi-impl package is a package without a specific +build system. The modules need to be installed manually here, +and ``python_foreach_impl`` function is used to repeat the install step +for all enabled implementations. + +For simple use cases, the install command can be inlined: + +.. code-block:: bash + :emphasize-lines: 6,7,17,19,23 + + # Copyright 1999-2020 Gentoo Foundation + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 ) + inherit python-r1 + + DESCRIPTION="MySQL abstraction layer for python" + HOMEPAGE="http://software.fionet.com/pSQL/" + SRC_URI="http://software.fionet.com/pSQL/release/${P}.tar.gz" + + SLOT="0" + LICENSE="GPL-2" + KEYWORDS="~amd64 ~x86" + IUSE="" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + RDEPEND="${PYTHON_DEPS}" + DEPEND="${RDEPEND}" + + src_install() { + python_foreach_impl python_domodule pSQL.py + } + +While ``python_foreach_impl`` can be repeated multiple times, it is +generally better to declare a function when multiple install commands +need to be executed: + +.. code-block:: bash + :emphasize-lines: 22-25,28 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 ) + inherit python-r1 + + DESCRIPTION="Proxy cache for Gentoo packages" + HOMEPAGE="https://sourceforge.net/projects/http-replicator" + SRC_URI="mirror://sourceforge/${PN}/${P}.tgz" + + LICENSE="GPL-2" + SLOT="0" + KEYWORDS="~alpha amd64 hppa ppc ~sparc x86" + IUSE="" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + RDEPEND="${PYTHON_DEPS}" + DEPEND="${RDEPEND}" + + python_install() { + python_doscript http-replicator + python_domodule *.py + } + + src_install() { + python_foreach_impl python_install + } + + +.. index:: PYTHON_USEDEP; python-r1 + +Dependencies +============ +When depending on other Python packages, USE dependencies need to be +declared in order to ensure that the dependencies would be built against +all the Python implementations enabled for the package. This is easily +done via appending the USE dependency string from ``${PYTHON_USEDEP}`` +to the dependencies:: + + RDEPEND="${PYTHON_DEPS} + sys-apps/portage[${PYTHON_USEDEP}] + " + DEPEND="${RDEPEND}" + + +.. index:: run_in_build_dir + +Pure Python autotools package +============================= +Another typical case for this eclass is to handle a pure Python package +with a non-standard build system. In this case, it is generally +necessary to call phase functions via ``python_foreach_impl``. Whenever +possible, out-of-source builds are recommended (i.e. installing to +separate directories from a single source directory). + + +.. code-block:: bash + :emphasize-lines: 32,36,40,44 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI="6" + PYTHON_COMPAT=( python3_6 ) + + inherit autotools python-r1 + + DESCRIPTION="Python wrapper for libcangjie" + HOMEPAGE="http://cangjians.github.io/" + SRC_URI="https://github.com/Cangjians/py${PN}/releases/download/v${PV}/${P#py}.tar.xz" + + LICENSE="LGPL-3+" + SLOT="0" + KEYWORDS="~amd64 ~x86" + IUSE="" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + RDEPEND="${PYTHON_DEPS} + app-i18n/libcangjie" + DEPEND="${RDEPEND} + dev-python/cython[${PYTHON_USEDEP}] + virtual/pkgconfig" + + src_prepare() { + default + eautoreconf + } + + src_configure() { + local ECONF_SOURCE=${S} + python_foreach_impl run_in_build_dir default + } + + src_compile() { + python_foreach_impl run_in_build_dir default + } + + src_test() { + python_foreach_impl run_in_build_dir default + } + + src_install() { + python_foreach_impl run_in_build_dir default + einstalldocs + find "${D}" -name '*.la' -delete || die + } + +Note the use of ``run_in_build_dir`` helper from ``multibuild`` eclass +(direct inherit is unnecessary here, as it is considered implicit part +of ``python-r1`` API). It changes the directory to ``BUILD_DIR`` (which +is set by ``python_foreach_impl`` to a unique directory for each +implementation) and runs the specified command there. In this case, +the ebuild performs autotools out-of-source build in a dedicated +directory for every interpreter enabled. + +Also note that the in-build-dir call to ``default`` does not install +documentation from source directory, hence the additional +``einstalldocs`` call. Libtool-based packages install ``.la`` files +that are unnecessary for Python extensions, hence they are removed +afterwards. + +If the package in question does not support out-of-source builds +(e.g. due to a buggy build system), ``python_copy_sources`` function +can be used to duplicate the package's sources in build directories +for each implementation. The same ebuild easily can be changed +to do that: + +.. code-block:: bash + :emphasize-lines: 28,32,36,40,44 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI="6" + PYTHON_COMPAT=( python3_6 ) + + inherit autotools python-r1 + + DESCRIPTION="Python wrapper for libcangjie" + HOMEPAGE="http://cangjians.github.io/" + SRC_URI="https://github.com/Cangjians/py${PN}/releases/download/v${PV}/${P#py}.tar.xz" + + LICENSE="LGPL-3+" + SLOT="0" + KEYWORDS="~amd64 ~x86" + IUSE="" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + RDEPEND="${PYTHON_DEPS} + app-i18n/libcangjie" + DEPEND="${RDEPEND} + dev-python/cython[${PYTHON_USEDEP}] + virtual/pkgconfig" + + src_prepare() { + default + eautoreconf + python_copy_sources + } + + src_configure() { + python_foreach_impl run_in_build_dir default + } + + src_compile() { + python_foreach_impl run_in_build_dir default + } + + src_test() { + python_foreach_impl run_in_build_dir default + } + + src_install() { + python_foreach_impl run_in_build_dir default + einstalldocs + find "${D}" -name '*.la' -delete || die + } + +Note that besides adding ``python_copy_sources`` call, ``ECONF_SOURCE`` +has been removed in order to disable out-of-source builds. + + +Conditional Python use +====================== +When the package installs Python components conditionally to a USE flag, +the respective USE conditional needs to be consistently used in metadata +variables and in ``python_foreach_impl`` calls. + +.. code-block:: bash + :emphasize-lines: 15,16,20-22,42-48 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + PYTHON_COMPAT=( python2_7 ) + + inherit gnome2 python-r1 + + DESCRIPTION="Canvas widget for GTK+ using the cairo 2D library for drawing" + HOMEPAGE="https://wiki.gnome.org/GooCanvas" + + LICENSE="LGPL-2" + SLOT="2.0" + KEYWORDS="~alpha amd64 ia64 ppc ppc64 sparc x86" + IUSE="python" + REQUIRED_USE="python? ( ${PYTHON_REQUIRED_USE} )" + + # python only enables python specific binding override + RDEPEND=" + python? ( + ${PYTHON_DEPS} + >=dev-python/pygobject-2.90.4:3[${PYTHON_USEDEP}] ) + " + DEPEND="${RDEPEND}" + + src_prepare() { + # Python bindings are built/installed manually. + sed -e "/SUBDIRS = python/d" -i bindings/Makefile.am \ + bindings/Makefile.in || die + + gnome2_src_prepare + } + + src_configure() { + gnome2_src_configure \ + --disable-python + } + + src_install() { + gnome2_src_install + + if use python; then + sub_install() { + python_moduleinto $(python -c "import gi;print gi._overridesdir") + python_domodule bindings/python/GooCanvas.py + } + python_foreach_impl sub_install + fi + } + +Note that in many cases, you will end up having to disable upstream +rules for installing Python files as they are suitable only for +single-impl installs. + + +.. index:: python_setup; for python-r1 + +Additional build-time Python use +================================ +Some packages additionally require Python at build time, independently +of Python components installed (i.e. outside ``python_foreach_impl``). +The eclass provides extensive API for this purpose but for now we'll +focus on the simplest case where the global code does not have any +dependencies or they are a subset of dependencies declared already. + +In this case, it is sufficient to call ``python_setup`` before +the routine requiring Python. It will choose the most preferred +of enabled implementations, and set the global environment for it. Note +that it is entirely normal that the same environment will be set inside +``python_foreach_impl`` afterwards. + +.. code-block:: bash + :linenos: + :emphasize-lines: 17,18,20,21,24,28-34,38-40 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI="7" + + PYTHON_COMPAT=( python{3_6,3_7} ) + PYTHON_REQ_USE="ncurses,readline" + inherit python-r1 + + DESCRIPTION="QEMU + Kernel-based Virtual Machine userland tools" + HOMEPAGE="http://www.qemu.org http://www.linux-kvm.org" + SRC_URI="http://wiki.qemu-project.org/download/${P}.tar.xz" + + LICENSE="GPL-2 LGPL-2 BSD-2" + SLOT="0" + KEYWORDS="amd64 ~arm64 ~ppc ~ppc64 x86" + IUSE="python" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + BDEPEND="${PYTHON_DEPS}" + RDEPEND="python? ( ${PYTHON_DEPS} )" + + src_configure() { + python_setup + ./configure || die + } + + qemu_python_install() { + python_domodule "${S}/python/qemu" + + python_doscript "${S}/scripts/kvm/vmxcap" + python_doscript "${S}/scripts/qmp/qmp-shell" + python_doscript "${S}/scripts/qmp/qemu-ga-client" + } + + src_install() { + default + if use python; then + python_foreach_impl qemu_python_install + fi + } + +Note that the parts affecting installation of runtime components +(``RDEPEND``, ``python_foreach_impl``) are made conditional to the USE +flag, while parts affecting build time (``REQUIRED_USE``, ``BDEPEND``, +``python_setup``) are unconditional. + + +.. _python-r1.eclass(5): + https://devmanual.gentoo.org/eclass-reference/python-r1.eclass/index.html diff --git a/guide/_sources/package-maintenance.rst.txt b/guide/_sources/package-maintenance.rst.txt new file mode 100644 index 0000000..512c477 --- /dev/null +++ b/guide/_sources/package-maintenance.rst.txt @@ -0,0 +1,81 @@ +========================== +Python package maintenance +========================== + +Support for Python 2 +==================== +Since Python 2.7 reached EOL, Gentoo is currently phasing out support +for Python 2. Unless your package or its reverse dependencies really +need it, you should omit it from ``PYTHON_COMPAT``. If you're adding +a new package and it does not support Python 3, do not add it. + +Many upstreams are removing Python 2 support from new releases of their +software. We remove it proactively whenever reverse dependencies permit +in order to anticipate this and avoid having to deal with lots +of reverse dependencies afterwards. + +Packages that do not support Python 3 and are unlikely to start +supporting it soon are being slowly removed. + + +Which implementations to test new packages for? +=============================================== +The absolute minimum set of targets are the current default targets +found in ``profiles/base/make.defaults``. However, developers +are strongly encouraged to test at least the next Python 3 version +in order to ease future transition, and preferably all future versions. + +Marking for PyPy3 is optional. At this moment, we do not aim for wide +coverage of PyPy3 support. + + +Adding new Python implementations to existing packages +====================================================== +New Python implementations can generally be added to existing packages +without a revision bump. This is because the new dependencies are added +conditionally to new USE flags. Since the existing users can not have +the new flags enabled, the dependencies do not need to be proactively +added to existing installations. + +This usually applies to stable packages as well as new Python targets +are generally ``use.stable.mask``-ed. This means that stable users +will not be able to enable newly added flags and therefore the risk +of the change breaking stable systems is minimal. + + +Which packages can be (co-)maintained by the Python project? +============================================================ +A large part of the Python ecosystem is fairly consistent, making it +feasible for (co-)maintenance by the Gentoo Python team. + +As a rule of thumb, Python team is ready to maintain packages specific +to the Python ecosystem and useful for the general population of Python +programmers. This includes Python interpreters and tooling, packages +purely providing Python modules and extensions and utilities specific +to the Python language. + +However, the Python team has limited manpower, therefore it may reject +packages that have high maintenance requirements. As a rule, Python +team does not accept packages without working tests. + +If your package matches the above profile, feel free to ask a member +of the Python project whether they would like to (co-)maintain +the package. However, if you are not a member of the project, please +do not add us without asking first. + + +Porting packages to a new EAPI +============================== +When porting packages to a new EAPI, please take care not to port +the dependencies of Portage prematurely. This generally includes +``app-portage/gemato``, ``dev-python/setuptools`` and their recursive +dependencies. + +Ideally, these ebuilds carry an appropriate note above their EAPI line, +e.g.:: + + # please keep this ebuild at EAPI 7 -- sys-apps/portage dep + EAPI=7 + +This does not apply to test dependencies — they are not strictly +necessary to install a new Portage version. diff --git a/guide/_sources/porting.rst.txt b/guide/_sources/porting.rst.txt new file mode 100644 index 0000000..432d5a5 --- /dev/null +++ b/guide/_sources/porting.rst.txt @@ -0,0 +1,198 @@ +============ +Porting tips +============ + +.. highlight:: python + +This section highlights some of the known incompatible changes made +in Python that could break Python scripts and modules that used to work +in prior versions. The sections are split into retroactive changes made +to all Python releases, and information specific to every Python branch +(compared to the previous one). + +This guide is by no means considered complete. If you can think +of other problems you've hit while porting your packages, please let me +know and I will update it. + + +Retroactive changes +=================== + +bpo43882_: urlsplit now strips LF, CR and HT characters +------------------------------------------------------- +Changed in: 2.7.18_p9, 3.6.13_p3, 3.7.10_p3, 3.8.9_p2, 3.9.4_p1 + +Historically, various urllib.parse_ methods have passed special +characters such as LF, CR and HT through into the split URL components. +This could have resulted in various exploits if Python programs did not +validate the resulting components and used them verbatim. + +bpo43882_ attempted to address the issue by making urllib.parse_ strip +the three aforementioned characters from the output of its functions. +This fixed one class of potential issues but at the same time opened +another can of worms. For example, URL validators that used to check +for dangerous special characters in the split URL components stopped +working correctly. In the best case, the URL were now sanitized instead +of being rejected. In the worst, the original unparsed URL with +dangerous characters started being passed through. See e.g. `django +PR#14349`_ for an example of impact and a fix. + +Behavior before:: + + >>> urllib.parse.urlparse('https://example.com/bad\nurl') + ParseResult(scheme='https', netloc='example.com', path='/bad\nurl', params='', query='', fragment='') + +Behavior after:: + + >>> urllib.parse.urlparse('https://example.com/bad\nurl') + ParseResult(scheme='https', netloc='example.com', path='/badurl', params='', query='', fragment='') + + +.. _bpo43882: https://bugs.python.org/issue43882 +.. _urllib.parse: https://docs.python.org/3/library/urllib.parse.html +.. _django PR#14349: https://github.com/django/django/pull/14349 + + +Python 3.10 +=========== + +See also: `what's new in Python 3.10`_ + +.. _what's new in Python 3.10: + https://docs.python.org/3/whatsnew/3.10.html + + +configure: No package 'python-3.1' found +---------------------------------------- +automake prior to 1.16.3 wrongly recognized Python 3.10 as 3.1. +As a result, build with Python 3.10 fails: + +.. code-block:: console + + checking for python version... 3.1 + checking for python platform... linux + checking for python script directory... ${prefix}/lib/python3.10/site-packages + checking for python extension module directory... ${exec_prefix}/lib/python3.10/site-packages + checking for PYTHON... no + configure: error: Package requirements (python-3.1) were not met: + + No package 'python-3.1' found + + Consider adjusting the PKG_CONFIG_PATH environment variable if you + installed software in a non-standard prefix. + + Alternatively, you may set the environment variables PYTHON_CFLAGS + and PYTHON_LIBS to avoid the need to call pkg-config. + See the pkg-config man page for more details. + Error: Process completed with exit code 1. + +To resolve this in ebuild, you need to autoreconf with the Gentoo +distribution of automake:: + + inherit autotools + + # ... + + src_prepare() { + default + eautoreconf + } + +The upstream fix is to create new distfiles using automake-1.16.3+. + + +distutils.sysconfig deprecation +------------------------------- +Upstream intends to remove distutils by Python 3.12. Python 3.10 starts +throwing deprecation warnings for various distutils modules. +The distutils.sysconfig is usually easy to port. + +The following table summarizes replacements for common path getters. + + =================================== ================================== + distutils.sysconfig call sysconfig replacement + =================================== ================================== + ``get_python_inc(False)`` ``get_path("include")`` + ``get_python_inc(True)`` ``get_path("platinclude")`` + ``get_python_lib(False, False)`` ``get_path("purelib")`` + ``get_python_lib(True, False)`` ``get_path("platlib")`` + ``get_python_lib(False, True)`` ``get_path("stdlib")`` + ``get_python_lib(True, True)`` ``get_path("platstdlib")`` + =================================== ================================== + +For both functions, omitted parameters default to ``False``. There is +no trivial replacement for the variants with ``prefix`` argument. + + +Python 3.9 +========== + +See also: `what's new in Python 3.9`_ + +.. _what's new in Python 3.9: + https://docs.python.org/3/whatsnew/3.9.html + + +base64.encodestring / base64.decodestring removal +------------------------------------------------- +Python 3.9 removes the deprecated ``base64.encodestring()`` +and ``base64.decodestring()`` functions. While they were deprecated +since Python 3.1, many packages still use them today. + +The drop-in Python 3.1+ replacements are ``base64.encodebytes()`` +and ``base64.decodebytes()``. Note that contrary to the names, the old +functions were simply aliases to the byte variants in Python 3 +and *required* the arguments to be ``bytes`` anyway. + +If compatibility with Python 2 is still desired, then the byte variants +ought to be called on 3.1+ and string variants before that. The old +variants accept both byte and unicode strings on Python 2. + +Example compatibility import:: + + import sys + + if sys.version_info >= (3, 1): + from base64 import encodebytes as b64_encodebytes + else: + from base64 import encodestring as b64_encodebytes + +Note that the ``base64`` module also provides ``b64encode()`` +and ``b64decode()`` functions that were not renamed. ``b64decode()`` +can be used as a drop-in replacement for ``decodebytes()``. However, +``b64encode()`` does not insert newlines to split the output +like ``encodebytes()`` does, and instead returns a single line +of base64-encoded data for any length of output. + + +Python 3.8 +========== + +See also: `what's new in Python 3.8`_ + +.. _what's new in Python 3.8: + https://docs.python.org/3/whatsnew/3.8.html + + +python-config and pkg-config no longer list Python library by default +--------------------------------------------------------------------- +Until Python 3.7, the ``python-X.Y`` pkg-config file and python-config +tool listed the Python library. Starting with 3.8, this is no longer +the case. If you are building Python extensions, this is fine (they +are not supposed to link directly to libpython). + +If you are building programs that need to embed the Python interpreter, +new ``python-X.Y-embed`` pkg-config file and ``--embed`` parameter +are provided for the purpose. + +.. code-block:: console + + $ pkg-config --libs python-3.7 + -lpython3.7m + $ pkg-config --libs python-3.8 + + $ pkg-config --libs python-3.8-embed + -lpython3.8 + +To achieve backwards compatibility, you should query +``python-X.Y-embed`` first and fall back to ``python-X.Y``. diff --git a/guide/_sources/preface.rst.txt b/guide/_sources/preface.rst.txt new file mode 100644 index 0000000..8fb20c2 --- /dev/null +++ b/guide/_sources/preface.rst.txt @@ -0,0 +1,37 @@ +======= +Preface +======= + +Gentoo provides one of the best frameworks for providing Python support +in packages among operating systems. This includes support for +running multiple versions of Python (while most other distributions +avoid going beyond simultaneous support for Python 2 and one version +of Python 3), alternative implementations of Python, reliable tests, +deep QA checks. While we aim to keep things simple, this is not always +possible. + +At the same time, the available documentation is limited and not always +up-to-date. Both the `built-in eclass documentation`_ and `Python +project wiki page`_ provide bits of documentation but they are mostly +in reference form and not very suitable for beginners nor people who +do not actively follow the developments within the ecosystem. This +results in suboptimal ebuilds, improper dependencies, missing tests. + +This document aims to fill the gap by providing a good, complete, +by-topic (rather than reference-style) documentation for the ecosystem +in Gentoo and the relevant eclasses. Combined with examples, it should +help you write good ebuilds and solve common problems as simply +as possible. + +`Gentoo Python Guide sources`_ are available on GitHub. Suggestions +and improvements are welcome. + + +.. _built-in eclass documentation: + https://devmanual.gentoo.org/eclass-reference/index.html + +.. _Python project wiki page: + https://wiki.gentoo.org/wiki/Project:Python + +.. _Gentoo Python Guide sources: + https://github.com/mgorny/python-guide/ diff --git a/guide/_sources/pytest.rst.txt b/guide/_sources/pytest.rst.txt new file mode 100644 index 0000000..2f3e7e5 --- /dev/null +++ b/guide/_sources/pytest.rst.txt @@ -0,0 +1,309 @@ +============== +pytest recipes +============== + +.. highlight:: bash + +Skipping tests based on markers +=============================== +A few packages use `custom pytest markers`_ to indicate e.g. tests +requiring Internet access. These markers can be used to conveniently +disable whole test groups, e.g.:: + + python_test() { + epytest -m 'not network' dask + } + + +Skipping tests based on paths/names +=================================== +There are two primary methods of skipping tests based on path (and name) +in pytest: using ``--ignore`` and ``--deselect``. + +``--ignore`` causes pytest to entirely ignore a file or a directory +when collecting tests. This works only for skipping whole files but it +ignores missing dependencies and other failures occurring while +importing the test file. + +``--deselect`` causes pytest to skip the specific test or tests. It can +be also used to select individual tests or even parametrized variants +of tests. + +Both options can be combined to get tests to pass without having +to alter the test files. They are preferable over suggestions from +skipping problematic tests when tests are installed as part +of the package. They can also be easily applied conditionally to Python +interpreter. + +The modern versions of eclasses provide two control variables, +``EPYTEST_IGNORE`` and ``EPYTEST_DESELECT`` that can be used to list +test files or tests to be ignored or deselected respectively. These +variables can be used in global scope to avoid redefining +``python_test()``. However, combining them with additional conditions +requires using the local scope. + +:: + + python_test() { + local EPYTEST_IGNORE=( + # ignore whole file with missing dep + --ignore tests/test_client.py + ) + local EPYTEST_DESELECT=( + # deselect a single test + 'tests/utils/test_general.py::test_filename' + # deselect a parametrized test based on first param + 'tests/test_transport.py::test_transport_works[eventlet' + ) + [[ ${EPYTHON} == python3.6 ]] && EPYTEST_DESELECT+=( + # deselect a test for py3.6 only + 'tests/utils/test_contextvars.py::test_leaks[greenlet]' + ) + epytest + } + + +Avoiding the dependency on pytest-runner +======================================== +pytest-runner_ is a package providing ``pytest`` command to setuptools. +While it might be convenient upstream, there is no real reason to use +it in Gentoo packages. It has no real advantage over calling pytest +directly. + +Some packages declare the dependency on ``pytest-runner`` +in ``setup_requires``. As a result, the dependency is enforced whenever +``setup.py`` is being run, even if the user has no intention of running +tests. If this is the case, the dependency must be stripped. + +The recommended method of stripping it is to use sed:: + + python_prepare_all() { + sed -i -e '/pytest-runner/d' setup.py || die + distutils-r1_python_prepare_all + } + + +Using pytest-xdist to run tests in parallel +=========================================== +pytest-xdist_ is a plugin that makes it possible to run multiple tests +in parallel. This is especially useful for programs with large test +suites that take significant time to run single-threaded. + +Not all test suites support pytest-xdist. Particularly, it requires +that the tests are written not to collide one with another. + +Using pytest-xdist is recommended if the package in question supports it +(i.e. it does not cause semi-random test failures) and its test suite +takes significant time. When using pytest-xdist, please respect user's +make options for the job number, e.g.:: + + inherit multiprocessing + + python_test() { + epytest -n "$(makeopts_jobs "${MAKEOPTS}" "$(get_nproc)")" + } + +Please note that some upstream use pytest-xdist even if there is no real +gain from doing so. If the package's tests take a short time to finish, +please avoid the dependency and strip it if necessary. + + +Avoiding dependencies on other pytest plugins +============================================= +There is a number of pytest plugins that have little value to Gentoo +users. They include plugins for test coverage +(``dev-python/pytest-cov``), coding style (``dev-python/pytest-flake8``) +and more. Generally, packages should avoid using those plugins. + +In some cases, upstream packages only list them as dependencies +but do not use them automatically. In other cases, you will need +to strip options enabling them from ``pytest.ini`` or ``setup.cfg``. + +:: + + src_prepare() { + sed -i -e 's:--cov=wheel::' setup.cfg || die + distutils-r1_src_prepare + } + + +Explicitly disabling automatic pytest plugins +============================================= +Besides plugins explicitly used by the package, there are a few pytest +plugins that enable themselves automatically for all test suites +when installed. In some cases, their presence causes tests of packages +that do not expect them, to fail. + +An example of such package used to be ``dev-python/pytest-relaxed``. +To resolve problems due to the plugin, it was necessary to disable +it explicitly:: + + python_test() { + # pytest-relaxed plugin makes our tests fail + epytest -p no:relaxed + } + + +Expert: disabling plugin autoloading entirely +============================================= +If a test suite invokes pytest recursively (this is particularly +the case when packaging other pytest plugins), the ``-p`` option +can be insufficient to disable problematic plugins, as it does not +get passed to the nested pytest invocations. For these packages, +the next best thing is to use environment variables. + +Unfortunately, environment variables can only be used to disable +autoloading entirely. When doing that, you need to explicitly force +loading plugins that the test suite really needs. + +This is done using two envvars: ``PYTEST_DISABLE_PLUGIN_AUTOLOAD`` +to disable autoloading plugins, and ``PYTEST_PLUGINS`` to specify +plugins to load. The latter takes a comma-separated list of entry point +modules. To find the correct module names, look into +the ``entry_points.txt`` inside the package's ``.egg-info`` directory. + +:: + + python_test() { + local -x PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 + local -x PYTEST_PLUGINS=xdist.plugin,xdist.looponfail,pytest_forked + + distutils_install_for_testing + epytest + } + + + +TypeError: _make_test_flaky() got an unexpected keyword argument 'reruns' +========================================================================= +If you see a test error resembling the following:: + + TypeError: _make_test_flaky() got an unexpected keyword argument 'reruns' + +This means that the tests are being run via flaky_ plugin while +the package in question expects pytest-rerunfailures_. This is +because both plugins utilize the same ``@pytest.mark.flaky`` marker +but support different set of arguments. + +To resolve the problem, explicitly disable the ``flaky`` plugin and make +sure to depend on ``dev-python/pytest-rerunfailures``:: + + BDEPEND=" + test? ( + dev-python/dev-python/pytest-rerunfailures[${PYTHON_USEDEP}] + )" + + python_test() { + epytest -p no:flaky + } + + +ImportPathMismatchError +======================= +An ``ImportPathMismatchError`` generally indicates that the same Python +module (or one that supposedly looks the same) has been loaded twice +using different paths, e.g.:: + + E _pytest.pathlib.ImportPathMismatchError: ('path', '/usr/lib/pypy3.7/site-packages/path', PosixPath('/tmp/portage/dev-python/jaraco-path-3.3.1/work/jaraco.path-3.3.1/jaraco/path.py')) + +These problems are usually caused by pytest test discovery getting +confused by namespace packages. In this case, the ``jaraco`` directory +is a Python 3-style namespace but pytest is treating it as a potential +test directory. Therefore, instead of loading it as ``jaraco.path`` +relatively to the top directory, it loads it as ``path`` relatively +to the ``jaraco`` directory. + +The simplest way to resolve this problem is to restrict the test +discovery to the actual test directories, e.g.:: + + python_test() { + epytest test + } + +or:: + + python_test() { + epytest --ignore jaraco + } + + +fixture '...' not found +======================= +Most of the time, a missing fixture indicates that some pytest plugin +is not installed. In rare cases, it can signify an incompatible pytest +version or package issue. + +The following table maps common fixture names to their respective +plugins. + +=================================== ==================================== +Fixture name Package +=================================== ==================================== +event_loop dev-python/pytest-asyncio +freezer dev-python/pytest-freezegun +httpbin dev-python/pytest-httpbin +loop dev-python/pytest-aiohttp +mocker dev-python/pytest-mock +=================================== ==================================== + + +Warnings +======== +pytest captures all warnings from the test suite by default, and prints +a summary of them at the end of the test suite run:: + + =============================== warnings summary =============================== + asgiref/sync.py:135: 1 warning + tests/test_local.py: 5 warnings + tests/test_sync.py: 12 warnings + tests/test_sync_contextvars.py: 1 warning + /tmp/asgiref/asgiref/sync.py:135: DeprecationWarning: There is no current event loop + self.main_event_loop = asyncio.get_event_loop() + [...] + +However, some projects go further and use ``filterwarnings`` option +to make (some) warnings fatal:: + + ==================================== ERRORS ==================================== + _____________________ ERROR collecting tests/test_sync.py ______________________ + tests/test_sync.py:577: in <module> + class ASGITest(TestCase): + tests/test_sync.py:583: in ASGITest + async def test_wrapped_case_is_collected(self): + asgiref/sync.py:135: in __init__ + self.main_event_loop = asyncio.get_event_loop() + E DeprecationWarning: There is no current event loop + =========================== short test summary info ============================ + ERROR tests/test_sync.py - DeprecationWarning: There is no current event loop + !!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!! + =============================== 1 error in 0.13s =============================== + +Unfortunately, this frequently means that warnings coming from +a dependency trigger test failures in other packages. Since making +warnings fatal is relatively common in the Python world, it is +recommended to: + +1. Fix warnings in Python packages whenever possible, even if they + are not fatal to the package itself. + +2. Do not enable new Python implementations if they trigger any new + warnings in the package. + +If the warnings come from issues in the package's test suite rather than +the installed code, it is acceptable to make them non-fatal. This can +be done either through removing the ``filterwarnings`` key from +``setup.cfg``, or adding an ignore entry. For example, the following +setting ignores ``DeprecationWarning`` in ``test`` directory:: + + filterwarnings = + error + ignore::DeprecationWarning:test + + +.. _custom pytest markers: + https://docs.pytest.org/en/stable/example/markers.html +.. _pytest-runner: https://pypi.org/project/pytest-runner/ +.. _pytest-xdist: https://pypi.org/project/pytest-xdist/ +.. _flaky: https://github.com/box/flaky/ +.. _pytest-rerunfailures: + https://github.com/pytest-dev/pytest-rerunfailures/ diff --git a/guide/_sources/single.rst.txt b/guide/_sources/single.rst.txt new file mode 100644 index 0000000..4636a4c --- /dev/null +++ b/guide/_sources/single.rst.txt @@ -0,0 +1,306 @@ +======================================= +python-single-r1 — single-impl packages +======================================= + +.. highlight:: bash + +The ``python-single-r1`` eclass is used to install single-impl packages. +It is probably the easiest eclass to use, and it is recommended over +``python-r1`` whenever multi-impl support would add unnecessary +complexity. However, for packages using distutils or a similar Python +build system, ``distutils-r1`` eclass should be used instead. + +Eclass reference: `python-single-r1.eclass(5)`_ + + +Basic use for unconditional Python +================================== +The defining feature of this eclass is that it defines a ``pkg_setup`` +phase. It normally calls ``python_setup`` function in order +to determine the interpreter selected by user, and set the global +environment appropriately. + +This means that a most trivial package using an autotools-compatible +build system along with unconditional dependency on Python could look +like the following: + +.. code-block:: bash + :emphasize-lines: 6,7,17,20 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python2_7 ) + inherit python-single-r1 + + DESCRIPTION="Scripts to prepare and plot VOACAP propagation predictions" + HOMEPAGE="https://www.qsl.net/h/hz1jw//pythonprop/" + SRC_URI="mirror://sourceforge/${PN}/${P}.tar.gz" + + LICENSE="GPL-2+" + SLOT="0" + KEYWORDS="~amd64 ~x86" + IUSE="" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + RDEPEND=" + ${PYTHON_DEPS} + ... + " + BDEPEND="${RDEPEND}" + +This ebuild demonstrates the absolute minimum working code. Only +the four highlighted lines are specific to Python eclasses, plus +the implicitly exported ``pkg_setup`` phase. + + +.. index:: PYTHON_SINGLE_USEDEP +.. index:: PYTHON_USEDEP; python-single-r1 +.. index:: python_gen_cond_dep; for python-single-r1 + +Dependencies +============ +When depending on other Python packages, USE dependencies need to be +declared in order to ensure that the dependencies would be built against +the Python implementation used for the package. The exact dependency +string depends on whether the target package is single-impl +or multi-impl. + +When depending on other single-impl packages, the eclass-defined +``${PYTHON_SINGLE_USEDEP}`` variable can be used to inject the correct +USE dependency:: + + RDEPEND=" + ... + dev-python/basemap[${PYTHON_SINGLE_USEDEP}] + " + +When depending on multi-impl packages, a more complex construct must +be used. The ``python_gen_cond_dep`` generator function is used +to copy the specified dependency template for all supported +implementations, and substitute ``${PYTHON_USEDEP}`` template inside +it:: + + RDEPEND=" + ... + $(python_gen_cond_dep ' + dev-python/matplotlib-python2[gtk2,${PYTHON_USEDEP}] + ') + " + +Please note that in this context, ``${...}`` is used as a literal +template substitution key, so it must be escaped to prevent bash from +substituting it immediately. In the above example, single quotes +are used for this purpose. When other variables are used, double quotes +with explicit escapes have to be used:: + + RDEPEND=" + ... + $(python_gen_cond_dep " + dev-python/wxpython:${WX_GTK_VER}[\${PYTHON_USEDEP}] + ")" + +As demonstrated above, the USE dependency string can be combined with +other USE dependencies. ``PYTHON_SINGLE_USEDEP`` can be used both +inside and outside ``python_gen_cond_dep``, while ``PYTHON_USEDEP`` only +inside it. + + +Conditional Python use +====================== +The examples so far assumed that Python is used unconditionally. +If Python support is conditional to a USE flag, appropriate USE +conditionals need to be used in metadata variables, and ``pkg_setup`` +needs to be rewritten to call the default implementation conditionally: + +.. code-block:: bash + :emphasize-lines: 16,17,20,21,23-27,30,35 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + + PYTHON_COMPAT=( python2_7 ) + inherit python-single-r1 + + DESCRIPTION="Yet more Objects for (High Energy Physics) Data Analysis" + HOMEPAGE="http://yoda.hepforge.org/" + SRC_URI="http://www.hepforge.org/archive/${PN}/${P}.tar.bz2" + + LICENSE="GPL-2" + SLOT="0/${PV}" + KEYWORDS="~amd64 ~x86 ~amd64-linux ~x86-linux" + IUSE="python root" + REQUIRED_USE="python? ( ${PYTHON_REQUIRED_USE} )" + + RDEPEND=" + python? ( ${PYTHON_DEPS} ) + root? ( sci-physics/root:=[python=,${PYTHON_SINGLE_USEDEP}] )" + DEPEND="${RDEPEND} + python? ( + $(python_gen_cond_dep ' + dev-python/cython[${PYTHON_USEDEP}] + ') + )" + + pkg_setup() { + use python && python-single-r1_pkg_setup + } + + src_configure() { + econf \ + $(use_enable python pyext) \ + $(use_enable root) + } + + +A hybrid: build-time + conditional runtime +========================================== +A fairly common pattern is for Python to be required unconditionally +at build time but only conditionally at runtime. This happens e.g. when +the package is calling some helper scripts at build time, and optionally +installing Python bindings. In this case, the build time dependency +is expressed unconditionally, and the runtime dependency is made +USE-conditional: + +.. code-block:: bash + :emphasize-lines: 18,19,23,26,32 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + + PYTHON_COMPAT=( python3_{6,7,8} ) + PYTHON_REQ_USE="threads(+)" + + inherit waf-utils python-single-r1 + + DESCRIPTION="Samba talloc library" + HOMEPAGE="https://talloc.samba.org/" + SRC_URI="https://www.samba.org/ftp/${PN}/${P}.tar.gz" + + LICENSE="GPL-3 LGPL-3+ LGPL-2" + SLOT="0" + KEYWORDS="~alpha amd64 arm ~arm64 ~hppa ia64 ~m68k ~mips ppc ppc64 ~riscv ~s390 ~sh ~sparc x86 ~amd64-linux ~x86-linux ~x64-macos ~sparc-solaris ~x64-solaris" + IUSE="+python" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + RDEPEND=" + ... + python? ( ${PYTHON_DEPS} )" + DEPEND="${RDEPEND} + ... + ${PYTHON_DEPS}" + + WAF_BINARY="${S}/buildtools/bin/waf" + + src_configure() { + local extra_opts=( + $(usex python '' --disable-python) + ) + waf-utils_src_configure "${extra_opts[@]}" + } + +Note that eclass-exported ``pkg_setup`` is used unconditionally here. + + +Multiple USE conditions +======================= +Finally, let's give an example of a package where Python is needed +for two independent conditions. To make it more complex, one of them +applies to build time (tests) while the other to runtime (bindings). + +.. code-block:: bash + :emphasize-lines: 16,19,20,24,27,31-33,38,39 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=7 + + PYTHON_COMPAT=( python3_{6,7,8} ) + inherit cmake python-single-r1 + + DESCRIPTION="Sound design and signal processing system for composition and performance" + HOMEPAGE="https://csound.github.io/" + SRC_URI="https://dev.gentoo.org/~fordfrog/distfiles/${P}-distributable.tar.xz" + + LICENSE="LGPL-2.1 doc? ( FDL-1.2+ )" + SLOT="0" + KEYWORDS="~amd64 ~x86" + IUSE="python test" + RESTRICT="!test? ( test )" + REQUIRED_USE=" + python? ( ${PYTHON_REQUIRED_USE} ) + test? ( ${PYTHON_REQUIRED_USE} )" + + BDEPEND=" + python? ( dev-lang/swig ) + test? ( ${PYTHON_DEPS} ) + " + RDEPEND=" + python? ( ${PYTHON_DEPS} ) + " + + pkg_setup() { + if use python || use test ; then + python-single-r1_pkg_setup + fi + } + + src_configure() { + local mycmakeargs=( + -DBUILD_PYTHON_INTERFACE=$(usex python) + -DBUILD_PYTHON_OPCODES=$(usex python) + ) + + cmake_src_configure + } + +Please note that in general, the condition in ``pkg_setup`` must match +the one in ``REQUIRED_USE``, and that one is a superset of conditions +used in dependencies. + + +Manual install +============== +Some packages do not include Python files in their build systems, +or do not install all of them. In this case, the necessary files +can be installed via one of the installation helpers. + +.. code-block:: bash + :emphasize-lines: 23,24 + + # Copyright 1999-2020 Gentoo Authors + # Distributed under the terms of the GNU General Public License v2 + + EAPI=6 + + PYTHON_COMPAT=( python2_7 ) + inherit python-single-r1 + + DESCRIPTION="Arabic dictionary based on the DICT protocol" + HOMEPAGE="https://www.arabeyes.org/Duali" + SRC_URI="mirror://sourceforge/arabeyes/${P}.tar.bz2" + + LICENSE="BSD" + SLOT="0" + KEYWORDS="~alpha amd64 ~hppa ~ia64 ~mips ~ppc ~sparc x86" + IUSE="" + REQUIRED_USE="${PYTHON_REQUIRED_USE}" + + DEPEND="${PYTHON_DEPS}" + RDEPEND="${DEPEND}" + + src_install() { + python_domodule pyduali + python_doscript duali dict2db trans2arabic arabic2trans + } + + +.. _python-single-r1.eclass(5): + https://devmanual.gentoo.org/eclass-reference/python-single-r1.eclass/index.html diff --git a/guide/_sources/test.rst.txt b/guide/_sources/test.rst.txt new file mode 100644 index 0000000..81efe47 --- /dev/null +++ b/guide/_sources/test.rst.txt @@ -0,0 +1,322 @@ +============================= +Resolving test suite problems +============================= + +.. highlight:: bash + +Choosing the correct test runner +================================ +There are a few modules used to run tests in Python packages. The most +common include the built-in unittest_ module, pytest_ and nose_. There +are also some rarely used test tools and domain-specific solutions, +e.g. django_ has its own test runner. This section will help you +determining which test runner to use and depend on. + +Firstly, it is a good idea to look at test sources. Explicit imports +clearly indicate that a particular test runner needs to be installed, +and most likely used. For example, if at least one test file has +``import pytest``, pytest is the obvious choice. If it has ``import +nose``, same goes for nosetests. + +In some rare cases the tests may use multiple test packages +simultaneously. In this case, you need to choose one of the test +runners (see other suggestions) but depend on all of them. + +Secondly, some test suites are relying on *implicit* features of a test +runner. For example, pytest and nose have less strict naming +and structural requirements for test cases. In some cases, unittest +runner will simply be unable to find all tests. + +Thirdly, there are cases when a particular feature of a test runner +is desired even if it is not strictly necessary to run tests. This +is particularly the case with pytest's output capture that can make +test output much more readable with particularly verbose packages. + +Upstream documentation, tox configuration, CI pipelines can provide tips +on the test runner to be used. However, you should establish whether +this information is wholly correct and up-to-date, and whether +the particular test tool is really desirable. + +If the test suite requires no particular runner (i.e. works with +built-in unittest module), using it is preferable to avoid unnecessary +dependencies. However, you need to make sure that it finds all tests +correctly (i.e. runs no less tests than the alternative) and that it +does not spew too much irrelevant output. + +If both pytest and nose seem equally good, the former is recommended +as the latter has ceased development and requires downstream patching. +If you have some free time, convincing upstream to switch from nose +to pytest is a worthwhile goal. + + +Missing test files in PyPI packages +=================================== +One of the more common test-related problems is that PyPI packages +(generated via ``setup.py sdist``) often miss some or all test files. +The latter results in no tests being run, the former in test failures +or errors. + +The simplest solution is to use a VCS snapshot instead of the PyPI +tarball:: + + # pypi tarballs are missing test data + #SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz" + SRC_URI="https://github.com/${PN}/${PN}/archive/${PV}.tar.gz -> ${P}.gh.tar.gz" + + +Checklist for dealing with test failures +======================================== +If you see some test failures but do not have a guess as to why they +would be happening, try the following for a start: + +1. Check upstream CI (if any). That's a quick way of verifying that + there is no known breakage at the relevant tag. + +2. Try running tests as your regular user, the way upstream suggests + (e.g. via ``tox``). Try using a git checkout at the specific tag. + This is the basic way of determining whether the package is actually + broken or if it is something on our end. + +3. If the tests fail at the specified tag, try upstream master branch. + Maybe there was a fix committed. + +If it seems that the issue is on our end, try the following and see +if it causes the subset of failing tests to change: + +1. Add ``distutils_install_for_testing`` to the test sub-phase. This + resolves majority of problems with test suite assuming the package + must already be installed. + +2. Actually install the package to the system (with tests disabled). + This can confirm cases of package for whom the above function + does not work. In the worst case, you can set a test self-dependency + to force users to install the package before testing:: + + test? ( ~dev-python/myself-${PV} ) + +3. Try testing a different Python implementation. If a subset of tests + is failing with Python 3.6, see if it still happens with 3.7 or 3.8. + If 3.8 is passing but 3.9 is not, it's most likely some + incompatibility upstream did not account for. + +4. Run tests with ``FEATURES=-network-sandbox``. Sometimes lack + of Internet access causes non-obvious failures. + +5. Try a different test runner. Sometimes the subtle differences + in how tests are executed can lead to test failures. But beware: + some test runners may not run the full set of tests, so verify + that you have actually fixed them and not just caused them to + be skipped. + + +Skipping problematic tests +========================== +While generally it is preferable to fix tests, sometimes you will face +failures that cannot be easily resolved. This especially applies +to tests that are broken themselves rather than indicating real problems +with the software. However, in some cases you will even find yourself +ignoring minor test failures. + +Tests that are known to fail reliably can be marked as *expected +failures*. This has the advantage that the test in question will +continue being run and the test suite will report when it unexpectedly +starts passing again. + +Expected failures are not supported by the standard Python unittest +module. It is supported e.g. by pytest. + +:: + + sed -i -e \ + "/def test_start_params_bug():/i@pytest.mark.xfail(reason='Known to fail on Gentoo')" \ + statsmodels/tsa/tests/test_arima.py || die + +Tests that cause inconsistent results, trigger errors, consume +horrendous amounts of disk space or cause another kind of undesirable +mayhem can be *skipped* instead. Skipping means that they will not be +run at all. + +There are multiple ways to skip a test. You can patch it to use a skip +decorator, possibly with a condition:: + + # broken on py2.7, upstream knows + sed -i -e '5a\ + import sys' \ + -e '/test_null_bytes/i\ + @pytest.mark.skipif(sys.hexversion < 0x03000000, reason="broken on py2")' \ + test/server.py || die + +The easy way to skip a test unconditioanlly is to prefix its name with +an underscore:: + + # tests requiring specific locales + sed -i -e 's:test_babel_with_language_:_&:' \ + tests/test_build_latex.py || die + sed -i -e 's:test_polyglossia_with_language_:_&:' \ + tests/test_build_latex.py || die + +Finally, if all tests in a particular file are problematic, you can +simply remove that file. If all tests belonging to the package +are broken, you can use ``RESTRICT=test`` to disable testing altogether. + + +Tests requiring Internet access +=============================== +One of more common causes of test failures are attempts to use Internet. +With Portage blocking network access by default, packages performing +tests against remote servers often fail. + +Ideally, packages would use mocking or replay tests rather than using +real Internet services. Devmanual provides a detailed explanation `why +tests must not use Internet`_. + +Some packages provide explicit methods of disabling network-based tests. +For example, ``dev-python/tox`` provides a switch for that:: + + python_test() { + distutils_install_for_testing + epytest --no-network + } + +There are packages that skip tests if they fail specifically due to +connection errors, or detect whether Internet is accessible. Ideally, +you should modify those packages to disable network tests +unconditionally. For example, ``dev-python/pygit2`` ebuild does this:: + + # unconditionally prevent it from using network + sed -i -e '/def no_network/a \ + return True' test/utils.py || die + +In other cases, you will have to explicitly disable these tests. +In some cases, it will be reasonable to remove whole test files or even +restrict tests entirely. + +If the package's test suite relies on Internet access entirely and there +is no point in running even a subset of tests, please implement running +tests and combine test restriction with ``PROPERTIES=test_network`` +to allow interested users to run tests when possible:: + + # users can use ALLOW_TEST=network to override this + PROPERTIES="test_network" + RESTRICT="test" + + distutils_enable_tests pytest + + +Tests aborting (due to assertions) +================================== +There are cases of package's tests terminating with an unclear error +message and backtrace similar to the following:: + + ============================= test session starts ============================== + platform linux -- Python 3.7.8, pytest-6.0.1, py-1.9.0, pluggy-0.13.1 -- /usr/bin/python3.7 + cachedir: .pytest_cache + rootdir: /var/tmp/portage/dev-python/sabyenc-4.0.2/work/sabyenc-4.0.2, configfile: pytest.ini + collecting ... collected 24 items + + [...] + tests/test_decoder.py::test_crc_pickles PASSED [ 54%] + tests/test_decoder.py::test_empty_size_pickles Fatal Python error: Aborted + + Current thread 0x00007f748bc47740 (most recent call first): + File "/var/tmp/portage/dev-python/sabyenc-4.0.2/work/sabyenc-4.0.2/tests/testsupport.py", line 74 in sabyenc3_wrapper + File "/var/tmp/portage/dev-python/sabyenc-4.0.2/work/sabyenc-4.0.2/tests/test_decoder.py", line 119 in test_empty_size_pickles + File "/usr/lib/python3.7/site-packages/_pytest/python.py", line 180 in pytest_pyfunc_call + File "/usr/lib/python3.7/site-packages/pluggy/callers.py", line 187 in _multicall + [...] + File "/usr/lib/python-exec/python3.7/pytest", line 11 in <module> + /var/tmp/portage/dev-python/sabyenc-4.0.2/temp/environment: line 2934: 66 Aborted (core dumped) pytest -vv + +This usually indicates that the C code of some Python extension failed +an assertion. Since pytest does not print captured output when exiting +due to a signal, you need to disable output capture (using ``-s``) +to get a more useful error, e.g.:: + + $ python3.7 -m pytest -s + =============================================================== test session starts =============================================================== + platform linux -- Python 3.7.8, pytest-6.0.1, py-1.9.0, pluggy-0.13.1 + rootdir: /tmp/sabyenc, configfile: pytest.ini + plugins: asyncio-0.14.0, forked-1.3.0, xdist-1.34.0, hypothesis-5.23.9, mock-3.2.0, flaky-3.7.0, timeout-1.4.2, freezegun-0.4.2 + collected 25 items + + tests/test_decoder.py .............python3.7: src/sabyenc3.c:596: decode_usenet_chunks: Assertion `PyByteArray_Check(PyList_GetItem(Py_input_list, lp))' failed. + Fatal Python error: Aborted + + Current thread 0x00007fb5db746740 (most recent call first): + File "/tmp/sabyenc/tests/testsupport.py", line 73 in sabyenc3_wrapper + File "/tmp/sabyenc/tests/test_decoder.py", line 117 in test_empty_size_pickles + File "/usr/lib/python3.7/site-packages/_pytest/python.py", line 180 in pytest_pyfunc_call + File "/usr/lib/python3.7/site-packages/pluggy/callers.py", line 187 in _multicall + File "/usr/lib/python3.7/site-packages/pluggy/manager.py", line 87 in <lambda> + [...] + File "/usr/lib/python3.7/site-packages/pytest/__main__.py", line 7 in <module> + File "/usr/lib/python3.7/runpy.py", line 85 in _run_code + File "/usr/lib/python3.7/runpy.py", line 193 in _run_module_as_main + Aborted (core dumped) + +Now the message clearly indicates the failed assertion. + +It is also common that upstream is initially unable to reproduce +the bug. This is because Ubuntu and many other common distributions +build Python with ``-DNDEBUG`` and the flag leaks to extension builds. +As a result, all assertions are stripped at build time. Upstream +can work around that by explicitly setting ``CFLAGS`` for the build, +e.g.:: + + $ CFLAGS='-O0 -g' python setup.py build build_ext -i + $ pytest -s + + +Installing extra dependencies in test environment (e.g. example plugins) +======================================================================== +Rarely, the test suite expects some package being installed that +does not fit being packaged and installed system-wide. For example, +isort's tests use a few example plugins that are not useful to end +users, or pip's test suite still requires old virtualenv that collides +with the modern versions. These problems can be resolved by installing +the packages locally within the ebuild. + +To do this, just use ``distutils_install_for_testing`` in every package +that you need to install. For example:: + + python_test() { + # the main package + distutils_install_for_testing + # additional plugins + local p + for p in example*/; do + pushd "${p}" >/dev/null || die + distutils_install_for_testing + popd >/dev/null || die + done + + epytest + } + +If the extra packages are not included in the main distribution tarball, +you will also need to fetch them, e.g.:: + + VENV_PV=16.7.10 + SRC_URI+=" + test? ( + https://github.com/pypa/virtualenv/archive/${VENV_PV}.tar.gz + -> virtualenv-${VENV_PV}.tar.gz + ) + " + + python_test() { + distutils_install_for_testing + pushd "${WORKDIR}/virtualenv-${VENV_PV}" >/dev/null || die + distutils_install_for_testing + popd >/dev/null || die + + epytest + } + + +.. _unittest: https://docs.python.org/3/library/unittest.html +.. _pytest: https://docs.pytest.org/en/latest/ +.. _nose: https://github.com/nose-devs/nose +.. _django: https://www.djangoproject.com/ +.. _why tests must not use Internet: + https://devmanual.gentoo.org/ebuild-writing/functions/src_test/#tests-that-require-network-or-service-access diff --git a/guide/_static/alabaster.css b/guide/_static/alabaster.css new file mode 100644 index 0000000..0eddaeb --- /dev/null +++ b/guide/_static/alabaster.css @@ -0,0 +1,701 @@ +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: Georgia, serif; + font-size: 17px; + background-color: #fff; + color: #000; + margin: 0; + padding: 0; +} + + +div.document { + width: 940px; + margin: 30px auto 0 auto; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 220px; +} + +div.sphinxsidebar { + width: 220px; + font-size: 14px; + line-height: 1.5; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.body { + background-color: #fff; + color: #3E4349; + padding: 0 30px 0 30px; +} + +div.body > .section { + text-align: left; +} + +div.footer { + width: 940px; + margin: 20px auto 30px auto; + font-size: 14px; + color: #888; + text-align: right; +} + +div.footer a { + color: #888; +} + +p.caption { + font-family: inherit; + font-size: inherit; +} + + +div.relations { + display: none; +} + + +div.sphinxsidebar a { + color: #444; + text-decoration: none; + border-bottom: 1px dotted #999; +} + +div.sphinxsidebar a:hover { + border-bottom: 1px solid #999; +} + +div.sphinxsidebarwrapper { + padding: 18px 10px; +} + +div.sphinxsidebarwrapper p.logo { + padding: 0; + margin: -10px 0 0 0px; + text-align: center; +} + +div.sphinxsidebarwrapper h1.logo { + margin-top: -10px; + text-align: center; + margin-bottom: 5px; + text-align: left; +} + +div.sphinxsidebarwrapper h1.logo-name { + margin-top: 0px; +} + +div.sphinxsidebarwrapper p.blurb { + margin-top: 0; + font-style: normal; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: Georgia, serif; + color: #444; + font-size: 24px; + font-weight: normal; + margin: 0 0 5px 0; + padding: 0; +} + +div.sphinxsidebar h4 { + font-size: 20px; +} + +div.sphinxsidebar h3 a { + color: #444; +} + +div.sphinxsidebar p.logo a, +div.sphinxsidebar h3 a, +div.sphinxsidebar p.logo a:hover, +div.sphinxsidebar h3 a:hover { + border: none; +} + +div.sphinxsidebar p { + color: #555; + margin: 10px 0; +} + +div.sphinxsidebar ul { + margin: 10px 0; + padding: 0; + color: #000; +} + +div.sphinxsidebar ul li.toctree-l1 > a { + font-size: 120%; +} + +div.sphinxsidebar ul li.toctree-l2 > a { + font-size: 110%; +} + +div.sphinxsidebar input { + border: 1px solid #CCC; + font-family: Georgia, serif; + font-size: 1em; +} + +div.sphinxsidebar hr { + border: none; + height: 1px; + color: #AAA; + background: #AAA; + + text-align: left; + margin-left: 0; + width: 50%; +} + +div.sphinxsidebar .badge { + border-bottom: none; +} + +div.sphinxsidebar .badge:hover { + border-bottom: none; +} + +/* To address an issue with donation coming after search */ +div.sphinxsidebar h3.donation { + margin-top: 10px; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #004B6B; + text-decoration: underline; +} + +a:hover { + color: #6D4100; + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: Georgia, serif; + font-weight: normal; + margin: 30px 0px 10px 0px; + padding: 0; +} + +div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } +div.body h2 { font-size: 180%; } +div.body h3 { font-size: 150%; } +div.body h4 { font-size: 130%; } +div.body h5 { font-size: 100%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #DDD; + padding: 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + color: #444; + background: #EAEAEA; +} + +div.body p, div.body dd, div.body li { + line-height: 1.4em; +} + +div.admonition { + margin: 20px 0px; + padding: 10px 30px; + background-color: #EEE; + border: 1px solid #CCC; +} + +div.admonition tt.xref, div.admonition code.xref, div.admonition a tt { + background-color: #FBFBFB; + border-bottom: 1px solid #fafafa; +} + +div.admonition p.admonition-title { + font-family: Georgia, serif; + font-weight: normal; + font-size: 24px; + margin: 0 0 10px 0; + padding: 0; + line-height: 1; +} + +div.admonition p.last { + margin-bottom: 0; +} + +div.highlight { + background-color: #fff; +} + +dt:target, .highlight { + background: #FAF3E8; +} + +div.warning { + background-color: #FCC; + border: 1px solid #FAA; +} + +div.danger { + background-color: #FCC; + border: 1px solid #FAA; + -moz-box-shadow: 2px 2px 4px #D52C2C; + -webkit-box-shadow: 2px 2px 4px #D52C2C; + box-shadow: 2px 2px 4px #D52C2C; +} + +div.error { + background-color: #FCC; + border: 1px solid #FAA; + -moz-box-shadow: 2px 2px 4px #D52C2C; + -webkit-box-shadow: 2px 2px 4px #D52C2C; + box-shadow: 2px 2px 4px #D52C2C; +} + +div.caution { + background-color: #FCC; + border: 1px solid #FAA; +} + +div.attention { + background-color: #FCC; + border: 1px solid #FAA; +} + +div.important { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.note { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.tip { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.hint { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.seealso { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.topic { + background-color: #EEE; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre, tt, code { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.9em; +} + +.hll { + background-color: #FFC; + margin: 0 -12px; + padding: 0 12px; + display: block; +} + +img.screenshot { +} + +tt.descname, tt.descclassname, code.descname, code.descclassname { + font-size: 0.95em; +} + +tt.descname, code.descname { + padding-right: 0.08em; +} + +img.screenshot { + -moz-box-shadow: 2px 2px 4px #EEE; + -webkit-box-shadow: 2px 2px 4px #EEE; + box-shadow: 2px 2px 4px #EEE; +} + +table.docutils { + border: 1px solid #888; + -moz-box-shadow: 2px 2px 4px #EEE; + -webkit-box-shadow: 2px 2px 4px #EEE; + box-shadow: 2px 2px 4px #EEE; +} + +table.docutils td, table.docutils th { + border: 1px solid #888; + padding: 0.25em 0.7em; +} + +table.field-list, table.footnote { + border: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + +table.footnote { + margin: 15px 0; + width: 100%; + border: 1px solid #EEE; + background: #FDFDFD; + font-size: 0.9em; +} + +table.footnote + table.footnote { + margin-top: -15px; + border-top: none; +} + +table.field-list th { + padding: 0 0.8em 0 0; +} + +table.field-list td { + padding: 0; +} + +table.field-list p { + margin-bottom: 0.8em; +} + +/* Cloned from + * https://github.com/sphinx-doc/sphinx/commit/ef60dbfce09286b20b7385333d63a60321784e68 + */ +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +table.footnote td.label { + width: .1px; + padding: 0.3em 0 0.3em 0.5em; +} + +table.footnote td { + padding: 0.3em 0.5em; +} + +dl { + margin: 0; + padding: 0; +} + +dl dd { + margin-left: 30px; +} + +blockquote { + margin: 0 0 0 30px; + padding: 0; +} + +ul, ol { + /* Matches the 30px from the narrow-screen "li > ul" selector below */ + margin: 10px 0 10px 30px; + padding: 0; +} + +pre { + background: #EEE; + padding: 7px 30px; + margin: 15px 0px; + line-height: 1.3em; +} + +div.viewcode-block:target { + background: #ffd; +} + +dl pre, blockquote pre, li pre { + margin-left: 0; + padding-left: 30px; +} + +tt, code { + background-color: #ecf0f3; + color: #222; + /* padding: 1px 2px; */ +} + +tt.xref, code.xref, a tt { + background-color: #FBFBFB; + border-bottom: 1px solid #fff; +} + +a.reference { + text-decoration: none; + border-bottom: 1px dotted #004B6B; +} + +/* Don't put an underline on images */ +a.image-reference, a.image-reference:hover { + border-bottom: none; +} + +a.reference:hover { + border-bottom: 1px solid #6D4100; +} + +a.footnote-reference { + text-decoration: none; + font-size: 0.7em; + vertical-align: top; + border-bottom: 1px dotted #004B6B; +} + +a.footnote-reference:hover { + border-bottom: 1px solid #6D4100; +} + +a:hover tt, a:hover code { + background: #EEE; +} + + +@media screen and (max-width: 870px) { + + div.sphinxsidebar { + display: none; + } + + div.document { + width: 100%; + + } + + div.documentwrapper { + margin-left: 0; + margin-top: 0; + margin-right: 0; + margin-bottom: 0; + } + + div.bodywrapper { + margin-top: 0; + margin-right: 0; + margin-bottom: 0; + margin-left: 0; + } + + ul { + margin-left: 0; + } + + li > ul { + /* Matches the 30px from the "ul, ol" selector above */ + margin-left: 30px; + } + + .document { + width: auto; + } + + .footer { + width: auto; + } + + .bodywrapper { + margin: 0; + } + + .footer { + width: auto; + } + + .github { + display: none; + } + + + +} + + + +@media screen and (max-width: 875px) { + + body { + margin: 0; + padding: 20px 30px; + } + + div.documentwrapper { + float: none; + background: #fff; + } + + div.sphinxsidebar { + display: block; + float: none; + width: 102.5%; + margin: 50px -30px -20px -30px; + padding: 10px 20px; + background: #333; + color: #FFF; + } + + div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p, + div.sphinxsidebar h3 a { + color: #fff; + } + + div.sphinxsidebar a { + color: #AAA; + } + + div.sphinxsidebar p.logo { + display: none; + } + + div.document { + width: 100%; + margin: 0; + } + + div.footer { + display: none; + } + + div.bodywrapper { + margin: 0; + } + + div.body { + min-height: 0; + padding: 0; + } + + .rtd_doc_footer { + display: none; + } + + .document { + width: auto; + } + + .footer { + width: auto; + } + + .footer { + width: auto; + } + + .github { + display: none; + } +} + + +/* misc. */ + +.revsys-inline { + display: none!important; +} + +/* Make nested-list/multi-paragraph items look better in Releases changelog + * pages. Without this, docutils' magical list fuckery causes inconsistent + * formatting between different release sub-lists. + */ +div#changelog > div.section > ul > li > p:only-child { + margin-bottom: 0; +} + +/* Hide fugly table cell borders in ..bibliography:: directive output */ +table.docutils.citation, table.docutils.citation td, table.docutils.citation th { + border: none; + /* Below needed in some edge cases; if not applied, bottom shadows appear */ + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + + +/* relbar */ + +.related { + line-height: 30px; + width: 100%; + font-size: 0.9rem; +} + +.related.top { + border-bottom: 1px solid #EEE; + margin-bottom: 20px; +} + +.related.bottom { + border-top: 1px solid #EEE; +} + +.related ul { + padding: 0; + margin: 0; + list-style: none; +} + +.related li { + display: inline; +} + +nav#rellinks { + float: right; +} + +nav#rellinks li+li:before { + content: "|"; +} + +nav#breadcrumbs li+li:before { + content: "\00BB"; +} + +/* Hide certain items when printing */ +@media print { + div.related { + display: none; + } +}
\ No newline at end of file diff --git a/guide/_static/basic.css b/guide/_static/basic.css new file mode 100644 index 0000000..bf18350 --- /dev/null +++ b/guide/_static/basic.css @@ -0,0 +1,906 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 450px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a.brackets:before, +span.brackets > a:before{ + content: "["; +} + +a.brackets:after, +span.brackets > a:after { + content: "]"; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +dl.footnote > dt, +dl.citation > dt { + float: left; + margin-right: 0.5em; +} + +dl.footnote > dd, +dl.citation > dd { + margin-bottom: 0em; +} + +dl.footnote > dd:after, +dl.citation > dd:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dt:after { + content: ":"; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +}
\ No newline at end of file diff --git a/guide/_static/custom.css b/guide/_static/custom.css new file mode 100644 index 0000000..2a924f1 --- /dev/null +++ b/guide/_static/custom.css @@ -0,0 +1 @@ +/* This file intentionally left blank. */ diff --git a/guide/_static/doctools.js b/guide/_static/doctools.js new file mode 100644 index 0000000..e509e48 --- /dev/null +++ b/guide/_static/doctools.js @@ -0,0 +1,326 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for all documentation. + * + * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", + "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", + "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {}; +} + */ + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initIndexTable(); + if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) { + this.initOnKeyListeners(); + } + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated === 'undefined') + return string; + return (typeof translated === 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated === 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[id] > :header:first').each(function() { + $('<a class="headerlink">\u00B6</a>'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[id]').each(function() { + $('<a class="headerlink">\u00B6</a>'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075 + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash && $.browser.mozilla) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + if (!body.length) { + body = $('body'); + } + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlighted'); + }); + }, 10); + $('<p class="highlight-link"><a href="javascript:Documentation.' + + 'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>') + .appendTo($('#searchbox')); + } + }, + + /** + * init the domain index toggle buttons + */ + initIndexTable : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + $('tr.cg-' + idnum).toggle(); + if (src.substr(-9) === 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('#searchbox .highlight-link').fadeOut(300); + $('span.highlighted').removeClass('highlighted'); + var url = new URL(window.location); + url.searchParams.delete('highlight'); + window.history.replaceState({}, '', url); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this === '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + }, + + initOnKeyListeners: function() { + $(document).keydown(function(event) { + var activeElementType = document.activeElement.tagName; + // don't navigate when in search box, textarea, dropdown or button + if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT' + && activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey + && !event.shiftKey) { + switch (event.keyCode) { + case 37: // left + var prevHref = $('link[rel="prev"]').prop('href'); + if (prevHref) { + window.location.href = prevHref; + return false; + } + break; + case 39: // right + var nextHref = $('link[rel="next"]').prop('href'); + if (nextHref) { + window.location.href = nextHref; + return false; + } + break; + } + } + }); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff --git a/guide/_static/documentation_options.js b/guide/_static/documentation_options.js new file mode 100644 index 0000000..2fa8c97 --- /dev/null +++ b/guide/_static/documentation_options.js @@ -0,0 +1,12 @@ +var DOCUMENTATION_OPTIONS = { + URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), + VERSION: '', + LANGUAGE: 'None', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false +};
\ No newline at end of file diff --git a/guide/_static/file.png b/guide/_static/file.png Binary files differnew file mode 100644 index 0000000..a858a41 --- /dev/null +++ b/guide/_static/file.png diff --git a/guide/_static/jquery-3.5.1.js b/guide/_static/jquery-3.5.1.js new file mode 100644 index 0000000..5093733 --- /dev/null +++ b/guide/_static/jquery-3.5.1.js @@ -0,0 +1,10872 @@ +/*! + * jQuery JavaScript Library v3.5.1 + * https://jquery.com/ + * + * Includes Sizzle.js + * https://sizzlejs.com/ + * + * Copyright JS Foundation and other contributors + * Released under the MIT license + * https://jquery.org/license + * + * Date: 2020-05-04T22:49Z + */ +( function( global, factory ) { + + "use strict"; + + if ( typeof module === "object" && typeof module.exports === "object" ) { + + // For CommonJS and CommonJS-like environments where a proper `window` + // is present, execute the factory and get jQuery. + // For environments that do not have a `window` with a `document` + // (such as Node.js), expose a factory as module.exports. + // This accentuates the need for the creation of a real `window`. + // e.g. var jQuery = require("jquery")(window); + // See ticket #14549 for more info. + module.exports = global.document ? + factory( global, true ) : + function( w ) { + if ( !w.document ) { + throw new Error( "jQuery requires a window with a document" ); + } + return factory( w ); + }; + } else { + factory( global ); + } + +// Pass this if window is not defined yet +} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) { + +// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1 +// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode +// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common +// enough that all such attempts are guarded in a try block. +"use strict"; + +var arr = []; + +var getProto = Object.getPrototypeOf; + +var slice = arr.slice; + +var flat = arr.flat ? function( array ) { + return arr.flat.call( array ); +} : function( array ) { + return arr.concat.apply( [], array ); +}; + + +var push = arr.push; + +var indexOf = arr.indexOf; + +var class2type = {}; + +var toString = class2type.toString; + +var hasOwn = class2type.hasOwnProperty; + +var fnToString = hasOwn.toString; + +var ObjectFunctionString = fnToString.call( Object ); + +var support = {}; + +var isFunction = function isFunction( obj ) { + + // Support: Chrome <=57, Firefox <=52 + // In some browsers, typeof returns "function" for HTML <object> elements + // (i.e., `typeof document.createElement( "object" ) === "function"`). + // We don't want to classify *any* DOM node as a function. + return typeof obj === "function" && typeof obj.nodeType !== "number"; + }; + + +var isWindow = function isWindow( obj ) { + return obj != null && obj === obj.window; + }; + + +var document = window.document; + + + + var preservedScriptAttributes = { + type: true, + src: true, + nonce: true, + noModule: true + }; + + function DOMEval( code, node, doc ) { + doc = doc || document; + + var i, val, + script = doc.createElement( "script" ); + + script.text = code; + if ( node ) { + for ( i in preservedScriptAttributes ) { + + // Support: Firefox 64+, Edge 18+ + // Some browsers don't support the "nonce" property on scripts. + // On the other hand, just using `getAttribute` is not enough as + // the `nonce` attribute is reset to an empty string whenever it + // becomes browsing-context connected. + // See https://github.com/whatwg/html/issues/2369 + // See https://html.spec.whatwg.org/#nonce-attributes + // The `node.getAttribute` check was added for the sake of + // `jQuery.globalEval` so that it can fake a nonce-containing node + // via an object. + val = node[ i ] || node.getAttribute && node.getAttribute( i ); + if ( val ) { + script.setAttribute( i, val ); + } + } + } + doc.head.appendChild( script ).parentNode.removeChild( script ); + } + + +function toType( obj ) { + if ( obj == null ) { + return obj + ""; + } + + // Support: Android <=2.3 only (functionish RegExp) + return typeof obj === "object" || typeof obj === "function" ? + class2type[ toString.call( obj ) ] || "object" : + typeof obj; +} +/* global Symbol */ +// Defining this global in .eslintrc.json would create a danger of using the global +// unguarded in another place, it seems safer to define global only for this module + + + +var + version = "3.5.1", + + // Define a local copy of jQuery + jQuery = function( selector, context ) { + + // The jQuery object is actually just the init constructor 'enhanced' + // Need init if jQuery is called (just allow error to be thrown if not included) + return new jQuery.fn.init( selector, context ); + }; + +jQuery.fn = jQuery.prototype = { + + // The current version of jQuery being used + jquery: version, + + constructor: jQuery, + + // The default length of a jQuery object is 0 + length: 0, + + toArray: function() { + return slice.call( this ); + }, + + // Get the Nth element in the matched element set OR + // Get the whole matched element set as a clean array + get: function( num ) { + + // Return all the elements in a clean array + if ( num == null ) { + return slice.call( this ); + } + + // Return just the one element from the set + return num < 0 ? this[ num + this.length ] : this[ num ]; + }, + + // Take an array of elements and push it onto the stack + // (returning the new matched element set) + pushStack: function( elems ) { + + // Build a new jQuery matched element set + var ret = jQuery.merge( this.constructor(), elems ); + + // Add the old object onto the stack (as a reference) + ret.prevObject = this; + + // Return the newly-formed element set + return ret; + }, + + // Execute a callback for every element in the matched set. + each: function( callback ) { + return jQuery.each( this, callback ); + }, + + map: function( callback ) { + return this.pushStack( jQuery.map( this, function( elem, i ) { + return callback.call( elem, i, elem ); + } ) ); + }, + + slice: function() { + return this.pushStack( slice.apply( this, arguments ) ); + }, + + first: function() { + return this.eq( 0 ); + }, + + last: function() { + return this.eq( -1 ); + }, + + even: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return ( i + 1 ) % 2; + } ) ); + }, + + odd: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return i % 2; + } ) ); + }, + + eq: function( i ) { + var len = this.length, + j = +i + ( i < 0 ? len : 0 ); + return this.pushStack( j >= 0 && j < len ? [ this[ j ] ] : [] ); + }, + + end: function() { + return this.prevObject || this.constructor(); + }, + + // For internal use only. + // Behaves like an Array's method, not like a jQuery method. + push: push, + sort: arr.sort, + splice: arr.splice +}; + +jQuery.extend = jQuery.fn.extend = function() { + var options, name, src, copy, copyIsArray, clone, + target = arguments[ 0 ] || {}, + i = 1, + length = arguments.length, + deep = false; + + // Handle a deep copy situation + if ( typeof target === "boolean" ) { + deep = target; + + // Skip the boolean and the target + target = arguments[ i ] || {}; + i++; + } + + // Handle case when target is a string or something (possible in deep copy) + if ( typeof target !== "object" && !isFunction( target ) ) { + target = {}; + } + + // Extend jQuery itself if only one argument is passed + if ( i === length ) { + target = this; + i--; + } + + for ( ; i < length; i++ ) { + + // Only deal with non-null/undefined values + if ( ( options = arguments[ i ] ) != null ) { + + // Extend the base object + for ( name in options ) { + copy = options[ name ]; + + // Prevent Object.prototype pollution + // Prevent never-ending loop + if ( name === "__proto__" || target === copy ) { + continue; + } + + // Recurse if we're merging plain objects or arrays + if ( deep && copy && ( jQuery.isPlainObject( copy ) || + ( copyIsArray = Array.isArray( copy ) ) ) ) { + src = target[ name ]; + + // Ensure proper type for the source value + if ( copyIsArray && !Array.isArray( src ) ) { + clone = []; + } else if ( !copyIsArray && !jQuery.isPlainObject( src ) ) { + clone = {}; + } else { + clone = src; + } + copyIsArray = false; + + // Never move original objects, clone them + target[ name ] = jQuery.extend( deep, clone, copy ); + + // Don't bring in undefined values + } else if ( copy !== undefined ) { + target[ name ] = copy; + } + } + } + } + + // Return the modified object + return target; +}; + +jQuery.extend( { + + // Unique for each copy of jQuery on the page + expando: "jQuery" + ( version + Math.random() ).replace( /\D/g, "" ), + + // Assume jQuery is ready without the ready module + isReady: true, + + error: function( msg ) { + throw new Error( msg ); + }, + + noop: function() {}, + + isPlainObject: function( obj ) { + var proto, Ctor; + + // Detect obvious negatives + // Use toString instead of jQuery.type to catch host objects + if ( !obj || toString.call( obj ) !== "[object Object]" ) { + return false; + } + + proto = getProto( obj ); + + // Objects with no prototype (e.g., `Object.create( null )`) are plain + if ( !proto ) { + return true; + } + + // Objects with prototype are plain iff they were constructed by a global Object function + Ctor = hasOwn.call( proto, "constructor" ) && proto.constructor; + return typeof Ctor === "function" && fnToString.call( Ctor ) === ObjectFunctionString; + }, + + isEmptyObject: function( obj ) { + var name; + + for ( name in obj ) { + return false; + } + return true; + }, + + // Evaluates a script in a provided context; falls back to the global one + // if not specified. + globalEval: function( code, options, doc ) { + DOMEval( code, { nonce: options && options.nonce }, doc ); + }, + + each: function( obj, callback ) { + var length, i = 0; + + if ( isArrayLike( obj ) ) { + length = obj.length; + for ( ; i < length; i++ ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } else { + for ( i in obj ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } + + return obj; + }, + + // results is for internal usage only + makeArray: function( arr, results ) { + var ret = results || []; + + if ( arr != null ) { + if ( isArrayLike( Object( arr ) ) ) { + jQuery.merge( ret, + typeof arr === "string" ? + [ arr ] : arr + ); + } else { + push.call( ret, arr ); + } + } + + return ret; + }, + + inArray: function( elem, arr, i ) { + return arr == null ? -1 : indexOf.call( arr, elem, i ); + }, + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + merge: function( first, second ) { + var len = +second.length, + j = 0, + i = first.length; + + for ( ; j < len; j++ ) { + first[ i++ ] = second[ j ]; + } + + first.length = i; + + return first; + }, + + grep: function( elems, callback, invert ) { + var callbackInverse, + matches = [], + i = 0, + length = elems.length, + callbackExpect = !invert; + + // Go through the array, only saving the items + // that pass the validator function + for ( ; i < length; i++ ) { + callbackInverse = !callback( elems[ i ], i ); + if ( callbackInverse !== callbackExpect ) { + matches.push( elems[ i ] ); + } + } + + return matches; + }, + + // arg is for internal usage only + map: function( elems, callback, arg ) { + var length, value, + i = 0, + ret = []; + + // Go through the array, translating each of the items to their new values + if ( isArrayLike( elems ) ) { + length = elems.length; + for ( ; i < length; i++ ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + + // Go through every key on the object, + } else { + for ( i in elems ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + } + + // Flatten any nested arrays + return flat( ret ); + }, + + // A global GUID counter for objects + guid: 1, + + // jQuery.support is not used in Core but other projects attach their + // properties to it so it needs to exist. + support: support +} ); + +if ( typeof Symbol === "function" ) { + jQuery.fn[ Symbol.iterator ] = arr[ Symbol.iterator ]; +} + +// Populate the class2type map +jQuery.each( "Boolean Number String Function Array Date RegExp Object Error Symbol".split( " " ), +function( _i, name ) { + class2type[ "[object " + name + "]" ] = name.toLowerCase(); +} ); + +function isArrayLike( obj ) { + + // Support: real iOS 8.2 only (not reproducible in simulator) + // `in` check used to prevent JIT error (gh-2145) + // hasOwn isn't used here due to false negatives + // regarding Nodelist length in IE + var length = !!obj && "length" in obj && obj.length, + type = toType( obj ); + + if ( isFunction( obj ) || isWindow( obj ) ) { + return false; + } + + return type === "array" || length === 0 || + typeof length === "number" && length > 0 && ( length - 1 ) in obj; +} +var Sizzle = +/*! + * Sizzle CSS Selector Engine v2.3.5 + * https://sizzlejs.com/ + * + * Copyright JS Foundation and other contributors + * Released under the MIT license + * https://js.foundation/ + * + * Date: 2020-03-14 + */ +( function( window ) { +var i, + support, + Expr, + getText, + isXML, + tokenize, + compile, + select, + outermostContext, + sortInput, + hasDuplicate, + + // Local document vars + setDocument, + document, + docElem, + documentIsHTML, + rbuggyQSA, + rbuggyMatches, + matches, + contains, + + // Instance-specific data + expando = "sizzle" + 1 * new Date(), + preferredDoc = window.document, + dirruns = 0, + done = 0, + classCache = createCache(), + tokenCache = createCache(), + compilerCache = createCache(), + nonnativeSelectorCache = createCache(), + sortOrder = function( a, b ) { + if ( a === b ) { + hasDuplicate = true; + } + return 0; + }, + + // Instance methods + hasOwn = ( {} ).hasOwnProperty, + arr = [], + pop = arr.pop, + pushNative = arr.push, + push = arr.push, + slice = arr.slice, + + // Use a stripped-down indexOf as it's faster than native + // https://jsperf.com/thor-indexof-vs-for/5 + indexOf = function( list, elem ) { + var i = 0, + len = list.length; + for ( ; i < len; i++ ) { + if ( list[ i ] === elem ) { + return i; + } + } + return -1; + }, + + booleans = "checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|" + + "ismap|loop|multiple|open|readonly|required|scoped", + + // Regular expressions + + // http://www.w3.org/TR/css3-selectors/#whitespace + whitespace = "[\\x20\\t\\r\\n\\f]", + + // https://www.w3.org/TR/css-syntax-3/#ident-token-diagram + identifier = "(?:\\\\[\\da-fA-F]{1,6}" + whitespace + + "?|\\\\[^\\r\\n\\f]|[\\w-]|[^\0-\\x7f])+", + + // Attribute selectors: http://www.w3.org/TR/selectors/#attribute-selectors + attributes = "\\[" + whitespace + "*(" + identifier + ")(?:" + whitespace + + + // Operator (capture 2) + "*([*^$|!~]?=)" + whitespace + + + // "Attribute values must be CSS identifiers [capture 5] + // or strings [capture 3 or capture 4]" + "*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|(" + identifier + "))|)" + + whitespace + "*\\]", + + pseudos = ":(" + identifier + ")(?:\\((" + + + // To reduce the number of selectors needing tokenize in the preFilter, prefer arguments: + // 1. quoted (capture 3; capture 4 or capture 5) + "('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|" + + + // 2. simple (capture 6) + "((?:\\\\.|[^\\\\()[\\]]|" + attributes + ")*)|" + + + // 3. anything else (capture 2) + ".*" + + ")\\)|)", + + // Leading and non-escaped trailing whitespace, capturing some non-whitespace characters preceding the latter + rwhitespace = new RegExp( whitespace + "+", "g" ), + rtrim = new RegExp( "^" + whitespace + "+|((?:^|[^\\\\])(?:\\\\.)*)" + + whitespace + "+$", "g" ), + + rcomma = new RegExp( "^" + whitespace + "*," + whitespace + "*" ), + rcombinators = new RegExp( "^" + whitespace + "*([>+~]|" + whitespace + ")" + whitespace + + "*" ), + rdescend = new RegExp( whitespace + "|>" ), + + rpseudo = new RegExp( pseudos ), + ridentifier = new RegExp( "^" + identifier + "$" ), + + matchExpr = { + "ID": new RegExp( "^#(" + identifier + ")" ), + "CLASS": new RegExp( "^\\.(" + identifier + ")" ), + "TAG": new RegExp( "^(" + identifier + "|[*])" ), + "ATTR": new RegExp( "^" + attributes ), + "PSEUDO": new RegExp( "^" + pseudos ), + "CHILD": new RegExp( "^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\(" + + whitespace + "*(even|odd|(([+-]|)(\\d*)n|)" + whitespace + "*(?:([+-]|)" + + whitespace + "*(\\d+)|))" + whitespace + "*\\)|)", "i" ), + "bool": new RegExp( "^(?:" + booleans + ")$", "i" ), + + // For use in libraries implementing .is() + // We use this for POS matching in `select` + "needsContext": new RegExp( "^" + whitespace + + "*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\(" + whitespace + + "*((?:-\\d)?\\d*)" + whitespace + "*\\)|)(?=[^-]|$)", "i" ) + }, + + rhtml = /HTML$/i, + rinputs = /^(?:input|select|textarea|button)$/i, + rheader = /^h\d$/i, + + rnative = /^[^{]+\{\s*\[native \w/, + + // Easily-parseable/retrievable ID or TAG or CLASS selectors + rquickExpr = /^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/, + + rsibling = /[+~]/, + + // CSS escapes + // http://www.w3.org/TR/CSS21/syndata.html#escaped-characters + runescape = new RegExp( "\\\\[\\da-fA-F]{1,6}" + whitespace + "?|\\\\([^\\r\\n\\f])", "g" ), + funescape = function( escape, nonHex ) { + var high = "0x" + escape.slice( 1 ) - 0x10000; + + return nonHex ? + + // Strip the backslash prefix from a non-hex escape sequence + nonHex : + + // Replace a hexadecimal escape sequence with the encoded Unicode code point + // Support: IE <=11+ + // For values outside the Basic Multilingual Plane (BMP), manually construct a + // surrogate pair + high < 0 ? + String.fromCharCode( high + 0x10000 ) : + String.fromCharCode( high >> 10 | 0xD800, high & 0x3FF | 0xDC00 ); + }, + + // CSS string/identifier serialization + // https://drafts.csswg.org/cssom/#common-serializing-idioms + rcssescape = /([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g, + fcssescape = function( ch, asCodePoint ) { + if ( asCodePoint ) { + + // U+0000 NULL becomes U+FFFD REPLACEMENT CHARACTER + if ( ch === "\0" ) { + return "\uFFFD"; + } + + // Control characters and (dependent upon position) numbers get escaped as code points + return ch.slice( 0, -1 ) + "\\" + + ch.charCodeAt( ch.length - 1 ).toString( 16 ) + " "; + } + + // Other potentially-special ASCII characters get backslash-escaped + return "\\" + ch; + }, + + // Used for iframes + // See setDocument() + // Removing the function wrapper causes a "Permission Denied" + // error in IE + unloadHandler = function() { + setDocument(); + }, + + inDisabledFieldset = addCombinator( + function( elem ) { + return elem.disabled === true && elem.nodeName.toLowerCase() === "fieldset"; + }, + { dir: "parentNode", next: "legend" } + ); + +// Optimize for push.apply( _, NodeList ) +try { + push.apply( + ( arr = slice.call( preferredDoc.childNodes ) ), + preferredDoc.childNodes + ); + + // Support: Android<4.0 + // Detect silently failing push.apply + // eslint-disable-next-line no-unused-expressions + arr[ preferredDoc.childNodes.length ].nodeType; +} catch ( e ) { + push = { apply: arr.length ? + + // Leverage slice if possible + function( target, els ) { + pushNative.apply( target, slice.call( els ) ); + } : + + // Support: IE<9 + // Otherwise append directly + function( target, els ) { + var j = target.length, + i = 0; + + // Can't trust NodeList.length + while ( ( target[ j++ ] = els[ i++ ] ) ) {} + target.length = j - 1; + } + }; +} + +function Sizzle( selector, context, results, seed ) { + var m, i, elem, nid, match, groups, newSelector, + newContext = context && context.ownerDocument, + + // nodeType defaults to 9, since context defaults to document + nodeType = context ? context.nodeType : 9; + + results = results || []; + + // Return early from calls with invalid selector or context + if ( typeof selector !== "string" || !selector || + nodeType !== 1 && nodeType !== 9 && nodeType !== 11 ) { + + return results; + } + + // Try to shortcut find operations (as opposed to filters) in HTML documents + if ( !seed ) { + setDocument( context ); + context = context || document; + + if ( documentIsHTML ) { + + // If the selector is sufficiently simple, try using a "get*By*" DOM method + // (excepting DocumentFragment context, where the methods don't exist) + if ( nodeType !== 11 && ( match = rquickExpr.exec( selector ) ) ) { + + // ID selector + if ( ( m = match[ 1 ] ) ) { + + // Document context + if ( nodeType === 9 ) { + if ( ( elem = context.getElementById( m ) ) ) { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( elem.id === m ) { + results.push( elem ); + return results; + } + } else { + return results; + } + + // Element context + } else { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( newContext && ( elem = newContext.getElementById( m ) ) && + contains( context, elem ) && + elem.id === m ) { + + results.push( elem ); + return results; + } + } + + // Type selector + } else if ( match[ 2 ] ) { + push.apply( results, context.getElementsByTagName( selector ) ); + return results; + + // Class selector + } else if ( ( m = match[ 3 ] ) && support.getElementsByClassName && + context.getElementsByClassName ) { + + push.apply( results, context.getElementsByClassName( m ) ); + return results; + } + } + + // Take advantage of querySelectorAll + if ( support.qsa && + !nonnativeSelectorCache[ selector + " " ] && + ( !rbuggyQSA || !rbuggyQSA.test( selector ) ) && + + // Support: IE 8 only + // Exclude object elements + ( nodeType !== 1 || context.nodeName.toLowerCase() !== "object" ) ) { + + newSelector = selector; + newContext = context; + + // qSA considers elements outside a scoping root when evaluating child or + // descendant combinators, which is not what we want. + // In such cases, we work around the behavior by prefixing every selector in the + // list with an ID selector referencing the scope context. + // The technique has to be used as well when a leading combinator is used + // as such selectors are not recognized by querySelectorAll. + // Thanks to Andrew Dupont for this technique. + if ( nodeType === 1 && + ( rdescend.test( selector ) || rcombinators.test( selector ) ) ) { + + // Expand context for sibling selectors + newContext = rsibling.test( selector ) && testContext( context.parentNode ) || + context; + + // We can use :scope instead of the ID hack if the browser + // supports it & if we're not changing the context. + if ( newContext !== context || !support.scope ) { + + // Capture the context ID, setting it first if necessary + if ( ( nid = context.getAttribute( "id" ) ) ) { + nid = nid.replace( rcssescape, fcssescape ); + } else { + context.setAttribute( "id", ( nid = expando ) ); + } + } + + // Prefix every selector in the list + groups = tokenize( selector ); + i = groups.length; + while ( i-- ) { + groups[ i ] = ( nid ? "#" + nid : ":scope" ) + " " + + toSelector( groups[ i ] ); + } + newSelector = groups.join( "," ); + } + + try { + push.apply( results, + newContext.querySelectorAll( newSelector ) + ); + return results; + } catch ( qsaError ) { + nonnativeSelectorCache( selector, true ); + } finally { + if ( nid === expando ) { + context.removeAttribute( "id" ); + } + } + } + } + } + + // All others + return select( selector.replace( rtrim, "$1" ), context, results, seed ); +} + +/** + * Create key-value caches of limited size + * @returns {function(string, object)} Returns the Object data after storing it on itself with + * property name the (space-suffixed) string and (if the cache is larger than Expr.cacheLength) + * deleting the oldest entry + */ +function createCache() { + var keys = []; + + function cache( key, value ) { + + // Use (key + " ") to avoid collision with native prototype properties (see Issue #157) + if ( keys.push( key + " " ) > Expr.cacheLength ) { + + // Only keep the most recent entries + delete cache[ keys.shift() ]; + } + return ( cache[ key + " " ] = value ); + } + return cache; +} + +/** + * Mark a function for special use by Sizzle + * @param {Function} fn The function to mark + */ +function markFunction( fn ) { + fn[ expando ] = true; + return fn; +} + +/** + * Support testing using an element + * @param {Function} fn Passed the created element and returns a boolean result + */ +function assert( fn ) { + var el = document.createElement( "fieldset" ); + + try { + return !!fn( el ); + } catch ( e ) { + return false; + } finally { + + // Remove from its parent by default + if ( el.parentNode ) { + el.parentNode.removeChild( el ); + } + + // release memory in IE + el = null; + } +} + +/** + * Adds the same handler for all of the specified attrs + * @param {String} attrs Pipe-separated list of attributes + * @param {Function} handler The method that will be applied + */ +function addHandle( attrs, handler ) { + var arr = attrs.split( "|" ), + i = arr.length; + + while ( i-- ) { + Expr.attrHandle[ arr[ i ] ] = handler; + } +} + +/** + * Checks document order of two siblings + * @param {Element} a + * @param {Element} b + * @returns {Number} Returns less than 0 if a precedes b, greater than 0 if a follows b + */ +function siblingCheck( a, b ) { + var cur = b && a, + diff = cur && a.nodeType === 1 && b.nodeType === 1 && + a.sourceIndex - b.sourceIndex; + + // Use IE sourceIndex if available on both nodes + if ( diff ) { + return diff; + } + + // Check if b follows a + if ( cur ) { + while ( ( cur = cur.nextSibling ) ) { + if ( cur === b ) { + return -1; + } + } + } + + return a ? 1 : -1; +} + +/** + * Returns a function to use in pseudos for input types + * @param {String} type + */ +function createInputPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for buttons + * @param {String} type + */ +function createButtonPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return ( name === "input" || name === "button" ) && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for :enabled/:disabled + * @param {Boolean} disabled true for :disabled; false for :enabled + */ +function createDisabledPseudo( disabled ) { + + // Known :disabled false positives: fieldset[disabled] > legend:nth-of-type(n+2) :can-disable + return function( elem ) { + + // Only certain elements can match :enabled or :disabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-enabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-disabled + if ( "form" in elem ) { + + // Check for inherited disabledness on relevant non-disabled elements: + // * listed form-associated elements in a disabled fieldset + // https://html.spec.whatwg.org/multipage/forms.html#category-listed + // https://html.spec.whatwg.org/multipage/forms.html#concept-fe-disabled + // * option elements in a disabled optgroup + // https://html.spec.whatwg.org/multipage/forms.html#concept-option-disabled + // All such elements have a "form" property. + if ( elem.parentNode && elem.disabled === false ) { + + // Option elements defer to a parent optgroup if present + if ( "label" in elem ) { + if ( "label" in elem.parentNode ) { + return elem.parentNode.disabled === disabled; + } else { + return elem.disabled === disabled; + } + } + + // Support: IE 6 - 11 + // Use the isDisabled shortcut property to check for disabled fieldset ancestors + return elem.isDisabled === disabled || + + // Where there is no isDisabled, check manually + /* jshint -W018 */ + elem.isDisabled !== !disabled && + inDisabledFieldset( elem ) === disabled; + } + + return elem.disabled === disabled; + + // Try to winnow out elements that can't be disabled before trusting the disabled property. + // Some victims get caught in our net (label, legend, menu, track), but it shouldn't + // even exist on them, let alone have a boolean value. + } else if ( "label" in elem ) { + return elem.disabled === disabled; + } + + // Remaining elements are neither :enabled nor :disabled + return false; + }; +} + +/** + * Returns a function to use in pseudos for positionals + * @param {Function} fn + */ +function createPositionalPseudo( fn ) { + return markFunction( function( argument ) { + argument = +argument; + return markFunction( function( seed, matches ) { + var j, + matchIndexes = fn( [], seed.length, argument ), + i = matchIndexes.length; + + // Match elements found at the specified indexes + while ( i-- ) { + if ( seed[ ( j = matchIndexes[ i ] ) ] ) { + seed[ j ] = !( matches[ j ] = seed[ j ] ); + } + } + } ); + } ); +} + +/** + * Checks a node for validity as a Sizzle context + * @param {Element|Object=} context + * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value + */ +function testContext( context ) { + return context && typeof context.getElementsByTagName !== "undefined" && context; +} + +// Expose support vars for convenience +support = Sizzle.support = {}; + +/** + * Detects XML nodes + * @param {Element|Object} elem An element or a document + * @returns {Boolean} True iff elem is a non-HTML XML node + */ +isXML = Sizzle.isXML = function( elem ) { + var namespace = elem.namespaceURI, + docElem = ( elem.ownerDocument || elem ).documentElement; + + // Support: IE <=8 + // Assume HTML when documentElement doesn't yet exist, such as inside loading iframes + // https://bugs.jquery.com/ticket/4833 + return !rhtml.test( namespace || docElem && docElem.nodeName || "HTML" ); +}; + +/** + * Sets document-related variables once based on the current document + * @param {Element|Object} [doc] An element or document object to use to set the document + * @returns {Object} Returns the current document + */ +setDocument = Sizzle.setDocument = function( node ) { + var hasCompare, subWindow, + doc = node ? node.ownerDocument || node : preferredDoc; + + // Return early if doc is invalid or already selected + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( doc == document || doc.nodeType !== 9 || !doc.documentElement ) { + return document; + } + + // Update global variables + document = doc; + docElem = document.documentElement; + documentIsHTML = !isXML( document ); + + // Support: IE 9 - 11+, Edge 12 - 18+ + // Accessing iframe documents after unload throws "permission denied" errors (jQuery #13936) + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( preferredDoc != document && + ( subWindow = document.defaultView ) && subWindow.top !== subWindow ) { + + // Support: IE 11, Edge + if ( subWindow.addEventListener ) { + subWindow.addEventListener( "unload", unloadHandler, false ); + + // Support: IE 9 - 10 only + } else if ( subWindow.attachEvent ) { + subWindow.attachEvent( "onunload", unloadHandler ); + } + } + + // Support: IE 8 - 11+, Edge 12 - 18+, Chrome <=16 - 25 only, Firefox <=3.6 - 31 only, + // Safari 4 - 5 only, Opera <=11.6 - 12.x only + // IE/Edge & older browsers don't support the :scope pseudo-class. + // Support: Safari 6.0 only + // Safari 6.0 supports :scope but it's an alias of :root there. + support.scope = assert( function( el ) { + docElem.appendChild( el ).appendChild( document.createElement( "div" ) ); + return typeof el.querySelectorAll !== "undefined" && + !el.querySelectorAll( ":scope fieldset div" ).length; + } ); + + /* Attributes + ---------------------------------------------------------------------- */ + + // Support: IE<8 + // Verify that getAttribute really returns attributes and not properties + // (excepting IE8 booleans) + support.attributes = assert( function( el ) { + el.className = "i"; + return !el.getAttribute( "className" ); + } ); + + /* getElement(s)By* + ---------------------------------------------------------------------- */ + + // Check if getElementsByTagName("*") returns only elements + support.getElementsByTagName = assert( function( el ) { + el.appendChild( document.createComment( "" ) ); + return !el.getElementsByTagName( "*" ).length; + } ); + + // Support: IE<9 + support.getElementsByClassName = rnative.test( document.getElementsByClassName ); + + // Support: IE<10 + // Check if getElementById returns elements by name + // The broken getElementById methods don't pick up programmatically-set names, + // so use a roundabout getElementsByName test + support.getById = assert( function( el ) { + docElem.appendChild( el ).id = expando; + return !document.getElementsByName || !document.getElementsByName( expando ).length; + } ); + + // ID filter and find + if ( support.getById ) { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + return elem.getAttribute( "id" ) === attrId; + }; + }; + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var elem = context.getElementById( id ); + return elem ? [ elem ] : []; + } + }; + } else { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + var node = typeof elem.getAttributeNode !== "undefined" && + elem.getAttributeNode( "id" ); + return node && node.value === attrId; + }; + }; + + // Support: IE 6 - 7 only + // getElementById is not reliable as a find shortcut + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var node, i, elems, + elem = context.getElementById( id ); + + if ( elem ) { + + // Verify the id attribute + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + + // Fall back on getElementsByName + elems = context.getElementsByName( id ); + i = 0; + while ( ( elem = elems[ i++ ] ) ) { + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + } + } + + return []; + } + }; + } + + // Tag + Expr.find[ "TAG" ] = support.getElementsByTagName ? + function( tag, context ) { + if ( typeof context.getElementsByTagName !== "undefined" ) { + return context.getElementsByTagName( tag ); + + // DocumentFragment nodes don't have gEBTN + } else if ( support.qsa ) { + return context.querySelectorAll( tag ); + } + } : + + function( tag, context ) { + var elem, + tmp = [], + i = 0, + + // By happy coincidence, a (broken) gEBTN appears on DocumentFragment nodes too + results = context.getElementsByTagName( tag ); + + // Filter out possible comments + if ( tag === "*" ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem.nodeType === 1 ) { + tmp.push( elem ); + } + } + + return tmp; + } + return results; + }; + + // Class + Expr.find[ "CLASS" ] = support.getElementsByClassName && function( className, context ) { + if ( typeof context.getElementsByClassName !== "undefined" && documentIsHTML ) { + return context.getElementsByClassName( className ); + } + }; + + /* QSA/matchesSelector + ---------------------------------------------------------------------- */ + + // QSA and matchesSelector support + + // matchesSelector(:active) reports false when true (IE9/Opera 11.5) + rbuggyMatches = []; + + // qSa(:focus) reports false when true (Chrome 21) + // We allow this because of a bug in IE8/9 that throws an error + // whenever `document.activeElement` is accessed on an iframe + // So, we allow :focus to pass through QSA all the time to avoid the IE error + // See https://bugs.jquery.com/ticket/13378 + rbuggyQSA = []; + + if ( ( support.qsa = rnative.test( document.querySelectorAll ) ) ) { + + // Build QSA regex + // Regex strategy adopted from Diego Perini + assert( function( el ) { + + var input; + + // Select is set to empty string on purpose + // This is to test IE's treatment of not explicitly + // setting a boolean content attribute, + // since its presence should be enough + // https://bugs.jquery.com/ticket/12359 + docElem.appendChild( el ).innerHTML = "<a id='" + expando + "'></a>" + + "<select id='" + expando + "-\r\\' msallowcapture=''>" + + "<option selected=''></option></select>"; + + // Support: IE8, Opera 11-12.16 + // Nothing should be selected when empty strings follow ^= or $= or *= + // The test attribute must be unknown in Opera but "safe" for WinRT + // https://msdn.microsoft.com/en-us/library/ie/hh465388.aspx#attribute_section + if ( el.querySelectorAll( "[msallowcapture^='']" ).length ) { + rbuggyQSA.push( "[*^$]=" + whitespace + "*(?:''|\"\")" ); + } + + // Support: IE8 + // Boolean attributes and "value" are not treated correctly + if ( !el.querySelectorAll( "[selected]" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*(?:value|" + booleans + ")" ); + } + + // Support: Chrome<29, Android<4.4, Safari<7.0+, iOS<7.0+, PhantomJS<1.9.8+ + if ( !el.querySelectorAll( "[id~=" + expando + "-]" ).length ) { + rbuggyQSA.push( "~=" ); + } + + // Support: IE 11+, Edge 15 - 18+ + // IE 11/Edge don't find elements on a `[name='']` query in some cases. + // Adding a temporary attribute to the document before the selection works + // around the issue. + // Interestingly, IE 10 & older don't seem to have the issue. + input = document.createElement( "input" ); + input.setAttribute( "name", "" ); + el.appendChild( input ); + if ( !el.querySelectorAll( "[name='']" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*name" + whitespace + "*=" + + whitespace + "*(?:''|\"\")" ); + } + + // Webkit/Opera - :checked should return selected option elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + // IE8 throws error here and will not see later tests + if ( !el.querySelectorAll( ":checked" ).length ) { + rbuggyQSA.push( ":checked" ); + } + + // Support: Safari 8+, iOS 8+ + // https://bugs.webkit.org/show_bug.cgi?id=136851 + // In-page `selector#id sibling-combinator selector` fails + if ( !el.querySelectorAll( "a#" + expando + "+*" ).length ) { + rbuggyQSA.push( ".#.+[+~]" ); + } + + // Support: Firefox <=3.6 - 5 only + // Old Firefox doesn't throw on a badly-escaped identifier. + el.querySelectorAll( "\\\f" ); + rbuggyQSA.push( "[\\r\\n\\f]" ); + } ); + + assert( function( el ) { + el.innerHTML = "<a href='' disabled='disabled'></a>" + + "<select disabled='disabled'><option/></select>"; + + // Support: Windows 8 Native Apps + // The type and name attributes are restricted during .innerHTML assignment + var input = document.createElement( "input" ); + input.setAttribute( "type", "hidden" ); + el.appendChild( input ).setAttribute( "name", "D" ); + + // Support: IE8 + // Enforce case-sensitivity of name attribute + if ( el.querySelectorAll( "[name=d]" ).length ) { + rbuggyQSA.push( "name" + whitespace + "*[*^$|!~]?=" ); + } + + // FF 3.5 - :enabled/:disabled and hidden elements (hidden elements are still enabled) + // IE8 throws error here and will not see later tests + if ( el.querySelectorAll( ":enabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: IE9-11+ + // IE's :disabled selector does not pick up the children of disabled fieldsets + docElem.appendChild( el ).disabled = true; + if ( el.querySelectorAll( ":disabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: Opera 10 - 11 only + // Opera 10-11 does not throw on post-comma invalid pseudos + el.querySelectorAll( "*,:x" ); + rbuggyQSA.push( ",.*:" ); + } ); + } + + if ( ( support.matchesSelector = rnative.test( ( matches = docElem.matches || + docElem.webkitMatchesSelector || + docElem.mozMatchesSelector || + docElem.oMatchesSelector || + docElem.msMatchesSelector ) ) ) ) { + + assert( function( el ) { + + // Check to see if it's possible to do matchesSelector + // on a disconnected node (IE 9) + support.disconnectedMatch = matches.call( el, "*" ); + + // This should fail with an exception + // Gecko does not error, returns false instead + matches.call( el, "[s!='']:x" ); + rbuggyMatches.push( "!=", pseudos ); + } ); + } + + rbuggyQSA = rbuggyQSA.length && new RegExp( rbuggyQSA.join( "|" ) ); + rbuggyMatches = rbuggyMatches.length && new RegExp( rbuggyMatches.join( "|" ) ); + + /* Contains + ---------------------------------------------------------------------- */ + hasCompare = rnative.test( docElem.compareDocumentPosition ); + + // Element contains another + // Purposefully self-exclusive + // As in, an element does not contain itself + contains = hasCompare || rnative.test( docElem.contains ) ? + function( a, b ) { + var adown = a.nodeType === 9 ? a.documentElement : a, + bup = b && b.parentNode; + return a === bup || !!( bup && bup.nodeType === 1 && ( + adown.contains ? + adown.contains( bup ) : + a.compareDocumentPosition && a.compareDocumentPosition( bup ) & 16 + ) ); + } : + function( a, b ) { + if ( b ) { + while ( ( b = b.parentNode ) ) { + if ( b === a ) { + return true; + } + } + } + return false; + }; + + /* Sorting + ---------------------------------------------------------------------- */ + + // Document order sorting + sortOrder = hasCompare ? + function( a, b ) { + + // Flag for duplicate removal + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + // Sort on method existence if only one input has compareDocumentPosition + var compare = !a.compareDocumentPosition - !b.compareDocumentPosition; + if ( compare ) { + return compare; + } + + // Calculate position if both inputs belong to the same document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + compare = ( a.ownerDocument || a ) == ( b.ownerDocument || b ) ? + a.compareDocumentPosition( b ) : + + // Otherwise we know they are disconnected + 1; + + // Disconnected nodes + if ( compare & 1 || + ( !support.sortDetached && b.compareDocumentPosition( a ) === compare ) ) { + + // Choose the first element that is related to our preferred document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( a == document || a.ownerDocument == preferredDoc && + contains( preferredDoc, a ) ) { + return -1; + } + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( b == document || b.ownerDocument == preferredDoc && + contains( preferredDoc, b ) ) { + return 1; + } + + // Maintain original order + return sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + } + + return compare & 4 ? -1 : 1; + } : + function( a, b ) { + + // Exit early if the nodes are identical + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + var cur, + i = 0, + aup = a.parentNode, + bup = b.parentNode, + ap = [ a ], + bp = [ b ]; + + // Parentless nodes are either documents or disconnected + if ( !aup || !bup ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + return a == document ? -1 : + b == document ? 1 : + /* eslint-enable eqeqeq */ + aup ? -1 : + bup ? 1 : + sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + + // If the nodes are siblings, we can do a quick check + } else if ( aup === bup ) { + return siblingCheck( a, b ); + } + + // Otherwise we need full lists of their ancestors for comparison + cur = a; + while ( ( cur = cur.parentNode ) ) { + ap.unshift( cur ); + } + cur = b; + while ( ( cur = cur.parentNode ) ) { + bp.unshift( cur ); + } + + // Walk down the tree looking for a discrepancy + while ( ap[ i ] === bp[ i ] ) { + i++; + } + + return i ? + + // Do a sibling check if the nodes have a common ancestor + siblingCheck( ap[ i ], bp[ i ] ) : + + // Otherwise nodes in our document sort first + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + ap[ i ] == preferredDoc ? -1 : + bp[ i ] == preferredDoc ? 1 : + /* eslint-enable eqeqeq */ + 0; + }; + + return document; +}; + +Sizzle.matches = function( expr, elements ) { + return Sizzle( expr, null, null, elements ); +}; + +Sizzle.matchesSelector = function( elem, expr ) { + setDocument( elem ); + + if ( support.matchesSelector && documentIsHTML && + !nonnativeSelectorCache[ expr + " " ] && + ( !rbuggyMatches || !rbuggyMatches.test( expr ) ) && + ( !rbuggyQSA || !rbuggyQSA.test( expr ) ) ) { + + try { + var ret = matches.call( elem, expr ); + + // IE 9's matchesSelector returns false on disconnected nodes + if ( ret || support.disconnectedMatch || + + // As well, disconnected nodes are said to be in a document + // fragment in IE 9 + elem.document && elem.document.nodeType !== 11 ) { + return ret; + } + } catch ( e ) { + nonnativeSelectorCache( expr, true ); + } + } + + return Sizzle( expr, document, null, [ elem ] ).length > 0; +}; + +Sizzle.contains = function( context, elem ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( context.ownerDocument || context ) != document ) { + setDocument( context ); + } + return contains( context, elem ); +}; + +Sizzle.attr = function( elem, name ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( elem.ownerDocument || elem ) != document ) { + setDocument( elem ); + } + + var fn = Expr.attrHandle[ name.toLowerCase() ], + + // Don't get fooled by Object.prototype properties (jQuery #13807) + val = fn && hasOwn.call( Expr.attrHandle, name.toLowerCase() ) ? + fn( elem, name, !documentIsHTML ) : + undefined; + + return val !== undefined ? + val : + support.attributes || !documentIsHTML ? + elem.getAttribute( name ) : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; +}; + +Sizzle.escape = function( sel ) { + return ( sel + "" ).replace( rcssescape, fcssescape ); +}; + +Sizzle.error = function( msg ) { + throw new Error( "Syntax error, unrecognized expression: " + msg ); +}; + +/** + * Document sorting and removing duplicates + * @param {ArrayLike} results + */ +Sizzle.uniqueSort = function( results ) { + var elem, + duplicates = [], + j = 0, + i = 0; + + // Unless we *know* we can detect duplicates, assume their presence + hasDuplicate = !support.detectDuplicates; + sortInput = !support.sortStable && results.slice( 0 ); + results.sort( sortOrder ); + + if ( hasDuplicate ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem === results[ i ] ) { + j = duplicates.push( i ); + } + } + while ( j-- ) { + results.splice( duplicates[ j ], 1 ); + } + } + + // Clear input after sorting to release objects + // See https://github.com/jquery/sizzle/pull/225 + sortInput = null; + + return results; +}; + +/** + * Utility function for retrieving the text value of an array of DOM nodes + * @param {Array|Element} elem + */ +getText = Sizzle.getText = function( elem ) { + var node, + ret = "", + i = 0, + nodeType = elem.nodeType; + + if ( !nodeType ) { + + // If no nodeType, this is expected to be an array + while ( ( node = elem[ i++ ] ) ) { + + // Do not traverse comment nodes + ret += getText( node ); + } + } else if ( nodeType === 1 || nodeType === 9 || nodeType === 11 ) { + + // Use textContent for elements + // innerText usage removed for consistency of new lines (jQuery #11153) + if ( typeof elem.textContent === "string" ) { + return elem.textContent; + } else { + + // Traverse its children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + ret += getText( elem ); + } + } + } else if ( nodeType === 3 || nodeType === 4 ) { + return elem.nodeValue; + } + + // Do not include comment or processing instruction nodes + + return ret; +}; + +Expr = Sizzle.selectors = { + + // Can be adjusted by the user + cacheLength: 50, + + createPseudo: markFunction, + + match: matchExpr, + + attrHandle: {}, + + find: {}, + + relative: { + ">": { dir: "parentNode", first: true }, + " ": { dir: "parentNode" }, + "+": { dir: "previousSibling", first: true }, + "~": { dir: "previousSibling" } + }, + + preFilter: { + "ATTR": function( match ) { + match[ 1 ] = match[ 1 ].replace( runescape, funescape ); + + // Move the given value to match[3] whether quoted or unquoted + match[ 3 ] = ( match[ 3 ] || match[ 4 ] || + match[ 5 ] || "" ).replace( runescape, funescape ); + + if ( match[ 2 ] === "~=" ) { + match[ 3 ] = " " + match[ 3 ] + " "; + } + + return match.slice( 0, 4 ); + }, + + "CHILD": function( match ) { + + /* matches from matchExpr["CHILD"] + 1 type (only|nth|...) + 2 what (child|of-type) + 3 argument (even|odd|\d*|\d*n([+-]\d+)?|...) + 4 xn-component of xn+y argument ([+-]?\d*n|) + 5 sign of xn-component + 6 x of xn-component + 7 sign of y-component + 8 y of y-component + */ + match[ 1 ] = match[ 1 ].toLowerCase(); + + if ( match[ 1 ].slice( 0, 3 ) === "nth" ) { + + // nth-* requires argument + if ( !match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + // numeric x and y parameters for Expr.filter.CHILD + // remember that false/true cast respectively to 0/1 + match[ 4 ] = +( match[ 4 ] ? + match[ 5 ] + ( match[ 6 ] || 1 ) : + 2 * ( match[ 3 ] === "even" || match[ 3 ] === "odd" ) ); + match[ 5 ] = +( ( match[ 7 ] + match[ 8 ] ) || match[ 3 ] === "odd" ); + + // other types prohibit arguments + } else if ( match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + return match; + }, + + "PSEUDO": function( match ) { + var excess, + unquoted = !match[ 6 ] && match[ 2 ]; + + if ( matchExpr[ "CHILD" ].test( match[ 0 ] ) ) { + return null; + } + + // Accept quoted arguments as-is + if ( match[ 3 ] ) { + match[ 2 ] = match[ 4 ] || match[ 5 ] || ""; + + // Strip excess characters from unquoted arguments + } else if ( unquoted && rpseudo.test( unquoted ) && + + // Get excess from tokenize (recursively) + ( excess = tokenize( unquoted, true ) ) && + + // advance to the next closing parenthesis + ( excess = unquoted.indexOf( ")", unquoted.length - excess ) - unquoted.length ) ) { + + // excess is a negative index + match[ 0 ] = match[ 0 ].slice( 0, excess ); + match[ 2 ] = unquoted.slice( 0, excess ); + } + + // Return only captures needed by the pseudo filter method (type and argument) + return match.slice( 0, 3 ); + } + }, + + filter: { + + "TAG": function( nodeNameSelector ) { + var nodeName = nodeNameSelector.replace( runescape, funescape ).toLowerCase(); + return nodeNameSelector === "*" ? + function() { + return true; + } : + function( elem ) { + return elem.nodeName && elem.nodeName.toLowerCase() === nodeName; + }; + }, + + "CLASS": function( className ) { + var pattern = classCache[ className + " " ]; + + return pattern || + ( pattern = new RegExp( "(^|" + whitespace + + ")" + className + "(" + whitespace + "|$)" ) ) && classCache( + className, function( elem ) { + return pattern.test( + typeof elem.className === "string" && elem.className || + typeof elem.getAttribute !== "undefined" && + elem.getAttribute( "class" ) || + "" + ); + } ); + }, + + "ATTR": function( name, operator, check ) { + return function( elem ) { + var result = Sizzle.attr( elem, name ); + + if ( result == null ) { + return operator === "!="; + } + if ( !operator ) { + return true; + } + + result += ""; + + /* eslint-disable max-len */ + + return operator === "=" ? result === check : + operator === "!=" ? result !== check : + operator === "^=" ? check && result.indexOf( check ) === 0 : + operator === "*=" ? check && result.indexOf( check ) > -1 : + operator === "$=" ? check && result.slice( -check.length ) === check : + operator === "~=" ? ( " " + result.replace( rwhitespace, " " ) + " " ).indexOf( check ) > -1 : + operator === "|=" ? result === check || result.slice( 0, check.length + 1 ) === check + "-" : + false; + /* eslint-enable max-len */ + + }; + }, + + "CHILD": function( type, what, _argument, first, last ) { + var simple = type.slice( 0, 3 ) !== "nth", + forward = type.slice( -4 ) !== "last", + ofType = what === "of-type"; + + return first === 1 && last === 0 ? + + // Shortcut for :nth-*(n) + function( elem ) { + return !!elem.parentNode; + } : + + function( elem, _context, xml ) { + var cache, uniqueCache, outerCache, node, nodeIndex, start, + dir = simple !== forward ? "nextSibling" : "previousSibling", + parent = elem.parentNode, + name = ofType && elem.nodeName.toLowerCase(), + useCache = !xml && !ofType, + diff = false; + + if ( parent ) { + + // :(first|last|only)-(child|of-type) + if ( simple ) { + while ( dir ) { + node = elem; + while ( ( node = node[ dir ] ) ) { + if ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) { + + return false; + } + } + + // Reverse direction for :only-* (if we haven't yet done so) + start = dir = type === "only" && !start && "nextSibling"; + } + return true; + } + + start = [ forward ? parent.firstChild : parent.lastChild ]; + + // non-xml :nth-child(...) stores cache data on `parent` + if ( forward && useCache ) { + + // Seek `elem` from a previously-cached index + + // ...in a gzip-friendly way + node = parent; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex && cache[ 2 ]; + node = nodeIndex && parent.childNodes[ nodeIndex ]; + + while ( ( node = ++nodeIndex && node && node[ dir ] || + + // Fallback to seeking `elem` from the start + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + // When found, cache indexes on `parent` and break + if ( node.nodeType === 1 && ++diff && node === elem ) { + uniqueCache[ type ] = [ dirruns, nodeIndex, diff ]; + break; + } + } + + } else { + + // Use previously-cached element index if available + if ( useCache ) { + + // ...in a gzip-friendly way + node = elem; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex; + } + + // xml :nth-child(...) + // or :nth-last-child(...) or :nth(-last)?-of-type(...) + if ( diff === false ) { + + // Use the same loop as above to seek `elem` from the start + while ( ( node = ++nodeIndex && node && node[ dir ] || + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + if ( ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) && + ++diff ) { + + // Cache the index of each encountered element + if ( useCache ) { + outerCache = node[ expando ] || + ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + uniqueCache[ type ] = [ dirruns, diff ]; + } + + if ( node === elem ) { + break; + } + } + } + } + } + + // Incorporate the offset, then check against cycle size + diff -= last; + return diff === first || ( diff % first === 0 && diff / first >= 0 ); + } + }; + }, + + "PSEUDO": function( pseudo, argument ) { + + // pseudo-class names are case-insensitive + // http://www.w3.org/TR/selectors/#pseudo-classes + // Prioritize by case sensitivity in case custom pseudos are added with uppercase letters + // Remember that setFilters inherits from pseudos + var args, + fn = Expr.pseudos[ pseudo ] || Expr.setFilters[ pseudo.toLowerCase() ] || + Sizzle.error( "unsupported pseudo: " + pseudo ); + + // The user may use createPseudo to indicate that + // arguments are needed to create the filter function + // just as Sizzle does + if ( fn[ expando ] ) { + return fn( argument ); + } + + // But maintain support for old signatures + if ( fn.length > 1 ) { + args = [ pseudo, pseudo, "", argument ]; + return Expr.setFilters.hasOwnProperty( pseudo.toLowerCase() ) ? + markFunction( function( seed, matches ) { + var idx, + matched = fn( seed, argument ), + i = matched.length; + while ( i-- ) { + idx = indexOf( seed, matched[ i ] ); + seed[ idx ] = !( matches[ idx ] = matched[ i ] ); + } + } ) : + function( elem ) { + return fn( elem, 0, args ); + }; + } + + return fn; + } + }, + + pseudos: { + + // Potentially complex pseudos + "not": markFunction( function( selector ) { + + // Trim the selector passed to compile + // to avoid treating leading and trailing + // spaces as combinators + var input = [], + results = [], + matcher = compile( selector.replace( rtrim, "$1" ) ); + + return matcher[ expando ] ? + markFunction( function( seed, matches, _context, xml ) { + var elem, + unmatched = matcher( seed, null, xml, [] ), + i = seed.length; + + // Match elements unmatched by `matcher` + while ( i-- ) { + if ( ( elem = unmatched[ i ] ) ) { + seed[ i ] = !( matches[ i ] = elem ); + } + } + } ) : + function( elem, _context, xml ) { + input[ 0 ] = elem; + matcher( input, null, xml, results ); + + // Don't keep the element (issue #299) + input[ 0 ] = null; + return !results.pop(); + }; + } ), + + "has": markFunction( function( selector ) { + return function( elem ) { + return Sizzle( selector, elem ).length > 0; + }; + } ), + + "contains": markFunction( function( text ) { + text = text.replace( runescape, funescape ); + return function( elem ) { + return ( elem.textContent || getText( elem ) ).indexOf( text ) > -1; + }; + } ), + + // "Whether an element is represented by a :lang() selector + // is based solely on the element's language value + // being equal to the identifier C, + // or beginning with the identifier C immediately followed by "-". + // The matching of C against the element's language value is performed case-insensitively. + // The identifier C does not have to be a valid language name." + // http://www.w3.org/TR/selectors/#lang-pseudo + "lang": markFunction( function( lang ) { + + // lang value must be a valid identifier + if ( !ridentifier.test( lang || "" ) ) { + Sizzle.error( "unsupported lang: " + lang ); + } + lang = lang.replace( runescape, funescape ).toLowerCase(); + return function( elem ) { + var elemLang; + do { + if ( ( elemLang = documentIsHTML ? + elem.lang : + elem.getAttribute( "xml:lang" ) || elem.getAttribute( "lang" ) ) ) { + + elemLang = elemLang.toLowerCase(); + return elemLang === lang || elemLang.indexOf( lang + "-" ) === 0; + } + } while ( ( elem = elem.parentNode ) && elem.nodeType === 1 ); + return false; + }; + } ), + + // Miscellaneous + "target": function( elem ) { + var hash = window.location && window.location.hash; + return hash && hash.slice( 1 ) === elem.id; + }, + + "root": function( elem ) { + return elem === docElem; + }, + + "focus": function( elem ) { + return elem === document.activeElement && + ( !document.hasFocus || document.hasFocus() ) && + !!( elem.type || elem.href || ~elem.tabIndex ); + }, + + // Boolean properties + "enabled": createDisabledPseudo( false ), + "disabled": createDisabledPseudo( true ), + + "checked": function( elem ) { + + // In CSS3, :checked should return both checked and selected elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + var nodeName = elem.nodeName.toLowerCase(); + return ( nodeName === "input" && !!elem.checked ) || + ( nodeName === "option" && !!elem.selected ); + }, + + "selected": function( elem ) { + + // Accessing this property makes selected-by-default + // options in Safari work properly + if ( elem.parentNode ) { + // eslint-disable-next-line no-unused-expressions + elem.parentNode.selectedIndex; + } + + return elem.selected === true; + }, + + // Contents + "empty": function( elem ) { + + // http://www.w3.org/TR/selectors/#empty-pseudo + // :empty is negated by element (1) or content nodes (text: 3; cdata: 4; entity ref: 5), + // but not by others (comment: 8; processing instruction: 7; etc.) + // nodeType < 6 works because attributes (2) do not appear as children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + if ( elem.nodeType < 6 ) { + return false; + } + } + return true; + }, + + "parent": function( elem ) { + return !Expr.pseudos[ "empty" ]( elem ); + }, + + // Element/input types + "header": function( elem ) { + return rheader.test( elem.nodeName ); + }, + + "input": function( elem ) { + return rinputs.test( elem.nodeName ); + }, + + "button": function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === "button" || name === "button"; + }, + + "text": function( elem ) { + var attr; + return elem.nodeName.toLowerCase() === "input" && + elem.type === "text" && + + // Support: IE<8 + // New HTML5 attribute values (e.g., "search") appear with elem.type === "text" + ( ( attr = elem.getAttribute( "type" ) ) == null || + attr.toLowerCase() === "text" ); + }, + + // Position-in-collection + "first": createPositionalPseudo( function() { + return [ 0 ]; + } ), + + "last": createPositionalPseudo( function( _matchIndexes, length ) { + return [ length - 1 ]; + } ), + + "eq": createPositionalPseudo( function( _matchIndexes, length, argument ) { + return [ argument < 0 ? argument + length : argument ]; + } ), + + "even": createPositionalPseudo( function( matchIndexes, length ) { + var i = 0; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "odd": createPositionalPseudo( function( matchIndexes, length ) { + var i = 1; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "lt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? + argument + length : + argument > length ? + length : + argument; + for ( ; --i >= 0; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "gt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? argument + length : argument; + for ( ; ++i < length; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ) + } +}; + +Expr.pseudos[ "nth" ] = Expr.pseudos[ "eq" ]; + +// Add button/input type pseudos +for ( i in { radio: true, checkbox: true, file: true, password: true, image: true } ) { + Expr.pseudos[ i ] = createInputPseudo( i ); +} +for ( i in { submit: true, reset: true } ) { + Expr.pseudos[ i ] = createButtonPseudo( i ); +} + +// Easy API for creating new setFilters +function setFilters() {} +setFilters.prototype = Expr.filters = Expr.pseudos; +Expr.setFilters = new setFilters(); + +tokenize = Sizzle.tokenize = function( selector, parseOnly ) { + var matched, match, tokens, type, + soFar, groups, preFilters, + cached = tokenCache[ selector + " " ]; + + if ( cached ) { + return parseOnly ? 0 : cached.slice( 0 ); + } + + soFar = selector; + groups = []; + preFilters = Expr.preFilter; + + while ( soFar ) { + + // Comma and first run + if ( !matched || ( match = rcomma.exec( soFar ) ) ) { + if ( match ) { + + // Don't consume trailing commas as valid + soFar = soFar.slice( match[ 0 ].length ) || soFar; + } + groups.push( ( tokens = [] ) ); + } + + matched = false; + + // Combinators + if ( ( match = rcombinators.exec( soFar ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + + // Cast descendant combinators to space + type: match[ 0 ].replace( rtrim, " " ) + } ); + soFar = soFar.slice( matched.length ); + } + + // Filters + for ( type in Expr.filter ) { + if ( ( match = matchExpr[ type ].exec( soFar ) ) && ( !preFilters[ type ] || + ( match = preFilters[ type ]( match ) ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + type: type, + matches: match + } ); + soFar = soFar.slice( matched.length ); + } + } + + if ( !matched ) { + break; + } + } + + // Return the length of the invalid excess + // if we're just parsing + // Otherwise, throw an error or return tokens + return parseOnly ? + soFar.length : + soFar ? + Sizzle.error( selector ) : + + // Cache the tokens + tokenCache( selector, groups ).slice( 0 ); +}; + +function toSelector( tokens ) { + var i = 0, + len = tokens.length, + selector = ""; + for ( ; i < len; i++ ) { + selector += tokens[ i ].value; + } + return selector; +} + +function addCombinator( matcher, combinator, base ) { + var dir = combinator.dir, + skip = combinator.next, + key = skip || dir, + checkNonElements = base && key === "parentNode", + doneName = done++; + + return combinator.first ? + + // Check against closest ancestor/preceding element + function( elem, context, xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + return matcher( elem, context, xml ); + } + } + return false; + } : + + // Check against all ancestor/preceding elements + function( elem, context, xml ) { + var oldCache, uniqueCache, outerCache, + newCache = [ dirruns, doneName ]; + + // We can't set arbitrary data on XML nodes, so they don't benefit from combinator caching + if ( xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + if ( matcher( elem, context, xml ) ) { + return true; + } + } + } + } else { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + outerCache = elem[ expando ] || ( elem[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ elem.uniqueID ] || + ( outerCache[ elem.uniqueID ] = {} ); + + if ( skip && skip === elem.nodeName.toLowerCase() ) { + elem = elem[ dir ] || elem; + } else if ( ( oldCache = uniqueCache[ key ] ) && + oldCache[ 0 ] === dirruns && oldCache[ 1 ] === doneName ) { + + // Assign to newCache so results back-propagate to previous elements + return ( newCache[ 2 ] = oldCache[ 2 ] ); + } else { + + // Reuse newcache so results back-propagate to previous elements + uniqueCache[ key ] = newCache; + + // A match means we're done; a fail means we have to keep checking + if ( ( newCache[ 2 ] = matcher( elem, context, xml ) ) ) { + return true; + } + } + } + } + } + return false; + }; +} + +function elementMatcher( matchers ) { + return matchers.length > 1 ? + function( elem, context, xml ) { + var i = matchers.length; + while ( i-- ) { + if ( !matchers[ i ]( elem, context, xml ) ) { + return false; + } + } + return true; + } : + matchers[ 0 ]; +} + +function multipleContexts( selector, contexts, results ) { + var i = 0, + len = contexts.length; + for ( ; i < len; i++ ) { + Sizzle( selector, contexts[ i ], results ); + } + return results; +} + +function condense( unmatched, map, filter, context, xml ) { + var elem, + newUnmatched = [], + i = 0, + len = unmatched.length, + mapped = map != null; + + for ( ; i < len; i++ ) { + if ( ( elem = unmatched[ i ] ) ) { + if ( !filter || filter( elem, context, xml ) ) { + newUnmatched.push( elem ); + if ( mapped ) { + map.push( i ); + } + } + } + } + + return newUnmatched; +} + +function setMatcher( preFilter, selector, matcher, postFilter, postFinder, postSelector ) { + if ( postFilter && !postFilter[ expando ] ) { + postFilter = setMatcher( postFilter ); + } + if ( postFinder && !postFinder[ expando ] ) { + postFinder = setMatcher( postFinder, postSelector ); + } + return markFunction( function( seed, results, context, xml ) { + var temp, i, elem, + preMap = [], + postMap = [], + preexisting = results.length, + + // Get initial elements from seed or context + elems = seed || multipleContexts( + selector || "*", + context.nodeType ? [ context ] : context, + [] + ), + + // Prefilter to get matcher input, preserving a map for seed-results synchronization + matcherIn = preFilter && ( seed || !selector ) ? + condense( elems, preMap, preFilter, context, xml ) : + elems, + + matcherOut = matcher ? + + // If we have a postFinder, or filtered seed, or non-seed postFilter or preexisting results, + postFinder || ( seed ? preFilter : preexisting || postFilter ) ? + + // ...intermediate processing is necessary + [] : + + // ...otherwise use results directly + results : + matcherIn; + + // Find primary matches + if ( matcher ) { + matcher( matcherIn, matcherOut, context, xml ); + } + + // Apply postFilter + if ( postFilter ) { + temp = condense( matcherOut, postMap ); + postFilter( temp, [], context, xml ); + + // Un-match failing elements by moving them back to matcherIn + i = temp.length; + while ( i-- ) { + if ( ( elem = temp[ i ] ) ) { + matcherOut[ postMap[ i ] ] = !( matcherIn[ postMap[ i ] ] = elem ); + } + } + } + + if ( seed ) { + if ( postFinder || preFilter ) { + if ( postFinder ) { + + // Get the final matcherOut by condensing this intermediate into postFinder contexts + temp = []; + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) ) { + + // Restore matcherIn since elem is not yet a final match + temp.push( ( matcherIn[ i ] = elem ) ); + } + } + postFinder( null, ( matcherOut = [] ), temp, xml ); + } + + // Move matched elements from seed to results to keep them synchronized + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) && + ( temp = postFinder ? indexOf( seed, elem ) : preMap[ i ] ) > -1 ) { + + seed[ temp ] = !( results[ temp ] = elem ); + } + } + } + + // Add elements to results, through postFinder if defined + } else { + matcherOut = condense( + matcherOut === results ? + matcherOut.splice( preexisting, matcherOut.length ) : + matcherOut + ); + if ( postFinder ) { + postFinder( null, results, matcherOut, xml ); + } else { + push.apply( results, matcherOut ); + } + } + } ); +} + +function matcherFromTokens( tokens ) { + var checkContext, matcher, j, + len = tokens.length, + leadingRelative = Expr.relative[ tokens[ 0 ].type ], + implicitRelative = leadingRelative || Expr.relative[ " " ], + i = leadingRelative ? 1 : 0, + + // The foundational matcher ensures that elements are reachable from top-level context(s) + matchContext = addCombinator( function( elem ) { + return elem === checkContext; + }, implicitRelative, true ), + matchAnyContext = addCombinator( function( elem ) { + return indexOf( checkContext, elem ) > -1; + }, implicitRelative, true ), + matchers = [ function( elem, context, xml ) { + var ret = ( !leadingRelative && ( xml || context !== outermostContext ) ) || ( + ( checkContext = context ).nodeType ? + matchContext( elem, context, xml ) : + matchAnyContext( elem, context, xml ) ); + + // Avoid hanging onto element (issue #299) + checkContext = null; + return ret; + } ]; + + for ( ; i < len; i++ ) { + if ( ( matcher = Expr.relative[ tokens[ i ].type ] ) ) { + matchers = [ addCombinator( elementMatcher( matchers ), matcher ) ]; + } else { + matcher = Expr.filter[ tokens[ i ].type ].apply( null, tokens[ i ].matches ); + + // Return special upon seeing a positional matcher + if ( matcher[ expando ] ) { + + // Find the next relative operator (if any) for proper handling + j = ++i; + for ( ; j < len; j++ ) { + if ( Expr.relative[ tokens[ j ].type ] ) { + break; + } + } + return setMatcher( + i > 1 && elementMatcher( matchers ), + i > 1 && toSelector( + + // If the preceding token was a descendant combinator, insert an implicit any-element `*` + tokens + .slice( 0, i - 1 ) + .concat( { value: tokens[ i - 2 ].type === " " ? "*" : "" } ) + ).replace( rtrim, "$1" ), + matcher, + i < j && matcherFromTokens( tokens.slice( i, j ) ), + j < len && matcherFromTokens( ( tokens = tokens.slice( j ) ) ), + j < len && toSelector( tokens ) + ); + } + matchers.push( matcher ); + } + } + + return elementMatcher( matchers ); +} + +function matcherFromGroupMatchers( elementMatchers, setMatchers ) { + var bySet = setMatchers.length > 0, + byElement = elementMatchers.length > 0, + superMatcher = function( seed, context, xml, results, outermost ) { + var elem, j, matcher, + matchedCount = 0, + i = "0", + unmatched = seed && [], + setMatched = [], + contextBackup = outermostContext, + + // We must always have either seed elements or outermost context + elems = seed || byElement && Expr.find[ "TAG" ]( "*", outermost ), + + // Use integer dirruns iff this is the outermost matcher + dirrunsUnique = ( dirruns += contextBackup == null ? 1 : Math.random() || 0.1 ), + len = elems.length; + + if ( outermost ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + outermostContext = context == document || context || outermost; + } + + // Add elements passing elementMatchers directly to results + // Support: IE<9, Safari + // Tolerate NodeList properties (IE: "length"; Safari: <number>) matching elements by id + for ( ; i !== len && ( elem = elems[ i ] ) != null; i++ ) { + if ( byElement && elem ) { + j = 0; + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( !context && elem.ownerDocument != document ) { + setDocument( elem ); + xml = !documentIsHTML; + } + while ( ( matcher = elementMatchers[ j++ ] ) ) { + if ( matcher( elem, context || document, xml ) ) { + results.push( elem ); + break; + } + } + if ( outermost ) { + dirruns = dirrunsUnique; + } + } + + // Track unmatched elements for set filters + if ( bySet ) { + + // They will have gone through all possible matchers + if ( ( elem = !matcher && elem ) ) { + matchedCount--; + } + + // Lengthen the array for every element, matched or not + if ( seed ) { + unmatched.push( elem ); + } + } + } + + // `i` is now the count of elements visited above, and adding it to `matchedCount` + // makes the latter nonnegative. + matchedCount += i; + + // Apply set filters to unmatched elements + // NOTE: This can be skipped if there are no unmatched elements (i.e., `matchedCount` + // equals `i`), unless we didn't visit _any_ elements in the above loop because we have + // no element matchers and no seed. + // Incrementing an initially-string "0" `i` allows `i` to remain a string only in that + // case, which will result in a "00" `matchedCount` that differs from `i` but is also + // numerically zero. + if ( bySet && i !== matchedCount ) { + j = 0; + while ( ( matcher = setMatchers[ j++ ] ) ) { + matcher( unmatched, setMatched, context, xml ); + } + + if ( seed ) { + + // Reintegrate element matches to eliminate the need for sorting + if ( matchedCount > 0 ) { + while ( i-- ) { + if ( !( unmatched[ i ] || setMatched[ i ] ) ) { + setMatched[ i ] = pop.call( results ); + } + } + } + + // Discard index placeholder values to get only actual matches + setMatched = condense( setMatched ); + } + + // Add matches to results + push.apply( results, setMatched ); + + // Seedless set matches succeeding multiple successful matchers stipulate sorting + if ( outermost && !seed && setMatched.length > 0 && + ( matchedCount + setMatchers.length ) > 1 ) { + + Sizzle.uniqueSort( results ); + } + } + + // Override manipulation of globals by nested matchers + if ( outermost ) { + dirruns = dirrunsUnique; + outermostContext = contextBackup; + } + + return unmatched; + }; + + return bySet ? + markFunction( superMatcher ) : + superMatcher; +} + +compile = Sizzle.compile = function( selector, match /* Internal Use Only */ ) { + var i, + setMatchers = [], + elementMatchers = [], + cached = compilerCache[ selector + " " ]; + + if ( !cached ) { + + // Generate a function of recursive functions that can be used to check each element + if ( !match ) { + match = tokenize( selector ); + } + i = match.length; + while ( i-- ) { + cached = matcherFromTokens( match[ i ] ); + if ( cached[ expando ] ) { + setMatchers.push( cached ); + } else { + elementMatchers.push( cached ); + } + } + + // Cache the compiled function + cached = compilerCache( + selector, + matcherFromGroupMatchers( elementMatchers, setMatchers ) + ); + + // Save selector and tokenization + cached.selector = selector; + } + return cached; +}; + +/** + * A low-level selection function that works with Sizzle's compiled + * selector functions + * @param {String|Function} selector A selector or a pre-compiled + * selector function built with Sizzle.compile + * @param {Element} context + * @param {Array} [results] + * @param {Array} [seed] A set of elements to match against + */ +select = Sizzle.select = function( selector, context, results, seed ) { + var i, tokens, token, type, find, + compiled = typeof selector === "function" && selector, + match = !seed && tokenize( ( selector = compiled.selector || selector ) ); + + results = results || []; + + // Try to minimize operations if there is only one selector in the list and no seed + // (the latter of which guarantees us context) + if ( match.length === 1 ) { + + // Reduce context if the leading compound selector is an ID + tokens = match[ 0 ] = match[ 0 ].slice( 0 ); + if ( tokens.length > 2 && ( token = tokens[ 0 ] ).type === "ID" && + context.nodeType === 9 && documentIsHTML && Expr.relative[ tokens[ 1 ].type ] ) { + + context = ( Expr.find[ "ID" ]( token.matches[ 0 ] + .replace( runescape, funescape ), context ) || [] )[ 0 ]; + if ( !context ) { + return results; + + // Precompiled matchers will still verify ancestry, so step up a level + } else if ( compiled ) { + context = context.parentNode; + } + + selector = selector.slice( tokens.shift().value.length ); + } + + // Fetch a seed set for right-to-left matching + i = matchExpr[ "needsContext" ].test( selector ) ? 0 : tokens.length; + while ( i-- ) { + token = tokens[ i ]; + + // Abort if we hit a combinator + if ( Expr.relative[ ( type = token.type ) ] ) { + break; + } + if ( ( find = Expr.find[ type ] ) ) { + + // Search, expanding context for leading sibling combinators + if ( ( seed = find( + token.matches[ 0 ].replace( runescape, funescape ), + rsibling.test( tokens[ 0 ].type ) && testContext( context.parentNode ) || + context + ) ) ) { + + // If seed is empty or no tokens remain, we can return early + tokens.splice( i, 1 ); + selector = seed.length && toSelector( tokens ); + if ( !selector ) { + push.apply( results, seed ); + return results; + } + + break; + } + } + } + } + + // Compile and execute a filtering function if one is not provided + // Provide `match` to avoid retokenization if we modified the selector above + ( compiled || compile( selector, match ) )( + seed, + context, + !documentIsHTML, + results, + !context || rsibling.test( selector ) && testContext( context.parentNode ) || context + ); + return results; +}; + +// One-time assignments + +// Sort stability +support.sortStable = expando.split( "" ).sort( sortOrder ).join( "" ) === expando; + +// Support: Chrome 14-35+ +// Always assume duplicates if they aren't passed to the comparison function +support.detectDuplicates = !!hasDuplicate; + +// Initialize against the default document +setDocument(); + +// Support: Webkit<537.32 - Safari 6.0.3/Chrome 25 (fixed in Chrome 27) +// Detached nodes confoundingly follow *each other* +support.sortDetached = assert( function( el ) { + + // Should return 1, but returns 4 (following) + return el.compareDocumentPosition( document.createElement( "fieldset" ) ) & 1; +} ); + +// Support: IE<8 +// Prevent attribute/property "interpolation" +// https://msdn.microsoft.com/en-us/library/ms536429%28VS.85%29.aspx +if ( !assert( function( el ) { + el.innerHTML = "<a href='#'></a>"; + return el.firstChild.getAttribute( "href" ) === "#"; +} ) ) { + addHandle( "type|href|height|width", function( elem, name, isXML ) { + if ( !isXML ) { + return elem.getAttribute( name, name.toLowerCase() === "type" ? 1 : 2 ); + } + } ); +} + +// Support: IE<9 +// Use defaultValue in place of getAttribute("value") +if ( !support.attributes || !assert( function( el ) { + el.innerHTML = "<input/>"; + el.firstChild.setAttribute( "value", "" ); + return el.firstChild.getAttribute( "value" ) === ""; +} ) ) { + addHandle( "value", function( elem, _name, isXML ) { + if ( !isXML && elem.nodeName.toLowerCase() === "input" ) { + return elem.defaultValue; + } + } ); +} + +// Support: IE<9 +// Use getAttributeNode to fetch booleans when getAttribute lies +if ( !assert( function( el ) { + return el.getAttribute( "disabled" ) == null; +} ) ) { + addHandle( booleans, function( elem, name, isXML ) { + var val; + if ( !isXML ) { + return elem[ name ] === true ? name.toLowerCase() : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; + } + } ); +} + +return Sizzle; + +} )( window ); + + + +jQuery.find = Sizzle; +jQuery.expr = Sizzle.selectors; + +// Deprecated +jQuery.expr[ ":" ] = jQuery.expr.pseudos; +jQuery.uniqueSort = jQuery.unique = Sizzle.uniqueSort; +jQuery.text = Sizzle.getText; +jQuery.isXMLDoc = Sizzle.isXML; +jQuery.contains = Sizzle.contains; +jQuery.escapeSelector = Sizzle.escape; + + + + +var dir = function( elem, dir, until ) { + var matched = [], + truncate = until !== undefined; + + while ( ( elem = elem[ dir ] ) && elem.nodeType !== 9 ) { + if ( elem.nodeType === 1 ) { + if ( truncate && jQuery( elem ).is( until ) ) { + break; + } + matched.push( elem ); + } + } + return matched; +}; + + +var siblings = function( n, elem ) { + var matched = []; + + for ( ; n; n = n.nextSibling ) { + if ( n.nodeType === 1 && n !== elem ) { + matched.push( n ); + } + } + + return matched; +}; + + +var rneedsContext = jQuery.expr.match.needsContext; + + + +function nodeName( elem, name ) { + + return elem.nodeName && elem.nodeName.toLowerCase() === name.toLowerCase(); + +}; +var rsingleTag = ( /^<([a-z][^\/\0>:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i ); + + + +// Implement the identical functionality for filter and not +function winnow( elements, qualifier, not ) { + if ( isFunction( qualifier ) ) { + return jQuery.grep( elements, function( elem, i ) { + return !!qualifier.call( elem, i, elem ) !== not; + } ); + } + + // Single element + if ( qualifier.nodeType ) { + return jQuery.grep( elements, function( elem ) { + return ( elem === qualifier ) !== not; + } ); + } + + // Arraylike of elements (jQuery, arguments, Array) + if ( typeof qualifier !== "string" ) { + return jQuery.grep( elements, function( elem ) { + return ( indexOf.call( qualifier, elem ) > -1 ) !== not; + } ); + } + + // Filtered directly for both simple and complex selectors + return jQuery.filter( qualifier, elements, not ); +} + +jQuery.filter = function( expr, elems, not ) { + var elem = elems[ 0 ]; + + if ( not ) { + expr = ":not(" + expr + ")"; + } + + if ( elems.length === 1 && elem.nodeType === 1 ) { + return jQuery.find.matchesSelector( elem, expr ) ? [ elem ] : []; + } + + return jQuery.find.matches( expr, jQuery.grep( elems, function( elem ) { + return elem.nodeType === 1; + } ) ); +}; + +jQuery.fn.extend( { + find: function( selector ) { + var i, ret, + len = this.length, + self = this; + + if ( typeof selector !== "string" ) { + return this.pushStack( jQuery( selector ).filter( function() { + for ( i = 0; i < len; i++ ) { + if ( jQuery.contains( self[ i ], this ) ) { + return true; + } + } + } ) ); + } + + ret = this.pushStack( [] ); + + for ( i = 0; i < len; i++ ) { + jQuery.find( selector, self[ i ], ret ); + } + + return len > 1 ? jQuery.uniqueSort( ret ) : ret; + }, + filter: function( selector ) { + return this.pushStack( winnow( this, selector || [], false ) ); + }, + not: function( selector ) { + return this.pushStack( winnow( this, selector || [], true ) ); + }, + is: function( selector ) { + return !!winnow( + this, + + // If this is a positional/relative selector, check membership in the returned set + // so $("p:first").is("p:last") won't return true for a doc with two "p". + typeof selector === "string" && rneedsContext.test( selector ) ? + jQuery( selector ) : + selector || [], + false + ).length; + } +} ); + + +// Initialize a jQuery object + + +// A central reference to the root jQuery(document) +var rootjQuery, + + // A simple way to check for HTML strings + // Prioritize #id over <tag> to avoid XSS via location.hash (#9521) + // Strict HTML recognition (#11290: must start with <) + // Shortcut simple #id case for speed + rquickExpr = /^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]+))$/, + + init = jQuery.fn.init = function( selector, context, root ) { + var match, elem; + + // HANDLE: $(""), $(null), $(undefined), $(false) + if ( !selector ) { + return this; + } + + // Method init() accepts an alternate rootjQuery + // so migrate can support jQuery.sub (gh-2101) + root = root || rootjQuery; + + // Handle HTML strings + if ( typeof selector === "string" ) { + if ( selector[ 0 ] === "<" && + selector[ selector.length - 1 ] === ">" && + selector.length >= 3 ) { + + // Assume that strings that start and end with <> are HTML and skip the regex check + match = [ null, selector, null ]; + + } else { + match = rquickExpr.exec( selector ); + } + + // Match html or make sure no context is specified for #id + if ( match && ( match[ 1 ] || !context ) ) { + + // HANDLE: $(html) -> $(array) + if ( match[ 1 ] ) { + context = context instanceof jQuery ? context[ 0 ] : context; + + // Option to run scripts is true for back-compat + // Intentionally let the error be thrown if parseHTML is not present + jQuery.merge( this, jQuery.parseHTML( + match[ 1 ], + context && context.nodeType ? context.ownerDocument || context : document, + true + ) ); + + // HANDLE: $(html, props) + if ( rsingleTag.test( match[ 1 ] ) && jQuery.isPlainObject( context ) ) { + for ( match in context ) { + + // Properties of context are called as methods if possible + if ( isFunction( this[ match ] ) ) { + this[ match ]( context[ match ] ); + + // ...and otherwise set as attributes + } else { + this.attr( match, context[ match ] ); + } + } + } + + return this; + + // HANDLE: $(#id) + } else { + elem = document.getElementById( match[ 2 ] ); + + if ( elem ) { + + // Inject the element directly into the jQuery object + this[ 0 ] = elem; + this.length = 1; + } + return this; + } + + // HANDLE: $(expr, $(...)) + } else if ( !context || context.jquery ) { + return ( context || root ).find( selector ); + + // HANDLE: $(expr, context) + // (which is just equivalent to: $(context).find(expr) + } else { + return this.constructor( context ).find( selector ); + } + + // HANDLE: $(DOMElement) + } else if ( selector.nodeType ) { + this[ 0 ] = selector; + this.length = 1; + return this; + + // HANDLE: $(function) + // Shortcut for document ready + } else if ( isFunction( selector ) ) { + return root.ready !== undefined ? + root.ready( selector ) : + + // Execute immediately if ready is not present + selector( jQuery ); + } + + return jQuery.makeArray( selector, this ); + }; + +// Give the init function the jQuery prototype for later instantiation +init.prototype = jQuery.fn; + +// Initialize central reference +rootjQuery = jQuery( document ); + + +var rparentsprev = /^(?:parents|prev(?:Until|All))/, + + // Methods guaranteed to produce a unique set when starting from a unique set + guaranteedUnique = { + children: true, + contents: true, + next: true, + prev: true + }; + +jQuery.fn.extend( { + has: function( target ) { + var targets = jQuery( target, this ), + l = targets.length; + + return this.filter( function() { + var i = 0; + for ( ; i < l; i++ ) { + if ( jQuery.contains( this, targets[ i ] ) ) { + return true; + } + } + } ); + }, + + closest: function( selectors, context ) { + var cur, + i = 0, + l = this.length, + matched = [], + targets = typeof selectors !== "string" && jQuery( selectors ); + + // Positional selectors never match, since there's no _selection_ context + if ( !rneedsContext.test( selectors ) ) { + for ( ; i < l; i++ ) { + for ( cur = this[ i ]; cur && cur !== context; cur = cur.parentNode ) { + + // Always skip document fragments + if ( cur.nodeType < 11 && ( targets ? + targets.index( cur ) > -1 : + + // Don't pass non-elements to Sizzle + cur.nodeType === 1 && + jQuery.find.matchesSelector( cur, selectors ) ) ) { + + matched.push( cur ); + break; + } + } + } + } + + return this.pushStack( matched.length > 1 ? jQuery.uniqueSort( matched ) : matched ); + }, + + // Determine the position of an element within the set + index: function( elem ) { + + // No argument, return index in parent + if ( !elem ) { + return ( this[ 0 ] && this[ 0 ].parentNode ) ? this.first().prevAll().length : -1; + } + + // Index in selector + if ( typeof elem === "string" ) { + return indexOf.call( jQuery( elem ), this[ 0 ] ); + } + + // Locate the position of the desired element + return indexOf.call( this, + + // If it receives a jQuery object, the first element is used + elem.jquery ? elem[ 0 ] : elem + ); + }, + + add: function( selector, context ) { + return this.pushStack( + jQuery.uniqueSort( + jQuery.merge( this.get(), jQuery( selector, context ) ) + ) + ); + }, + + addBack: function( selector ) { + return this.add( selector == null ? + this.prevObject : this.prevObject.filter( selector ) + ); + } +} ); + +function sibling( cur, dir ) { + while ( ( cur = cur[ dir ] ) && cur.nodeType !== 1 ) {} + return cur; +} + +jQuery.each( { + parent: function( elem ) { + var parent = elem.parentNode; + return parent && parent.nodeType !== 11 ? parent : null; + }, + parents: function( elem ) { + return dir( elem, "parentNode" ); + }, + parentsUntil: function( elem, _i, until ) { + return dir( elem, "parentNode", until ); + }, + next: function( elem ) { + return sibling( elem, "nextSibling" ); + }, + prev: function( elem ) { + return sibling( elem, "previousSibling" ); + }, + nextAll: function( elem ) { + return dir( elem, "nextSibling" ); + }, + prevAll: function( elem ) { + return dir( elem, "previousSibling" ); + }, + nextUntil: function( elem, _i, until ) { + return dir( elem, "nextSibling", until ); + }, + prevUntil: function( elem, _i, until ) { + return dir( elem, "previousSibling", until ); + }, + siblings: function( elem ) { + return siblings( ( elem.parentNode || {} ).firstChild, elem ); + }, + children: function( elem ) { + return siblings( elem.firstChild ); + }, + contents: function( elem ) { + if ( elem.contentDocument != null && + + // Support: IE 11+ + // <object> elements with no `data` attribute has an object + // `contentDocument` with a `null` prototype. + getProto( elem.contentDocument ) ) { + + return elem.contentDocument; + } + + // Support: IE 9 - 11 only, iOS 7 only, Android Browser <=4.3 only + // Treat the template element as a regular one in browsers that + // don't support it. + if ( nodeName( elem, "template" ) ) { + elem = elem.content || elem; + } + + return jQuery.merge( [], elem.childNodes ); + } +}, function( name, fn ) { + jQuery.fn[ name ] = function( until, selector ) { + var matched = jQuery.map( this, fn, until ); + + if ( name.slice( -5 ) !== "Until" ) { + selector = until; + } + + if ( selector && typeof selector === "string" ) { + matched = jQuery.filter( selector, matched ); + } + + if ( this.length > 1 ) { + + // Remove duplicates + if ( !guaranteedUnique[ name ] ) { + jQuery.uniqueSort( matched ); + } + + // Reverse order for parents* and prev-derivatives + if ( rparentsprev.test( name ) ) { + matched.reverse(); + } + } + + return this.pushStack( matched ); + }; +} ); +var rnothtmlwhite = ( /[^\x20\t\r\n\f]+/g ); + + + +// Convert String-formatted options into Object-formatted ones +function createOptions( options ) { + var object = {}; + jQuery.each( options.match( rnothtmlwhite ) || [], function( _, flag ) { + object[ flag ] = true; + } ); + return object; +} + +/* + * Create a callback list using the following parameters: + * + * options: an optional list of space-separated options that will change how + * the callback list behaves or a more traditional option object + * + * By default a callback list will act like an event callback list and can be + * "fired" multiple times. + * + * Possible options: + * + * once: will ensure the callback list can only be fired once (like a Deferred) + * + * memory: will keep track of previous values and will call any callback added + * after the list has been fired right away with the latest "memorized" + * values (like a Deferred) + * + * unique: will ensure a callback can only be added once (no duplicate in the list) + * + * stopOnFalse: interrupt callings when a callback returns false + * + */ +jQuery.Callbacks = function( options ) { + + // Convert options from String-formatted to Object-formatted if needed + // (we check in cache first) + options = typeof options === "string" ? + createOptions( options ) : + jQuery.extend( {}, options ); + + var // Flag to know if list is currently firing + firing, + + // Last fire value for non-forgettable lists + memory, + + // Flag to know if list was already fired + fired, + + // Flag to prevent firing + locked, + + // Actual callback list + list = [], + + // Queue of execution data for repeatable lists + queue = [], + + // Index of currently firing callback (modified by add/remove as needed) + firingIndex = -1, + + // Fire callbacks + fire = function() { + + // Enforce single-firing + locked = locked || options.once; + + // Execute callbacks for all pending executions, + // respecting firingIndex overrides and runtime changes + fired = firing = true; + for ( ; queue.length; firingIndex = -1 ) { + memory = queue.shift(); + while ( ++firingIndex < list.length ) { + + // Run callback and check for early termination + if ( list[ firingIndex ].apply( memory[ 0 ], memory[ 1 ] ) === false && + options.stopOnFalse ) { + + // Jump to end and forget the data so .add doesn't re-fire + firingIndex = list.length; + memory = false; + } + } + } + + // Forget the data if we're done with it + if ( !options.memory ) { + memory = false; + } + + firing = false; + + // Clean up if we're done firing for good + if ( locked ) { + + // Keep an empty list if we have data for future add calls + if ( memory ) { + list = []; + + // Otherwise, this object is spent + } else { + list = ""; + } + } + }, + + // Actual Callbacks object + self = { + + // Add a callback or a collection of callbacks to the list + add: function() { + if ( list ) { + + // If we have memory from a past run, we should fire after adding + if ( memory && !firing ) { + firingIndex = list.length - 1; + queue.push( memory ); + } + + ( function add( args ) { + jQuery.each( args, function( _, arg ) { + if ( isFunction( arg ) ) { + if ( !options.unique || !self.has( arg ) ) { + list.push( arg ); + } + } else if ( arg && arg.length && toType( arg ) !== "string" ) { + + // Inspect recursively + add( arg ); + } + } ); + } )( arguments ); + + if ( memory && !firing ) { + fire(); + } + } + return this; + }, + + // Remove a callback from the list + remove: function() { + jQuery.each( arguments, function( _, arg ) { + var index; + while ( ( index = jQuery.inArray( arg, list, index ) ) > -1 ) { + list.splice( index, 1 ); + + // Handle firing indexes + if ( index <= firingIndex ) { + firingIndex--; + } + } + } ); + return this; + }, + + // Check if a given callback is in the list. + // If no argument is given, return whether or not list has callbacks attached. + has: function( fn ) { + return fn ? + jQuery.inArray( fn, list ) > -1 : + list.length > 0; + }, + + // Remove all callbacks from the list + empty: function() { + if ( list ) { + list = []; + } + return this; + }, + + // Disable .fire and .add + // Abort any current/pending executions + // Clear all callbacks and values + disable: function() { + locked = queue = []; + list = memory = ""; + return this; + }, + disabled: function() { + return !list; + }, + + // Disable .fire + // Also disable .add unless we have memory (since it would have no effect) + // Abort any pending executions + lock: function() { + locked = queue = []; + if ( !memory && !firing ) { + list = memory = ""; + } + return this; + }, + locked: function() { + return !!locked; + }, + + // Call all callbacks with the given context and arguments + fireWith: function( context, args ) { + if ( !locked ) { + args = args || []; + args = [ context, args.slice ? args.slice() : args ]; + queue.push( args ); + if ( !firing ) { + fire(); + } + } + return this; + }, + + // Call all the callbacks with the given arguments + fire: function() { + self.fireWith( this, arguments ); + return this; + }, + + // To know if the callbacks have already been called at least once + fired: function() { + return !!fired; + } + }; + + return self; +}; + + +function Identity( v ) { + return v; +} +function Thrower( ex ) { + throw ex; +} + +function adoptValue( value, resolve, reject, noValue ) { + var method; + + try { + + // Check for promise aspect first to privilege synchronous behavior + if ( value && isFunction( ( method = value.promise ) ) ) { + method.call( value ).done( resolve ).fail( reject ); + + // Other thenables + } else if ( value && isFunction( ( method = value.then ) ) ) { + method.call( value, resolve, reject ); + + // Other non-thenables + } else { + + // Control `resolve` arguments by letting Array#slice cast boolean `noValue` to integer: + // * false: [ value ].slice( 0 ) => resolve( value ) + // * true: [ value ].slice( 1 ) => resolve() + resolve.apply( undefined, [ value ].slice( noValue ) ); + } + + // For Promises/A+, convert exceptions into rejections + // Since jQuery.when doesn't unwrap thenables, we can skip the extra checks appearing in + // Deferred#then to conditionally suppress rejection. + } catch ( value ) { + + // Support: Android 4.0 only + // Strict mode functions invoked without .call/.apply get global-object context + reject.apply( undefined, [ value ] ); + } +} + +jQuery.extend( { + + Deferred: function( func ) { + var tuples = [ + + // action, add listener, callbacks, + // ... .then handlers, argument index, [final state] + [ "notify", "progress", jQuery.Callbacks( "memory" ), + jQuery.Callbacks( "memory" ), 2 ], + [ "resolve", "done", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 0, "resolved" ], + [ "reject", "fail", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 1, "rejected" ] + ], + state = "pending", + promise = { + state: function() { + return state; + }, + always: function() { + deferred.done( arguments ).fail( arguments ); + return this; + }, + "catch": function( fn ) { + return promise.then( null, fn ); + }, + + // Keep pipe for back-compat + pipe: function( /* fnDone, fnFail, fnProgress */ ) { + var fns = arguments; + + return jQuery.Deferred( function( newDefer ) { + jQuery.each( tuples, function( _i, tuple ) { + + // Map tuples (progress, done, fail) to arguments (done, fail, progress) + var fn = isFunction( fns[ tuple[ 4 ] ] ) && fns[ tuple[ 4 ] ]; + + // deferred.progress(function() { bind to newDefer or newDefer.notify }) + // deferred.done(function() { bind to newDefer or newDefer.resolve }) + // deferred.fail(function() { bind to newDefer or newDefer.reject }) + deferred[ tuple[ 1 ] ]( function() { + var returned = fn && fn.apply( this, arguments ); + if ( returned && isFunction( returned.promise ) ) { + returned.promise() + .progress( newDefer.notify ) + .done( newDefer.resolve ) + .fail( newDefer.reject ); + } else { + newDefer[ tuple[ 0 ] + "With" ]( + this, + fn ? [ returned ] : arguments + ); + } + } ); + } ); + fns = null; + } ).promise(); + }, + then: function( onFulfilled, onRejected, onProgress ) { + var maxDepth = 0; + function resolve( depth, deferred, handler, special ) { + return function() { + var that = this, + args = arguments, + mightThrow = function() { + var returned, then; + + // Support: Promises/A+ section 2.3.3.3.3 + // https://promisesaplus.com/#point-59 + // Ignore double-resolution attempts + if ( depth < maxDepth ) { + return; + } + + returned = handler.apply( that, args ); + + // Support: Promises/A+ section 2.3.1 + // https://promisesaplus.com/#point-48 + if ( returned === deferred.promise() ) { + throw new TypeError( "Thenable self-resolution" ); + } + + // Support: Promises/A+ sections 2.3.3.1, 3.5 + // https://promisesaplus.com/#point-54 + // https://promisesaplus.com/#point-75 + // Retrieve `then` only once + then = returned && + + // Support: Promises/A+ section 2.3.4 + // https://promisesaplus.com/#point-64 + // Only check objects and functions for thenability + ( typeof returned === "object" || + typeof returned === "function" ) && + returned.then; + + // Handle a returned thenable + if ( isFunction( then ) ) { + + // Special processors (notify) just wait for resolution + if ( special ) { + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ) + ); + + // Normal processors (resolve) also hook into progress + } else { + + // ...and disregard older resolution values + maxDepth++; + + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ), + resolve( maxDepth, deferred, Identity, + deferred.notifyWith ) + ); + } + + // Handle all other returned values + } else { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Identity ) { + that = undefined; + args = [ returned ]; + } + + // Process the value(s) + // Default process is resolve + ( special || deferred.resolveWith )( that, args ); + } + }, + + // Only normal processors (resolve) catch and reject exceptions + process = special ? + mightThrow : + function() { + try { + mightThrow(); + } catch ( e ) { + + if ( jQuery.Deferred.exceptionHook ) { + jQuery.Deferred.exceptionHook( e, + process.stackTrace ); + } + + // Support: Promises/A+ section 2.3.3.3.4.1 + // https://promisesaplus.com/#point-61 + // Ignore post-resolution exceptions + if ( depth + 1 >= maxDepth ) { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Thrower ) { + that = undefined; + args = [ e ]; + } + + deferred.rejectWith( that, args ); + } + } + }; + + // Support: Promises/A+ section 2.3.3.3.1 + // https://promisesaplus.com/#point-57 + // Re-resolve promises immediately to dodge false rejection from + // subsequent errors + if ( depth ) { + process(); + } else { + + // Call an optional hook to record the stack, in case of exception + // since it's otherwise lost when execution goes async + if ( jQuery.Deferred.getStackHook ) { + process.stackTrace = jQuery.Deferred.getStackHook(); + } + window.setTimeout( process ); + } + }; + } + + return jQuery.Deferred( function( newDefer ) { + + // progress_handlers.add( ... ) + tuples[ 0 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onProgress ) ? + onProgress : + Identity, + newDefer.notifyWith + ) + ); + + // fulfilled_handlers.add( ... ) + tuples[ 1 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onFulfilled ) ? + onFulfilled : + Identity + ) + ); + + // rejected_handlers.add( ... ) + tuples[ 2 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onRejected ) ? + onRejected : + Thrower + ) + ); + } ).promise(); + }, + + // Get a promise for this deferred + // If obj is provided, the promise aspect is added to the object + promise: function( obj ) { + return obj != null ? jQuery.extend( obj, promise ) : promise; + } + }, + deferred = {}; + + // Add list-specific methods + jQuery.each( tuples, function( i, tuple ) { + var list = tuple[ 2 ], + stateString = tuple[ 5 ]; + + // promise.progress = list.add + // promise.done = list.add + // promise.fail = list.add + promise[ tuple[ 1 ] ] = list.add; + + // Handle state + if ( stateString ) { + list.add( + function() { + + // state = "resolved" (i.e., fulfilled) + // state = "rejected" + state = stateString; + }, + + // rejected_callbacks.disable + // fulfilled_callbacks.disable + tuples[ 3 - i ][ 2 ].disable, + + // rejected_handlers.disable + // fulfilled_handlers.disable + tuples[ 3 - i ][ 3 ].disable, + + // progress_callbacks.lock + tuples[ 0 ][ 2 ].lock, + + // progress_handlers.lock + tuples[ 0 ][ 3 ].lock + ); + } + + // progress_handlers.fire + // fulfilled_handlers.fire + // rejected_handlers.fire + list.add( tuple[ 3 ].fire ); + + // deferred.notify = function() { deferred.notifyWith(...) } + // deferred.resolve = function() { deferred.resolveWith(...) } + // deferred.reject = function() { deferred.rejectWith(...) } + deferred[ tuple[ 0 ] ] = function() { + deferred[ tuple[ 0 ] + "With" ]( this === deferred ? undefined : this, arguments ); + return this; + }; + + // deferred.notifyWith = list.fireWith + // deferred.resolveWith = list.fireWith + // deferred.rejectWith = list.fireWith + deferred[ tuple[ 0 ] + "With" ] = list.fireWith; + } ); + + // Make the deferred a promise + promise.promise( deferred ); + + // Call given func if any + if ( func ) { + func.call( deferred, deferred ); + } + + // All done! + return deferred; + }, + + // Deferred helper + when: function( singleValue ) { + var + + // count of uncompleted subordinates + remaining = arguments.length, + + // count of unprocessed arguments + i = remaining, + + // subordinate fulfillment data + resolveContexts = Array( i ), + resolveValues = slice.call( arguments ), + + // the master Deferred + master = jQuery.Deferred(), + + // subordinate callback factory + updateFunc = function( i ) { + return function( value ) { + resolveContexts[ i ] = this; + resolveValues[ i ] = arguments.length > 1 ? slice.call( arguments ) : value; + if ( !( --remaining ) ) { + master.resolveWith( resolveContexts, resolveValues ); + } + }; + }; + + // Single- and empty arguments are adopted like Promise.resolve + if ( remaining <= 1 ) { + adoptValue( singleValue, master.done( updateFunc( i ) ).resolve, master.reject, + !remaining ); + + // Use .then() to unwrap secondary thenables (cf. gh-3000) + if ( master.state() === "pending" || + isFunction( resolveValues[ i ] && resolveValues[ i ].then ) ) { + + return master.then(); + } + } + + // Multiple arguments are aggregated like Promise.all array elements + while ( i-- ) { + adoptValue( resolveValues[ i ], updateFunc( i ), master.reject ); + } + + return master.promise(); + } +} ); + + +// These usually indicate a programmer mistake during development, +// warn about them ASAP rather than swallowing them by default. +var rerrorNames = /^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/; + +jQuery.Deferred.exceptionHook = function( error, stack ) { + + // Support: IE 8 - 9 only + // Console exists when dev tools are open, which can happen at any time + if ( window.console && window.console.warn && error && rerrorNames.test( error.name ) ) { + window.console.warn( "jQuery.Deferred exception: " + error.message, error.stack, stack ); + } +}; + + + + +jQuery.readyException = function( error ) { + window.setTimeout( function() { + throw error; + } ); +}; + + + + +// The deferred used on DOM ready +var readyList = jQuery.Deferred(); + +jQuery.fn.ready = function( fn ) { + + readyList + .then( fn ) + + // Wrap jQuery.readyException in a function so that the lookup + // happens at the time of error handling instead of callback + // registration. + .catch( function( error ) { + jQuery.readyException( error ); + } ); + + return this; +}; + +jQuery.extend( { + + // Is the DOM ready to be used? Set to true once it occurs. + isReady: false, + + // A counter to track how many items to wait for before + // the ready event fires. See #6781 + readyWait: 1, + + // Handle when the DOM is ready + ready: function( wait ) { + + // Abort if there are pending holds or we're already ready + if ( wait === true ? --jQuery.readyWait : jQuery.isReady ) { + return; + } + + // Remember that the DOM is ready + jQuery.isReady = true; + + // If a normal DOM Ready event fired, decrement, and wait if need be + if ( wait !== true && --jQuery.readyWait > 0 ) { + return; + } + + // If there are functions bound, to execute + readyList.resolveWith( document, [ jQuery ] ); + } +} ); + +jQuery.ready.then = readyList.then; + +// The ready event handler and self cleanup method +function completed() { + document.removeEventListener( "DOMContentLoaded", completed ); + window.removeEventListener( "load", completed ); + jQuery.ready(); +} + +// Catch cases where $(document).ready() is called +// after the browser event has already occurred. +// Support: IE <=9 - 10 only +// Older IE sometimes signals "interactive" too soon +if ( document.readyState === "complete" || + ( document.readyState !== "loading" && !document.documentElement.doScroll ) ) { + + // Handle it asynchronously to allow scripts the opportunity to delay ready + window.setTimeout( jQuery.ready ); + +} else { + + // Use the handy event callback + document.addEventListener( "DOMContentLoaded", completed ); + + // A fallback to window.onload, that will always work + window.addEventListener( "load", completed ); +} + + + + +// Multifunctional method to get and set values of a collection +// The value/s can optionally be executed if it's a function +var access = function( elems, fn, key, value, chainable, emptyGet, raw ) { + var i = 0, + len = elems.length, + bulk = key == null; + + // Sets many values + if ( toType( key ) === "object" ) { + chainable = true; + for ( i in key ) { + access( elems, fn, i, key[ i ], true, emptyGet, raw ); + } + + // Sets one value + } else if ( value !== undefined ) { + chainable = true; + + if ( !isFunction( value ) ) { + raw = true; + } + + if ( bulk ) { + + // Bulk operations run against the entire set + if ( raw ) { + fn.call( elems, value ); + fn = null; + + // ...except when executing function values + } else { + bulk = fn; + fn = function( elem, _key, value ) { + return bulk.call( jQuery( elem ), value ); + }; + } + } + + if ( fn ) { + for ( ; i < len; i++ ) { + fn( + elems[ i ], key, raw ? + value : + value.call( elems[ i ], i, fn( elems[ i ], key ) ) + ); + } + } + } + + if ( chainable ) { + return elems; + } + + // Gets + if ( bulk ) { + return fn.call( elems ); + } + + return len ? fn( elems[ 0 ], key ) : emptyGet; +}; + + +// Matches dashed string for camelizing +var rmsPrefix = /^-ms-/, + rdashAlpha = /-([a-z])/g; + +// Used by camelCase as callback to replace() +function fcamelCase( _all, letter ) { + return letter.toUpperCase(); +} + +// Convert dashed to camelCase; used by the css and data modules +// Support: IE <=9 - 11, Edge 12 - 15 +// Microsoft forgot to hump their vendor prefix (#9572) +function camelCase( string ) { + return string.replace( rmsPrefix, "ms-" ).replace( rdashAlpha, fcamelCase ); +} +var acceptData = function( owner ) { + + // Accepts only: + // - Node + // - Node.ELEMENT_NODE + // - Node.DOCUMENT_NODE + // - Object + // - Any + return owner.nodeType === 1 || owner.nodeType === 9 || !( +owner.nodeType ); +}; + + + + +function Data() { + this.expando = jQuery.expando + Data.uid++; +} + +Data.uid = 1; + +Data.prototype = { + + cache: function( owner ) { + + // Check if the owner object already has a cache + var value = owner[ this.expando ]; + + // If not, create one + if ( !value ) { + value = {}; + + // We can accept data for non-element nodes in modern browsers, + // but we should not, see #8335. + // Always return an empty object. + if ( acceptData( owner ) ) { + + // If it is a node unlikely to be stringify-ed or looped over + // use plain assignment + if ( owner.nodeType ) { + owner[ this.expando ] = value; + + // Otherwise secure it in a non-enumerable property + // configurable must be true to allow the property to be + // deleted when data is removed + } else { + Object.defineProperty( owner, this.expando, { + value: value, + configurable: true + } ); + } + } + } + + return value; + }, + set: function( owner, data, value ) { + var prop, + cache = this.cache( owner ); + + // Handle: [ owner, key, value ] args + // Always use camelCase key (gh-2257) + if ( typeof data === "string" ) { + cache[ camelCase( data ) ] = value; + + // Handle: [ owner, { properties } ] args + } else { + + // Copy the properties one-by-one to the cache object + for ( prop in data ) { + cache[ camelCase( prop ) ] = data[ prop ]; + } + } + return cache; + }, + get: function( owner, key ) { + return key === undefined ? + this.cache( owner ) : + + // Always use camelCase key (gh-2257) + owner[ this.expando ] && owner[ this.expando ][ camelCase( key ) ]; + }, + access: function( owner, key, value ) { + + // In cases where either: + // + // 1. No key was specified + // 2. A string key was specified, but no value provided + // + // Take the "read" path and allow the get method to determine + // which value to return, respectively either: + // + // 1. The entire cache object + // 2. The data stored at the key + // + if ( key === undefined || + ( ( key && typeof key === "string" ) && value === undefined ) ) { + + return this.get( owner, key ); + } + + // When the key is not a string, or both a key and value + // are specified, set or extend (existing objects) with either: + // + // 1. An object of properties + // 2. A key and value + // + this.set( owner, key, value ); + + // Since the "set" path can have two possible entry points + // return the expected data based on which path was taken[*] + return value !== undefined ? value : key; + }, + remove: function( owner, key ) { + var i, + cache = owner[ this.expando ]; + + if ( cache === undefined ) { + return; + } + + if ( key !== undefined ) { + + // Support array or space separated string of keys + if ( Array.isArray( key ) ) { + + // If key is an array of keys... + // We always set camelCase keys, so remove that. + key = key.map( camelCase ); + } else { + key = camelCase( key ); + + // If a key with the spaces exists, use it. + // Otherwise, create an array by matching non-whitespace + key = key in cache ? + [ key ] : + ( key.match( rnothtmlwhite ) || [] ); + } + + i = key.length; + + while ( i-- ) { + delete cache[ key[ i ] ]; + } + } + + // Remove the expando if there's no more data + if ( key === undefined || jQuery.isEmptyObject( cache ) ) { + + // Support: Chrome <=35 - 45 + // Webkit & Blink performance suffers when deleting properties + // from DOM nodes, so set to undefined instead + // https://bugs.chromium.org/p/chromium/issues/detail?id=378607 (bug restricted) + if ( owner.nodeType ) { + owner[ this.expando ] = undefined; + } else { + delete owner[ this.expando ]; + } + } + }, + hasData: function( owner ) { + var cache = owner[ this.expando ]; + return cache !== undefined && !jQuery.isEmptyObject( cache ); + } +}; +var dataPriv = new Data(); + +var dataUser = new Data(); + + + +// Implementation Summary +// +// 1. Enforce API surface and semantic compatibility with 1.9.x branch +// 2. Improve the module's maintainability by reducing the storage +// paths to a single mechanism. +// 3. Use the same single mechanism to support "private" and "user" data. +// 4. _Never_ expose "private" data to user code (TODO: Drop _data, _removeData) +// 5. Avoid exposing implementation details on user objects (eg. expando properties) +// 6. Provide a clear path for implementation upgrade to WeakMap in 2014 + +var rbrace = /^(?:\{[\w\W]*\}|\[[\w\W]*\])$/, + rmultiDash = /[A-Z]/g; + +function getData( data ) { + if ( data === "true" ) { + return true; + } + + if ( data === "false" ) { + return false; + } + + if ( data === "null" ) { + return null; + } + + // Only convert to a number if it doesn't change the string + if ( data === +data + "" ) { + return +data; + } + + if ( rbrace.test( data ) ) { + return JSON.parse( data ); + } + + return data; +} + +function dataAttr( elem, key, data ) { + var name; + + // If nothing was found internally, try to fetch any + // data from the HTML5 data-* attribute + if ( data === undefined && elem.nodeType === 1 ) { + name = "data-" + key.replace( rmultiDash, "-$&" ).toLowerCase(); + data = elem.getAttribute( name ); + + if ( typeof data === "string" ) { + try { + data = getData( data ); + } catch ( e ) {} + + // Make sure we set the data so it isn't changed later + dataUser.set( elem, key, data ); + } else { + data = undefined; + } + } + return data; +} + +jQuery.extend( { + hasData: function( elem ) { + return dataUser.hasData( elem ) || dataPriv.hasData( elem ); + }, + + data: function( elem, name, data ) { + return dataUser.access( elem, name, data ); + }, + + removeData: function( elem, name ) { + dataUser.remove( elem, name ); + }, + + // TODO: Now that all calls to _data and _removeData have been replaced + // with direct calls to dataPriv methods, these can be deprecated. + _data: function( elem, name, data ) { + return dataPriv.access( elem, name, data ); + }, + + _removeData: function( elem, name ) { + dataPriv.remove( elem, name ); + } +} ); + +jQuery.fn.extend( { + data: function( key, value ) { + var i, name, data, + elem = this[ 0 ], + attrs = elem && elem.attributes; + + // Gets all values + if ( key === undefined ) { + if ( this.length ) { + data = dataUser.get( elem ); + + if ( elem.nodeType === 1 && !dataPriv.get( elem, "hasDataAttrs" ) ) { + i = attrs.length; + while ( i-- ) { + + // Support: IE 11 only + // The attrs elements can be null (#14894) + if ( attrs[ i ] ) { + name = attrs[ i ].name; + if ( name.indexOf( "data-" ) === 0 ) { + name = camelCase( name.slice( 5 ) ); + dataAttr( elem, name, data[ name ] ); + } + } + } + dataPriv.set( elem, "hasDataAttrs", true ); + } + } + + return data; + } + + // Sets multiple values + if ( typeof key === "object" ) { + return this.each( function() { + dataUser.set( this, key ); + } ); + } + + return access( this, function( value ) { + var data; + + // The calling jQuery object (element matches) is not empty + // (and therefore has an element appears at this[ 0 ]) and the + // `value` parameter was not undefined. An empty jQuery object + // will result in `undefined` for elem = this[ 0 ] which will + // throw an exception if an attempt to read a data cache is made. + if ( elem && value === undefined ) { + + // Attempt to get data from the cache + // The key will always be camelCased in Data + data = dataUser.get( elem, key ); + if ( data !== undefined ) { + return data; + } + + // Attempt to "discover" the data in + // HTML5 custom data-* attrs + data = dataAttr( elem, key ); + if ( data !== undefined ) { + return data; + } + + // We tried really hard, but the data doesn't exist. + return; + } + + // Set the data... + this.each( function() { + + // We always store the camelCased key + dataUser.set( this, key, value ); + } ); + }, null, value, arguments.length > 1, null, true ); + }, + + removeData: function( key ) { + return this.each( function() { + dataUser.remove( this, key ); + } ); + } +} ); + + +jQuery.extend( { + queue: function( elem, type, data ) { + var queue; + + if ( elem ) { + type = ( type || "fx" ) + "queue"; + queue = dataPriv.get( elem, type ); + + // Speed up dequeue by getting out quickly if this is just a lookup + if ( data ) { + if ( !queue || Array.isArray( data ) ) { + queue = dataPriv.access( elem, type, jQuery.makeArray( data ) ); + } else { + queue.push( data ); + } + } + return queue || []; + } + }, + + dequeue: function( elem, type ) { + type = type || "fx"; + + var queue = jQuery.queue( elem, type ), + startLength = queue.length, + fn = queue.shift(), + hooks = jQuery._queueHooks( elem, type ), + next = function() { + jQuery.dequeue( elem, type ); + }; + + // If the fx queue is dequeued, always remove the progress sentinel + if ( fn === "inprogress" ) { + fn = queue.shift(); + startLength--; + } + + if ( fn ) { + + // Add a progress sentinel to prevent the fx queue from being + // automatically dequeued + if ( type === "fx" ) { + queue.unshift( "inprogress" ); + } + + // Clear up the last queue stop function + delete hooks.stop; + fn.call( elem, next, hooks ); + } + + if ( !startLength && hooks ) { + hooks.empty.fire(); + } + }, + + // Not public - generate a queueHooks object, or return the current one + _queueHooks: function( elem, type ) { + var key = type + "queueHooks"; + return dataPriv.get( elem, key ) || dataPriv.access( elem, key, { + empty: jQuery.Callbacks( "once memory" ).add( function() { + dataPriv.remove( elem, [ type + "queue", key ] ); + } ) + } ); + } +} ); + +jQuery.fn.extend( { + queue: function( type, data ) { + var setter = 2; + + if ( typeof type !== "string" ) { + data = type; + type = "fx"; + setter--; + } + + if ( arguments.length < setter ) { + return jQuery.queue( this[ 0 ], type ); + } + + return data === undefined ? + this : + this.each( function() { + var queue = jQuery.queue( this, type, data ); + + // Ensure a hooks for this queue + jQuery._queueHooks( this, type ); + + if ( type === "fx" && queue[ 0 ] !== "inprogress" ) { + jQuery.dequeue( this, type ); + } + } ); + }, + dequeue: function( type ) { + return this.each( function() { + jQuery.dequeue( this, type ); + } ); + }, + clearQueue: function( type ) { + return this.queue( type || "fx", [] ); + }, + + // Get a promise resolved when queues of a certain type + // are emptied (fx is the type by default) + promise: function( type, obj ) { + var tmp, + count = 1, + defer = jQuery.Deferred(), + elements = this, + i = this.length, + resolve = function() { + if ( !( --count ) ) { + defer.resolveWith( elements, [ elements ] ); + } + }; + + if ( typeof type !== "string" ) { + obj = type; + type = undefined; + } + type = type || "fx"; + + while ( i-- ) { + tmp = dataPriv.get( elements[ i ], type + "queueHooks" ); + if ( tmp && tmp.empty ) { + count++; + tmp.empty.add( resolve ); + } + } + resolve(); + return defer.promise( obj ); + } +} ); +var pnum = ( /[+-]?(?:\d*\.|)\d+(?:[eE][+-]?\d+|)/ ).source; + +var rcssNum = new RegExp( "^(?:([+-])=|)(" + pnum + ")([a-z%]*)$", "i" ); + + +var cssExpand = [ "Top", "Right", "Bottom", "Left" ]; + +var documentElement = document.documentElement; + + + + var isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ); + }, + composed = { composed: true }; + + // Support: IE 9 - 11+, Edge 12 - 18+, iOS 10.0 - 10.2 only + // Check attachment across shadow DOM boundaries when possible (gh-3504) + // Support: iOS 10.0-10.2 only + // Early iOS 10 versions support `attachShadow` but not `getRootNode`, + // leading to errors. We need to check for `getRootNode`. + if ( documentElement.getRootNode ) { + isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ) || + elem.getRootNode( composed ) === elem.ownerDocument; + }; + } +var isHiddenWithinTree = function( elem, el ) { + + // isHiddenWithinTree might be called from jQuery#filter function; + // in that case, element will be second argument + elem = el || elem; + + // Inline style trumps all + return elem.style.display === "none" || + elem.style.display === "" && + + // Otherwise, check computed style + // Support: Firefox <=43 - 45 + // Disconnected elements can have computed display: none, so first confirm that elem is + // in the document. + isAttached( elem ) && + + jQuery.css( elem, "display" ) === "none"; + }; + + + +function adjustCSS( elem, prop, valueParts, tween ) { + var adjusted, scale, + maxIterations = 20, + currentValue = tween ? + function() { + return tween.cur(); + } : + function() { + return jQuery.css( elem, prop, "" ); + }, + initial = currentValue(), + unit = valueParts && valueParts[ 3 ] || ( jQuery.cssNumber[ prop ] ? "" : "px" ), + + // Starting value computation is required for potential unit mismatches + initialInUnit = elem.nodeType && + ( jQuery.cssNumber[ prop ] || unit !== "px" && +initial ) && + rcssNum.exec( jQuery.css( elem, prop ) ); + + if ( initialInUnit && initialInUnit[ 3 ] !== unit ) { + + // Support: Firefox <=54 + // Halve the iteration target value to prevent interference from CSS upper bounds (gh-2144) + initial = initial / 2; + + // Trust units reported by jQuery.css + unit = unit || initialInUnit[ 3 ]; + + // Iteratively approximate from a nonzero starting point + initialInUnit = +initial || 1; + + while ( maxIterations-- ) { + + // Evaluate and update our best guess (doubling guesses that zero out). + // Finish if the scale equals or crosses 1 (making the old*new product non-positive). + jQuery.style( elem, prop, initialInUnit + unit ); + if ( ( 1 - scale ) * ( 1 - ( scale = currentValue() / initial || 0.5 ) ) <= 0 ) { + maxIterations = 0; + } + initialInUnit = initialInUnit / scale; + + } + + initialInUnit = initialInUnit * 2; + jQuery.style( elem, prop, initialInUnit + unit ); + + // Make sure we update the tween properties later on + valueParts = valueParts || []; + } + + if ( valueParts ) { + initialInUnit = +initialInUnit || +initial || 0; + + // Apply relative offset (+=/-=) if specified + adjusted = valueParts[ 1 ] ? + initialInUnit + ( valueParts[ 1 ] + 1 ) * valueParts[ 2 ] : + +valueParts[ 2 ]; + if ( tween ) { + tween.unit = unit; + tween.start = initialInUnit; + tween.end = adjusted; + } + } + return adjusted; +} + + +var defaultDisplayMap = {}; + +function getDefaultDisplay( elem ) { + var temp, + doc = elem.ownerDocument, + nodeName = elem.nodeName, + display = defaultDisplayMap[ nodeName ]; + + if ( display ) { + return display; + } + + temp = doc.body.appendChild( doc.createElement( nodeName ) ); + display = jQuery.css( temp, "display" ); + + temp.parentNode.removeChild( temp ); + + if ( display === "none" ) { + display = "block"; + } + defaultDisplayMap[ nodeName ] = display; + + return display; +} + +function showHide( elements, show ) { + var display, elem, + values = [], + index = 0, + length = elements.length; + + // Determine new display value for elements that need to change + for ( ; index < length; index++ ) { + elem = elements[ index ]; + if ( !elem.style ) { + continue; + } + + display = elem.style.display; + if ( show ) { + + // Since we force visibility upon cascade-hidden elements, an immediate (and slow) + // check is required in this first loop unless we have a nonempty display value (either + // inline or about-to-be-restored) + if ( display === "none" ) { + values[ index ] = dataPriv.get( elem, "display" ) || null; + if ( !values[ index ] ) { + elem.style.display = ""; + } + } + if ( elem.style.display === "" && isHiddenWithinTree( elem ) ) { + values[ index ] = getDefaultDisplay( elem ); + } + } else { + if ( display !== "none" ) { + values[ index ] = "none"; + + // Remember what we're overwriting + dataPriv.set( elem, "display", display ); + } + } + } + + // Set the display of the elements in a second loop to avoid constant reflow + for ( index = 0; index < length; index++ ) { + if ( values[ index ] != null ) { + elements[ index ].style.display = values[ index ]; + } + } + + return elements; +} + +jQuery.fn.extend( { + show: function() { + return showHide( this, true ); + }, + hide: function() { + return showHide( this ); + }, + toggle: function( state ) { + if ( typeof state === "boolean" ) { + return state ? this.show() : this.hide(); + } + + return this.each( function() { + if ( isHiddenWithinTree( this ) ) { + jQuery( this ).show(); + } else { + jQuery( this ).hide(); + } + } ); + } +} ); +var rcheckableType = ( /^(?:checkbox|radio)$/i ); + +var rtagName = ( /<([a-z][^\/\0>\x20\t\r\n\f]*)/i ); + +var rscriptType = ( /^$|^module$|\/(?:java|ecma)script/i ); + + + +( function() { + var fragment = document.createDocumentFragment(), + div = fragment.appendChild( document.createElement( "div" ) ), + input = document.createElement( "input" ); + + // Support: Android 4.0 - 4.3 only + // Check state lost if the name is set (#11217) + // Support: Windows Web Apps (WWA) + // `name` and `type` must use .setAttribute for WWA (#14901) + input.setAttribute( "type", "radio" ); + input.setAttribute( "checked", "checked" ); + input.setAttribute( "name", "t" ); + + div.appendChild( input ); + + // Support: Android <=4.1 only + // Older WebKit doesn't clone checked state correctly in fragments + support.checkClone = div.cloneNode( true ).cloneNode( true ).lastChild.checked; + + // Support: IE <=11 only + // Make sure textarea (and checkbox) defaultValue is properly cloned + div.innerHTML = "<textarea>x</textarea>"; + support.noCloneChecked = !!div.cloneNode( true ).lastChild.defaultValue; + + // Support: IE <=9 only + // IE <=9 replaces <option> tags with their contents when inserted outside of + // the select element. + div.innerHTML = "<option></option>"; + support.option = !!div.lastChild; +} )(); + + +// We have to close these tags to support XHTML (#13200) +var wrapMap = { + + // XHTML parsers do not magically insert elements in the + // same way that tag soup parsers do. So we cannot shorten + // this by omitting <tbody> or other required elements. + thead: [ 1, "<table>", "</table>" ], + col: [ 2, "<table><colgroup>", "</colgroup></table>" ], + tr: [ 2, "<table><tbody>", "</tbody></table>" ], + td: [ 3, "<table><tbody><tr>", "</tr></tbody></table>" ], + + _default: [ 0, "", "" ] +}; + +wrapMap.tbody = wrapMap.tfoot = wrapMap.colgroup = wrapMap.caption = wrapMap.thead; +wrapMap.th = wrapMap.td; + +// Support: IE <=9 only +if ( !support.option ) { + wrapMap.optgroup = wrapMap.option = [ 1, "<select multiple='multiple'>", "</select>" ]; +} + + +function getAll( context, tag ) { + + // Support: IE <=9 - 11 only + // Use typeof to avoid zero-argument method invocation on host objects (#15151) + var ret; + + if ( typeof context.getElementsByTagName !== "undefined" ) { + ret = context.getElementsByTagName( tag || "*" ); + + } else if ( typeof context.querySelectorAll !== "undefined" ) { + ret = context.querySelectorAll( tag || "*" ); + + } else { + ret = []; + } + + if ( tag === undefined || tag && nodeName( context, tag ) ) { + return jQuery.merge( [ context ], ret ); + } + + return ret; +} + + +// Mark scripts as having already been evaluated +function setGlobalEval( elems, refElements ) { + var i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + dataPriv.set( + elems[ i ], + "globalEval", + !refElements || dataPriv.get( refElements[ i ], "globalEval" ) + ); + } +} + + +var rhtml = /<|&#?\w+;/; + +function buildFragment( elems, context, scripts, selection, ignored ) { + var elem, tmp, tag, wrap, attached, j, + fragment = context.createDocumentFragment(), + nodes = [], + i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + elem = elems[ i ]; + + if ( elem || elem === 0 ) { + + // Add nodes directly + if ( toType( elem ) === "object" ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, elem.nodeType ? [ elem ] : elem ); + + // Convert non-html into a text node + } else if ( !rhtml.test( elem ) ) { + nodes.push( context.createTextNode( elem ) ); + + // Convert html into DOM nodes + } else { + tmp = tmp || fragment.appendChild( context.createElement( "div" ) ); + + // Deserialize a standard representation + tag = ( rtagName.exec( elem ) || [ "", "" ] )[ 1 ].toLowerCase(); + wrap = wrapMap[ tag ] || wrapMap._default; + tmp.innerHTML = wrap[ 1 ] + jQuery.htmlPrefilter( elem ) + wrap[ 2 ]; + + // Descend through wrappers to the right content + j = wrap[ 0 ]; + while ( j-- ) { + tmp = tmp.lastChild; + } + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, tmp.childNodes ); + + // Remember the top-level container + tmp = fragment.firstChild; + + // Ensure the created nodes are orphaned (#12392) + tmp.textContent = ""; + } + } + } + + // Remove wrapper from fragment + fragment.textContent = ""; + + i = 0; + while ( ( elem = nodes[ i++ ] ) ) { + + // Skip elements already in the context collection (trac-4087) + if ( selection && jQuery.inArray( elem, selection ) > -1 ) { + if ( ignored ) { + ignored.push( elem ); + } + continue; + } + + attached = isAttached( elem ); + + // Append to fragment + tmp = getAll( fragment.appendChild( elem ), "script" ); + + // Preserve script evaluation history + if ( attached ) { + setGlobalEval( tmp ); + } + + // Capture executables + if ( scripts ) { + j = 0; + while ( ( elem = tmp[ j++ ] ) ) { + if ( rscriptType.test( elem.type || "" ) ) { + scripts.push( elem ); + } + } + } + } + + return fragment; +} + + +var + rkeyEvent = /^key/, + rmouseEvent = /^(?:mouse|pointer|contextmenu|drag|drop)|click/, + rtypenamespace = /^([^.]*)(?:\.(.+)|)/; + +function returnTrue() { + return true; +} + +function returnFalse() { + return false; +} + +// Support: IE <=9 - 11+ +// focus() and blur() are asynchronous, except when they are no-op. +// So expect focus to be synchronous when the element is already active, +// and blur to be synchronous when the element is not already active. +// (focus and blur are always synchronous in other supported browsers, +// this just defines when we can count on it). +function expectSync( elem, type ) { + return ( elem === safeActiveElement() ) === ( type === "focus" ); +} + +// Support: IE <=9 only +// Accessing document.activeElement can throw unexpectedly +// https://bugs.jquery.com/ticket/13393 +function safeActiveElement() { + try { + return document.activeElement; + } catch ( err ) { } +} + +function on( elem, types, selector, data, fn, one ) { + var origFn, type; + + // Types can be a map of types/handlers + if ( typeof types === "object" ) { + + // ( types-Object, selector, data ) + if ( typeof selector !== "string" ) { + + // ( types-Object, data ) + data = data || selector; + selector = undefined; + } + for ( type in types ) { + on( elem, type, selector, data, types[ type ], one ); + } + return elem; + } + + if ( data == null && fn == null ) { + + // ( types, fn ) + fn = selector; + data = selector = undefined; + } else if ( fn == null ) { + if ( typeof selector === "string" ) { + + // ( types, selector, fn ) + fn = data; + data = undefined; + } else { + + // ( types, data, fn ) + fn = data; + data = selector; + selector = undefined; + } + } + if ( fn === false ) { + fn = returnFalse; + } else if ( !fn ) { + return elem; + } + + if ( one === 1 ) { + origFn = fn; + fn = function( event ) { + + // Can use an empty set, since event contains the info + jQuery().off( event ); + return origFn.apply( this, arguments ); + }; + + // Use same guid so caller can remove using origFn + fn.guid = origFn.guid || ( origFn.guid = jQuery.guid++ ); + } + return elem.each( function() { + jQuery.event.add( this, types, fn, data, selector ); + } ); +} + +/* + * Helper functions for managing events -- not part of the public interface. + * Props to Dean Edwards' addEvent library for many of the ideas. + */ +jQuery.event = { + + global: {}, + + add: function( elem, types, handler, data, selector ) { + + var handleObjIn, eventHandle, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.get( elem ); + + // Only attach events to objects that accept data + if ( !acceptData( elem ) ) { + return; + } + + // Caller can pass in an object of custom data in lieu of the handler + if ( handler.handler ) { + handleObjIn = handler; + handler = handleObjIn.handler; + selector = handleObjIn.selector; + } + + // Ensure that invalid selectors throw exceptions at attach time + // Evaluate against documentElement in case elem is a non-element node (e.g., document) + if ( selector ) { + jQuery.find.matchesSelector( documentElement, selector ); + } + + // Make sure that the handler has a unique ID, used to find/remove it later + if ( !handler.guid ) { + handler.guid = jQuery.guid++; + } + + // Init the element's event structure and main handler, if this is the first + if ( !( events = elemData.events ) ) { + events = elemData.events = Object.create( null ); + } + if ( !( eventHandle = elemData.handle ) ) { + eventHandle = elemData.handle = function( e ) { + + // Discard the second event of a jQuery.event.trigger() and + // when an event is called after a page has unloaded + return typeof jQuery !== "undefined" && jQuery.event.triggered !== e.type ? + jQuery.event.dispatch.apply( elem, arguments ) : undefined; + }; + } + + // Handle multiple events separated by a space + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // There *must* be a type, no attaching namespace-only handlers + if ( !type ) { + continue; + } + + // If event changes its type, use the special event handlers for the changed type + special = jQuery.event.special[ type ] || {}; + + // If selector defined, determine special event api type, otherwise given type + type = ( selector ? special.delegateType : special.bindType ) || type; + + // Update special based on newly reset type + special = jQuery.event.special[ type ] || {}; + + // handleObj is passed to all event handlers + handleObj = jQuery.extend( { + type: type, + origType: origType, + data: data, + handler: handler, + guid: handler.guid, + selector: selector, + needsContext: selector && jQuery.expr.match.needsContext.test( selector ), + namespace: namespaces.join( "." ) + }, handleObjIn ); + + // Init the event handler queue if we're the first + if ( !( handlers = events[ type ] ) ) { + handlers = events[ type ] = []; + handlers.delegateCount = 0; + + // Only use addEventListener if the special events handler returns false + if ( !special.setup || + special.setup.call( elem, data, namespaces, eventHandle ) === false ) { + + if ( elem.addEventListener ) { + elem.addEventListener( type, eventHandle ); + } + } + } + + if ( special.add ) { + special.add.call( elem, handleObj ); + + if ( !handleObj.handler.guid ) { + handleObj.handler.guid = handler.guid; + } + } + + // Add to the element's handler list, delegates in front + if ( selector ) { + handlers.splice( handlers.delegateCount++, 0, handleObj ); + } else { + handlers.push( handleObj ); + } + + // Keep track of which events have ever been used, for event optimization + jQuery.event.global[ type ] = true; + } + + }, + + // Detach an event or set of events from an element + remove: function( elem, types, handler, selector, mappedTypes ) { + + var j, origCount, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.hasData( elem ) && dataPriv.get( elem ); + + if ( !elemData || !( events = elemData.events ) ) { + return; + } + + // Once for each type.namespace in types; type may be omitted + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // Unbind all events (on this namespace, if provided) for the element + if ( !type ) { + for ( type in events ) { + jQuery.event.remove( elem, type + types[ t ], handler, selector, true ); + } + continue; + } + + special = jQuery.event.special[ type ] || {}; + type = ( selector ? special.delegateType : special.bindType ) || type; + handlers = events[ type ] || []; + tmp = tmp[ 2 ] && + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ); + + // Remove matching events + origCount = j = handlers.length; + while ( j-- ) { + handleObj = handlers[ j ]; + + if ( ( mappedTypes || origType === handleObj.origType ) && + ( !handler || handler.guid === handleObj.guid ) && + ( !tmp || tmp.test( handleObj.namespace ) ) && + ( !selector || selector === handleObj.selector || + selector === "**" && handleObj.selector ) ) { + handlers.splice( j, 1 ); + + if ( handleObj.selector ) { + handlers.delegateCount--; + } + if ( special.remove ) { + special.remove.call( elem, handleObj ); + } + } + } + + // Remove generic event handler if we removed something and no more handlers exist + // (avoids potential for endless recursion during removal of special event handlers) + if ( origCount && !handlers.length ) { + if ( !special.teardown || + special.teardown.call( elem, namespaces, elemData.handle ) === false ) { + + jQuery.removeEvent( elem, type, elemData.handle ); + } + + delete events[ type ]; + } + } + + // Remove data and the expando if it's no longer used + if ( jQuery.isEmptyObject( events ) ) { + dataPriv.remove( elem, "handle events" ); + } + }, + + dispatch: function( nativeEvent ) { + + var i, j, ret, matched, handleObj, handlerQueue, + args = new Array( arguments.length ), + + // Make a writable jQuery.Event from the native event object + event = jQuery.event.fix( nativeEvent ), + + handlers = ( + dataPriv.get( this, "events" ) || Object.create( null ) + )[ event.type ] || [], + special = jQuery.event.special[ event.type ] || {}; + + // Use the fix-ed jQuery.Event rather than the (read-only) native event + args[ 0 ] = event; + + for ( i = 1; i < arguments.length; i++ ) { + args[ i ] = arguments[ i ]; + } + + event.delegateTarget = this; + + // Call the preDispatch hook for the mapped type, and let it bail if desired + if ( special.preDispatch && special.preDispatch.call( this, event ) === false ) { + return; + } + + // Determine handlers + handlerQueue = jQuery.event.handlers.call( this, event, handlers ); + + // Run delegates first; they may want to stop propagation beneath us + i = 0; + while ( ( matched = handlerQueue[ i++ ] ) && !event.isPropagationStopped() ) { + event.currentTarget = matched.elem; + + j = 0; + while ( ( handleObj = matched.handlers[ j++ ] ) && + !event.isImmediatePropagationStopped() ) { + + // If the event is namespaced, then each handler is only invoked if it is + // specially universal or its namespaces are a superset of the event's. + if ( !event.rnamespace || handleObj.namespace === false || + event.rnamespace.test( handleObj.namespace ) ) { + + event.handleObj = handleObj; + event.data = handleObj.data; + + ret = ( ( jQuery.event.special[ handleObj.origType ] || {} ).handle || + handleObj.handler ).apply( matched.elem, args ); + + if ( ret !== undefined ) { + if ( ( event.result = ret ) === false ) { + event.preventDefault(); + event.stopPropagation(); + } + } + } + } + } + + // Call the postDispatch hook for the mapped type + if ( special.postDispatch ) { + special.postDispatch.call( this, event ); + } + + return event.result; + }, + + handlers: function( event, handlers ) { + var i, handleObj, sel, matchedHandlers, matchedSelectors, + handlerQueue = [], + delegateCount = handlers.delegateCount, + cur = event.target; + + // Find delegate handlers + if ( delegateCount && + + // Support: IE <=9 + // Black-hole SVG <use> instance trees (trac-13180) + cur.nodeType && + + // Support: Firefox <=42 + // Suppress spec-violating clicks indicating a non-primary pointer button (trac-3861) + // https://www.w3.org/TR/DOM-Level-3-Events/#event-type-click + // Support: IE 11 only + // ...but not arrow key "clicks" of radio inputs, which can have `button` -1 (gh-2343) + !( event.type === "click" && event.button >= 1 ) ) { + + for ( ; cur !== this; cur = cur.parentNode || this ) { + + // Don't check non-elements (#13208) + // Don't process clicks on disabled elements (#6911, #8165, #11382, #11764) + if ( cur.nodeType === 1 && !( event.type === "click" && cur.disabled === true ) ) { + matchedHandlers = []; + matchedSelectors = {}; + for ( i = 0; i < delegateCount; i++ ) { + handleObj = handlers[ i ]; + + // Don't conflict with Object.prototype properties (#13203) + sel = handleObj.selector + " "; + + if ( matchedSelectors[ sel ] === undefined ) { + matchedSelectors[ sel ] = handleObj.needsContext ? + jQuery( sel, this ).index( cur ) > -1 : + jQuery.find( sel, this, null, [ cur ] ).length; + } + if ( matchedSelectors[ sel ] ) { + matchedHandlers.push( handleObj ); + } + } + if ( matchedHandlers.length ) { + handlerQueue.push( { elem: cur, handlers: matchedHandlers } ); + } + } + } + } + + // Add the remaining (directly-bound) handlers + cur = this; + if ( delegateCount < handlers.length ) { + handlerQueue.push( { elem: cur, handlers: handlers.slice( delegateCount ) } ); + } + + return handlerQueue; + }, + + addProp: function( name, hook ) { + Object.defineProperty( jQuery.Event.prototype, name, { + enumerable: true, + configurable: true, + + get: isFunction( hook ) ? + function() { + if ( this.originalEvent ) { + return hook( this.originalEvent ); + } + } : + function() { + if ( this.originalEvent ) { + return this.originalEvent[ name ]; + } + }, + + set: function( value ) { + Object.defineProperty( this, name, { + enumerable: true, + configurable: true, + writable: true, + value: value + } ); + } + } ); + }, + + fix: function( originalEvent ) { + return originalEvent[ jQuery.expando ] ? + originalEvent : + new jQuery.Event( originalEvent ); + }, + + special: { + load: { + + // Prevent triggered image.load events from bubbling to window.load + noBubble: true + }, + click: { + + // Utilize native event to ensure correct state for checkable inputs + setup: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Claim the first handler + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + // dataPriv.set( el, "click", ... ) + leverageNative( el, "click", returnTrue ); + } + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Force setup before triggering a click + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + leverageNative( el, "click" ); + } + + // Return non-false to allow normal event-path propagation + return true; + }, + + // For cross-browser consistency, suppress native .click() on links + // Also prevent it if we're currently inside a leveraged native-event stack + _default: function( event ) { + var target = event.target; + return rcheckableType.test( target.type ) && + target.click && nodeName( target, "input" ) && + dataPriv.get( target, "click" ) || + nodeName( target, "a" ); + } + }, + + beforeunload: { + postDispatch: function( event ) { + + // Support: Firefox 20+ + // Firefox doesn't alert if the returnValue field is not set. + if ( event.result !== undefined && event.originalEvent ) { + event.originalEvent.returnValue = event.result; + } + } + } + } +}; + +// Ensure the presence of an event listener that handles manually-triggered +// synthetic events by interrupting progress until reinvoked in response to +// *native* events that it fires directly, ensuring that state changes have +// already occurred before other listeners are invoked. +function leverageNative( el, type, expectSync ) { + + // Missing expectSync indicates a trigger call, which must force setup through jQuery.event.add + if ( !expectSync ) { + if ( dataPriv.get( el, type ) === undefined ) { + jQuery.event.add( el, type, returnTrue ); + } + return; + } + + // Register the controller as a special universal handler for all event namespaces + dataPriv.set( el, type, false ); + jQuery.event.add( el, type, { + namespace: false, + handler: function( event ) { + var notAsync, result, + saved = dataPriv.get( this, type ); + + if ( ( event.isTrigger & 1 ) && this[ type ] ) { + + // Interrupt processing of the outer synthetic .trigger()ed event + // Saved data should be false in such cases, but might be a leftover capture object + // from an async native handler (gh-4350) + if ( !saved.length ) { + + // Store arguments for use when handling the inner native event + // There will always be at least one argument (an event object), so this array + // will not be confused with a leftover capture object. + saved = slice.call( arguments ); + dataPriv.set( this, type, saved ); + + // Trigger the native event and capture its result + // Support: IE <=9 - 11+ + // focus() and blur() are asynchronous + notAsync = expectSync( this, type ); + this[ type ](); + result = dataPriv.get( this, type ); + if ( saved !== result || notAsync ) { + dataPriv.set( this, type, false ); + } else { + result = {}; + } + if ( saved !== result ) { + + // Cancel the outer synthetic event + event.stopImmediatePropagation(); + event.preventDefault(); + return result.value; + } + + // If this is an inner synthetic event for an event with a bubbling surrogate + // (focus or blur), assume that the surrogate already propagated from triggering the + // native event and prevent that from happening again here. + // This technically gets the ordering wrong w.r.t. to `.trigger()` (in which the + // bubbling surrogate propagates *after* the non-bubbling base), but that seems + // less bad than duplication. + } else if ( ( jQuery.event.special[ type ] || {} ).delegateType ) { + event.stopPropagation(); + } + + // If this is a native event triggered above, everything is now in order + // Fire an inner synthetic event with the original arguments + } else if ( saved.length ) { + + // ...and capture the result + dataPriv.set( this, type, { + value: jQuery.event.trigger( + + // Support: IE <=9 - 11+ + // Extend with the prototype to reset the above stopImmediatePropagation() + jQuery.extend( saved[ 0 ], jQuery.Event.prototype ), + saved.slice( 1 ), + this + ) + } ); + + // Abort handling of the native event + event.stopImmediatePropagation(); + } + } + } ); +} + +jQuery.removeEvent = function( elem, type, handle ) { + + // This "if" is needed for plain objects + if ( elem.removeEventListener ) { + elem.removeEventListener( type, handle ); + } +}; + +jQuery.Event = function( src, props ) { + + // Allow instantiation without the 'new' keyword + if ( !( this instanceof jQuery.Event ) ) { + return new jQuery.Event( src, props ); + } + + // Event object + if ( src && src.type ) { + this.originalEvent = src; + this.type = src.type; + + // Events bubbling up the document may have been marked as prevented + // by a handler lower down the tree; reflect the correct value. + this.isDefaultPrevented = src.defaultPrevented || + src.defaultPrevented === undefined && + + // Support: Android <=2.3 only + src.returnValue === false ? + returnTrue : + returnFalse; + + // Create target properties + // Support: Safari <=6 - 7 only + // Target should not be a text node (#504, #13143) + this.target = ( src.target && src.target.nodeType === 3 ) ? + src.target.parentNode : + src.target; + + this.currentTarget = src.currentTarget; + this.relatedTarget = src.relatedTarget; + + // Event type + } else { + this.type = src; + } + + // Put explicitly provided properties onto the event object + if ( props ) { + jQuery.extend( this, props ); + } + + // Create a timestamp if incoming event doesn't have one + this.timeStamp = src && src.timeStamp || Date.now(); + + // Mark it as fixed + this[ jQuery.expando ] = true; +}; + +// jQuery.Event is based on DOM3 Events as specified by the ECMAScript Language Binding +// https://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/ecma-script-binding.html +jQuery.Event.prototype = { + constructor: jQuery.Event, + isDefaultPrevented: returnFalse, + isPropagationStopped: returnFalse, + isImmediatePropagationStopped: returnFalse, + isSimulated: false, + + preventDefault: function() { + var e = this.originalEvent; + + this.isDefaultPrevented = returnTrue; + + if ( e && !this.isSimulated ) { + e.preventDefault(); + } + }, + stopPropagation: function() { + var e = this.originalEvent; + + this.isPropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopPropagation(); + } + }, + stopImmediatePropagation: function() { + var e = this.originalEvent; + + this.isImmediatePropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopImmediatePropagation(); + } + + this.stopPropagation(); + } +}; + +// Includes all common event props including KeyEvent and MouseEvent specific props +jQuery.each( { + altKey: true, + bubbles: true, + cancelable: true, + changedTouches: true, + ctrlKey: true, + detail: true, + eventPhase: true, + metaKey: true, + pageX: true, + pageY: true, + shiftKey: true, + view: true, + "char": true, + code: true, + charCode: true, + key: true, + keyCode: true, + button: true, + buttons: true, + clientX: true, + clientY: true, + offsetX: true, + offsetY: true, + pointerId: true, + pointerType: true, + screenX: true, + screenY: true, + targetTouches: true, + toElement: true, + touches: true, + + which: function( event ) { + var button = event.button; + + // Add which for key events + if ( event.which == null && rkeyEvent.test( event.type ) ) { + return event.charCode != null ? event.charCode : event.keyCode; + } + + // Add which for click: 1 === left; 2 === middle; 3 === right + if ( !event.which && button !== undefined && rmouseEvent.test( event.type ) ) { + if ( button & 1 ) { + return 1; + } + + if ( button & 2 ) { + return 3; + } + + if ( button & 4 ) { + return 2; + } + + return 0; + } + + return event.which; + } +}, jQuery.event.addProp ); + +jQuery.each( { focus: "focusin", blur: "focusout" }, function( type, delegateType ) { + jQuery.event.special[ type ] = { + + // Utilize native event if possible so blur/focus sequence is correct + setup: function() { + + // Claim the first handler + // dataPriv.set( this, "focus", ... ) + // dataPriv.set( this, "blur", ... ) + leverageNative( this, type, expectSync ); + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function() { + + // Force setup before trigger + leverageNative( this, type ); + + // Return non-false to allow normal event-path propagation + return true; + }, + + delegateType: delegateType + }; +} ); + +// Create mouseenter/leave events using mouseover/out and event-time checks +// so that event delegation works in jQuery. +// Do the same for pointerenter/pointerleave and pointerover/pointerout +// +// Support: Safari 7 only +// Safari sends mouseenter too often; see: +// https://bugs.chromium.org/p/chromium/issues/detail?id=470258 +// for the description of the bug (it existed in older Chrome versions as well). +jQuery.each( { + mouseenter: "mouseover", + mouseleave: "mouseout", + pointerenter: "pointerover", + pointerleave: "pointerout" +}, function( orig, fix ) { + jQuery.event.special[ orig ] = { + delegateType: fix, + bindType: fix, + + handle: function( event ) { + var ret, + target = this, + related = event.relatedTarget, + handleObj = event.handleObj; + + // For mouseenter/leave call the handler if related is outside the target. + // NB: No relatedTarget if the mouse left/entered the browser window + if ( !related || ( related !== target && !jQuery.contains( target, related ) ) ) { + event.type = handleObj.origType; + ret = handleObj.handler.apply( this, arguments ); + event.type = fix; + } + return ret; + } + }; +} ); + +jQuery.fn.extend( { + + on: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn ); + }, + one: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn, 1 ); + }, + off: function( types, selector, fn ) { + var handleObj, type; + if ( types && types.preventDefault && types.handleObj ) { + + // ( event ) dispatched jQuery.Event + handleObj = types.handleObj; + jQuery( types.delegateTarget ).off( + handleObj.namespace ? + handleObj.origType + "." + handleObj.namespace : + handleObj.origType, + handleObj.selector, + handleObj.handler + ); + return this; + } + if ( typeof types === "object" ) { + + // ( types-object [, selector] ) + for ( type in types ) { + this.off( type, selector, types[ type ] ); + } + return this; + } + if ( selector === false || typeof selector === "function" ) { + + // ( types [, fn] ) + fn = selector; + selector = undefined; + } + if ( fn === false ) { + fn = returnFalse; + } + return this.each( function() { + jQuery.event.remove( this, types, fn, selector ); + } ); + } +} ); + + +var + + // Support: IE <=10 - 11, Edge 12 - 13 only + // In IE/Edge using regex groups here causes severe slowdowns. + // See https://connect.microsoft.com/IE/feedback/details/1736512/ + rnoInnerhtml = /<script|<style|<link/i, + + // checked="checked" or checked + rchecked = /checked\s*(?:[^=]|=\s*.checked.)/i, + rcleanScript = /^\s*<!(?:\[CDATA\[|--)|(?:\]\]|--)>\s*$/g; + +// Prefer a tbody over its parent table for containing new rows +function manipulationTarget( elem, content ) { + if ( nodeName( elem, "table" ) && + nodeName( content.nodeType !== 11 ? content : content.firstChild, "tr" ) ) { + + return jQuery( elem ).children( "tbody" )[ 0 ] || elem; + } + + return elem; +} + +// Replace/restore the type attribute of script elements for safe DOM manipulation +function disableScript( elem ) { + elem.type = ( elem.getAttribute( "type" ) !== null ) + "/" + elem.type; + return elem; +} +function restoreScript( elem ) { + if ( ( elem.type || "" ).slice( 0, 5 ) === "true/" ) { + elem.type = elem.type.slice( 5 ); + } else { + elem.removeAttribute( "type" ); + } + + return elem; +} + +function cloneCopyEvent( src, dest ) { + var i, l, type, pdataOld, udataOld, udataCur, events; + + if ( dest.nodeType !== 1 ) { + return; + } + + // 1. Copy private data: events, handlers, etc. + if ( dataPriv.hasData( src ) ) { + pdataOld = dataPriv.get( src ); + events = pdataOld.events; + + if ( events ) { + dataPriv.remove( dest, "handle events" ); + + for ( type in events ) { + for ( i = 0, l = events[ type ].length; i < l; i++ ) { + jQuery.event.add( dest, type, events[ type ][ i ] ); + } + } + } + } + + // 2. Copy user data + if ( dataUser.hasData( src ) ) { + udataOld = dataUser.access( src ); + udataCur = jQuery.extend( {}, udataOld ); + + dataUser.set( dest, udataCur ); + } +} + +// Fix IE bugs, see support tests +function fixInput( src, dest ) { + var nodeName = dest.nodeName.toLowerCase(); + + // Fails to persist the checked state of a cloned checkbox or radio button. + if ( nodeName === "input" && rcheckableType.test( src.type ) ) { + dest.checked = src.checked; + + // Fails to return the selected option to the default selected state when cloning options + } else if ( nodeName === "input" || nodeName === "textarea" ) { + dest.defaultValue = src.defaultValue; + } +} + +function domManip( collection, args, callback, ignored ) { + + // Flatten any nested arrays + args = flat( args ); + + var fragment, first, scripts, hasScripts, node, doc, + i = 0, + l = collection.length, + iNoClone = l - 1, + value = args[ 0 ], + valueIsFunction = isFunction( value ); + + // We can't cloneNode fragments that contain checked, in WebKit + if ( valueIsFunction || + ( l > 1 && typeof value === "string" && + !support.checkClone && rchecked.test( value ) ) ) { + return collection.each( function( index ) { + var self = collection.eq( index ); + if ( valueIsFunction ) { + args[ 0 ] = value.call( this, index, self.html() ); + } + domManip( self, args, callback, ignored ); + } ); + } + + if ( l ) { + fragment = buildFragment( args, collection[ 0 ].ownerDocument, false, collection, ignored ); + first = fragment.firstChild; + + if ( fragment.childNodes.length === 1 ) { + fragment = first; + } + + // Require either new content or an interest in ignored elements to invoke the callback + if ( first || ignored ) { + scripts = jQuery.map( getAll( fragment, "script" ), disableScript ); + hasScripts = scripts.length; + + // Use the original fragment for the last item + // instead of the first because it can end up + // being emptied incorrectly in certain situations (#8070). + for ( ; i < l; i++ ) { + node = fragment; + + if ( i !== iNoClone ) { + node = jQuery.clone( node, true, true ); + + // Keep references to cloned scripts for later restoration + if ( hasScripts ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( scripts, getAll( node, "script" ) ); + } + } + + callback.call( collection[ i ], node, i ); + } + + if ( hasScripts ) { + doc = scripts[ scripts.length - 1 ].ownerDocument; + + // Reenable scripts + jQuery.map( scripts, restoreScript ); + + // Evaluate executable scripts on first document insertion + for ( i = 0; i < hasScripts; i++ ) { + node = scripts[ i ]; + if ( rscriptType.test( node.type || "" ) && + !dataPriv.access( node, "globalEval" ) && + jQuery.contains( doc, node ) ) { + + if ( node.src && ( node.type || "" ).toLowerCase() !== "module" ) { + + // Optional AJAX dependency, but won't run scripts if not present + if ( jQuery._evalUrl && !node.noModule ) { + jQuery._evalUrl( node.src, { + nonce: node.nonce || node.getAttribute( "nonce" ) + }, doc ); + } + } else { + DOMEval( node.textContent.replace( rcleanScript, "" ), node, doc ); + } + } + } + } + } + } + + return collection; +} + +function remove( elem, selector, keepData ) { + var node, + nodes = selector ? jQuery.filter( selector, elem ) : elem, + i = 0; + + for ( ; ( node = nodes[ i ] ) != null; i++ ) { + if ( !keepData && node.nodeType === 1 ) { + jQuery.cleanData( getAll( node ) ); + } + + if ( node.parentNode ) { + if ( keepData && isAttached( node ) ) { + setGlobalEval( getAll( node, "script" ) ); + } + node.parentNode.removeChild( node ); + } + } + + return elem; +} + +jQuery.extend( { + htmlPrefilter: function( html ) { + return html; + }, + + clone: function( elem, dataAndEvents, deepDataAndEvents ) { + var i, l, srcElements, destElements, + clone = elem.cloneNode( true ), + inPage = isAttached( elem ); + + // Fix IE cloning issues + if ( !support.noCloneChecked && ( elem.nodeType === 1 || elem.nodeType === 11 ) && + !jQuery.isXMLDoc( elem ) ) { + + // We eschew Sizzle here for performance reasons: https://jsperf.com/getall-vs-sizzle/2 + destElements = getAll( clone ); + srcElements = getAll( elem ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + fixInput( srcElements[ i ], destElements[ i ] ); + } + } + + // Copy the events from the original to the clone + if ( dataAndEvents ) { + if ( deepDataAndEvents ) { + srcElements = srcElements || getAll( elem ); + destElements = destElements || getAll( clone ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + cloneCopyEvent( srcElements[ i ], destElements[ i ] ); + } + } else { + cloneCopyEvent( elem, clone ); + } + } + + // Preserve script evaluation history + destElements = getAll( clone, "script" ); + if ( destElements.length > 0 ) { + setGlobalEval( destElements, !inPage && getAll( elem, "script" ) ); + } + + // Return the cloned set + return clone; + }, + + cleanData: function( elems ) { + var data, elem, type, + special = jQuery.event.special, + i = 0; + + for ( ; ( elem = elems[ i ] ) !== undefined; i++ ) { + if ( acceptData( elem ) ) { + if ( ( data = elem[ dataPriv.expando ] ) ) { + if ( data.events ) { + for ( type in data.events ) { + if ( special[ type ] ) { + jQuery.event.remove( elem, type ); + + // This is a shortcut to avoid jQuery.event.remove's overhead + } else { + jQuery.removeEvent( elem, type, data.handle ); + } + } + } + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataPriv.expando ] = undefined; + } + if ( elem[ dataUser.expando ] ) { + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataUser.expando ] = undefined; + } + } + } + } +} ); + +jQuery.fn.extend( { + detach: function( selector ) { + return remove( this, selector, true ); + }, + + remove: function( selector ) { + return remove( this, selector ); + }, + + text: function( value ) { + return access( this, function( value ) { + return value === undefined ? + jQuery.text( this ) : + this.empty().each( function() { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + this.textContent = value; + } + } ); + }, null, value, arguments.length ); + }, + + append: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.appendChild( elem ); + } + } ); + }, + + prepend: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.insertBefore( elem, target.firstChild ); + } + } ); + }, + + before: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this ); + } + } ); + }, + + after: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this.nextSibling ); + } + } ); + }, + + empty: function() { + var elem, + i = 0; + + for ( ; ( elem = this[ i ] ) != null; i++ ) { + if ( elem.nodeType === 1 ) { + + // Prevent memory leaks + jQuery.cleanData( getAll( elem, false ) ); + + // Remove any remaining nodes + elem.textContent = ""; + } + } + + return this; + }, + + clone: function( dataAndEvents, deepDataAndEvents ) { + dataAndEvents = dataAndEvents == null ? false : dataAndEvents; + deepDataAndEvents = deepDataAndEvents == null ? dataAndEvents : deepDataAndEvents; + + return this.map( function() { + return jQuery.clone( this, dataAndEvents, deepDataAndEvents ); + } ); + }, + + html: function( value ) { + return access( this, function( value ) { + var elem = this[ 0 ] || {}, + i = 0, + l = this.length; + + if ( value === undefined && elem.nodeType === 1 ) { + return elem.innerHTML; + } + + // See if we can take a shortcut and just use innerHTML + if ( typeof value === "string" && !rnoInnerhtml.test( value ) && + !wrapMap[ ( rtagName.exec( value ) || [ "", "" ] )[ 1 ].toLowerCase() ] ) { + + value = jQuery.htmlPrefilter( value ); + + try { + for ( ; i < l; i++ ) { + elem = this[ i ] || {}; + + // Remove element nodes and prevent memory leaks + if ( elem.nodeType === 1 ) { + jQuery.cleanData( getAll( elem, false ) ); + elem.innerHTML = value; + } + } + + elem = 0; + + // If using innerHTML throws an exception, use the fallback method + } catch ( e ) {} + } + + if ( elem ) { + this.empty().append( value ); + } + }, null, value, arguments.length ); + }, + + replaceWith: function() { + var ignored = []; + + // Make the changes, replacing each non-ignored context element with the new content + return domManip( this, arguments, function( elem ) { + var parent = this.parentNode; + + if ( jQuery.inArray( this, ignored ) < 0 ) { + jQuery.cleanData( getAll( this ) ); + if ( parent ) { + parent.replaceChild( elem, this ); + } + } + + // Force callback invocation + }, ignored ); + } +} ); + +jQuery.each( { + appendTo: "append", + prependTo: "prepend", + insertBefore: "before", + insertAfter: "after", + replaceAll: "replaceWith" +}, function( name, original ) { + jQuery.fn[ name ] = function( selector ) { + var elems, + ret = [], + insert = jQuery( selector ), + last = insert.length - 1, + i = 0; + + for ( ; i <= last; i++ ) { + elems = i === last ? this : this.clone( true ); + jQuery( insert[ i ] )[ original ]( elems ); + + // Support: Android <=4.0 only, PhantomJS 1 only + // .get() because push.apply(_, arraylike) throws on ancient WebKit + push.apply( ret, elems.get() ); + } + + return this.pushStack( ret ); + }; +} ); +var rnumnonpx = new RegExp( "^(" + pnum + ")(?!px)[a-z%]+$", "i" ); + +var getStyles = function( elem ) { + + // Support: IE <=11 only, Firefox <=30 (#15098, #14150) + // IE throws on elements created in popups + // FF meanwhile throws on frame elements through "defaultView.getComputedStyle" + var view = elem.ownerDocument.defaultView; + + if ( !view || !view.opener ) { + view = window; + } + + return view.getComputedStyle( elem ); + }; + +var swap = function( elem, options, callback ) { + var ret, name, + old = {}; + + // Remember the old values, and insert the new ones + for ( name in options ) { + old[ name ] = elem.style[ name ]; + elem.style[ name ] = options[ name ]; + } + + ret = callback.call( elem ); + + // Revert the old values + for ( name in options ) { + elem.style[ name ] = old[ name ]; + } + + return ret; +}; + + +var rboxStyle = new RegExp( cssExpand.join( "|" ), "i" ); + + + +( function() { + + // Executing both pixelPosition & boxSizingReliable tests require only one layout + // so they're executed at the same time to save the second computation. + function computeStyleTests() { + + // This is a singleton, we need to execute it only once + if ( !div ) { + return; + } + + container.style.cssText = "position:absolute;left:-11111px;width:60px;" + + "margin-top:1px;padding:0;border:0"; + div.style.cssText = + "position:relative;display:block;box-sizing:border-box;overflow:scroll;" + + "margin:auto;border:1px;padding:1px;" + + "width:60%;top:1%"; + documentElement.appendChild( container ).appendChild( div ); + + var divStyle = window.getComputedStyle( div ); + pixelPositionVal = divStyle.top !== "1%"; + + // Support: Android 4.0 - 4.3 only, Firefox <=3 - 44 + reliableMarginLeftVal = roundPixelMeasures( divStyle.marginLeft ) === 12; + + // Support: Android 4.0 - 4.3 only, Safari <=9.1 - 10.1, iOS <=7.0 - 9.3 + // Some styles come back with percentage values, even though they shouldn't + div.style.right = "60%"; + pixelBoxStylesVal = roundPixelMeasures( divStyle.right ) === 36; + + // Support: IE 9 - 11 only + // Detect misreporting of content dimensions for box-sizing:border-box elements + boxSizingReliableVal = roundPixelMeasures( divStyle.width ) === 36; + + // Support: IE 9 only + // Detect overflow:scroll screwiness (gh-3699) + // Support: Chrome <=64 + // Don't get tricked when zoom affects offsetWidth (gh-4029) + div.style.position = "absolute"; + scrollboxSizeVal = roundPixelMeasures( div.offsetWidth / 3 ) === 12; + + documentElement.removeChild( container ); + + // Nullify the div so it wouldn't be stored in the memory and + // it will also be a sign that checks already performed + div = null; + } + + function roundPixelMeasures( measure ) { + return Math.round( parseFloat( measure ) ); + } + + var pixelPositionVal, boxSizingReliableVal, scrollboxSizeVal, pixelBoxStylesVal, + reliableTrDimensionsVal, reliableMarginLeftVal, + container = document.createElement( "div" ), + div = document.createElement( "div" ); + + // Finish early in limited (non-browser) environments + if ( !div.style ) { + return; + } + + // Support: IE <=9 - 11 only + // Style of cloned element affects source element cloned (#8908) + div.style.backgroundClip = "content-box"; + div.cloneNode( true ).style.backgroundClip = ""; + support.clearCloneStyle = div.style.backgroundClip === "content-box"; + + jQuery.extend( support, { + boxSizingReliable: function() { + computeStyleTests(); + return boxSizingReliableVal; + }, + pixelBoxStyles: function() { + computeStyleTests(); + return pixelBoxStylesVal; + }, + pixelPosition: function() { + computeStyleTests(); + return pixelPositionVal; + }, + reliableMarginLeft: function() { + computeStyleTests(); + return reliableMarginLeftVal; + }, + scrollboxSize: function() { + computeStyleTests(); + return scrollboxSizeVal; + }, + + // Support: IE 9 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Behavior in IE 9 is more subtle than in newer versions & it passes + // some versions of this test; make sure not to make it pass there! + reliableTrDimensions: function() { + var table, tr, trChild, trStyle; + if ( reliableTrDimensionsVal == null ) { + table = document.createElement( "table" ); + tr = document.createElement( "tr" ); + trChild = document.createElement( "div" ); + + table.style.cssText = "position:absolute;left:-11111px"; + tr.style.height = "1px"; + trChild.style.height = "9px"; + + documentElement + .appendChild( table ) + .appendChild( tr ) + .appendChild( trChild ); + + trStyle = window.getComputedStyle( tr ); + reliableTrDimensionsVal = parseInt( trStyle.height ) > 3; + + documentElement.removeChild( table ); + } + return reliableTrDimensionsVal; + } + } ); +} )(); + + +function curCSS( elem, name, computed ) { + var width, minWidth, maxWidth, ret, + + // Support: Firefox 51+ + // Retrieving style before computed somehow + // fixes an issue with getting wrong values + // on detached elements + style = elem.style; + + computed = computed || getStyles( elem ); + + // getPropertyValue is needed for: + // .css('filter') (IE 9 only, #12537) + // .css('--customProperty) (#3144) + if ( computed ) { + ret = computed.getPropertyValue( name ) || computed[ name ]; + + if ( ret === "" && !isAttached( elem ) ) { + ret = jQuery.style( elem, name ); + } + + // A tribute to the "awesome hack by Dean Edwards" + // Android Browser returns percentage for some values, + // but width seems to be reliably pixels. + // This is against the CSSOM draft spec: + // https://drafts.csswg.org/cssom/#resolved-values + if ( !support.pixelBoxStyles() && rnumnonpx.test( ret ) && rboxStyle.test( name ) ) { + + // Remember the original values + width = style.width; + minWidth = style.minWidth; + maxWidth = style.maxWidth; + + // Put in the new values to get a computed value out + style.minWidth = style.maxWidth = style.width = ret; + ret = computed.width; + + // Revert the changed values + style.width = width; + style.minWidth = minWidth; + style.maxWidth = maxWidth; + } + } + + return ret !== undefined ? + + // Support: IE <=9 - 11 only + // IE returns zIndex value as an integer. + ret + "" : + ret; +} + + +function addGetHookIf( conditionFn, hookFn ) { + + // Define the hook, we'll check on the first run if it's really needed. + return { + get: function() { + if ( conditionFn() ) { + + // Hook not needed (or it's not possible to use it due + // to missing dependency), remove it. + delete this.get; + return; + } + + // Hook needed; redefine it so that the support test is not executed again. + return ( this.get = hookFn ).apply( this, arguments ); + } + }; +} + + +var cssPrefixes = [ "Webkit", "Moz", "ms" ], + emptyStyle = document.createElement( "div" ).style, + vendorProps = {}; + +// Return a vendor-prefixed property or undefined +function vendorPropName( name ) { + + // Check for vendor prefixed names + var capName = name[ 0 ].toUpperCase() + name.slice( 1 ), + i = cssPrefixes.length; + + while ( i-- ) { + name = cssPrefixes[ i ] + capName; + if ( name in emptyStyle ) { + return name; + } + } +} + +// Return a potentially-mapped jQuery.cssProps or vendor prefixed property +function finalPropName( name ) { + var final = jQuery.cssProps[ name ] || vendorProps[ name ]; + + if ( final ) { + return final; + } + if ( name in emptyStyle ) { + return name; + } + return vendorProps[ name ] = vendorPropName( name ) || name; +} + + +var + + // Swappable if display is none or starts with table + // except "table", "table-cell", or "table-caption" + // See here for display values: https://developer.mozilla.org/en-US/docs/CSS/display + rdisplayswap = /^(none|table(?!-c[ea]).+)/, + rcustomProp = /^--/, + cssShow = { position: "absolute", visibility: "hidden", display: "block" }, + cssNormalTransform = { + letterSpacing: "0", + fontWeight: "400" + }; + +function setPositiveNumber( _elem, value, subtract ) { + + // Any relative (+/-) values have already been + // normalized at this point + var matches = rcssNum.exec( value ); + return matches ? + + // Guard against undefined "subtract", e.g., when used as in cssHooks + Math.max( 0, matches[ 2 ] - ( subtract || 0 ) ) + ( matches[ 3 ] || "px" ) : + value; +} + +function boxModelAdjustment( elem, dimension, box, isBorderBox, styles, computedVal ) { + var i = dimension === "width" ? 1 : 0, + extra = 0, + delta = 0; + + // Adjustment may not be necessary + if ( box === ( isBorderBox ? "border" : "content" ) ) { + return 0; + } + + for ( ; i < 4; i += 2 ) { + + // Both box models exclude margin + if ( box === "margin" ) { + delta += jQuery.css( elem, box + cssExpand[ i ], true, styles ); + } + + // If we get here with a content-box, we're seeking "padding" or "border" or "margin" + if ( !isBorderBox ) { + + // Add padding + delta += jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + + // For "border" or "margin", add border + if ( box !== "padding" ) { + delta += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + + // But still keep track of it otherwise + } else { + extra += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + + // If we get here with a border-box (content + padding + border), we're seeking "content" or + // "padding" or "margin" + } else { + + // For "content", subtract padding + if ( box === "content" ) { + delta -= jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + } + + // For "content" or "padding", subtract border + if ( box !== "margin" ) { + delta -= jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + } + } + + // Account for positive content-box scroll gutter when requested by providing computedVal + if ( !isBorderBox && computedVal >= 0 ) { + + // offsetWidth/offsetHeight is a rounded sum of content, padding, scroll gutter, and border + // Assuming integer scroll gutter, subtract the rest and round down + delta += Math.max( 0, Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + computedVal - + delta - + extra - + 0.5 + + // If offsetWidth/offsetHeight is unknown, then we can't determine content-box scroll gutter + // Use an explicit zero to avoid NaN (gh-3964) + ) ) || 0; + } + + return delta; +} + +function getWidthOrHeight( elem, dimension, extra ) { + + // Start with computed style + var styles = getStyles( elem ), + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-4322). + // Fake content-box until we know it's needed to know the true value. + boxSizingNeeded = !support.boxSizingReliable() || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + valueIsBorderBox = isBorderBox, + + val = curCSS( elem, dimension, styles ), + offsetProp = "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ); + + // Support: Firefox <=54 + // Return a confounding non-pixel value or feign ignorance, as appropriate. + if ( rnumnonpx.test( val ) ) { + if ( !extra ) { + return val; + } + val = "auto"; + } + + + // Support: IE 9 - 11 only + // Use offsetWidth/offsetHeight for when box sizing is unreliable. + // In those cases, the computed value can be trusted to be border-box. + if ( ( !support.boxSizingReliable() && isBorderBox || + + // Support: IE 10 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Interestingly, in some cases IE 9 doesn't suffer from this issue. + !support.reliableTrDimensions() && nodeName( elem, "tr" ) || + + // Fall back to offsetWidth/offsetHeight when value is "auto" + // This happens for inline elements with no explicit setting (gh-3571) + val === "auto" || + + // Support: Android <=4.1 - 4.3 only + // Also use offsetWidth/offsetHeight for misreported inline dimensions (gh-3602) + !parseFloat( val ) && jQuery.css( elem, "display", false, styles ) === "inline" ) && + + // Make sure the element is visible & connected + elem.getClientRects().length ) { + + isBorderBox = jQuery.css( elem, "boxSizing", false, styles ) === "border-box"; + + // Where available, offsetWidth/offsetHeight approximate border box dimensions. + // Where not available (e.g., SVG), assume unreliable box-sizing and interpret the + // retrieved value as a content box dimension. + valueIsBorderBox = offsetProp in elem; + if ( valueIsBorderBox ) { + val = elem[ offsetProp ]; + } + } + + // Normalize "" and auto + val = parseFloat( val ) || 0; + + // Adjust for the element's box model + return ( val + + boxModelAdjustment( + elem, + dimension, + extra || ( isBorderBox ? "border" : "content" ), + valueIsBorderBox, + styles, + + // Provide the current computed size to request scroll gutter calculation (gh-3589) + val + ) + ) + "px"; +} + +jQuery.extend( { + + // Add in style property hooks for overriding the default + // behavior of getting and setting a style property + cssHooks: { + opacity: { + get: function( elem, computed ) { + if ( computed ) { + + // We should always get a number back from opacity + var ret = curCSS( elem, "opacity" ); + return ret === "" ? "1" : ret; + } + } + } + }, + + // Don't automatically add "px" to these possibly-unitless properties + cssNumber: { + "animationIterationCount": true, + "columnCount": true, + "fillOpacity": true, + "flexGrow": true, + "flexShrink": true, + "fontWeight": true, + "gridArea": true, + "gridColumn": true, + "gridColumnEnd": true, + "gridColumnStart": true, + "gridRow": true, + "gridRowEnd": true, + "gridRowStart": true, + "lineHeight": true, + "opacity": true, + "order": true, + "orphans": true, + "widows": true, + "zIndex": true, + "zoom": true + }, + + // Add in properties whose names you wish to fix before + // setting or getting the value + cssProps: {}, + + // Get and set the style property on a DOM Node + style: function( elem, name, value, extra ) { + + // Don't set styles on text and comment nodes + if ( !elem || elem.nodeType === 3 || elem.nodeType === 8 || !elem.style ) { + return; + } + + // Make sure that we're working with the right name + var ret, type, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ), + style = elem.style; + + // Make sure that we're working with the right name. We don't + // want to query the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Gets hook for the prefixed version, then unprefixed version + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // Check if we're setting a value + if ( value !== undefined ) { + type = typeof value; + + // Convert "+=" or "-=" to relative numbers (#7345) + if ( type === "string" && ( ret = rcssNum.exec( value ) ) && ret[ 1 ] ) { + value = adjustCSS( elem, name, ret ); + + // Fixes bug #9237 + type = "number"; + } + + // Make sure that null and NaN values aren't set (#7116) + if ( value == null || value !== value ) { + return; + } + + // If a number was passed in, add the unit (except for certain CSS properties) + // The isCustomProp check can be removed in jQuery 4.0 when we only auto-append + // "px" to a few hardcoded values. + if ( type === "number" && !isCustomProp ) { + value += ret && ret[ 3 ] || ( jQuery.cssNumber[ origName ] ? "" : "px" ); + } + + // background-* props affect original clone's values + if ( !support.clearCloneStyle && value === "" && name.indexOf( "background" ) === 0 ) { + style[ name ] = "inherit"; + } + + // If a hook was provided, use that value, otherwise just set the specified value + if ( !hooks || !( "set" in hooks ) || + ( value = hooks.set( elem, value, extra ) ) !== undefined ) { + + if ( isCustomProp ) { + style.setProperty( name, value ); + } else { + style[ name ] = value; + } + } + + } else { + + // If a hook was provided get the non-computed value from there + if ( hooks && "get" in hooks && + ( ret = hooks.get( elem, false, extra ) ) !== undefined ) { + + return ret; + } + + // Otherwise just get the value from the style object + return style[ name ]; + } + }, + + css: function( elem, name, extra, styles ) { + var val, num, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ); + + // Make sure that we're working with the right name. We don't + // want to modify the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Try prefixed name followed by the unprefixed name + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // If a hook was provided get the computed value from there + if ( hooks && "get" in hooks ) { + val = hooks.get( elem, true, extra ); + } + + // Otherwise, if a way to get the computed value exists, use that + if ( val === undefined ) { + val = curCSS( elem, name, styles ); + } + + // Convert "normal" to computed value + if ( val === "normal" && name in cssNormalTransform ) { + val = cssNormalTransform[ name ]; + } + + // Make numeric if forced or a qualifier was provided and val looks numeric + if ( extra === "" || extra ) { + num = parseFloat( val ); + return extra === true || isFinite( num ) ? num || 0 : val; + } + + return val; + } +} ); + +jQuery.each( [ "height", "width" ], function( _i, dimension ) { + jQuery.cssHooks[ dimension ] = { + get: function( elem, computed, extra ) { + if ( computed ) { + + // Certain elements can have dimension info if we invisibly show them + // but it must have a current display style that would benefit + return rdisplayswap.test( jQuery.css( elem, "display" ) ) && + + // Support: Safari 8+ + // Table columns in Safari have non-zero offsetWidth & zero + // getBoundingClientRect().width unless display is changed. + // Support: IE <=11 only + // Running getBoundingClientRect on a disconnected node + // in IE throws an error. + ( !elem.getClientRects().length || !elem.getBoundingClientRect().width ) ? + swap( elem, cssShow, function() { + return getWidthOrHeight( elem, dimension, extra ); + } ) : + getWidthOrHeight( elem, dimension, extra ); + } + }, + + set: function( elem, value, extra ) { + var matches, + styles = getStyles( elem ), + + // Only read styles.position if the test has a chance to fail + // to avoid forcing a reflow. + scrollboxSizeBuggy = !support.scrollboxSize() && + styles.position === "absolute", + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-3991) + boxSizingNeeded = scrollboxSizeBuggy || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + subtract = extra ? + boxModelAdjustment( + elem, + dimension, + extra, + isBorderBox, + styles + ) : + 0; + + // Account for unreliable border-box dimensions by comparing offset* to computed and + // faking a content-box to get border and padding (gh-3699) + if ( isBorderBox && scrollboxSizeBuggy ) { + subtract -= Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + parseFloat( styles[ dimension ] ) - + boxModelAdjustment( elem, dimension, "border", false, styles ) - + 0.5 + ); + } + + // Convert to pixels if value adjustment is needed + if ( subtract && ( matches = rcssNum.exec( value ) ) && + ( matches[ 3 ] || "px" ) !== "px" ) { + + elem.style[ dimension ] = value; + value = jQuery.css( elem, dimension ); + } + + return setPositiveNumber( elem, value, subtract ); + } + }; +} ); + +jQuery.cssHooks.marginLeft = addGetHookIf( support.reliableMarginLeft, + function( elem, computed ) { + if ( computed ) { + return ( parseFloat( curCSS( elem, "marginLeft" ) ) || + elem.getBoundingClientRect().left - + swap( elem, { marginLeft: 0 }, function() { + return elem.getBoundingClientRect().left; + } ) + ) + "px"; + } + } +); + +// These hooks are used by animate to expand properties +jQuery.each( { + margin: "", + padding: "", + border: "Width" +}, function( prefix, suffix ) { + jQuery.cssHooks[ prefix + suffix ] = { + expand: function( value ) { + var i = 0, + expanded = {}, + + // Assumes a single number if not a string + parts = typeof value === "string" ? value.split( " " ) : [ value ]; + + for ( ; i < 4; i++ ) { + expanded[ prefix + cssExpand[ i ] + suffix ] = + parts[ i ] || parts[ i - 2 ] || parts[ 0 ]; + } + + return expanded; + } + }; + + if ( prefix !== "margin" ) { + jQuery.cssHooks[ prefix + suffix ].set = setPositiveNumber; + } +} ); + +jQuery.fn.extend( { + css: function( name, value ) { + return access( this, function( elem, name, value ) { + var styles, len, + map = {}, + i = 0; + + if ( Array.isArray( name ) ) { + styles = getStyles( elem ); + len = name.length; + + for ( ; i < len; i++ ) { + map[ name[ i ] ] = jQuery.css( elem, name[ i ], false, styles ); + } + + return map; + } + + return value !== undefined ? + jQuery.style( elem, name, value ) : + jQuery.css( elem, name ); + }, name, value, arguments.length > 1 ); + } +} ); + + +function Tween( elem, options, prop, end, easing ) { + return new Tween.prototype.init( elem, options, prop, end, easing ); +} +jQuery.Tween = Tween; + +Tween.prototype = { + constructor: Tween, + init: function( elem, options, prop, end, easing, unit ) { + this.elem = elem; + this.prop = prop; + this.easing = easing || jQuery.easing._default; + this.options = options; + this.start = this.now = this.cur(); + this.end = end; + this.unit = unit || ( jQuery.cssNumber[ prop ] ? "" : "px" ); + }, + cur: function() { + var hooks = Tween.propHooks[ this.prop ]; + + return hooks && hooks.get ? + hooks.get( this ) : + Tween.propHooks._default.get( this ); + }, + run: function( percent ) { + var eased, + hooks = Tween.propHooks[ this.prop ]; + + if ( this.options.duration ) { + this.pos = eased = jQuery.easing[ this.easing ]( + percent, this.options.duration * percent, 0, 1, this.options.duration + ); + } else { + this.pos = eased = percent; + } + this.now = ( this.end - this.start ) * eased + this.start; + + if ( this.options.step ) { + this.options.step.call( this.elem, this.now, this ); + } + + if ( hooks && hooks.set ) { + hooks.set( this ); + } else { + Tween.propHooks._default.set( this ); + } + return this; + } +}; + +Tween.prototype.init.prototype = Tween.prototype; + +Tween.propHooks = { + _default: { + get: function( tween ) { + var result; + + // Use a property on the element directly when it is not a DOM element, + // or when there is no matching style property that exists. + if ( tween.elem.nodeType !== 1 || + tween.elem[ tween.prop ] != null && tween.elem.style[ tween.prop ] == null ) { + return tween.elem[ tween.prop ]; + } + + // Passing an empty string as a 3rd parameter to .css will automatically + // attempt a parseFloat and fallback to a string if the parse fails. + // Simple values such as "10px" are parsed to Float; + // complex values such as "rotate(1rad)" are returned as-is. + result = jQuery.css( tween.elem, tween.prop, "" ); + + // Empty strings, null, undefined and "auto" are converted to 0. + return !result || result === "auto" ? 0 : result; + }, + set: function( tween ) { + + // Use step hook for back compat. + // Use cssHook if its there. + // Use .style if available and use plain properties where available. + if ( jQuery.fx.step[ tween.prop ] ) { + jQuery.fx.step[ tween.prop ]( tween ); + } else if ( tween.elem.nodeType === 1 && ( + jQuery.cssHooks[ tween.prop ] || + tween.elem.style[ finalPropName( tween.prop ) ] != null ) ) { + jQuery.style( tween.elem, tween.prop, tween.now + tween.unit ); + } else { + tween.elem[ tween.prop ] = tween.now; + } + } + } +}; + +// Support: IE <=9 only +// Panic based approach to setting things on disconnected nodes +Tween.propHooks.scrollTop = Tween.propHooks.scrollLeft = { + set: function( tween ) { + if ( tween.elem.nodeType && tween.elem.parentNode ) { + tween.elem[ tween.prop ] = tween.now; + } + } +}; + +jQuery.easing = { + linear: function( p ) { + return p; + }, + swing: function( p ) { + return 0.5 - Math.cos( p * Math.PI ) / 2; + }, + _default: "swing" +}; + +jQuery.fx = Tween.prototype.init; + +// Back compat <1.8 extension point +jQuery.fx.step = {}; + + + + +var + fxNow, inProgress, + rfxtypes = /^(?:toggle|show|hide)$/, + rrun = /queueHooks$/; + +function schedule() { + if ( inProgress ) { + if ( document.hidden === false && window.requestAnimationFrame ) { + window.requestAnimationFrame( schedule ); + } else { + window.setTimeout( schedule, jQuery.fx.interval ); + } + + jQuery.fx.tick(); + } +} + +// Animations created synchronously will run synchronously +function createFxNow() { + window.setTimeout( function() { + fxNow = undefined; + } ); + return ( fxNow = Date.now() ); +} + +// Generate parameters to create a standard animation +function genFx( type, includeWidth ) { + var which, + i = 0, + attrs = { height: type }; + + // If we include width, step value is 1 to do all cssExpand values, + // otherwise step value is 2 to skip over Left and Right + includeWidth = includeWidth ? 1 : 0; + for ( ; i < 4; i += 2 - includeWidth ) { + which = cssExpand[ i ]; + attrs[ "margin" + which ] = attrs[ "padding" + which ] = type; + } + + if ( includeWidth ) { + attrs.opacity = attrs.width = type; + } + + return attrs; +} + +function createTween( value, prop, animation ) { + var tween, + collection = ( Animation.tweeners[ prop ] || [] ).concat( Animation.tweeners[ "*" ] ), + index = 0, + length = collection.length; + for ( ; index < length; index++ ) { + if ( ( tween = collection[ index ].call( animation, prop, value ) ) ) { + + // We're done with this property + return tween; + } + } +} + +function defaultPrefilter( elem, props, opts ) { + var prop, value, toggle, hooks, oldfire, propTween, restoreDisplay, display, + isBox = "width" in props || "height" in props, + anim = this, + orig = {}, + style = elem.style, + hidden = elem.nodeType && isHiddenWithinTree( elem ), + dataShow = dataPriv.get( elem, "fxshow" ); + + // Queue-skipping animations hijack the fx hooks + if ( !opts.queue ) { + hooks = jQuery._queueHooks( elem, "fx" ); + if ( hooks.unqueued == null ) { + hooks.unqueued = 0; + oldfire = hooks.empty.fire; + hooks.empty.fire = function() { + if ( !hooks.unqueued ) { + oldfire(); + } + }; + } + hooks.unqueued++; + + anim.always( function() { + + // Ensure the complete handler is called before this completes + anim.always( function() { + hooks.unqueued--; + if ( !jQuery.queue( elem, "fx" ).length ) { + hooks.empty.fire(); + } + } ); + } ); + } + + // Detect show/hide animations + for ( prop in props ) { + value = props[ prop ]; + if ( rfxtypes.test( value ) ) { + delete props[ prop ]; + toggle = toggle || value === "toggle"; + if ( value === ( hidden ? "hide" : "show" ) ) { + + // Pretend to be hidden if this is a "show" and + // there is still data from a stopped show/hide + if ( value === "show" && dataShow && dataShow[ prop ] !== undefined ) { + hidden = true; + + // Ignore all other no-op show/hide data + } else { + continue; + } + } + orig[ prop ] = dataShow && dataShow[ prop ] || jQuery.style( elem, prop ); + } + } + + // Bail out if this is a no-op like .hide().hide() + propTween = !jQuery.isEmptyObject( props ); + if ( !propTween && jQuery.isEmptyObject( orig ) ) { + return; + } + + // Restrict "overflow" and "display" styles during box animations + if ( isBox && elem.nodeType === 1 ) { + + // Support: IE <=9 - 11, Edge 12 - 15 + // Record all 3 overflow attributes because IE does not infer the shorthand + // from identically-valued overflowX and overflowY and Edge just mirrors + // the overflowX value there. + opts.overflow = [ style.overflow, style.overflowX, style.overflowY ]; + + // Identify a display type, preferring old show/hide data over the CSS cascade + restoreDisplay = dataShow && dataShow.display; + if ( restoreDisplay == null ) { + restoreDisplay = dataPriv.get( elem, "display" ); + } + display = jQuery.css( elem, "display" ); + if ( display === "none" ) { + if ( restoreDisplay ) { + display = restoreDisplay; + } else { + + // Get nonempty value(s) by temporarily forcing visibility + showHide( [ elem ], true ); + restoreDisplay = elem.style.display || restoreDisplay; + display = jQuery.css( elem, "display" ); + showHide( [ elem ] ); + } + } + + // Animate inline elements as inline-block + if ( display === "inline" || display === "inline-block" && restoreDisplay != null ) { + if ( jQuery.css( elem, "float" ) === "none" ) { + + // Restore the original display value at the end of pure show/hide animations + if ( !propTween ) { + anim.done( function() { + style.display = restoreDisplay; + } ); + if ( restoreDisplay == null ) { + display = style.display; + restoreDisplay = display === "none" ? "" : display; + } + } + style.display = "inline-block"; + } + } + } + + if ( opts.overflow ) { + style.overflow = "hidden"; + anim.always( function() { + style.overflow = opts.overflow[ 0 ]; + style.overflowX = opts.overflow[ 1 ]; + style.overflowY = opts.overflow[ 2 ]; + } ); + } + + // Implement show/hide animations + propTween = false; + for ( prop in orig ) { + + // General show/hide setup for this element animation + if ( !propTween ) { + if ( dataShow ) { + if ( "hidden" in dataShow ) { + hidden = dataShow.hidden; + } + } else { + dataShow = dataPriv.access( elem, "fxshow", { display: restoreDisplay } ); + } + + // Store hidden/visible for toggle so `.stop().toggle()` "reverses" + if ( toggle ) { + dataShow.hidden = !hidden; + } + + // Show elements before animating them + if ( hidden ) { + showHide( [ elem ], true ); + } + + /* eslint-disable no-loop-func */ + + anim.done( function() { + + /* eslint-enable no-loop-func */ + + // The final step of a "hide" animation is actually hiding the element + if ( !hidden ) { + showHide( [ elem ] ); + } + dataPriv.remove( elem, "fxshow" ); + for ( prop in orig ) { + jQuery.style( elem, prop, orig[ prop ] ); + } + } ); + } + + // Per-property setup + propTween = createTween( hidden ? dataShow[ prop ] : 0, prop, anim ); + if ( !( prop in dataShow ) ) { + dataShow[ prop ] = propTween.start; + if ( hidden ) { + propTween.end = propTween.start; + propTween.start = 0; + } + } + } +} + +function propFilter( props, specialEasing ) { + var index, name, easing, value, hooks; + + // camelCase, specialEasing and expand cssHook pass + for ( index in props ) { + name = camelCase( index ); + easing = specialEasing[ name ]; + value = props[ index ]; + if ( Array.isArray( value ) ) { + easing = value[ 1 ]; + value = props[ index ] = value[ 0 ]; + } + + if ( index !== name ) { + props[ name ] = value; + delete props[ index ]; + } + + hooks = jQuery.cssHooks[ name ]; + if ( hooks && "expand" in hooks ) { + value = hooks.expand( value ); + delete props[ name ]; + + // Not quite $.extend, this won't overwrite existing keys. + // Reusing 'index' because we have the correct "name" + for ( index in value ) { + if ( !( index in props ) ) { + props[ index ] = value[ index ]; + specialEasing[ index ] = easing; + } + } + } else { + specialEasing[ name ] = easing; + } + } +} + +function Animation( elem, properties, options ) { + var result, + stopped, + index = 0, + length = Animation.prefilters.length, + deferred = jQuery.Deferred().always( function() { + + // Don't match elem in the :animated selector + delete tick.elem; + } ), + tick = function() { + if ( stopped ) { + return false; + } + var currentTime = fxNow || createFxNow(), + remaining = Math.max( 0, animation.startTime + animation.duration - currentTime ), + + // Support: Android 2.3 only + // Archaic crash bug won't allow us to use `1 - ( 0.5 || 0 )` (#12497) + temp = remaining / animation.duration || 0, + percent = 1 - temp, + index = 0, + length = animation.tweens.length; + + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( percent ); + } + + deferred.notifyWith( elem, [ animation, percent, remaining ] ); + + // If there's more to do, yield + if ( percent < 1 && length ) { + return remaining; + } + + // If this was an empty animation, synthesize a final progress notification + if ( !length ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + } + + // Resolve the animation and report its conclusion + deferred.resolveWith( elem, [ animation ] ); + return false; + }, + animation = deferred.promise( { + elem: elem, + props: jQuery.extend( {}, properties ), + opts: jQuery.extend( true, { + specialEasing: {}, + easing: jQuery.easing._default + }, options ), + originalProperties: properties, + originalOptions: options, + startTime: fxNow || createFxNow(), + duration: options.duration, + tweens: [], + createTween: function( prop, end ) { + var tween = jQuery.Tween( elem, animation.opts, prop, end, + animation.opts.specialEasing[ prop ] || animation.opts.easing ); + animation.tweens.push( tween ); + return tween; + }, + stop: function( gotoEnd ) { + var index = 0, + + // If we are going to the end, we want to run all the tweens + // otherwise we skip this part + length = gotoEnd ? animation.tweens.length : 0; + if ( stopped ) { + return this; + } + stopped = true; + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( 1 ); + } + + // Resolve when we played the last frame; otherwise, reject + if ( gotoEnd ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + deferred.resolveWith( elem, [ animation, gotoEnd ] ); + } else { + deferred.rejectWith( elem, [ animation, gotoEnd ] ); + } + return this; + } + } ), + props = animation.props; + + propFilter( props, animation.opts.specialEasing ); + + for ( ; index < length; index++ ) { + result = Animation.prefilters[ index ].call( animation, elem, props, animation.opts ); + if ( result ) { + if ( isFunction( result.stop ) ) { + jQuery._queueHooks( animation.elem, animation.opts.queue ).stop = + result.stop.bind( result ); + } + return result; + } + } + + jQuery.map( props, createTween, animation ); + + if ( isFunction( animation.opts.start ) ) { + animation.opts.start.call( elem, animation ); + } + + // Attach callbacks from options + animation + .progress( animation.opts.progress ) + .done( animation.opts.done, animation.opts.complete ) + .fail( animation.opts.fail ) + .always( animation.opts.always ); + + jQuery.fx.timer( + jQuery.extend( tick, { + elem: elem, + anim: animation, + queue: animation.opts.queue + } ) + ); + + return animation; +} + +jQuery.Animation = jQuery.extend( Animation, { + + tweeners: { + "*": [ function( prop, value ) { + var tween = this.createTween( prop, value ); + adjustCSS( tween.elem, prop, rcssNum.exec( value ), tween ); + return tween; + } ] + }, + + tweener: function( props, callback ) { + if ( isFunction( props ) ) { + callback = props; + props = [ "*" ]; + } else { + props = props.match( rnothtmlwhite ); + } + + var prop, + index = 0, + length = props.length; + + for ( ; index < length; index++ ) { + prop = props[ index ]; + Animation.tweeners[ prop ] = Animation.tweeners[ prop ] || []; + Animation.tweeners[ prop ].unshift( callback ); + } + }, + + prefilters: [ defaultPrefilter ], + + prefilter: function( callback, prepend ) { + if ( prepend ) { + Animation.prefilters.unshift( callback ); + } else { + Animation.prefilters.push( callback ); + } + } +} ); + +jQuery.speed = function( speed, easing, fn ) { + var opt = speed && typeof speed === "object" ? jQuery.extend( {}, speed ) : { + complete: fn || !fn && easing || + isFunction( speed ) && speed, + duration: speed, + easing: fn && easing || easing && !isFunction( easing ) && easing + }; + + // Go to the end state if fx are off + if ( jQuery.fx.off ) { + opt.duration = 0; + + } else { + if ( typeof opt.duration !== "number" ) { + if ( opt.duration in jQuery.fx.speeds ) { + opt.duration = jQuery.fx.speeds[ opt.duration ]; + + } else { + opt.duration = jQuery.fx.speeds._default; + } + } + } + + // Normalize opt.queue - true/undefined/null -> "fx" + if ( opt.queue == null || opt.queue === true ) { + opt.queue = "fx"; + } + + // Queueing + opt.old = opt.complete; + + opt.complete = function() { + if ( isFunction( opt.old ) ) { + opt.old.call( this ); + } + + if ( opt.queue ) { + jQuery.dequeue( this, opt.queue ); + } + }; + + return opt; +}; + +jQuery.fn.extend( { + fadeTo: function( speed, to, easing, callback ) { + + // Show any hidden elements after setting opacity to 0 + return this.filter( isHiddenWithinTree ).css( "opacity", 0 ).show() + + // Animate to the value specified + .end().animate( { opacity: to }, speed, easing, callback ); + }, + animate: function( prop, speed, easing, callback ) { + var empty = jQuery.isEmptyObject( prop ), + optall = jQuery.speed( speed, easing, callback ), + doAnimation = function() { + + // Operate on a copy of prop so per-property easing won't be lost + var anim = Animation( this, jQuery.extend( {}, prop ), optall ); + + // Empty animations, or finishing resolves immediately + if ( empty || dataPriv.get( this, "finish" ) ) { + anim.stop( true ); + } + }; + doAnimation.finish = doAnimation; + + return empty || optall.queue === false ? + this.each( doAnimation ) : + this.queue( optall.queue, doAnimation ); + }, + stop: function( type, clearQueue, gotoEnd ) { + var stopQueue = function( hooks ) { + var stop = hooks.stop; + delete hooks.stop; + stop( gotoEnd ); + }; + + if ( typeof type !== "string" ) { + gotoEnd = clearQueue; + clearQueue = type; + type = undefined; + } + if ( clearQueue ) { + this.queue( type || "fx", [] ); + } + + return this.each( function() { + var dequeue = true, + index = type != null && type + "queueHooks", + timers = jQuery.timers, + data = dataPriv.get( this ); + + if ( index ) { + if ( data[ index ] && data[ index ].stop ) { + stopQueue( data[ index ] ); + } + } else { + for ( index in data ) { + if ( data[ index ] && data[ index ].stop && rrun.test( index ) ) { + stopQueue( data[ index ] ); + } + } + } + + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && + ( type == null || timers[ index ].queue === type ) ) { + + timers[ index ].anim.stop( gotoEnd ); + dequeue = false; + timers.splice( index, 1 ); + } + } + + // Start the next in the queue if the last step wasn't forced. + // Timers currently will call their complete callbacks, which + // will dequeue but only if they were gotoEnd. + if ( dequeue || !gotoEnd ) { + jQuery.dequeue( this, type ); + } + } ); + }, + finish: function( type ) { + if ( type !== false ) { + type = type || "fx"; + } + return this.each( function() { + var index, + data = dataPriv.get( this ), + queue = data[ type + "queue" ], + hooks = data[ type + "queueHooks" ], + timers = jQuery.timers, + length = queue ? queue.length : 0; + + // Enable finishing flag on private data + data.finish = true; + + // Empty the queue first + jQuery.queue( this, type, [] ); + + if ( hooks && hooks.stop ) { + hooks.stop.call( this, true ); + } + + // Look for any active animations, and finish them + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && timers[ index ].queue === type ) { + timers[ index ].anim.stop( true ); + timers.splice( index, 1 ); + } + } + + // Look for any animations in the old queue and finish them + for ( index = 0; index < length; index++ ) { + if ( queue[ index ] && queue[ index ].finish ) { + queue[ index ].finish.call( this ); + } + } + + // Turn off finishing flag + delete data.finish; + } ); + } +} ); + +jQuery.each( [ "toggle", "show", "hide" ], function( _i, name ) { + var cssFn = jQuery.fn[ name ]; + jQuery.fn[ name ] = function( speed, easing, callback ) { + return speed == null || typeof speed === "boolean" ? + cssFn.apply( this, arguments ) : + this.animate( genFx( name, true ), speed, easing, callback ); + }; +} ); + +// Generate shortcuts for custom animations +jQuery.each( { + slideDown: genFx( "show" ), + slideUp: genFx( "hide" ), + slideToggle: genFx( "toggle" ), + fadeIn: { opacity: "show" }, + fadeOut: { opacity: "hide" }, + fadeToggle: { opacity: "toggle" } +}, function( name, props ) { + jQuery.fn[ name ] = function( speed, easing, callback ) { + return this.animate( props, speed, easing, callback ); + }; +} ); + +jQuery.timers = []; +jQuery.fx.tick = function() { + var timer, + i = 0, + timers = jQuery.timers; + + fxNow = Date.now(); + + for ( ; i < timers.length; i++ ) { + timer = timers[ i ]; + + // Run the timer and safely remove it when done (allowing for external removal) + if ( !timer() && timers[ i ] === timer ) { + timers.splice( i--, 1 ); + } + } + + if ( !timers.length ) { + jQuery.fx.stop(); + } + fxNow = undefined; +}; + +jQuery.fx.timer = function( timer ) { + jQuery.timers.push( timer ); + jQuery.fx.start(); +}; + +jQuery.fx.interval = 13; +jQuery.fx.start = function() { + if ( inProgress ) { + return; + } + + inProgress = true; + schedule(); +}; + +jQuery.fx.stop = function() { + inProgress = null; +}; + +jQuery.fx.speeds = { + slow: 600, + fast: 200, + + // Default speed + _default: 400 +}; + + +// Based off of the plugin by Clint Helfers, with permission. +// https://web.archive.org/web/20100324014747/http://blindsignals.com/index.php/2009/07/jquery-delay/ +jQuery.fn.delay = function( time, type ) { + time = jQuery.fx ? jQuery.fx.speeds[ time ] || time : time; + type = type || "fx"; + + return this.queue( type, function( next, hooks ) { + var timeout = window.setTimeout( next, time ); + hooks.stop = function() { + window.clearTimeout( timeout ); + }; + } ); +}; + + +( function() { + var input = document.createElement( "input" ), + select = document.createElement( "select" ), + opt = select.appendChild( document.createElement( "option" ) ); + + input.type = "checkbox"; + + // Support: Android <=4.3 only + // Default value for a checkbox should be "on" + support.checkOn = input.value !== ""; + + // Support: IE <=11 only + // Must access selectedIndex to make default options select + support.optSelected = opt.selected; + + // Support: IE <=11 only + // An input loses its value after becoming a radio + input = document.createElement( "input" ); + input.value = "t"; + input.type = "radio"; + support.radioValue = input.value === "t"; +} )(); + + +var boolHook, + attrHandle = jQuery.expr.attrHandle; + +jQuery.fn.extend( { + attr: function( name, value ) { + return access( this, jQuery.attr, name, value, arguments.length > 1 ); + }, + + removeAttr: function( name ) { + return this.each( function() { + jQuery.removeAttr( this, name ); + } ); + } +} ); + +jQuery.extend( { + attr: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set attributes on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + // Fallback to prop when attributes are not supported + if ( typeof elem.getAttribute === "undefined" ) { + return jQuery.prop( elem, name, value ); + } + + // Attribute hooks are determined by the lowercase version + // Grab necessary hook if one is defined + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + hooks = jQuery.attrHooks[ name.toLowerCase() ] || + ( jQuery.expr.match.bool.test( name ) ? boolHook : undefined ); + } + + if ( value !== undefined ) { + if ( value === null ) { + jQuery.removeAttr( elem, name ); + return; + } + + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + elem.setAttribute( name, value + "" ); + return value; + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + ret = jQuery.find.attr( elem, name ); + + // Non-existent attributes return null, we normalize to undefined + return ret == null ? undefined : ret; + }, + + attrHooks: { + type: { + set: function( elem, value ) { + if ( !support.radioValue && value === "radio" && + nodeName( elem, "input" ) ) { + var val = elem.value; + elem.setAttribute( "type", value ); + if ( val ) { + elem.value = val; + } + return value; + } + } + } + }, + + removeAttr: function( elem, value ) { + var name, + i = 0, + + // Attribute names can contain non-HTML whitespace characters + // https://html.spec.whatwg.org/multipage/syntax.html#attributes-2 + attrNames = value && value.match( rnothtmlwhite ); + + if ( attrNames && elem.nodeType === 1 ) { + while ( ( name = attrNames[ i++ ] ) ) { + elem.removeAttribute( name ); + } + } + } +} ); + +// Hooks for boolean attributes +boolHook = { + set: function( elem, value, name ) { + if ( value === false ) { + + // Remove boolean attributes when set to false + jQuery.removeAttr( elem, name ); + } else { + elem.setAttribute( name, name ); + } + return name; + } +}; + +jQuery.each( jQuery.expr.match.bool.source.match( /\w+/g ), function( _i, name ) { + var getter = attrHandle[ name ] || jQuery.find.attr; + + attrHandle[ name ] = function( elem, name, isXML ) { + var ret, handle, + lowercaseName = name.toLowerCase(); + + if ( !isXML ) { + + // Avoid an infinite loop by temporarily removing this function from the getter + handle = attrHandle[ lowercaseName ]; + attrHandle[ lowercaseName ] = ret; + ret = getter( elem, name, isXML ) != null ? + lowercaseName : + null; + attrHandle[ lowercaseName ] = handle; + } + return ret; + }; +} ); + + + + +var rfocusable = /^(?:input|select|textarea|button)$/i, + rclickable = /^(?:a|area)$/i; + +jQuery.fn.extend( { + prop: function( name, value ) { + return access( this, jQuery.prop, name, value, arguments.length > 1 ); + }, + + removeProp: function( name ) { + return this.each( function() { + delete this[ jQuery.propFix[ name ] || name ]; + } ); + } +} ); + +jQuery.extend( { + prop: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set properties on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + + // Fix name and attach hooks + name = jQuery.propFix[ name ] || name; + hooks = jQuery.propHooks[ name ]; + } + + if ( value !== undefined ) { + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + return ( elem[ name ] = value ); + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + return elem[ name ]; + }, + + propHooks: { + tabIndex: { + get: function( elem ) { + + // Support: IE <=9 - 11 only + // elem.tabIndex doesn't always return the + // correct value when it hasn't been explicitly set + // https://web.archive.org/web/20141116233347/http://fluidproject.org/blog/2008/01/09/getting-setting-and-removing-tabindex-values-with-javascript/ + // Use proper attribute retrieval(#12072) + var tabindex = jQuery.find.attr( elem, "tabindex" ); + + if ( tabindex ) { + return parseInt( tabindex, 10 ); + } + + if ( + rfocusable.test( elem.nodeName ) || + rclickable.test( elem.nodeName ) && + elem.href + ) { + return 0; + } + + return -1; + } + } + }, + + propFix: { + "for": "htmlFor", + "class": "className" + } +} ); + +// Support: IE <=11 only +// Accessing the selectedIndex property +// forces the browser to respect setting selected +// on the option +// The getter ensures a default option is selected +// when in an optgroup +// eslint rule "no-unused-expressions" is disabled for this code +// since it considers such accessions noop +if ( !support.optSelected ) { + jQuery.propHooks.selected = { + get: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent && parent.parentNode ) { + parent.parentNode.selectedIndex; + } + return null; + }, + set: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent ) { + parent.selectedIndex; + + if ( parent.parentNode ) { + parent.parentNode.selectedIndex; + } + } + } + }; +} + +jQuery.each( [ + "tabIndex", + "readOnly", + "maxLength", + "cellSpacing", + "cellPadding", + "rowSpan", + "colSpan", + "useMap", + "frameBorder", + "contentEditable" +], function() { + jQuery.propFix[ this.toLowerCase() ] = this; +} ); + + + + + // Strip and collapse whitespace according to HTML spec + // https://infra.spec.whatwg.org/#strip-and-collapse-ascii-whitespace + function stripAndCollapse( value ) { + var tokens = value.match( rnothtmlwhite ) || []; + return tokens.join( " " ); + } + + +function getClass( elem ) { + return elem.getAttribute && elem.getAttribute( "class" ) || ""; +} + +function classesToArray( value ) { + if ( Array.isArray( value ) ) { + return value; + } + if ( typeof value === "string" ) { + return value.match( rnothtmlwhite ) || []; + } + return []; +} + +jQuery.fn.extend( { + addClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).addClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + if ( cur.indexOf( " " + clazz + " " ) < 0 ) { + cur += clazz + " "; + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + removeClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).removeClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + if ( !arguments.length ) { + return this.attr( "class", "" ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + + // This expression is here for better compressibility (see addClass) + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + + // Remove *all* instances + while ( cur.indexOf( " " + clazz + " " ) > -1 ) { + cur = cur.replace( " " + clazz + " ", " " ); + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + toggleClass: function( value, stateVal ) { + var type = typeof value, + isValidValue = type === "string" || Array.isArray( value ); + + if ( typeof stateVal === "boolean" && isValidValue ) { + return stateVal ? this.addClass( value ) : this.removeClass( value ); + } + + if ( isFunction( value ) ) { + return this.each( function( i ) { + jQuery( this ).toggleClass( + value.call( this, i, getClass( this ), stateVal ), + stateVal + ); + } ); + } + + return this.each( function() { + var className, i, self, classNames; + + if ( isValidValue ) { + + // Toggle individual class names + i = 0; + self = jQuery( this ); + classNames = classesToArray( value ); + + while ( ( className = classNames[ i++ ] ) ) { + + // Check each className given, space separated list + if ( self.hasClass( className ) ) { + self.removeClass( className ); + } else { + self.addClass( className ); + } + } + + // Toggle whole class name + } else if ( value === undefined || type === "boolean" ) { + className = getClass( this ); + if ( className ) { + + // Store className if set + dataPriv.set( this, "__className__", className ); + } + + // If the element has a class name or if we're passed `false`, + // then remove the whole classname (if there was one, the above saved it). + // Otherwise bring back whatever was previously saved (if anything), + // falling back to the empty string if nothing was stored. + if ( this.setAttribute ) { + this.setAttribute( "class", + className || value === false ? + "" : + dataPriv.get( this, "__className__" ) || "" + ); + } + } + } ); + }, + + hasClass: function( selector ) { + var className, elem, + i = 0; + + className = " " + selector + " "; + while ( ( elem = this[ i++ ] ) ) { + if ( elem.nodeType === 1 && + ( " " + stripAndCollapse( getClass( elem ) ) + " " ).indexOf( className ) > -1 ) { + return true; + } + } + + return false; + } +} ); + + + + +var rreturn = /\r/g; + +jQuery.fn.extend( { + val: function( value ) { + var hooks, ret, valueIsFunction, + elem = this[ 0 ]; + + if ( !arguments.length ) { + if ( elem ) { + hooks = jQuery.valHooks[ elem.type ] || + jQuery.valHooks[ elem.nodeName.toLowerCase() ]; + + if ( hooks && + "get" in hooks && + ( ret = hooks.get( elem, "value" ) ) !== undefined + ) { + return ret; + } + + ret = elem.value; + + // Handle most common string cases + if ( typeof ret === "string" ) { + return ret.replace( rreturn, "" ); + } + + // Handle cases where value is null/undef or number + return ret == null ? "" : ret; + } + + return; + } + + valueIsFunction = isFunction( value ); + + return this.each( function( i ) { + var val; + + if ( this.nodeType !== 1 ) { + return; + } + + if ( valueIsFunction ) { + val = value.call( this, i, jQuery( this ).val() ); + } else { + val = value; + } + + // Treat null/undefined as ""; convert numbers to string + if ( val == null ) { + val = ""; + + } else if ( typeof val === "number" ) { + val += ""; + + } else if ( Array.isArray( val ) ) { + val = jQuery.map( val, function( value ) { + return value == null ? "" : value + ""; + } ); + } + + hooks = jQuery.valHooks[ this.type ] || jQuery.valHooks[ this.nodeName.toLowerCase() ]; + + // If set returns undefined, fall back to normal setting + if ( !hooks || !( "set" in hooks ) || hooks.set( this, val, "value" ) === undefined ) { + this.value = val; + } + } ); + } +} ); + +jQuery.extend( { + valHooks: { + option: { + get: function( elem ) { + + var val = jQuery.find.attr( elem, "value" ); + return val != null ? + val : + + // Support: IE <=10 - 11 only + // option.text throws exceptions (#14686, #14858) + // Strip and collapse whitespace + // https://html.spec.whatwg.org/#strip-and-collapse-whitespace + stripAndCollapse( jQuery.text( elem ) ); + } + }, + select: { + get: function( elem ) { + var value, option, i, + options = elem.options, + index = elem.selectedIndex, + one = elem.type === "select-one", + values = one ? null : [], + max = one ? index + 1 : options.length; + + if ( index < 0 ) { + i = max; + + } else { + i = one ? index : 0; + } + + // Loop through all the selected options + for ( ; i < max; i++ ) { + option = options[ i ]; + + // Support: IE <=9 only + // IE8-9 doesn't update selected after form reset (#2551) + if ( ( option.selected || i === index ) && + + // Don't return options that are disabled or in a disabled optgroup + !option.disabled && + ( !option.parentNode.disabled || + !nodeName( option.parentNode, "optgroup" ) ) ) { + + // Get the specific value for the option + value = jQuery( option ).val(); + + // We don't need an array for one selects + if ( one ) { + return value; + } + + // Multi-Selects return an array + values.push( value ); + } + } + + return values; + }, + + set: function( elem, value ) { + var optionSet, option, + options = elem.options, + values = jQuery.makeArray( value ), + i = options.length; + + while ( i-- ) { + option = options[ i ]; + + /* eslint-disable no-cond-assign */ + + if ( option.selected = + jQuery.inArray( jQuery.valHooks.option.get( option ), values ) > -1 + ) { + optionSet = true; + } + + /* eslint-enable no-cond-assign */ + } + + // Force browsers to behave consistently when non-matching value is set + if ( !optionSet ) { + elem.selectedIndex = -1; + } + return values; + } + } + } +} ); + +// Radios and checkboxes getter/setter +jQuery.each( [ "radio", "checkbox" ], function() { + jQuery.valHooks[ this ] = { + set: function( elem, value ) { + if ( Array.isArray( value ) ) { + return ( elem.checked = jQuery.inArray( jQuery( elem ).val(), value ) > -1 ); + } + } + }; + if ( !support.checkOn ) { + jQuery.valHooks[ this ].get = function( elem ) { + return elem.getAttribute( "value" ) === null ? "on" : elem.value; + }; + } +} ); + + + + +// Return jQuery for attributes-only inclusion + + +support.focusin = "onfocusin" in window; + + +var rfocusMorph = /^(?:focusinfocus|focusoutblur)$/, + stopPropagationCallback = function( e ) { + e.stopPropagation(); + }; + +jQuery.extend( jQuery.event, { + + trigger: function( event, data, elem, onlyHandlers ) { + + var i, cur, tmp, bubbleType, ontype, handle, special, lastElement, + eventPath = [ elem || document ], + type = hasOwn.call( event, "type" ) ? event.type : event, + namespaces = hasOwn.call( event, "namespace" ) ? event.namespace.split( "." ) : []; + + cur = lastElement = tmp = elem = elem || document; + + // Don't do events on text and comment nodes + if ( elem.nodeType === 3 || elem.nodeType === 8 ) { + return; + } + + // focus/blur morphs to focusin/out; ensure we're not firing them right now + if ( rfocusMorph.test( type + jQuery.event.triggered ) ) { + return; + } + + if ( type.indexOf( "." ) > -1 ) { + + // Namespaced trigger; create a regexp to match event type in handle() + namespaces = type.split( "." ); + type = namespaces.shift(); + namespaces.sort(); + } + ontype = type.indexOf( ":" ) < 0 && "on" + type; + + // Caller can pass in a jQuery.Event object, Object, or just an event type string + event = event[ jQuery.expando ] ? + event : + new jQuery.Event( type, typeof event === "object" && event ); + + // Trigger bitmask: & 1 for native handlers; & 2 for jQuery (always true) + event.isTrigger = onlyHandlers ? 2 : 3; + event.namespace = namespaces.join( "." ); + event.rnamespace = event.namespace ? + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ) : + null; + + // Clean up the event in case it is being reused + event.result = undefined; + if ( !event.target ) { + event.target = elem; + } + + // Clone any incoming data and prepend the event, creating the handler arg list + data = data == null ? + [ event ] : + jQuery.makeArray( data, [ event ] ); + + // Allow special events to draw outside the lines + special = jQuery.event.special[ type ] || {}; + if ( !onlyHandlers && special.trigger && special.trigger.apply( elem, data ) === false ) { + return; + } + + // Determine event propagation path in advance, per W3C events spec (#9951) + // Bubble up to document, then to window; watch for a global ownerDocument var (#9724) + if ( !onlyHandlers && !special.noBubble && !isWindow( elem ) ) { + + bubbleType = special.delegateType || type; + if ( !rfocusMorph.test( bubbleType + type ) ) { + cur = cur.parentNode; + } + for ( ; cur; cur = cur.parentNode ) { + eventPath.push( cur ); + tmp = cur; + } + + // Only add window if we got to document (e.g., not plain obj or detached DOM) + if ( tmp === ( elem.ownerDocument || document ) ) { + eventPath.push( tmp.defaultView || tmp.parentWindow || window ); + } + } + + // Fire handlers on the event path + i = 0; + while ( ( cur = eventPath[ i++ ] ) && !event.isPropagationStopped() ) { + lastElement = cur; + event.type = i > 1 ? + bubbleType : + special.bindType || type; + + // jQuery handler + handle = ( + dataPriv.get( cur, "events" ) || Object.create( null ) + )[ event.type ] && + dataPriv.get( cur, "handle" ); + if ( handle ) { + handle.apply( cur, data ); + } + + // Native handler + handle = ontype && cur[ ontype ]; + if ( handle && handle.apply && acceptData( cur ) ) { + event.result = handle.apply( cur, data ); + if ( event.result === false ) { + event.preventDefault(); + } + } + } + event.type = type; + + // If nobody prevented the default action, do it now + if ( !onlyHandlers && !event.isDefaultPrevented() ) { + + if ( ( !special._default || + special._default.apply( eventPath.pop(), data ) === false ) && + acceptData( elem ) ) { + + // Call a native DOM method on the target with the same name as the event. + // Don't do default actions on window, that's where global variables be (#6170) + if ( ontype && isFunction( elem[ type ] ) && !isWindow( elem ) ) { + + // Don't re-trigger an onFOO event when we call its FOO() method + tmp = elem[ ontype ]; + + if ( tmp ) { + elem[ ontype ] = null; + } + + // Prevent re-triggering of the same event, since we already bubbled it above + jQuery.event.triggered = type; + + if ( event.isPropagationStopped() ) { + lastElement.addEventListener( type, stopPropagationCallback ); + } + + elem[ type ](); + + if ( event.isPropagationStopped() ) { + lastElement.removeEventListener( type, stopPropagationCallback ); + } + + jQuery.event.triggered = undefined; + + if ( tmp ) { + elem[ ontype ] = tmp; + } + } + } + } + + return event.result; + }, + + // Piggyback on a donor event to simulate a different one + // Used only for `focus(in | out)` events + simulate: function( type, elem, event ) { + var e = jQuery.extend( + new jQuery.Event(), + event, + { + type: type, + isSimulated: true + } + ); + + jQuery.event.trigger( e, null, elem ); + } + +} ); + +jQuery.fn.extend( { + + trigger: function( type, data ) { + return this.each( function() { + jQuery.event.trigger( type, data, this ); + } ); + }, + triggerHandler: function( type, data ) { + var elem = this[ 0 ]; + if ( elem ) { + return jQuery.event.trigger( type, data, elem, true ); + } + } +} ); + + +// Support: Firefox <=44 +// Firefox doesn't have focus(in | out) events +// Related ticket - https://bugzilla.mozilla.org/show_bug.cgi?id=687787 +// +// Support: Chrome <=48 - 49, Safari <=9.0 - 9.1 +// focus(in | out) events fire after focus & blur events, +// which is spec violation - http://www.w3.org/TR/DOM-Level-3-Events/#events-focusevent-event-order +// Related ticket - https://bugs.chromium.org/p/chromium/issues/detail?id=449857 +if ( !support.focusin ) { + jQuery.each( { focus: "focusin", blur: "focusout" }, function( orig, fix ) { + + // Attach a single capturing handler on the document while someone wants focusin/focusout + var handler = function( event ) { + jQuery.event.simulate( fix, event.target, jQuery.event.fix( event ) ); + }; + + jQuery.event.special[ fix ] = { + setup: function() { + + // Handle: regular nodes (via `this.ownerDocument`), window + // (via `this.document`) & document (via `this`). + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ); + + if ( !attaches ) { + doc.addEventListener( orig, handler, true ); + } + dataPriv.access( doc, fix, ( attaches || 0 ) + 1 ); + }, + teardown: function() { + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ) - 1; + + if ( !attaches ) { + doc.removeEventListener( orig, handler, true ); + dataPriv.remove( doc, fix ); + + } else { + dataPriv.access( doc, fix, attaches ); + } + } + }; + } ); +} +var location = window.location; + +var nonce = { guid: Date.now() }; + +var rquery = ( /\?/ ); + + + +// Cross-browser xml parsing +jQuery.parseXML = function( data ) { + var xml; + if ( !data || typeof data !== "string" ) { + return null; + } + + // Support: IE 9 - 11 only + // IE throws on parseFromString with invalid input. + try { + xml = ( new window.DOMParser() ).parseFromString( data, "text/xml" ); + } catch ( e ) { + xml = undefined; + } + + if ( !xml || xml.getElementsByTagName( "parsererror" ).length ) { + jQuery.error( "Invalid XML: " + data ); + } + return xml; +}; + + +var + rbracket = /\[\]$/, + rCRLF = /\r?\n/g, + rsubmitterTypes = /^(?:submit|button|image|reset|file)$/i, + rsubmittable = /^(?:input|select|textarea|keygen)/i; + +function buildParams( prefix, obj, traditional, add ) { + var name; + + if ( Array.isArray( obj ) ) { + + // Serialize array item. + jQuery.each( obj, function( i, v ) { + if ( traditional || rbracket.test( prefix ) ) { + + // Treat each array item as a scalar. + add( prefix, v ); + + } else { + + // Item is non-scalar (array or object), encode its numeric index. + buildParams( + prefix + "[" + ( typeof v === "object" && v != null ? i : "" ) + "]", + v, + traditional, + add + ); + } + } ); + + } else if ( !traditional && toType( obj ) === "object" ) { + + // Serialize object item. + for ( name in obj ) { + buildParams( prefix + "[" + name + "]", obj[ name ], traditional, add ); + } + + } else { + + // Serialize scalar item. + add( prefix, obj ); + } +} + +// Serialize an array of form elements or a set of +// key/values into a query string +jQuery.param = function( a, traditional ) { + var prefix, + s = [], + add = function( key, valueOrFunction ) { + + // If value is a function, invoke it and use its return value + var value = isFunction( valueOrFunction ) ? + valueOrFunction() : + valueOrFunction; + + s[ s.length ] = encodeURIComponent( key ) + "=" + + encodeURIComponent( value == null ? "" : value ); + }; + + if ( a == null ) { + return ""; + } + + // If an array was passed in, assume that it is an array of form elements. + if ( Array.isArray( a ) || ( a.jquery && !jQuery.isPlainObject( a ) ) ) { + + // Serialize the form elements + jQuery.each( a, function() { + add( this.name, this.value ); + } ); + + } else { + + // If traditional, encode the "old" way (the way 1.3.2 or older + // did it), otherwise encode params recursively. + for ( prefix in a ) { + buildParams( prefix, a[ prefix ], traditional, add ); + } + } + + // Return the resulting serialization + return s.join( "&" ); +}; + +jQuery.fn.extend( { + serialize: function() { + return jQuery.param( this.serializeArray() ); + }, + serializeArray: function() { + return this.map( function() { + + // Can add propHook for "elements" to filter or add form elements + var elements = jQuery.prop( this, "elements" ); + return elements ? jQuery.makeArray( elements ) : this; + } ) + .filter( function() { + var type = this.type; + + // Use .is( ":disabled" ) so that fieldset[disabled] works + return this.name && !jQuery( this ).is( ":disabled" ) && + rsubmittable.test( this.nodeName ) && !rsubmitterTypes.test( type ) && + ( this.checked || !rcheckableType.test( type ) ); + } ) + .map( function( _i, elem ) { + var val = jQuery( this ).val(); + + if ( val == null ) { + return null; + } + + if ( Array.isArray( val ) ) { + return jQuery.map( val, function( val ) { + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ); + } + + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ).get(); + } +} ); + + +var + r20 = /%20/g, + rhash = /#.*$/, + rantiCache = /([?&])_=[^&]*/, + rheaders = /^(.*?):[ \t]*([^\r\n]*)$/mg, + + // #7653, #8125, #8152: local protocol detection + rlocalProtocol = /^(?:about|app|app-storage|.+-extension|file|res|widget):$/, + rnoContent = /^(?:GET|HEAD)$/, + rprotocol = /^\/\//, + + /* Prefilters + * 1) They are useful to introduce custom dataTypes (see ajax/jsonp.js for an example) + * 2) These are called: + * - BEFORE asking for a transport + * - AFTER param serialization (s.data is a string if s.processData is true) + * 3) key is the dataType + * 4) the catchall symbol "*" can be used + * 5) execution will start with transport dataType and THEN continue down to "*" if needed + */ + prefilters = {}, + + /* Transports bindings + * 1) key is the dataType + * 2) the catchall symbol "*" can be used + * 3) selection will start with transport dataType and THEN go to "*" if needed + */ + transports = {}, + + // Avoid comment-prolog char sequence (#10098); must appease lint and evade compression + allTypes = "*/".concat( "*" ), + + // Anchor tag for parsing the document origin + originAnchor = document.createElement( "a" ); + originAnchor.href = location.href; + +// Base "constructor" for jQuery.ajaxPrefilter and jQuery.ajaxTransport +function addToPrefiltersOrTransports( structure ) { + + // dataTypeExpression is optional and defaults to "*" + return function( dataTypeExpression, func ) { + + if ( typeof dataTypeExpression !== "string" ) { + func = dataTypeExpression; + dataTypeExpression = "*"; + } + + var dataType, + i = 0, + dataTypes = dataTypeExpression.toLowerCase().match( rnothtmlwhite ) || []; + + if ( isFunction( func ) ) { + + // For each dataType in the dataTypeExpression + while ( ( dataType = dataTypes[ i++ ] ) ) { + + // Prepend if requested + if ( dataType[ 0 ] === "+" ) { + dataType = dataType.slice( 1 ) || "*"; + ( structure[ dataType ] = structure[ dataType ] || [] ).unshift( func ); + + // Otherwise append + } else { + ( structure[ dataType ] = structure[ dataType ] || [] ).push( func ); + } + } + } + }; +} + +// Base inspection function for prefilters and transports +function inspectPrefiltersOrTransports( structure, options, originalOptions, jqXHR ) { + + var inspected = {}, + seekingTransport = ( structure === transports ); + + function inspect( dataType ) { + var selected; + inspected[ dataType ] = true; + jQuery.each( structure[ dataType ] || [], function( _, prefilterOrFactory ) { + var dataTypeOrTransport = prefilterOrFactory( options, originalOptions, jqXHR ); + if ( typeof dataTypeOrTransport === "string" && + !seekingTransport && !inspected[ dataTypeOrTransport ] ) { + + options.dataTypes.unshift( dataTypeOrTransport ); + inspect( dataTypeOrTransport ); + return false; + } else if ( seekingTransport ) { + return !( selected = dataTypeOrTransport ); + } + } ); + return selected; + } + + return inspect( options.dataTypes[ 0 ] ) || !inspected[ "*" ] && inspect( "*" ); +} + +// A special extend for ajax options +// that takes "flat" options (not to be deep extended) +// Fixes #9887 +function ajaxExtend( target, src ) { + var key, deep, + flatOptions = jQuery.ajaxSettings.flatOptions || {}; + + for ( key in src ) { + if ( src[ key ] !== undefined ) { + ( flatOptions[ key ] ? target : ( deep || ( deep = {} ) ) )[ key ] = src[ key ]; + } + } + if ( deep ) { + jQuery.extend( true, target, deep ); + } + + return target; +} + +/* Handles responses to an ajax request: + * - finds the right dataType (mediates between content-type and expected dataType) + * - returns the corresponding response + */ +function ajaxHandleResponses( s, jqXHR, responses ) { + + var ct, type, finalDataType, firstDataType, + contents = s.contents, + dataTypes = s.dataTypes; + + // Remove auto dataType and get content-type in the process + while ( dataTypes[ 0 ] === "*" ) { + dataTypes.shift(); + if ( ct === undefined ) { + ct = s.mimeType || jqXHR.getResponseHeader( "Content-Type" ); + } + } + + // Check if we're dealing with a known content-type + if ( ct ) { + for ( type in contents ) { + if ( contents[ type ] && contents[ type ].test( ct ) ) { + dataTypes.unshift( type ); + break; + } + } + } + + // Check to see if we have a response for the expected dataType + if ( dataTypes[ 0 ] in responses ) { + finalDataType = dataTypes[ 0 ]; + } else { + + // Try convertible dataTypes + for ( type in responses ) { + if ( !dataTypes[ 0 ] || s.converters[ type + " " + dataTypes[ 0 ] ] ) { + finalDataType = type; + break; + } + if ( !firstDataType ) { + firstDataType = type; + } + } + + // Or just use first one + finalDataType = finalDataType || firstDataType; + } + + // If we found a dataType + // We add the dataType to the list if needed + // and return the corresponding response + if ( finalDataType ) { + if ( finalDataType !== dataTypes[ 0 ] ) { + dataTypes.unshift( finalDataType ); + } + return responses[ finalDataType ]; + } +} + +/* Chain conversions given the request and the original response + * Also sets the responseXXX fields on the jqXHR instance + */ +function ajaxConvert( s, response, jqXHR, isSuccess ) { + var conv2, current, conv, tmp, prev, + converters = {}, + + // Work with a copy of dataTypes in case we need to modify it for conversion + dataTypes = s.dataTypes.slice(); + + // Create converters map with lowercased keys + if ( dataTypes[ 1 ] ) { + for ( conv in s.converters ) { + converters[ conv.toLowerCase() ] = s.converters[ conv ]; + } + } + + current = dataTypes.shift(); + + // Convert to each sequential dataType + while ( current ) { + + if ( s.responseFields[ current ] ) { + jqXHR[ s.responseFields[ current ] ] = response; + } + + // Apply the dataFilter if provided + if ( !prev && isSuccess && s.dataFilter ) { + response = s.dataFilter( response, s.dataType ); + } + + prev = current; + current = dataTypes.shift(); + + if ( current ) { + + // There's only work to do if current dataType is non-auto + if ( current === "*" ) { + + current = prev; + + // Convert response if prev dataType is non-auto and differs from current + } else if ( prev !== "*" && prev !== current ) { + + // Seek a direct converter + conv = converters[ prev + " " + current ] || converters[ "* " + current ]; + + // If none found, seek a pair + if ( !conv ) { + for ( conv2 in converters ) { + + // If conv2 outputs current + tmp = conv2.split( " " ); + if ( tmp[ 1 ] === current ) { + + // If prev can be converted to accepted input + conv = converters[ prev + " " + tmp[ 0 ] ] || + converters[ "* " + tmp[ 0 ] ]; + if ( conv ) { + + // Condense equivalence converters + if ( conv === true ) { + conv = converters[ conv2 ]; + + // Otherwise, insert the intermediate dataType + } else if ( converters[ conv2 ] !== true ) { + current = tmp[ 0 ]; + dataTypes.unshift( tmp[ 1 ] ); + } + break; + } + } + } + } + + // Apply converter (if not an equivalence) + if ( conv !== true ) { + + // Unless errors are allowed to bubble, catch and return them + if ( conv && s.throws ) { + response = conv( response ); + } else { + try { + response = conv( response ); + } catch ( e ) { + return { + state: "parsererror", + error: conv ? e : "No conversion from " + prev + " to " + current + }; + } + } + } + } + } + } + + return { state: "success", data: response }; +} + +jQuery.extend( { + + // Counter for holding the number of active queries + active: 0, + + // Last-Modified header cache for next request + lastModified: {}, + etag: {}, + + ajaxSettings: { + url: location.href, + type: "GET", + isLocal: rlocalProtocol.test( location.protocol ), + global: true, + processData: true, + async: true, + contentType: "application/x-www-form-urlencoded; charset=UTF-8", + + /* + timeout: 0, + data: null, + dataType: null, + username: null, + password: null, + cache: null, + throws: false, + traditional: false, + headers: {}, + */ + + accepts: { + "*": allTypes, + text: "text/plain", + html: "text/html", + xml: "application/xml, text/xml", + json: "application/json, text/javascript" + }, + + contents: { + xml: /\bxml\b/, + html: /\bhtml/, + json: /\bjson\b/ + }, + + responseFields: { + xml: "responseXML", + text: "responseText", + json: "responseJSON" + }, + + // Data converters + // Keys separate source (or catchall "*") and destination types with a single space + converters: { + + // Convert anything to text + "* text": String, + + // Text to html (true = no transformation) + "text html": true, + + // Evaluate text as a json expression + "text json": JSON.parse, + + // Parse text as xml + "text xml": jQuery.parseXML + }, + + // For options that shouldn't be deep extended: + // you can add your own custom options here if + // and when you create one that shouldn't be + // deep extended (see ajaxExtend) + flatOptions: { + url: true, + context: true + } + }, + + // Creates a full fledged settings object into target + // with both ajaxSettings and settings fields. + // If target is omitted, writes into ajaxSettings. + ajaxSetup: function( target, settings ) { + return settings ? + + // Building a settings object + ajaxExtend( ajaxExtend( target, jQuery.ajaxSettings ), settings ) : + + // Extending ajaxSettings + ajaxExtend( jQuery.ajaxSettings, target ); + }, + + ajaxPrefilter: addToPrefiltersOrTransports( prefilters ), + ajaxTransport: addToPrefiltersOrTransports( transports ), + + // Main method + ajax: function( url, options ) { + + // If url is an object, simulate pre-1.5 signature + if ( typeof url === "object" ) { + options = url; + url = undefined; + } + + // Force options to be an object + options = options || {}; + + var transport, + + // URL without anti-cache param + cacheURL, + + // Response headers + responseHeadersString, + responseHeaders, + + // timeout handle + timeoutTimer, + + // Url cleanup var + urlAnchor, + + // Request state (becomes false upon send and true upon completion) + completed, + + // To know if global events are to be dispatched + fireGlobals, + + // Loop variable + i, + + // uncached part of the url + uncached, + + // Create the final options object + s = jQuery.ajaxSetup( {}, options ), + + // Callbacks context + callbackContext = s.context || s, + + // Context for global events is callbackContext if it is a DOM node or jQuery collection + globalEventContext = s.context && + ( callbackContext.nodeType || callbackContext.jquery ) ? + jQuery( callbackContext ) : + jQuery.event, + + // Deferreds + deferred = jQuery.Deferred(), + completeDeferred = jQuery.Callbacks( "once memory" ), + + // Status-dependent callbacks + statusCode = s.statusCode || {}, + + // Headers (they are sent all at once) + requestHeaders = {}, + requestHeadersNames = {}, + + // Default abort message + strAbort = "canceled", + + // Fake xhr + jqXHR = { + readyState: 0, + + // Builds headers hashtable if needed + getResponseHeader: function( key ) { + var match; + if ( completed ) { + if ( !responseHeaders ) { + responseHeaders = {}; + while ( ( match = rheaders.exec( responseHeadersString ) ) ) { + responseHeaders[ match[ 1 ].toLowerCase() + " " ] = + ( responseHeaders[ match[ 1 ].toLowerCase() + " " ] || [] ) + .concat( match[ 2 ] ); + } + } + match = responseHeaders[ key.toLowerCase() + " " ]; + } + return match == null ? null : match.join( ", " ); + }, + + // Raw string + getAllResponseHeaders: function() { + return completed ? responseHeadersString : null; + }, + + // Caches the header + setRequestHeader: function( name, value ) { + if ( completed == null ) { + name = requestHeadersNames[ name.toLowerCase() ] = + requestHeadersNames[ name.toLowerCase() ] || name; + requestHeaders[ name ] = value; + } + return this; + }, + + // Overrides response content-type header + overrideMimeType: function( type ) { + if ( completed == null ) { + s.mimeType = type; + } + return this; + }, + + // Status-dependent callbacks + statusCode: function( map ) { + var code; + if ( map ) { + if ( completed ) { + + // Execute the appropriate callbacks + jqXHR.always( map[ jqXHR.status ] ); + } else { + + // Lazy-add the new callbacks in a way that preserves old ones + for ( code in map ) { + statusCode[ code ] = [ statusCode[ code ], map[ code ] ]; + } + } + } + return this; + }, + + // Cancel the request + abort: function( statusText ) { + var finalText = statusText || strAbort; + if ( transport ) { + transport.abort( finalText ); + } + done( 0, finalText ); + return this; + } + }; + + // Attach deferreds + deferred.promise( jqXHR ); + + // Add protocol if not provided (prefilters might expect it) + // Handle falsy url in the settings object (#10093: consistency with old signature) + // We also use the url parameter if available + s.url = ( ( url || s.url || location.href ) + "" ) + .replace( rprotocol, location.protocol + "//" ); + + // Alias method option to type as per ticket #12004 + s.type = options.method || options.type || s.method || s.type; + + // Extract dataTypes list + s.dataTypes = ( s.dataType || "*" ).toLowerCase().match( rnothtmlwhite ) || [ "" ]; + + // A cross-domain request is in order when the origin doesn't match the current origin. + if ( s.crossDomain == null ) { + urlAnchor = document.createElement( "a" ); + + // Support: IE <=8 - 11, Edge 12 - 15 + // IE throws exception on accessing the href property if url is malformed, + // e.g. http://example.com:80x/ + try { + urlAnchor.href = s.url; + + // Support: IE <=8 - 11 only + // Anchor's host property isn't correctly set when s.url is relative + urlAnchor.href = urlAnchor.href; + s.crossDomain = originAnchor.protocol + "//" + originAnchor.host !== + urlAnchor.protocol + "//" + urlAnchor.host; + } catch ( e ) { + + // If there is an error parsing the URL, assume it is crossDomain, + // it can be rejected by the transport if it is invalid + s.crossDomain = true; + } + } + + // Convert data if not already a string + if ( s.data && s.processData && typeof s.data !== "string" ) { + s.data = jQuery.param( s.data, s.traditional ); + } + + // Apply prefilters + inspectPrefiltersOrTransports( prefilters, s, options, jqXHR ); + + // If request was aborted inside a prefilter, stop there + if ( completed ) { + return jqXHR; + } + + // We can fire global events as of now if asked to + // Don't fire events if jQuery.event is undefined in an AMD-usage scenario (#15118) + fireGlobals = jQuery.event && s.global; + + // Watch for a new set of requests + if ( fireGlobals && jQuery.active++ === 0 ) { + jQuery.event.trigger( "ajaxStart" ); + } + + // Uppercase the type + s.type = s.type.toUpperCase(); + + // Determine if request has content + s.hasContent = !rnoContent.test( s.type ); + + // Save the URL in case we're toying with the If-Modified-Since + // and/or If-None-Match header later on + // Remove hash to simplify url manipulation + cacheURL = s.url.replace( rhash, "" ); + + // More options handling for requests with no content + if ( !s.hasContent ) { + + // Remember the hash so we can put it back + uncached = s.url.slice( cacheURL.length ); + + // If data is available and should be processed, append data to url + if ( s.data && ( s.processData || typeof s.data === "string" ) ) { + cacheURL += ( rquery.test( cacheURL ) ? "&" : "?" ) + s.data; + + // #9682: remove data so that it's not used in an eventual retry + delete s.data; + } + + // Add or update anti-cache param if needed + if ( s.cache === false ) { + cacheURL = cacheURL.replace( rantiCache, "$1" ); + uncached = ( rquery.test( cacheURL ) ? "&" : "?" ) + "_=" + ( nonce.guid++ ) + + uncached; + } + + // Put hash and anti-cache on the URL that will be requested (gh-1732) + s.url = cacheURL + uncached; + + // Change '%20' to '+' if this is encoded form body content (gh-2658) + } else if ( s.data && s.processData && + ( s.contentType || "" ).indexOf( "application/x-www-form-urlencoded" ) === 0 ) { + s.data = s.data.replace( r20, "+" ); + } + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + if ( jQuery.lastModified[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-Modified-Since", jQuery.lastModified[ cacheURL ] ); + } + if ( jQuery.etag[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-None-Match", jQuery.etag[ cacheURL ] ); + } + } + + // Set the correct header, if data is being sent + if ( s.data && s.hasContent && s.contentType !== false || options.contentType ) { + jqXHR.setRequestHeader( "Content-Type", s.contentType ); + } + + // Set the Accepts header for the server, depending on the dataType + jqXHR.setRequestHeader( + "Accept", + s.dataTypes[ 0 ] && s.accepts[ s.dataTypes[ 0 ] ] ? + s.accepts[ s.dataTypes[ 0 ] ] + + ( s.dataTypes[ 0 ] !== "*" ? ", " + allTypes + "; q=0.01" : "" ) : + s.accepts[ "*" ] + ); + + // Check for headers option + for ( i in s.headers ) { + jqXHR.setRequestHeader( i, s.headers[ i ] ); + } + + // Allow custom headers/mimetypes and early abort + if ( s.beforeSend && + ( s.beforeSend.call( callbackContext, jqXHR, s ) === false || completed ) ) { + + // Abort if not done already and return + return jqXHR.abort(); + } + + // Aborting is no longer a cancellation + strAbort = "abort"; + + // Install callbacks on deferreds + completeDeferred.add( s.complete ); + jqXHR.done( s.success ); + jqXHR.fail( s.error ); + + // Get transport + transport = inspectPrefiltersOrTransports( transports, s, options, jqXHR ); + + // If no transport, we auto-abort + if ( !transport ) { + done( -1, "No Transport" ); + } else { + jqXHR.readyState = 1; + + // Send global event + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxSend", [ jqXHR, s ] ); + } + + // If request was aborted inside ajaxSend, stop there + if ( completed ) { + return jqXHR; + } + + // Timeout + if ( s.async && s.timeout > 0 ) { + timeoutTimer = window.setTimeout( function() { + jqXHR.abort( "timeout" ); + }, s.timeout ); + } + + try { + completed = false; + transport.send( requestHeaders, done ); + } catch ( e ) { + + // Rethrow post-completion exceptions + if ( completed ) { + throw e; + } + + // Propagate others as results + done( -1, e ); + } + } + + // Callback for when everything is done + function done( status, nativeStatusText, responses, headers ) { + var isSuccess, success, error, response, modified, + statusText = nativeStatusText; + + // Ignore repeat invocations + if ( completed ) { + return; + } + + completed = true; + + // Clear timeout if it exists + if ( timeoutTimer ) { + window.clearTimeout( timeoutTimer ); + } + + // Dereference transport for early garbage collection + // (no matter how long the jqXHR object will be used) + transport = undefined; + + // Cache response headers + responseHeadersString = headers || ""; + + // Set readyState + jqXHR.readyState = status > 0 ? 4 : 0; + + // Determine if successful + isSuccess = status >= 200 && status < 300 || status === 304; + + // Get response data + if ( responses ) { + response = ajaxHandleResponses( s, jqXHR, responses ); + } + + // Use a noop converter for missing script + if ( !isSuccess && jQuery.inArray( "script", s.dataTypes ) > -1 ) { + s.converters[ "text script" ] = function() {}; + } + + // Convert no matter what (that way responseXXX fields are always set) + response = ajaxConvert( s, response, jqXHR, isSuccess ); + + // If successful, handle type chaining + if ( isSuccess ) { + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + modified = jqXHR.getResponseHeader( "Last-Modified" ); + if ( modified ) { + jQuery.lastModified[ cacheURL ] = modified; + } + modified = jqXHR.getResponseHeader( "etag" ); + if ( modified ) { + jQuery.etag[ cacheURL ] = modified; + } + } + + // if no content + if ( status === 204 || s.type === "HEAD" ) { + statusText = "nocontent"; + + // if not modified + } else if ( status === 304 ) { + statusText = "notmodified"; + + // If we have data, let's convert it + } else { + statusText = response.state; + success = response.data; + error = response.error; + isSuccess = !error; + } + } else { + + // Extract error from statusText and normalize for non-aborts + error = statusText; + if ( status || !statusText ) { + statusText = "error"; + if ( status < 0 ) { + status = 0; + } + } + } + + // Set data for the fake xhr object + jqXHR.status = status; + jqXHR.statusText = ( nativeStatusText || statusText ) + ""; + + // Success/Error + if ( isSuccess ) { + deferred.resolveWith( callbackContext, [ success, statusText, jqXHR ] ); + } else { + deferred.rejectWith( callbackContext, [ jqXHR, statusText, error ] ); + } + + // Status-dependent callbacks + jqXHR.statusCode( statusCode ); + statusCode = undefined; + + if ( fireGlobals ) { + globalEventContext.trigger( isSuccess ? "ajaxSuccess" : "ajaxError", + [ jqXHR, s, isSuccess ? success : error ] ); + } + + // Complete + completeDeferred.fireWith( callbackContext, [ jqXHR, statusText ] ); + + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxComplete", [ jqXHR, s ] ); + + // Handle the global AJAX counter + if ( !( --jQuery.active ) ) { + jQuery.event.trigger( "ajaxStop" ); + } + } + } + + return jqXHR; + }, + + getJSON: function( url, data, callback ) { + return jQuery.get( url, data, callback, "json" ); + }, + + getScript: function( url, callback ) { + return jQuery.get( url, undefined, callback, "script" ); + } +} ); + +jQuery.each( [ "get", "post" ], function( _i, method ) { + jQuery[ method ] = function( url, data, callback, type ) { + + // Shift arguments if data argument was omitted + if ( isFunction( data ) ) { + type = type || callback; + callback = data; + data = undefined; + } + + // The url can be an options object (which then must have .url) + return jQuery.ajax( jQuery.extend( { + url: url, + type: method, + dataType: type, + data: data, + success: callback + }, jQuery.isPlainObject( url ) && url ) ); + }; +} ); + +jQuery.ajaxPrefilter( function( s ) { + var i; + for ( i in s.headers ) { + if ( i.toLowerCase() === "content-type" ) { + s.contentType = s.headers[ i ] || ""; + } + } +} ); + + +jQuery._evalUrl = function( url, options, doc ) { + return jQuery.ajax( { + url: url, + + // Make this explicit, since user can override this through ajaxSetup (#11264) + type: "GET", + dataType: "script", + cache: true, + async: false, + global: false, + + // Only evaluate the response if it is successful (gh-4126) + // dataFilter is not invoked for failure responses, so using it instead + // of the default converter is kludgy but it works. + converters: { + "text script": function() {} + }, + dataFilter: function( response ) { + jQuery.globalEval( response, options, doc ); + } + } ); +}; + + +jQuery.fn.extend( { + wrapAll: function( html ) { + var wrap; + + if ( this[ 0 ] ) { + if ( isFunction( html ) ) { + html = html.call( this[ 0 ] ); + } + + // The elements to wrap the target around + wrap = jQuery( html, this[ 0 ].ownerDocument ).eq( 0 ).clone( true ); + + if ( this[ 0 ].parentNode ) { + wrap.insertBefore( this[ 0 ] ); + } + + wrap.map( function() { + var elem = this; + + while ( elem.firstElementChild ) { + elem = elem.firstElementChild; + } + + return elem; + } ).append( this ); + } + + return this; + }, + + wrapInner: function( html ) { + if ( isFunction( html ) ) { + return this.each( function( i ) { + jQuery( this ).wrapInner( html.call( this, i ) ); + } ); + } + + return this.each( function() { + var self = jQuery( this ), + contents = self.contents(); + + if ( contents.length ) { + contents.wrapAll( html ); + + } else { + self.append( html ); + } + } ); + }, + + wrap: function( html ) { + var htmlIsFunction = isFunction( html ); + + return this.each( function( i ) { + jQuery( this ).wrapAll( htmlIsFunction ? html.call( this, i ) : html ); + } ); + }, + + unwrap: function( selector ) { + this.parent( selector ).not( "body" ).each( function() { + jQuery( this ).replaceWith( this.childNodes ); + } ); + return this; + } +} ); + + +jQuery.expr.pseudos.hidden = function( elem ) { + return !jQuery.expr.pseudos.visible( elem ); +}; +jQuery.expr.pseudos.visible = function( elem ) { + return !!( elem.offsetWidth || elem.offsetHeight || elem.getClientRects().length ); +}; + + + + +jQuery.ajaxSettings.xhr = function() { + try { + return new window.XMLHttpRequest(); + } catch ( e ) {} +}; + +var xhrSuccessStatus = { + + // File protocol always yields status code 0, assume 200 + 0: 200, + + // Support: IE <=9 only + // #1450: sometimes IE returns 1223 when it should be 204 + 1223: 204 + }, + xhrSupported = jQuery.ajaxSettings.xhr(); + +support.cors = !!xhrSupported && ( "withCredentials" in xhrSupported ); +support.ajax = xhrSupported = !!xhrSupported; + +jQuery.ajaxTransport( function( options ) { + var callback, errorCallback; + + // Cross domain only allowed if supported through XMLHttpRequest + if ( support.cors || xhrSupported && !options.crossDomain ) { + return { + send: function( headers, complete ) { + var i, + xhr = options.xhr(); + + xhr.open( + options.type, + options.url, + options.async, + options.username, + options.password + ); + + // Apply custom fields if provided + if ( options.xhrFields ) { + for ( i in options.xhrFields ) { + xhr[ i ] = options.xhrFields[ i ]; + } + } + + // Override mime type if needed + if ( options.mimeType && xhr.overrideMimeType ) { + xhr.overrideMimeType( options.mimeType ); + } + + // X-Requested-With header + // For cross-domain requests, seeing as conditions for a preflight are + // akin to a jigsaw puzzle, we simply never set it to be sure. + // (it can always be set on a per-request basis or even using ajaxSetup) + // For same-domain requests, won't change header if already provided. + if ( !options.crossDomain && !headers[ "X-Requested-With" ] ) { + headers[ "X-Requested-With" ] = "XMLHttpRequest"; + } + + // Set headers + for ( i in headers ) { + xhr.setRequestHeader( i, headers[ i ] ); + } + + // Callback + callback = function( type ) { + return function() { + if ( callback ) { + callback = errorCallback = xhr.onload = + xhr.onerror = xhr.onabort = xhr.ontimeout = + xhr.onreadystatechange = null; + + if ( type === "abort" ) { + xhr.abort(); + } else if ( type === "error" ) { + + // Support: IE <=9 only + // On a manual native abort, IE9 throws + // errors on any property access that is not readyState + if ( typeof xhr.status !== "number" ) { + complete( 0, "error" ); + } else { + complete( + + // File: protocol always yields status 0; see #8605, #14207 + xhr.status, + xhr.statusText + ); + } + } else { + complete( + xhrSuccessStatus[ xhr.status ] || xhr.status, + xhr.statusText, + + // Support: IE <=9 only + // IE9 has no XHR2 but throws on binary (trac-11426) + // For XHR2 non-text, let the caller handle it (gh-2498) + ( xhr.responseType || "text" ) !== "text" || + typeof xhr.responseText !== "string" ? + { binary: xhr.response } : + { text: xhr.responseText }, + xhr.getAllResponseHeaders() + ); + } + } + }; + }; + + // Listen to events + xhr.onload = callback(); + errorCallback = xhr.onerror = xhr.ontimeout = callback( "error" ); + + // Support: IE 9 only + // Use onreadystatechange to replace onabort + // to handle uncaught aborts + if ( xhr.onabort !== undefined ) { + xhr.onabort = errorCallback; + } else { + xhr.onreadystatechange = function() { + + // Check readyState before timeout as it changes + if ( xhr.readyState === 4 ) { + + // Allow onerror to be called first, + // but that will not handle a native abort + // Also, save errorCallback to a variable + // as xhr.onerror cannot be accessed + window.setTimeout( function() { + if ( callback ) { + errorCallback(); + } + } ); + } + }; + } + + // Create the abort callback + callback = callback( "abort" ); + + try { + + // Do send the request (this may raise an exception) + xhr.send( options.hasContent && options.data || null ); + } catch ( e ) { + + // #14683: Only rethrow if this hasn't been notified as an error yet + if ( callback ) { + throw e; + } + } + }, + + abort: function() { + if ( callback ) { + callback(); + } + } + }; + } +} ); + + + + +// Prevent auto-execution of scripts when no explicit dataType was provided (See gh-2432) +jQuery.ajaxPrefilter( function( s ) { + if ( s.crossDomain ) { + s.contents.script = false; + } +} ); + +// Install script dataType +jQuery.ajaxSetup( { + accepts: { + script: "text/javascript, application/javascript, " + + "application/ecmascript, application/x-ecmascript" + }, + contents: { + script: /\b(?:java|ecma)script\b/ + }, + converters: { + "text script": function( text ) { + jQuery.globalEval( text ); + return text; + } + } +} ); + +// Handle cache's special case and crossDomain +jQuery.ajaxPrefilter( "script", function( s ) { + if ( s.cache === undefined ) { + s.cache = false; + } + if ( s.crossDomain ) { + s.type = "GET"; + } +} ); + +// Bind script tag hack transport +jQuery.ajaxTransport( "script", function( s ) { + + // This transport only deals with cross domain or forced-by-attrs requests + if ( s.crossDomain || s.scriptAttrs ) { + var script, callback; + return { + send: function( _, complete ) { + script = jQuery( "<script>" ) + .attr( s.scriptAttrs || {} ) + .prop( { charset: s.scriptCharset, src: s.url } ) + .on( "load error", callback = function( evt ) { + script.remove(); + callback = null; + if ( evt ) { + complete( evt.type === "error" ? 404 : 200, evt.type ); + } + } ); + + // Use native DOM manipulation to avoid our domManip AJAX trickery + document.head.appendChild( script[ 0 ] ); + }, + abort: function() { + if ( callback ) { + callback(); + } + } + }; + } +} ); + + + + +var oldCallbacks = [], + rjsonp = /(=)\?(?=&|$)|\?\?/; + +// Default jsonp settings +jQuery.ajaxSetup( { + jsonp: "callback", + jsonpCallback: function() { + var callback = oldCallbacks.pop() || ( jQuery.expando + "_" + ( nonce.guid++ ) ); + this[ callback ] = true; + return callback; + } +} ); + +// Detect, normalize options and install callbacks for jsonp requests +jQuery.ajaxPrefilter( "json jsonp", function( s, originalSettings, jqXHR ) { + + var callbackName, overwritten, responseContainer, + jsonProp = s.jsonp !== false && ( rjsonp.test( s.url ) ? + "url" : + typeof s.data === "string" && + ( s.contentType || "" ) + .indexOf( "application/x-www-form-urlencoded" ) === 0 && + rjsonp.test( s.data ) && "data" + ); + + // Handle iff the expected data type is "jsonp" or we have a parameter to set + if ( jsonProp || s.dataTypes[ 0 ] === "jsonp" ) { + + // Get callback name, remembering preexisting value associated with it + callbackName = s.jsonpCallback = isFunction( s.jsonpCallback ) ? + s.jsonpCallback() : + s.jsonpCallback; + + // Insert callback into url or form data + if ( jsonProp ) { + s[ jsonProp ] = s[ jsonProp ].replace( rjsonp, "$1" + callbackName ); + } else if ( s.jsonp !== false ) { + s.url += ( rquery.test( s.url ) ? "&" : "?" ) + s.jsonp + "=" + callbackName; + } + + // Use data converter to retrieve json after script execution + s.converters[ "script json" ] = function() { + if ( !responseContainer ) { + jQuery.error( callbackName + " was not called" ); + } + return responseContainer[ 0 ]; + }; + + // Force json dataType + s.dataTypes[ 0 ] = "json"; + + // Install callback + overwritten = window[ callbackName ]; + window[ callbackName ] = function() { + responseContainer = arguments; + }; + + // Clean-up function (fires after converters) + jqXHR.always( function() { + + // If previous value didn't exist - remove it + if ( overwritten === undefined ) { + jQuery( window ).removeProp( callbackName ); + + // Otherwise restore preexisting value + } else { + window[ callbackName ] = overwritten; + } + + // Save back as free + if ( s[ callbackName ] ) { + + // Make sure that re-using the options doesn't screw things around + s.jsonpCallback = originalSettings.jsonpCallback; + + // Save the callback name for future use + oldCallbacks.push( callbackName ); + } + + // Call if it was a function and we have a response + if ( responseContainer && isFunction( overwritten ) ) { + overwritten( responseContainer[ 0 ] ); + } + + responseContainer = overwritten = undefined; + } ); + + // Delegate to script + return "script"; + } +} ); + + + + +// Support: Safari 8 only +// In Safari 8 documents created via document.implementation.createHTMLDocument +// collapse sibling forms: the second one becomes a child of the first one. +// Because of that, this security measure has to be disabled in Safari 8. +// https://bugs.webkit.org/show_bug.cgi?id=137337 +support.createHTMLDocument = ( function() { + var body = document.implementation.createHTMLDocument( "" ).body; + body.innerHTML = "<form></form><form></form>"; + return body.childNodes.length === 2; +} )(); + + +// Argument "data" should be string of html +// context (optional): If specified, the fragment will be created in this context, +// defaults to document +// keepScripts (optional): If true, will include scripts passed in the html string +jQuery.parseHTML = function( data, context, keepScripts ) { + if ( typeof data !== "string" ) { + return []; + } + if ( typeof context === "boolean" ) { + keepScripts = context; + context = false; + } + + var base, parsed, scripts; + + if ( !context ) { + + // Stop scripts or inline event handlers from being executed immediately + // by using document.implementation + if ( support.createHTMLDocument ) { + context = document.implementation.createHTMLDocument( "" ); + + // Set the base href for the created document + // so any parsed elements with URLs + // are based on the document's URL (gh-2965) + base = context.createElement( "base" ); + base.href = document.location.href; + context.head.appendChild( base ); + } else { + context = document; + } + } + + parsed = rsingleTag.exec( data ); + scripts = !keepScripts && []; + + // Single tag + if ( parsed ) { + return [ context.createElement( parsed[ 1 ] ) ]; + } + + parsed = buildFragment( [ data ], context, scripts ); + + if ( scripts && scripts.length ) { + jQuery( scripts ).remove(); + } + + return jQuery.merge( [], parsed.childNodes ); +}; + + +/** + * Load a url into a page + */ +jQuery.fn.load = function( url, params, callback ) { + var selector, type, response, + self = this, + off = url.indexOf( " " ); + + if ( off > -1 ) { + selector = stripAndCollapse( url.slice( off ) ); + url = url.slice( 0, off ); + } + + // If it's a function + if ( isFunction( params ) ) { + + // We assume that it's the callback + callback = params; + params = undefined; + + // Otherwise, build a param string + } else if ( params && typeof params === "object" ) { + type = "POST"; + } + + // If we have elements to modify, make the request + if ( self.length > 0 ) { + jQuery.ajax( { + url: url, + + // If "type" variable is undefined, then "GET" method will be used. + // Make value of this field explicit since + // user can override it through ajaxSetup method + type: type || "GET", + dataType: "html", + data: params + } ).done( function( responseText ) { + + // Save response for use in complete callback + response = arguments; + + self.html( selector ? + + // If a selector was specified, locate the right elements in a dummy div + // Exclude scripts to avoid IE 'Permission Denied' errors + jQuery( "<div>" ).append( jQuery.parseHTML( responseText ) ).find( selector ) : + + // Otherwise use the full result + responseText ); + + // If the request succeeds, this function gets "data", "status", "jqXHR" + // but they are ignored because response was set above. + // If it fails, this function gets "jqXHR", "status", "error" + } ).always( callback && function( jqXHR, status ) { + self.each( function() { + callback.apply( this, response || [ jqXHR.responseText, status, jqXHR ] ); + } ); + } ); + } + + return this; +}; + + + + +jQuery.expr.pseudos.animated = function( elem ) { + return jQuery.grep( jQuery.timers, function( fn ) { + return elem === fn.elem; + } ).length; +}; + + + + +jQuery.offset = { + setOffset: function( elem, options, i ) { + var curPosition, curLeft, curCSSTop, curTop, curOffset, curCSSLeft, calculatePosition, + position = jQuery.css( elem, "position" ), + curElem = jQuery( elem ), + props = {}; + + // Set position first, in-case top/left are set even on static elem + if ( position === "static" ) { + elem.style.position = "relative"; + } + + curOffset = curElem.offset(); + curCSSTop = jQuery.css( elem, "top" ); + curCSSLeft = jQuery.css( elem, "left" ); + calculatePosition = ( position === "absolute" || position === "fixed" ) && + ( curCSSTop + curCSSLeft ).indexOf( "auto" ) > -1; + + // Need to be able to calculate position if either + // top or left is auto and position is either absolute or fixed + if ( calculatePosition ) { + curPosition = curElem.position(); + curTop = curPosition.top; + curLeft = curPosition.left; + + } else { + curTop = parseFloat( curCSSTop ) || 0; + curLeft = parseFloat( curCSSLeft ) || 0; + } + + if ( isFunction( options ) ) { + + // Use jQuery.extend here to allow modification of coordinates argument (gh-1848) + options = options.call( elem, i, jQuery.extend( {}, curOffset ) ); + } + + if ( options.top != null ) { + props.top = ( options.top - curOffset.top ) + curTop; + } + if ( options.left != null ) { + props.left = ( options.left - curOffset.left ) + curLeft; + } + + if ( "using" in options ) { + options.using.call( elem, props ); + + } else { + if ( typeof props.top === "number" ) { + props.top += "px"; + } + if ( typeof props.left === "number" ) { + props.left += "px"; + } + curElem.css( props ); + } + } +}; + +jQuery.fn.extend( { + + // offset() relates an element's border box to the document origin + offset: function( options ) { + + // Preserve chaining for setter + if ( arguments.length ) { + return options === undefined ? + this : + this.each( function( i ) { + jQuery.offset.setOffset( this, options, i ); + } ); + } + + var rect, win, + elem = this[ 0 ]; + + if ( !elem ) { + return; + } + + // Return zeros for disconnected and hidden (display: none) elements (gh-2310) + // Support: IE <=11 only + // Running getBoundingClientRect on a + // disconnected node in IE throws an error + if ( !elem.getClientRects().length ) { + return { top: 0, left: 0 }; + } + + // Get document-relative position by adding viewport scroll to viewport-relative gBCR + rect = elem.getBoundingClientRect(); + win = elem.ownerDocument.defaultView; + return { + top: rect.top + win.pageYOffset, + left: rect.left + win.pageXOffset + }; + }, + + // position() relates an element's margin box to its offset parent's padding box + // This corresponds to the behavior of CSS absolute positioning + position: function() { + if ( !this[ 0 ] ) { + return; + } + + var offsetParent, offset, doc, + elem = this[ 0 ], + parentOffset = { top: 0, left: 0 }; + + // position:fixed elements are offset from the viewport, which itself always has zero offset + if ( jQuery.css( elem, "position" ) === "fixed" ) { + + // Assume position:fixed implies availability of getBoundingClientRect + offset = elem.getBoundingClientRect(); + + } else { + offset = this.offset(); + + // Account for the *real* offset parent, which can be the document or its root element + // when a statically positioned element is identified + doc = elem.ownerDocument; + offsetParent = elem.offsetParent || doc.documentElement; + while ( offsetParent && + ( offsetParent === doc.body || offsetParent === doc.documentElement ) && + jQuery.css( offsetParent, "position" ) === "static" ) { + + offsetParent = offsetParent.parentNode; + } + if ( offsetParent && offsetParent !== elem && offsetParent.nodeType === 1 ) { + + // Incorporate borders into its offset, since they are outside its content origin + parentOffset = jQuery( offsetParent ).offset(); + parentOffset.top += jQuery.css( offsetParent, "borderTopWidth", true ); + parentOffset.left += jQuery.css( offsetParent, "borderLeftWidth", true ); + } + } + + // Subtract parent offsets and element margins + return { + top: offset.top - parentOffset.top - jQuery.css( elem, "marginTop", true ), + left: offset.left - parentOffset.left - jQuery.css( elem, "marginLeft", true ) + }; + }, + + // This method will return documentElement in the following cases: + // 1) For the element inside the iframe without offsetParent, this method will return + // documentElement of the parent window + // 2) For the hidden or detached element + // 3) For body or html element, i.e. in case of the html node - it will return itself + // + // but those exceptions were never presented as a real life use-cases + // and might be considered as more preferable results. + // + // This logic, however, is not guaranteed and can change at any point in the future + offsetParent: function() { + return this.map( function() { + var offsetParent = this.offsetParent; + + while ( offsetParent && jQuery.css( offsetParent, "position" ) === "static" ) { + offsetParent = offsetParent.offsetParent; + } + + return offsetParent || documentElement; + } ); + } +} ); + +// Create scrollLeft and scrollTop methods +jQuery.each( { scrollLeft: "pageXOffset", scrollTop: "pageYOffset" }, function( method, prop ) { + var top = "pageYOffset" === prop; + + jQuery.fn[ method ] = function( val ) { + return access( this, function( elem, method, val ) { + + // Coalesce documents and windows + var win; + if ( isWindow( elem ) ) { + win = elem; + } else if ( elem.nodeType === 9 ) { + win = elem.defaultView; + } + + if ( val === undefined ) { + return win ? win[ prop ] : elem[ method ]; + } + + if ( win ) { + win.scrollTo( + !top ? val : win.pageXOffset, + top ? val : win.pageYOffset + ); + + } else { + elem[ method ] = val; + } + }, method, val, arguments.length ); + }; +} ); + +// Support: Safari <=7 - 9.1, Chrome <=37 - 49 +// Add the top/left cssHooks using jQuery.fn.position +// Webkit bug: https://bugs.webkit.org/show_bug.cgi?id=29084 +// Blink bug: https://bugs.chromium.org/p/chromium/issues/detail?id=589347 +// getComputedStyle returns percent when specified for top/left/bottom/right; +// rather than make the css module depend on the offset module, just check for it here +jQuery.each( [ "top", "left" ], function( _i, prop ) { + jQuery.cssHooks[ prop ] = addGetHookIf( support.pixelPosition, + function( elem, computed ) { + if ( computed ) { + computed = curCSS( elem, prop ); + + // If curCSS returns percentage, fallback to offset + return rnumnonpx.test( computed ) ? + jQuery( elem ).position()[ prop ] + "px" : + computed; + } + } + ); +} ); + + +// Create innerHeight, innerWidth, height, width, outerHeight and outerWidth methods +jQuery.each( { Height: "height", Width: "width" }, function( name, type ) { + jQuery.each( { padding: "inner" + name, content: type, "": "outer" + name }, + function( defaultExtra, funcName ) { + + // Margin is only for outerHeight, outerWidth + jQuery.fn[ funcName ] = function( margin, value ) { + var chainable = arguments.length && ( defaultExtra || typeof margin !== "boolean" ), + extra = defaultExtra || ( margin === true || value === true ? "margin" : "border" ); + + return access( this, function( elem, type, value ) { + var doc; + + if ( isWindow( elem ) ) { + + // $( window ).outerWidth/Height return w/h including scrollbars (gh-1729) + return funcName.indexOf( "outer" ) === 0 ? + elem[ "inner" + name ] : + elem.document.documentElement[ "client" + name ]; + } + + // Get document width or height + if ( elem.nodeType === 9 ) { + doc = elem.documentElement; + + // Either scroll[Width/Height] or offset[Width/Height] or client[Width/Height], + // whichever is greatest + return Math.max( + elem.body[ "scroll" + name ], doc[ "scroll" + name ], + elem.body[ "offset" + name ], doc[ "offset" + name ], + doc[ "client" + name ] + ); + } + + return value === undefined ? + + // Get width or height on the element, requesting but not forcing parseFloat + jQuery.css( elem, type, extra ) : + + // Set width or height on the element + jQuery.style( elem, type, value, extra ); + }, type, chainable ? margin : undefined, chainable ); + }; + } ); +} ); + + +jQuery.each( [ + "ajaxStart", + "ajaxStop", + "ajaxComplete", + "ajaxError", + "ajaxSuccess", + "ajaxSend" +], function( _i, type ) { + jQuery.fn[ type ] = function( fn ) { + return this.on( type, fn ); + }; +} ); + + + + +jQuery.fn.extend( { + + bind: function( types, data, fn ) { + return this.on( types, null, data, fn ); + }, + unbind: function( types, fn ) { + return this.off( types, null, fn ); + }, + + delegate: function( selector, types, data, fn ) { + return this.on( types, selector, data, fn ); + }, + undelegate: function( selector, types, fn ) { + + // ( namespace ) or ( selector, types [, fn] ) + return arguments.length === 1 ? + this.off( selector, "**" ) : + this.off( types, selector || "**", fn ); + }, + + hover: function( fnOver, fnOut ) { + return this.mouseenter( fnOver ).mouseleave( fnOut || fnOver ); + } +} ); + +jQuery.each( ( "blur focus focusin focusout resize scroll click dblclick " + + "mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave " + + "change select submit keydown keypress keyup contextmenu" ).split( " " ), + function( _i, name ) { + + // Handle event binding + jQuery.fn[ name ] = function( data, fn ) { + return arguments.length > 0 ? + this.on( name, null, data, fn ) : + this.trigger( name ); + }; + } ); + + + + +// Support: Android <=4.0 only +// Make sure we trim BOM and NBSP +var rtrim = /^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g; + +// Bind a function to a context, optionally partially applying any +// arguments. +// jQuery.proxy is deprecated to promote standards (specifically Function#bind) +// However, it is not slated for removal any time soon +jQuery.proxy = function( fn, context ) { + var tmp, args, proxy; + + if ( typeof context === "string" ) { + tmp = fn[ context ]; + context = fn; + fn = tmp; + } + + // Quick check to determine if target is callable, in the spec + // this throws a TypeError, but we will just return undefined. + if ( !isFunction( fn ) ) { + return undefined; + } + + // Simulated bind + args = slice.call( arguments, 2 ); + proxy = function() { + return fn.apply( context || this, args.concat( slice.call( arguments ) ) ); + }; + + // Set the guid of unique handler to the same of original handler, so it can be removed + proxy.guid = fn.guid = fn.guid || jQuery.guid++; + + return proxy; +}; + +jQuery.holdReady = function( hold ) { + if ( hold ) { + jQuery.readyWait++; + } else { + jQuery.ready( true ); + } +}; +jQuery.isArray = Array.isArray; +jQuery.parseJSON = JSON.parse; +jQuery.nodeName = nodeName; +jQuery.isFunction = isFunction; +jQuery.isWindow = isWindow; +jQuery.camelCase = camelCase; +jQuery.type = toType; + +jQuery.now = Date.now; + +jQuery.isNumeric = function( obj ) { + + // As of jQuery 3.0, isNumeric is limited to + // strings and numbers (primitives or objects) + // that can be coerced to finite numbers (gh-2662) + var type = jQuery.type( obj ); + return ( type === "number" || type === "string" ) && + + // parseFloat NaNs numeric-cast false positives ("") + // ...but misinterprets leading-number strings, particularly hex literals ("0x...") + // subtraction forces infinities to NaN + !isNaN( obj - parseFloat( obj ) ); +}; + +jQuery.trim = function( text ) { + return text == null ? + "" : + ( text + "" ).replace( rtrim, "" ); +}; + + + +// Register as a named AMD module, since jQuery can be concatenated with other +// files that may use define, but not via a proper concatenation script that +// understands anonymous AMD modules. A named AMD is safest and most robust +// way to register. Lowercase jquery is used because AMD module names are +// derived from file names, and jQuery is normally delivered in a lowercase +// file name. Do this after creating the global so that if an AMD module wants +// to call noConflict to hide this version of jQuery, it will work. + +// Note that for maximum portability, libraries that are not jQuery should +// declare themselves as anonymous modules, and avoid setting a global if an +// AMD loader is present. jQuery is a special case. For more information, see +// https://github.com/jrburke/requirejs/wiki/Updating-existing-libraries#wiki-anon + +if ( typeof define === "function" && define.amd ) { + define( "jquery", [], function() { + return jQuery; + } ); +} + + + + +var + + // Map over jQuery in case of overwrite + _jQuery = window.jQuery, + + // Map over the $ in case of overwrite + _$ = window.$; + +jQuery.noConflict = function( deep ) { + if ( window.$ === jQuery ) { + window.$ = _$; + } + + if ( deep && window.jQuery === jQuery ) { + window.jQuery = _jQuery; + } + + return jQuery; +}; + +// Expose jQuery and $ identifiers, even in AMD +// (#7102#comment:10, https://github.com/jquery/jquery/pull/557) +// and CommonJS for browser emulators (#13566) +if ( typeof noGlobal === "undefined" ) { + window.jQuery = window.$ = jQuery; +} + + + + +return jQuery; +} ); diff --git a/guide/_static/jquery.js b/guide/_static/jquery.js new file mode 100644 index 0000000..b061403 --- /dev/null +++ b/guide/_static/jquery.js @@ -0,0 +1,2 @@ +/*! jQuery v3.5.1 | (c) JS Foundation and other contributors | jquery.org/license */ +!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],r=Object.getPrototypeOf,s=t.slice,g=t.flat?function(e){return t.flat.call(e)}:function(e){return t.concat.apply([],e)},u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType},x=function(e){return null!=e&&e===e.window},E=C.document,c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.5.1",S=function(e,t){return new S.fn.init(e,t)};function p(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0<t&&t-1 in e)}S.fn=S.prototype={jquery:f,constructor:S,length:0,toArray:function(){return s.call(this)},get:function(e){return null==e?s.call(this):e<0?this[e+this.length]:this[e]},pushStack:function(e){var t=S.merge(this.constructor(),e);return t.prevObject=this,t},each:function(e){return S.each(this,e)},map:function(n){return this.pushStack(S.map(this,function(e,t){return n.call(e,t,e)}))},slice:function(){return this.pushStack(s.apply(this,arguments))},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},even:function(){return this.pushStack(S.grep(this,function(e,t){return(t+1)%2}))},odd:function(){return this.pushStack(S.grep(this,function(e,t){return t%2}))},eq:function(e){var t=this.length,n=+e+(e<0?t:0);return this.pushStack(0<=n&&n<t?[this[n]]:[])},end:function(){return this.prevObject||this.constructor()},push:u,sort:t.sort,splice:t.splice},S.extend=S.fn.extend=function(){var e,t,n,r,i,o,a=arguments[0]||{},s=1,u=arguments.length,l=!1;for("boolean"==typeof a&&(l=a,a=arguments[s]||{},s++),"object"==typeof a||m(a)||(a={}),s===u&&(a=this,s--);s<u;s++)if(null!=(e=arguments[s]))for(t in e)r=e[t],"__proto__"!==t&&a!==r&&(l&&r&&(S.isPlainObject(r)||(i=Array.isArray(r)))?(n=a[t],o=i&&!Array.isArray(n)?[]:i||S.isPlainObject(n)?n:{},i=!1,a[t]=S.extend(l,o,r)):void 0!==r&&(a[t]=r));return a},S.extend({expando:"jQuery"+(f+Math.random()).replace(/\D/g,""),isReady:!0,error:function(e){throw new Error(e)},noop:function(){},isPlainObject:function(e){var t,n;return!(!e||"[object Object]"!==o.call(e))&&(!(t=r(e))||"function"==typeof(n=v.call(t,"constructor")&&t.constructor)&&a.call(n)===l)},isEmptyObject:function(e){var t;for(t in e)return!1;return!0},globalEval:function(e,t,n){b(e,{nonce:t&&t.nonce},n)},each:function(e,t){var n,r=0;if(p(e)){for(n=e.length;r<n;r++)if(!1===t.call(e[r],r,e[r]))break}else for(r in e)if(!1===t.call(e[r],r,e[r]))break;return e},makeArray:function(e,t){var n=t||[];return null!=e&&(p(Object(e))?S.merge(n,"string"==typeof e?[e]:e):u.call(n,e)),n},inArray:function(e,t,n){return null==t?-1:i.call(t,e,n)},merge:function(e,t){for(var n=+t.length,r=0,i=e.length;r<n;r++)e[i++]=t[r];return e.length=i,e},grep:function(e,t,n){for(var r=[],i=0,o=e.length,a=!n;i<o;i++)!t(e[i],i)!==a&&r.push(e[i]);return r},map:function(e,t,n){var r,i,o=0,a=[];if(p(e))for(r=e.length;o<r;o++)null!=(i=t(e[o],o,n))&&a.push(i);else for(o in e)null!=(i=t(e[o],o,n))&&a.push(i);return g(a)},guid:1,support:y}),"function"==typeof Symbol&&(S.fn[Symbol.iterator]=t[Symbol.iterator]),S.each("Boolean Number String Function Array Date RegExp Object Error Symbol".split(" "),function(e,t){n["[object "+t+"]"]=t.toLowerCase()});var d=function(n){var e,d,b,o,i,h,f,g,w,u,l,T,C,a,E,v,s,c,y,S="sizzle"+1*new Date,p=n.document,k=0,r=0,m=ue(),x=ue(),A=ue(),N=ue(),D=function(e,t){return e===t&&(l=!0),0},j={}.hasOwnProperty,t=[],q=t.pop,L=t.push,H=t.push,O=t.slice,P=function(e,t){for(var n=0,r=e.length;n<r;n++)if(e[n]===t)return n;return-1},R="checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|ismap|loop|multiple|open|readonly|required|scoped",M="[\\x20\\t\\r\\n\\f]",I="(?:\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\[^\\r\\n\\f]|[\\w-]|[^\0-\\x7f])+",W="\\["+M+"*("+I+")(?:"+M+"*([*^$|!~]?=)"+M+"*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|("+I+"))|)"+M+"*\\]",F=":("+I+")(?:\\((('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|((?:\\\\.|[^\\\\()[\\]]|"+W+")*)|.*)\\)|)",B=new RegExp(M+"+","g"),$=new RegExp("^"+M+"+|((?:^|[^\\\\])(?:\\\\.)*)"+M+"+$","g"),_=new RegExp("^"+M+"*,"+M+"*"),z=new RegExp("^"+M+"*([>+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\([^\\r\\n\\f])","g"),ne=function(e,t){var n="0x"+e.slice(1)-65536;return t||(n<0?String.fromCharCode(n+65536):String.fromCharCode(n>>10|55296,1023&n|56320))},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(p.childNodes),p.childNodes),t[p.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&(T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!N[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&(U.test(t)||z.test(t))){(f=ee.test(t)&&ye(e.parentNode)||e)===e&&d.scope||((s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=S)),o=(l=h(t)).length;while(o--)l[o]=(s?"#"+s:":scope")+" "+xe(l[o]);c=l.join(",")}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){N(t,!0)}finally{s===S&&e.removeAttribute("id")}}}return g(t.replace($,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[S]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e.namespaceURI,n=(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:p;return r!=C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),p!=C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.scope=ce(function(e){return a.appendChild(e).appendChild(C.createElement("div")),"undefined"!=typeof e.querySelectorAll&&!e.querySelectorAll(":scope fieldset div").length}),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=S,!C.getElementsByName||!C.getElementsByName(S).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){var t;a.appendChild(e).innerHTML="<a id='"+S+"'></a><select id='"+S+"-\r\\' msallowcapture=''><option selected=''></option></select>",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+S+"-]").length||v.push("~="),(t=C.createElement("input")).setAttribute("name",""),e.appendChild(t),e.querySelectorAll("[name='']").length||v.push("\\["+M+"*name"+M+"*="+M+"*(?:''|\"\")"),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+S+"+*").length||v.push(".#.+[+~]"),e.querySelectorAll("\\\f"),v.push("[\\r\\n\\f]")}),ce(function(e){e.innerHTML="<a href='' disabled='disabled'></a><select disabled='disabled'><option/></select>";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",F)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},D=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)==(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e==C||e.ownerDocument==p&&y(p,e)?-1:t==C||t.ownerDocument==p&&y(p,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e==C?-1:t==C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]==p?-1:s[r]==p?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if(T(e),d.matchesSelector&&E&&!N[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){N(t,!0)}return 0<se(t,C,null,[e]).length},se.contains=function(e,t){return(e.ownerDocument||e)!=C&&T(e),y(e,t)},se.attr=function(e,t){(e.ownerDocument||e)!=C&&T(e);var n=b.attrHandle[t.toLowerCase()],r=n&&j.call(b.attrHandle,t.toLowerCase())?n(e,t,!E):void 0;return void 0!==r?r:d.attributes||!E?e.getAttribute(t):(r=e.getAttributeNode(t))&&r.specified?r.value:null},se.escape=function(e){return(e+"").replace(re,ie)},se.error=function(e){throw new Error("Syntax error, unrecognized expression: "+e)},se.uniqueSort=function(e){var t,n=[],r=0,i=0;if(l=!d.detectDuplicates,u=!d.sortStable&&e.slice(0),e.sort(D),l){while(t=e[i++])t===e[i]&&(r=n.push(i));while(r--)e.splice(n[r],1)}return u=null,e},o=se.getText=function(e){var t,n="",r=0,i=e.nodeType;if(i){if(1===i||9===i||11===i){if("string"==typeof e.textContent)return e.textContent;for(e=e.firstChild;e;e=e.nextSibling)n+=o(e)}else if(3===i||4===i)return e.nodeValue}else while(t=e[r++])n+=o(t);return n},(b=se.selectors={cacheLength:50,createPseudo:le,match:G,attrHandle:{},find:{},relative:{">":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=m[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&m(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1<t.indexOf(i):"$="===r?i&&t.slice(-i.length)===i:"~="===r?-1<(" "+t.replace(B," ")+" ").indexOf(i):"|="===r&&(t===i||t.slice(0,i.length+1)===i+"-"))}},CHILD:function(h,e,t,g,v){var y="nth"!==h.slice(0,3),m="last"!==h.slice(-4),x="of-type"===e;return 1===g&&0===v?function(e){return!!e.parentNode}:function(e,t,n){var r,i,o,a,s,u,l=y!==m?"nextSibling":"previousSibling",c=e.parentNode,f=x&&e.nodeName.toLowerCase(),p=!n&&!x,d=!1;if(c){if(y){while(l){a=e;while(a=a[l])if(x?a.nodeName.toLowerCase()===f:1===a.nodeType)return!1;u=l="only"===h&&!u&&"nextSibling"}return!0}if(u=[m?c.firstChild:c.lastChild],m&&p){d=(s=(r=(i=(o=(a=c)[S]||(a[S]={}))[a.uniqueID]||(o[a.uniqueID]={}))[h]||[])[0]===k&&r[1])&&r[2],a=s&&c.childNodes[s];while(a=++s&&a&&a[l]||(d=s=0)||u.pop())if(1===a.nodeType&&++d&&a===e){i[h]=[k,s,d];break}}else if(p&&(d=s=(r=(i=(o=(a=e)[S]||(a[S]={}))[a.uniqueID]||(o[a.uniqueID]={}))[h]||[])[0]===k&&r[1]),!1===d)while(a=++s&&a&&a[l]||(d=s=0)||u.pop())if((x?a.nodeName.toLowerCase()===f:1===a.nodeType)&&++d&&(p&&((i=(o=a[S]||(a[S]={}))[a.uniqueID]||(o[a.uniqueID]={}))[h]=[k,d]),a===e))break;return(d-=v)===g||d%g==0&&0<=d/g}}},PSEUDO:function(e,o){var t,a=b.pseudos[e]||b.setFilters[e.toLowerCase()]||se.error("unsupported pseudo: "+e);return a[S]?a(o):1<a.length?(t=[e,e,"",o],b.setFilters.hasOwnProperty(e.toLowerCase())?le(function(e,t){var n,r=a(e,o),i=r.length;while(i--)e[n=P(e,r[i])]=!(t[n]=r[i])}):function(e){return a(e,0,t)}):a}},pseudos:{not:le(function(e){var r=[],i=[],s=f(e.replace($,"$1"));return s[S]?le(function(e,t,n,r){var i,o=s(e,null,r,[]),a=e.length;while(a--)(i=o[a])&&(e[a]=!(t[a]=i))}):function(e,t,n){return r[0]=e,s(r,null,n,i),r[0]=null,!i.pop()}}),has:le(function(t){return function(e){return 0<se(t,e).length}}),contains:le(function(t){return t=t.replace(te,ne),function(e){return-1<(e.textContent||o(e)).indexOf(t)}}),lang:le(function(n){return V.test(n||"")||se.error("unsupported lang: "+n),n=n.replace(te,ne).toLowerCase(),function(e){var t;do{if(t=E?e.lang:e.getAttribute("xml:lang")||e.getAttribute("lang"))return(t=t.toLowerCase())===n||0===t.indexOf(n+"-")}while((e=e.parentNode)&&1===e.nodeType);return!1}}),target:function(e){var t=n.location&&n.location.hash;return t&&t.slice(1)===e.id},root:function(e){return e===a},focus:function(e){return e===C.activeElement&&(!C.hasFocus||C.hasFocus())&&!!(e.type||e.href||~e.tabIndex)},enabled:ge(!1),disabled:ge(!0),checked:function(e){var t=e.nodeName.toLowerCase();return"input"===t&&!!e.checked||"option"===t&&!!e.selected},selected:function(e){return e.parentNode&&e.parentNode.selectedIndex,!0===e.selected},empty:function(e){for(e=e.firstChild;e;e=e.nextSibling)if(e.nodeType<6)return!1;return!0},parent:function(e){return!b.pseudos.empty(e)},header:function(e){return J.test(e.nodeName)},input:function(e){return Q.test(e.nodeName)},button:function(e){var t=e.nodeName.toLowerCase();return"input"===t&&"button"===e.type||"button"===t},text:function(e){var t;return"input"===e.nodeName.toLowerCase()&&"text"===e.type&&(null==(t=e.getAttribute("type"))||"text"===t.toLowerCase())},first:ve(function(){return[0]}),last:ve(function(e,t){return[t-1]}),eq:ve(function(e,t,n){return[n<0?n+t:n]}),even:ve(function(e,t){for(var n=0;n<t;n+=2)e.push(n);return e}),odd:ve(function(e,t){for(var n=1;n<t;n+=2)e.push(n);return e}),lt:ve(function(e,t,n){for(var r=n<0?n+t:t<n?t:n;0<=--r;)e.push(r);return e}),gt:ve(function(e,t,n){for(var r=n<0?n+t:n;++r<t;)e.push(r);return e})}}).pseudos.nth=b.pseudos.eq,{radio:!0,checkbox:!0,file:!0,password:!0,image:!0})b.pseudos[e]=de(e);for(e in{submit:!0,reset:!0})b.pseudos[e]=he(e);function me(){}function xe(e){for(var t=0,n=e.length,r="";t<n;t++)r+=e[t].value;return r}function be(s,e,t){var u=e.dir,l=e.next,c=l||u,f=t&&"parentNode"===c,p=r++;return e.first?function(e,t,n){while(e=e[u])if(1===e.nodeType||f)return s(e,t,n);return!1}:function(e,t,n){var r,i,o,a=[k,p];if(n){while(e=e[u])if((1===e.nodeType||f)&&s(e,t,n))return!0}else while(e=e[u])if(1===e.nodeType||f)if(i=(o=e[S]||(e[S]={}))[e.uniqueID]||(o[e.uniqueID]={}),l&&l===e.nodeName.toLowerCase())e=e[u]||e;else{if((r=i[c])&&r[0]===k&&r[1]===p)return a[2]=r[2];if((i[c]=a)[2]=s(e,t,n))return!0}return!1}}function we(i){return 1<i.length?function(e,t,n){var r=i.length;while(r--)if(!i[r](e,t,n))return!1;return!0}:i[0]}function Te(e,t,n,r,i){for(var o,a=[],s=0,u=e.length,l=null!=t;s<u;s++)(o=e[s])&&(n&&!n(o,r,i)||(a.push(o),l&&t.push(s)));return a}function Ce(d,h,g,v,y,e){return v&&!v[S]&&(v=Ce(v)),y&&!y[S]&&(y=Ce(y,e)),le(function(e,t,n,r){var i,o,a,s=[],u=[],l=t.length,c=e||function(e,t,n){for(var r=0,i=t.length;r<i;r++)se(e,t[r],n);return n}(h||"*",n.nodeType?[n]:n,[]),f=!d||!e&&h?c:Te(c,s,d,n,r),p=g?y||(e?d:l||v)?[]:t:f;if(g&&g(f,p,n,r),v){i=Te(p,u),v(i,[],n,r),o=i.length;while(o--)(a=i[o])&&(p[u[o]]=!(f[u[o]]=a))}if(e){if(y||d){if(y){i=[],o=p.length;while(o--)(a=p[o])&&i.push(f[o]=a);y(null,p=[],i,r)}o=p.length;while(o--)(a=p[o])&&-1<(i=y?P(e,a):s[o])&&(e[i]=!(t[i]=a))}}else p=Te(p===t?p.splice(l,p.length):p),y?y(null,t,p,r):H.apply(t,p)})}function Ee(e){for(var i,t,n,r=e.length,o=b.relative[e[0].type],a=o||b.relative[" "],s=o?1:0,u=be(function(e){return e===i},a,!0),l=be(function(e){return-1<P(i,e)},a,!0),c=[function(e,t,n){var r=!o&&(n||t!==w)||((i=t).nodeType?u(e,t,n):l(e,t,n));return i=null,r}];s<r;s++)if(t=b.relative[e[s].type])c=[be(we(c),t)];else{if((t=b.filter[e[s].type].apply(null,e[s].matches))[S]){for(n=++s;n<r;n++)if(b.relative[e[n].type])break;return Ce(1<s&&we(c),1<s&&xe(e.slice(0,s-1).concat({value:" "===e[s-2].type?"*":""})).replace($,"$1"),t,s<n&&Ee(e.slice(s,n)),n<r&&Ee(e=e.slice(n)),n<r&&xe(e))}c.push(t)}return we(c)}return me.prototype=b.filters=b.pseudos,b.setFilters=new me,h=se.tokenize=function(e,t){var n,r,i,o,a,s,u,l=x[e+" "];if(l)return t?0:l.slice(0);a=e,s=[],u=b.preFilter;while(a){for(o in n&&!(r=_.exec(a))||(r&&(a=a.slice(r[0].length)||a),s.push(i=[])),n=!1,(r=z.exec(a))&&(n=r.shift(),i.push({value:n,type:r[0].replace($," ")}),a=a.slice(n.length)),b.filter)!(r=G[o].exec(a))||u[o]&&!(r=u[o](r))||(n=r.shift(),i.push({value:n,type:o,matches:r}),a=a.slice(n.length));if(!n)break}return t?a.length:a?se.error(e):x(e,s).slice(0)},f=se.compile=function(e,t){var n,v,y,m,x,r,i=[],o=[],a=A[e+" "];if(!a){t||(t=h(e)),n=t.length;while(n--)(a=Ee(t[n]))[S]?i.push(a):o.push(a);(a=A(e,(v=o,m=0<(y=i).length,x=0<v.length,r=function(e,t,n,r,i){var o,a,s,u=0,l="0",c=e&&[],f=[],p=w,d=e||x&&b.find.TAG("*",i),h=k+=null==p?1:Math.random()||.1,g=d.length;for(i&&(w=t==C||t||i);l!==g&&null!=(o=d[l]);l++){if(x&&o){a=0,t||o.ownerDocument==C||(T(o),n=!E);while(s=v[a++])if(s(o,t||C,n)){r.push(o);break}i&&(k=h)}m&&((o=!s&&o)&&u--,e&&c.push(o))}if(u+=l,m&&l!==u){a=0;while(s=y[a++])s(c,f,t,n);if(e){if(0<u)while(l--)c[l]||f[l]||(f[l]=q.call(r));f=Te(f)}H.apply(r,f),i&&!e&&0<f.length&&1<u+y.length&&se.uniqueSort(r)}return i&&(k=h,w=p),c},m?le(r):r))).selector=e}return a},g=se.select=function(e,t,n,r){var i,o,a,s,u,l="function"==typeof e&&e,c=!r&&h(e=l.selector||e);if(n=n||[],1===c.length){if(2<(o=c[0]=c[0].slice(0)).length&&"ID"===(a=o[0]).type&&9===t.nodeType&&E&&b.relative[o[1].type]){if(!(t=(b.find.ID(a.matches[0].replace(te,ne),t)||[])[0]))return n;l&&(t=t.parentNode),e=e.slice(o.shift().value.length)}i=G.needsContext.test(e)?0:o.length;while(i--){if(a=o[i],b.relative[s=a.type])break;if((u=b.find[s])&&(r=u(a.matches[0].replace(te,ne),ee.test(o[0].type)&&ye(t.parentNode)||t))){if(o.splice(i,1),!(e=r.length&&xe(o)))return H.apply(n,r),n;break}}}return(l||f(e,c))(r,t,!E,n,!t||ee.test(e)&&ye(t.parentNode)||t),n},d.sortStable=S.split("").sort(D).join("")===S,d.detectDuplicates=!!l,T(),d.sortDetached=ce(function(e){return 1&e.compareDocumentPosition(C.createElement("fieldset"))}),ce(function(e){return e.innerHTML="<a href='#'></a>","#"===e.firstChild.getAttribute("href")})||fe("type|href|height|width",function(e,t,n){if(!n)return e.getAttribute(t,"type"===t.toLowerCase()?1:2)}),d.attributes&&ce(function(e){return e.innerHTML="<input/>",e.firstChild.setAttribute("value",""),""===e.firstChild.getAttribute("value")})||fe("value",function(e,t,n){if(!n&&"input"===e.nodeName.toLowerCase())return e.defaultValue}),ce(function(e){return null==e.getAttribute("disabled")})||fe(R,function(e,t,n){var r;if(!n)return!0===e[t]?t.toLowerCase():(r=e.getAttributeNode(t))&&r.specified?r.value:null}),se}(C);S.find=d,S.expr=d.selectors,S.expr[":"]=S.expr.pseudos,S.uniqueSort=S.unique=d.uniqueSort,S.text=d.getText,S.isXMLDoc=d.isXML,S.contains=d.contains,S.escapeSelector=d.escape;var h=function(e,t,n){var r=[],i=void 0!==n;while((e=e[t])&&9!==e.nodeType)if(1===e.nodeType){if(i&&S(e).is(n))break;r.push(e)}return r},T=function(e,t){for(var n=[];e;e=e.nextSibling)1===e.nodeType&&e!==t&&n.push(e);return n},k=S.expr.match.needsContext;function A(e,t){return e.nodeName&&e.nodeName.toLowerCase()===t.toLowerCase()}var N=/^<([a-z][^\/\0>:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function D(e,n,r){return m(n)?S.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?S.grep(e,function(e){return e===n!==r}):"string"!=typeof n?S.grep(e,function(e){return-1<i.call(n,e)!==r}):S.filter(n,e,r)}S.filter=function(e,t,n){var r=t[0];return n&&(e=":not("+e+")"),1===t.length&&1===r.nodeType?S.find.matchesSelector(r,e)?[r]:[]:S.find.matches(e,S.grep(t,function(e){return 1===e.nodeType}))},S.fn.extend({find:function(e){var t,n,r=this.length,i=this;if("string"!=typeof e)return this.pushStack(S(e).filter(function(){for(t=0;t<r;t++)if(S.contains(i[t],this))return!0}));for(n=this.pushStack([]),t=0;t<r;t++)S.find(e,i[t],n);return 1<r?S.uniqueSort(n):n},filter:function(e){return this.pushStack(D(this,e||[],!1))},not:function(e){return this.pushStack(D(this,e||[],!0))},is:function(e){return!!D(this,"string"==typeof e&&k.test(e)?S(e):e||[],!1).length}});var j,q=/^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]+))$/;(S.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||j,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:q.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof S?t[0]:t,S.merge(this,S.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),N.test(r[1])&&S.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(S):S.makeArray(e,this)}).prototype=S.fn,j=S(E);var L=/^(?:parents|prev(?:Until|All))/,H={children:!0,contents:!0,next:!0,prev:!0};function O(e,t){while((e=e[t])&&1!==e.nodeType);return e}S.fn.extend({has:function(e){var t=S(e,this),n=t.length;return this.filter(function(){for(var e=0;e<n;e++)if(S.contains(this,t[e]))return!0})},closest:function(e,t){var n,r=0,i=this.length,o=[],a="string"!=typeof e&&S(e);if(!k.test(e))for(;r<i;r++)for(n=this[r];n&&n!==t;n=n.parentNode)if(n.nodeType<11&&(a?-1<a.index(n):1===n.nodeType&&S.find.matchesSelector(n,e))){o.push(n);break}return this.pushStack(1<o.length?S.uniqueSort(o):o)},index:function(e){return e?"string"==typeof e?i.call(S(e),this[0]):i.call(this,e.jquery?e[0]:e):this[0]&&this[0].parentNode?this.first().prevAll().length:-1},add:function(e,t){return this.pushStack(S.uniqueSort(S.merge(this.get(),S(e,t))))},addBack:function(e){return this.add(null==e?this.prevObject:this.prevObject.filter(e))}}),S.each({parent:function(e){var t=e.parentNode;return t&&11!==t.nodeType?t:null},parents:function(e){return h(e,"parentNode")},parentsUntil:function(e,t,n){return h(e,"parentNode",n)},next:function(e){return O(e,"nextSibling")},prev:function(e){return O(e,"previousSibling")},nextAll:function(e){return h(e,"nextSibling")},prevAll:function(e){return h(e,"previousSibling")},nextUntil:function(e,t,n){return h(e,"nextSibling",n)},prevUntil:function(e,t,n){return h(e,"previousSibling",n)},siblings:function(e){return T((e.parentNode||{}).firstChild,e)},children:function(e){return T(e.firstChild)},contents:function(e){return null!=e.contentDocument&&r(e.contentDocument)?e.contentDocument:(A(e,"template")&&(e=e.content||e),S.merge([],e.childNodes))}},function(r,i){S.fn[r]=function(e,t){var n=S.map(this,i,e);return"Until"!==r.slice(-5)&&(t=e),t&&"string"==typeof t&&(n=S.filter(t,n)),1<this.length&&(H[r]||S.uniqueSort(n),L.test(r)&&n.reverse()),this.pushStack(n)}});var P=/[^\x20\t\r\n\f]+/g;function R(e){return e}function M(e){throw e}function I(e,t,n,r){var i;try{e&&m(i=e.promise)?i.call(e).done(t).fail(n):e&&m(i=e.then)?i.call(e,t,n):t.apply(void 0,[e].slice(r))}catch(e){n.apply(void 0,[e])}}S.Callbacks=function(r){var e,n;r="string"==typeof r?(e=r,n={},S.each(e.match(P)||[],function(e,t){n[t]=!0}),n):S.extend({},r);var i,t,o,a,s=[],u=[],l=-1,c=function(){for(a=a||r.once,o=i=!0;u.length;l=-1){t=u.shift();while(++l<s.length)!1===s[l].apply(t[0],t[1])&&r.stopOnFalse&&(l=s.length,t=!1)}r.memory||(t=!1),i=!1,a&&(s=t?[]:"")},f={add:function(){return s&&(t&&!i&&(l=s.length-1,u.push(t)),function n(e){S.each(e,function(e,t){m(t)?r.unique&&f.has(t)||s.push(t):t&&t.length&&"string"!==w(t)&&n(t)})}(arguments),t&&!i&&c()),this},remove:function(){return S.each(arguments,function(e,t){var n;while(-1<(n=S.inArray(t,s,n)))s.splice(n,1),n<=l&&l--}),this},has:function(e){return e?-1<S.inArray(e,s):0<s.length},empty:function(){return s&&(s=[]),this},disable:function(){return a=u=[],s=t="",this},disabled:function(){return!s},lock:function(){return a=u=[],t||i||(s=t=""),this},locked:function(){return!!a},fireWith:function(e,t){return a||(t=[e,(t=t||[]).slice?t.slice():t],u.push(t),i||c()),this},fire:function(){return f.fireWith(this,arguments),this},fired:function(){return!!o}};return f},S.extend({Deferred:function(e){var o=[["notify","progress",S.Callbacks("memory"),S.Callbacks("memory"),2],["resolve","done",S.Callbacks("once memory"),S.Callbacks("once memory"),0,"resolved"],["reject","fail",S.Callbacks("once memory"),S.Callbacks("once memory"),1,"rejected"]],i="pending",a={state:function(){return i},always:function(){return s.done(arguments).fail(arguments),this},"catch":function(e){return a.then(null,e)},pipe:function(){var i=arguments;return S.Deferred(function(r){S.each(o,function(e,t){var n=m(i[t[4]])&&i[t[4]];s[t[1]](function(){var e=n&&n.apply(this,arguments);e&&m(e.promise)?e.promise().progress(r.notify).done(r.resolve).fail(r.reject):r[t[0]+"With"](this,n?[e]:arguments)})}),i=null}).promise()},then:function(t,n,r){var u=0;function l(i,o,a,s){return function(){var n=this,r=arguments,e=function(){var e,t;if(!(i<u)){if((e=a.apply(n,r))===o.promise())throw new TypeError("Thenable self-resolution");t=e&&("object"==typeof e||"function"==typeof e)&&e.then,m(t)?s?t.call(e,l(u,o,R,s),l(u,o,M,s)):(u++,t.call(e,l(u,o,R,s),l(u,o,M,s),l(u,o,R,o.notifyWith))):(a!==R&&(n=void 0,r=[e]),(s||o.resolveWith)(n,r))}},t=s?e:function(){try{e()}catch(e){S.Deferred.exceptionHook&&S.Deferred.exceptionHook(e,t.stackTrace),u<=i+1&&(a!==M&&(n=void 0,r=[e]),o.rejectWith(n,r))}};i?t():(S.Deferred.getStackHook&&(t.stackTrace=S.Deferred.getStackHook()),C.setTimeout(t))}}return S.Deferred(function(e){o[0][3].add(l(0,e,m(r)?r:R,e.notifyWith)),o[1][3].add(l(0,e,m(t)?t:R)),o[2][3].add(l(0,e,m(n)?n:M))}).promise()},promise:function(e){return null!=e?S.extend(e,a):a}},s={};return S.each(o,function(e,t){var n=t[2],r=t[5];a[t[1]]=n.add,r&&n.add(function(){i=r},o[3-e][2].disable,o[3-e][3].disable,o[0][2].lock,o[0][3].lock),n.add(t[3].fire),s[t[0]]=function(){return s[t[0]+"With"](this===s?void 0:this,arguments),this},s[t[0]+"With"]=n.fireWith}),a.promise(s),e&&e.call(s,s),s},when:function(e){var n=arguments.length,t=n,r=Array(t),i=s.call(arguments),o=S.Deferred(),a=function(t){return function(e){r[t]=this,i[t]=1<arguments.length?s.call(arguments):e,--n||o.resolveWith(r,i)}};if(n<=1&&(I(e,o.done(a(t)).resolve,o.reject,!n),"pending"===o.state()||m(i[t]&&i[t].then)))return o.then();while(t--)I(i[t],a(t),o.reject);return o.promise()}});var W=/^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/;S.Deferred.exceptionHook=function(e,t){C.console&&C.console.warn&&e&&W.test(e.name)&&C.console.warn("jQuery.Deferred exception: "+e.message,e.stack,t)},S.readyException=function(e){C.setTimeout(function(){throw e})};var F=S.Deferred();function B(){E.removeEventListener("DOMContentLoaded",B),C.removeEventListener("load",B),S.ready()}S.fn.ready=function(e){return F.then(e)["catch"](function(e){S.readyException(e)}),this},S.extend({isReady:!1,readyWait:1,ready:function(e){(!0===e?--S.readyWait:S.isReady)||(S.isReady=!0)!==e&&0<--S.readyWait||F.resolveWith(E,[S])}}),S.ready.then=F.then,"complete"===E.readyState||"loading"!==E.readyState&&!E.documentElement.doScroll?C.setTimeout(S.ready):(E.addEventListener("DOMContentLoaded",B),C.addEventListener("load",B));var $=function(e,t,n,r,i,o,a){var s=0,u=e.length,l=null==n;if("object"===w(n))for(s in i=!0,n)$(e,t,s,n[s],!0,o,a);else if(void 0!==r&&(i=!0,m(r)||(a=!0),l&&(a?(t.call(e,r),t=null):(l=t,t=function(e,t,n){return l.call(S(e),n)})),t))for(;s<u;s++)t(e[s],n,a?r:r.call(e[s],s,t(e[s],n)));return i?e:l?t.call(e):u?t(e[0],n):o},_=/^-ms-/,z=/-([a-z])/g;function U(e,t){return t.toUpperCase()}function X(e){return e.replace(_,"ms-").replace(z,U)}var V=function(e){return 1===e.nodeType||9===e.nodeType||!+e.nodeType};function G(){this.expando=S.expando+G.uid++}G.uid=1,G.prototype={cache:function(e){var t=e[this.expando];return t||(t={},V(e)&&(e.nodeType?e[this.expando]=t:Object.defineProperty(e,this.expando,{value:t,configurable:!0}))),t},set:function(e,t,n){var r,i=this.cache(e);if("string"==typeof t)i[X(t)]=n;else for(r in t)i[X(r)]=t[r];return i},get:function(e,t){return void 0===t?this.cache(e):e[this.expando]&&e[this.expando][X(t)]},access:function(e,t,n){return void 0===t||t&&"string"==typeof t&&void 0===n?this.get(e,t):(this.set(e,t,n),void 0!==n?n:t)},remove:function(e,t){var n,r=e[this.expando];if(void 0!==r){if(void 0!==t){n=(t=Array.isArray(t)?t.map(X):(t=X(t))in r?[t]:t.match(P)||[]).length;while(n--)delete r[t[n]]}(void 0===t||S.isEmptyObject(r))&&(e.nodeType?e[this.expando]=void 0:delete e[this.expando])}},hasData:function(e){var t=e[this.expando];return void 0!==t&&!S.isEmptyObject(t)}};var Y=new G,Q=new G,J=/^(?:\{[\w\W]*\}|\[[\w\W]*\])$/,K=/[A-Z]/g;function Z(e,t,n){var r,i;if(void 0===n&&1===e.nodeType)if(r="data-"+t.replace(K,"-$&").toLowerCase(),"string"==typeof(n=e.getAttribute(r))){try{n="true"===(i=n)||"false"!==i&&("null"===i?null:i===+i+""?+i:J.test(i)?JSON.parse(i):i)}catch(e){}Q.set(e,t,n)}else n=void 0;return n}S.extend({hasData:function(e){return Q.hasData(e)||Y.hasData(e)},data:function(e,t,n){return Q.access(e,t,n)},removeData:function(e,t){Q.remove(e,t)},_data:function(e,t,n){return Y.access(e,t,n)},_removeData:function(e,t){Y.remove(e,t)}}),S.fn.extend({data:function(n,e){var t,r,i,o=this[0],a=o&&o.attributes;if(void 0===n){if(this.length&&(i=Q.get(o),1===o.nodeType&&!Y.get(o,"hasDataAttrs"))){t=a.length;while(t--)a[t]&&0===(r=a[t].name).indexOf("data-")&&(r=X(r.slice(5)),Z(o,r,i[r]));Y.set(o,"hasDataAttrs",!0)}return i}return"object"==typeof n?this.each(function(){Q.set(this,n)}):$(this,function(e){var t;if(o&&void 0===e)return void 0!==(t=Q.get(o,n))?t:void 0!==(t=Z(o,n))?t:void 0;this.each(function(){Q.set(this,n,e)})},null,e,1<arguments.length,null,!0)},removeData:function(e){return this.each(function(){Q.remove(this,e)})}}),S.extend({queue:function(e,t,n){var r;if(e)return t=(t||"fx")+"queue",r=Y.get(e,t),n&&(!r||Array.isArray(n)?r=Y.access(e,t,S.makeArray(n)):r.push(n)),r||[]},dequeue:function(e,t){t=t||"fx";var n=S.queue(e,t),r=n.length,i=n.shift(),o=S._queueHooks(e,t);"inprogress"===i&&(i=n.shift(),r--),i&&("fx"===t&&n.unshift("inprogress"),delete o.stop,i.call(e,function(){S.dequeue(e,t)},o)),!r&&o&&o.empty.fire()},_queueHooks:function(e,t){var n=t+"queueHooks";return Y.get(e,n)||Y.access(e,n,{empty:S.Callbacks("once memory").add(function(){Y.remove(e,[t+"queue",n])})})}}),S.fn.extend({queue:function(t,n){var e=2;return"string"!=typeof t&&(n=t,t="fx",e--),arguments.length<e?S.queue(this[0],t):void 0===n?this:this.each(function(){var e=S.queue(this,t,n);S._queueHooks(this,t),"fx"===t&&"inprogress"!==e[0]&&S.dequeue(this,t)})},dequeue:function(e){return this.each(function(){S.dequeue(this,e)})},clearQueue:function(e){return this.queue(e||"fx",[])},promise:function(e,t){var n,r=1,i=S.Deferred(),o=this,a=this.length,s=function(){--r||i.resolveWith(o,[o])};"string"!=typeof e&&(t=e,e=void 0),e=e||"fx";while(a--)(n=Y.get(o[a],e+"queueHooks"))&&n.empty&&(r++,n.empty.add(s));return s(),i.promise(t)}});var ee=/[+-]?(?:\d*\.|)\d+(?:[eE][+-]?\d+|)/.source,te=new RegExp("^(?:([+-])=|)("+ee+")([a-z%]*)$","i"),ne=["Top","Right","Bottom","Left"],re=E.documentElement,ie=function(e){return S.contains(e.ownerDocument,e)},oe={composed:!0};re.getRootNode&&(ie=function(e){return S.contains(e.ownerDocument,e)||e.getRootNode(oe)===e.ownerDocument});var ae=function(e,t){return"none"===(e=t||e).style.display||""===e.style.display&&ie(e)&&"none"===S.css(e,"display")};function se(e,t,n,r){var i,o,a=20,s=r?function(){return r.cur()}:function(){return S.css(e,t,"")},u=s(),l=n&&n[3]||(S.cssNumber[t]?"":"px"),c=e.nodeType&&(S.cssNumber[t]||"px"!==l&&+u)&&te.exec(S.css(e,t));if(c&&c[3]!==l){u/=2,l=l||c[3],c=+u||1;while(a--)S.style(e,t,c+l),(1-o)*(1-(o=s()/u||.5))<=0&&(a=0),c/=o;c*=2,S.style(e,t,c+l),n=n||[]}return n&&(c=+c||+u||0,i=n[1]?c+(n[1]+1)*n[2]:+n[2],r&&(r.unit=l,r.start=c,r.end=i)),i}var ue={};function le(e,t){for(var n,r,i,o,a,s,u,l=[],c=0,f=e.length;c<f;c++)(r=e[c]).style&&(n=r.style.display,t?("none"===n&&(l[c]=Y.get(r,"display")||null,l[c]||(r.style.display="")),""===r.style.display&&ae(r)&&(l[c]=(u=a=o=void 0,a=(i=r).ownerDocument,s=i.nodeName,(u=ue[s])||(o=a.body.appendChild(a.createElement(s)),u=S.css(o,"display"),o.parentNode.removeChild(o),"none"===u&&(u="block"),ue[s]=u)))):"none"!==n&&(l[c]="none",Y.set(r,"display",n)));for(c=0;c<f;c++)null!=l[c]&&(e[c].style.display=l[c]);return e}S.fn.extend({show:function(){return le(this,!0)},hide:function(){return le(this)},toggle:function(e){return"boolean"==typeof e?e?this.show():this.hide():this.each(function(){ae(this)?S(this).show():S(this).hide()})}});var ce,fe,pe=/^(?:checkbox|radio)$/i,de=/<([a-z][^\/\0>\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i;ce=E.createDocumentFragment().appendChild(E.createElement("div")),(fe=E.createElement("input")).setAttribute("type","radio"),fe.setAttribute("checked","checked"),fe.setAttribute("name","t"),ce.appendChild(fe),y.checkClone=ce.cloneNode(!0).cloneNode(!0).lastChild.checked,ce.innerHTML="<textarea>x</textarea>",y.noCloneChecked=!!ce.cloneNode(!0).lastChild.defaultValue,ce.innerHTML="<option></option>",y.option=!!ce.lastChild;var ge={thead:[1,"<table>","</table>"],col:[2,"<table><colgroup>","</colgroup></table>"],tr:[2,"<table><tbody>","</tbody></table>"],td:[3,"<table><tbody><tr>","</tr></tbody></table>"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?S.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;n<r;n++)Y.set(e[n],"globalEval",!t||Y.get(t[n],"globalEval"))}ge.tbody=ge.tfoot=ge.colgroup=ge.caption=ge.thead,ge.th=ge.td,y.option||(ge.optgroup=ge.option=[1,"<select multiple='multiple'>","</select>"]);var me=/<|&#?\w+;/;function xe(e,t,n,r,i){for(var o,a,s,u,l,c,f=t.createDocumentFragment(),p=[],d=0,h=e.length;d<h;d++)if((o=e[d])||0===o)if("object"===w(o))S.merge(p,o.nodeType?[o]:o);else if(me.test(o)){a=a||f.appendChild(t.createElement("div")),s=(de.exec(o)||["",""])[1].toLowerCase(),u=ge[s]||ge._default,a.innerHTML=u[1]+S.htmlPrefilter(o)+u[2],c=u[0];while(c--)a=a.lastChild;S.merge(p,a.childNodes),(a=f.firstChild).textContent=""}else p.push(t.createTextNode(o));f.textContent="",d=0;while(o=p[d++])if(r&&-1<S.inArray(o,r))i&&i.push(o);else if(l=ie(o),a=ve(f.appendChild(o),"script"),l&&ye(a),n){c=0;while(o=a[c++])he.test(o.type||"")&&n.push(o)}return f}var be=/^key/,we=/^(?:mouse|pointer|contextmenu|drag|drop)|click/,Te=/^([^.]*)(?:\.(.+)|)/;function Ce(){return!0}function Ee(){return!1}function Se(e,t){return e===function(){try{return E.activeElement}catch(e){}}()==("focus"===t)}function ke(e,t,n,r,i,o){var a,s;if("object"==typeof t){for(s in"string"!=typeof n&&(r=r||n,n=void 0),t)ke(e,s,n,r,t[s],o);return e}if(null==r&&null==i?(i=n,r=n=void 0):null==i&&("string"==typeof n?(i=r,r=void 0):(i=r,r=n,n=void 0)),!1===i)i=Ee;else if(!i)return e;return 1===o&&(a=i,(i=function(e){return S().off(e),a.apply(this,arguments)}).guid=a.guid||(a.guid=S.guid++)),e.each(function(){S.event.add(this,t,i,r,n)})}function Ae(e,i,o){o?(Y.set(e,i,!1),S.event.add(e,i,{namespace:!1,handler:function(e){var t,n,r=Y.get(this,i);if(1&e.isTrigger&&this[i]){if(r.length)(S.event.special[i]||{}).delegateType&&e.stopPropagation();else if(r=s.call(arguments),Y.set(this,i,r),t=o(this,i),this[i](),r!==(n=Y.get(this,i))||t?Y.set(this,i,!1):n={},r!==n)return e.stopImmediatePropagation(),e.preventDefault(),n.value}else r.length&&(Y.set(this,i,{value:S.event.trigger(S.extend(r[0],S.Event.prototype),r.slice(1),this)}),e.stopImmediatePropagation())}})):void 0===Y.get(e,i)&&S.event.add(e,i,Ce)}S.event={global:{},add:function(t,e,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Y.get(t);if(V(t)){n.handler&&(n=(o=n).handler,i=o.selector),i&&S.find.matchesSelector(re,i),n.guid||(n.guid=S.guid++),(u=v.events)||(u=v.events=Object.create(null)),(a=v.handle)||(a=v.handle=function(e){return"undefined"!=typeof S&&S.event.triggered!==e.type?S.event.dispatch.apply(t,arguments):void 0}),l=(e=(e||"").match(P)||[""]).length;while(l--)d=g=(s=Te.exec(e[l])||[])[1],h=(s[2]||"").split(".").sort(),d&&(f=S.event.special[d]||{},d=(i?f.delegateType:f.bindType)||d,f=S.event.special[d]||{},c=S.extend({type:d,origType:g,data:r,handler:n,guid:n.guid,selector:i,needsContext:i&&S.expr.match.needsContext.test(i),namespace:h.join(".")},o),(p=u[d])||((p=u[d]=[]).delegateCount=0,f.setup&&!1!==f.setup.call(t,r,h,a)||t.addEventListener&&t.addEventListener(d,a)),f.add&&(f.add.call(t,c),c.handler.guid||(c.handler.guid=n.guid)),i?p.splice(p.delegateCount++,0,c):p.push(c),S.event.global[d]=!0)}},remove:function(e,t,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Y.hasData(e)&&Y.get(e);if(v&&(u=v.events)){l=(t=(t||"").match(P)||[""]).length;while(l--)if(d=g=(s=Te.exec(t[l])||[])[1],h=(s[2]||"").split(".").sort(),d){f=S.event.special[d]||{},p=u[d=(r?f.delegateType:f.bindType)||d]||[],s=s[2]&&new RegExp("(^|\\.)"+h.join("\\.(?:.*\\.|)")+"(\\.|$)"),a=o=p.length;while(o--)c=p[o],!i&&g!==c.origType||n&&n.guid!==c.guid||s&&!s.test(c.namespace)||r&&r!==c.selector&&("**"!==r||!c.selector)||(p.splice(o,1),c.selector&&p.delegateCount--,f.remove&&f.remove.call(e,c));a&&!p.length&&(f.teardown&&!1!==f.teardown.call(e,h,v.handle)||S.removeEvent(e,d,v.handle),delete u[d])}else for(d in u)S.event.remove(e,d+t[l],n,r,!0);S.isEmptyObject(u)&&Y.remove(e,"handle events")}},dispatch:function(e){var t,n,r,i,o,a,s=new Array(arguments.length),u=S.event.fix(e),l=(Y.get(this,"events")||Object.create(null))[u.type]||[],c=S.event.special[u.type]||{};for(s[0]=u,t=1;t<arguments.length;t++)s[t]=arguments[t];if(u.delegateTarget=this,!c.preDispatch||!1!==c.preDispatch.call(this,u)){a=S.event.handlers.call(this,u,l),t=0;while((i=a[t++])&&!u.isPropagationStopped()){u.currentTarget=i.elem,n=0;while((o=i.handlers[n++])&&!u.isImmediatePropagationStopped())u.rnamespace&&!1!==o.namespace&&!u.rnamespace.test(o.namespace)||(u.handleObj=o,u.data=o.data,void 0!==(r=((S.event.special[o.origType]||{}).handle||o.handler).apply(i.elem,s))&&!1===(u.result=r)&&(u.preventDefault(),u.stopPropagation()))}return c.postDispatch&&c.postDispatch.call(this,u),u.result}},handlers:function(e,t){var n,r,i,o,a,s=[],u=t.delegateCount,l=e.target;if(u&&l.nodeType&&!("click"===e.type&&1<=e.button))for(;l!==this;l=l.parentNode||this)if(1===l.nodeType&&("click"!==e.type||!0!==l.disabled)){for(o=[],a={},n=0;n<u;n++)void 0===a[i=(r=t[n]).selector+" "]&&(a[i]=r.needsContext?-1<S(i,this).index(l):S.find(i,this,null,[l]).length),a[i]&&o.push(r);o.length&&s.push({elem:l,handlers:o})}return l=this,u<t.length&&s.push({elem:l,handlers:t.slice(u)}),s},addProp:function(t,e){Object.defineProperty(S.Event.prototype,t,{enumerable:!0,configurable:!0,get:m(e)?function(){if(this.originalEvent)return e(this.originalEvent)}:function(){if(this.originalEvent)return this.originalEvent[t]},set:function(e){Object.defineProperty(this,t,{enumerable:!0,configurable:!0,writable:!0,value:e})}})},fix:function(e){return e[S.expando]?e:new S.Event(e)},special:{load:{noBubble:!0},click:{setup:function(e){var t=this||e;return pe.test(t.type)&&t.click&&A(t,"input")&&Ae(t,"click",Ce),!1},trigger:function(e){var t=this||e;return pe.test(t.type)&&t.click&&A(t,"input")&&Ae(t,"click"),!0},_default:function(e){var t=e.target;return pe.test(t.type)&&t.click&&A(t,"input")&&Y.get(t,"click")||A(t,"a")}},beforeunload:{postDispatch:function(e){void 0!==e.result&&e.originalEvent&&(e.originalEvent.returnValue=e.result)}}}},S.removeEvent=function(e,t,n){e.removeEventListener&&e.removeEventListener(t,n)},S.Event=function(e,t){if(!(this instanceof S.Event))return new S.Event(e,t);e&&e.type?(this.originalEvent=e,this.type=e.type,this.isDefaultPrevented=e.defaultPrevented||void 0===e.defaultPrevented&&!1===e.returnValue?Ce:Ee,this.target=e.target&&3===e.target.nodeType?e.target.parentNode:e.target,this.currentTarget=e.currentTarget,this.relatedTarget=e.relatedTarget):this.type=e,t&&S.extend(this,t),this.timeStamp=e&&e.timeStamp||Date.now(),this[S.expando]=!0},S.Event.prototype={constructor:S.Event,isDefaultPrevented:Ee,isPropagationStopped:Ee,isImmediatePropagationStopped:Ee,isSimulated:!1,preventDefault:function(){var e=this.originalEvent;this.isDefaultPrevented=Ce,e&&!this.isSimulated&&e.preventDefault()},stopPropagation:function(){var e=this.originalEvent;this.isPropagationStopped=Ce,e&&!this.isSimulated&&e.stopPropagation()},stopImmediatePropagation:function(){var e=this.originalEvent;this.isImmediatePropagationStopped=Ce,e&&!this.isSimulated&&e.stopImmediatePropagation(),this.stopPropagation()}},S.each({altKey:!0,bubbles:!0,cancelable:!0,changedTouches:!0,ctrlKey:!0,detail:!0,eventPhase:!0,metaKey:!0,pageX:!0,pageY:!0,shiftKey:!0,view:!0,"char":!0,code:!0,charCode:!0,key:!0,keyCode:!0,button:!0,buttons:!0,clientX:!0,clientY:!0,offsetX:!0,offsetY:!0,pointerId:!0,pointerType:!0,screenX:!0,screenY:!0,targetTouches:!0,toElement:!0,touches:!0,which:function(e){var t=e.button;return null==e.which&&be.test(e.type)?null!=e.charCode?e.charCode:e.keyCode:!e.which&&void 0!==t&&we.test(e.type)?1&t?1:2&t?3:4&t?2:0:e.which}},S.event.addProp),S.each({focus:"focusin",blur:"focusout"},function(e,t){S.event.special[e]={setup:function(){return Ae(this,e,Se),!1},trigger:function(){return Ae(this,e),!0},delegateType:t}}),S.each({mouseenter:"mouseover",mouseleave:"mouseout",pointerenter:"pointerover",pointerleave:"pointerout"},function(e,i){S.event.special[e]={delegateType:i,bindType:i,handle:function(e){var t,n=e.relatedTarget,r=e.handleObj;return n&&(n===this||S.contains(this,n))||(e.type=r.origType,t=r.handler.apply(this,arguments),e.type=i),t}}}),S.fn.extend({on:function(e,t,n,r){return ke(this,e,t,n,r)},one:function(e,t,n,r){return ke(this,e,t,n,r,1)},off:function(e,t,n){var r,i;if(e&&e.preventDefault&&e.handleObj)return r=e.handleObj,S(e.delegateTarget).off(r.namespace?r.origType+"."+r.namespace:r.origType,r.selector,r.handler),this;if("object"==typeof e){for(i in e)this.off(i,t,e[i]);return this}return!1!==t&&"function"!=typeof t||(n=t,t=void 0),!1===n&&(n=Ee),this.each(function(){S.event.remove(this,e,n,t)})}});var Ne=/<script|<style|<link/i,De=/checked\s*(?:[^=]|=\s*.checked.)/i,je=/^\s*<!(?:\[CDATA\[|--)|(?:\]\]|--)>\s*$/g;function qe(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&S(e).children("tbody")[0]||e}function Le(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function He(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Oe(e,t){var n,r,i,o,a,s;if(1===t.nodeType){if(Y.hasData(e)&&(s=Y.get(e).events))for(i in Y.remove(t,"handle events"),s)for(n=0,r=s[i].length;n<r;n++)S.event.add(t,i,s[i][n]);Q.hasData(e)&&(o=Q.access(e),a=S.extend({},o),Q.set(t,a))}}function Pe(n,r,i,o){r=g(r);var e,t,a,s,u,l,c=0,f=n.length,p=f-1,d=r[0],h=m(d);if(h||1<f&&"string"==typeof d&&!y.checkClone&&De.test(d))return n.each(function(e){var t=n.eq(e);h&&(r[0]=d.call(this,e,t.html())),Pe(t,r,i,o)});if(f&&(t=(e=xe(r,n[0].ownerDocument,!1,n,o)).firstChild,1===e.childNodes.length&&(e=t),t||o)){for(s=(a=S.map(ve(e,"script"),Le)).length;c<f;c++)u=e,c!==p&&(u=S.clone(u,!0,!0),s&&S.merge(a,ve(u,"script"))),i.call(n[c],u,c);if(s)for(l=a[a.length-1].ownerDocument,S.map(a,He),c=0;c<s;c++)u=a[c],he.test(u.type||"")&&!Y.access(u,"globalEval")&&S.contains(l,u)&&(u.src&&"module"!==(u.type||"").toLowerCase()?S._evalUrl&&!u.noModule&&S._evalUrl(u.src,{nonce:u.nonce||u.getAttribute("nonce")},l):b(u.textContent.replace(je,""),u,l))}return n}function Re(e,t,n){for(var r,i=t?S.filter(t,e):e,o=0;null!=(r=i[o]);o++)n||1!==r.nodeType||S.cleanData(ve(r)),r.parentNode&&(n&&ie(r)&&ye(ve(r,"script")),r.parentNode.removeChild(r));return e}S.extend({htmlPrefilter:function(e){return e},clone:function(e,t,n){var r,i,o,a,s,u,l,c=e.cloneNode(!0),f=ie(e);if(!(y.noCloneChecked||1!==e.nodeType&&11!==e.nodeType||S.isXMLDoc(e)))for(a=ve(c),r=0,i=(o=ve(e)).length;r<i;r++)s=o[r],u=a[r],void 0,"input"===(l=u.nodeName.toLowerCase())&&pe.test(s.type)?u.checked=s.checked:"input"!==l&&"textarea"!==l||(u.defaultValue=s.defaultValue);if(t)if(n)for(o=o||ve(e),a=a||ve(c),r=0,i=o.length;r<i;r++)Oe(o[r],a[r]);else Oe(e,c);return 0<(a=ve(c,"script")).length&&ye(a,!f&&ve(e,"script")),c},cleanData:function(e){for(var t,n,r,i=S.event.special,o=0;void 0!==(n=e[o]);o++)if(V(n)){if(t=n[Y.expando]){if(t.events)for(r in t.events)i[r]?S.event.remove(n,r):S.removeEvent(n,r,t.handle);n[Y.expando]=void 0}n[Q.expando]&&(n[Q.expando]=void 0)}}}),S.fn.extend({detach:function(e){return Re(this,e,!0)},remove:function(e){return Re(this,e)},text:function(e){return $(this,function(e){return void 0===e?S.text(this):this.empty().each(function(){1!==this.nodeType&&11!==this.nodeType&&9!==this.nodeType||(this.textContent=e)})},null,e,arguments.length)},append:function(){return Pe(this,arguments,function(e){1!==this.nodeType&&11!==this.nodeType&&9!==this.nodeType||qe(this,e).appendChild(e)})},prepend:function(){return Pe(this,arguments,function(e){if(1===this.nodeType||11===this.nodeType||9===this.nodeType){var t=qe(this,e);t.insertBefore(e,t.firstChild)}})},before:function(){return Pe(this,arguments,function(e){this.parentNode&&this.parentNode.insertBefore(e,this)})},after:function(){return Pe(this,arguments,function(e){this.parentNode&&this.parentNode.insertBefore(e,this.nextSibling)})},empty:function(){for(var e,t=0;null!=(e=this[t]);t++)1===e.nodeType&&(S.cleanData(ve(e,!1)),e.textContent="");return this},clone:function(e,t){return e=null!=e&&e,t=null==t?e:t,this.map(function(){return S.clone(this,e,t)})},html:function(e){return $(this,function(e){var t=this[0]||{},n=0,r=this.length;if(void 0===e&&1===t.nodeType)return t.innerHTML;if("string"==typeof e&&!Ne.test(e)&&!ge[(de.exec(e)||["",""])[1].toLowerCase()]){e=S.htmlPrefilter(e);try{for(;n<r;n++)1===(t=this[n]||{}).nodeType&&(S.cleanData(ve(t,!1)),t.innerHTML=e);t=0}catch(e){}}t&&this.empty().append(e)},null,e,arguments.length)},replaceWith:function(){var n=[];return Pe(this,arguments,function(e){var t=this.parentNode;S.inArray(this,n)<0&&(S.cleanData(ve(this)),t&&t.replaceChild(e,this))},n)}}),S.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(e,a){S.fn[e]=function(e){for(var t,n=[],r=S(e),i=r.length-1,o=0;o<=i;o++)t=o===i?this:this.clone(!0),S(r[o])[a](t),u.apply(n,t.get());return this.pushStack(n)}});var Me=new RegExp("^("+ee+")(?!px)[a-z%]+$","i"),Ie=function(e){var t=e.ownerDocument.defaultView;return t&&t.opener||(t=C),t.getComputedStyle(e)},We=function(e,t,n){var r,i,o={};for(i in t)o[i]=e.style[i],e.style[i]=t[i];for(i in r=n.call(e),t)e.style[i]=o[i];return r},Fe=new RegExp(ne.join("|"),"i");function Be(e,t,n){var r,i,o,a,s=e.style;return(n=n||Ie(e))&&(""!==(a=n.getPropertyValue(t)||n[t])||ie(e)||(a=S.style(e,t)),!y.pixelBoxStyles()&&Me.test(a)&&Fe.test(t)&&(r=s.width,i=s.minWidth,o=s.maxWidth,s.minWidth=s.maxWidth=s.width=a,a=n.width,s.width=r,s.minWidth=i,s.maxWidth=o)),void 0!==a?a+"":a}function $e(e,t){return{get:function(){if(!e())return(this.get=t).apply(this,arguments);delete this.get}}}!function(){function e(){if(l){u.style.cssText="position:absolute;left:-11111px;width:60px;margin-top:1px;padding:0;border:0",l.style.cssText="position:relative;display:block;box-sizing:border-box;overflow:scroll;margin:auto;border:1px;padding:1px;width:60%;top:1%",re.appendChild(u).appendChild(l);var e=C.getComputedStyle(l);n="1%"!==e.top,s=12===t(e.marginLeft),l.style.right="60%",o=36===t(e.right),r=36===t(e.width),l.style.position="absolute",i=12===t(l.offsetWidth/3),re.removeChild(u),l=null}}function t(e){return Math.round(parseFloat(e))}var n,r,i,o,a,s,u=E.createElement("div"),l=E.createElement("div");l.style&&(l.style.backgroundClip="content-box",l.cloneNode(!0).style.backgroundClip="",y.clearCloneStyle="content-box"===l.style.backgroundClip,S.extend(y,{boxSizingReliable:function(){return e(),r},pixelBoxStyles:function(){return e(),o},pixelPosition:function(){return e(),n},reliableMarginLeft:function(){return e(),s},scrollboxSize:function(){return e(),i},reliableTrDimensions:function(){var e,t,n,r;return null==a&&(e=E.createElement("table"),t=E.createElement("tr"),n=E.createElement("div"),e.style.cssText="position:absolute;left:-11111px",t.style.height="1px",n.style.height="9px",re.appendChild(e).appendChild(t).appendChild(n),r=C.getComputedStyle(t),a=3<parseInt(r.height),re.removeChild(e)),a}}))}();var _e=["Webkit","Moz","ms"],ze=E.createElement("div").style,Ue={};function Xe(e){var t=S.cssProps[e]||Ue[e];return t||(e in ze?e:Ue[e]=function(e){var t=e[0].toUpperCase()+e.slice(1),n=_e.length;while(n--)if((e=_e[n]+t)in ze)return e}(e)||e)}var Ve=/^(none|table(?!-c[ea]).+)/,Ge=/^--/,Ye={position:"absolute",visibility:"hidden",display:"block"},Qe={letterSpacing:"0",fontWeight:"400"};function Je(e,t,n){var r=te.exec(t);return r?Math.max(0,r[2]-(n||0))+(r[3]||"px"):t}function Ke(e,t,n,r,i,o){var a="width"===t?1:0,s=0,u=0;if(n===(r?"border":"content"))return 0;for(;a<4;a+=2)"margin"===n&&(u+=S.css(e,n+ne[a],!0,i)),r?("content"===n&&(u-=S.css(e,"padding"+ne[a],!0,i)),"margin"!==n&&(u-=S.css(e,"border"+ne[a]+"Width",!0,i))):(u+=S.css(e,"padding"+ne[a],!0,i),"padding"!==n?u+=S.css(e,"border"+ne[a]+"Width",!0,i):s+=S.css(e,"border"+ne[a]+"Width",!0,i));return!r&&0<=o&&(u+=Math.max(0,Math.ceil(e["offset"+t[0].toUpperCase()+t.slice(1)]-o-u-s-.5))||0),u}function Ze(e,t,n){var r=Ie(e),i=(!y.boxSizingReliable()||n)&&"border-box"===S.css(e,"boxSizing",!1,r),o=i,a=Be(e,t,r),s="offset"+t[0].toUpperCase()+t.slice(1);if(Me.test(a)){if(!n)return a;a="auto"}return(!y.boxSizingReliable()&&i||!y.reliableTrDimensions()&&A(e,"tr")||"auto"===a||!parseFloat(a)&&"inline"===S.css(e,"display",!1,r))&&e.getClientRects().length&&(i="border-box"===S.css(e,"boxSizing",!1,r),(o=s in e)&&(a=e[s])),(a=parseFloat(a)||0)+Ke(e,t,n||(i?"border":"content"),o,r,a)+"px"}function et(e,t,n,r,i){return new et.prototype.init(e,t,n,r,i)}S.extend({cssHooks:{opacity:{get:function(e,t){if(t){var n=Be(e,"opacity");return""===n?"1":n}}}},cssNumber:{animationIterationCount:!0,columnCount:!0,fillOpacity:!0,flexGrow:!0,flexShrink:!0,fontWeight:!0,gridArea:!0,gridColumn:!0,gridColumnEnd:!0,gridColumnStart:!0,gridRow:!0,gridRowEnd:!0,gridRowStart:!0,lineHeight:!0,opacity:!0,order:!0,orphans:!0,widows:!0,zIndex:!0,zoom:!0},cssProps:{},style:function(e,t,n,r){if(e&&3!==e.nodeType&&8!==e.nodeType&&e.style){var i,o,a,s=X(t),u=Ge.test(t),l=e.style;if(u||(t=Xe(s)),a=S.cssHooks[t]||S.cssHooks[s],void 0===n)return a&&"get"in a&&void 0!==(i=a.get(e,!1,r))?i:l[t];"string"===(o=typeof n)&&(i=te.exec(n))&&i[1]&&(n=se(e,t,i),o="number"),null!=n&&n==n&&("number"!==o||u||(n+=i&&i[3]||(S.cssNumber[s]?"":"px")),y.clearCloneStyle||""!==n||0!==t.indexOf("background")||(l[t]="inherit"),a&&"set"in a&&void 0===(n=a.set(e,n,r))||(u?l.setProperty(t,n):l[t]=n))}},css:function(e,t,n,r){var i,o,a,s=X(t);return Ge.test(t)||(t=Xe(s)),(a=S.cssHooks[t]||S.cssHooks[s])&&"get"in a&&(i=a.get(e,!0,n)),void 0===i&&(i=Be(e,t,r)),"normal"===i&&t in Qe&&(i=Qe[t]),""===n||n?(o=parseFloat(i),!0===n||isFinite(o)?o||0:i):i}}),S.each(["height","width"],function(e,u){S.cssHooks[u]={get:function(e,t,n){if(t)return!Ve.test(S.css(e,"display"))||e.getClientRects().length&&e.getBoundingClientRect().width?Ze(e,u,n):We(e,Ye,function(){return Ze(e,u,n)})},set:function(e,t,n){var r,i=Ie(e),o=!y.scrollboxSize()&&"absolute"===i.position,a=(o||n)&&"border-box"===S.css(e,"boxSizing",!1,i),s=n?Ke(e,u,n,a,i):0;return a&&o&&(s-=Math.ceil(e["offset"+u[0].toUpperCase()+u.slice(1)]-parseFloat(i[u])-Ke(e,u,"border",!1,i)-.5)),s&&(r=te.exec(t))&&"px"!==(r[3]||"px")&&(e.style[u]=t,t=S.css(e,u)),Je(0,t,s)}}}),S.cssHooks.marginLeft=$e(y.reliableMarginLeft,function(e,t){if(t)return(parseFloat(Be(e,"marginLeft"))||e.getBoundingClientRect().left-We(e,{marginLeft:0},function(){return e.getBoundingClientRect().left}))+"px"}),S.each({margin:"",padding:"",border:"Width"},function(i,o){S.cssHooks[i+o]={expand:function(e){for(var t=0,n={},r="string"==typeof e?e.split(" "):[e];t<4;t++)n[i+ne[t]+o]=r[t]||r[t-2]||r[0];return n}},"margin"!==i&&(S.cssHooks[i+o].set=Je)}),S.fn.extend({css:function(e,t){return $(this,function(e,t,n){var r,i,o={},a=0;if(Array.isArray(t)){for(r=Ie(e),i=t.length;a<i;a++)o[t[a]]=S.css(e,t[a],!1,r);return o}return void 0!==n?S.style(e,t,n):S.css(e,t)},e,t,1<arguments.length)}}),((S.Tween=et).prototype={constructor:et,init:function(e,t,n,r,i,o){this.elem=e,this.prop=n,this.easing=i||S.easing._default,this.options=t,this.start=this.now=this.cur(),this.end=r,this.unit=o||(S.cssNumber[n]?"":"px")},cur:function(){var e=et.propHooks[this.prop];return e&&e.get?e.get(this):et.propHooks._default.get(this)},run:function(e){var t,n=et.propHooks[this.prop];return this.options.duration?this.pos=t=S.easing[this.easing](e,this.options.duration*e,0,1,this.options.duration):this.pos=t=e,this.now=(this.end-this.start)*t+this.start,this.options.step&&this.options.step.call(this.elem,this.now,this),n&&n.set?n.set(this):et.propHooks._default.set(this),this}}).init.prototype=et.prototype,(et.propHooks={_default:{get:function(e){var t;return 1!==e.elem.nodeType||null!=e.elem[e.prop]&&null==e.elem.style[e.prop]?e.elem[e.prop]:(t=S.css(e.elem,e.prop,""))&&"auto"!==t?t:0},set:function(e){S.fx.step[e.prop]?S.fx.step[e.prop](e):1!==e.elem.nodeType||!S.cssHooks[e.prop]&&null==e.elem.style[Xe(e.prop)]?e.elem[e.prop]=e.now:S.style(e.elem,e.prop,e.now+e.unit)}}}).scrollTop=et.propHooks.scrollLeft={set:function(e){e.elem.nodeType&&e.elem.parentNode&&(e.elem[e.prop]=e.now)}},S.easing={linear:function(e){return e},swing:function(e){return.5-Math.cos(e*Math.PI)/2},_default:"swing"},S.fx=et.prototype.init,S.fx.step={};var tt,nt,rt,it,ot=/^(?:toggle|show|hide)$/,at=/queueHooks$/;function st(){nt&&(!1===E.hidden&&C.requestAnimationFrame?C.requestAnimationFrame(st):C.setTimeout(st,S.fx.interval),S.fx.tick())}function ut(){return C.setTimeout(function(){tt=void 0}),tt=Date.now()}function lt(e,t){var n,r=0,i={height:e};for(t=t?1:0;r<4;r+=2-t)i["margin"+(n=ne[r])]=i["padding"+n]=e;return t&&(i.opacity=i.width=e),i}function ct(e,t,n){for(var r,i=(ft.tweeners[t]||[]).concat(ft.tweeners["*"]),o=0,a=i.length;o<a;o++)if(r=i[o].call(n,t,e))return r}function ft(o,e,t){var n,a,r=0,i=ft.prefilters.length,s=S.Deferred().always(function(){delete u.elem}),u=function(){if(a)return!1;for(var e=tt||ut(),t=Math.max(0,l.startTime+l.duration-e),n=1-(t/l.duration||0),r=0,i=l.tweens.length;r<i;r++)l.tweens[r].run(n);return s.notifyWith(o,[l,n,t]),n<1&&i?t:(i||s.notifyWith(o,[l,1,0]),s.resolveWith(o,[l]),!1)},l=s.promise({elem:o,props:S.extend({},e),opts:S.extend(!0,{specialEasing:{},easing:S.easing._default},t),originalProperties:e,originalOptions:t,startTime:tt||ut(),duration:t.duration,tweens:[],createTween:function(e,t){var n=S.Tween(o,l.opts,e,t,l.opts.specialEasing[e]||l.opts.easing);return l.tweens.push(n),n},stop:function(e){var t=0,n=e?l.tweens.length:0;if(a)return this;for(a=!0;t<n;t++)l.tweens[t].run(1);return e?(s.notifyWith(o,[l,1,0]),s.resolveWith(o,[l,e])):s.rejectWith(o,[l,e]),this}}),c=l.props;for(!function(e,t){var n,r,i,o,a;for(n in e)if(i=t[r=X(n)],o=e[n],Array.isArray(o)&&(i=o[1],o=e[n]=o[0]),n!==r&&(e[r]=o,delete e[n]),(a=S.cssHooks[r])&&"expand"in a)for(n in o=a.expand(o),delete e[r],o)n in e||(e[n]=o[n],t[n]=i);else t[r]=i}(c,l.opts.specialEasing);r<i;r++)if(n=ft.prefilters[r].call(l,o,c,l.opts))return m(n.stop)&&(S._queueHooks(l.elem,l.opts.queue).stop=n.stop.bind(n)),n;return S.map(c,ct,l),m(l.opts.start)&&l.opts.start.call(o,l),l.progress(l.opts.progress).done(l.opts.done,l.opts.complete).fail(l.opts.fail).always(l.opts.always),S.fx.timer(S.extend(u,{elem:o,anim:l,queue:l.opts.queue})),l}S.Animation=S.extend(ft,{tweeners:{"*":[function(e,t){var n=this.createTween(e,t);return se(n.elem,e,te.exec(t),n),n}]},tweener:function(e,t){m(e)?(t=e,e=["*"]):e=e.match(P);for(var n,r=0,i=e.length;r<i;r++)n=e[r],ft.tweeners[n]=ft.tweeners[n]||[],ft.tweeners[n].unshift(t)},prefilters:[function(e,t,n){var r,i,o,a,s,u,l,c,f="width"in t||"height"in t,p=this,d={},h=e.style,g=e.nodeType&&ae(e),v=Y.get(e,"fxshow");for(r in n.queue||(null==(a=S._queueHooks(e,"fx")).unqueued&&(a.unqueued=0,s=a.empty.fire,a.empty.fire=function(){a.unqueued||s()}),a.unqueued++,p.always(function(){p.always(function(){a.unqueued--,S.queue(e,"fx").length||a.empty.fire()})})),t)if(i=t[r],ot.test(i)){if(delete t[r],o=o||"toggle"===i,i===(g?"hide":"show")){if("show"!==i||!v||void 0===v[r])continue;g=!0}d[r]=v&&v[r]||S.style(e,r)}if((u=!S.isEmptyObject(t))||!S.isEmptyObject(d))for(r in f&&1===e.nodeType&&(n.overflow=[h.overflow,h.overflowX,h.overflowY],null==(l=v&&v.display)&&(l=Y.get(e,"display")),"none"===(c=S.css(e,"display"))&&(l?c=l:(le([e],!0),l=e.style.display||l,c=S.css(e,"display"),le([e]))),("inline"===c||"inline-block"===c&&null!=l)&&"none"===S.css(e,"float")&&(u||(p.done(function(){h.display=l}),null==l&&(c=h.display,l="none"===c?"":c)),h.display="inline-block")),n.overflow&&(h.overflow="hidden",p.always(function(){h.overflow=n.overflow[0],h.overflowX=n.overflow[1],h.overflowY=n.overflow[2]})),u=!1,d)u||(v?"hidden"in v&&(g=v.hidden):v=Y.access(e,"fxshow",{display:l}),o&&(v.hidden=!g),g&&le([e],!0),p.done(function(){for(r in g||le([e]),Y.remove(e,"fxshow"),d)S.style(e,r,d[r])})),u=ct(g?v[r]:0,r,p),r in v||(v[r]=u.start,g&&(u.end=u.start,u.start=0))}],prefilter:function(e,t){t?ft.prefilters.unshift(e):ft.prefilters.push(e)}}),S.speed=function(e,t,n){var r=e&&"object"==typeof e?S.extend({},e):{complete:n||!n&&t||m(e)&&e,duration:e,easing:n&&t||t&&!m(t)&&t};return S.fx.off?r.duration=0:"number"!=typeof r.duration&&(r.duration in S.fx.speeds?r.duration=S.fx.speeds[r.duration]:r.duration=S.fx.speeds._default),null!=r.queue&&!0!==r.queue||(r.queue="fx"),r.old=r.complete,r.complete=function(){m(r.old)&&r.old.call(this),r.queue&&S.dequeue(this,r.queue)},r},S.fn.extend({fadeTo:function(e,t,n,r){return this.filter(ae).css("opacity",0).show().end().animate({opacity:t},e,n,r)},animate:function(t,e,n,r){var i=S.isEmptyObject(t),o=S.speed(e,n,r),a=function(){var e=ft(this,S.extend({},t),o);(i||Y.get(this,"finish"))&&e.stop(!0)};return a.finish=a,i||!1===o.queue?this.each(a):this.queue(o.queue,a)},stop:function(i,e,o){var a=function(e){var t=e.stop;delete e.stop,t(o)};return"string"!=typeof i&&(o=e,e=i,i=void 0),e&&this.queue(i||"fx",[]),this.each(function(){var e=!0,t=null!=i&&i+"queueHooks",n=S.timers,r=Y.get(this);if(t)r[t]&&r[t].stop&&a(r[t]);else for(t in r)r[t]&&r[t].stop&&at.test(t)&&a(r[t]);for(t=n.length;t--;)n[t].elem!==this||null!=i&&n[t].queue!==i||(n[t].anim.stop(o),e=!1,n.splice(t,1));!e&&o||S.dequeue(this,i)})},finish:function(a){return!1!==a&&(a=a||"fx"),this.each(function(){var e,t=Y.get(this),n=t[a+"queue"],r=t[a+"queueHooks"],i=S.timers,o=n?n.length:0;for(t.finish=!0,S.queue(this,a,[]),r&&r.stop&&r.stop.call(this,!0),e=i.length;e--;)i[e].elem===this&&i[e].queue===a&&(i[e].anim.stop(!0),i.splice(e,1));for(e=0;e<o;e++)n[e]&&n[e].finish&&n[e].finish.call(this);delete t.finish})}}),S.each(["toggle","show","hide"],function(e,r){var i=S.fn[r];S.fn[r]=function(e,t,n){return null==e||"boolean"==typeof e?i.apply(this,arguments):this.animate(lt(r,!0),e,t,n)}}),S.each({slideDown:lt("show"),slideUp:lt("hide"),slideToggle:lt("toggle"),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"},fadeToggle:{opacity:"toggle"}},function(e,r){S.fn[e]=function(e,t,n){return this.animate(r,e,t,n)}}),S.timers=[],S.fx.tick=function(){var e,t=0,n=S.timers;for(tt=Date.now();t<n.length;t++)(e=n[t])()||n[t]!==e||n.splice(t--,1);n.length||S.fx.stop(),tt=void 0},S.fx.timer=function(e){S.timers.push(e),S.fx.start()},S.fx.interval=13,S.fx.start=function(){nt||(nt=!0,st())},S.fx.stop=function(){nt=null},S.fx.speeds={slow:600,fast:200,_default:400},S.fn.delay=function(r,e){return r=S.fx&&S.fx.speeds[r]||r,e=e||"fx",this.queue(e,function(e,t){var n=C.setTimeout(e,r);t.stop=function(){C.clearTimeout(n)}})},rt=E.createElement("input"),it=E.createElement("select").appendChild(E.createElement("option")),rt.type="checkbox",y.checkOn=""!==rt.value,y.optSelected=it.selected,(rt=E.createElement("input")).value="t",rt.type="radio",y.radioValue="t"===rt.value;var pt,dt=S.expr.attrHandle;S.fn.extend({attr:function(e,t){return $(this,S.attr,e,t,1<arguments.length)},removeAttr:function(e){return this.each(function(){S.removeAttr(this,e)})}}),S.extend({attr:function(e,t,n){var r,i,o=e.nodeType;if(3!==o&&8!==o&&2!==o)return"undefined"==typeof e.getAttribute?S.prop(e,t,n):(1===o&&S.isXMLDoc(e)||(i=S.attrHooks[t.toLowerCase()]||(S.expr.match.bool.test(t)?pt:void 0)),void 0!==n?null===n?void S.removeAttr(e,t):i&&"set"in i&&void 0!==(r=i.set(e,n,t))?r:(e.setAttribute(t,n+""),n):i&&"get"in i&&null!==(r=i.get(e,t))?r:null==(r=S.find.attr(e,t))?void 0:r)},attrHooks:{type:{set:function(e,t){if(!y.radioValue&&"radio"===t&&A(e,"input")){var n=e.value;return e.setAttribute("type",t),n&&(e.value=n),t}}}},removeAttr:function(e,t){var n,r=0,i=t&&t.match(P);if(i&&1===e.nodeType)while(n=i[r++])e.removeAttribute(n)}}),pt={set:function(e,t,n){return!1===t?S.removeAttr(e,n):e.setAttribute(n,n),n}},S.each(S.expr.match.bool.source.match(/\w+/g),function(e,t){var a=dt[t]||S.find.attr;dt[t]=function(e,t,n){var r,i,o=t.toLowerCase();return n||(i=dt[o],dt[o]=r,r=null!=a(e,t,n)?o:null,dt[o]=i),r}});var ht=/^(?:input|select|textarea|button)$/i,gt=/^(?:a|area)$/i;function vt(e){return(e.match(P)||[]).join(" ")}function yt(e){return e.getAttribute&&e.getAttribute("class")||""}function mt(e){return Array.isArray(e)?e:"string"==typeof e&&e.match(P)||[]}S.fn.extend({prop:function(e,t){return $(this,S.prop,e,t,1<arguments.length)},removeProp:function(e){return this.each(function(){delete this[S.propFix[e]||e]})}}),S.extend({prop:function(e,t,n){var r,i,o=e.nodeType;if(3!==o&&8!==o&&2!==o)return 1===o&&S.isXMLDoc(e)||(t=S.propFix[t]||t,i=S.propHooks[t]),void 0!==n?i&&"set"in i&&void 0!==(r=i.set(e,n,t))?r:e[t]=n:i&&"get"in i&&null!==(r=i.get(e,t))?r:e[t]},propHooks:{tabIndex:{get:function(e){var t=S.find.attr(e,"tabindex");return t?parseInt(t,10):ht.test(e.nodeName)||gt.test(e.nodeName)&&e.href?0:-1}}},propFix:{"for":"htmlFor","class":"className"}}),y.optSelected||(S.propHooks.selected={get:function(e){var t=e.parentNode;return t&&t.parentNode&&t.parentNode.selectedIndex,null},set:function(e){var t=e.parentNode;t&&(t.selectedIndex,t.parentNode&&t.parentNode.selectedIndex)}}),S.each(["tabIndex","readOnly","maxLength","cellSpacing","cellPadding","rowSpan","colSpan","useMap","frameBorder","contentEditable"],function(){S.propFix[this.toLowerCase()]=this}),S.fn.extend({addClass:function(t){var e,n,r,i,o,a,s,u=0;if(m(t))return this.each(function(e){S(this).addClass(t.call(this,e,yt(this)))});if((e=mt(t)).length)while(n=this[u++])if(i=yt(n),r=1===n.nodeType&&" "+vt(i)+" "){a=0;while(o=e[a++])r.indexOf(" "+o+" ")<0&&(r+=o+" ");i!==(s=vt(r))&&n.setAttribute("class",s)}return this},removeClass:function(t){var e,n,r,i,o,a,s,u=0;if(m(t))return this.each(function(e){S(this).removeClass(t.call(this,e,yt(this)))});if(!arguments.length)return this.attr("class","");if((e=mt(t)).length)while(n=this[u++])if(i=yt(n),r=1===n.nodeType&&" "+vt(i)+" "){a=0;while(o=e[a++])while(-1<r.indexOf(" "+o+" "))r=r.replace(" "+o+" "," ");i!==(s=vt(r))&&n.setAttribute("class",s)}return this},toggleClass:function(i,t){var o=typeof i,a="string"===o||Array.isArray(i);return"boolean"==typeof t&&a?t?this.addClass(i):this.removeClass(i):m(i)?this.each(function(e){S(this).toggleClass(i.call(this,e,yt(this),t),t)}):this.each(function(){var e,t,n,r;if(a){t=0,n=S(this),r=mt(i);while(e=r[t++])n.hasClass(e)?n.removeClass(e):n.addClass(e)}else void 0!==i&&"boolean"!==o||((e=yt(this))&&Y.set(this,"__className__",e),this.setAttribute&&this.setAttribute("class",e||!1===i?"":Y.get(this,"__className__")||""))})},hasClass:function(e){var t,n,r=0;t=" "+e+" ";while(n=this[r++])if(1===n.nodeType&&-1<(" "+vt(yt(n))+" ").indexOf(t))return!0;return!1}});var xt=/\r/g;S.fn.extend({val:function(n){var r,e,i,t=this[0];return arguments.length?(i=m(n),this.each(function(e){var t;1===this.nodeType&&(null==(t=i?n.call(this,e,S(this).val()):n)?t="":"number"==typeof t?t+="":Array.isArray(t)&&(t=S.map(t,function(e){return null==e?"":e+""})),(r=S.valHooks[this.type]||S.valHooks[this.nodeName.toLowerCase()])&&"set"in r&&void 0!==r.set(this,t,"value")||(this.value=t))})):t?(r=S.valHooks[t.type]||S.valHooks[t.nodeName.toLowerCase()])&&"get"in r&&void 0!==(e=r.get(t,"value"))?e:"string"==typeof(e=t.value)?e.replace(xt,""):null==e?"":e:void 0}}),S.extend({valHooks:{option:{get:function(e){var t=S.find.attr(e,"value");return null!=t?t:vt(S.text(e))}},select:{get:function(e){var t,n,r,i=e.options,o=e.selectedIndex,a="select-one"===e.type,s=a?null:[],u=a?o+1:i.length;for(r=o<0?u:a?o:0;r<u;r++)if(((n=i[r]).selected||r===o)&&!n.disabled&&(!n.parentNode.disabled||!A(n.parentNode,"optgroup"))){if(t=S(n).val(),a)return t;s.push(t)}return s},set:function(e,t){var n,r,i=e.options,o=S.makeArray(t),a=i.length;while(a--)((r=i[a]).selected=-1<S.inArray(S.valHooks.option.get(r),o))&&(n=!0);return n||(e.selectedIndex=-1),o}}}}),S.each(["radio","checkbox"],function(){S.valHooks[this]={set:function(e,t){if(Array.isArray(t))return e.checked=-1<S.inArray(S(e).val(),t)}},y.checkOn||(S.valHooks[this].get=function(e){return null===e.getAttribute("value")?"on":e.value})}),y.focusin="onfocusin"in C;var bt=/^(?:focusinfocus|focusoutblur)$/,wt=function(e){e.stopPropagation()};S.extend(S.event,{trigger:function(e,t,n,r){var i,o,a,s,u,l,c,f,p=[n||E],d=v.call(e,"type")?e.type:e,h=v.call(e,"namespace")?e.namespace.split("."):[];if(o=f=a=n=n||E,3!==n.nodeType&&8!==n.nodeType&&!bt.test(d+S.event.triggered)&&(-1<d.indexOf(".")&&(d=(h=d.split(".")).shift(),h.sort()),u=d.indexOf(":")<0&&"on"+d,(e=e[S.expando]?e:new S.Event(d,"object"==typeof e&&e)).isTrigger=r?2:3,e.namespace=h.join("."),e.rnamespace=e.namespace?new RegExp("(^|\\.)"+h.join("\\.(?:.*\\.|)")+"(\\.|$)"):null,e.result=void 0,e.target||(e.target=n),t=null==t?[e]:S.makeArray(t,[e]),c=S.event.special[d]||{},r||!c.trigger||!1!==c.trigger.apply(n,t))){if(!r&&!c.noBubble&&!x(n)){for(s=c.delegateType||d,bt.test(s+d)||(o=o.parentNode);o;o=o.parentNode)p.push(o),a=o;a===(n.ownerDocument||E)&&p.push(a.defaultView||a.parentWindow||C)}i=0;while((o=p[i++])&&!e.isPropagationStopped())f=o,e.type=1<i?s:c.bindType||d,(l=(Y.get(o,"events")||Object.create(null))[e.type]&&Y.get(o,"handle"))&&l.apply(o,t),(l=u&&o[u])&&l.apply&&V(o)&&(e.result=l.apply(o,t),!1===e.result&&e.preventDefault());return e.type=d,r||e.isDefaultPrevented()||c._default&&!1!==c._default.apply(p.pop(),t)||!V(n)||u&&m(n[d])&&!x(n)&&((a=n[u])&&(n[u]=null),S.event.triggered=d,e.isPropagationStopped()&&f.addEventListener(d,wt),n[d](),e.isPropagationStopped()&&f.removeEventListener(d,wt),S.event.triggered=void 0,a&&(n[u]=a)),e.result}},simulate:function(e,t,n){var r=S.extend(new S.Event,n,{type:e,isSimulated:!0});S.event.trigger(r,null,t)}}),S.fn.extend({trigger:function(e,t){return this.each(function(){S.event.trigger(e,t,this)})},triggerHandler:function(e,t){var n=this[0];if(n)return S.event.trigger(e,t,n,!0)}}),y.focusin||S.each({focus:"focusin",blur:"focusout"},function(n,r){var i=function(e){S.event.simulate(r,e.target,S.event.fix(e))};S.event.special[r]={setup:function(){var e=this.ownerDocument||this.document||this,t=Y.access(e,r);t||e.addEventListener(n,i,!0),Y.access(e,r,(t||0)+1)},teardown:function(){var e=this.ownerDocument||this.document||this,t=Y.access(e,r)-1;t?Y.access(e,r,t):(e.removeEventListener(n,i,!0),Y.remove(e,r))}}});var Tt=C.location,Ct={guid:Date.now()},Et=/\?/;S.parseXML=function(e){var t;if(!e||"string"!=typeof e)return null;try{t=(new C.DOMParser).parseFromString(e,"text/xml")}catch(e){t=void 0}return t&&!t.getElementsByTagName("parsererror").length||S.error("Invalid XML: "+e),t};var St=/\[\]$/,kt=/\r?\n/g,At=/^(?:submit|button|image|reset|file)$/i,Nt=/^(?:input|select|textarea|keygen)/i;function Dt(n,e,r,i){var t;if(Array.isArray(e))S.each(e,function(e,t){r||St.test(n)?i(n,t):Dt(n+"["+("object"==typeof t&&null!=t?e:"")+"]",t,r,i)});else if(r||"object"!==w(e))i(n,e);else for(t in e)Dt(n+"["+t+"]",e[t],r,i)}S.param=function(e,t){var n,r=[],i=function(e,t){var n=m(t)?t():t;r[r.length]=encodeURIComponent(e)+"="+encodeURIComponent(null==n?"":n)};if(null==e)return"";if(Array.isArray(e)||e.jquery&&!S.isPlainObject(e))S.each(e,function(){i(this.name,this.value)});else for(n in e)Dt(n,e[n],t,i);return r.join("&")},S.fn.extend({serialize:function(){return S.param(this.serializeArray())},serializeArray:function(){return this.map(function(){var e=S.prop(this,"elements");return e?S.makeArray(e):this}).filter(function(){var e=this.type;return this.name&&!S(this).is(":disabled")&&Nt.test(this.nodeName)&&!At.test(e)&&(this.checked||!pe.test(e))}).map(function(e,t){var n=S(this).val();return null==n?null:Array.isArray(n)?S.map(n,function(e){return{name:t.name,value:e.replace(kt,"\r\n")}}):{name:t.name,value:n.replace(kt,"\r\n")}}).get()}});var jt=/%20/g,qt=/#.*$/,Lt=/([?&])_=[^&]*/,Ht=/^(.*?):[ \t]*([^\r\n]*)$/gm,Ot=/^(?:GET|HEAD)$/,Pt=/^\/\//,Rt={},Mt={},It="*/".concat("*"),Wt=E.createElement("a");function Ft(o){return function(e,t){"string"!=typeof e&&(t=e,e="*");var n,r=0,i=e.toLowerCase().match(P)||[];if(m(t))while(n=i[r++])"+"===n[0]?(n=n.slice(1)||"*",(o[n]=o[n]||[]).unshift(t)):(o[n]=o[n]||[]).push(t)}}function Bt(t,i,o,a){var s={},u=t===Mt;function l(e){var r;return s[e]=!0,S.each(t[e]||[],function(e,t){var n=t(i,o,a);return"string"!=typeof n||u||s[n]?u?!(r=n):void 0:(i.dataTypes.unshift(n),l(n),!1)}),r}return l(i.dataTypes[0])||!s["*"]&&l("*")}function $t(e,t){var n,r,i=S.ajaxSettings.flatOptions||{};for(n in t)void 0!==t[n]&&((i[n]?e:r||(r={}))[n]=t[n]);return r&&S.extend(!0,e,r),e}Wt.href=Tt.href,S.extend({active:0,lastModified:{},etag:{},ajaxSettings:{url:Tt.href,type:"GET",isLocal:/^(?:about|app|app-storage|.+-extension|file|res|widget):$/.test(Tt.protocol),global:!0,processData:!0,async:!0,contentType:"application/x-www-form-urlencoded; charset=UTF-8",accepts:{"*":It,text:"text/plain",html:"text/html",xml:"application/xml, text/xml",json:"application/json, text/javascript"},contents:{xml:/\bxml\b/,html:/\bhtml/,json:/\bjson\b/},responseFields:{xml:"responseXML",text:"responseText",json:"responseJSON"},converters:{"* text":String,"text html":!0,"text json":JSON.parse,"text xml":S.parseXML},flatOptions:{url:!0,context:!0}},ajaxSetup:function(e,t){return t?$t($t(e,S.ajaxSettings),t):$t(S.ajaxSettings,e)},ajaxPrefilter:Ft(Rt),ajaxTransport:Ft(Mt),ajax:function(e,t){"object"==typeof e&&(t=e,e=void 0),t=t||{};var c,f,p,n,d,r,h,g,i,o,v=S.ajaxSetup({},t),y=v.context||v,m=v.context&&(y.nodeType||y.jquery)?S(y):S.event,x=S.Deferred(),b=S.Callbacks("once memory"),w=v.statusCode||{},a={},s={},u="canceled",T={readyState:0,getResponseHeader:function(e){var t;if(h){if(!n){n={};while(t=Ht.exec(p))n[t[1].toLowerCase()+" "]=(n[t[1].toLowerCase()+" "]||[]).concat(t[2])}t=n[e.toLowerCase()+" "]}return null==t?null:t.join(", ")},getAllResponseHeaders:function(){return h?p:null},setRequestHeader:function(e,t){return null==h&&(e=s[e.toLowerCase()]=s[e.toLowerCase()]||e,a[e]=t),this},overrideMimeType:function(e){return null==h&&(v.mimeType=e),this},statusCode:function(e){var t;if(e)if(h)T.always(e[T.status]);else for(t in e)w[t]=[w[t],e[t]];return this},abort:function(e){var t=e||u;return c&&c.abort(t),l(0,t),this}};if(x.promise(T),v.url=((e||v.url||Tt.href)+"").replace(Pt,Tt.protocol+"//"),v.type=t.method||t.type||v.method||v.type,v.dataTypes=(v.dataType||"*").toLowerCase().match(P)||[""],null==v.crossDomain){r=E.createElement("a");try{r.href=v.url,r.href=r.href,v.crossDomain=Wt.protocol+"//"+Wt.host!=r.protocol+"//"+r.host}catch(e){v.crossDomain=!0}}if(v.data&&v.processData&&"string"!=typeof v.data&&(v.data=S.param(v.data,v.traditional)),Bt(Rt,v,t,T),h)return T;for(i in(g=S.event&&v.global)&&0==S.active++&&S.event.trigger("ajaxStart"),v.type=v.type.toUpperCase(),v.hasContent=!Ot.test(v.type),f=v.url.replace(qt,""),v.hasContent?v.data&&v.processData&&0===(v.contentType||"").indexOf("application/x-www-form-urlencoded")&&(v.data=v.data.replace(jt,"+")):(o=v.url.slice(f.length),v.data&&(v.processData||"string"==typeof v.data)&&(f+=(Et.test(f)?"&":"?")+v.data,delete v.data),!1===v.cache&&(f=f.replace(Lt,"$1"),o=(Et.test(f)?"&":"?")+"_="+Ct.guid+++o),v.url=f+o),v.ifModified&&(S.lastModified[f]&&T.setRequestHeader("If-Modified-Since",S.lastModified[f]),S.etag[f]&&T.setRequestHeader("If-None-Match",S.etag[f])),(v.data&&v.hasContent&&!1!==v.contentType||t.contentType)&&T.setRequestHeader("Content-Type",v.contentType),T.setRequestHeader("Accept",v.dataTypes[0]&&v.accepts[v.dataTypes[0]]?v.accepts[v.dataTypes[0]]+("*"!==v.dataTypes[0]?", "+It+"; q=0.01":""):v.accepts["*"]),v.headers)T.setRequestHeader(i,v.headers[i]);if(v.beforeSend&&(!1===v.beforeSend.call(y,T,v)||h))return T.abort();if(u="abort",b.add(v.complete),T.done(v.success),T.fail(v.error),c=Bt(Mt,v,t,T)){if(T.readyState=1,g&&m.trigger("ajaxSend",[T,v]),h)return T;v.async&&0<v.timeout&&(d=C.setTimeout(function(){T.abort("timeout")},v.timeout));try{h=!1,c.send(a,l)}catch(e){if(h)throw e;l(-1,e)}}else l(-1,"No Transport");function l(e,t,n,r){var i,o,a,s,u,l=t;h||(h=!0,d&&C.clearTimeout(d),c=void 0,p=r||"",T.readyState=0<e?4:0,i=200<=e&&e<300||304===e,n&&(s=function(e,t,n){var r,i,o,a,s=e.contents,u=e.dataTypes;while("*"===u[0])u.shift(),void 0===r&&(r=e.mimeType||t.getResponseHeader("Content-Type"));if(r)for(i in s)if(s[i]&&s[i].test(r)){u.unshift(i);break}if(u[0]in n)o=u[0];else{for(i in n){if(!u[0]||e.converters[i+" "+u[0]]){o=i;break}a||(a=i)}o=o||a}if(o)return o!==u[0]&&u.unshift(o),n[o]}(v,T,n)),!i&&-1<S.inArray("script",v.dataTypes)&&(v.converters["text script"]=function(){}),s=function(e,t,n,r){var i,o,a,s,u,l={},c=e.dataTypes.slice();if(c[1])for(a in e.converters)l[a.toLowerCase()]=e.converters[a];o=c.shift();while(o)if(e.responseFields[o]&&(n[e.responseFields[o]]=t),!u&&r&&e.dataFilter&&(t=e.dataFilter(t,e.dataType)),u=o,o=c.shift())if("*"===o)o=u;else if("*"!==u&&u!==o){if(!(a=l[u+" "+o]||l["* "+o]))for(i in l)if((s=i.split(" "))[1]===o&&(a=l[u+" "+s[0]]||l["* "+s[0]])){!0===a?a=l[i]:!0!==l[i]&&(o=s[0],c.unshift(s[1]));break}if(!0!==a)if(a&&e["throws"])t=a(t);else try{t=a(t)}catch(e){return{state:"parsererror",error:a?e:"No conversion from "+u+" to "+o}}}return{state:"success",data:t}}(v,s,T,i),i?(v.ifModified&&((u=T.getResponseHeader("Last-Modified"))&&(S.lastModified[f]=u),(u=T.getResponseHeader("etag"))&&(S.etag[f]=u)),204===e||"HEAD"===v.type?l="nocontent":304===e?l="notmodified":(l=s.state,o=s.data,i=!(a=s.error))):(a=l,!e&&l||(l="error",e<0&&(e=0))),T.status=e,T.statusText=(t||l)+"",i?x.resolveWith(y,[o,l,T]):x.rejectWith(y,[T,l,a]),T.statusCode(w),w=void 0,g&&m.trigger(i?"ajaxSuccess":"ajaxError",[T,v,i?o:a]),b.fireWith(y,[T,l]),g&&(m.trigger("ajaxComplete",[T,v]),--S.active||S.event.trigger("ajaxStop")))}return T},getJSON:function(e,t,n){return S.get(e,t,n,"json")},getScript:function(e,t){return S.get(e,void 0,t,"script")}}),S.each(["get","post"],function(e,i){S[i]=function(e,t,n,r){return m(t)&&(r=r||n,n=t,t=void 0),S.ajax(S.extend({url:e,type:i,dataType:r,data:t,success:n},S.isPlainObject(e)&&e))}}),S.ajaxPrefilter(function(e){var t;for(t in e.headers)"content-type"===t.toLowerCase()&&(e.contentType=e.headers[t]||"")}),S._evalUrl=function(e,t,n){return S.ajax({url:e,type:"GET",dataType:"script",cache:!0,async:!1,global:!1,converters:{"text script":function(){}},dataFilter:function(e){S.globalEval(e,t,n)}})},S.fn.extend({wrapAll:function(e){var t;return this[0]&&(m(e)&&(e=e.call(this[0])),t=S(e,this[0].ownerDocument).eq(0).clone(!0),this[0].parentNode&&t.insertBefore(this[0]),t.map(function(){var e=this;while(e.firstElementChild)e=e.firstElementChild;return e}).append(this)),this},wrapInner:function(n){return m(n)?this.each(function(e){S(this).wrapInner(n.call(this,e))}):this.each(function(){var e=S(this),t=e.contents();t.length?t.wrapAll(n):e.append(n)})},wrap:function(t){var n=m(t);return this.each(function(e){S(this).wrapAll(n?t.call(this,e):t)})},unwrap:function(e){return this.parent(e).not("body").each(function(){S(this).replaceWith(this.childNodes)}),this}}),S.expr.pseudos.hidden=function(e){return!S.expr.pseudos.visible(e)},S.expr.pseudos.visible=function(e){return!!(e.offsetWidth||e.offsetHeight||e.getClientRects().length)},S.ajaxSettings.xhr=function(){try{return new C.XMLHttpRequest}catch(e){}};var _t={0:200,1223:204},zt=S.ajaxSettings.xhr();y.cors=!!zt&&"withCredentials"in zt,y.ajax=zt=!!zt,S.ajaxTransport(function(i){var o,a;if(y.cors||zt&&!i.crossDomain)return{send:function(e,t){var n,r=i.xhr();if(r.open(i.type,i.url,i.async,i.username,i.password),i.xhrFields)for(n in i.xhrFields)r[n]=i.xhrFields[n];for(n in i.mimeType&&r.overrideMimeType&&r.overrideMimeType(i.mimeType),i.crossDomain||e["X-Requested-With"]||(e["X-Requested-With"]="XMLHttpRequest"),e)r.setRequestHeader(n,e[n]);o=function(e){return function(){o&&(o=a=r.onload=r.onerror=r.onabort=r.ontimeout=r.onreadystatechange=null,"abort"===e?r.abort():"error"===e?"number"!=typeof r.status?t(0,"error"):t(r.status,r.statusText):t(_t[r.status]||r.status,r.statusText,"text"!==(r.responseType||"text")||"string"!=typeof r.responseText?{binary:r.response}:{text:r.responseText},r.getAllResponseHeaders()))}},r.onload=o(),a=r.onerror=r.ontimeout=o("error"),void 0!==r.onabort?r.onabort=a:r.onreadystatechange=function(){4===r.readyState&&C.setTimeout(function(){o&&a()})},o=o("abort");try{r.send(i.hasContent&&i.data||null)}catch(e){if(o)throw e}},abort:function(){o&&o()}}}),S.ajaxPrefilter(function(e){e.crossDomain&&(e.contents.script=!1)}),S.ajaxSetup({accepts:{script:"text/javascript, application/javascript, application/ecmascript, application/x-ecmascript"},contents:{script:/\b(?:java|ecma)script\b/},converters:{"text script":function(e){return S.globalEval(e),e}}}),S.ajaxPrefilter("script",function(e){void 0===e.cache&&(e.cache=!1),e.crossDomain&&(e.type="GET")}),S.ajaxTransport("script",function(n){var r,i;if(n.crossDomain||n.scriptAttrs)return{send:function(e,t){r=S("<script>").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var Ut,Xt=[],Vt=/(=)\?(?=&|$)|\?\?/;S.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=Xt.pop()||S.expando+"_"+Ct.guid++;return this[e]=!0,e}}),S.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Vt.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Vt.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Vt,"$1"+r):!1!==e.jsonp&&(e.url+=(Et.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||S.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?S(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,Xt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((Ut=E.implementation.createHTMLDocument("").body).innerHTML="<form></form><form></form>",2===Ut.childNodes.length),S.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=N.exec(e))?[t.createElement(i[1])]:(i=xe([e],t,o),o&&o.length&&S(o).remove(),S.merge([],i.childNodes)));var r,i,o},S.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1<s&&(r=vt(e.slice(s)),e=e.slice(0,s)),m(t)?(n=t,t=void 0):t&&"object"==typeof t&&(i="POST"),0<a.length&&S.ajax({url:e,type:i||"GET",dataType:"html",data:t}).done(function(e){o=arguments,a.html(r?S("<div>").append(S.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},S.expr.pseudos.animated=function(t){return S.grep(S.timers,function(e){return t===e.elem}).length},S.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=S.css(e,"position"),c=S(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=S.css(e,"top"),u=S.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,S.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):("number"==typeof f.top&&(f.top+="px"),"number"==typeof f.left&&(f.left+="px"),c.css(f))}},S.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){S.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===S.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===S.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=S(e).offset()).top+=S.css(e,"borderTopWidth",!0),i.left+=S.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-S.css(r,"marginTop",!0),left:t.left-i.left-S.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===S.css(e,"position"))e=e.offsetParent;return e||re})}}),S.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;S.fn[t]=function(e){return $(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),S.each(["top","left"],function(e,n){S.cssHooks[n]=$e(y.pixelPosition,function(e,t){if(t)return t=Be(e,n),Me.test(t)?S(e).position()[n]+"px":t})}),S.each({Height:"height",Width:"width"},function(a,s){S.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){S.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return $(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?S.css(e,t,i):S.style(e,t,n,i)},s,n?e:void 0,n)}})}),S.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){S.fn[t]=function(e){return this.on(t,e)}}),S.fn.extend({bind:function(e,t,n){return this.on(e,null,t,n)},unbind:function(e,t){return this.off(e,null,t)},delegate:function(e,t,n,r){return this.on(t,e,n,r)},undelegate:function(e,t,n){return 1===arguments.length?this.off(e,"**"):this.off(t,e||"**",n)},hover:function(e,t){return this.mouseenter(e).mouseleave(t||e)}}),S.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){S.fn[n]=function(e,t){return 0<arguments.length?this.on(n,null,e,t):this.trigger(n)}});var Gt=/^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g;S.proxy=function(e,t){var n,r,i;if("string"==typeof t&&(n=e[t],t=e,e=n),m(e))return r=s.call(arguments,2),(i=function(){return e.apply(t||this,r.concat(s.call(arguments)))}).guid=e.guid=e.guid||S.guid++,i},S.holdReady=function(e){e?S.readyWait++:S.ready(!0)},S.isArray=Array.isArray,S.parseJSON=JSON.parse,S.nodeName=A,S.isFunction=m,S.isWindow=x,S.camelCase=X,S.type=w,S.now=Date.now,S.isNumeric=function(e){var t=S.type(e);return("number"===t||"string"===t)&&!isNaN(e-parseFloat(e))},S.trim=function(e){return null==e?"":(e+"").replace(Gt,"")},"function"==typeof define&&define.amd&&define("jquery",[],function(){return S});var Yt=C.jQuery,Qt=C.$;return S.noConflict=function(e){return C.$===S&&(C.$=Qt),e&&C.jQuery===S&&(C.jQuery=Yt),S},"undefined"==typeof e&&(C.jQuery=C.$=S),S}); diff --git a/guide/_static/language_data.js b/guide/_static/language_data.js new file mode 100644 index 0000000..ebe2f03 --- /dev/null +++ b/guide/_static/language_data.js @@ -0,0 +1,297 @@ +/* + * language_data.js + * ~~~~~~~~~~~~~~~~ + * + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + * + * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +var stopwords = ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"]; + + +/* Non-minified version is copied as a separate JS file, is available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + + + + +var splitChars = (function() { + var result = {}; + var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648, + 1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702, + 2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971, + 2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345, + 3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761, + 3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823, + 4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125, + 8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695, + 11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587, + 43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141]; + var i, j, start, end; + for (i = 0; i < singles.length; i++) { + result[singles[i]] = true; + } + var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709], + [722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161], + [1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568], + [1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807], + [1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047], + [2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383], + [2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450], + [2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547], + [2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673], + [2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820], + [2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946], + [2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023], + [3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173], + [3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332], + [3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481], + [3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718], + [3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791], + [3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095], + [4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205], + [4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687], + [4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968], + [4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869], + [5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102], + [6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271], + [6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592], + [6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822], + [6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167], + [7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959], + [7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143], + [8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318], + [8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483], + [8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101], + [10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567], + [11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292], + [12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444], + [12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783], + [12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311], + [19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511], + [42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774], + [42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071], + [43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263], + [43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519], + [43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647], + [43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967], + [44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295], + [57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274], + [64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007], + [65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381], + [65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]]; + for (i = 0; i < ranges.length; i++) { + start = ranges[i][0]; + end = ranges[i][1]; + for (j = start; j <= end; j++) { + result[j] = true; + } + } + return result; +})(); + +function splitQuery(query) { + var result = []; + var start = -1; + for (var i = 0; i < query.length; i++) { + if (splitChars[query.charCodeAt(i)]) { + if (start !== -1) { + result.push(query.slice(start, i)); + start = -1; + } + } else if (start === -1) { + start = i; + } + } + if (start !== -1) { + result.push(query.slice(start)); + } + return result; +} + + diff --git a/guide/_static/minus.png b/guide/_static/minus.png Binary files differnew file mode 100644 index 0000000..d96755f --- /dev/null +++ b/guide/_static/minus.png diff --git a/guide/_static/plus.png b/guide/_static/plus.png Binary files differnew file mode 100644 index 0000000..7107cec --- /dev/null +++ b/guide/_static/plus.png diff --git a/guide/_static/pygments.css b/guide/_static/pygments.css new file mode 100644 index 0000000..87f8bd1 --- /dev/null +++ b/guide/_static/pygments.css @@ -0,0 +1,82 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #f8f8f8; } +.highlight .c { color: #8f5902; font-style: italic } /* Comment */ +.highlight .err { color: #a40000; border: 1px solid #ef2929 } /* Error */ +.highlight .g { color: #000000 } /* Generic */ +.highlight .k { color: #004461; font-weight: bold } /* Keyword */ +.highlight .l { color: #000000 } /* Literal */ +.highlight .n { color: #000000 } /* Name */ +.highlight .o { color: #582800 } /* Operator */ +.highlight .x { color: #000000 } /* Other */ +.highlight .p { color: #000000; font-weight: bold } /* Punctuation */ +.highlight .ch { color: #8f5902; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #8f5902 } /* Comment.Preproc */ +.highlight .cpf { color: #8f5902; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #8f5902; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #a40000 } /* Generic.Deleted */ +.highlight .ge { color: #000000; font-style: italic } /* Generic.Emph */ +.highlight .gr { color: #ef2929 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #888888 } /* Generic.Output */ +.highlight .gp { color: #745334 } /* Generic.Prompt */ +.highlight .gs { color: #000000; font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #a40000; font-weight: bold } /* Generic.Traceback */ +.highlight .kc { color: #004461; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #004461; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #004461; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #004461; font-weight: bold } /* Keyword.Pseudo */ +.highlight .kr { color: #004461; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #004461; font-weight: bold } /* Keyword.Type */ +.highlight .ld { color: #000000 } /* Literal.Date */ +.highlight .m { color: #990000 } /* Literal.Number */ +.highlight .s { color: #4e9a06 } /* Literal.String */ +.highlight .na { color: #c4a000 } /* Name.Attribute */ +.highlight .nb { color: #004461 } /* Name.Builtin */ +.highlight .nc { color: #000000 } /* Name.Class */ +.highlight .no { color: #000000 } /* Name.Constant */ +.highlight .nd { color: #888888 } /* Name.Decorator */ +.highlight .ni { color: #ce5c00 } /* Name.Entity */ +.highlight .ne { color: #cc0000; font-weight: bold } /* Name.Exception */ +.highlight .nf { color: #000000 } /* Name.Function */ +.highlight .nl { color: #f57900 } /* Name.Label */ +.highlight .nn { color: #000000 } /* Name.Namespace */ +.highlight .nx { color: #000000 } /* Name.Other */ +.highlight .py { color: #000000 } /* Name.Property */ +.highlight .nt { color: #004461; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #000000 } /* Name.Variable */ +.highlight .ow { color: #004461; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #f8f8f8; text-decoration: underline } /* Text.Whitespace */ +.highlight .mb { color: #990000 } /* Literal.Number.Bin */ +.highlight .mf { color: #990000 } /* Literal.Number.Float */ +.highlight .mh { color: #990000 } /* Literal.Number.Hex */ +.highlight .mi { color: #990000 } /* Literal.Number.Integer */ +.highlight .mo { color: #990000 } /* Literal.Number.Oct */ +.highlight .sa { color: #4e9a06 } /* Literal.String.Affix */ +.highlight .sb { color: #4e9a06 } /* Literal.String.Backtick */ +.highlight .sc { color: #4e9a06 } /* Literal.String.Char */ +.highlight .dl { color: #4e9a06 } /* Literal.String.Delimiter */ +.highlight .sd { color: #8f5902; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4e9a06 } /* Literal.String.Double */ +.highlight .se { color: #4e9a06 } /* Literal.String.Escape */ +.highlight .sh { color: #4e9a06 } /* Literal.String.Heredoc */ +.highlight .si { color: #4e9a06 } /* Literal.String.Interpol */ +.highlight .sx { color: #4e9a06 } /* Literal.String.Other */ +.highlight .sr { color: #4e9a06 } /* Literal.String.Regex */ +.highlight .s1 { color: #4e9a06 } /* Literal.String.Single */ +.highlight .ss { color: #4e9a06 } /* Literal.String.Symbol */ +.highlight .bp { color: #3465a4 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #000000 } /* Name.Function.Magic */ +.highlight .vc { color: #000000 } /* Name.Variable.Class */ +.highlight .vg { color: #000000 } /* Name.Variable.Global */ +.highlight .vi { color: #000000 } /* Name.Variable.Instance */ +.highlight .vm { color: #000000 } /* Name.Variable.Magic */ +.highlight .il { color: #990000 } /* Literal.Number.Integer.Long */
\ No newline at end of file diff --git a/guide/_static/searchtools.js b/guide/_static/searchtools.js new file mode 100644 index 0000000..2d77859 --- /dev/null +++ b/guide/_static/searchtools.js @@ -0,0 +1,529 @@ +/* + * searchtools.js + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for the full-text search. + * + * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +if (!Scorer) { + /** + * Simple result scoring code. + */ + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [filename, title, anchor, descr, score] + // and returns the new score. + /* + score: function(result) { + return result[4]; + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: {0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5}, // used to be unimportantResults + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2 + }; +} + +if (!splitQuery) { + function splitQuery(query) { + return query.split(/\s+/); + } +} + +/** + * Search Module + */ +var Search = { + + _index : null, + _queued_query : null, + _pulse_status : -1, + + htmlToText : function(htmlString) { + var virtualDocument = document.implementation.createHTMLDocument('virtual'); + var htmlElement = $(htmlString, virtualDocument); + htmlElement.find('.headerlink').remove(); + docContent = htmlElement.find('[role=main]')[0]; + if(docContent === undefined) { + console.warn("Content block not found. Sphinx search tries to obtain it " + + "via '[role=main]'. Could you check your theme or template."); + return ""; + } + return docContent.textContent || docContent.innerText; + }, + + init : function() { + var params = $.getQueryParameters(); + if (params.q) { + var query = params.q[0]; + $('input[name="q"]')[0].value = query; + this.performSearch(query); + } + }, + + loadIndex : function(url) { + $.ajax({type: "GET", url: url, data: null, + dataType: "script", cache: true, + complete: function(jqxhr, textstatus) { + if (textstatus != "success") { + document.getElementById("searchindexloader").src = url; + } + }}); + }, + + setIndex : function(index) { + var q; + this._index = index; + if ((q = this._queued_query) !== null) { + this._queued_query = null; + Search.query(q); + } + }, + + hasIndex : function() { + return this._index !== null; + }, + + deferQuery : function(query) { + this._queued_query = query; + }, + + stopPulse : function() { + this._pulse_status = 0; + }, + + startPulse : function() { + if (this._pulse_status >= 0) + return; + function pulse() { + var i; + Search._pulse_status = (Search._pulse_status + 1) % 4; + var dotString = ''; + for (i = 0; i < Search._pulse_status; i++) + dotString += '.'; + Search.dots.text(dotString); + if (Search._pulse_status > -1) + window.setTimeout(pulse, 500); + } + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch : function(query) { + // create the required interface elements + this.out = $('#search-results'); + this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out); + this.dots = $('<span></span>').appendTo(this.title); + this.status = $('<p class="search-summary"> </p>').appendTo(this.out); + this.output = $('<ul class="search"/>').appendTo(this.out); + + $('#search-progress').text(_('Preparing search...')); + this.startPulse(); + + // index already loaded, the browser was quick! + if (this.hasIndex()) + this.query(query); + else + this.deferQuery(query); + }, + + /** + * execute search (requires search index to be loaded) + */ + query : function(query) { + var i; + + // stem the searchterms and add them to the correct list + var stemmer = new Stemmer(); + var searchterms = []; + var excluded = []; + var hlterms = []; + var tmp = splitQuery(query); + var objectterms = []; + for (i = 0; i < tmp.length; i++) { + if (tmp[i] !== "") { + objectterms.push(tmp[i].toLowerCase()); + } + + if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i] === "") { + // skip this "word" + continue; + } + // stem the word + var word = stemmer.stemWord(tmp[i].toLowerCase()); + // prevent stemmer from cutting word smaller than two chars + if(word.length < 3 && tmp[i].length >= 3) { + word = tmp[i]; + } + var toAppend; + // select the correct list + if (word[0] == '-') { + toAppend = excluded; + word = word.substr(1); + } + else { + toAppend = searchterms; + hlterms.push(tmp[i].toLowerCase()); + } + // only add if not already in the list + if (!$u.contains(toAppend, word)) + toAppend.push(word); + } + var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" ")); + + // console.debug('SEARCH: searching for:'); + // console.info('required: ', searchterms); + // console.info('excluded: ', excluded); + + // prepare search + var terms = this._index.terms; + var titleterms = this._index.titleterms; + + // array of [filename, title, anchor, descr, score] + var results = []; + $('#search-progress').empty(); + + // lookup as object + for (i = 0; i < objectterms.length; i++) { + var others = [].concat(objectterms.slice(0, i), + objectterms.slice(i+1, objectterms.length)); + results = results.concat(this.performObjectSearch(objectterms[i], others)); + } + + // lookup as search terms in fulltext + results = results.concat(this.performTermsSearch(searchterms, excluded, terms, titleterms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + for (i = 0; i < results.length; i++) + results[i][4] = Scorer.score(results[i]); + } + + // now sort the results by score (in opposite order of appearance, since the + // display function below uses pop() to retrieve items) and then + // alphabetically + results.sort(function(a, b) { + var left = a[4]; + var right = b[4]; + if (left > right) { + return 1; + } else if (left < right) { + return -1; + } else { + // same score: sort alphabetically + left = a[1].toLowerCase(); + right = b[1].toLowerCase(); + return (left > right) ? -1 : ((left < right) ? 1 : 0); + } + }); + + // for debugging + //Search.lastresults = results.slice(); // a copy + //console.info('search results:', Search.lastresults); + + // print the results + var resultCount = results.length; + function displayNextItem() { + // results left, load the summary and display it + if (results.length) { + var item = results.pop(); + var listItem = $('<li></li>'); + var requestUrl = ""; + var linkUrl = ""; + if (DOCUMENTATION_OPTIONS.BUILDER === 'dirhtml') { + // dirhtml builder + var dirname = item[0] + '/'; + if (dirname.match(/\/index\/$/)) { + dirname = dirname.substring(0, dirname.length-6); + } else if (dirname == 'index/') { + dirname = ''; + } + requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + dirname; + linkUrl = requestUrl; + + } else { + // normal html builders + requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX; + linkUrl = item[0] + DOCUMENTATION_OPTIONS.LINK_SUFFIX; + } + listItem.append($('<a/>').attr('href', + linkUrl + + highlightstring + item[2]).html(item[1])); + if (item[3]) { + listItem.append($('<span> (' + item[3] + ')</span>')); + Search.output.append(listItem); + setTimeout(function() { + displayNextItem(); + }, 5); + } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { + $.ajax({url: requestUrl, + dataType: "text", + complete: function(jqxhr, textstatus) { + var data = jqxhr.responseText; + if (data !== '' && data !== undefined) { + var summary = Search.makeSearchSummary(data, searchterms, hlterms); + if (summary) { + listItem.append(summary); + } + } + Search.output.append(listItem); + setTimeout(function() { + displayNextItem(); + }, 5); + }}); + } else { + // no source available, just display title + Search.output.append(listItem); + setTimeout(function() { + displayNextItem(); + }, 5); + } + } + // search finished, update title and status message + else { + Search.stopPulse(); + Search.title.text(_('Search Results')); + if (!resultCount) + Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.')); + else + Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount)); + Search.status.fadeIn(500); + } + } + displayNextItem(); + }, + + /** + * search for object names + */ + performObjectSearch : function(object, otherterms) { + var filenames = this._index.filenames; + var docnames = this._index.docnames; + var objects = this._index.objects; + var objnames = this._index.objnames; + var titles = this._index.titles; + + var i; + var results = []; + + for (var prefix in objects) { + for (var iMatch = 0; iMatch != objects[prefix].length; ++iMatch) { + var match = objects[prefix][iMatch]; + var name = match[4]; + var fullname = (prefix ? prefix + '.' : '') + name; + var fullnameLower = fullname.toLowerCase() + if (fullnameLower.indexOf(object) > -1) { + var score = 0; + var parts = fullnameLower.split('.'); + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower == object || parts[parts.length - 1] == object) { + score += Scorer.objNameMatch; + // matches in last name + } else if (parts[parts.length - 1].indexOf(object) > -1) { + score += Scorer.objPartialMatch; + } + var objname = objnames[match[1]][2]; + var title = titles[match[0]]; + // If more than one term searched for, we require other words to be + // found in the name/title/description + if (otherterms.length > 0) { + var haystack = (prefix + ' ' + name + ' ' + + objname + ' ' + title).toLowerCase(); + var allfound = true; + for (i = 0; i < otherterms.length; i++) { + if (haystack.indexOf(otherterms[i]) == -1) { + allfound = false; + break; + } + } + if (!allfound) { + continue; + } + } + var descr = objname + _(', in ') + title; + + var anchor = match[3]; + if (anchor === '') + anchor = fullname; + else if (anchor == '-') + anchor = objnames[match[1]][1] + '-' + fullname; + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) { + score += Scorer.objPrio[match[2]]; + } else { + score += Scorer.objPrioDefault; + } + results.push([docnames[match[0]], fullname, '#'+anchor, descr, score, filenames[match[0]]]); + } + } + } + + return results; + }, + + /** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions + */ + escapeRegExp : function(string) { + return string.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch : function(searchterms, excluded, terms, titleterms) { + var docnames = this._index.docnames; + var filenames = this._index.filenames; + var titles = this._index.titles; + + var i, j, file; + var fileMap = {}; + var scoreMap = {}; + var results = []; + + // perform the search on the required terms + for (i = 0; i < searchterms.length; i++) { + var word = searchterms[i]; + var files = []; + var _o = [ + {files: terms[word], score: Scorer.term}, + {files: titleterms[word], score: Scorer.title} + ]; + // add support for partial matches + if (word.length > 2) { + var word_regex = this.escapeRegExp(word); + for (var w in terms) { + if (w.match(word_regex) && !terms[word]) { + _o.push({files: terms[w], score: Scorer.partialTerm}) + } + } + for (var w in titleterms) { + if (w.match(word_regex) && !titleterms[word]) { + _o.push({files: titleterms[w], score: Scorer.partialTitle}) + } + } + } + + // no match but word was a required one + if ($u.every(_o, function(o){return o.files === undefined;})) { + break; + } + // found search word in contents + $u.each(_o, function(o) { + var _files = o.files; + if (_files === undefined) + return + + if (_files.length === undefined) + _files = [_files]; + files = files.concat(_files); + + // set score for the word in each file to Scorer.term + for (j = 0; j < _files.length; j++) { + file = _files[j]; + if (!(file in scoreMap)) + scoreMap[file] = {}; + scoreMap[file][word] = o.score; + } + }); + + // create the mapping + for (j = 0; j < files.length; j++) { + file = files[j]; + if (file in fileMap && fileMap[file].indexOf(word) === -1) + fileMap[file].push(word); + else + fileMap[file] = [word]; + } + } + + // now check if the files don't contain excluded terms + for (file in fileMap) { + var valid = true; + + // check if all requirements are matched + var filteredTermCount = // as search terms with length < 3 are discarded: ignore + searchterms.filter(function(term){return term.length > 2}).length + if ( + fileMap[file].length != searchterms.length && + fileMap[file].length != filteredTermCount + ) continue; + + // ensure that none of the excluded terms is in the search result + for (i = 0; i < excluded.length; i++) { + if (terms[excluded[i]] == file || + titleterms[excluded[i]] == file || + $u.contains(terms[excluded[i]] || [], file) || + $u.contains(titleterms[excluded[i]] || [], file)) { + valid = false; + break; + } + } + + // if we have still a valid result we can add it to the result list + if (valid) { + // select one (max) score for the file. + // for better ranking, we should calculate ranking by using words statistics like basic tf-idf... + var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]})); + results.push([docnames[file], titles[file], '', null, score, filenames[file]]); + } + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words, hlwords is the list of normal, unstemmed + * words. the first one is used to find the occurrence, the + * latter for highlighting it. + */ + makeSearchSummary : function(htmlText, keywords, hlwords) { + var text = Search.htmlToText(htmlText); + if (text == "") { + return null; + } + var textLower = text.toLowerCase(); + var start = 0; + $.each(keywords, function() { + var i = textLower.indexOf(this.toLowerCase()); + if (i > -1) + start = i; + }); + start = Math.max(start - 120, 0); + var excerpt = ((start > 0) ? '...' : '') + + $.trim(text.substr(start, 240)) + + ((start + 240 - text.length) ? '...' : ''); + var rv = $('<p class="context"></p>').text(excerpt); + $.each(hlwords, function() { + rv = rv.highlightText(this, 'highlighted'); + }); + return rv; + } +}; + +$(document).ready(function() { + Search.init(); +}); diff --git a/guide/_static/underscore-1.13.1.js b/guide/_static/underscore-1.13.1.js new file mode 100644 index 0000000..ffd77af --- /dev/null +++ b/guide/_static/underscore-1.13.1.js @@ -0,0 +1,2042 @@ +(function (global, factory) { + typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() : + typeof define === 'function' && define.amd ? define('underscore', factory) : + (global = typeof globalThis !== 'undefined' ? globalThis : global || self, (function () { + var current = global._; + var exports = global._ = factory(); + exports.noConflict = function () { global._ = current; return exports; }; + }())); +}(this, (function () { + // Underscore.js 1.13.1 + // https://underscorejs.org + // (c) 2009-2021 Jeremy Ashkenas, Julian Gonggrijp, and DocumentCloud and Investigative Reporters & Editors + // Underscore may be freely distributed under the MIT license. + + // Current version. + var VERSION = '1.13.1'; + + // Establish the root object, `window` (`self`) in the browser, `global` + // on the server, or `this` in some virtual machines. We use `self` + // instead of `window` for `WebWorker` support. + var root = typeof self == 'object' && self.self === self && self || + typeof global == 'object' && global.global === global && global || + Function('return this')() || + {}; + + // Save bytes in the minified (but not gzipped) version: + var ArrayProto = Array.prototype, ObjProto = Object.prototype; + var SymbolProto = typeof Symbol !== 'undefined' ? Symbol.prototype : null; + + // Create quick reference variables for speed access to core prototypes. + var push = ArrayProto.push, + slice = ArrayProto.slice, + toString = ObjProto.toString, + hasOwnProperty = ObjProto.hasOwnProperty; + + // Modern feature detection. + var supportsArrayBuffer = typeof ArrayBuffer !== 'undefined', + supportsDataView = typeof DataView !== 'undefined'; + + // All **ECMAScript 5+** native function implementations that we hope to use + // are declared here. + var nativeIsArray = Array.isArray, + nativeKeys = Object.keys, + nativeCreate = Object.create, + nativeIsView = supportsArrayBuffer && ArrayBuffer.isView; + + // Create references to these builtin functions because we override them. + var _isNaN = isNaN, + _isFinite = isFinite; + + // Keys in IE < 9 that won't be iterated by `for key in ...` and thus missed. + var hasEnumBug = !{toString: null}.propertyIsEnumerable('toString'); + var nonEnumerableProps = ['valueOf', 'isPrototypeOf', 'toString', + 'propertyIsEnumerable', 'hasOwnProperty', 'toLocaleString']; + + // The largest integer that can be represented exactly. + var MAX_ARRAY_INDEX = Math.pow(2, 53) - 1; + + // Some functions take a variable number of arguments, or a few expected + // arguments at the beginning and then a variable number of values to operate + // on. This helper accumulates all remaining arguments past the function’s + // argument length (or an explicit `startIndex`), into an array that becomes + // the last argument. Similar to ES6’s "rest parameter". + function restArguments(func, startIndex) { + startIndex = startIndex == null ? func.length - 1 : +startIndex; + return function() { + var length = Math.max(arguments.length - startIndex, 0), + rest = Array(length), + index = 0; + for (; index < length; index++) { + rest[index] = arguments[index + startIndex]; + } + switch (startIndex) { + case 0: return func.call(this, rest); + case 1: return func.call(this, arguments[0], rest); + case 2: return func.call(this, arguments[0], arguments[1], rest); + } + var args = Array(startIndex + 1); + for (index = 0; index < startIndex; index++) { + args[index] = arguments[index]; + } + args[startIndex] = rest; + return func.apply(this, args); + }; + } + + // Is a given variable an object? + function isObject(obj) { + var type = typeof obj; + return type === 'function' || type === 'object' && !!obj; + } + + // Is a given value equal to null? + function isNull(obj) { + return obj === null; + } + + // Is a given variable undefined? + function isUndefined(obj) { + return obj === void 0; + } + + // Is a given value a boolean? + function isBoolean(obj) { + return obj === true || obj === false || toString.call(obj) === '[object Boolean]'; + } + + // Is a given value a DOM element? + function isElement(obj) { + return !!(obj && obj.nodeType === 1); + } + + // Internal function for creating a `toString`-based type tester. + function tagTester(name) { + var tag = '[object ' + name + ']'; + return function(obj) { + return toString.call(obj) === tag; + }; + } + + var isString = tagTester('String'); + + var isNumber = tagTester('Number'); + + var isDate = tagTester('Date'); + + var isRegExp = tagTester('RegExp'); + + var isError = tagTester('Error'); + + var isSymbol = tagTester('Symbol'); + + var isArrayBuffer = tagTester('ArrayBuffer'); + + var isFunction = tagTester('Function'); + + // Optimize `isFunction` if appropriate. Work around some `typeof` bugs in old + // v8, IE 11 (#1621), Safari 8 (#1929), and PhantomJS (#2236). + var nodelist = root.document && root.document.childNodes; + if (typeof /./ != 'function' && typeof Int8Array != 'object' && typeof nodelist != 'function') { + isFunction = function(obj) { + return typeof obj == 'function' || false; + }; + } + + var isFunction$1 = isFunction; + + var hasObjectTag = tagTester('Object'); + + // In IE 10 - Edge 13, `DataView` has string tag `'[object Object]'`. + // In IE 11, the most common among them, this problem also applies to + // `Map`, `WeakMap` and `Set`. + var hasStringTagBug = ( + supportsDataView && hasObjectTag(new DataView(new ArrayBuffer(8))) + ), + isIE11 = (typeof Map !== 'undefined' && hasObjectTag(new Map)); + + var isDataView = tagTester('DataView'); + + // In IE 10 - Edge 13, we need a different heuristic + // to determine whether an object is a `DataView`. + function ie10IsDataView(obj) { + return obj != null && isFunction$1(obj.getInt8) && isArrayBuffer(obj.buffer); + } + + var isDataView$1 = (hasStringTagBug ? ie10IsDataView : isDataView); + + // Is a given value an array? + // Delegates to ECMA5's native `Array.isArray`. + var isArray = nativeIsArray || tagTester('Array'); + + // Internal function to check whether `key` is an own property name of `obj`. + function has$1(obj, key) { + return obj != null && hasOwnProperty.call(obj, key); + } + + var isArguments = tagTester('Arguments'); + + // Define a fallback version of the method in browsers (ahem, IE < 9), where + // there isn't any inspectable "Arguments" type. + (function() { + if (!isArguments(arguments)) { + isArguments = function(obj) { + return has$1(obj, 'callee'); + }; + } + }()); + + var isArguments$1 = isArguments; + + // Is a given object a finite number? + function isFinite$1(obj) { + return !isSymbol(obj) && _isFinite(obj) && !isNaN(parseFloat(obj)); + } + + // Is the given value `NaN`? + function isNaN$1(obj) { + return isNumber(obj) && _isNaN(obj); + } + + // Predicate-generating function. Often useful outside of Underscore. + function constant(value) { + return function() { + return value; + }; + } + + // Common internal logic for `isArrayLike` and `isBufferLike`. + function createSizePropertyCheck(getSizeProperty) { + return function(collection) { + var sizeProperty = getSizeProperty(collection); + return typeof sizeProperty == 'number' && sizeProperty >= 0 && sizeProperty <= MAX_ARRAY_INDEX; + } + } + + // Internal helper to generate a function to obtain property `key` from `obj`. + function shallowProperty(key) { + return function(obj) { + return obj == null ? void 0 : obj[key]; + }; + } + + // Internal helper to obtain the `byteLength` property of an object. + var getByteLength = shallowProperty('byteLength'); + + // Internal helper to determine whether we should spend extensive checks against + // `ArrayBuffer` et al. + var isBufferLike = createSizePropertyCheck(getByteLength); + + // Is a given value a typed array? + var typedArrayPattern = /\[object ((I|Ui)nt(8|16|32)|Float(32|64)|Uint8Clamped|Big(I|Ui)nt64)Array\]/; + function isTypedArray(obj) { + // `ArrayBuffer.isView` is the most future-proof, so use it when available. + // Otherwise, fall back on the above regular expression. + return nativeIsView ? (nativeIsView(obj) && !isDataView$1(obj)) : + isBufferLike(obj) && typedArrayPattern.test(toString.call(obj)); + } + + var isTypedArray$1 = supportsArrayBuffer ? isTypedArray : constant(false); + + // Internal helper to obtain the `length` property of an object. + var getLength = shallowProperty('length'); + + // Internal helper to create a simple lookup structure. + // `collectNonEnumProps` used to depend on `_.contains`, but this led to + // circular imports. `emulatedSet` is a one-off solution that only works for + // arrays of strings. + function emulatedSet(keys) { + var hash = {}; + for (var l = keys.length, i = 0; i < l; ++i) hash[keys[i]] = true; + return { + contains: function(key) { return hash[key]; }, + push: function(key) { + hash[key] = true; + return keys.push(key); + } + }; + } + + // Internal helper. Checks `keys` for the presence of keys in IE < 9 that won't + // be iterated by `for key in ...` and thus missed. Extends `keys` in place if + // needed. + function collectNonEnumProps(obj, keys) { + keys = emulatedSet(keys); + var nonEnumIdx = nonEnumerableProps.length; + var constructor = obj.constructor; + var proto = isFunction$1(constructor) && constructor.prototype || ObjProto; + + // Constructor is a special case. + var prop = 'constructor'; + if (has$1(obj, prop) && !keys.contains(prop)) keys.push(prop); + + while (nonEnumIdx--) { + prop = nonEnumerableProps[nonEnumIdx]; + if (prop in obj && obj[prop] !== proto[prop] && !keys.contains(prop)) { + keys.push(prop); + } + } + } + + // Retrieve the names of an object's own properties. + // Delegates to **ECMAScript 5**'s native `Object.keys`. + function keys(obj) { + if (!isObject(obj)) return []; + if (nativeKeys) return nativeKeys(obj); + var keys = []; + for (var key in obj) if (has$1(obj, key)) keys.push(key); + // Ahem, IE < 9. + if (hasEnumBug) collectNonEnumProps(obj, keys); + return keys; + } + + // Is a given array, string, or object empty? + // An "empty" object has no enumerable own-properties. + function isEmpty(obj) { + if (obj == null) return true; + // Skip the more expensive `toString`-based type checks if `obj` has no + // `.length`. + var length = getLength(obj); + if (typeof length == 'number' && ( + isArray(obj) || isString(obj) || isArguments$1(obj) + )) return length === 0; + return getLength(keys(obj)) === 0; + } + + // Returns whether an object has a given set of `key:value` pairs. + function isMatch(object, attrs) { + var _keys = keys(attrs), length = _keys.length; + if (object == null) return !length; + var obj = Object(object); + for (var i = 0; i < length; i++) { + var key = _keys[i]; + if (attrs[key] !== obj[key] || !(key in obj)) return false; + } + return true; + } + + // If Underscore is called as a function, it returns a wrapped object that can + // be used OO-style. This wrapper holds altered versions of all functions added + // through `_.mixin`. Wrapped objects may be chained. + function _$1(obj) { + if (obj instanceof _$1) return obj; + if (!(this instanceof _$1)) return new _$1(obj); + this._wrapped = obj; + } + + _$1.VERSION = VERSION; + + // Extracts the result from a wrapped and chained object. + _$1.prototype.value = function() { + return this._wrapped; + }; + + // Provide unwrapping proxies for some methods used in engine operations + // such as arithmetic and JSON stringification. + _$1.prototype.valueOf = _$1.prototype.toJSON = _$1.prototype.value; + + _$1.prototype.toString = function() { + return String(this._wrapped); + }; + + // Internal function to wrap or shallow-copy an ArrayBuffer, + // typed array or DataView to a new view, reusing the buffer. + function toBufferView(bufferSource) { + return new Uint8Array( + bufferSource.buffer || bufferSource, + bufferSource.byteOffset || 0, + getByteLength(bufferSource) + ); + } + + // We use this string twice, so give it a name for minification. + var tagDataView = '[object DataView]'; + + // Internal recursive comparison function for `_.isEqual`. + function eq(a, b, aStack, bStack) { + // Identical objects are equal. `0 === -0`, but they aren't identical. + // See the [Harmony `egal` proposal](https://wiki.ecmascript.org/doku.php?id=harmony:egal). + if (a === b) return a !== 0 || 1 / a === 1 / b; + // `null` or `undefined` only equal to itself (strict comparison). + if (a == null || b == null) return false; + // `NaN`s are equivalent, but non-reflexive. + if (a !== a) return b !== b; + // Exhaust primitive checks + var type = typeof a; + if (type !== 'function' && type !== 'object' && typeof b != 'object') return false; + return deepEq(a, b, aStack, bStack); + } + + // Internal recursive comparison function for `_.isEqual`. + function deepEq(a, b, aStack, bStack) { + // Unwrap any wrapped objects. + if (a instanceof _$1) a = a._wrapped; + if (b instanceof _$1) b = b._wrapped; + // Compare `[[Class]]` names. + var className = toString.call(a); + if (className !== toString.call(b)) return false; + // Work around a bug in IE 10 - Edge 13. + if (hasStringTagBug && className == '[object Object]' && isDataView$1(a)) { + if (!isDataView$1(b)) return false; + className = tagDataView; + } + switch (className) { + // These types are compared by value. + case '[object RegExp]': + // RegExps are coerced to strings for comparison (Note: '' + /a/i === '/a/i') + case '[object String]': + // Primitives and their corresponding object wrappers are equivalent; thus, `"5"` is + // equivalent to `new String("5")`. + return '' + a === '' + b; + case '[object Number]': + // `NaN`s are equivalent, but non-reflexive. + // Object(NaN) is equivalent to NaN. + if (+a !== +a) return +b !== +b; + // An `egal` comparison is performed for other numeric values. + return +a === 0 ? 1 / +a === 1 / b : +a === +b; + case '[object Date]': + case '[object Boolean]': + // Coerce dates and booleans to numeric primitive values. Dates are compared by their + // millisecond representations. Note that invalid dates with millisecond representations + // of `NaN` are not equivalent. + return +a === +b; + case '[object Symbol]': + return SymbolProto.valueOf.call(a) === SymbolProto.valueOf.call(b); + case '[object ArrayBuffer]': + case tagDataView: + // Coerce to typed array so we can fall through. + return deepEq(toBufferView(a), toBufferView(b), aStack, bStack); + } + + var areArrays = className === '[object Array]'; + if (!areArrays && isTypedArray$1(a)) { + var byteLength = getByteLength(a); + if (byteLength !== getByteLength(b)) return false; + if (a.buffer === b.buffer && a.byteOffset === b.byteOffset) return true; + areArrays = true; + } + if (!areArrays) { + if (typeof a != 'object' || typeof b != 'object') return false; + + // Objects with different constructors are not equivalent, but `Object`s or `Array`s + // from different frames are. + var aCtor = a.constructor, bCtor = b.constructor; + if (aCtor !== bCtor && !(isFunction$1(aCtor) && aCtor instanceof aCtor && + isFunction$1(bCtor) && bCtor instanceof bCtor) + && ('constructor' in a && 'constructor' in b)) { + return false; + } + } + // Assume equality for cyclic structures. The algorithm for detecting cyclic + // structures is adapted from ES 5.1 section 15.12.3, abstract operation `JO`. + + // Initializing stack of traversed objects. + // It's done here since we only need them for objects and arrays comparison. + aStack = aStack || []; + bStack = bStack || []; + var length = aStack.length; + while (length--) { + // Linear search. Performance is inversely proportional to the number of + // unique nested structures. + if (aStack[length] === a) return bStack[length] === b; + } + + // Add the first object to the stack of traversed objects. + aStack.push(a); + bStack.push(b); + + // Recursively compare objects and arrays. + if (areArrays) { + // Compare array lengths to determine if a deep comparison is necessary. + length = a.length; + if (length !== b.length) return false; + // Deep compare the contents, ignoring non-numeric properties. + while (length--) { + if (!eq(a[length], b[length], aStack, bStack)) return false; + } + } else { + // Deep compare objects. + var _keys = keys(a), key; + length = _keys.length; + // Ensure that both objects contain the same number of properties before comparing deep equality. + if (keys(b).length !== length) return false; + while (length--) { + // Deep compare each member + key = _keys[length]; + if (!(has$1(b, key) && eq(a[key], b[key], aStack, bStack))) return false; + } + } + // Remove the first object from the stack of traversed objects. + aStack.pop(); + bStack.pop(); + return true; + } + + // Perform a deep comparison to check if two objects are equal. + function isEqual(a, b) { + return eq(a, b); + } + + // Retrieve all the enumerable property names of an object. + function allKeys(obj) { + if (!isObject(obj)) return []; + var keys = []; + for (var key in obj) keys.push(key); + // Ahem, IE < 9. + if (hasEnumBug) collectNonEnumProps(obj, keys); + return keys; + } + + // Since the regular `Object.prototype.toString` type tests don't work for + // some types in IE 11, we use a fingerprinting heuristic instead, based + // on the methods. It's not great, but it's the best we got. + // The fingerprint method lists are defined below. + function ie11fingerprint(methods) { + var length = getLength(methods); + return function(obj) { + if (obj == null) return false; + // `Map`, `WeakMap` and `Set` have no enumerable keys. + var keys = allKeys(obj); + if (getLength(keys)) return false; + for (var i = 0; i < length; i++) { + if (!isFunction$1(obj[methods[i]])) return false; + } + // If we are testing against `WeakMap`, we need to ensure that + // `obj` doesn't have a `forEach` method in order to distinguish + // it from a regular `Map`. + return methods !== weakMapMethods || !isFunction$1(obj[forEachName]); + }; + } + + // In the interest of compact minification, we write + // each string in the fingerprints only once. + var forEachName = 'forEach', + hasName = 'has', + commonInit = ['clear', 'delete'], + mapTail = ['get', hasName, 'set']; + + // `Map`, `WeakMap` and `Set` each have slightly different + // combinations of the above sublists. + var mapMethods = commonInit.concat(forEachName, mapTail), + weakMapMethods = commonInit.concat(mapTail), + setMethods = ['add'].concat(commonInit, forEachName, hasName); + + var isMap = isIE11 ? ie11fingerprint(mapMethods) : tagTester('Map'); + + var isWeakMap = isIE11 ? ie11fingerprint(weakMapMethods) : tagTester('WeakMap'); + + var isSet = isIE11 ? ie11fingerprint(setMethods) : tagTester('Set'); + + var isWeakSet = tagTester('WeakSet'); + + // Retrieve the values of an object's properties. + function values(obj) { + var _keys = keys(obj); + var length = _keys.length; + var values = Array(length); + for (var i = 0; i < length; i++) { + values[i] = obj[_keys[i]]; + } + return values; + } + + // Convert an object into a list of `[key, value]` pairs. + // The opposite of `_.object` with one argument. + function pairs(obj) { + var _keys = keys(obj); + var length = _keys.length; + var pairs = Array(length); + for (var i = 0; i < length; i++) { + pairs[i] = [_keys[i], obj[_keys[i]]]; + } + return pairs; + } + + // Invert the keys and values of an object. The values must be serializable. + function invert(obj) { + var result = {}; + var _keys = keys(obj); + for (var i = 0, length = _keys.length; i < length; i++) { + result[obj[_keys[i]]] = _keys[i]; + } + return result; + } + + // Return a sorted list of the function names available on the object. + function functions(obj) { + var names = []; + for (var key in obj) { + if (isFunction$1(obj[key])) names.push(key); + } + return names.sort(); + } + + // An internal function for creating assigner functions. + function createAssigner(keysFunc, defaults) { + return function(obj) { + var length = arguments.length; + if (defaults) obj = Object(obj); + if (length < 2 || obj == null) return obj; + for (var index = 1; index < length; index++) { + var source = arguments[index], + keys = keysFunc(source), + l = keys.length; + for (var i = 0; i < l; i++) { + var key = keys[i]; + if (!defaults || obj[key] === void 0) obj[key] = source[key]; + } + } + return obj; + }; + } + + // Extend a given object with all the properties in passed-in object(s). + var extend = createAssigner(allKeys); + + // Assigns a given object with all the own properties in the passed-in + // object(s). + // (https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) + var extendOwn = createAssigner(keys); + + // Fill in a given object with default properties. + var defaults = createAssigner(allKeys, true); + + // Create a naked function reference for surrogate-prototype-swapping. + function ctor() { + return function(){}; + } + + // An internal function for creating a new object that inherits from another. + function baseCreate(prototype) { + if (!isObject(prototype)) return {}; + if (nativeCreate) return nativeCreate(prototype); + var Ctor = ctor(); + Ctor.prototype = prototype; + var result = new Ctor; + Ctor.prototype = null; + return result; + } + + // Creates an object that inherits from the given prototype object. + // If additional properties are provided then they will be added to the + // created object. + function create(prototype, props) { + var result = baseCreate(prototype); + if (props) extendOwn(result, props); + return result; + } + + // Create a (shallow-cloned) duplicate of an object. + function clone(obj) { + if (!isObject(obj)) return obj; + return isArray(obj) ? obj.slice() : extend({}, obj); + } + + // Invokes `interceptor` with the `obj` and then returns `obj`. + // The primary purpose of this method is to "tap into" a method chain, in + // order to perform operations on intermediate results within the chain. + function tap(obj, interceptor) { + interceptor(obj); + return obj; + } + + // Normalize a (deep) property `path` to array. + // Like `_.iteratee`, this function can be customized. + function toPath$1(path) { + return isArray(path) ? path : [path]; + } + _$1.toPath = toPath$1; + + // Internal wrapper for `_.toPath` to enable minification. + // Similar to `cb` for `_.iteratee`. + function toPath(path) { + return _$1.toPath(path); + } + + // Internal function to obtain a nested property in `obj` along `path`. + function deepGet(obj, path) { + var length = path.length; + for (var i = 0; i < length; i++) { + if (obj == null) return void 0; + obj = obj[path[i]]; + } + return length ? obj : void 0; + } + + // Get the value of the (deep) property on `path` from `object`. + // If any property in `path` does not exist or if the value is + // `undefined`, return `defaultValue` instead. + // The `path` is normalized through `_.toPath`. + function get(object, path, defaultValue) { + var value = deepGet(object, toPath(path)); + return isUndefined(value) ? defaultValue : value; + } + + // Shortcut function for checking if an object has a given property directly on + // itself (in other words, not on a prototype). Unlike the internal `has` + // function, this public version can also traverse nested properties. + function has(obj, path) { + path = toPath(path); + var length = path.length; + for (var i = 0; i < length; i++) { + var key = path[i]; + if (!has$1(obj, key)) return false; + obj = obj[key]; + } + return !!length; + } + + // Keep the identity function around for default iteratees. + function identity(value) { + return value; + } + + // Returns a predicate for checking whether an object has a given set of + // `key:value` pairs. + function matcher(attrs) { + attrs = extendOwn({}, attrs); + return function(obj) { + return isMatch(obj, attrs); + }; + } + + // Creates a function that, when passed an object, will traverse that object’s + // properties down the given `path`, specified as an array of keys or indices. + function property(path) { + path = toPath(path); + return function(obj) { + return deepGet(obj, path); + }; + } + + // Internal function that returns an efficient (for current engines) version + // of the passed-in callback, to be repeatedly applied in other Underscore + // functions. + function optimizeCb(func, context, argCount) { + if (context === void 0) return func; + switch (argCount == null ? 3 : argCount) { + case 1: return function(value) { + return func.call(context, value); + }; + // The 2-argument case is omitted because we’re not using it. + case 3: return function(value, index, collection) { + return func.call(context, value, index, collection); + }; + case 4: return function(accumulator, value, index, collection) { + return func.call(context, accumulator, value, index, collection); + }; + } + return function() { + return func.apply(context, arguments); + }; + } + + // An internal function to generate callbacks that can be applied to each + // element in a collection, returning the desired result — either `_.identity`, + // an arbitrary callback, a property matcher, or a property accessor. + function baseIteratee(value, context, argCount) { + if (value == null) return identity; + if (isFunction$1(value)) return optimizeCb(value, context, argCount); + if (isObject(value) && !isArray(value)) return matcher(value); + return property(value); + } + + // External wrapper for our callback generator. Users may customize + // `_.iteratee` if they want additional predicate/iteratee shorthand styles. + // This abstraction hides the internal-only `argCount` argument. + function iteratee(value, context) { + return baseIteratee(value, context, Infinity); + } + _$1.iteratee = iteratee; + + // The function we call internally to generate a callback. It invokes + // `_.iteratee` if overridden, otherwise `baseIteratee`. + function cb(value, context, argCount) { + if (_$1.iteratee !== iteratee) return _$1.iteratee(value, context); + return baseIteratee(value, context, argCount); + } + + // Returns the results of applying the `iteratee` to each element of `obj`. + // In contrast to `_.map` it returns an object. + function mapObject(obj, iteratee, context) { + iteratee = cb(iteratee, context); + var _keys = keys(obj), + length = _keys.length, + results = {}; + for (var index = 0; index < length; index++) { + var currentKey = _keys[index]; + results[currentKey] = iteratee(obj[currentKey], currentKey, obj); + } + return results; + } + + // Predicate-generating function. Often useful outside of Underscore. + function noop(){} + + // Generates a function for a given object that returns a given property. + function propertyOf(obj) { + if (obj == null) return noop; + return function(path) { + return get(obj, path); + }; + } + + // Run a function **n** times. + function times(n, iteratee, context) { + var accum = Array(Math.max(0, n)); + iteratee = optimizeCb(iteratee, context, 1); + for (var i = 0; i < n; i++) accum[i] = iteratee(i); + return accum; + } + + // Return a random integer between `min` and `max` (inclusive). + function random(min, max) { + if (max == null) { + max = min; + min = 0; + } + return min + Math.floor(Math.random() * (max - min + 1)); + } + + // A (possibly faster) way to get the current timestamp as an integer. + var now = Date.now || function() { + return new Date().getTime(); + }; + + // Internal helper to generate functions for escaping and unescaping strings + // to/from HTML interpolation. + function createEscaper(map) { + var escaper = function(match) { + return map[match]; + }; + // Regexes for identifying a key that needs to be escaped. + var source = '(?:' + keys(map).join('|') + ')'; + var testRegexp = RegExp(source); + var replaceRegexp = RegExp(source, 'g'); + return function(string) { + string = string == null ? '' : '' + string; + return testRegexp.test(string) ? string.replace(replaceRegexp, escaper) : string; + }; + } + + // Internal list of HTML entities for escaping. + var escapeMap = { + '&': '&', + '<': '<', + '>': '>', + '"': '"', + "'": ''', + '`': '`' + }; + + // Function for escaping strings to HTML interpolation. + var _escape = createEscaper(escapeMap); + + // Internal list of HTML entities for unescaping. + var unescapeMap = invert(escapeMap); + + // Function for unescaping strings from HTML interpolation. + var _unescape = createEscaper(unescapeMap); + + // By default, Underscore uses ERB-style template delimiters. Change the + // following template settings to use alternative delimiters. + var templateSettings = _$1.templateSettings = { + evaluate: /<%([\s\S]+?)%>/g, + interpolate: /<%=([\s\S]+?)%>/g, + escape: /<%-([\s\S]+?)%>/g + }; + + // When customizing `_.templateSettings`, if you don't want to define an + // interpolation, evaluation or escaping regex, we need one that is + // guaranteed not to match. + var noMatch = /(.)^/; + + // Certain characters need to be escaped so that they can be put into a + // string literal. + var escapes = { + "'": "'", + '\\': '\\', + '\r': 'r', + '\n': 'n', + '\u2028': 'u2028', + '\u2029': 'u2029' + }; + + var escapeRegExp = /\\|'|\r|\n|\u2028|\u2029/g; + + function escapeChar(match) { + return '\\' + escapes[match]; + } + + // In order to prevent third-party code injection through + // `_.templateSettings.variable`, we test it against the following regular + // expression. It is intentionally a bit more liberal than just matching valid + // identifiers, but still prevents possible loopholes through defaults or + // destructuring assignment. + var bareIdentifier = /^\s*(\w|\$)+\s*$/; + + // JavaScript micro-templating, similar to John Resig's implementation. + // Underscore templating handles arbitrary delimiters, preserves whitespace, + // and correctly escapes quotes within interpolated code. + // NB: `oldSettings` only exists for backwards compatibility. + function template(text, settings, oldSettings) { + if (!settings && oldSettings) settings = oldSettings; + settings = defaults({}, settings, _$1.templateSettings); + + // Combine delimiters into one regular expression via alternation. + var matcher = RegExp([ + (settings.escape || noMatch).source, + (settings.interpolate || noMatch).source, + (settings.evaluate || noMatch).source + ].join('|') + '|$', 'g'); + + // Compile the template source, escaping string literals appropriately. + var index = 0; + var source = "__p+='"; + text.replace(matcher, function(match, escape, interpolate, evaluate, offset) { + source += text.slice(index, offset).replace(escapeRegExp, escapeChar); + index = offset + match.length; + + if (escape) { + source += "'+\n((__t=(" + escape + "))==null?'':_.escape(__t))+\n'"; + } else if (interpolate) { + source += "'+\n((__t=(" + interpolate + "))==null?'':__t)+\n'"; + } else if (evaluate) { + source += "';\n" + evaluate + "\n__p+='"; + } + + // Adobe VMs need the match returned to produce the correct offset. + return match; + }); + source += "';\n"; + + var argument = settings.variable; + if (argument) { + // Insure against third-party code injection. (CVE-2021-23358) + if (!bareIdentifier.test(argument)) throw new Error( + 'variable is not a bare identifier: ' + argument + ); + } else { + // If a variable is not specified, place data values in local scope. + source = 'with(obj||{}){\n' + source + '}\n'; + argument = 'obj'; + } + + source = "var __t,__p='',__j=Array.prototype.join," + + "print=function(){__p+=__j.call(arguments,'');};\n" + + source + 'return __p;\n'; + + var render; + try { + render = new Function(argument, '_', source); + } catch (e) { + e.source = source; + throw e; + } + + var template = function(data) { + return render.call(this, data, _$1); + }; + + // Provide the compiled source as a convenience for precompilation. + template.source = 'function(' + argument + '){\n' + source + '}'; + + return template; + } + + // Traverses the children of `obj` along `path`. If a child is a function, it + // is invoked with its parent as context. Returns the value of the final + // child, or `fallback` if any child is undefined. + function result(obj, path, fallback) { + path = toPath(path); + var length = path.length; + if (!length) { + return isFunction$1(fallback) ? fallback.call(obj) : fallback; + } + for (var i = 0; i < length; i++) { + var prop = obj == null ? void 0 : obj[path[i]]; + if (prop === void 0) { + prop = fallback; + i = length; // Ensure we don't continue iterating. + } + obj = isFunction$1(prop) ? prop.call(obj) : prop; + } + return obj; + } + + // Generate a unique integer id (unique within the entire client session). + // Useful for temporary DOM ids. + var idCounter = 0; + function uniqueId(prefix) { + var id = ++idCounter + ''; + return prefix ? prefix + id : id; + } + + // Start chaining a wrapped Underscore object. + function chain(obj) { + var instance = _$1(obj); + instance._chain = true; + return instance; + } + + // Internal function to execute `sourceFunc` bound to `context` with optional + // `args`. Determines whether to execute a function as a constructor or as a + // normal function. + function executeBound(sourceFunc, boundFunc, context, callingContext, args) { + if (!(callingContext instanceof boundFunc)) return sourceFunc.apply(context, args); + var self = baseCreate(sourceFunc.prototype); + var result = sourceFunc.apply(self, args); + if (isObject(result)) return result; + return self; + } + + // Partially apply a function by creating a version that has had some of its + // arguments pre-filled, without changing its dynamic `this` context. `_` acts + // as a placeholder by default, allowing any combination of arguments to be + // pre-filled. Set `_.partial.placeholder` for a custom placeholder argument. + var partial = restArguments(function(func, boundArgs) { + var placeholder = partial.placeholder; + var bound = function() { + var position = 0, length = boundArgs.length; + var args = Array(length); + for (var i = 0; i < length; i++) { + args[i] = boundArgs[i] === placeholder ? arguments[position++] : boundArgs[i]; + } + while (position < arguments.length) args.push(arguments[position++]); + return executeBound(func, bound, this, this, args); + }; + return bound; + }); + + partial.placeholder = _$1; + + // Create a function bound to a given object (assigning `this`, and arguments, + // optionally). + var bind = restArguments(function(func, context, args) { + if (!isFunction$1(func)) throw new TypeError('Bind must be called on a function'); + var bound = restArguments(function(callArgs) { + return executeBound(func, bound, context, this, args.concat(callArgs)); + }); + return bound; + }); + + // Internal helper for collection methods to determine whether a collection + // should be iterated as an array or as an object. + // Related: https://people.mozilla.org/~jorendorff/es6-draft.html#sec-tolength + // Avoids a very nasty iOS 8 JIT bug on ARM-64. #2094 + var isArrayLike = createSizePropertyCheck(getLength); + + // Internal implementation of a recursive `flatten` function. + function flatten$1(input, depth, strict, output) { + output = output || []; + if (!depth && depth !== 0) { + depth = Infinity; + } else if (depth <= 0) { + return output.concat(input); + } + var idx = output.length; + for (var i = 0, length = getLength(input); i < length; i++) { + var value = input[i]; + if (isArrayLike(value) && (isArray(value) || isArguments$1(value))) { + // Flatten current level of array or arguments object. + if (depth > 1) { + flatten$1(value, depth - 1, strict, output); + idx = output.length; + } else { + var j = 0, len = value.length; + while (j < len) output[idx++] = value[j++]; + } + } else if (!strict) { + output[idx++] = value; + } + } + return output; + } + + // Bind a number of an object's methods to that object. Remaining arguments + // are the method names to be bound. Useful for ensuring that all callbacks + // defined on an object belong to it. + var bindAll = restArguments(function(obj, keys) { + keys = flatten$1(keys, false, false); + var index = keys.length; + if (index < 1) throw new Error('bindAll must be passed function names'); + while (index--) { + var key = keys[index]; + obj[key] = bind(obj[key], obj); + } + return obj; + }); + + // Memoize an expensive function by storing its results. + function memoize(func, hasher) { + var memoize = function(key) { + var cache = memoize.cache; + var address = '' + (hasher ? hasher.apply(this, arguments) : key); + if (!has$1(cache, address)) cache[address] = func.apply(this, arguments); + return cache[address]; + }; + memoize.cache = {}; + return memoize; + } + + // Delays a function for the given number of milliseconds, and then calls + // it with the arguments supplied. + var delay = restArguments(function(func, wait, args) { + return setTimeout(function() { + return func.apply(null, args); + }, wait); + }); + + // Defers a function, scheduling it to run after the current call stack has + // cleared. + var defer = partial(delay, _$1, 1); + + // Returns a function, that, when invoked, will only be triggered at most once + // during a given window of time. Normally, the throttled function will run + // as much as it can, without ever going more than once per `wait` duration; + // but if you'd like to disable the execution on the leading edge, pass + // `{leading: false}`. To disable execution on the trailing edge, ditto. + function throttle(func, wait, options) { + var timeout, context, args, result; + var previous = 0; + if (!options) options = {}; + + var later = function() { + previous = options.leading === false ? 0 : now(); + timeout = null; + result = func.apply(context, args); + if (!timeout) context = args = null; + }; + + var throttled = function() { + var _now = now(); + if (!previous && options.leading === false) previous = _now; + var remaining = wait - (_now - previous); + context = this; + args = arguments; + if (remaining <= 0 || remaining > wait) { + if (timeout) { + clearTimeout(timeout); + timeout = null; + } + previous = _now; + result = func.apply(context, args); + if (!timeout) context = args = null; + } else if (!timeout && options.trailing !== false) { + timeout = setTimeout(later, remaining); + } + return result; + }; + + throttled.cancel = function() { + clearTimeout(timeout); + previous = 0; + timeout = context = args = null; + }; + + return throttled; + } + + // When a sequence of calls of the returned function ends, the argument + // function is triggered. The end of a sequence is defined by the `wait` + // parameter. If `immediate` is passed, the argument function will be + // triggered at the beginning of the sequence instead of at the end. + function debounce(func, wait, immediate) { + var timeout, previous, args, result, context; + + var later = function() { + var passed = now() - previous; + if (wait > passed) { + timeout = setTimeout(later, wait - passed); + } else { + timeout = null; + if (!immediate) result = func.apply(context, args); + // This check is needed because `func` can recursively invoke `debounced`. + if (!timeout) args = context = null; + } + }; + + var debounced = restArguments(function(_args) { + context = this; + args = _args; + previous = now(); + if (!timeout) { + timeout = setTimeout(later, wait); + if (immediate) result = func.apply(context, args); + } + return result; + }); + + debounced.cancel = function() { + clearTimeout(timeout); + timeout = args = context = null; + }; + + return debounced; + } + + // Returns the first function passed as an argument to the second, + // allowing you to adjust arguments, run code before and after, and + // conditionally execute the original function. + function wrap(func, wrapper) { + return partial(wrapper, func); + } + + // Returns a negated version of the passed-in predicate. + function negate(predicate) { + return function() { + return !predicate.apply(this, arguments); + }; + } + + // Returns a function that is the composition of a list of functions, each + // consuming the return value of the function that follows. + function compose() { + var args = arguments; + var start = args.length - 1; + return function() { + var i = start; + var result = args[start].apply(this, arguments); + while (i--) result = args[i].call(this, result); + return result; + }; + } + + // Returns a function that will only be executed on and after the Nth call. + function after(times, func) { + return function() { + if (--times < 1) { + return func.apply(this, arguments); + } + }; + } + + // Returns a function that will only be executed up to (but not including) the + // Nth call. + function before(times, func) { + var memo; + return function() { + if (--times > 0) { + memo = func.apply(this, arguments); + } + if (times <= 1) func = null; + return memo; + }; + } + + // Returns a function that will be executed at most one time, no matter how + // often you call it. Useful for lazy initialization. + var once = partial(before, 2); + + // Returns the first key on an object that passes a truth test. + function findKey(obj, predicate, context) { + predicate = cb(predicate, context); + var _keys = keys(obj), key; + for (var i = 0, length = _keys.length; i < length; i++) { + key = _keys[i]; + if (predicate(obj[key], key, obj)) return key; + } + } + + // Internal function to generate `_.findIndex` and `_.findLastIndex`. + function createPredicateIndexFinder(dir) { + return function(array, predicate, context) { + predicate = cb(predicate, context); + var length = getLength(array); + var index = dir > 0 ? 0 : length - 1; + for (; index >= 0 && index < length; index += dir) { + if (predicate(array[index], index, array)) return index; + } + return -1; + }; + } + + // Returns the first index on an array-like that passes a truth test. + var findIndex = createPredicateIndexFinder(1); + + // Returns the last index on an array-like that passes a truth test. + var findLastIndex = createPredicateIndexFinder(-1); + + // Use a comparator function to figure out the smallest index at which + // an object should be inserted so as to maintain order. Uses binary search. + function sortedIndex(array, obj, iteratee, context) { + iteratee = cb(iteratee, context, 1); + var value = iteratee(obj); + var low = 0, high = getLength(array); + while (low < high) { + var mid = Math.floor((low + high) / 2); + if (iteratee(array[mid]) < value) low = mid + 1; else high = mid; + } + return low; + } + + // Internal function to generate the `_.indexOf` and `_.lastIndexOf` functions. + function createIndexFinder(dir, predicateFind, sortedIndex) { + return function(array, item, idx) { + var i = 0, length = getLength(array); + if (typeof idx == 'number') { + if (dir > 0) { + i = idx >= 0 ? idx : Math.max(idx + length, i); + } else { + length = idx >= 0 ? Math.min(idx + 1, length) : idx + length + 1; + } + } else if (sortedIndex && idx && length) { + idx = sortedIndex(array, item); + return array[idx] === item ? idx : -1; + } + if (item !== item) { + idx = predicateFind(slice.call(array, i, length), isNaN$1); + return idx >= 0 ? idx + i : -1; + } + for (idx = dir > 0 ? i : length - 1; idx >= 0 && idx < length; idx += dir) { + if (array[idx] === item) return idx; + } + return -1; + }; + } + + // Return the position of the first occurrence of an item in an array, + // or -1 if the item is not included in the array. + // If the array is large and already in sort order, pass `true` + // for **isSorted** to use binary search. + var indexOf = createIndexFinder(1, findIndex, sortedIndex); + + // Return the position of the last occurrence of an item in an array, + // or -1 if the item is not included in the array. + var lastIndexOf = createIndexFinder(-1, findLastIndex); + + // Return the first value which passes a truth test. + function find(obj, predicate, context) { + var keyFinder = isArrayLike(obj) ? findIndex : findKey; + var key = keyFinder(obj, predicate, context); + if (key !== void 0 && key !== -1) return obj[key]; + } + + // Convenience version of a common use case of `_.find`: getting the first + // object containing specific `key:value` pairs. + function findWhere(obj, attrs) { + return find(obj, matcher(attrs)); + } + + // The cornerstone for collection functions, an `each` + // implementation, aka `forEach`. + // Handles raw objects in addition to array-likes. Treats all + // sparse array-likes as if they were dense. + function each(obj, iteratee, context) { + iteratee = optimizeCb(iteratee, context); + var i, length; + if (isArrayLike(obj)) { + for (i = 0, length = obj.length; i < length; i++) { + iteratee(obj[i], i, obj); + } + } else { + var _keys = keys(obj); + for (i = 0, length = _keys.length; i < length; i++) { + iteratee(obj[_keys[i]], _keys[i], obj); + } + } + return obj; + } + + // Return the results of applying the iteratee to each element. + function map(obj, iteratee, context) { + iteratee = cb(iteratee, context); + var _keys = !isArrayLike(obj) && keys(obj), + length = (_keys || obj).length, + results = Array(length); + for (var index = 0; index < length; index++) { + var currentKey = _keys ? _keys[index] : index; + results[index] = iteratee(obj[currentKey], currentKey, obj); + } + return results; + } + + // Internal helper to create a reducing function, iterating left or right. + function createReduce(dir) { + // Wrap code that reassigns argument variables in a separate function than + // the one that accesses `arguments.length` to avoid a perf hit. (#1991) + var reducer = function(obj, iteratee, memo, initial) { + var _keys = !isArrayLike(obj) && keys(obj), + length = (_keys || obj).length, + index = dir > 0 ? 0 : length - 1; + if (!initial) { + memo = obj[_keys ? _keys[index] : index]; + index += dir; + } + for (; index >= 0 && index < length; index += dir) { + var currentKey = _keys ? _keys[index] : index; + memo = iteratee(memo, obj[currentKey], currentKey, obj); + } + return memo; + }; + + return function(obj, iteratee, memo, context) { + var initial = arguments.length >= 3; + return reducer(obj, optimizeCb(iteratee, context, 4), memo, initial); + }; + } + + // **Reduce** builds up a single result from a list of values, aka `inject`, + // or `foldl`. + var reduce = createReduce(1); + + // The right-associative version of reduce, also known as `foldr`. + var reduceRight = createReduce(-1); + + // Return all the elements that pass a truth test. + function filter(obj, predicate, context) { + var results = []; + predicate = cb(predicate, context); + each(obj, function(value, index, list) { + if (predicate(value, index, list)) results.push(value); + }); + return results; + } + + // Return all the elements for which a truth test fails. + function reject(obj, predicate, context) { + return filter(obj, negate(cb(predicate)), context); + } + + // Determine whether all of the elements pass a truth test. + function every(obj, predicate, context) { + predicate = cb(predicate, context); + var _keys = !isArrayLike(obj) && keys(obj), + length = (_keys || obj).length; + for (var index = 0; index < length; index++) { + var currentKey = _keys ? _keys[index] : index; + if (!predicate(obj[currentKey], currentKey, obj)) return false; + } + return true; + } + + // Determine if at least one element in the object passes a truth test. + function some(obj, predicate, context) { + predicate = cb(predicate, context); + var _keys = !isArrayLike(obj) && keys(obj), + length = (_keys || obj).length; + for (var index = 0; index < length; index++) { + var currentKey = _keys ? _keys[index] : index; + if (predicate(obj[currentKey], currentKey, obj)) return true; + } + return false; + } + + // Determine if the array or object contains a given item (using `===`). + function contains(obj, item, fromIndex, guard) { + if (!isArrayLike(obj)) obj = values(obj); + if (typeof fromIndex != 'number' || guard) fromIndex = 0; + return indexOf(obj, item, fromIndex) >= 0; + } + + // Invoke a method (with arguments) on every item in a collection. + var invoke = restArguments(function(obj, path, args) { + var contextPath, func; + if (isFunction$1(path)) { + func = path; + } else { + path = toPath(path); + contextPath = path.slice(0, -1); + path = path[path.length - 1]; + } + return map(obj, function(context) { + var method = func; + if (!method) { + if (contextPath && contextPath.length) { + context = deepGet(context, contextPath); + } + if (context == null) return void 0; + method = context[path]; + } + return method == null ? method : method.apply(context, args); + }); + }); + + // Convenience version of a common use case of `_.map`: fetching a property. + function pluck(obj, key) { + return map(obj, property(key)); + } + + // Convenience version of a common use case of `_.filter`: selecting only + // objects containing specific `key:value` pairs. + function where(obj, attrs) { + return filter(obj, matcher(attrs)); + } + + // Return the maximum element (or element-based computation). + function max(obj, iteratee, context) { + var result = -Infinity, lastComputed = -Infinity, + value, computed; + if (iteratee == null || typeof iteratee == 'number' && typeof obj[0] != 'object' && obj != null) { + obj = isArrayLike(obj) ? obj : values(obj); + for (var i = 0, length = obj.length; i < length; i++) { + value = obj[i]; + if (value != null && value > result) { + result = value; + } + } + } else { + iteratee = cb(iteratee, context); + each(obj, function(v, index, list) { + computed = iteratee(v, index, list); + if (computed > lastComputed || computed === -Infinity && result === -Infinity) { + result = v; + lastComputed = computed; + } + }); + } + return result; + } + + // Return the minimum element (or element-based computation). + function min(obj, iteratee, context) { + var result = Infinity, lastComputed = Infinity, + value, computed; + if (iteratee == null || typeof iteratee == 'number' && typeof obj[0] != 'object' && obj != null) { + obj = isArrayLike(obj) ? obj : values(obj); + for (var i = 0, length = obj.length; i < length; i++) { + value = obj[i]; + if (value != null && value < result) { + result = value; + } + } + } else { + iteratee = cb(iteratee, context); + each(obj, function(v, index, list) { + computed = iteratee(v, index, list); + if (computed < lastComputed || computed === Infinity && result === Infinity) { + result = v; + lastComputed = computed; + } + }); + } + return result; + } + + // Sample **n** random values from a collection using the modern version of the + // [Fisher-Yates shuffle](https://en.wikipedia.org/wiki/Fisher–Yates_shuffle). + // If **n** is not specified, returns a single random element. + // The internal `guard` argument allows it to work with `_.map`. + function sample(obj, n, guard) { + if (n == null || guard) { + if (!isArrayLike(obj)) obj = values(obj); + return obj[random(obj.length - 1)]; + } + var sample = isArrayLike(obj) ? clone(obj) : values(obj); + var length = getLength(sample); + n = Math.max(Math.min(n, length), 0); + var last = length - 1; + for (var index = 0; index < n; index++) { + var rand = random(index, last); + var temp = sample[index]; + sample[index] = sample[rand]; + sample[rand] = temp; + } + return sample.slice(0, n); + } + + // Shuffle a collection. + function shuffle(obj) { + return sample(obj, Infinity); + } + + // Sort the object's values by a criterion produced by an iteratee. + function sortBy(obj, iteratee, context) { + var index = 0; + iteratee = cb(iteratee, context); + return pluck(map(obj, function(value, key, list) { + return { + value: value, + index: index++, + criteria: iteratee(value, key, list) + }; + }).sort(function(left, right) { + var a = left.criteria; + var b = right.criteria; + if (a !== b) { + if (a > b || a === void 0) return 1; + if (a < b || b === void 0) return -1; + } + return left.index - right.index; + }), 'value'); + } + + // An internal function used for aggregate "group by" operations. + function group(behavior, partition) { + return function(obj, iteratee, context) { + var result = partition ? [[], []] : {}; + iteratee = cb(iteratee, context); + each(obj, function(value, index) { + var key = iteratee(value, index, obj); + behavior(result, value, key); + }); + return result; + }; + } + + // Groups the object's values by a criterion. Pass either a string attribute + // to group by, or a function that returns the criterion. + var groupBy = group(function(result, value, key) { + if (has$1(result, key)) result[key].push(value); else result[key] = [value]; + }); + + // Indexes the object's values by a criterion, similar to `_.groupBy`, but for + // when you know that your index values will be unique. + var indexBy = group(function(result, value, key) { + result[key] = value; + }); + + // Counts instances of an object that group by a certain criterion. Pass + // either a string attribute to count by, or a function that returns the + // criterion. + var countBy = group(function(result, value, key) { + if (has$1(result, key)) result[key]++; else result[key] = 1; + }); + + // Split a collection into two arrays: one whose elements all pass the given + // truth test, and one whose elements all do not pass the truth test. + var partition = group(function(result, value, pass) { + result[pass ? 0 : 1].push(value); + }, true); + + // Safely create a real, live array from anything iterable. + var reStrSymbol = /[^\ud800-\udfff]|[\ud800-\udbff][\udc00-\udfff]|[\ud800-\udfff]/g; + function toArray(obj) { + if (!obj) return []; + if (isArray(obj)) return slice.call(obj); + if (isString(obj)) { + // Keep surrogate pair characters together. + return obj.match(reStrSymbol); + } + if (isArrayLike(obj)) return map(obj, identity); + return values(obj); + } + + // Return the number of elements in a collection. + function size(obj) { + if (obj == null) return 0; + return isArrayLike(obj) ? obj.length : keys(obj).length; + } + + // Internal `_.pick` helper function to determine whether `key` is an enumerable + // property name of `obj`. + function keyInObj(value, key, obj) { + return key in obj; + } + + // Return a copy of the object only containing the allowed properties. + var pick = restArguments(function(obj, keys) { + var result = {}, iteratee = keys[0]; + if (obj == null) return result; + if (isFunction$1(iteratee)) { + if (keys.length > 1) iteratee = optimizeCb(iteratee, keys[1]); + keys = allKeys(obj); + } else { + iteratee = keyInObj; + keys = flatten$1(keys, false, false); + obj = Object(obj); + } + for (var i = 0, length = keys.length; i < length; i++) { + var key = keys[i]; + var value = obj[key]; + if (iteratee(value, key, obj)) result[key] = value; + } + return result; + }); + + // Return a copy of the object without the disallowed properties. + var omit = restArguments(function(obj, keys) { + var iteratee = keys[0], context; + if (isFunction$1(iteratee)) { + iteratee = negate(iteratee); + if (keys.length > 1) context = keys[1]; + } else { + keys = map(flatten$1(keys, false, false), String); + iteratee = function(value, key) { + return !contains(keys, key); + }; + } + return pick(obj, iteratee, context); + }); + + // Returns everything but the last entry of the array. Especially useful on + // the arguments object. Passing **n** will return all the values in + // the array, excluding the last N. + function initial(array, n, guard) { + return slice.call(array, 0, Math.max(0, array.length - (n == null || guard ? 1 : n))); + } + + // Get the first element of an array. Passing **n** will return the first N + // values in the array. The **guard** check allows it to work with `_.map`. + function first(array, n, guard) { + if (array == null || array.length < 1) return n == null || guard ? void 0 : []; + if (n == null || guard) return array[0]; + return initial(array, array.length - n); + } + + // Returns everything but the first entry of the `array`. Especially useful on + // the `arguments` object. Passing an **n** will return the rest N values in the + // `array`. + function rest(array, n, guard) { + return slice.call(array, n == null || guard ? 1 : n); + } + + // Get the last element of an array. Passing **n** will return the last N + // values in the array. + function last(array, n, guard) { + if (array == null || array.length < 1) return n == null || guard ? void 0 : []; + if (n == null || guard) return array[array.length - 1]; + return rest(array, Math.max(0, array.length - n)); + } + + // Trim out all falsy values from an array. + function compact(array) { + return filter(array, Boolean); + } + + // Flatten out an array, either recursively (by default), or up to `depth`. + // Passing `true` or `false` as `depth` means `1` or `Infinity`, respectively. + function flatten(array, depth) { + return flatten$1(array, depth, false); + } + + // Take the difference between one array and a number of other arrays. + // Only the elements present in just the first array will remain. + var difference = restArguments(function(array, rest) { + rest = flatten$1(rest, true, true); + return filter(array, function(value){ + return !contains(rest, value); + }); + }); + + // Return a version of the array that does not contain the specified value(s). + var without = restArguments(function(array, otherArrays) { + return difference(array, otherArrays); + }); + + // Produce a duplicate-free version of the array. If the array has already + // been sorted, you have the option of using a faster algorithm. + // The faster algorithm will not work with an iteratee if the iteratee + // is not a one-to-one function, so providing an iteratee will disable + // the faster algorithm. + function uniq(array, isSorted, iteratee, context) { + if (!isBoolean(isSorted)) { + context = iteratee; + iteratee = isSorted; + isSorted = false; + } + if (iteratee != null) iteratee = cb(iteratee, context); + var result = []; + var seen = []; + for (var i = 0, length = getLength(array); i < length; i++) { + var value = array[i], + computed = iteratee ? iteratee(value, i, array) : value; + if (isSorted && !iteratee) { + if (!i || seen !== computed) result.push(value); + seen = computed; + } else if (iteratee) { + if (!contains(seen, computed)) { + seen.push(computed); + result.push(value); + } + } else if (!contains(result, value)) { + result.push(value); + } + } + return result; + } + + // Produce an array that contains the union: each distinct element from all of + // the passed-in arrays. + var union = restArguments(function(arrays) { + return uniq(flatten$1(arrays, true, true)); + }); + + // Produce an array that contains every item shared between all the + // passed-in arrays. + function intersection(array) { + var result = []; + var argsLength = arguments.length; + for (var i = 0, length = getLength(array); i < length; i++) { + var item = array[i]; + if (contains(result, item)) continue; + var j; + for (j = 1; j < argsLength; j++) { + if (!contains(arguments[j], item)) break; + } + if (j === argsLength) result.push(item); + } + return result; + } + + // Complement of zip. Unzip accepts an array of arrays and groups + // each array's elements on shared indices. + function unzip(array) { + var length = array && max(array, getLength).length || 0; + var result = Array(length); + + for (var index = 0; index < length; index++) { + result[index] = pluck(array, index); + } + return result; + } + + // Zip together multiple lists into a single array -- elements that share + // an index go together. + var zip = restArguments(unzip); + + // Converts lists into objects. Pass either a single array of `[key, value]` + // pairs, or two parallel arrays of the same length -- one of keys, and one of + // the corresponding values. Passing by pairs is the reverse of `_.pairs`. + function object(list, values) { + var result = {}; + for (var i = 0, length = getLength(list); i < length; i++) { + if (values) { + result[list[i]] = values[i]; + } else { + result[list[i][0]] = list[i][1]; + } + } + return result; + } + + // Generate an integer Array containing an arithmetic progression. A port of + // the native Python `range()` function. See + // [the Python documentation](https://docs.python.org/library/functions.html#range). + function range(start, stop, step) { + if (stop == null) { + stop = start || 0; + start = 0; + } + if (!step) { + step = stop < start ? -1 : 1; + } + + var length = Math.max(Math.ceil((stop - start) / step), 0); + var range = Array(length); + + for (var idx = 0; idx < length; idx++, start += step) { + range[idx] = start; + } + + return range; + } + + // Chunk a single array into multiple arrays, each containing `count` or fewer + // items. + function chunk(array, count) { + if (count == null || count < 1) return []; + var result = []; + var i = 0, length = array.length; + while (i < length) { + result.push(slice.call(array, i, i += count)); + } + return result; + } + + // Helper function to continue chaining intermediate results. + function chainResult(instance, obj) { + return instance._chain ? _$1(obj).chain() : obj; + } + + // Add your own custom functions to the Underscore object. + function mixin(obj) { + each(functions(obj), function(name) { + var func = _$1[name] = obj[name]; + _$1.prototype[name] = function() { + var args = [this._wrapped]; + push.apply(args, arguments); + return chainResult(this, func.apply(_$1, args)); + }; + }); + return _$1; + } + + // Add all mutator `Array` functions to the wrapper. + each(['pop', 'push', 'reverse', 'shift', 'sort', 'splice', 'unshift'], function(name) { + var method = ArrayProto[name]; + _$1.prototype[name] = function() { + var obj = this._wrapped; + if (obj != null) { + method.apply(obj, arguments); + if ((name === 'shift' || name === 'splice') && obj.length === 0) { + delete obj[0]; + } + } + return chainResult(this, obj); + }; + }); + + // Add all accessor `Array` functions to the wrapper. + each(['concat', 'join', 'slice'], function(name) { + var method = ArrayProto[name]; + _$1.prototype[name] = function() { + var obj = this._wrapped; + if (obj != null) obj = method.apply(obj, arguments); + return chainResult(this, obj); + }; + }); + + // Named Exports + + var allExports = { + __proto__: null, + VERSION: VERSION, + restArguments: restArguments, + isObject: isObject, + isNull: isNull, + isUndefined: isUndefined, + isBoolean: isBoolean, + isElement: isElement, + isString: isString, + isNumber: isNumber, + isDate: isDate, + isRegExp: isRegExp, + isError: isError, + isSymbol: isSymbol, + isArrayBuffer: isArrayBuffer, + isDataView: isDataView$1, + isArray: isArray, + isFunction: isFunction$1, + isArguments: isArguments$1, + isFinite: isFinite$1, + isNaN: isNaN$1, + isTypedArray: isTypedArray$1, + isEmpty: isEmpty, + isMatch: isMatch, + isEqual: isEqual, + isMap: isMap, + isWeakMap: isWeakMap, + isSet: isSet, + isWeakSet: isWeakSet, + keys: keys, + allKeys: allKeys, + values: values, + pairs: pairs, + invert: invert, + functions: functions, + methods: functions, + extend: extend, + extendOwn: extendOwn, + assign: extendOwn, + defaults: defaults, + create: create, + clone: clone, + tap: tap, + get: get, + has: has, + mapObject: mapObject, + identity: identity, + constant: constant, + noop: noop, + toPath: toPath$1, + property: property, + propertyOf: propertyOf, + matcher: matcher, + matches: matcher, + times: times, + random: random, + now: now, + escape: _escape, + unescape: _unescape, + templateSettings: templateSettings, + template: template, + result: result, + uniqueId: uniqueId, + chain: chain, + iteratee: iteratee, + partial: partial, + bind: bind, + bindAll: bindAll, + memoize: memoize, + delay: delay, + defer: defer, + throttle: throttle, + debounce: debounce, + wrap: wrap, + negate: negate, + compose: compose, + after: after, + before: before, + once: once, + findKey: findKey, + findIndex: findIndex, + findLastIndex: findLastIndex, + sortedIndex: sortedIndex, + indexOf: indexOf, + lastIndexOf: lastIndexOf, + find: find, + detect: find, + findWhere: findWhere, + each: each, + forEach: each, + map: map, + collect: map, + reduce: reduce, + foldl: reduce, + inject: reduce, + reduceRight: reduceRight, + foldr: reduceRight, + filter: filter, + select: filter, + reject: reject, + every: every, + all: every, + some: some, + any: some, + contains: contains, + includes: contains, + include: contains, + invoke: invoke, + pluck: pluck, + where: where, + max: max, + min: min, + shuffle: shuffle, + sample: sample, + sortBy: sortBy, + groupBy: groupBy, + indexBy: indexBy, + countBy: countBy, + partition: partition, + toArray: toArray, + size: size, + pick: pick, + omit: omit, + first: first, + head: first, + take: first, + initial: initial, + last: last, + rest: rest, + tail: rest, + drop: rest, + compact: compact, + flatten: flatten, + without: without, + uniq: uniq, + unique: uniq, + union: union, + intersection: intersection, + difference: difference, + unzip: unzip, + transpose: unzip, + zip: zip, + object: object, + range: range, + chunk: chunk, + mixin: mixin, + 'default': _$1 + }; + + // Default Export + + // Add all of the Underscore functions to the wrapper object. + var _ = mixin(allExports); + // Legacy Node.js API. + _._ = _; + + return _; + +}))); +//# sourceMappingURL=underscore-umd.js.map diff --git a/guide/_static/underscore.js b/guide/_static/underscore.js new file mode 100644 index 0000000..cf177d4 --- /dev/null +++ b/guide/_static/underscore.js @@ -0,0 +1,6 @@ +!function(n,r){"object"==typeof exports&&"undefined"!=typeof module?module.exports=r():"function"==typeof define&&define.amd?define("underscore",r):(n="undefined"!=typeof globalThis?globalThis:n||self,function(){var t=n._,e=n._=r();e.noConflict=function(){return n._=t,e}}())}(this,(function(){ +// Underscore.js 1.13.1 +// https://underscorejs.org +// (c) 2009-2021 Jeremy Ashkenas, Julian Gonggrijp, and DocumentCloud and Investigative Reporters & Editors +// Underscore may be freely distributed under the MIT license. +var n="1.13.1",r="object"==typeof self&&self.self===self&&self||"object"==typeof global&&global.global===global&&global||Function("return this")()||{},t=Array.prototype,e=Object.prototype,u="undefined"!=typeof Symbol?Symbol.prototype:null,o=t.push,i=t.slice,a=e.toString,f=e.hasOwnProperty,c="undefined"!=typeof ArrayBuffer,l="undefined"!=typeof DataView,s=Array.isArray,p=Object.keys,v=Object.create,h=c&&ArrayBuffer.isView,y=isNaN,d=isFinite,g=!{toString:null}.propertyIsEnumerable("toString"),b=["valueOf","isPrototypeOf","toString","propertyIsEnumerable","hasOwnProperty","toLocaleString"],m=Math.pow(2,53)-1;function j(n,r){return r=null==r?n.length-1:+r,function(){for(var t=Math.max(arguments.length-r,0),e=Array(t),u=0;u<t;u++)e[u]=arguments[u+r];switch(r){case 0:return n.call(this,e);case 1:return n.call(this,arguments[0],e);case 2:return n.call(this,arguments[0],arguments[1],e)}var o=Array(r+1);for(u=0;u<r;u++)o[u]=arguments[u];return o[r]=e,n.apply(this,o)}}function _(n){var r=typeof n;return"function"===r||"object"===r&&!!n}function w(n){return void 0===n}function A(n){return!0===n||!1===n||"[object Boolean]"===a.call(n)}function x(n){var r="[object "+n+"]";return function(n){return a.call(n)===r}}var S=x("String"),O=x("Number"),M=x("Date"),E=x("RegExp"),B=x("Error"),N=x("Symbol"),I=x("ArrayBuffer"),T=x("Function"),k=r.document&&r.document.childNodes;"function"!=typeof/./&&"object"!=typeof Int8Array&&"function"!=typeof k&&(T=function(n){return"function"==typeof n||!1});var D=T,R=x("Object"),F=l&&R(new DataView(new ArrayBuffer(8))),V="undefined"!=typeof Map&&R(new Map),P=x("DataView");var q=F?function(n){return null!=n&&D(n.getInt8)&&I(n.buffer)}:P,U=s||x("Array");function W(n,r){return null!=n&&f.call(n,r)}var z=x("Arguments");!function(){z(arguments)||(z=function(n){return W(n,"callee")})}();var L=z;function $(n){return O(n)&&y(n)}function C(n){return function(){return n}}function K(n){return function(r){var t=n(r);return"number"==typeof t&&t>=0&&t<=m}}function J(n){return function(r){return null==r?void 0:r[n]}}var G=J("byteLength"),H=K(G),Q=/\[object ((I|Ui)nt(8|16|32)|Float(32|64)|Uint8Clamped|Big(I|Ui)nt64)Array\]/;var X=c?function(n){return h?h(n)&&!q(n):H(n)&&Q.test(a.call(n))}:C(!1),Y=J("length");function Z(n,r){r=function(n){for(var r={},t=n.length,e=0;e<t;++e)r[n[e]]=!0;return{contains:function(n){return r[n]},push:function(t){return r[t]=!0,n.push(t)}}}(r);var t=b.length,u=n.constructor,o=D(u)&&u.prototype||e,i="constructor";for(W(n,i)&&!r.contains(i)&&r.push(i);t--;)(i=b[t])in n&&n[i]!==o[i]&&!r.contains(i)&&r.push(i)}function nn(n){if(!_(n))return[];if(p)return p(n);var r=[];for(var t in n)W(n,t)&&r.push(t);return g&&Z(n,r),r}function rn(n,r){var t=nn(r),e=t.length;if(null==n)return!e;for(var u=Object(n),o=0;o<e;o++){var i=t[o];if(r[i]!==u[i]||!(i in u))return!1}return!0}function tn(n){return n instanceof tn?n:this instanceof tn?void(this._wrapped=n):new tn(n)}function en(n){return new Uint8Array(n.buffer||n,n.byteOffset||0,G(n))}tn.VERSION=n,tn.prototype.value=function(){return this._wrapped},tn.prototype.valueOf=tn.prototype.toJSON=tn.prototype.value,tn.prototype.toString=function(){return String(this._wrapped)};var un="[object DataView]";function on(n,r,t,e){if(n===r)return 0!==n||1/n==1/r;if(null==n||null==r)return!1;if(n!=n)return r!=r;var o=typeof n;return("function"===o||"object"===o||"object"==typeof r)&&function n(r,t,e,o){r instanceof tn&&(r=r._wrapped);t instanceof tn&&(t=t._wrapped);var i=a.call(r);if(i!==a.call(t))return!1;if(F&&"[object Object]"==i&&q(r)){if(!q(t))return!1;i=un}switch(i){case"[object RegExp]":case"[object String]":return""+r==""+t;case"[object Number]":return+r!=+r?+t!=+t:0==+r?1/+r==1/t:+r==+t;case"[object Date]":case"[object Boolean]":return+r==+t;case"[object Symbol]":return u.valueOf.call(r)===u.valueOf.call(t);case"[object ArrayBuffer]":case un:return n(en(r),en(t),e,o)}var f="[object Array]"===i;if(!f&&X(r)){if(G(r)!==G(t))return!1;if(r.buffer===t.buffer&&r.byteOffset===t.byteOffset)return!0;f=!0}if(!f){if("object"!=typeof r||"object"!=typeof t)return!1;var c=r.constructor,l=t.constructor;if(c!==l&&!(D(c)&&c instanceof c&&D(l)&&l instanceof l)&&"constructor"in r&&"constructor"in t)return!1}o=o||[];var s=(e=e||[]).length;for(;s--;)if(e[s]===r)return o[s]===t;if(e.push(r),o.push(t),f){if((s=r.length)!==t.length)return!1;for(;s--;)if(!on(r[s],t[s],e,o))return!1}else{var p,v=nn(r);if(s=v.length,nn(t).length!==s)return!1;for(;s--;)if(p=v[s],!W(t,p)||!on(r[p],t[p],e,o))return!1}return e.pop(),o.pop(),!0}(n,r,t,e)}function an(n){if(!_(n))return[];var r=[];for(var t in n)r.push(t);return g&&Z(n,r),r}function fn(n){var r=Y(n);return function(t){if(null==t)return!1;var e=an(t);if(Y(e))return!1;for(var u=0;u<r;u++)if(!D(t[n[u]]))return!1;return n!==hn||!D(t[cn])}}var cn="forEach",ln="has",sn=["clear","delete"],pn=["get",ln,"set"],vn=sn.concat(cn,pn),hn=sn.concat(pn),yn=["add"].concat(sn,cn,ln),dn=V?fn(vn):x("Map"),gn=V?fn(hn):x("WeakMap"),bn=V?fn(yn):x("Set"),mn=x("WeakSet");function jn(n){for(var r=nn(n),t=r.length,e=Array(t),u=0;u<t;u++)e[u]=n[r[u]];return e}function _n(n){for(var r={},t=nn(n),e=0,u=t.length;e<u;e++)r[n[t[e]]]=t[e];return r}function wn(n){var r=[];for(var t in n)D(n[t])&&r.push(t);return r.sort()}function An(n,r){return function(t){var e=arguments.length;if(r&&(t=Object(t)),e<2||null==t)return t;for(var u=1;u<e;u++)for(var o=arguments[u],i=n(o),a=i.length,f=0;f<a;f++){var c=i[f];r&&void 0!==t[c]||(t[c]=o[c])}return t}}var xn=An(an),Sn=An(nn),On=An(an,!0);function Mn(n){if(!_(n))return{};if(v)return v(n);var r=function(){};r.prototype=n;var t=new r;return r.prototype=null,t}function En(n){return _(n)?U(n)?n.slice():xn({},n):n}function Bn(n){return U(n)?n:[n]}function Nn(n){return tn.toPath(n)}function In(n,r){for(var t=r.length,e=0;e<t;e++){if(null==n)return;n=n[r[e]]}return t?n:void 0}function Tn(n,r,t){var e=In(n,Nn(r));return w(e)?t:e}function kn(n){return n}function Dn(n){return n=Sn({},n),function(r){return rn(r,n)}}function Rn(n){return n=Nn(n),function(r){return In(r,n)}}function Fn(n,r,t){if(void 0===r)return n;switch(null==t?3:t){case 1:return function(t){return n.call(r,t)};case 3:return function(t,e,u){return n.call(r,t,e,u)};case 4:return function(t,e,u,o){return n.call(r,t,e,u,o)}}return function(){return n.apply(r,arguments)}}function Vn(n,r,t){return null==n?kn:D(n)?Fn(n,r,t):_(n)&&!U(n)?Dn(n):Rn(n)}function Pn(n,r){return Vn(n,r,1/0)}function qn(n,r,t){return tn.iteratee!==Pn?tn.iteratee(n,r):Vn(n,r,t)}function Un(){}function Wn(n,r){return null==r&&(r=n,n=0),n+Math.floor(Math.random()*(r-n+1))}tn.toPath=Bn,tn.iteratee=Pn;var zn=Date.now||function(){return(new Date).getTime()};function Ln(n){var r=function(r){return n[r]},t="(?:"+nn(n).join("|")+")",e=RegExp(t),u=RegExp(t,"g");return function(n){return n=null==n?"":""+n,e.test(n)?n.replace(u,r):n}}var $n={"&":"&","<":"<",">":">",'"':""","'":"'","`":"`"},Cn=Ln($n),Kn=Ln(_n($n)),Jn=tn.templateSettings={evaluate:/<%([\s\S]+?)%>/g,interpolate:/<%=([\s\S]+?)%>/g,escape:/<%-([\s\S]+?)%>/g},Gn=/(.)^/,Hn={"'":"'","\\":"\\","\r":"r","\n":"n","\u2028":"u2028","\u2029":"u2029"},Qn=/\\|'|\r|\n|\u2028|\u2029/g;function Xn(n){return"\\"+Hn[n]}var Yn=/^\s*(\w|\$)+\s*$/;var Zn=0;function nr(n,r,t,e,u){if(!(e instanceof r))return n.apply(t,u);var o=Mn(n.prototype),i=n.apply(o,u);return _(i)?i:o}var rr=j((function(n,r){var t=rr.placeholder,e=function(){for(var u=0,o=r.length,i=Array(o),a=0;a<o;a++)i[a]=r[a]===t?arguments[u++]:r[a];for(;u<arguments.length;)i.push(arguments[u++]);return nr(n,e,this,this,i)};return e}));rr.placeholder=tn;var tr=j((function(n,r,t){if(!D(n))throw new TypeError("Bind must be called on a function");var e=j((function(u){return nr(n,e,r,this,t.concat(u))}));return e})),er=K(Y);function ur(n,r,t,e){if(e=e||[],r||0===r){if(r<=0)return e.concat(n)}else r=1/0;for(var u=e.length,o=0,i=Y(n);o<i;o++){var a=n[o];if(er(a)&&(U(a)||L(a)))if(r>1)ur(a,r-1,t,e),u=e.length;else for(var f=0,c=a.length;f<c;)e[u++]=a[f++];else t||(e[u++]=a)}return e}var or=j((function(n,r){var t=(r=ur(r,!1,!1)).length;if(t<1)throw new Error("bindAll must be passed function names");for(;t--;){var e=r[t];n[e]=tr(n[e],n)}return n}));var ir=j((function(n,r,t){return setTimeout((function(){return n.apply(null,t)}),r)})),ar=rr(ir,tn,1);function fr(n){return function(){return!n.apply(this,arguments)}}function cr(n,r){var t;return function(){return--n>0&&(t=r.apply(this,arguments)),n<=1&&(r=null),t}}var lr=rr(cr,2);function sr(n,r,t){r=qn(r,t);for(var e,u=nn(n),o=0,i=u.length;o<i;o++)if(r(n[e=u[o]],e,n))return e}function pr(n){return function(r,t,e){t=qn(t,e);for(var u=Y(r),o=n>0?0:u-1;o>=0&&o<u;o+=n)if(t(r[o],o,r))return o;return-1}}var vr=pr(1),hr=pr(-1);function yr(n,r,t,e){for(var u=(t=qn(t,e,1))(r),o=0,i=Y(n);o<i;){var a=Math.floor((o+i)/2);t(n[a])<u?o=a+1:i=a}return o}function dr(n,r,t){return function(e,u,o){var a=0,f=Y(e);if("number"==typeof o)n>0?a=o>=0?o:Math.max(o+f,a):f=o>=0?Math.min(o+1,f):o+f+1;else if(t&&o&&f)return e[o=t(e,u)]===u?o:-1;if(u!=u)return(o=r(i.call(e,a,f),$))>=0?o+a:-1;for(o=n>0?a:f-1;o>=0&&o<f;o+=n)if(e[o]===u)return o;return-1}}var gr=dr(1,vr,yr),br=dr(-1,hr);function mr(n,r,t){var e=(er(n)?vr:sr)(n,r,t);if(void 0!==e&&-1!==e)return n[e]}function jr(n,r,t){var e,u;if(r=Fn(r,t),er(n))for(e=0,u=n.length;e<u;e++)r(n[e],e,n);else{var o=nn(n);for(e=0,u=o.length;e<u;e++)r(n[o[e]],o[e],n)}return n}function _r(n,r,t){r=qn(r,t);for(var e=!er(n)&&nn(n),u=(e||n).length,o=Array(u),i=0;i<u;i++){var a=e?e[i]:i;o[i]=r(n[a],a,n)}return o}function wr(n){var r=function(r,t,e,u){var o=!er(r)&&nn(r),i=(o||r).length,a=n>0?0:i-1;for(u||(e=r[o?o[a]:a],a+=n);a>=0&&a<i;a+=n){var f=o?o[a]:a;e=t(e,r[f],f,r)}return e};return function(n,t,e,u){var o=arguments.length>=3;return r(n,Fn(t,u,4),e,o)}}var Ar=wr(1),xr=wr(-1);function Sr(n,r,t){var e=[];return r=qn(r,t),jr(n,(function(n,t,u){r(n,t,u)&&e.push(n)})),e}function Or(n,r,t){r=qn(r,t);for(var e=!er(n)&&nn(n),u=(e||n).length,o=0;o<u;o++){var i=e?e[o]:o;if(!r(n[i],i,n))return!1}return!0}function Mr(n,r,t){r=qn(r,t);for(var e=!er(n)&&nn(n),u=(e||n).length,o=0;o<u;o++){var i=e?e[o]:o;if(r(n[i],i,n))return!0}return!1}function Er(n,r,t,e){return er(n)||(n=jn(n)),("number"!=typeof t||e)&&(t=0),gr(n,r,t)>=0}var Br=j((function(n,r,t){var e,u;return D(r)?u=r:(r=Nn(r),e=r.slice(0,-1),r=r[r.length-1]),_r(n,(function(n){var o=u;if(!o){if(e&&e.length&&(n=In(n,e)),null==n)return;o=n[r]}return null==o?o:o.apply(n,t)}))}));function Nr(n,r){return _r(n,Rn(r))}function Ir(n,r,t){var e,u,o=-1/0,i=-1/0;if(null==r||"number"==typeof r&&"object"!=typeof n[0]&&null!=n)for(var a=0,f=(n=er(n)?n:jn(n)).length;a<f;a++)null!=(e=n[a])&&e>o&&(o=e);else r=qn(r,t),jr(n,(function(n,t,e){((u=r(n,t,e))>i||u===-1/0&&o===-1/0)&&(o=n,i=u)}));return o}function Tr(n,r,t){if(null==r||t)return er(n)||(n=jn(n)),n[Wn(n.length-1)];var e=er(n)?En(n):jn(n),u=Y(e);r=Math.max(Math.min(r,u),0);for(var o=u-1,i=0;i<r;i++){var a=Wn(i,o),f=e[i];e[i]=e[a],e[a]=f}return e.slice(0,r)}function kr(n,r){return function(t,e,u){var o=r?[[],[]]:{};return e=qn(e,u),jr(t,(function(r,u){var i=e(r,u,t);n(o,r,i)})),o}}var Dr=kr((function(n,r,t){W(n,t)?n[t].push(r):n[t]=[r]})),Rr=kr((function(n,r,t){n[t]=r})),Fr=kr((function(n,r,t){W(n,t)?n[t]++:n[t]=1})),Vr=kr((function(n,r,t){n[t?0:1].push(r)}),!0),Pr=/[^\ud800-\udfff]|[\ud800-\udbff][\udc00-\udfff]|[\ud800-\udfff]/g;function qr(n,r,t){return r in t}var Ur=j((function(n,r){var t={},e=r[0];if(null==n)return t;D(e)?(r.length>1&&(e=Fn(e,r[1])),r=an(n)):(e=qr,r=ur(r,!1,!1),n=Object(n));for(var u=0,o=r.length;u<o;u++){var i=r[u],a=n[i];e(a,i,n)&&(t[i]=a)}return t})),Wr=j((function(n,r){var t,e=r[0];return D(e)?(e=fr(e),r.length>1&&(t=r[1])):(r=_r(ur(r,!1,!1),String),e=function(n,t){return!Er(r,t)}),Ur(n,e,t)}));function zr(n,r,t){return i.call(n,0,Math.max(0,n.length-(null==r||t?1:r)))}function Lr(n,r,t){return null==n||n.length<1?null==r||t?void 0:[]:null==r||t?n[0]:zr(n,n.length-r)}function $r(n,r,t){return i.call(n,null==r||t?1:r)}var Cr=j((function(n,r){return r=ur(r,!0,!0),Sr(n,(function(n){return!Er(r,n)}))})),Kr=j((function(n,r){return Cr(n,r)}));function Jr(n,r,t,e){A(r)||(e=t,t=r,r=!1),null!=t&&(t=qn(t,e));for(var u=[],o=[],i=0,a=Y(n);i<a;i++){var f=n[i],c=t?t(f,i,n):f;r&&!t?(i&&o===c||u.push(f),o=c):t?Er(o,c)||(o.push(c),u.push(f)):Er(u,f)||u.push(f)}return u}var Gr=j((function(n){return Jr(ur(n,!0,!0))}));function Hr(n){for(var r=n&&Ir(n,Y).length||0,t=Array(r),e=0;e<r;e++)t[e]=Nr(n,e);return t}var Qr=j(Hr);function Xr(n,r){return n._chain?tn(r).chain():r}function Yr(n){return jr(wn(n),(function(r){var t=tn[r]=n[r];tn.prototype[r]=function(){var n=[this._wrapped];return o.apply(n,arguments),Xr(this,t.apply(tn,n))}})),tn}jr(["pop","push","reverse","shift","sort","splice","unshift"],(function(n){var r=t[n];tn.prototype[n]=function(){var t=this._wrapped;return null!=t&&(r.apply(t,arguments),"shift"!==n&&"splice"!==n||0!==t.length||delete t[0]),Xr(this,t)}})),jr(["concat","join","slice"],(function(n){var r=t[n];tn.prototype[n]=function(){var n=this._wrapped;return null!=n&&(n=r.apply(n,arguments)),Xr(this,n)}}));var Zr=Yr({__proto__:null,VERSION:n,restArguments:j,isObject:_,isNull:function(n){return null===n},isUndefined:w,isBoolean:A,isElement:function(n){return!(!n||1!==n.nodeType)},isString:S,isNumber:O,isDate:M,isRegExp:E,isError:B,isSymbol:N,isArrayBuffer:I,isDataView:q,isArray:U,isFunction:D,isArguments:L,isFinite:function(n){return!N(n)&&d(n)&&!isNaN(parseFloat(n))},isNaN:$,isTypedArray:X,isEmpty:function(n){if(null==n)return!0;var r=Y(n);return"number"==typeof r&&(U(n)||S(n)||L(n))?0===r:0===Y(nn(n))},isMatch:rn,isEqual:function(n,r){return on(n,r)},isMap:dn,isWeakMap:gn,isSet:bn,isWeakSet:mn,keys:nn,allKeys:an,values:jn,pairs:function(n){for(var r=nn(n),t=r.length,e=Array(t),u=0;u<t;u++)e[u]=[r[u],n[r[u]]];return e},invert:_n,functions:wn,methods:wn,extend:xn,extendOwn:Sn,assign:Sn,defaults:On,create:function(n,r){var t=Mn(n);return r&&Sn(t,r),t},clone:En,tap:function(n,r){return r(n),n},get:Tn,has:function(n,r){for(var t=(r=Nn(r)).length,e=0;e<t;e++){var u=r[e];if(!W(n,u))return!1;n=n[u]}return!!t},mapObject:function(n,r,t){r=qn(r,t);for(var e=nn(n),u=e.length,o={},i=0;i<u;i++){var a=e[i];o[a]=r(n[a],a,n)}return o},identity:kn,constant:C,noop:Un,toPath:Bn,property:Rn,propertyOf:function(n){return null==n?Un:function(r){return Tn(n,r)}},matcher:Dn,matches:Dn,times:function(n,r,t){var e=Array(Math.max(0,n));r=Fn(r,t,1);for(var u=0;u<n;u++)e[u]=r(u);return e},random:Wn,now:zn,escape:Cn,unescape:Kn,templateSettings:Jn,template:function(n,r,t){!r&&t&&(r=t),r=On({},r,tn.templateSettings);var e=RegExp([(r.escape||Gn).source,(r.interpolate||Gn).source,(r.evaluate||Gn).source].join("|")+"|$","g"),u=0,o="__p+='";n.replace(e,(function(r,t,e,i,a){return o+=n.slice(u,a).replace(Qn,Xn),u=a+r.length,t?o+="'+\n((__t=("+t+"))==null?'':_.escape(__t))+\n'":e?o+="'+\n((__t=("+e+"))==null?'':__t)+\n'":i&&(o+="';\n"+i+"\n__p+='"),r})),o+="';\n";var i,a=r.variable;if(a){if(!Yn.test(a))throw new Error("variable is not a bare identifier: "+a)}else o="with(obj||{}){\n"+o+"}\n",a="obj";o="var __t,__p='',__j=Array.prototype.join,"+"print=function(){__p+=__j.call(arguments,'');};\n"+o+"return __p;\n";try{i=new Function(a,"_",o)}catch(n){throw n.source=o,n}var f=function(n){return i.call(this,n,tn)};return f.source="function("+a+"){\n"+o+"}",f},result:function(n,r,t){var e=(r=Nn(r)).length;if(!e)return D(t)?t.call(n):t;for(var u=0;u<e;u++){var o=null==n?void 0:n[r[u]];void 0===o&&(o=t,u=e),n=D(o)?o.call(n):o}return n},uniqueId:function(n){var r=++Zn+"";return n?n+r:r},chain:function(n){var r=tn(n);return r._chain=!0,r},iteratee:Pn,partial:rr,bind:tr,bindAll:or,memoize:function(n,r){var t=function(e){var u=t.cache,o=""+(r?r.apply(this,arguments):e);return W(u,o)||(u[o]=n.apply(this,arguments)),u[o]};return t.cache={},t},delay:ir,defer:ar,throttle:function(n,r,t){var e,u,o,i,a=0;t||(t={});var f=function(){a=!1===t.leading?0:zn(),e=null,i=n.apply(u,o),e||(u=o=null)},c=function(){var c=zn();a||!1!==t.leading||(a=c);var l=r-(c-a);return u=this,o=arguments,l<=0||l>r?(e&&(clearTimeout(e),e=null),a=c,i=n.apply(u,o),e||(u=o=null)):e||!1===t.trailing||(e=setTimeout(f,l)),i};return c.cancel=function(){clearTimeout(e),a=0,e=u=o=null},c},debounce:function(n,r,t){var e,u,o,i,a,f=function(){var c=zn()-u;r>c?e=setTimeout(f,r-c):(e=null,t||(i=n.apply(a,o)),e||(o=a=null))},c=j((function(c){return a=this,o=c,u=zn(),e||(e=setTimeout(f,r),t&&(i=n.apply(a,o))),i}));return c.cancel=function(){clearTimeout(e),e=o=a=null},c},wrap:function(n,r){return rr(r,n)},negate:fr,compose:function(){var n=arguments,r=n.length-1;return function(){for(var t=r,e=n[r].apply(this,arguments);t--;)e=n[t].call(this,e);return e}},after:function(n,r){return function(){if(--n<1)return r.apply(this,arguments)}},before:cr,once:lr,findKey:sr,findIndex:vr,findLastIndex:hr,sortedIndex:yr,indexOf:gr,lastIndexOf:br,find:mr,detect:mr,findWhere:function(n,r){return mr(n,Dn(r))},each:jr,forEach:jr,map:_r,collect:_r,reduce:Ar,foldl:Ar,inject:Ar,reduceRight:xr,foldr:xr,filter:Sr,select:Sr,reject:function(n,r,t){return Sr(n,fr(qn(r)),t)},every:Or,all:Or,some:Mr,any:Mr,contains:Er,includes:Er,include:Er,invoke:Br,pluck:Nr,where:function(n,r){return Sr(n,Dn(r))},max:Ir,min:function(n,r,t){var e,u,o=1/0,i=1/0;if(null==r||"number"==typeof r&&"object"!=typeof n[0]&&null!=n)for(var a=0,f=(n=er(n)?n:jn(n)).length;a<f;a++)null!=(e=n[a])&&e<o&&(o=e);else r=qn(r,t),jr(n,(function(n,t,e){((u=r(n,t,e))<i||u===1/0&&o===1/0)&&(o=n,i=u)}));return o},shuffle:function(n){return Tr(n,1/0)},sample:Tr,sortBy:function(n,r,t){var e=0;return r=qn(r,t),Nr(_r(n,(function(n,t,u){return{value:n,index:e++,criteria:r(n,t,u)}})).sort((function(n,r){var t=n.criteria,e=r.criteria;if(t!==e){if(t>e||void 0===t)return 1;if(t<e||void 0===e)return-1}return n.index-r.index})),"value")},groupBy:Dr,indexBy:Rr,countBy:Fr,partition:Vr,toArray:function(n){return n?U(n)?i.call(n):S(n)?n.match(Pr):er(n)?_r(n,kn):jn(n):[]},size:function(n){return null==n?0:er(n)?n.length:nn(n).length},pick:Ur,omit:Wr,first:Lr,head:Lr,take:Lr,initial:zr,last:function(n,r,t){return null==n||n.length<1?null==r||t?void 0:[]:null==r||t?n[n.length-1]:$r(n,Math.max(0,n.length-r))},rest:$r,tail:$r,drop:$r,compact:function(n){return Sr(n,Boolean)},flatten:function(n,r){return ur(n,r,!1)},without:Kr,uniq:Jr,unique:Jr,union:Gr,intersection:function(n){for(var r=[],t=arguments.length,e=0,u=Y(n);e<u;e++){var o=n[e];if(!Er(r,o)){var i;for(i=1;i<t&&Er(arguments[i],o);i++);i===t&&r.push(o)}}return r},difference:Cr,unzip:Hr,transpose:Hr,zip:Qr,object:function(n,r){for(var t={},e=0,u=Y(n);e<u;e++)r?t[n[e]]=r[e]:t[n[e][0]]=n[e][1];return t},range:function(n,r,t){null==r&&(r=n||0,n=0),t||(t=r<n?-1:1);for(var e=Math.max(Math.ceil((r-n)/t),0),u=Array(e),o=0;o<e;o++,n+=t)u[o]=n;return u},chunk:function(n,r){if(null==r||r<1)return[];for(var t=[],e=0,u=n.length;e<u;)t.push(i.call(n,e,e+=r));return t},mixin:Yr,default:tn});return Zr._=Zr,Zr}));
\ No newline at end of file diff --git a/guide/any.html b/guide/any.html new file mode 100644 index 0000000..fd68055 --- /dev/null +++ b/guide/any.html @@ -0,0 +1,372 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>python-any-r1 — build-time dependency — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="python-single-r1 — single-impl packages" href="single.html" /> + <link rel="prev" title="Common basics" href="basic.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="python-any-r1-build-time-dependency"> +<h1>python-any-r1 — build-time dependency<a class="headerlink" href="#python-any-r1-build-time-dependency" title="Permalink to this headline">¶</a></h1> +<p>The <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code> eclass is used to enable Python support +in packages needing it purely at build time.</p> +<p>Eclass reference: <a class="reference external" href="https://devmanual.gentoo.org/eclass-reference/python-any-r1.eclass/index.html">python-any-r1.eclass(5)</a></p> +<section id="basic-use-for-unconditional-python"> +<h2>Basic use for unconditional Python<a class="headerlink" href="#basic-use-for-unconditional-python" title="Permalink to this headline">¶</a></h2> +<p>The defining feature of this eclass is that it defines a <code class="docutils literal notranslate"><span class="pre">pkg_setup</span></code> +phase. It normally calls <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> function in order to find +a suitable Python interpreter, and set the global environment +appropriately.</p> +<p>This means that a most trivial package using an autotools-compatible +build system that needs Python at build time could look like +the following:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + +<span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>..8<span class="o">}</span> <span class="o">)</span> +</span><span class="hll"> inherit python-any-r1 +</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"A repository of data files describing media player capabilities"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://cgit.freedesktop.org/media-player-info/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://www.freedesktop.org/software/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 ~arm ~arm64 ~hppa ~ia64 ~mips ppc ppc64 ~sh ~sparc x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">""</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">">=virtual/udev-208"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2">"</span> + <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +</span><span class="s2"> virtual/pkgconfig</span> +<span class="s2"> "</span> +</pre></div> +</div> +<p>This ebuild demonstrates the absolute minimum working code. Only +the three highlighted lines are specific to Python eclasses, plus +the implicitly exported <code class="docutils literal notranslate"><span class="pre">pkg_setup</span></code> phase.</p> +<span class="target" id="index-0"></span><span class="target" id="index-1"></span></section> +<section id="dependencies"> +<span id="index-2"></span><h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2> +<p>When depending on other Python packages, USE dependencies need to be +declared in order to ensure that the dependencies would be built against +the Python implementation used for the package. When Python +dependencies need to be specified, <code class="docutils literal notranslate"><span class="pre">${PYTHON_DEPS}</span></code> gets replaced +by a call to <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code> generator and a matching +<code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code> function.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code> function accepts a template where literal +<code class="docutils literal notranslate"><span class="pre">${PYTHON_USEDEP}</span></code> is substituted with appropriate USE dependency. +It generates an any-of (<code class="docutils literal notranslate"><span class="pre">||</span></code>) dependency that requires all +the packages to use the same Python interpreter, for at least one +of the supported implementations.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code> function needs to be declared by ebuild +in order to test whether the implementation in question is suitable +for building the package. In particular, it needs to verify whether +the particular branch of the any-of was satisfied, or whether all +dependencies were installed for the current interpreter. For that +purpose, the function is called with <code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> variable declared +to the USE dependency string for the currently tested implementation.</p> +<p>This is best explained using an example:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> <span class="o">)</span> + + inherit meson python-any-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"A file manager for Cinnamon, forked from Nautilus"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"http://developer.linuxmint.com/projects/cinnamon-projects.html"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/linuxmint/nemo/archive/</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">.tar.gz -> </span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2+ LGPL-2+ FDL-1.1"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"amd64 x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">""</span> + + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> dev-python/polib[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/pygobject:3[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> "</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/polib[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/pygobject:3[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span></pre></div> +</div> +<p>This means that the package will work with Python 3.6, 3.7 or 3.8, +provided that its both dependencies have the same implementation +enabled. The generated <code class="docutils literal notranslate"><span class="pre">||</span></code> dep ensures that this is true for +at least one of them, while <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code> verifies which +branch was satisfied.</p> +<p>It is important to understand that this works correctly only if +<code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code> and <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code> match exactly. +Furthermore, for any USE flag combination <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code> must be +called at most once. In particular, it is invalid to split the above +example into multiple <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code> calls.</p> +</section> +<section id="conditional-python-use"> +<h2>Conditional Python use<a class="headerlink" href="#conditional-python-use" title="Permalink to this headline">¶</a></h2> +<p>In some packages, Python is only necessary with specific USE flag +combinations. This is particularly common when Python is used for +the test suite. In that case, the dependencies and <code class="docutils literal notranslate"><span class="pre">pkg_setup</span></code> call +need to be wrapped in appropriate USE conditions:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7<span class="o">}</span> <span class="o">)</span> + inherit python-any-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Programmable Completion for bash"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/scop/bash-completion"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/scop/bash-completion/releases/download/</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.xz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2+"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 arm ~arm64 ~hppa ia64 ~mips ppc ~ppc64 ~s390 ~sh sparc x86 ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos ~m68k-mint ~sparc-solaris ~sparc64-solaris"</span> +<span class="hll"> <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"test"</span> +</span><span class="hll"> <span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span> +</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">">=app-shells/bash-4.3_p30-r1:0"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> test? (</span> +</span><span class="hll"><span class="s2"> </span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +</span><span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> dev-python/pexpect[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/pytest[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +</span><span class="hll"><span class="s2"> )"</span> +</span> + python_check_deps<span class="o">()</span> <span class="o">{</span> + has_version -d <span class="s2">"dev-python/pexpect[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> + has_version -d <span class="s2">"dev-python/pytest[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> + <span class="o">}</span> + + pkg_setup<span class="o">()</span> <span class="o">{</span> +<span class="hll"> use <span class="nb">test</span> <span class="o">&&</span> python-any-r1_pkg_setup +</span> <span class="o">}</span> +</pre></div> +</div> +</section> +<section id="additional-conditional-dependencies"> +<h2>Additional conditional dependencies<a class="headerlink" href="#additional-conditional-dependencies" title="Permalink to this headline">¶</a></h2> +<p>Another possible case is that Python is required unconditionally +but some dependencies are required only conditionally to USE flags. +The simplest way to achieve that is to use <code class="docutils literal notranslate"><span class="pre">${PYTHON_DEPS}</span></code> globally +and <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code> in USE-conditional block, then express +a similar condition in <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code>:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7<span class="o">}</span> <span class="o">)</span> + inherit python-any-r1 cmake + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Qt bindings for the Telepathy D-Bus protocol"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://telepathy.freedesktop.org/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://telepathy.freedesktop.org/releases/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"LGPL-2.1"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"amd64 ~arm arm64 x86"</span> +<span class="hll"> <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"test"</span> +</span> <span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span> + +<span class="hll"> <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +</span><span class="hll"><span class="s2"> test? (</span> +</span><span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> dev-python/dbus-python[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +</span><span class="hll"><span class="s2"> )</span> +</span><span class="s2"> "</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> use <span class="nb">test</span> <span class="o">||</span> <span class="k">return</span> <span class="m">0</span> +</span><span class="hll"> has_version -b <span class="s2">"dev-python/dbus-python[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span></pre></div> +</div> +</section> +<section id="multiple-sets-of-conditional-dependencies"> +<h2>Multiple sets of conditional dependencies<a class="headerlink" href="#multiple-sets-of-conditional-dependencies" title="Permalink to this headline">¶</a></h2> +<p>The hardest case for this eclass is to declare multiple Python +dependencies conditional to different USE flags. While there are +multiple possible ways of doing that, the least error-prone is to move +USE conditional blocks inside <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code>:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_6 <span class="o">)</span> + + inherit gnome2 python-any-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"GObject library for accessing the freedesktop.org Secret Service API"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://wiki.gnome.org/Projects/Libsecret"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"LGPL-2.1+ Apache-2.0"</span> <span class="c1"># Apache-2.0 license is used for tests only</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 arm arm64 ia64 ~mips ppc ppc64 sparc x86"</span> +<span class="hll"> <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"+introspection test"</span> +</span> <span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span> + <span class="c1"># Tests fail with USE=-introspection, https://bugs.gentoo.org/655482</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"test? ( introspection )"</span> + + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> test? (</span> +</span><span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> dev-python/mock[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/dbus-python[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> introspection? ( dev-python/pygobject:3[${PYTHON_USEDEP}] )</span> +</span><span class="hll"><span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +</span><span class="hll"><span class="s2"> )</span> +</span><span class="s2"> "</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> <span class="k">if</span> use introspection<span class="p">;</span> <span class="k">then</span> +</span><span class="hll"> has_version --host-root <span class="s2">"dev-python/pygobject:3[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">||</span> <span class="k">return</span> <span class="m">1</span> +</span><span class="hll"> <span class="k">fi</span> +</span><span class="hll"> has_version --host-root <span class="s2">"dev-python/mock[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> +</span><span class="hll"> has_version --host-root <span class="s2">"dev-python/dbus-python[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + pkg_setup<span class="o">()</span> <span class="o">{</span> +<span class="hll"> use <span class="nb">test</span> <span class="o">&&</span> python-any-r1_pkg_setup +</span> <span class="o">}</span> +</pre></div> +</div> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">python-any-r1 — build-time dependency</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#basic-use-for-unconditional-python">Basic use for unconditional Python</a></li> +<li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="#conditional-python-use">Conditional Python use</a></li> +<li class="toctree-l2"><a class="reference internal" href="#additional-conditional-dependencies">Additional conditional dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="#multiple-sets-of-conditional-dependencies">Multiple sets of conditional dependencies</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="basic.html" title="previous chapter">Common basics</a></li> + <li>Next: <a href="single.html" title="next chapter">python-single-r1 — single-impl packages</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/any.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/basic.html b/guide/basic.html new file mode 100644 index 0000000..ac2c0e0 --- /dev/null +++ b/guide/basic.html @@ -0,0 +1,194 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Common basics — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="python-any-r1 — build-time dependency" href="any.html" /> + <link rel="prev" title="Choosing between Python eclasses" href="eclass.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="common-basics"> +<h1>Common basics<a class="headerlink" href="#common-basics" title="Permalink to this headline">¶</a></h1> +<p>The various eclasses in python-r1 try to follow a single design. You +will probably use more than one of them, so it is worthwhile to shortly +explain the common bits used by all of them, as well as the non-obvious +differences between them.</p> +<section id="python-compat"> +<span id="index-0"></span><h2>PYTHON_COMPAT<a class="headerlink" href="#python-compat" title="Permalink to this headline">¶</a></h2> +<p>The <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code> variable is used by all Python eclasses, and must +be declared in all ebuilds before they are inherited. It specifies +the list of Python implementations supported by the package.</p> +<p>The valid values are:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">pythonX_Y</span></code> for CPython X.Y</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">pypy3</span></code> for PyPy3.</p></li> +</ul> +<p>Typical use:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> pypy3 <span class="o">)</span> +inherit python-single-r1 +</pre></div> +</div> +<span class="target" id="index-1"></span></section> +<section id="python-deps-and-python-required-use"> +<span id="index-2"></span><h2>PYTHON_DEPS and PYTHON_REQUIRED_USE<a class="headerlink" href="#python-deps-and-python-required-use" title="Permalink to this headline">¶</a></h2> +<p>The <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code>, <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> and <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> eclasses +all assume that the developer is responsible for explicitly putting +the dependency strings and USE requirements in correct variables. +This is meant to consistently cover packages that use Python +unconditionally and conditionally, at build time and at runtime.</p> +<p>For <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> and <code class="docutils literal notranslate"><span class="pre">python-r1</span></code>, the most basic form to use +Python unconditionally is to define the following:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span> + +<span class="nv">RDEPEND</span><span class="o">=</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span> +<span class="nv">BDEPEND</span><span class="o">=</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span> +</pre></div> +</div> +<p>For <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code>, only build-time dependencies are used:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">BDEPEND</span><span class="o">=</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span> +</pre></div> +</div> +<p>This does not apply to <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> as it does the above assignment +by default.</p> +<span class="target" id="index-3"></span></section> +<section id="python-environment"> +<span id="index-4"></span><h2>Python environment<a class="headerlink" href="#python-environment" title="Permalink to this headline">¶</a></h2> +<p>The eclasses commonly use the concept of <em>Python environment</em>. This +means a state of environment enforcing a particular Python +implementation. Whenever the ebuild code is run inside this +environment, <code class="docutils literal notranslate"><span class="pre">EPYTHON</span></code> variable indicates which implementation +is being used (by its executable name, e.g. <code class="docutils literal notranslate"><span class="pre">python3.8</span></code>).</p> +<p>Additionally, <code class="docutils literal notranslate"><span class="pre">PYTHON</span></code> provides the absolute path to the interpreter +(however, using <code class="docutils literal notranslate"><span class="pre">EPYTHON</span></code> is preferable whenever possible). Wrappers +for <code class="docutils literal notranslate"><span class="pre">python</span></code>, <code class="docutils literal notranslate"><span class="pre">pythonN</span></code> and some common tools are provided in PATH, +and <code class="docutils literal notranslate"><span class="pre">/usr/bin/python</span></code> etc. also enforce the specific implementation +via python-exec (for programs that hardcode full path).</p> +<p>The environment can be either established in local scope, or globally. +The local scope generally applies to multi-impl packages, and is created +either by calls to <code class="docutils literal notranslate"><span class="pre">python_foreach_impl</span></code> from <code class="docutils literal notranslate"><span class="pre">python-r1</span></code>, or inside +sub-phase functions in <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code>. The global scope setup is done +via calling <code class="docutils literal notranslate"><span class="pre">python_setup</span></code>, either directly or via default +<code class="docutils literal notranslate"><span class="pre">pkg_setup</span></code> in <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code> and <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>.</p> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Common basics</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#python-compat">PYTHON_COMPAT</a></li> +<li class="toctree-l2"><a class="reference internal" href="#python-deps-and-python-required-use">PYTHON_DEPS and PYTHON_REQUIRED_USE</a></li> +<li class="toctree-l2"><a class="reference internal" href="#python-environment">Python environment</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="eclass.html" title="previous chapter">Choosing between Python eclasses</a></li> + <li>Next: <a href="any.html" title="next chapter">python-any-r1 — build-time dependency</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/basic.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/buildsys.html b/guide/buildsys.html new file mode 100644 index 0000000..fe5e788 --- /dev/null +++ b/guide/buildsys.html @@ -0,0 +1,745 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Integration with build systems written in Python — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Porting tips" href="porting.html" /> + <link rel="prev" title="Expert python-r1 usage" href="expert-multi.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="integration-with-build-systems-written-in-python"> +<h1>Integration with build systems written in Python<a class="headerlink" href="#integration-with-build-systems-written-in-python" title="Permalink to this headline">¶</a></h1> +<p>Besides the build systems commonly used by Python packages there are +a few build systems written in Python and requiring the packages +to script them in Python. This makes it necessary to use a proper +Python eclass in order to declare their compatibility with Python +versions.</p> +<section id="meson"> +<h2>Meson<a class="headerlink" href="#meson" title="Permalink to this headline">¶</a></h2> +<p><a class="reference external" href="https://mesonbuild.com/">Meson</a> build system is a fairly recent addition. While it is written +in Python, its scripts use a custom Python-agnostic script language. +Hence, it can be treated as an arbitrary external tool and does not need +any Python eclass.</p> +</section> +<section id="scons"> +<h2>SCons<a class="headerlink" href="#scons" title="Permalink to this headline">¶</a></h2> +<p><a class="reference external" href="https://scons.org/">SCons</a> has gained Python 3 support quite recently. At the same time, +many old script files were written for Python 2 and fail when run +via Python 3 SCons. For this reason, it is necessary to use Python +eclass when using SCons.</p> +<p>In the simplest case when the package has no other use for Python, +it is sufficient to declare <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code> for the SCons scripts +in the package, and inherit <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code> prior to <code class="docutils literal notranslate"><span class="pre">scons-utils</span></code> +(this happens naturally when you sort includes by eclass name). +The latter eclass takes care of setting as much as possible.</p> +<p>If the package has other Python components, it is necessary to account +for them and use an appropriate eclass as detailed in the eclass choice +chapter.</p> +<section id="build-time-use-with-no-extra-dependencies"> +<h3>Build-time use with no extra dependencies<a class="headerlink" href="#build-time-use-with-no-extra-dependencies" title="Permalink to this headline">¶</a></h3> +<p>If the package either has no other Python components than SCons, or all +of them are purely build-time and have no dependencies, it is sufficient +to inherit <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code>. The eclass takes care of setting +<code class="docutils literal notranslate"><span class="pre">BDEPEND</span></code> along with matching <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code>.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + +<span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7<span class="o">}</span> <span class="o">)</span> +</span><span class="hll"> inherit python-any-r1 scons-utils toolchain-funcs +</span> + <span class="nv">COMMIT</span><span class="o">=</span><span class="s2">"6e5e8a57628095d8d0c8bbb38187afb0f3a42112"</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Userspace Xbox 360 Controller driver"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://xboxdrv.gitlab.io"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/chewi/xboxdrv/archive/</span><span class="si">${</span><span class="nv">COMMIT</span><span class="si">}</span><span class="s2">.tar.gz -> </span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + <span class="nv">S</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">WORKDIR</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">-</span><span class="si">${</span><span class="nv">COMMIT</span><span class="si">}</span><span class="s2">"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-3"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> dev-libs/boost:=</span> +<span class="s2"> dev-libs/dbus-glib</span> +<span class="s2"> dev-libs/glib:2</span> +<span class="s2"> sys-apps/dbus</span> +<span class="s2"> virtual/libudev:=</span> +<span class="s2"> virtual/libusb:1</span> +<span class="s2"> x11-libs/libX11</span> +<span class="s2"> "</span> + + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> </span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> "</span> + + <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> dev-util/glib-utils</span> +<span class="s2"> virtual/pkgconfig</span> +<span class="s2"> "</span> + + src_compile<span class="o">()</span> <span class="o">{</span> + escons <span class="se">\</span> + <span class="nv">BUILD</span><span class="o">=</span>custom <span class="se">\</span> + <span class="nv">CXX</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>tc-getCXX<span class="k">)</span><span class="s2">"</span> <span class="se">\</span> + <span class="nv">AR</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>tc-getAR<span class="k">)</span><span class="s2">"</span> <span class="se">\</span> + <span class="nv">RANLIB</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>tc-getRANLIB<span class="k">)</span><span class="s2">"</span> <span class="se">\</span> + <span class="nv">CXXFLAGS</span><span class="o">=</span><span class="s2">"-Wall </span><span class="si">${</span><span class="nv">CXXFLAGS</span><span class="si">}</span><span class="s2">"</span> <span class="se">\</span> + <span class="nv">LINKFLAGS</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">LDFLAGS</span><span class="si">}</span><span class="s2">"</span> + <span class="o">}</span> + + src_install<span class="o">()</span> <span class="o">{</span> + dobin xboxdrv + doman doc/xboxdrv.1 + dodoc AUTHORS NEWS PROTOCOL README.md TODO + <span class="o">}</span> +</pre></div> +</div> +</section> +<section id="build-time-use-with-extra-dependencies"> +<h3>Build-time use with extra dependencies<a class="headerlink" href="#build-time-use-with-extra-dependencies" title="Permalink to this headline">¶</a></h3> +<p>If the package has extra dependencies, you need to take care of <em>all</em> +dependencies yourself. This is because <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code> cannot +be combined.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + +<span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7<span class="o">}</span> <span class="o">)</span> +</span><span class="hll"> inherit python-any-r1 scons-utils toolchain-funcs +</span> + <span class="nv">MY_P</span><span class="o">=</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span>-src-r<span class="si">${</span><span class="nv">PV</span><span class="p">/_rc/-rc</span><span class="si">}</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"A high-performance, open source, schema-free document-oriented database"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://www.mongodb.com"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://fastdl.mongodb.org/src/</span><span class="si">${</span><span class="nv">MY_P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + <span class="nv">S</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">WORKDIR</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">MY_P</span><span class="si">}</span><span class="s2">"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"Apache-2.0 SSPL-1"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"test +tools"</span> + <span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"acct-group/mongodb</span> +<span class="s2"> acct-user/mongodb</span> +<span class="s2"> >=app-arch/snappy-1.1.3</span> +<span class="s2"> >=dev-cpp/yaml-cpp-0.6.2:=</span> +<span class="s2"> >=dev-libs/boost-1.70:=[threads(+)]</span> +<span class="s2"> >=dev-libs/libpcre-8.42[cxx]</span> +<span class="s2"> app-arch/zstd</span> +<span class="s2"> dev-libs/snowball-stemmer</span> +<span class="s2"> net-libs/libpcap</span> +<span class="s2"> >=sys-libs/zlib-1.2.11:="</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +<span class="s1"> test? ( dev-python/pymongo[${PYTHON_USEDEP}] )</span> +<span class="hll"><span class="s1"> >=dev-util/scons-2.5.0[${PYTHON_USEDEP}]</span> +</span><span class="s1"> dev-python/cheetah3[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/psutil[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/pyyaml[${PYTHON_USEDEP}]</span> +<span class="s1"> virtual/python-typing[${PYTHON_USEDEP}]</span> +<span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +<span class="s2"> sys-libs/ncurses:0=</span> +<span class="s2"> sys-libs/readline:0="</span> + <span class="nv">PDEPEND</span><span class="o">=</span><span class="s2">"tools? ( >=app-admin/mongo-tools-</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2"> )"</span> + + python_check_deps<span class="o">()</span> <span class="o">{</span> + <span class="k">if</span> use test<span class="p">;</span> <span class="k">then</span> + has_version <span class="s2">"dev-python/pymongo[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">||</span> + <span class="k">return</span> <span class="m">1</span> + <span class="k">fi</span> + +<span class="hll"> has_version <span class="s2">">=dev-util/scons-2.5.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> +</span> has_version <span class="s2">"dev-python/cheetah3[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> + has_version <span class="s2">"dev-python/psutil[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> + has_version <span class="s2">"dev-python/pyyaml[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> + has_version <span class="s2">"virtual/python-typing[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> + <span class="o">}</span> + + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nv">scons_opts</span><span class="o">=(</span> + <span class="nv">CC</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>tc-getCC<span class="k">)</span><span class="s2">"</span> + <span class="nv">CXX</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>tc-getCXX<span class="k">)</span><span class="s2">"</span> + + --disable-warnings-as-errors + --use-system-boost + --use-system-pcre + --use-system-snappy + --use-system-stemmer + --use-system-yaml + --use-system-zlib + --use-system-zstd + <span class="o">)</span> + + default + <span class="o">}</span> + + src_compile<span class="o">()</span> <span class="o">{</span> + escons <span class="s2">"</span><span class="si">${</span><span class="nv">scons_opts</span><span class="p">[@]</span><span class="si">}</span><span class="s2">"</span> core tools + <span class="o">}</span> + + src_test<span class="o">()</span> <span class="o">{</span> + <span class="s2">"</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">"</span> ./buildscripts/resmoke.py --dbpathPrefix<span class="o">=</span><span class="nb">test</span> <span class="se">\</span> + --suites core --jobs<span class="o">=</span><span class="k">$(</span>makeopts_jobs<span class="k">)</span> <span class="o">||</span> die <span class="s2">"Tests failed"</span> + <span class="o">}</span> + + src_install<span class="o">()</span> <span class="o">{</span> + escons <span class="s2">"</span><span class="si">${</span><span class="nv">scons_opts</span><span class="p">[@]</span><span class="si">}</span><span class="s2">"</span> --nostrip install --prefix<span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">ED</span><span class="si">}</span><span class="s2">"</span>/usr + <span class="o">}</span> +</pre></div> +</div> +</section> +<section id="single-impl-package"> +<h3>Single-impl package<a class="headerlink" href="#single-impl-package" title="Permalink to this headline">¶</a></h3> +<p>If the package needs to install some Python components, and single-impl +install is appropriate, you need to combine <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> +with <code class="docutils literal notranslate"><span class="pre">scons-utils</span></code>. In this case, the eclass takes care of everything +needed for SCons, and you take care of everything needed for your +package.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">5</span> + +<span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 <span class="o">)</span> +</span><span class="hll"> inherit eutils python-single-r1 scons-utils toolchain-funcs +</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Molecular dynamics by NMR data analysis"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://www.nmr-relax.com/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"http://download.gna.org/relax/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.src.tar.bz2"</span> + + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86 ~amd64-linux ~x86-linux"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"test"</span> + <span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span> +<span class="hll"> <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> +</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s2">"</span> +<span class="s2"> dev-python/Numdifftools[\${PYTHON_USEDEP}]</span> +<span class="s2"> || (</span> +<span class="s2"> dev-python/matplotlib-python2[\${PYTHON_USEDEP}]</span> +<span class="s2"> dev-python/matplotlib[\${PYTHON_USEDEP}]</span> +<span class="s2"> )</span> +<span class="s2"> || (</span> +<span class="s2"> dev-python/numpy-python2[\${PYTHON_USEDEP}]</span> +<span class="s2"> dev-python/numpy[\${PYTHON_USEDEP}]</span> +<span class="s2"> )</span> +<span class="s2"> dev-python/wxpython:</span><span class="si">${</span><span class="nv">WX_GTK_VER</span><span class="si">}</span><span class="s2">[\${PYTHON_USEDEP}]</span> +<span class="s2"> sci-chemistry/pymol[\${PYTHON_USEDEP}]</span> +<span class="s2"> >=sci-libs/bmrblib-1.0.3[\${PYTHON_USEDEP}]</span> +<span class="s2"> >=sci-libs/minfx-1.0.11[\${PYTHON_USEDEP}]</span> +<span class="s2"> || (</span> +<span class="s2"> sci-libs/scipy-python2[\${PYTHON_USEDEP}]</span> +<span class="s2"> sci-libs/scipy[\${PYTHON_USEDEP}]</span> +<span class="s2"> )</span> +<span class="s2"> "</span><span class="k">)</span><span class="s2"></span> +<span class="s2"> sci-chemistry/molmol</span> +<span class="s2"> sci-chemistry/vmd</span> +<span class="s2"> sci-visualization/grace</span> +<span class="s2"> sci-visualization/opendx"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> media-gfx/pngcrush</span> +<span class="s2"> test? ( </span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"> )</span> +<span class="s2"> "</span> + + src_compile<span class="o">()</span> <span class="o">{</span> + tc-export CC + escons + <span class="o">}</span> + + src_install<span class="o">()</span> <span class="o">{</span> + python_moduleinto <span class="si">${</span><span class="nv">PN</span><span class="si">}</span> + python_domodule * + + make_wrapper <span class="si">${</span><span class="nv">PN</span><span class="si">}</span>-nmr <span class="s2">"</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2"> </span><span class="k">$(</span>python_get_sitedir<span class="k">)</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">.py </span><span class="nv">$@</span><span class="s2">"</span> + <span class="o">}</span> +</pre></div> +</div> +</section> +<section id="single-impl-package-with-conditional-python-install"> +<h3>Single-impl package with conditional Python install<a class="headerlink" href="#single-impl-package-with-conditional-python-install" title="Permalink to this headline">¶</a></h3> +<p>If the runtime part of the package uses Python only conditionally, +the use is similar to a package with unconditional build-time +and conditional runtime dependency on Python. That is, build-time +dependencies, <code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code> and <code class="docutils literal notranslate"><span class="pre">pkg_setup</span></code> must be called +unconditionally.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + +<span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> <span class="o">)</span> +</span> + <span class="nv">FORTRAN_NEEDED</span><span class="o">=</span>fortran + <span class="nv">FORTRAN_STANDARD</span><span class="o">=</span><span class="m">90</span> + +<span class="hll"> inherit python-single-r1 scons-utils toolchain-funcs +</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Object-oriented tool suite for chemical kinetics, thermodynamics, and transport"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://www.cantera.org"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/Cantera/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/archive/v</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">.tar.gz -> </span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"amd64 ~x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"fortran pch +python"</span> + + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"></span> +</span><span class="s2"> "</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> python? (</span> +<span class="s2"> </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +<span class="s1"> dev-python/numpy[${PYTHON_USEDEP}]</span> +<span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +<span class="s2"> )</span> +<span class="s2"> <sci-libs/sundials-5.1.0:0=</span> +<span class="s2"> "</span> + + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> </span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> dev-cpp/eigen:3</span> +<span class="s2"> dev-libs/boost</span> +<span class="s2"> dev-libs/libfmt</span> +<span class="s2"> python? (</span> +<span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +<span class="s1"> dev-python/cython[${PYTHON_USEDEP}]</span> +<span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +<span class="s2"> )</span> +<span class="s2"> "</span> + + pkg_setup<span class="o">()</span> <span class="o">{</span> + fortran-2_pkg_setup +<span class="hll"> python-single-r1_pkg_setup +</span> <span class="o">}</span> + + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nv">scons_vars</span><span class="o">=(</span> + <span class="nv">CC</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>tc-getCC<span class="k">)</span><span class="s2">"</span> + <span class="nv">CXX</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>tc-getCXX<span class="k">)</span><span class="s2">"</span> + <span class="nv">cc_flags</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">CXXFLAGS</span><span class="si">}</span><span class="s2">"</span> + <span class="nv">cxx_flags</span><span class="o">=</span><span class="s2">"-std=c++11"</span> + <span class="nv">debug</span><span class="o">=</span><span class="s2">"no"</span> + <span class="nv">FORTRAN</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>tc-getFC<span class="k">)</span><span class="s2">"</span> + <span class="nv">FORTRANFLAGS</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">CXXFLAGS</span><span class="si">}</span><span class="s2">"</span> + <span class="nv">optimize_flags</span><span class="o">=</span><span class="s2">"-Wno-inline"</span> + <span class="nv">renamed_shared_libraries</span><span class="o">=</span><span class="s2">"no"</span> + <span class="nv">use_pch</span><span class="o">=</span><span class="k">$(</span>usex pch<span class="k">)</span> + <span class="nv">system_fmt</span><span class="o">=</span><span class="s2">"y"</span> + <span class="nv">system_sundials</span><span class="o">=</span><span class="s2">"y"</span> + <span class="nv">system_eigen</span><span class="o">=</span><span class="s2">"y"</span> + <span class="nv">env_vars</span><span class="o">=</span><span class="s2">"all"</span> + <span class="nv">extra_inc_dirs</span><span class="o">=</span><span class="s2">"/usr/include/eigen3"</span> + <span class="o">)</span> + + <span class="nv">scons_targets</span><span class="o">=(</span> + <span class="nv">f90_interface</span><span class="o">=</span><span class="k">$(</span>usex fortran y n<span class="k">)</span> + <span class="nv">python2_package</span><span class="o">=</span><span class="s2">"none"</span> + <span class="o">)</span> + + <span class="k">if</span> use python <span class="p">;</span> <span class="k">then</span> + <span class="nv">scons_targets</span><span class="o">+=(</span> <span class="nv">python3_package</span><span class="o">=</span><span class="s2">"full"</span> <span class="nv">python3_cmd</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">"</span> <span class="o">)</span> + <span class="k">else</span> + <span class="nv">scons_targets</span><span class="o">+=(</span> <span class="nv">python3_package</span><span class="o">=</span><span class="s2">"none"</span> <span class="o">)</span> + <span class="k">fi</span> + <span class="o">}</span> + + src_compile<span class="o">()</span> <span class="o">{</span> + escons build <span class="s2">"</span><span class="si">${</span><span class="nv">scons_vars</span><span class="p">[@]</span><span class="si">}</span><span class="s2">"</span> <span class="s2">"</span><span class="si">${</span><span class="nv">scons_targets</span><span class="p">[@]</span><span class="si">}</span><span class="s2">"</span> <span class="nv">prefix</span><span class="o">=</span><span class="s2">"/usr"</span> + <span class="o">}</span> + + src_test<span class="o">()</span> <span class="o">{</span> + escons <span class="nb">test</span> + <span class="o">}</span> + + src_install<span class="o">()</span> <span class="o">{</span> + escons install <span class="nv">stage_dir</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">D</span><span class="si">}</span><span class="s2">"</span> <span class="nv">libdirname</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>get_libdir<span class="k">)</span><span class="s2">"</span> + python_optimize + <span class="o">}</span> +</pre></div> +</div> +</section> +<section id="pure-python-multi-impl-package"> +<h3>Pure Python multi-impl package<a class="headerlink" href="#pure-python-multi-impl-package" title="Permalink to this headline">¶</a></h3> +<p>When you are dealing with a pure Python package using SCons, it makes +sense to use plain <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> API. This means that SCons is going +to be called from a <code class="docutils literal notranslate"><span class="pre">python_foreach_impl</span></code> loop only.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + +<span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 <span class="o">)</span> +</span><span class="hll"> inherit fortran-2 python-r1 scons-utils toolchain-funcs +</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Automated pipeline for performing Poisson-Boltzmann electrostatics calculations"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://www.poissonboltzmann.org/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/Electrostatics/apbs-</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/releases/download/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">-src-</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"amd64 x86 ~amd64-linux ~x86-linux"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"opal"</span> +<span class="hll"> <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> +</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> || (</span> +<span class="s2"> dev-python/numpy-python2[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> dev-python/numpy[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> )</span> +<span class="s2"> sci-chemistry/openbabel-python[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> opal? ( dev-python/zsi[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">] )</span> +<span class="s2"> "</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> dev-lang/swig:0</span> +<span class="hll"><span class="s2"> dev-util/scons[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span> + src_prepare<span class="o">()</span> <span class="o">{</span> + find -type f <span class="se">\(</span> -name <span class="s2">"*.pyc"</span> -o -name <span class="s2">"*.pyo"</span> <span class="se">\)</span> -delete <span class="o">||</span> die + + eapply <span class="s2">"</span><span class="si">${</span><span class="nv">PATCHES</span><span class="p">[@]</span><span class="si">}</span><span class="s2">"</span> + eapply_user + rm -rf scons <span class="o">||</span> die + + python_copy_sources + <span class="o">}</span> + + python_configure<span class="o">()</span> <span class="o">{</span> + tc-export CXX + cat > <span class="s2">"</span><span class="si">${</span><span class="nv">BUILD_DIR</span><span class="si">}</span><span class="s2">"</span>/build_config.py <span class="s"><<-EOF || die</span> +<span class="s"> PREFIX="${D}/$(python_get_sitedir)/${PN}"</span> +<span class="s"> APBS="${EPREFIX}/usr/bin/apbs"</span> +<span class="s"> MAX_ATOMS=10000</span> +<span class="s"> BUILD_PDB2PKA=False</span> +<span class="s"> REBUILD_SWIG=True</span> +<span class="s"> EOF</span> + <span class="o">}</span> + + src_configure<span class="o">()</span> <span class="o">{</span> + python_foreach_impl python_configure + <span class="o">}</span> + + src_compile<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl run_in_build_dir escons +</span> <span class="o">}</span> + + python_install<span class="o">()</span> <span class="o">{</span> + <span class="nb">cd</span> <span class="s2">"</span><span class="si">${</span><span class="nv">BUILD_DIR</span><span class="si">}</span><span class="s2">"</span> <span class="o">||</span> die +<span class="hll"> escons install +</span> python_optimize + <span class="o">}</span> + + src_install<span class="o">()</span> <span class="o">{</span> + python_foreach_impl python_install + <span class="o">}</span> +</pre></div> +</div> +</section> +<section id="hybrid-python-r1-scons-package"> +<h3>Hybrid python-r1 + SCons package<a class="headerlink" href="#hybrid-python-r1-scons-package" title="Permalink to this headline">¶</a></h3> +<p>Finally, let’s consider a package that uses SCons as a build system +and installs Python components independently of it. This could be +e.g. a C/C++ program with separate Python bindings.</p> +<p>Let’s presume that the Python bindings need to be installed manually, +and they support a wider target range than the build system. In this +case, the any-r1 API is recommended.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_6 <span class="o">)</span> + inherit python-r1 scons-utils toolchain-funcs + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"GPS daemon and library for USB/serial GPS devices and GPS/mapping clients"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://gpsd.gitlab.io/gpsd/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://nongnu/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0/24"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm ~ppc ~ppc64 ~sparc ~x86"</span> + + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"python"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"> )"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=net-misc/pps-tools-0.0.20120407</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'>=dev-util/scons-2.3.0[${PYTHON_USEDEP}]'</span> -2<span class="k">)</span><span class="s2"></span> +</span><span class="s2"> virtual/pkgconfig"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> has_version <span class="s2">">=dev-util/scons-2.3.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nv">myesconsargs</span><span class="o">=(</span> + <span class="nv">prefix</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">EPREFIX</span><span class="si">}</span><span class="s2">/usr"</span> + <span class="nv">libdir</span><span class="o">=</span><span class="s2">"\$prefix/</span><span class="k">$(</span>get_libdir<span class="k">)</span><span class="s2">"</span> + <span class="nv">udevdir</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>get_udevdir<span class="k">)</span><span class="s2">"</span> + <span class="nv">chrpath</span><span class="o">=</span>False + <span class="nv">gpsd_user</span><span class="o">=</span>gpsd + <span class="nv">gpsd_group</span><span class="o">=</span>uucp + <span class="nv">nostrip</span><span class="o">=</span>True + <span class="nv">manbuild</span><span class="o">=</span>False + <span class="k">$(</span>use_scons python<span class="k">)</span> + <span class="o">)</span> + + <span class="c1"># SConstruct uses py2 constructs</span> +<span class="hll"> python_setup -2 +</span> <span class="o">}</span> + + src_compile<span class="o">()</span> <span class="o">{</span> + <span class="nb">export</span> <span class="nv">CHRPATH</span><span class="o">=</span> + tc-export CC CXX PKG_CONFIG + <span class="nb">export</span> <span class="nv">SHLINKFLAGS</span><span class="o">=</span><span class="si">${</span><span class="nv">LDFLAGS</span><span class="si">}</span> <span class="nv">LINKFLAGS</span><span class="o">=</span><span class="si">${</span><span class="nv">LDFLAGS</span><span class="si">}</span> + escons + <span class="o">}</span> + + src_install<span class="o">()</span> <span class="o">{</span> + <span class="nv">DESTDIR</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">D</span><span class="si">}</span><span class="s2">"</span> escons install + use python <span class="o">&&</span> python_foreach_impl python_domodule gps + <span class="o">}</span> +</pre></div> +</div> +</section> +</section> +<section id="waf"> +<h2>waf<a class="headerlink" href="#waf" title="Permalink to this headline">¶</a></h2> +<p>The <a class="reference external" href="https://waf.io/">waf</a> build system is written in Python and bundled with the packages +using it. Therefore, it is necessary to combine <code class="docutils literal notranslate"><span class="pre">waf-utils</span></code> eclass +with one of the Python eclasses.</p> +<p>Since SCons does not have any dependencies beside the Python +interpreter, the integration is generally simple. You consider waf +like any other build-time script, and use the eclass implied by other +Python components in package.</p> +<p>Furthermore, since waf requires threading support in the Python +interpreter, it is necessary to add <code class="docutils literal notranslate"><span class="pre">PYTHON_REQ_USE='threads(+)'</span></code> in +all waf packages (combined with individual package requirements if +applicable).</p> +<section id="build-time-use"> +<h3>Build-time use<a class="headerlink" href="#build-time-use" title="Permalink to this headline">¶</a></h3> +<p>If waf is the only build-time Python script in the package, it is only +necessary to add <code class="docutils literal notranslate"><span class="pre">PYTHON_REQ_USE</span></code> and <code class="docutils literal notranslate"><span class="pre">${PYTHON_DEPS}</span></code> to build-time +dependencies. If the package had other Python dependencies, you would +specify them instead.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + +<span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 <span class="o">)</span> +</span><span class="hll"> <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s1">'threads(+)'</span> +</span> <span class="nv">NO_WAF_LIBDIR</span><span class="o">=</span>yes + +<span class="hll"> inherit python-any-r1 waf-utils +</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"C++ Template Unit Test Framework"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"http://mrzechonek.github.io/tut-framework/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/mrzechonek/tut-framework/archive/</span><span class="si">${</span><span class="nv">PV</span><span class="p">//./-</span><span class="si">}</span><span class="s2">.tar.gz -> </span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + <span class="nv">S</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">WORKDIR</span><span class="si">}</span><span class="s2">/tut-framework-</span><span class="si">${</span><span class="nv">PV</span><span class="p">//./-</span><span class="si">}</span><span class="s2">"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD-2"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">""</span> + +<span class="hll"> <span class="nv">BDEPEND</span><span class="o">=</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span> +</span></pre></div> +</div> +</section> +<section id="id1"> +<h3>Single-impl package<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3> +<p>The rules for integrating simple-impl package are roughly the same +as for pure <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> use. Again, waf requires only plain +build-time <code class="docutils literal notranslate"><span class="pre">${PYTHON_DEPS}</span></code> and <code class="docutils literal notranslate"><span class="pre">PYTHON_REQ_USE</span></code>.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> +<span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 <span class="o">)</span> +</span><span class="hll"> <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"threads"</span> +</span> +<span class="hll"> inherit python-single-r1 waf-utils +</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"An LDAP-like embedded database"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://ldb.samba.org/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://www.samba.org/ftp/pub/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"LGPL-3"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0/</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 arm ~arm64 ~hppa ia64 ~mips ppc ppc64 ~s390 ~sh sparc x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"+ldap python"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"python? ( </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"> )"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"!elibc_FreeBSD? ( dev-libs/libbsd )</span> +<span class="s2"> dev-libs/popt</span> +<span class="s2"> >=sys-libs/talloc-2.1.8[python?]</span> +<span class="s2"> >=sys-libs/tevent-0.9.31[python(+)?]</span> +<span class="s2"> >=sys-libs/tdb-1.3.12[python?]</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )</span> +<span class="s2"> ldap? ( net-nds/openldap )</span> +<span class="s2"> "</span> + + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"dev-libs/libxslt</span> +<span class="s2"> virtual/pkgconfig</span> +<span class="hll"><span class="s2"> </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +</span><span class="s2"> </span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2">"</span> + + <span class="nv">WAF_BINARY</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span><span class="s2">/buildtools/bin/waf"</span> + + <span class="nv">PATCHES</span><span class="o">=(</span> + <span class="s2">"</span><span class="si">${</span><span class="nv">FILESDIR</span><span class="si">}</span><span class="s2">"</span>/<span class="si">${</span><span class="nv">PN</span><span class="si">}</span>-1.1.27-optional_packages.patch + <span class="s2">"</span><span class="si">${</span><span class="nv">FILESDIR</span><span class="si">}</span><span class="s2">"</span>/<span class="si">${</span><span class="nv">P</span><span class="si">}</span>-disable-python.patch + <span class="o">)</span> + + pkg_setup<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python-single-r1_pkg_setup +</span> <span class="o">}</span> + + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nb">local</span> <span class="nv">myconf</span><span class="o">=(</span> + <span class="k">$(</span>usex ldap <span class="s1">''</span> --disable-ldap<span class="k">)</span> + <span class="k">$(</span>usex python <span class="s1">''</span> <span class="s1">'--disable-python'</span><span class="k">)</span> + --disable-rpath + --disable-rpath-install --bundled-libraries<span class="o">=</span>NONE + --with-modulesdir<span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">EPREFIX</span><span class="si">}</span><span class="s2">"</span>/usr/<span class="k">$(</span>get_libdir<span class="k">)</span>/samba + --builtin-libraries<span class="o">=</span>NONE + <span class="o">)</span> + waf-utils_src_configure <span class="s2">"</span><span class="si">${</span><span class="nv">myconf</span><span class="p">[@]</span><span class="si">}</span><span class="s2">"</span> + <span class="o">}</span> +</pre></div> +</div> +</section> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Integration with build systems written in Python</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#meson">Meson</a></li> +<li class="toctree-l2"><a class="reference internal" href="#scons">SCons</a></li> +<li class="toctree-l2"><a class="reference internal" href="#waf">waf</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="expert-multi.html" title="previous chapter">Expert python-r1 usage</a></li> + <li>Next: <a href="porting.html" title="next chapter">Porting tips</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/buildsys.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/concept.html b/guide/concept.html new file mode 100644 index 0000000..7b10bca --- /dev/null +++ b/guide/concept.html @@ -0,0 +1,312 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Advanced concepts — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Expert python-r1 usage" href="expert-multi.html" /> + <link rel="prev" title="pytest recipes" href="pytest.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="advanced-concepts"> +<h1>Advanced concepts<a class="headerlink" href="#advanced-concepts" title="Permalink to this headline">¶</a></h1> +<section id="namespace-packages"> +<h2>Namespace packages<a class="headerlink" href="#namespace-packages" title="Permalink to this headline">¶</a></h2> +<section id="hierarchical-package-structure"> +<h3>Hierarchical package structure<a class="headerlink" href="#hierarchical-package-structure" title="Permalink to this headline">¶</a></h3> +<p>Traditionally, Python packages were organized into a hierarchical +structure with modules and subpackages being located inside the parent +package directory. When submodules are imported, they are represented +as attributes on the parent module. Consider the following session:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">sphinx.addnodes</span> +<span class="gp">>>> </span><span class="n">sphinx</span> +<span class="go"><module 'sphinx' from '/usr/lib/python3.8/site-packages/sphinx/__init__.py'></span> +<span class="gp">>>> </span><span class="n">sphinx</span><span class="o">.</span><span class="n">addnodes</span> +<span class="go"><module 'sphinx.addnodes' from '/usr/lib/python3.8/site-packages/sphinx/addnodes.py'></span> +</pre></div> +</div> +<p>This works fine most of the time. However, it start being problematic +when multiple Gentoo packages install parts of the same top-level +package. This may happen e.g. with some plugin layouts where plugins +are installed inside the package. More commonly, it happens when +upstream wishes all their packages to start with a common component.</p> +<p>This is the case with Zope framework. Different Zope packages share +common <code class="docutils literal notranslate"><span class="pre">zope</span></code> top-level package. <code class="docutils literal notranslate"><span class="pre">dev-python/zope-interface</span></code> +installs into <code class="docutils literal notranslate"><span class="pre">zope.interface</span></code>, <code class="docutils literal notranslate"><span class="pre">dev-python/zope-event</span></code> +into <code class="docutils literal notranslate"><span class="pre">zope.event</span></code>. For this to work using the hierarchical layout, +a common package has to install <code class="docutils literal notranslate"><span class="pre">zope/__init__.py</span></code>, then other Zope +packages have to depend on it and install sub-packages inside that +directory. As far as installed packages are concerned, this is entirely +doable.</p> +<p>The real problem happens when we wish to test a freshly built package +that depends on an installed package. In that case, Python imports +<code class="docutils literal notranslate"><span class="pre">zope</span></code> from build directory that contains only <code class="docutils literal notranslate"><span class="pre">zope.interface</span></code>. +It will not be able to import <code class="docutils literal notranslate"><span class="pre">zope.event</span></code> that is installed in system +package directory:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">zope.interface</span> +<span class="gp">>>> </span><span class="n">zope</span> +<span class="go"><module 'zope' from '/tmp/portage/dev-python/zope-interface-4.7.1/work/zope.interface-4.7.1-python3_8/lib/zope/__init__.py'></span> +<span class="gp">>>> </span><span class="n">zope</span><span class="o">.</span><span class="n">interface</span> +<span class="go"><module 'zope.interface' from '/tmp/portage/dev-python/zope-interface-4.7.1/work/zope.interface-4.7.1-python3_8/lib/zope/interface/__init__.py'></span> +<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">zope.event</span> +<span class="gt">Traceback (most recent call last):</span> + File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span> +<span class="gr">ModuleNotFoundError</span>: <span class="n">No module named 'zope.event'</span> +</pre></div> +</div> +<p>Now, this could be worked around by copying all other subpackages back +to the build directory. However, there is a better solution.</p> +</section> +<section id="namespace-package-structure"> +<h3>Namespace package structure<a class="headerlink" href="#namespace-package-structure" title="Permalink to this headline">¶</a></h3> +<p>Unlike traditional packages, namespace packages act as a kind of proxy. +They are not strictly bound to the containing directory, and instead +permit loading subpackages from all directories found in module search +path. If we make <code class="docutils literal notranslate"><span class="pre">zope</span></code> a namespace package, we can import both +the locally built <code class="docutils literal notranslate"><span class="pre">zope.interface</span></code> and system <code class="docutils literal notranslate"><span class="pre">zope.event</span></code> +packages:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">zope.interface</span> +<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">zope.event</span> +<span class="gp">>>> </span><span class="n">zope</span> +<span class="go"><module 'zope' (namespace)></span> +<span class="gp">>>> </span><span class="n">zope</span><span class="o">.</span><span class="n">interface</span> +<span class="go"><module 'zope.interface' from '/tmp/portage/dev-python/zope-interface-4.7.1/work/zope.interface-4.7.1-python3_8/lib/zope/interface/__init__.py'></span> +<span class="gp">>>> </span><span class="n">zope</span><span class="o">.</span><span class="n">event</span> +<span class="go"><module 'zope.event' from '/usr/lib/python3.8/site-packages/zope/event/__init__.py'></span> +</pre></div> +</div> +<p>There are three common methods of creating namespace packages:</p> +<ol class="arabic simple"> +<li><p><a class="reference external" href="https://www.python.org/dev/peps/pep-0420/">PEP-0420</a> namespaces implemented in Python 3.3 and newer,</p></li> +<li><p>Using <a class="reference external" href="https://docs.python.org/3/library/pkgutil.html">pkgutil</a> standard library module,</p></li> +<li><p>Using <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#namespace-packages">namespace package support in setuptools</a> (discouraged).</p></li> +</ol> +<p>PEP-0420 namespaces are created implicitly when a package directory +does not contain <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file. While earlier versions +of Python (including Python 2.7) ignored such directories and did not +permit importing Python modules within them, Python 3.3 imports such +directories as namespace packages.</p> +<p>pkgutil namespaces use <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> with the following content:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">__path__</span> <span class="o">=</span> <span class="nb">__import__</span><span class="p">(</span><span class="s1">'pkgutil'</span><span class="p">)</span><span class="o">.</span><span class="n">extend_path</span><span class="p">(</span><span class="n">__path__</span><span class="p">,</span> <span class="vm">__name__</span><span class="p">)</span> +</pre></div> +</div> +<p>setuptools namespace can use <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> with the following +content:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nb">__import__</span><span class="p">(</span><span class="s1">'pkg_resources'</span><span class="p">)</span><span class="o">.</span><span class="n">declare_namespace</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span> +</pre></div> +</div> +<p>Alternatively, setuptools normally installs a <code class="docutils literal notranslate"><span class="pre">.pth</span></code> file that is +automatically loaded by Python and implicitly injects the namespace +into Python.</p> +<p>Both pkgutil and setuptools namespaces are portable to all versions +of Python.</p> +<p>PEP-0420 and pkgutil namespaces are considered mutually compatible, +while setuptools namespaces are considered incompatible with them. +It is recommended not to mix different methods within a single +namespace.</p> +<p>More general information on the topic can be found under <a class="reference external" href="https://packaging.python.org/guides/packaging-namespace-packages/">packaging +namespace packages</a> in Python Packaging User Guide.</p> +</section> +<section id="namespace-packages-in-python-3"> +<h3>Namespace packages in Python 3<a class="headerlink" href="#namespace-packages-in-python-3" title="Permalink to this headline">¶</a></h3> +<p>Since all supported Python versions in Gentoo support PEP-0420 +namespaces, the other two methods are technically unnecessary. However, +the incompatibility between pkg_resources namespaces and the other two +methods makes removing them non-trivial.</p> +<p>If all packages within the namespace are using only pkgutil-style +namespaces, you can safely remove the dependencies on the package +providing the namespace and the package itself. Even partial removal +should not cause any issues. However, if the package was explicitly +provided upstream, note that some packages may carry an explicit +dependency on it and that dependency would need to be removed or made +conditional to Python < 3.3. You will also need to strip colliding +<code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files.</p> +<p>If setuptools-style namespace are used, the namespace packages need +to remain as-is for the time being, as otherwise tests relying +on the namespaced packages are going to be broken. We have not yet +conceived a way forward for them.</p> +</section> +<section id="packaging-pkgutil-style-namespaces-in-gentoo"> +<h3>Packaging pkgutil-style namespaces in Gentoo<a class="headerlink" href="#packaging-pkgutil-style-namespaces-in-gentoo" title="Permalink to this headline">¶</a></h3> +<p>Normally all packages using the same pkgutil-style namespace install +its <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file causing package collisions. As having this +file is no longer necessary for Python 3.3 and newer, the recommended +solution is to strip it before installing the package. The presence +of this file is harmless during build and testing.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_install<span class="o">()</span> <span class="o">{</span> + rm <span class="s2">"</span><span class="si">${</span><span class="nv">BUILD_DIR</span><span class="si">}</span><span class="s2">"</span>/lib/jaraco/__init__.py <span class="o">||</span> die + distutils-r1_python_install +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="packaging-setuptools-style-namespaces-in-gentoo"> +<h3>Packaging setuptools-style namespaces in Gentoo<a class="headerlink" href="#packaging-setuptools-style-namespaces-in-gentoo" title="Permalink to this headline">¶</a></h3> +<p>Similar approach is used for setuptools-style namespace packages. +The only differences are in <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> code and removal method.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">dev-python/namespace-<name></span></code> package for setuptools-style +namespace should use the following code:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> pypy3 python<span class="o">{</span>2_7,3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}}</span> <span class="o">)</span> + inherit python-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Namespace package declaration for zope"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://wiki.gentoo.org/wiki/Project:Python/Namespace_packages"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">""</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"public-domain"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 arm arm64 hppa ia64 ~m68k ~mips ppc ppc64 s390 ~sh sparc x86 ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos ~sparc-solaris ~sparc64-solaris ~x64-solaris ~x86-solaris"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">""</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"dev-python/setuptools[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2">"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2">"</span> + + src_unpack<span class="o">()</span> <span class="o">{</span> +<span class="hll"> mkdir -p <span class="s2">"</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span><span class="s2">"</span>/zope <span class="o">||</span> die +</span><span class="hll"> cat > <span class="s2">"</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span><span class="s2">"</span>/zope/__init__.py <span class="s"><<-EOF || die</span> +</span><span class="hll"><span class="s"> __import__('pkg_resources').declare_namespace(__name__)</span> +</span><span class="hll"><span class="s"> EOF</span> +</span> <span class="o">}</span> + + src_install<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl python_domodule zope +</span> <span class="o">}</span> +</pre></div> +</div> +<p>Setuptools normally do not install <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> files but <code class="docutils literal notranslate"><span class="pre">*.pth</span></code> +files that do not collide. It is therefore easy to miss them but they +can cause quite a mayhem. Therefore, remember to strip them:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_install_all<span class="o">()</span> <span class="o">{</span> + distutils-r1_python_install_all + find <span class="s2">"</span><span class="si">${</span><span class="nv">D</span><span class="si">}</span><span class="s2">"</span> -name <span class="s1">'*.pth'</span> -delete <span class="o">||</span> die +<span class="o">}</span> +</pre></div> +</div> +</section> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Advanced concepts</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#namespace-packages">Namespace packages</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="pytest.html" title="previous chapter">pytest recipes</a></li> + <li>Next: <a href="expert-multi.html" title="next chapter">Expert python-r1 usage</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/concept.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/depend.html b/guide/depend.html new file mode 100644 index 0000000..428f2ec --- /dev/null +++ b/guide/depend.html @@ -0,0 +1,286 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Advanced dependencies — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Resolving test suite problems" href="test.html" /> + <link rel="prev" title="Common helper functions" href="helper.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="advanced-dependencies"> +<h1>Advanced dependencies<a class="headerlink" href="#advanced-dependencies" title="Permalink to this headline">¶</a></h1> +<span class="target" id="index-0"></span><section id="requesting-use-flags-on-the-python-interpreter"> +<span id="index-1"></span><h2>Requesting USE flags on the Python interpreter<a class="headerlink" href="#requesting-use-flags-on-the-python-interpreter" title="Permalink to this headline">¶</a></h2> +<p>While the majority of Python standard library modules are available +unconditionally, a few are controlled by USE flags. For example, +the <a class="reference external" href="https://docs.python.org/3.8/library/sqlite3.html">sqlite3</a> module requires <code class="docutils literal notranslate"><span class="pre">sqlite</span></code> flag to be enabled +on the interpreter. If a package requires this module, it needs +to enforce the matching flag via a USE dependency.</p> +<p>In order to create a USE dependency on the Python interpreter, set +<code class="docutils literal notranslate"><span class="pre">PYTHON_REQ_USE</span></code> before inheriting the eclass. This will cause +the eclass to generate appropriate dependency string in <code class="docutils literal notranslate"><span class="pre">PYTHON_DEPS</span></code>.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_6 <span class="o">)</span> +<span class="hll"> <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"sqlite"</span> +</span> inherit python-r1 gnome2-utils meson xdg-utils + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Modern music player for GNOME"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://wiki.gnome.org/Apps/Lollypop"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://adishatz.org/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.xz"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-3"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span> + + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> ..."</span> +</pre></div> +</div> +<p>Full USE dependency syntax is permitted. For example, you can make +the dependency conditional to a flag on the package:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_6 <span class="o">)</span> +<span class="hll"> <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"sqlite?"</span> +</span> inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"A lightweight password-manager with multiple database backends"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://pwman3.github.io/pwman3/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/pwman3/pwman3/archive/v</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">.tar.gz -> </span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-3"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64"</span> +<span class="hll"> <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"mongodb mysql postgres +sqlite"</span> +</span></pre></div> +</div> +<p>Finally, there are cases when the problem cannot be fully solved using +a single USE dependency. Additional Python interpreter dependencies +with specific USE flags can be constructed using <code class="docutils literal notranslate"><span class="pre">python_gen_impl_dep</span></code> +helper then. For example, the following ebuild requires Python with +SQLite support when running tests:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python<span class="o">{</span>2_7,3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}}</span> pypy3 <span class="o">)</span> + + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Let your Python tests travel through time"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/spulec/freezegun"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"Apache-2.0"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~x86 ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >dev-python/python-dateutil-2.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> dev-python/six[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> "</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> dev-python/setuptools[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> test? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_impl_dep sqlite<span class="k">)</span><span class="s2"></span> +</span><span class="s2"> dev-python/mock[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> dev-python/nose[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> )</span> +<span class="s2"> "</span> + + distutils_enable_tests pytest +</pre></div> +</div> +</section> +<section id="dependencies-conditional-to-python-version"> +<span id="index-2"></span><h2>Dependencies conditional to Python version<a class="headerlink" href="#dependencies-conditional-to-python-version" title="Permalink to this headline">¶</a></h2> +<p>When packaging software for multiple Python versions, it is quite likely +that you’ll find yourself needing some packages only with some +of the versions, and not with others. This is the case with backports +and other compatibility packages. It also happens if some +of the optional dependencies do not support the full set +of implementations your package supports.</p> +<p>A dependency that applies only to a subset of <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code> can +be created using <code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> function (the same as used +in <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>). In addition to the dependency template, +it accepts an optional list of applicable implementations as arguments.</p> +<p>For example, <code class="docutils literal notranslate"><span class="pre">dev-python/importlib_metadata</span></code> package is a backport +from Python 3.8. Therefore, the majority of its consumers require +it only with older versions of Python:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +<span class="s1"> dev-python/importlib_metadata[${PYTHON_USEDEP}]</span> +<span class="s1"> '</span> pypy3 python3_<span class="o">{</span><span class="m">6</span>,7<span class="o">}</span><span class="k">)</span><span class="s2"></span> +<span class="s2">"</span> +</pre></div> +</div> +<p>Please note that the first argument is a template containing literal +(escaped through use of single quotes) <code class="docutils literal notranslate"><span class="pre">${PYTHON_USEDEP}</span></code> that will +be substituted with partial USE dependency by the eclass function +(<code class="docutils literal notranslate"><span class="pre">${PYTHON_SINGLE_USEDEP}</span></code> is also permitted when using +<code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>). It is followed by a list of implementations that +are <em>not</em> quoted. The example is using bash brace expansion to express +<code class="docutils literal notranslate"><span class="pre">python3_6</span> <span class="pre">python3_7</span></code> shorter.</p> +<p>Since <code class="docutils literal notranslate"><span class="pre">pypy3</span></code> can refer to any version of PyPy3, the dependency will +eventually become outdated as PyPy3 upgrades to Python 3.8 +compatibility. This is a known limitation of the eclasses and currently +no solution is provided for it, besides updating dependencies once old +version of PyPy3 is removed.</p> +<p>An important feature of <code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> is that it handles +removal of old implementations gracefully. When one of the listed +implementations is no longer supported, it silently ignores it. This +makes it possible to remove old implementations without having to update +all dependency strings immediately.</p> +<p>For example, in the example below the dependency became empty when +Python 3.7 was removed.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +<span class="s1"> dev-python/importlib_metadata[${PYTHON_USEDEP}]</span> +<span class="s1"> '</span> python3_7<span class="k">)</span><span class="s2">"</span> +</pre></div> +</div> +</section> +<section id="dependencies-on-cffi-and-greenlet"> +<span id="index-3"></span><h2>Dependencies on CFFI and greenlet<a class="headerlink" href="#dependencies-on-cffi-and-greenlet" title="Permalink to this headline">¶</a></h2> +<p>The PyPy distribution includes special versions of the <a class="reference external" href="https://pypi.org/project/cffi/">cffi</a> +and <a class="reference external" href="https://pypi.org/project/greenlet/">greenlet</a> packages. For this reason, packages using CFFI +and/or greenlet and supporting PyPy3 need to make the explicit +dependencies conditional to CPython:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +<span class="s1"> >=dev-python/cffi-1.1.0:=[${PYTHON_USEDEP}]</span> +<span class="s1"> '</span> <span class="s1">'python*'</span><span class="k">)</span><span class="s2"></span> +<span class="s2">"</span> +</pre></div> +</div> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Advanced dependencies</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#requesting-use-flags-on-the-python-interpreter">Requesting USE flags on the Python interpreter</a></li> +<li class="toctree-l2"><a class="reference internal" href="#dependencies-conditional-to-python-version">Dependencies conditional to Python version</a></li> +<li class="toctree-l2"><a class="reference internal" href="#dependencies-on-cffi-and-greenlet">Dependencies on CFFI and greenlet</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="helper.html" title="previous chapter">Common helper functions</a></li> + <li>Next: <a href="test.html" title="next chapter">Resolving test suite problems</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/depend.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/distutils-legacy.html b/guide/distutils-legacy.html new file mode 100644 index 0000000..1f316c1 --- /dev/null +++ b/guide/distutils-legacy.html @@ -0,0 +1,422 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>distutils-r1 legacy concepts — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Common helper functions" href="helper.html" /> + <link rel="prev" title="distutils-r1 — standard Python build systems" href="distutils.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="distutils-r1-legacy-concepts"> +<h1>distutils-r1 legacy concepts<a class="headerlink" href="#distutils-r1-legacy-concepts" title="Permalink to this headline">¶</a></h1> +<p>This section describes concepts specific to the legacy mode +of the <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> eclass. When using the modern PEP 517 mode, +none of the features described here are available.</p> +<section id="different-build-system-variations"> +<span id="index-0"></span><h2>Different build system variations<a class="headerlink" href="#different-build-system-variations" title="Permalink to this headline">¶</a></h2> +<p>The commonly used build systems specific to Python packages can be +classified for eclass support into following groups:</p> +<ol class="arabic simple"> +<li><p>Plain distutils (built-in in Python).</p></li> +<li><p>Setuptools and its direct derivatives (e.g. pbr).</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>-based build systems (Flit, Poetry).</p></li> +</ol> +<p>The eclass supports the first two directly. Support for Flit and Poetry +is provided through the <code class="docutils literal notranslate"><span class="pre">dev-python/pyproject2setuppy</span></code> package that +converts the package’s metadata to setuptools call.</p> +<p>In addition to being a build system, setuptools provides runtime +facilities via the <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> module. If these facilities +are used, the package needs to have a runtime dependency +on <code class="docutils literal notranslate"><span class="pre">dev-python/setuptools</span></code>. Otherwise, a build-time dependency +is sufficient.</p> +<section id="distutils-use-setuptools"> +<h3>DISTUTILS_USE_SETUPTOOLS<a class="headerlink" href="#distutils-use-setuptools" title="Permalink to this headline">¶</a></h3> +<p>The most common case right now is a package using setuptools as a build +system, and therefore needing a build-time dependency only. This +is the eclass’ default. If your package does not fit this profile, +you can set <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_SETUPTOOLS</span></code> variable to one +of the supported values:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">no</span></code> — pure distutils use (no extra dependencies).</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">bdepend</span></code> — build-time use of setuptools (<code class="docutils literal notranslate"><span class="pre">BDEPEND</span></code> +on <code class="docutils literal notranslate"><span class="pre">dev-python/setuptools</span></code>).</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">rdepend</span></code> — build- and runtime use of setuptools (<code class="docutils literal notranslate"><span class="pre">BDEPEND</span></code> +and <code class="docutils literal notranslate"><span class="pre">RDEPEND</span></code> on <code class="docutils literal notranslate"><span class="pre">dev-python/setuptools</span></code>).</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> — use of Flit or Poetry (<code class="docutils literal notranslate"><span class="pre">BDEPEND</span></code> +on <code class="docutils literal notranslate"><span class="pre">dev-python/pyproject2toml</span></code> and <code class="docutils literal notranslate"><span class="pre">dev-python/setuptools</span></code>).</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">manual</span></code> — special value indicating that the eclass logic misbehaves +and the dependency needs to be specified manually. Strongly +discouraged, please report a bug and/or fix the package instead.</p></li> +</ul> +<p>The cases for particular values are explained in subsequent sections.</p> +<p>The Gentoo repository includes a post-install QA check that verifies +whether the value of <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_SETUPTOOLS</span></code> is correct, +and reports if it is most likely incorrect. This is why it is important +to use the variable rather than specifying the dependency directly. +An example report is:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>* DISTUTILS_USE_SETUPTOOLS value is probably incorrect +* have: <span class="nv">DISTUTILS_USE_SETUPTOOLS</span><span class="o">=</span>bdepend <span class="o">(</span>or <span class="nb">unset</span><span class="o">)</span> +* expected: <span class="nv">DISTUTILS_USE_SETUPTOOLS</span><span class="o">=</span>rdepend +</pre></div> +</div> +<p>The value needs to be set before inheriting the eclass:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> pypy3 <span class="o">)</span> +<span class="hll"> <span class="nv">DISTUTILS_USE_SETUPTOOLS</span><span class="o">=</span>rdepend +</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"A configurable sidebar-enabled Sphinx theme"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/bitprophet/alabaster"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~x86 ~x64-solaris"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> +</pre></div> +</div> +</section> +<section id="distutils-and-setuptools-build-systems"> +<h3>distutils and setuptools build systems<a class="headerlink" href="#distutils-and-setuptools-build-systems" title="Permalink to this headline">¶</a></h3> +<p>Distutils and setuptools are the two most common build systems +for Python packages right now. Their common feature is that they use +a <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> script that interfaces with the build system. Generally, +you can determine which of the two build systems are being used +by looking at the imports in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>, in particular from which +module the <code class="docutils literal notranslate"><span class="pre">setup</span></code> function is imported.</p> +<p>Distutils-based packages (<code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_SETUPTOOLS=no</span></code>) use e.g.:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils</span> <span class="kn">import</span> <span class="n">setup</span> +</pre></div> +</div> +<p>Setuptools-based package (<code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_SETUPTOOLS=bdepend</span></code>, unset +or possibly <code class="docutils literal notranslate"><span class="pre">rdepend</span></code> as indicated by the subsequent sections) use:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="kn">import</span> <span class="n">setup</span> +</pre></div> +</div> +<p>In some cases, upstreams find it convenient to alternatively support +both setuptools and distutils. A commonly used snippet is:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span> + <span class="kn">from</span> <span class="nn">setuptools</span> <span class="kn">import</span> <span class="n">setup</span> +<span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span> + <span class="kn">from</span> <span class="nn">distutils</span> <span class="kn">import</span> <span class="n">setup</span> +</pre></div> +</div> +<p>However, non-fixed build system choice can be problematic to Gentoo +users. This is because pure distutils installs egg-info data as a +single file, while setuptools install the same data as a directory +(using the same path). Therefore, if you rebuild the same version +of the package with a different build system than before, you end up +trying to replace a file with a directory or the other way around. +This is not permitted by the PMS and not handled cleanly by the package +managers.</p> +<p>You must always ensure that a single build system will be used +unconditionally. In the case of the condition presented above, it is +sufficient to leave <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_SETUPTOOLS</span></code> at its default value +as that will ensure that setuptools is installed and therefore +the fallback will never take place. However, patching <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> may +be necessary if you want to force distutils (e.g. to enable clean +bootstrap) or the upstream condition requiers that.</p> +</section> +<section id="setuptools-entry-points"> +<h3>Setuptools’ entry points<a class="headerlink" href="#setuptools-entry-points" title="Permalink to this headline">¶</a></h3> +<div class="admonition important"> +<p class="admonition-title">Important</p> +<p>With removal of Python 3.7, the correct <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_SETUPTOOLS</span></code> +value for packages using entry points changed to <code class="docutils literal notranslate"><span class="pre">bdepend</span></code>.</p> +</div> +<p><em>Entry points</em> provide the ability to expose some of the package’s +Python functions to other packages. They are commonly used to implement +plugin systems and by setuptools themselves to implement wrapper scripts +for starting programs.</p> +<p>Entry points are defined as <code class="docutils literal notranslate"><span class="pre">entry_points</span></code> argument to the <code class="docutils literal notranslate"><span class="pre">setup()</span></code> +function, or <code class="docutils literal notranslate"><span class="pre">entry_points</span></code> section in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>. They are +installed in the package’s egg-info as <code class="docutils literal notranslate"><span class="pre">entry_points.txt</span></code>. In both +cases, they are grouped by entry point type, and defined as a dictionary +mapping entry points names to the relevant functions.</p> +<p>For our purposes, we are only interested in entry points used to define +wrapper scripts, the <code class="docutils literal notranslate"><span class="pre">console_scripts</span></code> and <code class="docutils literal notranslate"><span class="pre">gui_scripts</span></code> groups, +as they are installed with the package itself. As for plugin systems, +it is reasonable to assume that the installed plugins are only +meaningful to the package using them, and therefore that the package +using them will depend on the appropriate metadata provider.</p> +<p>Old versions of setuptools used to implement the script wrappers using +<code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> package. Modern versions of setuptools use +the following logic:</p> +<ol class="arabic simple"> +<li><p>If <code class="docutils literal notranslate"><span class="pre">importlib.metadata</span></code> module is available (Python 3.8+), use it. +In this case, no external dependencies are necessary.</p></li> +<li><p>If <code class="docutils literal notranslate"><span class="pre">importlib_metadata</span></code> backport is available, use it. It is +provided by <code class="docutils literal notranslate"><span class="pre">dev-python/importlib_metadata</span></code>.</p></li> +<li><p>Otherwise, fall back to <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>. It is provided +by <code class="docutils literal notranslate"><span class="pre">dev-python/setuptools</span></code>.</p></li> +</ol> +<p>Since Python 3.7 is no longer present in Gentoo (we are not considering +PyPy3.7 correctness important for the time being), new ebuilds do not +need any additional dependencies for entry points and should use +the default value (i.e. remove <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_SETUPTOOLS</span></code>).</p> +<p>For the time being, the QA check for incorrect values is accepting +both the new value and the old <code class="docutils literal notranslate"><span class="pre">rdepend</span></code> value. If you wish to be +reminded about the update, you can add the following variable to your +<code class="docutils literal notranslate"><span class="pre">make.conf</span></code>:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">DISTUTILS_STRICT_ENTRY_POINTS</span><span class="o">=</span><span class="m">1</span> +</pre></div> +</div> +<p>Please note that in some cases <code class="docutils literal notranslate"><span class="pre">rdepend</span></code> can still be the correct +value, if there are <a class="reference internal" href="#other-runtime-uses-of-setuptools">other runtime uses of setuptools</a>. In some cases +the QA check will also trigger the wrong value because of leftover +explicit dependencies on setuptools.</p> +</section> +<section id="other-runtime-uses-of-setuptools"> +<h3>Other runtime uses of setuptools<a class="headerlink" href="#other-runtime-uses-of-setuptools" title="Permalink to this headline">¶</a></h3> +<p>Besides the generated wrapper scripts, the package code itself may use +the <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> or <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code> packages. The common cases +for this include getting package metadata and resource files. This +could also be a case for plugin managers and derived build systems.</p> +<p>As a rule of thumb, if any installed Python file imports <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> +or <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>, the package needs to use the value of <code class="docutils literal notranslate"><span class="pre">rdepend</span></code>.</p> +<p>The QA check determines that this is the case by looking at the upstream +dependencies (<code class="docutils literal notranslate"><span class="pre">install_requires</span></code>) installed by the package. It is +quite common for packages to miss the dependency, or have a leftover +dependency. If <code class="docutils literal notranslate"><span class="pre">install_requires</span></code> does not match actual imports +in the installed modules, please submit a patch upstream.</p> +</section> +<section id="pyproject-toml-based-projects"> +<h3>pyproject.toml-based projects<a class="headerlink" href="#pyproject-toml-based-projects" title="Permalink to this headline">¶</a></h3> +<p>The newer build systems used for Python packages avoid supplying +<code class="docutils literal notranslate"><span class="pre">setup.py</span></code> and instead declare package’s metadata and build system +information in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>. Examples of these build systems +are Flit and Poetry.</p> +<p>These build systems are generally very heavy and do not support plain +installation to a directory. For this reason, Gentoo is using +<code class="docutils literal notranslate"><span class="pre">dev-python/pyproject2setuppy</span></code> to provide a thin wrapper for +installing these packages using setuptools.</p> +<p>To enable the necessary eclass logic and add appropriate build-time +dependencies, specify the value of <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> +to <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_SETUPTOOLS</span></code>.</p> +<p>Strictly speaking, both Flit and Poetry do support entry points, +and therefore some packages actually need a runtime dependency +on setuptools. This is a known limitation, and it will probably +not be addressed for the same reason as the logic for setuptools’ entry +points is not updated.</p> +</section> +</section> +<section id="in-source-vs-out-of-source-builds"> +<span id="index-1"></span><h2>In-source vs out-of-source builds<a class="headerlink" href="#in-source-vs-out-of-source-builds" title="Permalink to this headline">¶</a></h2> +<p>In the general definition, an <em>out-of-source build</em> is a build where +output files are placed in a directory separate from source files. +By default, distutils and its derivatives always do out-of-source builds +and place output files in subdirectories of <code class="docutils literal notranslate"><span class="pre">build</span></code> directory.</p> +<p>Conversely, an <em>in-source build</em> happens when the output files are +interspersed with source files. The closest distutils equivalent +of an in-source build is the <code class="docutils literal notranslate"><span class="pre">--inplace</span></code> option of <code class="docutils literal notranslate"><span class="pre">build_ext</span></code> +that places compiled C extensions alongside Python module sources.</p> +<p><code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> shifts this concept a little. When performing +an out-of-source build (the default), it creates a dedicated output +directory for every Python interpreter enabled, and then uses it +throughout all build and install steps.</p> +<p>It should be noted that unlike build systems such as autotools or CMake, +out-of-source builds in distutils are not executed from the build +directory. Instead, the setup script is executed from source directory +and passed path to build directory.</p> +<p>Sometimes out-of-source builds are incompatible with custom hacks used +upstream. This could be a case if the setup script is writing +implementation-specific changes to the source files (e.g. using <code class="docutils literal notranslate"><span class="pre">2to3</span></code> +to convert them to Python 3) or relying on specific build paths. +For better compatibility with those cases, the eclass provides +an in-source build mode enabled via <code class="docutils literal notranslate"><span class="pre">DISTUTILS_IN_SOURCE_BUILD</span></code>.</p> +<p>In this mode, the eclass creates a separate copy of the source directory +for each Python implementation, and then runs the build and install +steps inside that copy. As a result, any changes done to the source +files are contained within the copy used for the current interpreter.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + <span class="nv">DISTUTILS_USE_SETUPTOOLS</span><span class="o">=</span>no + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> pypy3 <span class="o">)</span> + <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"xml(+)"</span> + + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Collection of extensions to Distutils"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/pypa/setuptools https://pypi.org/project/setuptools/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.zip"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"MIT"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~riscv ~s390 ~sh ~sparc ~x86 ~x64-cygwin ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos ~sparc-solaris ~sparc64-solaris ~x64-solaris ~x86-solaris"</span> + + <span class="c1"># Force in-source build because build system modifies sources.</span> +<span class="hll"> <span class="nv">DISTUTILS_IN_SOURCE_BUILD</span><span class="o">=</span><span class="m">1</span> +</span></pre></div> +</div> +</section> +<section id="installing-the-package-before-testing"> +<span id="index-2"></span><h2>Installing the package before testing<a class="headerlink" href="#installing-the-package-before-testing" title="Permalink to this headline">¶</a></h2> +<p>The tests are executed in <code class="docutils literal notranslate"><span class="pre">src_test</span></code> phase, after <code class="docutils literal notranslate"><span class="pre">src_compile</span></code> +installed package files into the build directory. The eclass +automatically adds appropriate <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> so that the installed +Python modules and extensions are used during testing. This works +for the majority of packages.</p> +<p>However, some test suites will not work correctly unless the package +has been properly installed via <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">install</span></code>. This may apply +specifically to packages calling their executables that are created +via entry points, various plugin systems or the use of package metadata.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">distutils_install_for_testing</span></code> function runs <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">install</span></code> +into a temporary directory, and adds the appropriate paths to <code class="docutils literal notranslate"><span class="pre">PATH</span></code> +and <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code>.</p> +<p>This function currently supports two install layouts:</p> +<ul class="simple"> +<li><p>the standard <em>root directory</em> layout that is enabled +via <code class="docutils literal notranslate"><span class="pre">--via-root</span></code>,</p></li> +<li><p>a virtualenv-alike <em>venv</em> layout that is enabled via <code class="docutils literal notranslate"><span class="pre">--via-venv</span></code>.</p></li> +</ul> +<p>The eclass defaults to the root directory layout that is consistent +with the layout used for the actual install. This ensures that +the package’s scripts are found on <code class="docutils literal notranslate"><span class="pre">PATH</span></code>, and the package metadata +is found via <code class="docutils literal notranslate"><span class="pre">importlib.metadata</span></code> / <code class="docutils literal notranslate"><span class="pre">pkg_resources</span></code>. It should +be sufficient to resolve the most common test problems.</p> +<p>In some cases, particularly packages that do not preserve <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> +correctly, the virtualenv-alike layout (<code class="docutils literal notranslate"><span class="pre">--via-venv</span></code>) is better. +Through wrapping the Python interpreter itself, it guarantees that +the packages installed in the test environment are found independently +of <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> (just like a true venv). It should cover the few +extreme cases.</p> +<p>In EAPIs prior to 8, an additional legacy <code class="docutils literal notranslate"><span class="pre">--via-home</span></code> layout used +to be supported. It historically used to be necessary to fix problems +with some packages. However, the underlying issues probably went away +along with old versions of Python, and the <a class="reference external" href="https://github.com/pypa/setuptools/commit/91213fb2e7eecde9f5d7582de485398f546e7aa8">removal of site.py hack</a> +has broken it for most of the consumers.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + distutils_install_for_testing + epytest --no-network +<span class="o">}</span> +</pre></div> +</div> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">distutils-r1 legacy concepts</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#different-build-system-variations">Different build system variations</a></li> +<li class="toctree-l2"><a class="reference internal" href="#in-source-vs-out-of-source-builds">In-source vs out-of-source builds</a></li> +<li class="toctree-l2"><a class="reference internal" href="#installing-the-package-before-testing">Installing the package before testing</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="distutils.html" title="previous chapter">distutils-r1 — standard Python build systems</a></li> + <li>Next: <a href="helper.html" title="next chapter">Common helper functions</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/distutils-legacy.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/distutils.html b/guide/distutils.html new file mode 100644 index 0000000..35bd9c8 --- /dev/null +++ b/guide/distutils.html @@ -0,0 +1,1062 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>distutils-r1 — standard Python build systems — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="distutils-r1 legacy concepts" href="distutils-legacy.html" /> + <link rel="prev" title="python-r1 — multi-impl packages" href="multi.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="distutils-r1-standard-python-build-systems"> +<h1>distutils-r1 — standard Python build systems<a class="headerlink" href="#distutils-r1-standard-python-build-systems" title="Permalink to this headline">¶</a></h1> +<p>The <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> eclass is used to facilitate build systems using +<code class="docutils literal notranslate"><span class="pre">setup.py</span></code> (distutils and its derivatives, notably setuptools) +or <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> (flit, poetry). It is built on top +of <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> and <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>, and therefore supports +efficiently building multi-impl and single-impl packages.</p> +<p>Eclass reference: <a class="reference external" href="https://devmanual.gentoo.org/eclass-reference/distutils-r1.eclass/index.html">distutils-r1.eclass(5)</a></p> +<section id="the-pep-517-and-legacy-modes"> +<h2>The PEP 517 and legacy modes<a class="headerlink" href="#the-pep-517-and-legacy-modes" title="Permalink to this headline">¶</a></h2> +<div class="admonition warning"> +<p class="admonition-title">Warning</p> +<p>The PEP 517 mode is still experimental and it is not guaranteed +to handle all packages correctly. When using it, please verify +that all necessary files are installed correctly. The hooks provided +by <code class="docutils literal notranslate"><span class="pre">app-portage/iwdevtools</span></code> can be helpful in checking for +regressions when migrating existing packages.</p> +</div> +<p>The <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> eclass has currently two modes of operation: +the PEP 517 mode and the legacy mode. The former mode should be +preferred for new ebuilds; the latter is provided for backwards +compatibility and packages that are not PEP 517-ready.</p> +<p>The PEP 517 mode uses backends as defined by <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/">PEP 517</a> to build +packages. It supports a greater number of Python build systems +at the cost of flexibility and performance. In the eclass +implementation, the PEP 517 backend is used to build a wheel (i.e. a zip +archive) with the package and then an installer tool is used to install +the wheel into a staging directory. The complete process is done +in compile phase, and the install phase merely moves the files into +the image directory.</p> +<p>The legacy mode invokes the <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> script directly. The build +command is invoked to populate the build directory in the compile phase, +then the install command is used in the install phase. Normally, this +mode works only for packages using backwards-compatible distutils +derivatives. Additionally, it supports flit and poetry through +pyproject2setuppy hack. This mode relies on deprecated features.</p> +<p>The PEP 517 mode is enabled via declaring the <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_PEP517</span></code> +variable. Otherwise, the legacy mode is used.</p> +</section> +<section id="basic-use-pep-517-mode"> +<h2>Basic use (PEP 517 mode)<a class="headerlink" href="#basic-use-pep-517-mode" title="Permalink to this headline">¶</a></h2> +<p>By default, <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> sets appropriate metadata variables +and exports a full set of phase functions necessary to install packages +using Python build systems.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_PEP517</span></code> variable is used to enable the modern +PEP 517 mode and declare the build system used. The eclass +automatically generates a build-time dependency on the packages needed +for the build system.</p> +<p>The simplest case of ebuild is:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2022 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">8</span> + +<span class="hll"> <span class="nv">DISTUTILS_USE_PEP517</span><span class="o">=</span>setuptools +</span><span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">8</span>..10<span class="o">}</span> pypy3 <span class="o">)</span> +</span><span class="hll"> inherit distutils-r1 +</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Makes working with XML feel like you are working with JSON"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/martinblech/xmltodict/ https://pypi.org/project/xmltodict/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"MIT"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm ~arm64 ~x86"</span> +</pre></div> +</div> +</section> +<section id="dependencies"> +<h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2> +<p>Dependencies on Python packages are declared using the same method +as the underlying eclass — that is, <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> +or <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>.</p> +<p>In packages using <code class="docutils literal notranslate"><span class="pre">dev-python/setuptools</span></code>, dependencies are often +specified in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> or <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> file. +The <code class="docutils literal notranslate"><span class="pre">install_requires</span></code> key specifies runtime dependencies, +<code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> pure build-time dependencies, <code class="docutils literal notranslate"><span class="pre">extras_require</span></code> +optional dependencies. Test dependencies are sometimes specified +as one of the ‘extras’, and sometimes as <code class="docutils literal notranslate"><span class="pre">tests_require</span></code>.</p> +<p>Setuptools strictly enforces <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code> at build time, +and <code class="docutils literal notranslate"><span class="pre">tests_require</span></code> when running <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">test</span></code>. Runtime +dependencies are enforced only when starting installed programs +via entry points.</p> +<p>In other cases, dependencies are listed in additional files named +e.g. <code class="docutils literal notranslate"><span class="pre">requirements.txt</span></code>. They could be also found in test runner +setup (<code class="docutils literal notranslate"><span class="pre">tox.ini</span></code>) or CI setup files (<code class="docutils literal notranslate"><span class="pre">.travis.yml</span></code>). Finally, you +can grep source code for <code class="docutils literal notranslate"><span class="pre">import</span></code> statements.</p> +<p>In general, you should take special care when listing dependencies +of Python packages. Upstreams sometimes specify indirect dependencies, +often list packages that are not strictly relevant to Gentoo runs +but used on CI/CD setup, unnecessarily restrict version requirements.</p> +<p>Most of the time, runtime dependencies do not need to be present +at build time. However, they do need to be copied there if the Python +modules needing them are imported at build time. Often this is the case +when running tests, hence the following logic is common in Python +ebuilds:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"..."</span> +<span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"test? ( </span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"> )"</span> +</pre></div> +</div> +<p>There are two different approaches used for optional runtime +dependencies. Some packages are installing them conditionally to USE +flags (this is generally acceptable as long as package builds quickly), +others list them in <code class="docutils literal notranslate"><span class="pre">pkg_postinst()</span></code> messages. It is recommended +that optional test dependencies are used unconditionally (to ensure +the widest test coverage, and avoid unpredictable test failures on users +who have more dependencies installed).</p> +</section> +<section id="python-single-r1-variant"> +<span id="index-0"></span><h2>python-single-r1 variant<a class="headerlink" href="#python-single-r1-variant" title="Permalink to this headline">¶</a></h2> +<p>Normally, <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> uses <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> to build multi-impl +packages, and this is the recommended mode. However, in some cases +you will need to use <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> instead, especially if you +need to depend on other packages using that eclass.</p> +<p>The single-impl mode can be enabled by setting <code class="docutils literal notranslate"><span class="pre">DISTUTILS_SINGLE_IMPL</span></code> +variable before inheriting the eclass. The eclass aims to provide +maximum compatibility between these two modes, so most of the existing +code will work with either. However, the functions specific to +the underlying eclass are not compatible — e.g. the dependencies need +to be rewritten.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2022 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">8</span>..10<span class="o">}</span> <span class="o">)</span> + <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"readline"</span> + <span class="nv">DISTUTILS_USE_PEP517</span><span class="o">=</span>setuptools +<span class="hll"> <span class="nv">DISTUTILS_SINGLE_IMPL</span><span class="o">=</span><span class="m">1</span> +</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Pythonic layer on top of the ROOT framework's PyROOT bindings"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"http://rootpy.org"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86 ~amd64-linux ~x86-linux"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> sci-physics/root:=[</span><span class="si">${</span><span class="nv">PYTHON_SINGLE_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> dev-python/root_numpy[</span><span class="si">${</span><span class="nv">PYTHON_SINGLE_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +<span class="s1"> dev-python/matplotlib[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/pytables[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/termcolor[${PYTHON_USEDEP}]</span> +<span class="s1"> '</span><span class="k">)</span><span class="s2">"</span> + + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> sci-physics/root[</span><span class="si">${</span><span class="nv">PYTHON_SINGLE_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</pre></div> +</div> +</section> +<section id="pep-517-build-systems"> +<span id="index-1"></span><h2>PEP 517 build systems<a class="headerlink" href="#pep-517-build-systems" title="Permalink to this headline">¶</a></h2> +<p>The majority of examples in this guide assume using setuptools build +system. However, PEP 517 mode provides support for other build systems.</p> +<p>In order to determine the correct build system used, read +the <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file. An example file could start with:</p> +<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span><span class="w"></span> +<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">"flit_core >=3.6.0,<4"</span><span class="p">]</span><span class="w"></span> +<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"flit_core.buildapi"</span><span class="w"></span> +</pre></div> +</div> +<p>The <code class="docutils literal notranslate"><span class="pre">requires</span></code> key indicates the packages required in order to run +the build system, while <code class="docutils literal notranslate"><span class="pre">build-backend</span></code> indicates the module +(and optionally the class) providing the build system backend. +The eclass maintains a mapping of backend paths to the respective +<code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_PEP517</span></code> and automatically suggests the correct value.</p> +<p>The following table summarizes supported backends.</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 25%" /> +<col style="width: 31%" /> +<col style="width: 44%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>USE_PEP517 value</p></th> +<th class="head"><p>Provider package</p></th> +<th class="head"><p>build-backend</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>flit</p></td> +<td><p>dev-python/flit_core</p></td> +<td><p>flit_core.buildapi</p></td> +</tr> +<tr class="row-odd"><td><p>pdm</p></td> +<td><p>dev-python/pdm-pep517</p></td> +<td><p>pdm.pep517.api</p></td> +</tr> +<tr class="row-even"><td><p>poetry</p></td> +<td><p>dev-python/poetry-core</p></td> +<td><p>poetry.core.masonry.api</p></td> +</tr> +<tr class="row-odd"><td><p>setuptools</p></td> +<td><p>dev-python/setuptools</p></td> +<td><p>setuptools.build_meta +setuptools.__legacy__.build_meta</p></td> +</tr> +<tr class="row-even"><td><p>standalone</p></td> +<td><p>(none)</p></td> +<td><p>(various)</p></td> +</tr> +</tbody> +</table> +<p>The special value <code class="docutils literal notranslate"><span class="pre">standalone</span></code> is reserved for bootstrapping build +systems. It indicates that the package itself provides its own build +backend.</p> +<p>Legacy packages that provide <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> but no <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> +(or do not define a backend inside it) should be installed via +the <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> backend (this applies to pure distutils packages +as well). The eclass automatically uses the legacy setuptools backend +for them.</p> +</section> +<section id="deprecated-pep-517-backends"> +<h2>Deprecated PEP 517 backends<a class="headerlink" href="#deprecated-pep-517-backends" title="Permalink to this headline">¶</a></h2> +<section id="flit-buildapi"> +<h3>flit.buildapi<a class="headerlink" href="#flit-buildapi" title="Permalink to this headline">¶</a></h3> +<p>Some packages are still found using the historical flit build backend. +Their <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> files contain a section similar +to the following:</p> +<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span><span class="w"></span> +<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">"flit"</span><span class="p">]</span><span class="w"></span> +<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"flit.buildapi"</span><span class="w"></span> +</pre></div> +</div> +<p>This backend requires installing the complete flit package manager. +Instead, the package should be fixed upstream to use flit_core +per <a class="reference external" href="https://flit.readthedocs.io/en/latest/pyproject_toml.html#build-system-section">flit build system section documentation</a> instead:</p> +<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span><span class="w"></span> +<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">"flit_core"</span><span class="p">]</span><span class="w"></span> +<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"flit_core.buildapi"</span><span class="w"></span> +</pre></div> +</div> +<p>flit_core produces identical artifacts to flit. At the same time, it +reduces the build-time dependency footprint and therefore makes isolated +PEP 517 builds faster.</p> +</section> +<section id="poetry-masonry-api"> +<h3>poetry.masonry.api<a class="headerlink" href="#poetry-masonry-api" title="Permalink to this headline">¶</a></h3> +<p>A similar problem applies to the packages using poetry. The respective +<code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> files contain:</p> +<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span><span class="w"></span> +<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">"poetry>=0.12"</span><span class="p">]</span><span class="w"></span> +<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"poetry.masonry.api"</span><span class="w"></span> +</pre></div> +</div> +<p>Instead, the lightweight poetry-core module should be used per <a class="reference external" href="https://python-poetry.org/docs/pyproject/#poetry-and-pep-517">poetry +PEP-517 documentation</a>:</p> +<div class="highlight-toml notranslate"><div class="highlight"><pre><span></span><span class="k">[build-system]</span><span class="w"></span> +<span class="n">requires</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="s">"poetry_core>=1.0.0"</span><span class="p">]</span><span class="w"></span> +<span class="n">build-backend</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"poetry.core.masonry.api"</span><span class="w"></span> +</pre></div> +</div> +<p>poetry-core produces identical artifacts to poetry. It has smaller +dependency footprint and makes isolated builds much faster.</p> +</section> +</section> +<section id="setuptools-scm-and-snapshots"> +<span id="index-2"></span><h2>setuptools_scm and snapshots<a class="headerlink" href="#setuptools-scm-and-snapshots" title="Permalink to this headline">¶</a></h2> +<p><a class="reference external" href="https://pypi.org/project/setuptools-scm/">setuptools_scm</a> is a package providing additional features for running +inside a VCS checkout, in particular the ability to determine version +from VCS tags. However, this works correctly only when the package +is built from VCS checkout or an <code class="docutils literal notranslate"><span class="pre">sdist</span></code> archive containing +pregenerated metadata. It does not work when building from a GitHub +snapshot:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>Traceback <span class="o">(</span>most recent call last<span class="o">)</span>: + File <span class="s2">"/tmp/executing-0.5.2/setup.py"</span>, line <span class="m">4</span>, <span class="k">in</span> <module> + setup<span class="o">()</span> + File <span class="s2">"/usr/lib/python3.9/site-packages/setuptools/__init__.py"</span>, line <span class="m">143</span>, <span class="k">in</span> setup + _install_setup_requires<span class="o">(</span>attrs<span class="o">)</span> + File <span class="s2">"/usr/lib/python3.9/site-packages/setuptools/__init__.py"</span>, line <span class="m">131</span>, <span class="k">in</span> _install_setup_requires + <span class="nv">dist</span> <span class="o">=</span> distutils.core.Distribution<span class="o">(</span>dict<span class="o">(</span> + File <span class="s2">"/usr/lib/python3.9/site-packages/setuptools/dist.py"</span>, line <span class="m">425</span>, <span class="k">in</span> __init__ + _Distribution.__init__<span class="o">(</span>self, <span class="o">{</span> + File <span class="s2">"/usr/lib/python3.9/distutils/dist.py"</span>, line <span class="m">292</span>, <span class="k">in</span> __init__ + self.finalize_options<span class="o">()</span> + File <span class="s2">"/usr/lib/python3.9/site-packages/setuptools/dist.py"</span>, line <span class="m">717</span>, <span class="k">in</span> finalize_options + ep<span class="o">(</span>self<span class="o">)</span> + File <span class="s2">"/usr/lib/python3.9/site-packages/setuptools_scm/integration.py"</span>, line <span class="m">48</span>, <span class="k">in</span> infer_version + dist.metadata.version <span class="o">=</span> _get_version<span class="o">(</span>config<span class="o">)</span> + File <span class="s2">"/usr/lib/python3.9/site-packages/setuptools_scm/__init__.py"</span>, line <span class="m">148</span>, <span class="k">in</span> _get_version + <span class="nv">parsed_version</span> <span class="o">=</span> _do_parse<span class="o">(</span>config<span class="o">)</span> + File <span class="s2">"/usr/lib/python3.9/site-packages/setuptools_scm/__init__.py"</span>, line <span class="m">110</span>, <span class="k">in</span> _do_parse + raise LookupError<span class="o">(</span> +LookupError: setuptools-scm was unable to detect version <span class="k">for</span> <span class="s1">'/tmp/executing-0.5.2'</span>. + +Make sure you<span class="s1">'re either building from a fully intact git repository or PyPI tarballs. Most other sources (such as GitHub'</span>s tarballs, a git checkout without the .git folder<span class="o">)</span> don<span class="s1">'t contain the necessary metadata and will not work.</span> + +<span class="s1">For example, if you'</span>re using pip, instead of https://github.com/user/proj/archive/master.zip use git+https://github.com/user/proj.git#egg<span class="o">=</span>proj +</pre></div> +</div> +<p>This problem can be resolved by providing the correct version externally +via <code class="docutils literal notranslate"><span class="pre">SETUPTOOLS_SCM_PRETEND_VERSION</span></code>:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span> <span class="nv">SETUPTOOLS_SCM_PRETEND_VERSION</span><span class="o">=</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span> +</pre></div> +</div> +</section> +<section id="parallel-build-race-conditions"> +<h2>Parallel build race conditions<a class="headerlink" href="#parallel-build-race-conditions" title="Permalink to this headline">¶</a></h2> +<p>The distutils build system has a major unresolved bug regarding race +conditions. If the same source file is used to build multiple Python +extensions, the build can start multiple simultaneous compiler processes +using the same output file. As a result, there is a race between +the compilers writing output file and link editors reading it. This +generally does not cause immediate build failures but results in broken +extensions causing cryptic issues in reverse dependencies.</p> +<p>For example, a miscompilation of <code class="docutils literal notranslate"><span class="pre">dev-python/pandas</span></code> have recently +caused breakage in <code class="docutils literal notranslate"><span class="pre">dev-python/dask</span></code>:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>/usr/lib/python3.8/site-packages/pandas/__init__.py:29: <span class="k">in</span> <module> + from pandas._libs import hashtable as _hashtable, lib as _lib, tslib as _tslib +/usr/lib/python3.8/site-packages/pandas/_libs/__init__.py:13: <span class="k">in</span> <module> + from pandas._libs.interval import Interval +pandas/_libs/interval.pyx:1: <span class="k">in</span> init pandas._libs.interval + ??? +pandas/_libs/hashtable.pyx:1: <span class="k">in</span> init pandas._libs.hashtable + ??? +pandas/_libs/missing.pyx:1: <span class="k">in</span> init pandas._libs.missing + ??? +/usr/lib/python3.8/site-packages/pandas/_libs/tslibs/__init__.py:30: <span class="k">in</span> <module> + from .conversion import OutOfBoundsTimedelta, localize_pydatetime +E ImportError: /usr/lib/python3.8/site-packages/pandas/_libs/tslibs/conversion.cpython-38-x86_64-linux-gnu.so: undefined symbol: pandas_datetime_to_datetimestruct +</pre></div> +</div> +<p>The easiest way to workaround the problem in ebuild is to append <code class="docutils literal notranslate"><span class="pre">-j1</span></code> +in <a class="reference internal" href="#python-compile">python_compile</a> sub-phase.</p> +<p>The common way of working around the problem upstream is to create +additional .c files that <code class="docutils literal notranslate"><span class="pre">#include</span></code> the original file, and use unique +source files for every extension.</p> +</section> +<section id="sub-phase-functions"> +<h2>Sub-phase functions<a class="headerlink" href="#sub-phase-functions" title="Permalink to this headline">¶</a></h2> +<p>Ebuilds define phase functions in order to conveniently override parts +of the build process. <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> extends this concept +by introducing <em>sub-phases</em>. All <code class="docutils literal notranslate"><span class="pre">src_*</span></code> phases in ebuild are split +into two sub-phases: <code class="docutils literal notranslate"><span class="pre">python_*</span></code> sub-phases that are run in a loop +for all enabled interpreters, and <code class="docutils literal notranslate"><span class="pre">python_*_all</span></code> sub-phases that +comprise the common code to be run only once.</p> +<p>Sub-phase functions behave similarly to phase functions. They are run +if defined by the ebuild. If they’re not, the default implementation +is run (if any). The ebuild overrides can call the default +as <code class="docutils literal notranslate"><span class="pre">distutils-r1_<sub-phase></span></code>, the same way it can call eclass’ phase +function defaults.</p> +<p>There are 10 sub-phases corresponding to 5 phase functions. They are +run in the following order:</p> +<ol class="arabic simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">python_prepare_all</span></code> (for <code class="docutils literal notranslate"><span class="pre">src_prepare</span></code>, has default)</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_prepare</span></code> (for each impl.)</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_configure</span></code> (for <code class="docutils literal notranslate"><span class="pre">src_configure</span></code>, foreach impl.)</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_configure_all</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_compile</span></code> (for <code class="docutils literal notranslate"><span class="pre">src_compile</span></code>, for each impl., has default)</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_compile_all</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_test</span></code> (for <code class="docutils literal notranslate"><span class="pre">src_test</span></code>, for each impl.)</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_test_all</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_install</span></code> (for <code class="docutils literal notranslate"><span class="pre">src_install</span></code>, for each impl., has default)</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_install_all</span></code> (has default)</p></li> +</ol> +<p>Note that normally all phases are run in the source directory, while +defining <code class="docutils literal notranslate"><span class="pre">${BUILD_DIR}</span></code> to a dedicated build directory for each +implementation. However, if in-source builds are enabled, all phases +are run in these build directories.</p> +<span class="target" id="index-3"></span><section id="python-prepare"> +<span id="index-4"></span><h3>python_prepare<a class="headerlink" href="#python-prepare" title="Permalink to this headline">¶</a></h3> +<p><code class="docutils literal notranslate"><span class="pre">python_prepare_all</span></code> is responsible for applying changes +to the package sources that are common to all Python implementations. +The default implementation performs the tasks of <code class="docutils literal notranslate"><span class="pre">default_src_prepare</span></code> +(applying patches), as well as eclass-specific tasks: removing +<code class="docutils literal notranslate"><span class="pre">ez_setup</span></code> (method of bootstrapping setuptools used in old packages) +and handling <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>. In the end, the function copies +sources to build dirs if in-source build is requested.</p> +<p>If additional changes need to be done to the package, either this +sub-phase or <code class="docutils literal notranslate"><span class="pre">src_prepare</span></code> in general can be replaced. However, +you should always call the original implementation from your override. +For example, you could use it to strip extraneous dependencies or broken +tests:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_prepare_all<span class="o">()</span> <span class="o">{</span> + <span class="c1"># FIXME</span> + rm tests/test_pytest_plugin.py <span class="o">||</span> die + sed -i -e <span class="s1">'s:test_testcase_no_app:_&:'</span> tests/test_test_utils.py <span class="o">||</span> die + + <span class="c1"># remove pointless dep on pytest-cov</span> + sed -i -e <span class="s1">'/addopts/s/--cov=aiohttp//'</span> pytest.ini <span class="o">||</span> die + + distutils-r1_python_prepare_all +<span class="o">}</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">python_prepare</span></code> is responsible for applying changes specific to one +interpreter. It has no default implementation. When defined, in-source +builds are enabled implicitly as sources need to be duplicated to apply +implementation-specific changes.</p> +<p>In the following example, it is used to remove a CLI script whose +dependencies only support Python 3.8 and 3.9 at the moment. Naturally, +since this modification needs to be done on a subset of all Python +interpreters, the eclass needs to keep a separate copy of the sources +for every one of them. This is why <code class="docutils literal notranslate"><span class="pre">python_prepare</span></code> automatically +enables in-source builds.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_prepare<span class="o">()</span> <span class="o">{</span> + <span class="k">if</span> ! use cli <span class="o">||</span> ! has <span class="s2">"</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">"</span> python3.<span class="o">{</span><span class="m">7</span>..9<span class="o">}</span><span class="p">;</span> <span class="k">then</span> + sed -i -e <span class="s1">'/console_scripts/d'</span> setup.py <span class="o">||</span> die + <span class="k">fi</span> +<span class="o">}</span> +</pre></div> +</div> +<span class="target" id="index-5"></span></section> +<section id="python-configure"> +<span id="index-6"></span><h3>python_configure<a class="headerlink" href="#python-configure" title="Permalink to this headline">¶</a></h3> +<p><code class="docutils literal notranslate"><span class="pre">python_configure</span></code> and <code class="docutils literal notranslate"><span class="pre">python_configure_all</span></code> have no default +functionality. The former is convenient for running additional +configuration steps if needed by the package, the latter for defining +global environment variables.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_configure<span class="o">()</span> <span class="o">{</span> + esetup.py configure <span class="k">$(</span>usex mpi --mpi <span class="s1">''</span><span class="k">)</span> +<span class="o">}</span> +</pre></div> +</div> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_configure_all<span class="o">()</span> <span class="o">{</span> + <span class="nv">DISTUTILS_ARGS</span><span class="o">=(</span> + --resourcepath<span class="o">=</span>/usr/share + --no-compress-manpages + <span class="o">)</span> +<span class="o">}</span> +</pre></div> +</div> +<span class="target" id="index-7"></span></section> +<section id="python-compile"> +<span id="index-8"></span><h3>python_compile<a class="headerlink" href="#python-compile" title="Permalink to this headline">¶</a></h3> +<p><code class="docutils literal notranslate"><span class="pre">python_compile</span></code> normally builds the package. It is sometimes used +to pass additional arguments to the build step. For example, it can +be used to disable parallel extension builds in packages that are broken +with it:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_compile<span class="o">()</span> <span class="o">{</span> + distutils-r1_python_compile -j1 +<span class="o">}</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">python_compile_all</span></code> +has no default implementation. It is convenient for performing +additional common build steps, in particular for building +the documentation (see <code class="docutils literal notranslate"><span class="pre">distutils_enable_sphinx</span></code>).</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_compile_all<span class="o">()</span> <span class="o">{</span> + use doc <span class="o">&&</span> emake -C docs html +<span class="o">}</span> +</pre></div> +</div> +<span class="target" id="index-9"></span></section> +<section id="python-test"> +<span id="index-10"></span><h3>python_test<a class="headerlink" href="#python-test" title="Permalink to this headline">¶</a></h3> +<p><code class="docutils literal notranslate"><span class="pre">python_test</span></code> is responsible for running tests. It has no default +implementation but you are strongly encouraged to provide one (either +directly or via <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code>). <code class="docutils literal notranslate"><span class="pre">python_test_all</span></code> +can be used to run additional testing code that is not specific +to Python.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + <span class="s2">"</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">"</span> TestBitVector/Test.py <span class="o">||</span> die <span class="s2">"Tests fail with </span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">"</span> +<span class="o">}</span> +</pre></div> +</div> +<span class="target" id="index-11"></span></section> +<section id="python-install"> +<span id="index-12"></span><h3>python_install<a class="headerlink" href="#python-install" title="Permalink to this headline">¶</a></h3> +<p><code class="docutils literal notranslate"><span class="pre">python_install</span></code> installs the package’s Python part. It is usually +redefined in order to pass additional <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> arguments +or to install additional Python modules.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_install<span class="o">()</span> <span class="o">{</span> + distutils-r1_python_install + + <span class="c1"># ensure data files for tests are getting installed too</span> + python_moduleinto collada/tests/ + python_domodule collada/tests/data +<span class="o">}</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">python_install_all</span></code> installs documentation via <code class="docutils literal notranslate"><span class="pre">einstalldocs</span></code>. +It is usually defined by ebuilds to install additional common files +such as bash completions or examples.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_install_all<span class="o">()</span> <span class="o">{</span> + <span class="k">if</span> use examples<span class="p">;</span> <span class="k">then</span> + docinto examples + dodoc -r Sample_Code/. + docompress -x /usr/share/doc/<span class="si">${</span><span class="nv">PF</span><span class="si">}</span>/examples + <span class="k">fi</span> + distutils-r1_python_install_all +<span class="o">}</span> +</pre></div> +</div> +</section> +</section> +<section id="passing-arguments-to-setup-py-commands"> +<h2>Passing arguments to setup.py commands<a class="headerlink" href="#passing-arguments-to-setup-py-commands" title="Permalink to this headline">¶</a></h2> +<p>The PEP 517 mode does not support passing additional commands arguments +via <code class="docutils literal notranslate"><span class="pre">DISTUTILS_ARGS</span></code> anymore. Instead, the additional parameters +can be passed using the <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> file.</p> +<p>For example, Pillow provides for configuring available backends via +additional <code class="docutils literal notranslate"><span class="pre">build_ext</span></code> command flags:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>setup.py build_ext --enable-tiff --disable-webp ... +</pre></div> +</div> +<p>The respective options can be setup via the configuration file, where +sections represent the commands and individual keys — options. Note +that dashes need to be replaced by underscores, and flag-style options +take boolean arguments. In this case, the ebuild can use:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>src_configure<span class="o">()</span> <span class="o">{</span> + cat >> setup.cfg <span class="s"><<-EOF</span> +<span class="s"> [build_ext]</span> +<span class="s"> disable_tiff = $(usex !tiff True False)</span> +<span class="s"> enable_tiff = $(usex tiff True False)</span> +<span class="s"> disable_webp = $(usex !webp True False)</span> +<span class="s"> enable_webp = $(usex webp True False)</span> +<span class="s"> #...</span> +<span class="s"> EOF</span> +<span class="o">}</span> +</pre></div> +</div> +<p>Note that this method works only for arguments to specific commands. +Some packages use hacks to support global options, e.g. via manipulating +<code class="docutils literal notranslate"><span class="pre">sys.argv</span></code> directly. This is no longer possible with PEP 517 builds +and the packages need to be fixed not to rely on it. The possible +alternatives include using environment variables or custom commands.</p> +</section> +<section id="calling-custom-setup-py-commands"> +<span id="index-13"></span><h2>Calling custom setup.py commands<a class="headerlink" href="#calling-custom-setup-py-commands" title="Permalink to this headline">¶</a></h2> +<p>When working on packages using setuptools or modified distutils, you +sometimes need to manually invoke <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>. The eclass provides +a <code class="docutils literal notranslate"><span class="pre">esetup.py</span></code> helper that wraps it with additional checks, error +handling and ensures that the override configuration file is created +beforehand (much like <code class="docutils literal notranslate"><span class="pre">econf</span></code> or <code class="docutils literal notranslate"><span class="pre">emake</span></code>).</p> +<p><code class="docutils literal notranslate"><span class="pre">esetup.py</span></code> passes all its paremeters to <code class="docutils literal notranslate"><span class="pre">./setup.py</span></code>.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + esetup.py check +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="preventing-test-directory-from-being-installed"> +<h2>Preventing test directory from being installed<a class="headerlink" href="#preventing-test-directory-from-being-installed" title="Permalink to this headline">¶</a></h2> +<p>Many packages using the setuptools build system utilize the convenient +<code class="docutils literal notranslate"><span class="pre">find_packages()</span></code> method to locate the Python sources. In some cases, +this method also wrongly grabs top-level test directories or other files +that were not intended to be installed.</p> +<p>The eclass attempts to detect and report the most common mistakes:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">* Package installs 'tests' package which is forbidden and likely a bug in the build system.</span> +</pre></div> +</div> +<p>The correct fix for this problem is to add an <code class="docutils literal notranslate"><span class="pre">exclude</span></code> parameter +to the <code class="docutils literal notranslate"><span class="pre">find_packages()</span></code> call in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>, e.g.:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span> + <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">(</span><span class="n">exclude</span><span class="o">=</span><span class="p">[</span><span class="s2">"tests"</span><span class="p">,</span> <span class="s2">"tests.*"</span><span class="p">]))</span> +</pre></div> +</div> +<p>Note that if the top-level <code class="docutils literal notranslate"><span class="pre">tests</span></code> package has any subpackages, both +<code class="docutils literal notranslate"><span class="pre">tests</span></code> and <code class="docutils literal notranslate"><span class="pre">tests.*</span></code> need to be listed.</p> +<div class="admonition warning"> +<p class="admonition-title">Warning</p> +<p>In order to test your fix properly, you need to remove the previous +build directory. Otherwise, the install command will install all +files found there, including the files that are now excluded.</p> +</div> +<p>As an intermediate solution it is possible to strip the extra +directories in the install phase:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_install<span class="o">()</span> <span class="o">{</span> + rm -r <span class="s2">"</span><span class="si">${</span><span class="nv">BUILD_DIR</span><span class="si">}</span><span class="s2">"</span>/lib/tests <span class="o">||</span> die + distutils-r1_python_install +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="enabling-tests"> +<span id="index-14"></span><h2>Enabling tests<a class="headerlink" href="#enabling-tests" title="Permalink to this headline">¶</a></h2> +<p>Since Python performs only minimal build-time (or more precisely, +import-time) checking of correctness, it is important to run tests +of Python packages in order to catch any problems early. This is +especially important for permitting others to verify support for new +Python implementations.</p> +<p>Many Python packages use one of the standard test runners, and work fine +with the default ways of calling them. Note that upstreams sometimes +specify a test runner that’s not strictly necessary — e.g. specify +<code class="docutils literal notranslate"><span class="pre">dev-python/pytest</span></code> as a dependency while the tests do not use it +anywhere and work just fine with built-in modules. The best way +to determine the test runner to use is to grep the test sources.</p> +<section id="using-distutils-enable-tests"> +<h3>Using distutils_enable_tests<a class="headerlink" href="#using-distutils-enable-tests" title="Permalink to this headline">¶</a></h3> +<p>The simplest way of enabling tests is to call <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> +in global scope, passing the test runner name as the first argument. +This function takes care of declaring test phase, setting appropriate +dependencies and <code class="docutils literal notranslate"><span class="pre">test</span></code> USE flag if necessary. If called after +setting <code class="docutils literal notranslate"><span class="pre">RDEPEND</span></code>, it also copies it to test dependencies.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> pypy3 <span class="o">)</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"An easy whitelist-based HTML-sanitizing tool"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/mozilla/bleach https://pypi.org/project/bleach/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"Apache-2.0"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~mips ~ppc ~ppc64 ~s390 ~sparc ~x86"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> dev-python/six[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> dev-python/webencodings[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> "</span> + +<span class="hll"> distutils_enable_tests pytest +</span></pre></div> +</div> +<p>The valid values include:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">nose</span></code> for <code class="docutils literal notranslate"><span class="pre">dev-python/nose</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">pytest</span></code> for <code class="docutils literal notranslate"><span class="pre">dev-python/pytest</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">setup.py</span></code> to call <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">test</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">unittest</span></code> to use built-in unittest discovery</p></li> +</ul> +</section> +<section id="adding-more-test-dependencies"> +<h3>Adding more test dependencies<a class="headerlink" href="#adding-more-test-dependencies" title="Permalink to this headline">¶</a></h3> +<p>Additional test dependencies can be specified in <code class="docutils literal notranslate"><span class="pre">test?</span></code> conditional. +The flag normally does not need to be explicitly declared, +as <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> does that in the majority of cases.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> pypy3 <span class="o">)</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Universal encoding detector"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/chardet/chardet https://pypi.org/project/chardet/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/chardet/chardet/archive/</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">.tar.gz -> </span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"LGPL-2.1"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 arm arm64 hppa ia64 ~m68k ~mips ppc ppc64 s390 ~sh sparc x86 ~x64-cygwin ~amd64-linux ~x86-linux ~x64-macos ~x86-macos ~x64-solaris"</span> + + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> test? ( dev-python/hypothesis[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">] )</span> +</span><span class="s2"> "</span> + +<span class="hll"> distutils_enable_tests pytest +</span></pre></div> +</div> +<p>Note that <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> modifies variables directly +in the ebuild environment. This means that if you wish to change their +values, you need to append to them, i.e. the bottom part of that ebuild +can be rewritten as:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> distutils_enable_tests pytest + +<span class="hll"> <span class="nv">DEPEND</span><span class="o">+=</span><span class="s2">"</span> +</span><span class="s2"> test? ( dev-python/hypothesis[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">] )</span> +<span class="s2"> "</span> +</pre></div> +</div> +</section> +<section id="installing-the-package-before-running-tests"> +<h3>Installing the package before running tests<a class="headerlink" href="#installing-the-package-before-running-tests" title="Permalink to this headline">¶</a></h3> +<p>In PEP 517 mode, the eclass automatically exposes a venv-style install +tree to the test phase. No explicit action in necessary.</p> +<p>In the legacy mode, <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> has an optional +<code class="docutils literal notranslate"><span class="pre">--install</span></code> option that can be used to force performing an install +to a temporary directory. More information can be found in the legacy +section.</p> +</section> +<section id="undesirable-test-dependencies"> +<h3>Undesirable test dependencies<a class="headerlink" href="#undesirable-test-dependencies" title="Permalink to this headline">¶</a></h3> +<p>There is a number of packages that are frequently listed as test +dependencies upstream but have little to no value for Gentoo users. +It is recommended to skip those test dependencies whenever possible. +If tests fail to run without them, it is often preferable to strip +the dependencies and/or configuration values enforcing them.</p> +<p><em>Coverage testing</em> establishes how much of the package’s code is covered +by the test suite. While this is useful statistic upstream, it has +no value for Gentoo users who just want to install the package. This +is often represented by dependencies on <code class="docutils literal notranslate"><span class="pre">dev-python/coverage</span></code>, +<code class="docutils literal notranslate"><span class="pre">dev-python/pytest-cov</span></code>. In the latter case, you usually need +to strip <code class="docutils literal notranslate"><span class="pre">--cov</span></code> parameter from <code class="docutils literal notranslate"><span class="pre">pytest.ini</span></code>.</p> +<p><em>PEP-8 testing</em> enforces standard coding style across Python programs. +Issues found by it are relevant to upstream but entirely irrelevant +to Gentoo users. If the package uses <code class="docutils literal notranslate"><span class="pre">dev-python/pep8</span></code>, +<code class="docutils literal notranslate"><span class="pre">dev-python/pycodestyle</span></code>, <code class="docutils literal notranslate"><span class="pre">dev-python/flake8</span></code>, strip that +dependency.</p> +<p><code class="docutils literal notranslate"><span class="pre">dev-python/pytest-runner</span></code> is a thin wrapper to run pytest +from <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>. Do not use it, just call pytest directly.</p> +<p><code class="docutils literal notranslate"><span class="pre">dev-python/tox</span></code> is a convenient wrapper to run tests for multiple +Python versions, in a virtualenv. The eclass already provides the logic +for the former, and an environment close enough to the latter. Do not +use tox in ebuilds.</p> +</section> +<section id="customizing-the-test-phase"> +<h3>Customizing the test phase<a class="headerlink" href="#customizing-the-test-phase" title="Permalink to this headline">¶</a></h3> +<p>If additional pre-/post-test phase actions need to be performed, +they can be easily injected via overriding <code class="docutils literal notranslate"><span class="pre">src_test()</span></code> and making +it call <code class="docutils literal notranslate"><span class="pre">distutils-r1_src_test</span></code>:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> <span class="o">)</span> + inherit distutils-r1 virtualx + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Extra features for standard library's cmd module"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/python-cmd2/cmd2"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"MIT"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm ~arm64 ~ppc64 ~x86 ~amd64-linux ~x86-linux"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> dev-python/attrs[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/colorama-0.3.7[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/pyperclip-1.6[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> dev-python/six[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> dev-python/wcwidth[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> "</span> + <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> dev-python/setuptools_scm[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> "</span> + + distutils_enable_tests pytest + +<span class="hll"> src_test<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> <span class="c1"># tests rely on very specific text wrapping...</span> +</span><span class="hll"> <span class="nb">local</span> -x <span class="nv">COLUMNS</span><span class="o">=</span><span class="m">80</span> +</span><span class="hll"> distutils-r1_src_test +</span><span class="hll"> <span class="o">}</span> +</span></pre></div> +</div> +<p>If the actual test command needs to be customized, or a non-standard +test tool needs to be used, you can define a <code class="docutils literal notranslate"><span class="pre">python_test()</span></code> sub-phase +function. This function is called for every enabled Python target +by the default <code class="docutils literal notranslate"><span class="pre">src_test</span></code> implementation. This can either be combined +with <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> call, or used instead of it. In fact, +the former function simply defines a <code class="docutils literal notranslate"><span class="pre">python_test()</span></code> function as part +of its logic.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python<span class="o">{</span>2_7,3_6,3_7,3_8<span class="o">}</span> pypy3 <span class="o">)</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Bash tab completion for argparse"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://pypi.org/project/argcomplete/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"Apache-2.0"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm ~arm64 ~hppa ~x86 ~amd64-linux ~x86-linux ~x64-macos"</span> +<span class="hll"> <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"test"</span> +</span><span class="hll"> <span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span> +</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +<span class="s1"> <dev-python/importlib_metadata-2[${PYTHON_USEDEP}]</span> +<span class="s1"> '</span> -2 python3_<span class="o">{</span><span class="m">5</span>,6,7<span class="o">}</span> pypy3<span class="k">)</span><span class="s2">"</span> + <span class="c1"># pip is called as an external tool</span> + <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> dev-python/setuptools[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="hll"><span class="s2"> test? (</span> +</span><span class="hll"><span class="s2"> app-shells/fish</span> +</span><span class="hll"><span class="s2"> app-shells/tcsh</span> +</span><span class="hll"><span class="s2"> dev-python/pexpect[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +</span><span class="hll"><span class="s2"> dev-python/pip</span> +</span><span class="hll"><span class="s2"> )"</span> +</span> +<span class="hll"> python_test<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> <span class="s2">"</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">"</span> test/test.py -v <span class="o">||</span> die +</span><span class="hll"> <span class="o">}</span> +</span></pre></div> +</div> +<p>Note that <code class="docutils literal notranslate"><span class="pre">python_test</span></code> is called by <code class="docutils literal notranslate"><span class="pre">distutils-r1_src_test</span></code>, +so you must make sure to call it if you override <code class="docutils literal notranslate"><span class="pre">src_test</span></code>.</p> +</section> +<section id="customizing-the-test-phase-for-pytest"> +<span id="index-15"></span><h3>Customizing the test phase for pytest<a class="headerlink" href="#customizing-the-test-phase-for-pytest" title="Permalink to this headline">¶</a></h3> +<p>For the relatively frequent case of pytest-based packages needing +additional customization, a <code class="docutils literal notranslate"><span class="pre">epytest</span></code> helper is provided. The helper +runs <code class="docutils literal notranslate"><span class="pre">pytest</span></code> with a standard set of options and automatic handling +of test failures.</p> +<p>For example, if upstream uses <code class="docutils literal notranslate"><span class="pre">network</span></code> marker to disable +network-based tests, you can override the test phase in the following +way:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>distutils_enable_tests pytest + +python_test<span class="o">()</span> <span class="o">{</span> + epytest -m <span class="s1">'not network'</span> +<span class="o">}</span> +</pre></div> +</div> +</section> +</section> +<section id="building-documentation-via-sphinx"> +<span id="index-16"></span><h2>Building documentation via Sphinx<a class="headerlink" href="#building-documentation-via-sphinx" title="Permalink to this headline">¶</a></h2> +<p><code class="docutils literal notranslate"><span class="pre">dev-python/sphinx</span></code> is commonly used to document Python packages. +It comes with a number of plugins and themes that make it convenient +to write and combine large text documents (such as this Guide!), +as well as automatically document Python code.</p> +<p>Depending on the exact package, building documentation may range +from being trivial to very hard. Packages that do not use autodoc +(documenting of Python code) do not need to USE-depend on Sphinx at all. +Packages that do that need to use a supported Python implementation +for Sphinx, and packages that use plugins need to guarantee the same +implementation across all plugins. To cover all those use cases easily, +the <code class="docutils literal notranslate"><span class="pre">distutils_enable_sphinx</span></code> function is provided.</p> +<section id="basic-documentation-with-autodoc"> +<h3>Basic documentation with autodoc<a class="headerlink" href="#basic-documentation-with-autodoc" title="Permalink to this headline">¶</a></h3> +<p>The most common case is a package that uses Sphinx along with autodoc. +It can be recognized by <code class="docutils literal notranslate"><span class="pre">conf.py</span></code> listing <code class="docutils literal notranslate"><span class="pre">sphinx.ext.autodoc</span></code> +in the extension list. In order to support building documentation, +call <code class="docutils literal notranslate"><span class="pre">distutils_enable_sphinx</span></code> and pass the path to the directory +containing Sphinx documentation:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> <span class="o">)</span> + <span class="nv">DISTUTILS_USE_SETUPTOOLS</span><span class="o">=</span>rdepend + + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Colored stream handler for the logging module"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> https://pypi.org/project/coloredlogs/</span> +<span class="s2"> https://github.com/xolox/python-coloredlogs</span> +<span class="s2"> https://coloredlogs.readthedocs.io/en/latest/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"MIT"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86 ~amd64-linux ~x86-linux"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"dev-python/humanfriendly[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> + +<span class="hll"> distutils_enable_sphinx docs +</span></pre></div> +</div> +<p>This call takes care of it all: it adds <code class="docutils literal notranslate"><span class="pre">doc</span></code> USE flag to control +building documentation, appropriate dependencies via the expert any-r1 +API making it sufficient for Sphinx to be installed with only one +of the supported implementations, and appropriate <code class="docutils literal notranslate"><span class="pre">python_compile_all</span></code> +implementation to build and install HTML documentation.</p> +</section> +<section id="additional-sphinx-extensions"> +<h3>Additional Sphinx extensions<a class="headerlink" href="#additional-sphinx-extensions" title="Permalink to this headline">¶</a></h3> +<p>It is not uncommon for packages to require additional third-party +extensions to Sphinx. Those include themes. In order to specify +dependencies on the additional packages, pass them as extra arguments +to <code class="docutils literal notranslate"><span class="pre">distutils_enable_sphinx</span></code>.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> pypy3 python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> <span class="o">)</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Correctly inflect words and numbers"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/jazzband/inflect"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"MIT"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm64 ~ia64 ~ppc ~ppc64 ~x86"</span> + +<span class="hll"> distutils_enable_sphinx docs <span class="se">\</span> +</span><span class="hll"> <span class="s1">'>=dev-python/jaraco-packaging-3.2'</span> <span class="se">\</span> +</span><span class="hll"> <span class="s1">'>=dev-python/rst-linker-1.9'</span> <span class="se">\</span> +</span><span class="hll"> dev-python/alabaster +</span></pre></div> +</div> +<p>In this case, the function uses the any-r1 API to request one +of the supported implementations to be enabled on <em>all</em> of those +packages. However, it does not have to be the one in <code class="docutils literal notranslate"><span class="pre">PYTHON_TARGETS</span></code> +for this package.</p> +</section> +<section id="sphinx-without-autodoc-or-extensions"> +<h3>Sphinx without autodoc or extensions<a class="headerlink" href="#sphinx-without-autodoc-or-extensions" title="Permalink to this headline">¶</a></h3> +<p>Finally, there are packages that use Sphinx purely to build +documentation from text files, without inspecting Python code. +For those packages, the any-r1 API can be omitted entirely and plain +dependency on <code class="docutils literal notranslate"><span class="pre">dev-python/sphinx</span></code> is sufficient. In this case, +the <code class="docutils literal notranslate"><span class="pre">--no-autodoc</span></code> option can be specified instead of additional +packages.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> <span class="o">)</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Python Serial Port extension"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/pyserial/pyserial https://pypi.org/project/pyserial/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">PN</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"PSF-2"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 ~arm arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~x86"</span> + +<span class="hll"> distutils_enable_sphinx documentation --no-autodoc +</span></pre></div> +</div> +<p>Note that this is valid only if no third-party extensions are used. +If additional packages need to be installed, the previous variant +must be used instead.</p> +<p>The eclass tries to automatically determine whether <code class="docutils literal notranslate"><span class="pre">--no-autodoc</span></code> +should be used, and issue a warning if it’s missing or incorrect.</p> +</section> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">distutils-r1 — standard Python build systems</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#the-pep-517-and-legacy-modes">The PEP 517 and legacy modes</a></li> +<li class="toctree-l2"><a class="reference internal" href="#basic-use-pep-517-mode">Basic use (PEP 517 mode)</a></li> +<li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="#python-single-r1-variant">python-single-r1 variant</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pep-517-build-systems">PEP 517 build systems</a></li> +<li class="toctree-l2"><a class="reference internal" href="#deprecated-pep-517-backends">Deprecated PEP 517 backends</a></li> +<li class="toctree-l2"><a class="reference internal" href="#setuptools-scm-and-snapshots">setuptools_scm and snapshots</a></li> +<li class="toctree-l2"><a class="reference internal" href="#parallel-build-race-conditions">Parallel build race conditions</a></li> +<li class="toctree-l2"><a class="reference internal" href="#sub-phase-functions">Sub-phase functions</a></li> +<li class="toctree-l2"><a class="reference internal" href="#passing-arguments-to-setup-py-commands">Passing arguments to setup.py commands</a></li> +<li class="toctree-l2"><a class="reference internal" href="#calling-custom-setup-py-commands">Calling custom setup.py commands</a></li> +<li class="toctree-l2"><a class="reference internal" href="#preventing-test-directory-from-being-installed">Preventing test directory from being installed</a></li> +<li class="toctree-l2"><a class="reference internal" href="#enabling-tests">Enabling tests</a></li> +<li class="toctree-l2"><a class="reference internal" href="#building-documentation-via-sphinx">Building documentation via Sphinx</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="multi.html" title="previous chapter">python-r1 — multi-impl packages</a></li> + <li>Next: <a href="distutils-legacy.html" title="next chapter">distutils-r1 legacy concepts</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/distutils.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/eclass.html b/guide/eclass.html new file mode 100644 index 0000000..95cb674 --- /dev/null +++ b/guide/eclass.html @@ -0,0 +1,240 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Choosing between Python eclasses — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Common basics" href="basic.html" /> + <link rel="prev" title="Python interpreters" href="interpreter.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="choosing-between-python-eclasses"> +<h1>Choosing between Python eclasses<a class="headerlink" href="#choosing-between-python-eclasses" title="Permalink to this headline">¶</a></h1> +<section id="build-time-vs-runtime-use"> +<h2>Build-time vs runtime use<a class="headerlink" href="#build-time-vs-runtime-use" title="Permalink to this headline">¶</a></h2> +<p>The first basis for choosing Python eclass is whether Python is used +merely at build-time or at runtime as well.</p> +<p>A runtime use occurs if the package explicitly needs Python to be +installed along with it, in order for it to function correctly. This +generally happens if the package installs Python modules, extensions, +scripts, or executables calling the Python interpreter or linking +to libpython. This also applies to bash scripts or other executables +that call python inline.</p> +<p>A build-time use occurs if the package calls the Python interpreter +or any kind of aforementioned executables during package’s build +(or install) phases.</p> +<p>If the package uses Python purely at build-time, the <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code> +eclass is appropriate. Otherwise, <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>, <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> +or their derivatives are to be used.</p> +<p>A specific exception to that rule is when the package is only calling +external Python scripts directly (i.e. not via <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">/usr/bin/foo</span></code>). +If the called executables can be considered fully contained +dependency-wise, there is no need to use an eclass.</p> +<p>For example, when using <code class="docutils literal notranslate"><span class="pre">dev-util/meson</span></code> to build a package, there is +no need to use a Python eclass since Meson abstracts away its Pythonic +implementation details and works as a regular executable for your +packages. However, <code class="docutils literal notranslate"><span class="pre">dev-util/scons</span></code> requires Python eclass since it +loads Python code from the package and a compatible Python version must +be enforced.</p> +</section> +<section id="single-impl-vs-multi-impl"> +<h2>Single-impl vs multi-impl<a class="headerlink" href="#single-impl-vs-multi-impl" title="Permalink to this headline">¶</a></h2> +<p>The second important basis for packages using Python at runtime is +whether the package in question should support multi-implementation +install or not.</p> +<p>A <em>single-impl</em> package is a package requiring the user to choose +exactly one Python implementation to be built against. This means +that the scripts installed by that package will be run via specified +Python interpreter, and that the modules and extensions will be +importable from it only. The package’s Python reverse dependencies will +also have to use the same implementation. Since the package can’t +support having more than one implementation enabled, its reverse +dependencies have to be simple-impl as well.</p> +<p>Single-impl packages use <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> eclass. Writing ebuilds +for them is easier since it is generally sufficient to call setup +function early on, and the upstream build system generally takes care +of using selected Python version correctly. Making packages single-impl +is recommended when dealing with packages that are not purely written +for Python or have single-impl dependencies.</p> +<p>A <em>multi-impl</em> package allows user to enable multiple (preferably +any number of) implementations. The modules, extensions and scripts +installed by the package are installed separately for each enabled +implementation, and can therefore be used from any of them. The package +can have reverse dependencies enabling only a subset of its +implementations.</p> +<p>Multi-impl packages use <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> eclass. Ebuilds are more complex +since they need to explicitly repeat build and install steps for each +enabled implementation. Using this model is recommended for packages +providing Python modules or extensions only, or having multi-impl +reverse dependencies. In some cases supporting multi-impl build +requires applying hacks, e.g. <code class="docutils literal notranslate"><span class="pre">dev-libs/boost[python]</span></code> uses +non-standard names to install <code class="docutils literal notranslate"><span class="pre">libboost_python</span></code> for multiple Python +versions.</p> +<p>The implementation for single-impl packages is selected +via <code class="docutils literal notranslate"><span class="pre">PYTHON_SINGLE_TARGET</span></code>, while multi-impl uses <code class="docutils literal notranslate"><span class="pre">PYTHON_TARGETS</span></code>. +These USE flag sets can be set independently to provide greater +flexibility for developers and end users.</p> +</section> +<section id="distutils-and-related-build-systems"> +<h2>Distutils and related build systems<a class="headerlink" href="#distutils-and-related-build-systems" title="Permalink to this headline">¶</a></h2> +<p>The third basis for choosing an eclass is the build system used. +If the project uses one of Python-specific build systems, that is +distutils, setuptools, flit or poetry, the <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> eclass +should be used instead of the other eclasses. As a rule of thumb, +this happens when either <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> or <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file exists +in the distribution.</p> +<p><code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> builds on either <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> or <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>, +therefore it can be used to create both multi-impl and single-impl +packages. It provides full set of default phase functions, making +writing ebuilds much easier.</p> +</section> +<section id="a-rule-of-thumb"> +<h2>A rule of thumb<a class="headerlink" href="#a-rule-of-thumb" title="Permalink to this headline">¶</a></h2> +<p>As a rule of thumb, the following checklist can be used to determine +the eclass to use:</p> +<ol class="arabic simple"> +<li><p>If the package has <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> or <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> file, +use <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code>.</p></li> +<li><p>If the package primarily installs Python modules or extensions +or has multi-impl reverse dependencies, use <code class="docutils literal notranslate"><span class="pre">python-r1</span></code>.</p></li> +<li><p>If the package (possibly conditionally) qualifies as using Python +at runtime, use <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code>.</p></li> +<li><p>If the package uses Python at build time only, use <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code>.</p></li> +</ol> +</section> +<section id="python-utils-r1"> +<h2>python-utils-r1<a class="headerlink" href="#python-utils-r1" title="Permalink to this headline">¶</a></h2> +<p>Besides the aforementioned eclasses, the suite includes a common utility +eclass <code class="docutils literal notranslate"><span class="pre">python-utils-r1</span></code>. This eclass is inherited by all other +eclasses, and it is considered to be a part of their API. Therefore, +it must not be inherited directly if any other of the eclasses +is inherited.</p> +<p>The only case for direct inherit of <code class="docutils literal notranslate"><span class="pre">python-utils-r1</span></code> is when you +are only using some of its utility functions without inheriting +any of the remaining eclasses. However, note that the majority of those +utility functions actually rely on mechanics provided by these eclasses +and are not suitable for being used otherwise.</p> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Choosing between Python eclasses</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#build-time-vs-runtime-use">Build-time vs runtime use</a></li> +<li class="toctree-l2"><a class="reference internal" href="#single-impl-vs-multi-impl">Single-impl vs multi-impl</a></li> +<li class="toctree-l2"><a class="reference internal" href="#distutils-and-related-build-systems">Distutils and related build systems</a></li> +<li class="toctree-l2"><a class="reference internal" href="#a-rule-of-thumb">A rule of thumb</a></li> +<li class="toctree-l2"><a class="reference internal" href="#python-utils-r1">python-utils-r1</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="interpreter.html" title="previous chapter">Python interpreters</a></li> + <li>Next: <a href="basic.html" title="next chapter">Common basics</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/eclass.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/expert-multi.html b/guide/expert-multi.html new file mode 100644 index 0000000..31e75ca --- /dev/null +++ b/guide/expert-multi.html @@ -0,0 +1,642 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Expert python-r1 usage — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Integration with build systems written in Python" href="buildsys.html" /> + <link rel="prev" title="Advanced concepts" href="concept.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="expert-python-r1-usage"> +<h1>Expert python-r1 usage<a class="headerlink" href="#expert-python-r1-usage" title="Permalink to this headline">¶</a></h1> +<p>The APIs described in this chapter are powerful but even harder to use +than those described in <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> chapter. You should not consider +using them unless you have a proper ninja training.</p> +<section id="partially-restricting-python-implementation"> +<span id="index-0"></span><h2>Partially restricting Python implementation<a class="headerlink" href="#partially-restricting-python-implementation" title="Permalink to this headline">¶</a></h2> +<p>There are packages that have been ported to Python 3 only partially. +They may still have some optional dependencies that support Python 2 +only, they may have some components that do not support Python 3 yet. +The opposite is also possible — some of the features being available +only for Python 3.</p> +<p>There are two approaches to this problem. You can either skip features +(ignore USE flags) if the necessary implementation is not enabled, +or you can use <code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code> to enforce at least one interpreter +having the requested feature.</p> +<p>Skipping specific tasks can be done via investigating <code class="docutils literal notranslate"><span class="pre">${EPYTHON}</span></code>. +If USE flags are involved, you will probably also need to use +<code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> with additional parameters restricting +dependencies to available targets.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> pypy<span class="o">{</span>,3<span class="o">}</span> <span class="o">)</span> + <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"threads(+)"</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"HTTP library for human beings"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"http://python-requests.org/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://pypi/</span><span class="si">${</span><span class="nv">P</span><span class="p">:</span><span class="nv">0</span><span class="p">:</span><span class="nv">1</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"Apache-2.0"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm ~arm64 ~sparc ~x86 ~amd64-linux ~x86-linux"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"socks5 +ssl test"</span> + <span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=dev-python/certifi-2017.4.17[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/chardet-3.0.2[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> <dev-python/chardet-4[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/idna-2.5[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> <dev-python/idna-3[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> <dev-python/urllib3-1.26[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> socks5? ( >=dev-python/PySocks-1.5.6[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">] )</span> +<span class="s2"> ssl? (</span> +<span class="s2"> >=dev-python/cryptography-1.3.4[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/pyopenssl-0.14[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> )</span> +<span class="s2"> "</span> + + <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> dev-python/setuptools[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> test? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> ${RDEPEND}</span> +</span><span class="hll"><span class="s1"> dev-python/pytest[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/pytest-httpbin[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/pytest-mock[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> >=dev-python/PySocks-1.5.6[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span> <span class="s1">'python*'</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )</span> +<span class="s2"> "</span> + + python_test<span class="o">()</span> <span class="o">{</span> + <span class="c1"># tests hang with pypy & pypy3</span> +<span class="hll"> <span class="o">[[</span> <span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span> <span class="o">==</span> pypy* <span class="o">]]</span> <span class="o">&&</span> <span class="k">continue</span> +</span> + epytest + <span class="o">}</span> +</pre></div> +</div> +<p>Enforcing implementations is done via putting <code class="docutils literal notranslate"><span class="pre">||</span></code> block with all +targets providing the feature in <code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code>. The eclass provides +<code class="docutils literal notranslate"><span class="pre">python_gen_useflags</span></code> function to print valid flag names for specified +implementation list. Please always use this function instead of listing +actual flag names as it handled phasing implementations out gracefully. +<code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> should also be called with matching target +list.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> <span class="o">)</span> + <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"sqlite"</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Toolkit to convert between many translation formats"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://github.com/translate/translate"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/translate/translate/releases/download/</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"amd64 arm64 x86 ~amd64-linux ~x86-linux"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"+subtitles"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"></span> +<span class="hll"><span class="s2"> subtitles? ( || ( </span><span class="k">$(</span>python_gen_useflags python3_<span class="o">{</span><span class="m">6</span>,7<span class="o">}</span><span class="k">)</span><span class="s2"> ) )"</span> +</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">">=dev-python/six-1.10.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">DEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> !dev-python/pydiff</span> +<span class="s2"> app-text/iso-codes</span> +<span class="s2"> >=dev-python/chardet-3.0.4[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/lxml-3.5[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/pycountry-18.5.26[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> >=dev-python/python-levenshtein-0.12.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> sys-devel/gettext</span> +<span class="s2"> subtitles? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> media-video/gaupol[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span> python3_<span class="o">{</span><span class="m">6</span>,7<span class="o">}</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )</span> +<span class="s2"> "</span> +</pre></div> +</div> +<span class="target" id="index-1"></span></section> +<section id="restricting-interpreters-for-python-setup"> +<span id="index-2"></span><h2>Restricting interpreters for python_setup<a class="headerlink" href="#restricting-interpreters-for-python-setup" title="Permalink to this headline">¶</a></h2> +<p>A specific case of the restriction described above is when the build +step supports a subset of Python targets for the runtime part. This +could happen e.g. if package’s Python bindings have been ported +to Python 3 but the test suite or building tooling still requires +Python 2.</p> +<p>To support this use case, <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> can optionally take a list +of implementations. This list must be a subset of <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code>, +and only implementation on the list can be used by <code class="docutils literal notranslate"><span class="pre">python_setup</span></code>. +Note that you also need to set matching <code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code>, as otherwise +the function will fail if the user does not enable any of the supported +targets.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_<span class="o">{</span><span class="m">5</span>,6,7<span class="o">}</span> <span class="o">)</span> + + inherit python-r1 toolchain-funcs + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Python extension module generator for C and C++ libraries"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://www.riverbankcomputing.com/software/sip/intro"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://www.riverbankcomputing.com/static/Downloads/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="c1"># Sub-slot based on SIP_API_MAJOR_NR from siplib/sip.h</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0/12"</span> + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"|| ( GPL-2 GPL-3 SIP )"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"alpha amd64 arm arm64 ~hppa ia64 ppc ppc64 ~sparc x86 ~amd64-linux ~x86-linux ~ppc-macos ~x64-macos ~x86-macos"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"></span> +<span class="hll"><span class="s2"> || ( </span><span class="k">$(</span>python_gen_useflags <span class="s1">'python2*'</span><span class="k">)</span><span class="s2"> )"</span> +</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2">"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> sys-devel/bison</span> +<span class="s2"> sys-devel/flex</span> + +<span class="s2"> src_prepare() {</span> +<span class="hll"><span class="s2"> python_setup 'python2*'</span> +</span><span class="s2"> "</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">" build.py prepare || die</span> +<span class="s2"> default</span> +<span class="s2"> }</span> + +<span class="s2"> src_configure() {</span> +<span class="s2"> configuration() {</span> +<span class="s2"> local myconf=(</span> +<span class="s2"> "</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">"</span> +<span class="s2"> "</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span><span class="s2">"/configure.py</span> +<span class="s2"> --bindir="</span><span class="si">${</span><span class="nv">EPREFIX</span><span class="si">}</span>/usr/bin<span class="s2">"</span> +<span class="s2"> --destdir="</span><span class="k">$(</span>python_get_sitedir<span class="k">)</span><span class="s2">"</span> +<span class="s2"> --incdir="</span><span class="k">$(</span>python_get_includedir<span class="k">)</span><span class="s2">"</span> +<span class="s2"> )</span> +<span class="s2"> echo "</span><span class="si">${</span><span class="nv">myconf</span><span class="p">[@]</span><span class="si">}</span><span class="s2">"</span> +<span class="s2"> "</span><span class="si">${</span><span class="nv">myconf</span><span class="p">[@]</span><span class="si">}</span><span class="s2">" || die</span> +<span class="s2"> }</span> +<span class="s2"> python_foreach_impl run_in_build_dir configuration</span> +<span class="s2"> }</span> + +<span class="s2"> src_compile() {</span> +<span class="s2"> python_foreach_impl run_in_build_dir default</span> +<span class="s2"> }</span> + +<span class="s2"> src_install() {</span> +<span class="s2"> installation() {</span> +<span class="s2"> emake DESTDIR="</span><span class="si">${</span><span class="nv">D</span><span class="si">}</span><span class="s2">" install</span> +<span class="s2"> python_optimize</span> +<span class="s2"> }</span> +<span class="s2"> python_foreach_impl run_in_build_dir installation</span> + +<span class="s2"> einstalldocs</span> +<span class="s2"> }</span> +</pre></div> +</div> +<p>The <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> equivalent of <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> parameters is +the <code class="docutils literal notranslate"><span class="pre">DISTUTILS_ALL_SUBPHASE_IMPLS</span></code> variable. Alternatively to global +scope, it can be set in an early phase function (prior to any sub-phase +call).</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">5</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> + pypy + python3_5 python3_6 python3_7 + python2_7 + <span class="o">)</span> + <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s1">'bzip2(+),ssl(+),threads(+)'</span> + inherit distutils-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Portage is the package management and distribution system for Gentoo"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://wiki.gentoo.org/wiki/Project:Portage"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://gentoo/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.bz2"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~riscv ~s390 ~sh ~sparc ~x86"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"epydoc"</span> +<span class="hll"> <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"epydoc? ( </span><span class="k">$(</span>python_gen_useflags <span class="s1">'python2*'</span><span class="k">)</span><span class="s2"> )"</span> +</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=app-arch/tar-1.27</span> +<span class="s2"> >=sys-apps/sed-4.0.5 sys-devel/patch</span> +<span class="s2"> epydoc? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> >=dev-python/epydoc-2.0[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span> <span class="s1">'python2*'</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )"</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=app-arch/tar-1.27</span> +<span class="s2"> dev-lang/python-exec:2</span> +<span class="s2"> >=sys-apps/sed-4.0.5</span> +<span class="s2"> app-shells/bash:0[readline]</span> +<span class="s2"> >=app-admin/eselect-1.2</span> +<span class="s2"> elibc_glibc? ( >=sys-apps/sandbox-2.2 )</span> +<span class="s2"> kernel_linux? ( sys-apps/util-linux )</span> +<span class="s2"> >=app-misc/pax-utils-0.1.17"</span> + <span class="nv">PDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=net-misc/rsync-2.6.4</span> +<span class="s2"> userland_GNU? ( >=sys-apps/coreutils-6.4 )"</span> + + pkg_setup<span class="o">()</span> <span class="o">{</span> +<span class="hll"> use epydoc <span class="o">&&</span> <span class="nv">DISTUTILS_ALL_SUBPHASE_IMPLS</span><span class="o">=(</span> python2.7 <span class="o">)</span> +</span> <span class="o">}</span> + + python_compile_all<span class="o">()</span> <span class="o">{</span> + <span class="k">if</span> use epydoc<span class="p">;</span> <span class="k">then</span> + esetup.py epydoc + <span class="k">fi</span> + <span class="o">}</span> +</pre></div> +</div> +<p>Note that when the restriction is caused by dependencies rather than +package’s files, the any-r1 API described below is preferable to this.</p> +<span class="target" id="index-3"></span></section> +<section id="disjoint-build-dependencies-any-r1-api"> +<span id="index-4"></span><h2>Disjoint build dependencies (any-r1 API)<a class="headerlink" href="#disjoint-build-dependencies-any-r1-api" title="Permalink to this headline">¶</a></h2> +<p>Some packages have disjoint sets of runtime and pure build-time +dependencies. The former need to be built for all enabled +implementations, the latter only for one of them. The any-r1 API +in <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> is specifically suited for expressing that.</p> +<p>Let’s consider an example package that uses Sphinx with a plugin +to build documentation. Naturally, you’re going to build the documents +only once, not separately for every enabled target.</p> +<section id="using-regular-python-r1-api"> +<h3>Using regular python-r1 API<a class="headerlink" href="#using-regular-python-r1-api" title="Permalink to this headline">¶</a></h3> +<p>If you were using the regular API, you’d have to use +<code class="docutils literal notranslate"><span class="pre">${PYTHON_USEDEP}</span></code> on the dependencies. The resulting code could look +like the following:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> doc? (</span> +<span class="s2"> dev-python/sphinx[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> dev-python/sphinx_rtd_theme[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> )"</span> + +src_compile<span class="o">()</span> <span class="o">{</span> + ... + + <span class="k">if</span> use doc<span class="p">;</span> <span class="k">then</span> + python_setup + emake -C docs html + <span class="k">fi</span> +<span class="o">}</span> +</pre></div> +</div> +<p>If your package is built with support for Python 3.6, 3.7 and 3.8, +then this dependency string will enforce the same targets for Sphinx +and the theme. However, in practice it will only be used through +Python 3.8. Normally, this is not such a big deal.</p> +<p>Now imagine your package supports Python 2.7 as well, while Sphinx +does not anymore. This means that your package will force downgrade +to the old version of <code class="docutils literal notranslate"><span class="pre">dev-python/sphinx</span></code> even though it will not +be used via Python 2.7 at all.</p> +</section> +<section id="using-any-r1-api-with-python-r1"> +<h3>Using any-r1 API with python-r1<a class="headerlink" href="#using-any-r1-api-with-python-r1" title="Permalink to this headline">¶</a></h3> +<p>As the name suggests, the any-r1 API resembles the API used +by <code class="docutils literal notranslate"><span class="pre">python-any-r1</span></code> eclass. The disjoint build-time dependencies +are declared using <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code>, and need to be tested +via <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code> function. The presence of the latter +function activates the alternate behavior of <code class="docutils literal notranslate"><span class="pre">python_setup</span></code>. Instead +of selecting one of the enabled targets, it will run it to verify +installed dependencies and use one having all dependencies satisfied.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> doc? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> dev-python/sphinx[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx_rtd_theme[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + src_compile<span class="o">()</span> <span class="o">{</span> + ... + + <span class="k">if</span> use doc<span class="p">;</span> <span class="k">then</span> +<span class="hll"> python_setup +</span> emake -C docs html + <span class="k">fi</span> + <span class="o">}</span> +</pre></div> +</div> +<p>Note that <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> may select an implementation that is not even +enabled via <code class="docutils literal notranslate"><span class="pre">PYTHON_TARGETS</span></code>. The goal is to try hard to avoid +requiring user to change USE flags on dependencies if possible.</p> +<p>An interesting side effect of that is that the supported targets +in the dependencies can be a subset of the one in package. For example, +we have used this API to add Python 3.8 support to packages before +<code class="docutils literal notranslate"><span class="pre">dev-python/sphinx</span></code> supported it — the eclass implicitly forced using +another implementation for Sphinx.</p> +</section> +<section id="different-sets-of-build-time-dependencies"> +<h3>Different sets of build-time dependencies<a class="headerlink" href="#different-sets-of-build-time-dependencies" title="Permalink to this headline">¶</a></h3> +<p>Let’s consider the case when Python is used at build-time for something +else still. In that case, we want <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> to work +unconditionally but enforce dependencies only with <code class="docutils literal notranslate"><span class="pre">doc</span></code> flag enabled.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> doc? (</span> +<span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +<span class="s1"> dev-python/sphinx[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}]</span> +<span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +<span class="s2"> )"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> use doc <span class="o">||</span> <span class="k">return</span> <span class="m">0</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx_rtd_theme[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + src_compile<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_setup +</span> + ... + + use doc <span class="o">&&</span> emake -C docs html + <span class="o">}</span> +</pre></div> +</div> +<p>Note that <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> behaves according to the any-r1 API here. +While it will not enforce doc dependencies with <code class="docutils literal notranslate"><span class="pre">doc</span></code> flag disabled, +it will use <em>any</em> interpreter that is supported and installed, even +if it is not enabled explicitly in <code class="docutils literal notranslate"><span class="pre">PYTHON_TARGETS</span></code>.</p> +</section> +<section id="using-any-r1-api-with-distutils-r1"> +<h3>Using any-r1 API with distutils-r1<a class="headerlink" href="#using-any-r1-api-with-distutils-r1" title="Permalink to this headline">¶</a></h3> +<p>The alternate build dependency API also integrates with <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> +eclass. If <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code> is declared, the <code class="docutils literal notranslate"><span class="pre">python_*_all()</span></code> +sub-phase functions are called with the interpreter selected according +to any-r1 rules.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> doc? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> dev-python/sphinx[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> dev-python/sphinx_rtd_theme[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> use doc <span class="o">||</span> <span class="k">return</span> <span class="m">0</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> <span class="o">&&</span> +</span><span class="hll"> has_version <span class="s2">"dev-python/sphinx_rtd_theme[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + python_compile_all<span class="o">()</span> <span class="o">{</span> + use doc <span class="o">&&</span> emake -C docs html + <span class="o">}</span> +</pre></div> +</div> +<p>Note that <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> calls <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> unconditionally, +therefore <code class="docutils literal notranslate"><span class="pre">python_check_deps()</span></code> needs to account for that.</p> +<p>Normally you won’t have to use this API for Sphinx though — +<code class="docutils literal notranslate"><span class="pre">distutils_enable_sphinx</span></code> does precisely that for you.</p> +</section> +</section> +<section id="combining-any-r1-api-with-implementation-restrictions"> +<h2>Combining any-r1 API with implementation restrictions<a class="headerlink" href="#combining-any-r1-api-with-implementation-restrictions" title="Permalink to this headline">¶</a></h2> +<p>Both APIs described above can be combined. This can be used when +build-time scripts support a subset of implementations supported +by the package itself, and by its build-time dependencies. For example, +if the package uses <code class="docutils literal notranslate"><span class="pre">dev-util/scons</span></code> build system with <code class="docutils literal notranslate"><span class="pre">SConstruct</span></code> +files using Python 2 construct.</p> +<p>There are two approaches to achieve that: either the build-time +implementation list needs to be passed to <code class="docutils literal notranslate"><span class="pre">python_setup</span></code>, +or <code class="docutils literal notranslate"><span class="pre">python_check_deps</span></code> needs to explicitly reject unsupported targets. +In both cases, a matching implementation list needs to be passed +to <code class="docutils literal notranslate"><span class="pre">python_gen_any_dep</span></code>.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_6 <span class="o">)</span> + inherit python-r1 toolchain-funcs + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"GPS daemon and library for USB/serial GPS devices and GPS/mapping clients"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://gpsd.gitlab.io/gpsd/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://nongnu/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0/24"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm ~ppc ~ppc64 ~sparc ~x86"</span> + + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"python"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"> )"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=net-misc/pps-tools-0.0.20120407</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'>=dev-util/scons-2.3.0[${PYTHON_USEDEP}]'</span> -2<span class="k">)</span><span class="s2"></span> +</span><span class="s2"> virtual/pkgconfig"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> has_version <span class="s2">">=dev-util/scons-2.3.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nv">myesconsargs</span><span class="o">=(</span> + <span class="nv">prefix</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">EPREFIX</span><span class="si">}</span><span class="s2">/usr"</span> + <span class="nv">libdir</span><span class="o">=</span><span class="s2">"\$prefix/</span><span class="k">$(</span>get_libdir<span class="k">)</span><span class="s2">"</span> + <span class="nv">udevdir</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>get_udevdir<span class="k">)</span><span class="s2">"</span> + <span class="nv">chrpath</span><span class="o">=</span>False + <span class="nv">gpsd_user</span><span class="o">=</span>gpsd + <span class="nv">gpsd_group</span><span class="o">=</span>uucp + <span class="nv">nostrip</span><span class="o">=</span>True + <span class="nv">manbuild</span><span class="o">=</span>False + <span class="k">$(</span>use_scons python<span class="k">)</span> + <span class="o">)</span> + + <span class="c1"># SConstruct uses py2 constructs</span> +<span class="hll"> python_setup -2 +</span> <span class="o">}</span> +</pre></div> +</div> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 python3_6 <span class="o">)</span> + inherit python-r1 toolchain-funcs + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"GPS daemon and library for USB/serial GPS devices and GPS/mapping clients"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://gpsd.gitlab.io/gpsd/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://nongnu/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0/24"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~arm ~ppc ~ppc64 ~sparc ~x86"</span> + + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"python"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"> )"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> >=net-misc/pps-tools-0.0.20120407</span> +<span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_any_dep <span class="s1">'>=dev-util/scons-2.3.0[${PYTHON_USEDEP}]'</span> -2<span class="k">)</span><span class="s2"></span> +</span><span class="s2"> virtual/pkgconfig"</span> + +<span class="hll"> python_check_deps<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> python_is_python3 <span class="o">&&</span> <span class="k">return</span> <span class="m">1</span> +</span><span class="hll"> has_version <span class="s2">">=dev-util/scons-2.3.0[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]"</span> +</span><span class="hll"> <span class="o">}</span> +</span> + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nv">myesconsargs</span><span class="o">=(</span> + <span class="nv">prefix</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">EPREFIX</span><span class="si">}</span><span class="s2">/usr"</span> + <span class="nv">libdir</span><span class="o">=</span><span class="s2">"\$prefix/</span><span class="k">$(</span>get_libdir<span class="k">)</span><span class="s2">"</span> + <span class="nv">udevdir</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>get_udevdir<span class="k">)</span><span class="s2">"</span> + <span class="nv">chrpath</span><span class="o">=</span>False + <span class="nv">gpsd_user</span><span class="o">=</span>gpsd + <span class="nv">gpsd_group</span><span class="o">=</span>uucp + <span class="nv">nostrip</span><span class="o">=</span>True + <span class="nv">manbuild</span><span class="o">=</span>False + <span class="k">$(</span>use_scons python<span class="k">)</span> + <span class="o">)</span> + +<span class="hll"> python_setup +</span> <span class="o">}</span> +</pre></div> +</div> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Expert python-r1 usage</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#partially-restricting-python-implementation">Partially restricting Python implementation</a></li> +<li class="toctree-l2"><a class="reference internal" href="#restricting-interpreters-for-python-setup">Restricting interpreters for python_setup</a></li> +<li class="toctree-l2"><a class="reference internal" href="#disjoint-build-dependencies-any-r1-api">Disjoint build dependencies (any-r1 API)</a></li> +<li class="toctree-l2"><a class="reference internal" href="#combining-any-r1-api-with-implementation-restrictions">Combining any-r1 API with implementation restrictions</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="concept.html" title="previous chapter">Advanced concepts</a></li> + <li>Next: <a href="buildsys.html" title="next chapter">Integration with build systems written in Python</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/expert-multi.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/genindex.html b/guide/genindex.html new file mode 100644 index 0000000..eb5f8e8 --- /dev/null +++ b/guide/genindex.html @@ -0,0 +1,331 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Index — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="#" /> + <link rel="search" title="Search" href="search.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + +<h1 id="index">Index</h1> + +<div class="genindex-jumpbox"> + <a href="#C"><strong>C</strong></a> + | <a href="#D"><strong>D</strong></a> + | <a href="#E"><strong>E</strong></a> + | <a href="#G"><strong>G</strong></a> + | <a href="#P"><strong>P</strong></a> + | <a href="#R"><strong>R</strong></a> + | <a href="#S"><strong>S</strong></a> + +</div> +<h2 id="C">C</h2> +<table style="width: 100%" class="indextable genindextable"><tr> + <td style="width: 33%; vertical-align: top;"><ul> + <li><a href="depend.html#index-3">cffi</a> +</li> + </ul></td> +</tr></table> + +<h2 id="D">D</h2> +<table style="width: 100%" class="indextable genindextable"><tr> + <td style="width: 33%; vertical-align: top;"><ul> + <li><a href="expert-multi.html#index-2">DISTUTILS_ALL_SUBPHASE_IMPLS</a> +</li> + <li><a href="distutils.html#index-16">distutils_enable_sphinx</a> +</li> + <li><a href="distutils.html#index-14">distutils_enable_tests</a> +</li> + <li><a href="distutils-legacy.html#index-1">DISTUTILS_IN_SOURCE_BUILD</a> +</li> + </ul></td> + <td style="width: 33%; vertical-align: top;"><ul> + <li><a href="distutils-legacy.html#index-2">distutils_install_for_testing</a> +</li> + <li><a href="distutils.html#index-0">DISTUTILS_SINGLE_IMPL</a> +</li> + <li><a href="distutils.html#index-1">DISTUTILS_USE_PEP517</a> +</li> + <li><a href="distutils-legacy.html#index-0">DISTUTILS_USE_SETUPTOOLS</a> +</li> + </ul></td> +</tr></table> + +<h2 id="E">E</h2> +<table style="width: 100%" class="indextable genindextable"><tr> + <td style="width: 33%; vertical-align: top;"><ul> + <li><a href="migration.html#index-1">EAPI 8</a> +</li> + <li><a href="distutils.html#index-15">epytest</a> +</li> + </ul></td> + <td style="width: 33%; vertical-align: top;"><ul> + <li><a href="basic.html#index-3">EPYTHON</a> +</li> + <li><a href="distutils.html#index-13">esetup.py</a> +</li> + </ul></td> +</tr></table> + +<h2 id="G">G</h2> +<table style="width: 100%" class="indextable genindextable"><tr> + <td style="width: 33%; vertical-align: top;"><ul> + <li><a href="depend.html#index-3">greenlet</a> +</li> + </ul></td> +</tr></table> + +<h2 id="P">P</h2> +<table style="width: 100%" class="indextable genindextable"><tr> + <td style="width: 33%; vertical-align: top;"><ul> + <li><a href="basic.html#index-4">PYTHON</a> +</li> + <li> + python_check_deps + + <ul> + <li><a href="any.html#index-1">python-any-r1</a> +</li> + <li><a href="expert-multi.html#index-4">python-r1</a> +</li> + </ul></li> + <li><a href="basic.html#index-0">PYTHON_COMPAT</a> +</li> + <li><a href="distutils.html#index-7">python_compile</a> +</li> + <li><a href="distutils.html#index-8">python_compile_all</a> +</li> + <li><a href="distutils.html#index-5">python_configure</a> +</li> + <li><a href="distutils.html#index-6">python_configure_all</a> +</li> + <li><a href="basic.html#index-1">PYTHON_DEPS</a> +</li> + <li><a href="helper.html#index-0">python_doexe</a> +</li> + <li><a href="helper.html#index-5">python_doheaders</a> +</li> + <li><a href="helper.html#index-4">python_domodule</a> +</li> + <li><a href="helper.html#index-2">python_doscript</a> +</li> + <li><a href="helper.html#index-8">python_fix_shebang</a> +</li> + <li><a href="multi.html#index-0">python_foreach_impl</a> +</li> + <li> + python_gen_any_dep + + <ul> + <li><a href="any.html#index-0">python-any-r1</a> +</li> + <li><a href="expert-multi.html#index-3">python-r1</a> +</li> + </ul></li> + <li> + python_gen_cond_dep + + <ul> + <li><a href="depend.html#index-2">for conditional deps</a> +</li> + <li><a href="single.html#index-2">for python-single-r1</a> +</li> + </ul></li> + <li><a href="depend.html#index-1">python_gen_impl_dep</a> +</li> + <li><a href="expert-multi.html#index-0">python_gen_useflags</a> +</li> + <li><a href="helper.html#index-14">python_get_CFLAGS</a> +</li> + <li><a href="helper.html#index-11">python_get_includedir</a> +</li> + </ul></td> + <td style="width: 33%; vertical-align: top;"><ul> + <li><a href="helper.html#index-13">python_get_library_path</a> +</li> + <li><a href="helper.html#index-15">python_get_LIBS</a> +</li> + <li><a href="helper.html#index-16">python_get_PYTHON_CONFIG</a> +</li> + <li><a href="helper.html#index-12">python_get_scriptdir</a> +</li> + <li><a href="helper.html#index-10">python_get_sitedir</a> +</li> + <li><a href="distutils.html#index-11">python_install</a> +</li> + <li><a href="distutils.html#index-12">python_install_all</a> +</li> + <li><a href="helper.html#index-7">python_moduleinto</a> +</li> + <li><a href="migration.html#index-0">PYTHON_MULTI_USEDEP</a> +</li> + <li><a href="helper.html#index-1">python_newexe</a> +</li> + <li><a href="helper.html#index-3">python_newscript</a> +</li> + <li><a href="helper.html#index-9">python_optimize</a> +</li> + <li><a href="distutils.html#index-3">python_prepare</a> +</li> + <li><a href="distutils.html#index-4">python_prepare_all</a> +</li> + <li><a href="depend.html#index-0">PYTHON_REQ_USE</a> +</li> + <li><a href="basic.html#index-2">PYTHON_REQUIRED_USE</a> +</li> + <li><a href="helper.html#index-6">python_scriptinto</a> +</li> + <li> + python_setup + + <ul> + <li><a href="multi.html#index-3">for python-r1</a> +</li> + <li><a href="expert-multi.html#index-1">with implementation parameter</a> +</li> + </ul></li> + <li><a href="single.html#index-0">PYTHON_SINGLE_USEDEP</a> +</li> + <li><a href="distutils.html#index-9">python_test</a> +</li> + <li><a href="distutils.html#index-10">python_test_all</a> +</li> + <li> + PYTHON_USEDEP + + <ul> + <li><a href="any.html#index-2">python-any-r1</a> +</li> + <li><a href="multi.html#index-1">python-r1</a> +</li> + <li><a href="single.html#index-1">python-single-r1</a> +</li> + </ul></li> + </ul></td> +</tr></table> + +<h2 id="R">R</h2> +<table style="width: 100%" class="indextable genindextable"><tr> + <td style="width: 33%; vertical-align: top;"><ul> + <li><a href="multi.html#index-2">run_in_build_dir</a> +</li> + </ul></td> +</tr></table> + +<h2 id="S">S</h2> +<table style="width: 100%" class="indextable genindextable"><tr> + <td style="width: 33%; vertical-align: top;"><ul> + <li><a href="distutils.html#index-2">SETUPTOOLS_SCM_PRETEND_VERSION</a> +</li> + </ul></td> +</tr></table> + + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/helper.html b/guide/helper.html new file mode 100644 index 0000000..83ec7d9 --- /dev/null +++ b/guide/helper.html @@ -0,0 +1,351 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Common helper functions — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Advanced dependencies" href="depend.html" /> + <link rel="prev" title="distutils-r1 legacy concepts" href="distutils-legacy.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="common-helper-functions"> +<h1>Common helper functions<a class="headerlink" href="#common-helper-functions" title="Permalink to this headline">¶</a></h1> +<p>The functions described in this chapter are common to all three basic +eclasses. To facilitate code reuse, they are declared +in <code class="docutils literal notranslate"><span class="pre">python-utils-r1.eclass</span></code>. However, you should not inherit this +eclass directly and instead assume the functions are provided as part +of the API of other eclasses.</p> +<p>Eclass reference: <a class="reference external" href="https://devmanual.gentoo.org/eclass-reference/python-utils-r1.eclass/index.html">python-utils-r1.eclass(5)</a></p> +<span class="target" id="index-0"></span><span class="target" id="index-1"></span><span class="target" id="index-2"></span><span class="target" id="index-3"></span><span class="target" id="index-4"></span><span class="target" id="index-5"></span><span class="target" id="index-6"></span><section id="install-helpers"> +<span id="index-7"></span><h2>Install helpers<a class="headerlink" href="#install-helpers" title="Permalink to this headline">¶</a></h2> +<p>The install helpers are provided commonly for <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> +and <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> eclasses. Their main purpose is to facilitate +installing Python scripts, modules and extensions whenever the package +lacks a build system or the build system is not suited for installing +them.</p> +<p>The API is consistent with the standard <code class="docutils literal notranslate"><span class="pre">do*</span></code>, <code class="docutils literal notranslate"><span class="pre">new*</span></code> and <code class="docutils literal notranslate"><span class="pre">*into</span></code> +helpers. There are four kinds of functions provided:</p> +<ol class="arabic simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">python_doexe</span></code> and <code class="docutils literal notranslate"><span class="pre">python_newexe</span></code> that install executables +wrapping them via python-exec,</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_doscript</span></code> and <code class="docutils literal notranslate"><span class="pre">python_newscript</span></code> that install Python +scripts, updating the shebangs and wrapping them via python-exec,</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_domodule</span></code> that installs Python modules, or recursively +installs packages (directories),</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_doheader</span></code> that installs header files to Python-specific +include directory.</p></li> +</ol> +<p>The install path for executables and scripts (1. and 2.) can be adjusted +by calling <code class="docutils literal notranslate"><span class="pre">python_scriptinto</span></code>. Note that this actually affects only +the wrapper symlink install path; the actual scripts will be installed +in the standard python-exec script directories. This also implies that +no two executables can have the same name, even if final directory is +different. The default install path is <code class="docutils literal notranslate"><span class="pre">/usr/bin</span></code>.</p> +<p>The install path for modules and packages (3.) can be adjusted +by calling <code class="docutils literal notranslate"><span class="pre">python_moduleinto</span></code>. This function accepts either absolute +path or Python parent module name that causes modules to be installed +in an appropriate subdirectory of the site-packages directory. +The default install path is top-level site-packages (equivalent +to <code class="docutils literal notranslate"><span class="pre">python_moduleinto</span> <span class="pre">.</span></code>).</p> +<p>The install path for headers (4.) cannot be adjusted.</p> +<p><code class="docutils literal notranslate"><span class="pre">python_doexe</span></code> is generally used to install executables that reference +Python but are not Python scripts. This could be e.g. a bash script +that calls Python:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make_wrapper</span> <span class="s2">"$</span><span class="si">{PN}</span><span class="s2">.tmp"</span> <span class="s2">"$</span><span class="si">{EPYTHON}</span><span class="s2"> $(python_get_sitedir)/$</span><span class="si">{PN}</span><span class="s2">/cropgtk.py"</span> +<span class="n">python_newexe</span> <span class="s2">"${ED%/}/usr/bin/$</span><span class="si">{PN}</span><span class="s2">.tmp"</span> <span class="s2">"$</span><span class="si">{PN}</span><span class="s2">"</span> +<span class="n">rm</span> <span class="s2">"${ED%/}/usr/bin/$</span><span class="si">{PN}</span><span class="s2">.tmp"</span> <span class="o">||</span> <span class="n">die</span> +</pre></div> +</div> +<p>Note that you need to ensure that the executable calls correct Python +interpreter itself.</p> +<p><code class="docutils literal notranslate"><span class="pre">python_doscript</span></code> is generally used to install Python scripts +to binary directories:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python_scriptinto</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">sbin</span> +<span class="n">python_newscript</span> <span class="n">pynslcd</span><span class="o">.</span><span class="n">py</span> <span class="n">pynslcd</span> +</pre></div> +</div> +<p>It takes care of updating the shebang for you.</p> +<p><code class="docutils literal notranslate"><span class="pre">python_domodule</span></code> is used to install Python modules, extensions, +packages, data files and in general anything that lands in site-packages +directory:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>python_moduleinto ${PN} +python_domodule images application ${MY_PN}.py \ + AUTHORS CHANGES COPYING DEPENDS TODO __init__.py +</pre></div> +</div> +<p>It is roughly equivalent to <code class="docutils literal notranslate"><span class="pre">dodir</span> <span class="pre">-r</span></code>, except that it byte-compiles +all Python modules found inside it.</p> +<p><code class="docutils literal notranslate"><span class="pre">python_doheader</span></code> is used in the very rare cases when Python packages +install additional header files that are used to compile other +extensions:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python_doheader</span> <span class="n">src</span><span class="o">/</span><span class="n">libImaging</span><span class="o">/*.</span><span class="n">h</span> +</pre></div> +</div> +</section> +<section id="fixing-shebangs-on-installed-scripts"> +<span id="index-8"></span><h2>Fixing shebangs on installed scripts<a class="headerlink" href="#fixing-shebangs-on-installed-scripts" title="Permalink to this headline">¶</a></h2> +<p>If upstream build system installs Python scripts, it should also update +their shebangs to match the interpreter used for install. Otherwise, +the scripts could end up being run via another implementation, one +that possible does not have the necessary dependencies installed. +An example of correct shebang is:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python3.8</span> +</pre></div> +</div> +<p>However, if the build system installs a script with <code class="docutils literal notranslate"><span class="pre">python3</span></code> or even +<code class="docutils literal notranslate"><span class="pre">python</span></code> shebang, it needs to be updated. The <code class="docutils literal notranslate"><span class="pre">python_fix_shebang</span></code> +function is provided precisely for that purpose. It can be used to +update the shebang on an installed file:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">src_install</span><span class="p">()</span> <span class="p">{</span> + <span class="n">default</span> + <span class="n">python_fix_shebang</span> <span class="s2">"$</span><span class="si">{D}</span><span class="s2">"</span><span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">sphinxtrain</span> +<span class="p">}</span> +</pre></div> +</div> +<p>It can also be used in working directory to update a script that’s used +at build time or before it is installed:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">src_prepare</span><span class="p">()</span> <span class="p">{</span> + <span class="n">default</span> + <span class="n">python_fix_shebang</span> <span class="n">openvpn</span><span class="o">-</span><span class="n">vulnkey</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Finally, it can also be used on a directory to recursively update +shebangs in all Python scripts found inside it:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">src_install</span><span class="p">()</span> <span class="p">{</span> + <span class="n">insinto</span> <span class="o">/</span><span class="n">usr</span> + <span class="n">doins</span> <span class="o">-</span><span class="n">r</span> <span class="n">linux</span><span class="o">-</span><span class="n">package</span><span class="o">/*</span> + <span class="n">dobin</span> <span class="n">linux</span><span class="o">-</span><span class="n">package</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">kitty</span> + <span class="n">python_fix_shebang</span> <span class="s2">"$</span><span class="si">{ED}</span><span class="s2">"</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Normally, <code class="docutils literal notranslate"><span class="pre">python_fix_shebang</span></code> errors out when the target interpreter +is not compatible with the original shebang, e.g. when you are trying +to install a script with <code class="docutils literal notranslate"><span class="pre">python2</span></code> shebang for Python 3. <code class="docutils literal notranslate"><span class="pre">-f</span></code> +(force) switch can be used to override that:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">src_prepare</span><span class="p">()</span> <span class="p">{</span> + <span class="n">default</span> + <span class="n">python_fix_shebang</span> <span class="o">-</span><span class="n">f</span> <span class="s2">"$</span><span class="si">{PN}</span><span class="s2">.py"</span> +<span class="p">}</span> +</pre></div> +</div> +</section> +<section id="byte-compiling-python-modules"> +<span id="index-9"></span><h2>Byte-compiling Python modules<a class="headerlink" href="#byte-compiling-python-modules" title="Permalink to this headline">¶</a></h2> +<p>Python modules are byte compiled in order to speed up their loading. +Byte-compilation is normally done by the build system when the modules +are installed. However, sometimes packages fail to compile them +entirely, or byte-compile them only partially. Nowadays, QA checks +detect and report that:</p> +<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>* This package installs one or more Python modules that are not byte-compiled. +* The following files are missing: +* +* /usr/lib/pypy2.7/site-packages/_feedparser_sgmllib.pyc +* /usr/lib64/python2.7/site-packages/_feedparser_sgmllib.pyc +* /usr/lib64/python2.7/site-packages/_feedparser_sgmllib.pyo +* +* Please either fix the upstream build system to byte-compile Python modules +* correctly, or call python_optimize after installing them. For more +* information, see: +* https://wiki.gentoo.org/wiki/Project:Python/Byte_compiling +</pre></div> +</div> +<p>The eclass provides a <code class="docutils literal notranslate"><span class="pre">python_optimize</span></code> function to byte-compile +modules. The most common way of using it is to call it after installing +the package to byte-compile all modules installed into site-packages:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">src_install</span><span class="p">()</span> <span class="p">{</span> + <span class="n">cmake_src_install</span> + <span class="n">python_optimize</span> +<span class="p">}</span> +</pre></div> +</div> +<p>If Python scripts are installed to a non-standard directory, the path +to them can be passed to the function:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">src_install</span><span class="p">()</span> <span class="p">{</span> + <span class="n">cd</span> <span class="s2">"$</span><span class="si">{S}</span><span class="s2">"</span><span class="o">/</span><span class="n">client</span> <span class="o">||</span> <span class="n">die</span> + <span class="n">emake</span> <span class="n">DESTDIR</span><span class="o">=</span><span class="s2">"$</span><span class="si">{D}</span><span class="s2">"</span> <span class="n">LIBDIR</span><span class="o">=</span><span class="s2">"usr/lib"</span> <span class="n">install</span> + <span class="n">python_optimize</span> <span class="s2">"$</span><span class="si">{D}</span><span class="s2">/usr/lib/entropy/client"</span> +<span class="p">}</span> +</pre></div> +</div> +<span class="target" id="index-10"></span><span class="target" id="index-11"></span><span class="target" id="index-12"></span><span class="target" id="index-13"></span><span class="target" id="index-14"></span><span class="target" id="index-15"></span></section> +<section id="querying-the-implementation-information"> +<span id="index-16"></span><h2>Querying the implementation information<a class="headerlink" href="#querying-the-implementation-information" title="Permalink to this headline">¶</a></h2> +<p>Most of the time, various build systems manage to detect and query +the Python implementation correctly for necessary build details. +Ocassionally, you need to provide those values or override bad detection +results. For this purpose, the eclasses provide a series of <em>getters</em>.</p> +<p>The following generic getters are provided:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">python_get_sitedir</span></code> that outputs the absolute path to the target’s +site-packages directory (where Python modules are installed).</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_get_includedir</span></code> that outputs the absolute path +to the target-specific header directory.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_get_scriptdir</span></code> that outputs the absolute path +to the python-exec script directory for the implementation.</p></li> +</ul> +<p>The following getters are provided only for CPython targets:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">python_get_library_path</span></code> that outputs the absolute path +to the <code class="docutils literal notranslate"><span class="pre">python</span></code> library.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_get_CFLAGS</span></code> that outputs the C preprocessor flags +for linking against the Python library (equivalent to <code class="docutils literal notranslate"><span class="pre">pkg-config</span> +<span class="pre">--cflags</span> <span class="pre">...</span></code>).</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_get_LIBS</span></code> that outputs the linker flags for linking +against the Python library (equivalent to <code class="docutils literal notranslate"><span class="pre">pkg-config</span> <span class="pre">--libs</span> <span class="pre">...</span></code>).</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_get_PYTHON_CONFIG</span></code> that outputs the absolute path +to the <code class="docutils literal notranslate"><span class="pre">python-config</span></code> executable.</p></li> +</ul> +<p>Note that all paths provided by getters include the offset-prefix +(<code class="docutils literal notranslate"><span class="pre">${EPREFIX}</span></code>) already and they are not suitable to passing +to <code class="docutils literal notranslate"><span class="pre">*into</span></code> helpers. If you need to install something, use <a class="reference internal" href="#install-helpers">install +helpers</a> instead.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nb">local</span> <span class="nv">mycmakeargs</span><span class="o">=(</span> + ... + <span class="o">)</span> + use python <span class="o">&&</span> <span class="nv">mycmakeargs</span><span class="o">+=(</span> + -DPYTHON_DEST<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>python_get_sitedir<span class="k">)</span><span class="s2">"</span> + -DPYTHON_EXECUTABLE<span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON</span><span class="si">}</span><span class="s2">"</span> + -DPYTHON_INCLUDE_DIR<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>python_get_includedir<span class="k">)</span><span class="s2">"</span> + -DPYTHON_LIBRARY<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>python_get_library_path<span class="k">)</span><span class="s2">"</span> + <span class="o">)</span> + + cmake_src_configure +<span class="o">}</span> +</pre></div> +</div> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + <span class="c1"># prepare embedded executable</span> + emake <span class="se">\</span> + <span class="nv">CC</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>tc-getCC<span class="k">)</span><span class="s2">"</span> <span class="se">\</span> + <span class="nv">PYINC</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>python_get_CFLAGS<span class="k">)</span><span class="s2">"</span> <span class="se">\</span> + <span class="nv">PYLIB</span><span class="o">=</span><span class="s2">"</span><span class="k">$(</span>python_get_LIBS<span class="k">)</span><span class="s2">"</span> <span class="se">\</span> + check +<span class="o">}</span> +</pre></div> +</div> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Common helper functions</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#install-helpers">Install helpers</a></li> +<li class="toctree-l2"><a class="reference internal" href="#fixing-shebangs-on-installed-scripts">Fixing shebangs on installed scripts</a></li> +<li class="toctree-l2"><a class="reference internal" href="#byte-compiling-python-modules">Byte-compiling Python modules</a></li> +<li class="toctree-l2"><a class="reference internal" href="#querying-the-implementation-information">Querying the implementation information</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="distutils-legacy.html" title="previous chapter">distutils-r1 legacy concepts</a></li> + <li>Next: <a href="depend.html" title="next chapter">Advanced dependencies</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/helper.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/index.html b/guide/index.html new file mode 100644 index 0000000..55c66a4 --- /dev/null +++ b/guide/index.html @@ -0,0 +1,298 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Gentoo Python Guide — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Preface" href="preface.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="gentoo-python-guide"> +<h1>Gentoo Python Guide<a class="headerlink" href="#gentoo-python-guide" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Author</dt> +<dd class="field-odd"><p>Michał Górny</p> +</dd> +<dt class="field-even">License</dt> +<dd class="field-even"><p><a class="reference external" href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International</a></p> +</dd> +</dl> +<div class="toctree-wrapper compound"> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a><ul> +<li class="toctree-l2"><a class="reference internal" href="interpreter.html#versions-of-python">Versions of Python</a></li> +<li class="toctree-l2"><a class="reference internal" href="interpreter.html#alternative-python-implementations">Alternative Python implementations</a></li> +<li class="toctree-l2"><a class="reference internal" href="interpreter.html#support-for-multiple-implementations">Support for multiple implementations</a></li> +<li class="toctree-l2"><a class="reference internal" href="interpreter.html#backports">Backports</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a><ul> +<li class="toctree-l2"><a class="reference internal" href="eclass.html#build-time-vs-runtime-use">Build-time vs runtime use</a></li> +<li class="toctree-l2"><a class="reference internal" href="eclass.html#single-impl-vs-multi-impl">Single-impl vs multi-impl</a></li> +<li class="toctree-l2"><a class="reference internal" href="eclass.html#distutils-and-related-build-systems">Distutils and related build systems</a></li> +<li class="toctree-l2"><a class="reference internal" href="eclass.html#a-rule-of-thumb">A rule of thumb</a></li> +<li class="toctree-l2"><a class="reference internal" href="eclass.html#python-utils-r1">python-utils-r1</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a><ul> +<li class="toctree-l2"><a class="reference internal" href="basic.html#python-compat">PYTHON_COMPAT</a></li> +<li class="toctree-l2"><a class="reference internal" href="basic.html#python-deps-and-python-required-use">PYTHON_DEPS and PYTHON_REQUIRED_USE</a></li> +<li class="toctree-l2"><a class="reference internal" href="basic.html#python-environment">Python environment</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a><ul> +<li class="toctree-l2"><a class="reference internal" href="any.html#basic-use-for-unconditional-python">Basic use for unconditional Python</a></li> +<li class="toctree-l2"><a class="reference internal" href="any.html#dependencies">Dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="any.html#conditional-python-use">Conditional Python use</a></li> +<li class="toctree-l2"><a class="reference internal" href="any.html#additional-conditional-dependencies">Additional conditional dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="any.html#multiple-sets-of-conditional-dependencies">Multiple sets of conditional dependencies</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a><ul> +<li class="toctree-l2"><a class="reference internal" href="single.html#basic-use-for-unconditional-python">Basic use for unconditional Python</a></li> +<li class="toctree-l2"><a class="reference internal" href="single.html#dependencies">Dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="single.html#conditional-python-use">Conditional Python use</a></li> +<li class="toctree-l2"><a class="reference internal" href="single.html#a-hybrid-build-time-conditional-runtime">A hybrid: build-time + conditional runtime</a></li> +<li class="toctree-l2"><a class="reference internal" href="single.html#multiple-use-conditions">Multiple USE conditions</a></li> +<li class="toctree-l2"><a class="reference internal" href="single.html#manual-install">Manual install</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a><ul> +<li class="toctree-l2"><a class="reference internal" href="multi.html#manual-install">Manual install</a></li> +<li class="toctree-l2"><a class="reference internal" href="multi.html#dependencies">Dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="multi.html#pure-python-autotools-package">Pure Python autotools package</a></li> +<li class="toctree-l2"><a class="reference internal" href="multi.html#conditional-python-use">Conditional Python use</a></li> +<li class="toctree-l2"><a class="reference internal" href="multi.html#additional-build-time-python-use">Additional build-time Python use</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a><ul> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#the-pep-517-and-legacy-modes">The PEP 517 and legacy modes</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#basic-use-pep-517-mode">Basic use (PEP 517 mode)</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#dependencies">Dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#python-single-r1-variant">python-single-r1 variant</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#pep-517-build-systems">PEP 517 build systems</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#deprecated-pep-517-backends">Deprecated PEP 517 backends</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#setuptools-scm-and-snapshots">setuptools_scm and snapshots</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#parallel-build-race-conditions">Parallel build race conditions</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#sub-phase-functions">Sub-phase functions</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#passing-arguments-to-setup-py-commands">Passing arguments to setup.py commands</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#calling-custom-setup-py-commands">Calling custom setup.py commands</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#preventing-test-directory-from-being-installed">Preventing test directory from being installed</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#enabling-tests">Enabling tests</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils.html#building-documentation-via-sphinx">Building documentation via Sphinx</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a><ul> +<li class="toctree-l2"><a class="reference internal" href="distutils-legacy.html#different-build-system-variations">Different build system variations</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils-legacy.html#in-source-vs-out-of-source-builds">In-source vs out-of-source builds</a></li> +<li class="toctree-l2"><a class="reference internal" href="distutils-legacy.html#installing-the-package-before-testing">Installing the package before testing</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a><ul> +<li class="toctree-l2"><a class="reference internal" href="helper.html#install-helpers">Install helpers</a></li> +<li class="toctree-l2"><a class="reference internal" href="helper.html#fixing-shebangs-on-installed-scripts">Fixing shebangs on installed scripts</a></li> +<li class="toctree-l2"><a class="reference internal" href="helper.html#byte-compiling-python-modules">Byte-compiling Python modules</a></li> +<li class="toctree-l2"><a class="reference internal" href="helper.html#querying-the-implementation-information">Querying the implementation information</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a><ul> +<li class="toctree-l2"><a class="reference internal" href="depend.html#requesting-use-flags-on-the-python-interpreter">Requesting USE flags on the Python interpreter</a></li> +<li class="toctree-l2"><a class="reference internal" href="depend.html#dependencies-conditional-to-python-version">Dependencies conditional to Python version</a></li> +<li class="toctree-l2"><a class="reference internal" href="depend.html#dependencies-on-cffi-and-greenlet">Dependencies on CFFI and greenlet</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a><ul> +<li class="toctree-l2"><a class="reference internal" href="test.html#choosing-the-correct-test-runner">Choosing the correct test runner</a></li> +<li class="toctree-l2"><a class="reference internal" href="test.html#missing-test-files-in-pypi-packages">Missing test files in PyPI packages</a></li> +<li class="toctree-l2"><a class="reference internal" href="test.html#checklist-for-dealing-with-test-failures">Checklist for dealing with test failures</a></li> +<li class="toctree-l2"><a class="reference internal" href="test.html#skipping-problematic-tests">Skipping problematic tests</a></li> +<li class="toctree-l2"><a class="reference internal" href="test.html#tests-requiring-internet-access">Tests requiring Internet access</a></li> +<li class="toctree-l2"><a class="reference internal" href="test.html#tests-aborting-due-to-assertions">Tests aborting (due to assertions)</a></li> +<li class="toctree-l2"><a class="reference internal" href="test.html#installing-extra-dependencies-in-test-environment-e-g-example-plugins">Installing extra dependencies in test environment (e.g. example plugins)</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a><ul> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#skipping-tests-based-on-markers">Skipping tests based on markers</a></li> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#skipping-tests-based-on-paths-names">Skipping tests based on paths/names</a></li> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#avoiding-the-dependency-on-pytest-runner">Avoiding the dependency on pytest-runner</a></li> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#using-pytest-xdist-to-run-tests-in-parallel">Using pytest-xdist to run tests in parallel</a></li> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#avoiding-dependencies-on-other-pytest-plugins">Avoiding dependencies on other pytest plugins</a></li> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#explicitly-disabling-automatic-pytest-plugins">Explicitly disabling automatic pytest plugins</a></li> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#expert-disabling-plugin-autoloading-entirely">Expert: disabling plugin autoloading entirely</a></li> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#typeerror-make-test-flaky-got-an-unexpected-keyword-argument-reruns">TypeError: _make_test_flaky() got an unexpected keyword argument ‘reruns’</a></li> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#importpathmismatcherror">ImportPathMismatchError</a></li> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#fixture-not-found">fixture ‘…’ not found</a></li> +<li class="toctree-l2"><a class="reference internal" href="pytest.html#warnings">Warnings</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a><ul> +<li class="toctree-l2"><a class="reference internal" href="concept.html#namespace-packages">Namespace packages</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a><ul> +<li class="toctree-l2"><a class="reference internal" href="expert-multi.html#partially-restricting-python-implementation">Partially restricting Python implementation</a></li> +<li class="toctree-l2"><a class="reference internal" href="expert-multi.html#restricting-interpreters-for-python-setup">Restricting interpreters for python_setup</a></li> +<li class="toctree-l2"><a class="reference internal" href="expert-multi.html#disjoint-build-dependencies-any-r1-api">Disjoint build dependencies (any-r1 API)</a></li> +<li class="toctree-l2"><a class="reference internal" href="expert-multi.html#combining-any-r1-api-with-implementation-restrictions">Combining any-r1 API with implementation restrictions</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a><ul> +<li class="toctree-l2"><a class="reference internal" href="buildsys.html#meson">Meson</a></li> +<li class="toctree-l2"><a class="reference internal" href="buildsys.html#scons">SCons</a></li> +<li class="toctree-l2"><a class="reference internal" href="buildsys.html#waf">waf</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a><ul> +<li class="toctree-l2"><a class="reference internal" href="porting.html#retroactive-changes">Retroactive changes</a></li> +<li class="toctree-l2"><a class="reference internal" href="porting.html#python-3-10">Python 3.10</a></li> +<li class="toctree-l2"><a class="reference internal" href="porting.html#python-3-9">Python 3.9</a></li> +<li class="toctree-l2"><a class="reference internal" href="porting.html#python-3-8">Python 3.8</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a><ul> +<li class="toctree-l2"><a class="reference internal" href="migration.html#migrating-from-old-python-usedep-syntax-in-python-single-r1">Migrating from old PYTHON_USEDEP syntax in python-single-r1</a></li> +<li class="toctree-l2"><a class="reference internal" href="migration.html#migrating-from-eapi-7-to-eapi-8">Migrating from EAPI 7 to EAPI 8</a></li> +<li class="toctree-l2"><a class="reference internal" href="migration.html#migrating-to-pep-517-builds">Migrating to PEP 517 builds</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a><ul> +<li class="toctree-l2"><a class="reference internal" href="package-maintenance.html#support-for-python-2">Support for Python 2</a></li> +<li class="toctree-l2"><a class="reference internal" href="package-maintenance.html#which-implementations-to-test-new-packages-for">Which implementations to test new packages for?</a></li> +<li class="toctree-l2"><a class="reference internal" href="package-maintenance.html#adding-new-python-implementations-to-existing-packages">Adding new Python implementations to existing packages</a></li> +<li class="toctree-l2"><a class="reference internal" href="package-maintenance.html#which-packages-can-be-co-maintained-by-the-python-project">Which packages can be (co-)maintained by the Python project?</a></li> +<li class="toctree-l2"><a class="reference internal" href="package-maintenance.html#porting-packages-to-a-new-eapi">Porting packages to a new EAPI</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a><ul> +<li class="toctree-l2"><a class="reference internal" href="interpreter-maintenance.html#life-cycle-of-a-python-implementation">Life cycle of a Python implementation</a></li> +<li class="toctree-l2"><a class="reference internal" href="interpreter-maintenance.html#notes-specific-to-python-interpreters">Notes specific to Python interpreters</a></li> +<li class="toctree-l2"><a class="reference internal" href="interpreter-maintenance.html#adding-a-new-python-implementation">Adding a new Python implementation</a></li> +<li class="toctree-l2"><a class="reference internal" href="interpreter-maintenance.html#python-build-system-bootstrap">Python build system bootstrap</a></li> +</ul> +</li> +</ul> +</div> +<section id="indices-and-tables"> +<h2>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li> +<li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li> +</ul> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="#">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="#">Documentation overview</a><ul> + <li>Next: <a href="preface.html" title="next chapter">Preface</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/index.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/interpreter-maintenance.html b/guide/interpreter-maintenance.html new file mode 100644 index 0000000..181b8b9 --- /dev/null +++ b/guide/interpreter-maintenance.html @@ -0,0 +1,368 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Maintenance of Python implementations — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="prev" title="Python package maintenance" href="package-maintenance.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="maintenance-of-python-implementations"> +<h1>Maintenance of Python implementations<a class="headerlink" href="#maintenance-of-python-implementations" title="Permalink to this headline">¶</a></h1> +<section id="life-cycle-of-a-python-implementation"> +<h2>Life cycle of a Python implementation<a class="headerlink" href="#life-cycle-of-a-python-implementation" title="Permalink to this headline">¶</a></h2> +<p>Every Python implementation (understood as a potential target) in Gentoo +follows roughly the following life cycle:</p> +<ol class="arabic simple"> +<li><p>The interpreter is added to <code class="docutils literal notranslate"><span class="pre">~arch</span></code> for initial testing. At this +point, packages can not declare support for the implementation yet.</p></li> +<li><p>The new Python target is added. It is initially stable-masked, +so only <code class="docutils literal notranslate"><span class="pre">~arch</span></code> users can use it. At this point, packages start +being tested against the new target and its support starts being +declared in <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code>.</p></li> +<li><p>When ready, the new interpreter is stabilized. The target is not yet +available for stable users, though.</p></li> +<li><p>The stable-mask for the target is removed. For this to happen, +the inconsistencies in stable graph need to be addressed first +via stabilizing newer versions of packages.</p></li> +<li><p>Over time, developers are repeatedly asked to push testing packages +for the new target forward and stabilize new versions supporting it. +Eventually, the final push for updates happens and packages +not supporting the new target start being removed.</p></li> +<li><p>If applicable, the new target becomes the default. The developers +are required to test new packages against it. The support for old +target is slowly being discontinued.</p></li> +<li><p>Eventually, the target becomes replaced by the next one. When it +nears end of life, the final packages requiring it are masked for +removal and the target flags are disabled.</p></li> +<li><p>The compatibility declarations are cleaned up from <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code> +and obsolete ebuild and eclass code is cleaned up.</p></li> +<li><p>Finally, the interpreter is moved to <a class="reference external" href="https://gitweb.gentoo.org/proj/python.git/">python repository</a> where it +lives for as long as it builds.</p></li> +</ol> +<p>For example, Python 3.9 is at stage 1 at the time of writing. It is +still in alpha stage, and upstream has not finalized its feature set, +therefore it is too early to declare package support for Python 3.9 +and there are no target flags.</p> +<p>Python 3.8 is moving from stage 2 to stage 3 — it is being stabilized +by arch teams at this very moment. When that’s done, we will work +on unmasking the flag on stable systems and it will become our next +default target.</p> +<p>Python 3.7 is moving from stage 5 to stage 6. The vast majority +of packages have been ported to it, and we have already announced +the switch date.</p> +<p>When the switch happens, Python 3.6 will move from stage 6 to stage 7. +We are going to support it for quite some time still but as things +progress, we will eventually decide to remove it.</p> +<p>Python 3.5 and 3.4 are at stage 9. They live in the Python repository +but have no targets. You can still use them e.g. inside a virtualenv +to test your own software.</p> +<p>Python 2.7 is currently somewhere between stages 6 and 7. It is still +enabled by default for backwards compatibility but we are aggressively +removing it.</p> +<p>PyPy3 has recently reached stage 3. It is not clear if we are going +to pursue enabling the target on stable system though. PyPy2.7 is +at stage 8, as the targets were removed already and it is kept +as a dependency and testing target.</p> +</section> +<section id="notes-specific-to-python-interpreters"> +<h2>Notes specific to Python interpreters<a class="headerlink" href="#notes-specific-to-python-interpreters" title="Permalink to this headline">¶</a></h2> +<section id="cpython-patchsets"> +<h3>CPython patchsets<a class="headerlink" href="#cpython-patchsets" title="Permalink to this headline">¶</a></h3> +<p>Gentoo is maintaining patchsets for all CPython versions. These include +some non-upstreamable Gentoo patches and upstream backports. While it +is considered acceptable to add a new patch (e.g. a security bug fix) +to <code class="docutils literal notranslate"><span class="pre">files/</span></code> directory, it should be eventually moved into +the respective patchset.</p> +<p>When adding a new version, it is fine to use an old patchset if it +applies cleanly. If it does not, you should regenerate the patchset +for new version.</p> +<p>The origin for Gentoo patches are the <code class="docutils literal notranslate"><span class="pre">gentoo-*</span></code> tags the <a class="reference external" href="https://gitweb.gentoo.org/fork/cpython.git/">Gentoo fork +of CPython repository</a>. The recommended workflow is to clone +the upstream repository, then add Gentoo fork as a remote, e.g.:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">python</span><span class="o">/</span><span class="n">cpython</span> +<span class="n">cd</span> <span class="n">cpython</span> +<span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">gentoo</span> <span class="n">git</span><span class="nd">@git</span><span class="o">.</span><span class="n">gentoo</span><span class="o">.</span><span class="n">org</span><span class="p">:</span><span class="n">fork</span><span class="o">/</span><span class="n">cpython</span><span class="o">.</span><span class="n">git</span> +<span class="n">git</span> <span class="n">fetch</span> <span class="o">--</span><span class="n">tags</span> <span class="n">gentoo</span> +</pre></div> +</div> +<p>In order to rebase the patchset, check out the tag corresponding +to the previous patchset version and rebase it against the upstream +release tag:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">gentoo</span><span class="o">-</span><span class="mf">3.7.4</span> +<span class="n">git</span> <span class="n">rebase</span> <span class="n">v3</span><span class="mf">.7.6</span> +</pre></div> +</div> +<p>You may also add additional changes via <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">cherry-pick</span></code>. Once +the new patches are ready, create the tarball and upload it, then +create the tag and push it:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mkdir</span> <span class="n">python</span><span class="o">-</span><span class="n">gentoo</span><span class="o">-</span><span class="n">patches</span><span class="o">-</span><span class="mf">3.7.6</span> +<span class="n">cd</span> <span class="n">python</span><span class="o">-</span><span class="n">gentoo</span><span class="o">-</span><span class="n">patches</span><span class="o">-</span><span class="mf">3.7.6</span> +<span class="n">git</span> <span class="nb">format</span><span class="o">-</span><span class="n">patch</span> <span class="n">v3</span><span class="mf">.7.6</span> +<span class="n">cd</span> <span class="o">..</span> +<span class="n">tar</span> <span class="o">-</span><span class="n">cf</span> <span class="n">python</span><span class="o">-</span><span class="n">gentoo</span><span class="o">-</span><span class="n">patches</span><span class="o">-</span><span class="mf">3.7.6</span><span class="o">.</span><span class="n">tar</span> <span class="n">python</span><span class="o">-</span><span class="n">gentoo</span><span class="o">-</span><span class="n">patches</span><span class="o">-</span><span class="mf">3.7.6</span> +<span class="n">xz</span> <span class="o">-</span><span class="mi">9</span> <span class="n">python</span><span class="o">-</span><span class="n">gentoo</span><span class="o">-</span><span class="n">patches</span><span class="o">-</span><span class="mf">3.7.6</span><span class="o">.</span><span class="n">tar</span> +<span class="n">scp</span> <span class="n">python</span><span class="o">-</span><span class="n">gentoo</span><span class="o">-</span><span class="n">patches</span><span class="o">-</span><span class="mf">3.7.6</span><span class="o">.</span><span class="n">tar</span><span class="o">.</span><span class="n">xz</span> <span class="o">...</span> +<span class="n">git</span> <span class="n">tag</span> <span class="n">gentoo</span><span class="o">-</span><span class="mf">3.7.6</span> +<span class="n">git</span> <span class="n">push</span> <span class="o">--</span><span class="n">tags</span> <span class="n">gentoo</span> +</pre></div> +</div> +</section> +<section id="pypy"> +<h3>PyPy<a class="headerlink" href="#pypy" title="Permalink to this headline">¶</a></h3> +<p>Due to high resource requirements and long build time, PyPy on Gentoo +is provided both in source and precompiled form. This creates a bit +unusual ebuild structure:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">dev-python/pypy-exe</span></code> provides the PyPy executable and generated +files built from source,</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">dev-python/pypy-exe-bin</span></code> does the same in precompiled binary form,</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">dev-python/pypy</span></code> combines the above with the common files. This +is the package that runs tests and satisfies the PyPy target.</p></li> +</ul> +<p>Matching <code class="docutils literal notranslate"><span class="pre">dev-python/pypy3*</span></code> exist for PyPy3.</p> +<p>When bumping PyPy, <code class="docutils literal notranslate"><span class="pre">pypy-exe</span></code> needs to be updated first. Then it +should be used to build a binary package and bump <code class="docutils literal notranslate"><span class="pre">pypy-exe-bin</span></code>. +Technically, <code class="docutils literal notranslate"><span class="pre">pypy</span></code> can be bumped after <code class="docutils literal notranslate"><span class="pre">pypy-exe</span></code> and used to test +it but it should not be pushed before <code class="docutils literal notranslate"><span class="pre">pypy-exe-bin</span></code> is ready, as it +would force all users to switch to source form implicitly.</p> +<p>The binary packages are built using <a class="reference external" href="https://www.docker.com/">Docker</a> nowadays, using +<a class="reference external" href="https://github.com/mgorny/binpkg-docker">binpkg-docker</a> scripts. To produce them, create a <code class="docutils literal notranslate"><span class="pre">local.diff</span></code> +containing changes related to PyPy bump and run <code class="docutils literal notranslate"><span class="pre">amd64-pypy</span></code> +(and/or <code class="docutils literal notranslate"><span class="pre">amd64-pypy3</span></code>) and <code class="docutils literal notranslate"><span class="pre">x86-pypy</span></code> (and/or <code class="docutils literal notranslate"><span class="pre">x86-pypy3</span></code>) make +targets:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">mgorny</span><span class="o">/</span><span class="n">binpkg</span><span class="o">-</span><span class="n">docker</span> +<span class="n">cd</span> <span class="n">binpkg</span><span class="o">-</span><span class="n">docker</span> +<span class="p">(</span><span class="n">cd</span> <span class="o">~/</span><span class="n">git</span><span class="o">/</span><span class="n">gentoo</span> <span class="o">&&</span> <span class="n">git</span> <span class="n">diff</span> <span class="n">origin</span><span class="p">)</span> <span class="o">></span> <span class="n">local</span><span class="o">.</span><span class="n">diff</span> +<span class="n">make</span> <span class="n">amd64</span><span class="o">-</span><span class="n">pypy</span> <span class="n">amd64</span><span class="o">-</span><span class="n">pypy3</span> <span class="n">x86</span><span class="o">-</span><span class="n">pypy</span> <span class="n">x86</span><span class="o">-</span><span class="n">pypy3</span> +</pre></div> +</div> +<p>The resulting binary packages will be placed in your home directory, +in <code class="docutils literal notranslate"><span class="pre">~/binpkg/${arch}/pypy</span></code>. Upload them and use them to bump +<code class="docutils literal notranslate"><span class="pre">pypy-exe-bin</span></code>.</p> +</section> +</section> +<section id="adding-a-new-python-implementation"> +<h2>Adding a new Python implementation<a class="headerlink" href="#adding-a-new-python-implementation" title="Permalink to this headline">¶</a></h2> +<section id="eclass-and-profile-changes"> +<h3>Eclass and profile changes<a class="headerlink" href="#eclass-and-profile-changes" title="Permalink to this headline">¶</a></h3> +<p>When adding a new Python target, please remember to perform all +the following tasks:</p> +<ul class="simple"> +<li><p>add the new target flags to <code class="docutils literal notranslate"><span class="pre">profiles/desc/python_targets.desc</span></code> +and <code class="docutils literal notranslate"><span class="pre">python_single_target.desc</span></code>.</p></li> +<li><p>force the new implementation on <code class="docutils literal notranslate"><span class="pre">dev-lang/python-exec</span></code> +via <code class="docutils literal notranslate"><span class="pre">profiles/base/package.use.force</span></code>.</p></li> +<li><p>mask the new target flags on stable profiles +via <code class="docutils literal notranslate"><span class="pre">profiles/base/use.stable.mask</span></code>.</p></li> +<li><p>add the new target to <code class="docutils literal notranslate"><span class="pre">_PYTHON_ALL_IMPLS</span></code> and update the patterns +in <code class="docutils literal notranslate"><span class="pre">_python_impl_supported()</span></code> in <code class="docutils literal notranslate"><span class="pre">python-utils-r1.eclass</span></code>.</p></li> +<li><p>add the new implementation to the list +in <code class="docutils literal notranslate"><span class="pre">app-portage/gpyutils/files/implementations.txt</span></code>.</p></li> +</ul> +</section> +<section id="porting-initial-packages"> +<h3>Porting initial packages<a class="headerlink" href="#porting-initial-packages" title="Permalink to this headline">¶</a></h3> +<p>The initial porting is quite hard due to a number of circular +dependencies. To ease the process, some of the high profile packages +are ported first with tests and their dependencies disabled for the new +implementation, e.g.:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> test? (</span> +<span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +</span><span class="s1"> dev-python/jaraco-envs[${PYTHON_USEDEP}]</span> +<span class="s1"> >=dev-python/jaraco-path-3.2.0[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/mock[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/pip[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/sphinx[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/pytest[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/pytest-fixture-config[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/pytest-virtualenv[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/pytest-xdist[${PYTHON_USEDEP}]</span> +<span class="s1"> >=dev-python/virtualenv-20[${PYTHON_USEDEP}]</span> +<span class="s1"> dev-python/wheel[${PYTHON_USEDEP}]</span> +<span class="hll"><span class="s1"> '</span> python3_<span class="o">{</span><span class="m">7</span>..10<span class="o">}</span> pypy3<span class="k">)</span><span class="s2"></span> +</span><span class="s2"> )</span> +<span class="s2"> "</span> + + python_test<span class="o">()</span> <span class="o">{</span> +<span class="hll"> <span class="c1"># keep in sync with python_gen_cond_dep above!</span> +</span><span class="hll"> has <span class="s2">"</span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="s2">"</span> python3.<span class="o">{</span><span class="m">7</span>..10<span class="o">}</span> pypy3 <span class="o">||</span> <span class="k">continue</span> +</span> + distutils_install_for_testing + <span class="nv">HOME</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PWD</span><span class="si">}</span><span class="s2">"</span> epytest setuptools + <span class="o">}</span> +</pre></div> +</div> +<p>The recommended process is to, in order:</p> +<ol class="arabic simple"> +<li><p>Port <code class="docutils literal notranslate"><span class="pre">dev-python/setuptools</span></code> and <code class="docutils literal notranslate"><span class="pre">dev-python/certifi</span></code> with tests +disabled. Test it via <code class="docutils literal notranslate"><span class="pre">tox</span></code> in a git checkout.</p></li> +<li><p>Port <code class="docutils literal notranslate"><span class="pre">dev-python/nose</span></code> with additional dependencies disabled +(tests skip missing dependencies gracefully).</p></li> +<li><p>Port <code class="docutils literal notranslate"><span class="pre">dev-python/pytest</span></code> and its runtime dependencies with pytest’s +tests disabled (but tests of the dependencies enabled). This should +yield around 20 packages. Test it via <code class="docutils literal notranslate"><span class="pre">tox</span></code> in a git checkout.</p></li> +<li><p>Port <code class="docutils literal notranslate"><span class="pre">dev-python/urllib3</span></code> and its runtime dependencies with +urllib3’s tests disabled (but tests of the dependencies enabled). +This should yield another 20 packages. Test it from a git checkout +(it uses nox, so you may want to write <code class="docutils literal notranslate"><span class="pre">tox.ini</span></code> yourself).</p></li> +</ol> +<p>Once these packages are done, you should be able to work towards +reenabling tests in them via porting their (deep) dependencies in groups +of around 10 packages without cyclic dependencies extending out +of the group.</p> +</section> +</section> +<section id="python-build-system-bootstrap"> +<h2>Python build system bootstrap<a class="headerlink" href="#python-build-system-bootstrap" title="Permalink to this headline">¶</a></h2> +<p>Python build systems are often facing the bootstrap problem — that is, +the build system itself has some dependencies, while these dependencies +require the same build system to build. The common upstream way +(actually recommended in <a class="reference external" href="https://www.python.org/dev/peps/pep-0517/#build-requirements">PEP 517 build requirements</a> section) is +to bundle the necessary dependencies as part of the build system. +However, this goes against best Gentoo practices.</p> +<p>The current Gentoo practice for bootstrap with dependency unbundling +is to:</p> +<ol class="arabic simple"> +<li><p>Install the dependencies of flit_core and the eclass PEP 517 logic +(installer, tomli) manually using <code class="docutils literal notranslate"><span class="pre">python_domodule</span></code>.</p></li> +<li><p>Install flit_core using the standalone PEP 517 backend.</p></li> +<li><p>Install the dependencies of setuptools using flit (writing trivial +<code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> within the ebuild if necessary).</p></li> +<li><p>Install setuptools using the standalone PEP 517 backend.</p></li> +<li><p>The dependencies of other build systems can be installed using +flit, setuptools or other previously unbundled build systems.</p></li> +</ol> +<p>Note that for the purpose of bootstrap only obligatory baseline +dependencies are considered significant. Non-obligatory dependencies +(i.e. ones that can be missing during the bootstrap process) can be +placed in <code class="docutils literal notranslate"><span class="pre">PDEPEND</span></code>. Test suite dependencies can include cycles +with the package itself — running tests is not considered obligatory +during the bootstrap process.</p> +<p>flit_core has been chosen as the base build system for unbundling since +it has the fewest external dependencies (i.e. only depends on tomli). +Its author indicates in the <a class="reference external" href="https://github.com/pypa/flit/blob/main/flit_core/flit_core/vendor/README">flit_core vendoring README</a> that no other +dependencies will be added or vendored into flit_core.</p> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Maintenance of Python implementations</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#life-cycle-of-a-python-implementation">Life cycle of a Python implementation</a></li> +<li class="toctree-l2"><a class="reference internal" href="#notes-specific-to-python-interpreters">Notes specific to Python interpreters</a></li> +<li class="toctree-l2"><a class="reference internal" href="#adding-a-new-python-implementation">Adding a new Python implementation</a></li> +<li class="toctree-l2"><a class="reference internal" href="#python-build-system-bootstrap">Python build system bootstrap</a></li> +</ul> +</li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="package-maintenance.html" title="previous chapter">Python package maintenance</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/interpreter-maintenance.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/interpreter.html b/guide/interpreter.html new file mode 100644 index 0000000..8003211 --- /dev/null +++ b/guide/interpreter.html @@ -0,0 +1,285 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Python interpreters — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Choosing between Python eclasses" href="eclass.html" /> + <link rel="prev" title="Preface" href="preface.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="python-interpreters"> +<h1>Python interpreters<a class="headerlink" href="#python-interpreters" title="Permalink to this headline">¶</a></h1> +<section id="versions-of-python"> +<h2>Versions of Python<a class="headerlink" href="#versions-of-python" title="Permalink to this headline">¶</a></h2> +<p>By a <em>version of Python</em> we usually mean the variant of Python language +and standard library interface as used by a specific version +of <a class="reference external" href="https://www.python.org/">CPython</a>, the reference implementation of Python.</p> +<p>Python versions are determined from the two first version components. +The major version is incremented when major incompatible changes are +introduced in the language, as was the case in Python 3. Along with +minor version changes, the new releases introduce new features +and remove deprecated APIs. The Python documentation generally +indicates when a particular API was added or deprecated, and when it +is planned to be removed.</p> +<p>Practically speaking, this means that a program written purely +for Python 2 is unlikely to work on Python 3, and requires major changes +to achieve compatibility. On the other hand, a program written for +Python 3.7 is very likely to work with Python 3.8, and reasonably likely +to support Python 3.6 as well. If that is not the case, minor changes +are usually sufficient to fix that.</p> +<p>For example, Python 3.7 introduced a new <a class="reference external" href="https://docs.python.org/3.7/library/importlib.html#module-importlib.resources">importlib.resources</a> module. +If your program uses it, it will not work on Python 3.6 without +a backwards compatibility code.</p> +<p>Python 3.8 removed the deprecated <a class="reference external" href="https://docs.python.org/3.7/library/platform.html#platform.linux_distribution">platform.linux_distribution()</a> +function. If your program used it, it will not work on Python 3.8 +without changes. However, it was deprecated since Python 3.5, so if you +were targetting 3.7, you should not have been using it in the first +place.</p> +<p>Gentoo supports building packages against Python 2.7 and a shifting +window of 3-4 versions of Python 3. They are provided as slots +of <code class="docutils literal notranslate"><span class="pre">dev-lang/python</span></code>.</p> +</section> +<section id="alternative-python-implementations"> +<h2>Alternative Python implementations<a class="headerlink" href="#alternative-python-implementations" title="Permalink to this headline">¶</a></h2> +<p>CPython is the reference and most commonly used Python implementation. +However, there are other interpreters that aim to maintain reasonable +compatibility with it.</p> +<p><a class="reference external" href="https://www.pypy.org/">PyPy</a> is an implementation of Python built using in-house RPython +language, using a Just-in-Time compiler to achieve better performance +(generally in long-running programs running a lot of Python code). +It maintains quite good compatibility with CPython, except when programs +rely on its implementation details or GC behavior.</p> +<p>PyPy upstream provides PyPy variants compatible with Python 2.7 +and one version of Python 3. Gentoo supports building packages against +PyPy3. PyPy2.7 is provided as <code class="docutils literal notranslate"><span class="pre">dev-python/pypy</span></code>, while PyPy3 is +provided as <code class="docutils literal notranslate"><span class="pre">dev-python/pypy3</span></code>.</p> +<p><a class="reference external" href="https://www.jython.org/">Jython</a> is an implementation of Python written in Java. Besides being +a stand-alone Python interpreter, it supports bidirectional interaction +between Python and Java libraries.</p> +<p>Jython development is very slow paced, and it is currently bound +to Python 2.7. Gentoo does not support building packages for Jython +anymore. The interpreter is still provided as <code class="docutils literal notranslate"><span class="pre">dev-java/jython</span></code>.</p> +<p><a class="reference external" href="https://ironpython.net/">IronPython</a> is an implementation of Python for the .NET framework. +Alike Jython, it supports bidirectional interaction between Python +and .NET Framework. It is currently bound to Python 2.7. It is not +packaged in Gentoo.</p> +<p><a class="reference external" href="https://www.brython.info/">Brython</a> is an implementation of Python 3 for client-side web +programming (in JavaScript). It provides a subset of Python 3 standard +library combined with access to DOM objects. It is packaged in Gentoo +as <code class="docutils literal notranslate"><span class="pre">dev-python/brython</span></code>.</p> +<p><a class="reference external" href="https://micropython.org/">MicroPython</a> is an implementation of Python 3 aimed for microcontrollers +and embedded environments. It aims to maintain some compatibility +with CPython while providing stripped down standard library +and additional modules to interface with hardware. It is packaged +as <code class="docutils literal notranslate"><span class="pre">dev-lang/micropython</span></code>.</p> +<p><a class="reference external" href="https://github.com/naftaliharris/tauthon">Tauthon</a> is a fork of Python 2.7 that aims to backport new language +features and standard library modules while preserving backwards +compatibility with existing code. It is not packaged in Gentoo.</p> +</section> +<section id="support-for-multiple-implementations"> +<h2>Support for multiple implementations<a class="headerlink" href="#support-for-multiple-implementations" title="Permalink to this headline">¶</a></h2> +<p>The support for simultaneously using multiple Python implementations +is implemented primarily through USE flags. The packages installing +or using Python files define either <code class="docutils literal notranslate"><span class="pre">PYTHON_TARGETS</span></code> +or <code class="docutils literal notranslate"><span class="pre">PYTHON_SINGLE_TARGET</span></code> flags that permit user to choose which +implementations are used.</p> +<p>Modules and extensions are installed separately for each interpreter, +in its specific site-packages directory. This means that a package +can run using a specific target correctly only if all its dependencies +were also installed for the same implementation. This is enforced +via USE dependencies.</p> +<p>Additionally, <code class="docutils literal notranslate"><span class="pre">dev-lang/python-exec</span></code> provides a mechanism for +installing multiple variants of each Python script simultaneously. This +is necessary to support scripts that differ between Python versions +(particularly between Python 2 and Python 3) but it is also used +to prevent scripts from being called via unsupported interpreter +(i.e. one that does not have its accompanying modules or dependencies +installed).</p> +<p>This also implies that all installed Python scripts must have their +shebangs adjusted to use a specific Python interpreter (not <code class="docutils literal notranslate"><span class="pre">python</span></code> +nor <code class="docutils literal notranslate"><span class="pre">python3</span></code> but e.g. <code class="docutils literal notranslate"><span class="pre">python3.7</span></code>), and all other executables must +also be modified to call specific version of Python directly.</p> +</section> +<section id="backports"> +<h2>Backports<a class="headerlink" href="#backports" title="Permalink to this headline">¶</a></h2> +<p>A common method of improving compatibility with older versions of Python +is to backport new standard library modules or features. Packages doing +that are generally called <em>backports</em>.</p> +<p>Ideally, backports copy the code from the standard library with minimal +changes, and provide a matching API. In some cases, new versions +of backports are released as the standard library changes, and their +usability extends from providing a missing module to extending older +version of the module. For example, the <code class="docutils literal notranslate"><span class="pre">dev-python/funcsigs</span></code> package +originally backported function signatures from Python 3.3 to older +versions, and afterwards was updated to backport new features from +Python 3.6, becoming useful to versions 3.3 through 3.5.</p> +<p>Sometimes, the opposite happens. <code class="docutils literal notranslate"><span class="pre">dev-python/mock</span></code> started +as a stand-alone package, and was integrated into the standard library +as <a class="reference external" href="https://docs.python.org/3.3/library/unittest.mock.html">unittest.mock</a> later on. Afterwards, the external package became +a backport of the standard library module.</p> +<p>In some cases backports effectively replace external packages. Once +<a class="reference external" href="https://docs.python.org/3.3/library/lzma.html">lzma</a> module has been added to the standard library, its backport +<code class="docutils literal notranslate"><span class="pre">dev-python/backports-lzma</span></code> has effectively replaced the competing +LZMA packages.</p> +<p>Individual backports differ by the level of compatibility with +the standard library provided, and therefore on the amount of additional +code needed in your program. The exact kind of dependencies used +depends on that.</p> +<p><code class="docutils literal notranslate"><span class="pre">dev-python/ipaddress</span></code> is a drop-in backport of the <a class="reference external" href="https://docs.python.org/3.3/library/ipaddress.html">ipaddress</a> module +from Python 3.3. It is using the same module name, so a code written +to use this module will work out-of-the-box on Python 2.7 if the package +is installed. As a side note, since Python always prefers built-in +modules over external packages, there is no point in enabling Python 3 +in this package as the installed module would never be used. +Appropriately, you should depend on this package only for the Python +versions needing it.</p> +<p><code class="docutils literal notranslate"><span class="pre">dev-python/mock</span></code> is a compatible backport of the <a class="reference external" href="https://docs.python.org/3.3/library/unittest.mock.html">unittest.mock</a> +module. It can’t use the same name as the standard library module, +therefore the packages need to use it conditionally, e.g.:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span> + <span class="kn">from</span> <span class="nn">unittest.mock</span> <span class="kn">import</span> <span class="n">Mock</span> +<span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span> <span class="c1"># py<3.3</span> + <span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">Mock</span> +</pre></div> +</div> +<p>or:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span> +<span class="k">if</span> <span class="n">sys</span><span class="o">.</span><span class="n">hexversion</span> <span class="o">>=</span> <span class="mh">0x03030000</span><span class="p">:</span> + <span class="kn">from</span> <span class="nn">unittest.mock</span> <span class="kn">import</span> <span class="n">Mock</span> +<span class="k">else</span><span class="p">:</span> + <span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">Mock</span> +</pre></div> +</div> +<p>However, the actual API remains compatible, so the programs do not need +more compatibility code than that. In some cases, upstreams fail (or +even refuse) to use the external <code class="docutils literal notranslate"><span class="pre">mock</span></code> package conditionally — +in that case, you either need to depend on this package unconditionally, +or patch it.</p> +<p><code class="docutils literal notranslate"><span class="pre">dev-python/trollius</span></code> aimed to provide a backport of <a class="reference external" href="https://docs.python.org/3.4/library/asyncio.html">asyncio</a> +for Python 2. Since the asyncio framework relies on new Python syntax, +the backport cannot be API compatible and requires using a different +syntax than native asyncio code.</p> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Python interpreters</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#versions-of-python">Versions of Python</a></li> +<li class="toctree-l2"><a class="reference internal" href="#alternative-python-implementations">Alternative Python implementations</a></li> +<li class="toctree-l2"><a class="reference internal" href="#support-for-multiple-implementations">Support for multiple implementations</a></li> +<li class="toctree-l2"><a class="reference internal" href="#backports">Backports</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="preface.html" title="previous chapter">Preface</a></li> + <li>Next: <a href="eclass.html" title="next chapter">Choosing between Python eclasses</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/interpreter.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/migration.html b/guide/migration.html new file mode 100644 index 0000000..3104e32 --- /dev/null +++ b/guide/migration.html @@ -0,0 +1,329 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Migration guides — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Python package maintenance" href="package-maintenance.html" /> + <link rel="prev" title="Porting tips" href="porting.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="migration-guides"> +<h1>Migration guides<a class="headerlink" href="#migration-guides" title="Permalink to this headline">¶</a></h1> +<section id="migrating-from-old-python-usedep-syntax-in-python-single-r1"> +<span id="index-0"></span><h2>Migrating from old PYTHON_USEDEP syntax in python-single-r1<a class="headerlink" href="#migrating-from-old-python-usedep-syntax-in-python-single-r1" title="Permalink to this headline">¶</a></h2> +<p>Prior to February 2020, <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> used to provide a single +<code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> variable alike the two other eclasses. However, +getting it to work correctly both on single-impl and multi-impl packages +required a gross hack.</p> +<p>The current eclass API requires using <code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> function +to generate multi-impl deps instead, with <code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> serving +as a placeholder. Single-impl deps can be expressed with +<code class="docutils literal notranslate"><span class="pre">PYTHON_SINGLE_USEDEP</span></code> that can be used either as placeholder, +or directly as a variable.</p> +<p>During a transitional period, <code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> was banned entirely +and <code class="docutils literal notranslate"><span class="pre">PYTHON_MULTI_USEDEP</span></code> was used instead. As of EAPI 8, +the opposite is true — <code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> is to be used, +and <code class="docutils literal notranslate"><span class="pre">PYTHON_MULTI_USEDEP</span></code> was removed.</p> +<p>The recommended rule of thumb for migrating old ebuilds is to:</p> +<ol class="arabic simple"> +<li><p>Replace all instances of <code class="docutils literal notranslate"><span class="pre">${PYTHON_USEDEP}</span></code> for simple-impl deps +with <code class="docutils literal notranslate"><span class="pre">${PYTHON_SINGLE_USEDEP}</span></code>. If you don’t know the type +of given dep, dependency check (repoman, pkgcheck) will tell you +if you chose wrong.</p></li> +<li><p>Wrap the dependencies using <code class="docutils literal notranslate"><span class="pre">${PYTHON_USEDEP}</span></code> in a single +<code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> block (reordering may be desirable).</p></li> +<li><p>Run <code class="docutils literal notranslate"><span class="pre">pkgcheck</span> <span class="pre">scan</span></code> or <code class="docutils literal notranslate"><span class="pre">repoman</span> <span class="pre">full</span></code>. If you get syntax errors, +you probably missed <code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> or did not escape +the <code class="docutils literal notranslate"><span class="pre">$</span></code> in placeholder properly. If you get unmatched dependency, +you probably got single-impl vs. multi-impl wrong.</p></li> +</ol> +<p>This way, you can generally convert ebuilds using trial-and-error +method.</p> +</section> +<section id="migrating-from-eapi-7-to-eapi-8"> +<span id="index-1"></span><h2>Migrating from EAPI 7 to EAPI 8<a class="headerlink" href="#migrating-from-eapi-7-to-eapi-8" title="Permalink to this headline">¶</a></h2> +<p>EAPI 8 has banned everything that’s been deprecated in EAPI 7, as well +as some other obsolete stuff. The following table lists all banned +things along with their suggested replacements.</p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 46%" /> +<col style="width: 54%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>Deprecated thing</p></th> +<th class="head"><p>Replacement</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td colspan="2"><p>Private eclass API</p></td> +</tr> +<tr class="row-odd"><td><p>python_export</p></td> +<td><p>python_setup / getters</p></td> +</tr> +<tr class="row-even"><td><p>python_wrapper_setup</p></td> +<td><p>python_setup</p></td> +</tr> +<tr class="row-odd"><td colspan="2"><p>Obsolete API</p></td> +</tr> +<tr class="row-even"><td><p>distutils_install_for_testing +<code class="docutils literal notranslate"><span class="pre">--via-home</span></code></p></td> +<td><p>no argument (<code class="docutils literal notranslate"><span class="pre">--via-root</span></code>) +or <code class="docutils literal notranslate"><span class="pre">--via-venv</span></code></p></td> +</tr> +<tr class="row-odd"><td><p>python_gen_usedep</p></td> +<td><p>python_gen_cond_dep</p></td> +</tr> +<tr class="row-even"><td><p>PYTHON_MULTI_USEDEP</p></td> +<td><p>PYTHON_USEDEP</p></td> +</tr> +<tr class="row-odd"><td colspan="2"><p>mydistutilsargs rename</p></td> +</tr> +<tr class="row-even"><td><p>mydistutilsargs</p></td> +<td><p>DISTUTILS_ARGS</p></td> +</tr> +<tr class="row-odd"><td colspan="2"><p>Post-Python 2 cleanup</p></td> +</tr> +<tr class="row-even"><td><p>python_gen* -2 / python2 +/ pypy</p></td> +<td><p>remove entirely</p></td> +</tr> +<tr class="row-odd"><td><p>python_gen* -3</p></td> +<td><p>make unconditional</p></td> +</tr> +<tr class="row-even"><td><p>python_is_python3</p></td> +<td><p>always assume true</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p>The changes can be split roughly into four groups: ban of now-private +eclass API, ban of obsolete API functions, mydistutilsargs rename +and bans related to post-Python 2 cleanup.</p> +<p>The private eclass API part involves <code class="docutils literal notranslate"><span class="pre">python_export</span></code> +and <code class="docutils literal notranslate"><span class="pre">python_wrapper_setup</span></code>. Both were deprecated in March 2020, +and they were never covered in this guide. The former was historically +used to get information about the Python interpreter (either the current +<code class="docutils literal notranslate"><span class="pre">${EPYTHON}</span></code> or an arbitrary choice), the latter to create the wrapper +directory containing <code class="docutils literal notranslate"><span class="pre">python</span></code> and other executables.</p> +<p>When the functions were used to establish a Python build environment, +the replacement for both is a single <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> call. When +<code class="docutils literal notranslate"><span class="pre">python_export</span></code> was used to grab additional details about the Python +interpreter, the various <code class="docutils literal notranslate"><span class="pre">python_get*</span></code> functions should be used +instead.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>src_configure<span class="o">()</span> <span class="o">{</span> + <span class="c1"># ...</span> + + <span class="c1"># OLD:</span> + <span class="nb">local</span> PYTHON_INCLUDEDIR PYTHON_LIBPATH + python_export PYTHON_INCLUDEDIR PYTHON_LIBPATH + <span class="nv">mycmakeargs</span><span class="o">+=(</span> + -DPython3_INCLUDE_DIR<span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_INCLUDEDIR</span><span class="si">}</span><span class="s2">"</span> + -DPython3_LIBRARY<span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_LIBPATH</span><span class="si">}</span><span class="s2">"</span> + <span class="o">)</span> + + <span class="c1"># NEW:</span> + <span class="nv">mycmakeargs</span><span class="o">+=(</span> + -DPython3_INCLUDE_DIR<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>python_get_includedir<span class="k">)</span><span class="s2">"</span> + -DPython3_LIBRARY<span class="o">=</span><span class="s2">"</span><span class="k">$(</span>python_get_library_path<span class="k">)</span><span class="s2">"</span> + <span class="o">)</span> +<span class="o">}</span> +</pre></div> +</div> +<p>The second group involves sundry API that were deprecated earlier. +These are:</p> +<ol class="arabic simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">distutils_install_for_testing</span> <span class="pre">--via-home</span></code> layout that stopped +working correctly at some point. The default <code class="docutils literal notranslate"><span class="pre">--via-root</span></code> should +work most of the time, and <code class="docutils literal notranslate"><span class="pre">-via-venv</span></code> replace the remaining cases +for the removed layout.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">python_gen_usedep</span></code> function that was historically used to generate +partial USE dependencies, and was generally combined with +<code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code> to force specific (usually old) Python interpreters +for specific features. This was really ugly. Nowadays, you should +really use <code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> instead.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">PYTHON_MULTI_USEDEP</span></code> placeholder that was temporarily used +in python-single-r1 ebuilds. <code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> is equivalent now.</p></li> +</ol> +<p>The third group is a sole rename of <code class="docutils literal notranslate"><span class="pre">mydistutilsargs</span></code> variable. +Since you usually need to pass the same arguments in all phase +functions, this variable was not really used in local scope. It has +been renamed to uppercase <code class="docutils literal notranslate"><span class="pre">DISTUTILS_ARGS</span></code> to follow the common +pattern for global scope variables.</p> +<p>Finally, the fourth group involves banning some of the features that +were specifically used in order to support distinguish between Python 2 +and Python 3. This is meant to force cleaning up old cruft from +ebuilds. It comes in three parts:</p> +<ol class="arabic simple"> +<li><p>Banning arguments to <code class="docutils literal notranslate"><span class="pre">python_gen*</span></code> that reference Python 2 +(e.g. <code class="docutils literal notranslate"><span class="pre">-2</span></code>, <code class="docutils literal notranslate"><span class="pre">python2*</span></code>, <code class="docutils literal notranslate"><span class="pre">python2_7</span></code>, <code class="docutils literal notranslate"><span class="pre">pypy</span></code>). Since Python 2 +is no longer supported in the relevant code paths, the relevant calls +should just be removed.</p></li> +<li><p>Banning the <code class="docutils literal notranslate"><span class="pre">-3</span></code> short-hand to <code class="docutils literal notranslate"><span class="pre">python_gen*</span></code>. Since all +supported interpreters are compatible with Python 3 now, the relevant +code should be made unconditional. Note that <code class="docutils literal notranslate"><span class="pre">python3*</span></code> is still +useful, as it distinguishes CPython from PyPy3.</p></li> +<li><p>Banning the <code class="docutils literal notranslate"><span class="pre">python_is_python3</span></code> function. Since the removal +of Python 2 support, it always evaluated to true.</p></li> +</ol> +<p>All the aforementioned replacements are available in all EAPIs.</p> +</section> +<section id="migrating-to-pep-517-builds"> +<h2>Migrating to PEP 517 builds<a class="headerlink" href="#migrating-to-pep-517-builds" title="Permalink to this headline">¶</a></h2> +<p>As of January 2022, the <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> can use PEP 517 build backends +instead of calling setuptools directly. The new mode is particularly +useful for:</p> +<ul class="simple"> +<li><p>packages using flit and poetry, as a better replacement for +the deprecated <code class="docutils literal notranslate"><span class="pre">dev-python/pyproject2setuppy</span></code> hack</p></li> +<li><p>packages using other PEP 517 build systems (such as pdm) that are not +supported in legacy mode at all</p></li> +<li><p>packages using setuptools without <code class="docutils literal notranslate"><span class="pre">setup.py</span></code></p></li> +<li><p>packages using plain distutils, as the mode handles the switch from +deprecated stdlib distutils to the version vendored in setuptools +safely</p></li> +</ul> +<p>The PEP 517 mode provides the test phase with venv-style installed +package tree (alike <code class="docutils literal notranslate"><span class="pre">distutils_install_for_testing</span> <span class="pre">--via-venv</span></code>) +that should make testing more streamlined.</p> +<p>Unfortunately, the new mode can cause issues with customized distutils +and setuptools build systems. It is important to verify the installed +file list after the migration. Packages that require custom configure +phases or passing arguments are not supported at the moment.</p> +<p>For simple packages, the migration consists of:</p> +<ol class="arabic simple"> +<li><p>Adding <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_PEP517</span></code> above the inherit line. The value +indicates the build system used, e.g. <code class="docutils literal notranslate"><span class="pre">flit</span></code>, <code class="docutils literal notranslate"><span class="pre">poetry</span></code>, +<code class="docutils literal notranslate"><span class="pre">setuptools</span></code> (used also for distutils).</p></li> +<li><p>Removing <code class="docutils literal notranslate"><span class="pre">DISTUTILS_USE_SETUPTOOLS</span></code>. If the previous value was +<code class="docutils literal notranslate"><span class="pre">rdepend</span></code> (and indeed a runtime dependency is required), then +<code class="docutils literal notranslate"><span class="pre">dev-python/setuptools</span></code> needs to be explicitly added to +<code class="docutils literal notranslate"><span class="pre">RDEPEND</span></code>.</p></li> +<li><p>Removing <code class="docutils literal notranslate"><span class="pre">distutils_install_for_testing</span></code> and/or <code class="docutils literal notranslate"><span class="pre">--install</span></code> +option to <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code>. This should no longer be +necessary and tests should work out of the box.</p></li> +</ol> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Migration guides</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#migrating-from-old-python-usedep-syntax-in-python-single-r1">Migrating from old PYTHON_USEDEP syntax in python-single-r1</a></li> +<li class="toctree-l2"><a class="reference internal" href="#migrating-from-eapi-7-to-eapi-8">Migrating from EAPI 7 to EAPI 8</a></li> +<li class="toctree-l2"><a class="reference internal" href="#migrating-to-pep-517-builds">Migrating to PEP 517 builds</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="porting.html" title="previous chapter">Porting tips</a></li> + <li>Next: <a href="package-maintenance.html" title="next chapter">Python package maintenance</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/migration.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/multi.html b/guide/multi.html new file mode 100644 index 0000000..301e6a1 --- /dev/null +++ b/guide/multi.html @@ -0,0 +1,468 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>python-r1 — multi-impl packages — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="distutils-r1 — standard Python build systems" href="distutils.html" /> + <link rel="prev" title="python-single-r1 — single-impl packages" href="single.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="python-r1-multi-impl-packages"> +<h1>python-r1 — multi-impl packages<a class="headerlink" href="#python-r1-multi-impl-packages" title="Permalink to this headline">¶</a></h1> +<p>The <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> eclass is used to install multi-impl packages. +It is considered an expert eclass — when possible, you should prefer +using <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> instead. For packages using distutils +or a similar Python build system, <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> eclass should be used +instead.</p> +<p>Eclass reference: <a class="reference external" href="https://devmanual.gentoo.org/eclass-reference/python-r1.eclass/index.html">python-r1.eclass(5)</a></p> +<section id="manual-install"> +<span id="index-0"></span><h2>Manual install<a class="headerlink" href="#manual-install" title="Permalink to this headline">¶</a></h2> +<p>The simplest case of multi-impl package is a package without a specific +build system. The modules need to be installed manually here, +and <code class="docutils literal notranslate"><span class="pre">python_foreach_impl</span></code> function is used to repeat the install step +for all enabled implementations.</p> +<p>For simple use cases, the install command can be inlined:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Foundation</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + +<span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 <span class="o">)</span> +</span><span class="hll"> inherit python-r1 +</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"MySQL abstraction layer for python"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"http://software.fionet.com/pSQL/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"http://software.fionet.com/pSQL/release/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">""</span> +<span class="hll"> <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> +</span> +<span class="hll"> <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2">"</span> +</span> <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2">"</span> + + src_install<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl python_domodule pSQL.py +</span> <span class="o">}</span> +</pre></div> +</div> +<p>While <code class="docutils literal notranslate"><span class="pre">python_foreach_impl</span></code> can be repeated multiple times, it is +generally better to declare a function when multiple install commands +need to be executed:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 <span class="o">)</span> + inherit python-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Proxy cache for Gentoo packages"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://sourceforge.net/projects/http-replicator"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://sourceforge/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tgz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 hppa ppc ~sparc x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">""</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2">"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2">"</span> + +<span class="hll"> python_install<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> python_doscript http-replicator +</span><span class="hll"> python_domodule *.py +</span><span class="hll"> <span class="o">}</span> +</span> + src_install<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl python_install +</span> <span class="o">}</span> +</pre></div> +</div> +</section> +<section id="dependencies"> +<span id="index-1"></span><h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2> +<p>When depending on other Python packages, USE dependencies need to be +declared in order to ensure that the dependencies would be built against +all the Python implementations enabled for the package. This is easily +done via appending the USE dependency string from <code class="docutils literal notranslate"><span class="pre">${PYTHON_USEDEP}</span></code> +to the dependencies:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> sys-apps/portage[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2">"</span> +<span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2">"</span> +</pre></div> +</div> +</section> +<section id="pure-python-autotools-package"> +<span id="index-2"></span><h2>Pure Python autotools package<a class="headerlink" href="#pure-python-autotools-package" title="Permalink to this headline">¶</a></h2> +<p>Another typical case for this eclass is to handle a pure Python package +with a non-standard build system. In this case, it is generally +necessary to call phase functions via <code class="docutils literal notranslate"><span class="pre">python_foreach_impl</span></code>. Whenever +possible, out-of-source builds are recommended (i.e. installing to +separate directories from a single source directory).</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="s2">"6"</span> + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_6 <span class="o">)</span> + + inherit autotools python-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Python wrapper for libcangjie"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"http://cangjians.github.io/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/Cangjians/py</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/releases/download/v</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="p">#py</span><span class="si">}</span><span class="s2">.tar.xz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"LGPL-3+"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">""</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> app-i18n/libcangjie"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> dev-python/cython[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> virtual/pkgconfig"</span> + + src_prepare<span class="o">()</span> <span class="o">{</span> + default + eautoreconf + <span class="o">}</span> + + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nb">local</span> <span class="nv">ECONF_SOURCE</span><span class="o">=</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span> +<span class="hll"> python_foreach_impl run_in_build_dir default +</span> <span class="o">}</span> + + src_compile<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl run_in_build_dir default +</span> <span class="o">}</span> + + src_test<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl run_in_build_dir default +</span> <span class="o">}</span> + + src_install<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl run_in_build_dir default +</span> einstalldocs + find <span class="s2">"</span><span class="si">${</span><span class="nv">D</span><span class="si">}</span><span class="s2">"</span> -name <span class="s1">'*.la'</span> -delete <span class="o">||</span> die + <span class="o">}</span> +</pre></div> +</div> +<p>Note the use of <code class="docutils literal notranslate"><span class="pre">run_in_build_dir</span></code> helper from <code class="docutils literal notranslate"><span class="pre">multibuild</span></code> eclass +(direct inherit is unnecessary here, as it is considered implicit part +of <code class="docutils literal notranslate"><span class="pre">python-r1</span></code> API). It changes the directory to <code class="docutils literal notranslate"><span class="pre">BUILD_DIR</span></code> (which +is set by <code class="docutils literal notranslate"><span class="pre">python_foreach_impl</span></code> to a unique directory for each +implementation) and runs the specified command there. In this case, +the ebuild performs autotools out-of-source build in a dedicated +directory for every interpreter enabled.</p> +<p>Also note that the in-build-dir call to <code class="docutils literal notranslate"><span class="pre">default</span></code> does not install +documentation from source directory, hence the additional +<code class="docutils literal notranslate"><span class="pre">einstalldocs</span></code> call. Libtool-based packages install <code class="docutils literal notranslate"><span class="pre">.la</span></code> files +that are unnecessary for Python extensions, hence they are removed +afterwards.</p> +<p>If the package in question does not support out-of-source builds +(e.g. due to a buggy build system), <code class="docutils literal notranslate"><span class="pre">python_copy_sources</span></code> function +can be used to duplicate the package’s sources in build directories +for each implementation. The same ebuild easily can be changed +to do that:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="s2">"6"</span> + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_6 <span class="o">)</span> + + inherit autotools python-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Python wrapper for libcangjie"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"http://cangjians.github.io/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/Cangjians/py</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/releases/download/v</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="p">#py</span><span class="si">}</span><span class="s2">.tar.xz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"LGPL-3+"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">""</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> + + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> app-i18n/libcangjie"</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> dev-python/cython[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> virtual/pkgconfig"</span> + + src_prepare<span class="o">()</span> <span class="o">{</span> + default + eautoreconf +<span class="hll"> python_copy_sources +</span> <span class="o">}</span> + + src_configure<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl run_in_build_dir default +</span> <span class="o">}</span> + + src_compile<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl run_in_build_dir default +</span> <span class="o">}</span> + + src_test<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl run_in_build_dir default +</span> <span class="o">}</span> + + src_install<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_foreach_impl run_in_build_dir default +</span> einstalldocs + find <span class="s2">"</span><span class="si">${</span><span class="nv">D</span><span class="si">}</span><span class="s2">"</span> -name <span class="s1">'*.la'</span> -delete <span class="o">||</span> die + <span class="o">}</span> +</pre></div> +</div> +<p>Note that besides adding <code class="docutils literal notranslate"><span class="pre">python_copy_sources</span></code> call, <code class="docutils literal notranslate"><span class="pre">ECONF_SOURCE</span></code> +has been removed in order to disable out-of-source builds.</p> +</section> +<section id="conditional-python-use"> +<h2>Conditional Python use<a class="headerlink" href="#conditional-python-use" title="Permalink to this headline">¶</a></h2> +<p>When the package installs Python components conditionally to a USE flag, +the respective USE conditional needs to be consistently used in metadata +variables and in <code class="docutils literal notranslate"><span class="pre">python_foreach_impl</span></code> calls.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 <span class="o">)</span> + + inherit gnome2 python-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Canvas widget for GTK+ using the cairo 2D library for drawing"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://wiki.gnome.org/GooCanvas"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"LGPL-2"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"2.0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 ia64 ppc ppc64 sparc x86"</span> +<span class="hll"> <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"python"</span> +</span><span class="hll"> <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"python? ( </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"> )"</span> +</span> + <span class="c1"># python only enables python specific binding override</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> python? (</span> +</span><span class="hll"><span class="s2"> </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +</span><span class="hll"><span class="s2"> >=dev-python/pygobject-2.90.4:3[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">] )</span> +</span><span class="s2"> "</span> + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2">"</span> + + src_prepare<span class="o">()</span> <span class="o">{</span> + <span class="c1"># Python bindings are built/installed manually.</span> + sed -e <span class="s2">"/SUBDIRS = python/d"</span> -i bindings/Makefile.am <span class="se">\</span> + bindings/Makefile.in <span class="o">||</span> die + + gnome2_src_prepare + <span class="o">}</span> + + src_configure<span class="o">()</span> <span class="o">{</span> + gnome2_src_configure <span class="se">\</span> + --disable-python + <span class="o">}</span> + + src_install<span class="o">()</span> <span class="o">{</span> + gnome2_src_install + +<span class="hll"> <span class="k">if</span> use python<span class="p">;</span> <span class="k">then</span> +</span><span class="hll"> sub_install<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"> python_moduleinto <span class="k">$(</span>python -c <span class="s2">"import gi;print gi._overridesdir"</span><span class="k">)</span> +</span><span class="hll"> python_domodule bindings/python/GooCanvas.py +</span><span class="hll"> <span class="o">}</span> +</span><span class="hll"> python_foreach_impl sub_install +</span><span class="hll"> <span class="k">fi</span> +</span> <span class="o">}</span> +</pre></div> +</div> +<p>Note that in many cases, you will end up having to disable upstream +rules for installing Python files as they are suitable only for +single-impl installs.</p> +</section> +<section id="additional-build-time-python-use"> +<span id="index-3"></span><h2>Additional build-time Python use<a class="headerlink" href="#additional-build-time-python-use" title="Permalink to this headline">¶</a></h2> +<p>Some packages additionally require Python at build time, independently +of Python components installed (i.e. outside <code class="docutils literal notranslate"><span class="pre">python_foreach_impl</span></code>). +The eclass provides extensive API for this purpose but for now we’ll +focus on the simplest case where the global code does not have any +dependencies or they are a subset of dependencies declared already.</p> +<p>In this case, it is sufficient to call <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> before +the routine requiring Python. It will choose the most preferred +of enabled implementations, and set the global environment for it. Note +that it is entirely normal that the same environment will be set inside +<code class="docutils literal notranslate"><span class="pre">python_foreach_impl</span></code> afterwards.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> +<span class="linenos"> 2</span> <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> +<span class="linenos"> 3</span> +<span class="linenos"> 4</span> <span class="nv">EAPI</span><span class="o">=</span><span class="s2">"7"</span> +<span class="linenos"> 5</span> +<span class="linenos"> 6</span> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python<span class="o">{</span>3_6,3_7<span class="o">}</span> <span class="o">)</span> +<span class="linenos"> 7</span> <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"ncurses,readline"</span> +<span class="linenos"> 8</span> inherit python-r1 +<span class="linenos"> 9</span> +<span class="linenos">10</span> <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"QEMU + Kernel-based Virtual Machine userland tools"</span> +<span class="linenos">11</span> <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"http://www.qemu.org http://www.linux-kvm.org"</span> +<span class="linenos">12</span> <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"http://wiki.qemu-project.org/download/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.xz"</span> +<span class="linenos">13</span> +<span class="linenos">14</span> <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2 LGPL-2 BSD-2"</span> +<span class="linenos">15</span> <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> +<span class="linenos">16</span> <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"amd64 ~arm64 ~ppc ~ppc64 x86"</span> +<span class="hll"><span class="linenos">17</span> <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"python"</span> +</span><span class="hll"><span class="linenos">18</span> <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> +</span><span class="linenos">19</span> +<span class="hll"><span class="linenos">20</span> <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2">"</span> +</span><span class="hll"><span class="linenos">21</span> <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"python? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )"</span> +</span><span class="linenos">22</span> +<span class="linenos">23</span> src_configure<span class="o">()</span> <span class="o">{</span> +<span class="hll"><span class="linenos">24</span> python_setup +</span><span class="linenos">25</span> ./configure <span class="o">||</span> die +<span class="linenos">26</span> <span class="o">}</span> +<span class="linenos">27</span> +<span class="hll"><span class="linenos">28</span> qemu_python_install<span class="o">()</span> <span class="o">{</span> +</span><span class="hll"><span class="linenos">29</span> python_domodule <span class="s2">"</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span><span class="s2">/python/qemu"</span> +</span><span class="hll"><span class="linenos">30</span> +</span><span class="hll"><span class="linenos">31</span> python_doscript <span class="s2">"</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span><span class="s2">/scripts/kvm/vmxcap"</span> +</span><span class="hll"><span class="linenos">32</span> python_doscript <span class="s2">"</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span><span class="s2">/scripts/qmp/qmp-shell"</span> +</span><span class="hll"><span class="linenos">33</span> python_doscript <span class="s2">"</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span><span class="s2">/scripts/qmp/qemu-ga-client"</span> +</span><span class="hll"><span class="linenos">34</span> <span class="o">}</span> +</span><span class="linenos">35</span> +<span class="linenos">36</span> src_install<span class="o">()</span> <span class="o">{</span> +<span class="linenos">37</span> default +<span class="hll"><span class="linenos">38</span> <span class="k">if</span> use python<span class="p">;</span> <span class="k">then</span> +</span><span class="hll"><span class="linenos">39</span> python_foreach_impl qemu_python_install +</span><span class="hll"><span class="linenos">40</span> <span class="k">fi</span> +</span><span class="linenos">41</span> <span class="o">}</span> +</pre></div> +</div> +<p>Note that the parts affecting installation of runtime components +(<code class="docutils literal notranslate"><span class="pre">RDEPEND</span></code>, <code class="docutils literal notranslate"><span class="pre">python_foreach_impl</span></code>) are made conditional to the USE +flag, while parts affecting build time (<code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code>, <code class="docutils literal notranslate"><span class="pre">BDEPEND</span></code>, +<code class="docutils literal notranslate"><span class="pre">python_setup</span></code>) are unconditional.</p> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">python-r1 — multi-impl packages</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#manual-install">Manual install</a></li> +<li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pure-python-autotools-package">Pure Python autotools package</a></li> +<li class="toctree-l2"><a class="reference internal" href="#conditional-python-use">Conditional Python use</a></li> +<li class="toctree-l2"><a class="reference internal" href="#additional-build-time-python-use">Additional build-time Python use</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="single.html" title="previous chapter">python-single-r1 — single-impl packages</a></li> + <li>Next: <a href="distutils.html" title="next chapter">distutils-r1 — standard Python build systems</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/multi.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/objects.inv b/guide/objects.inv Binary files differnew file mode 100644 index 0000000..c5c212a --- /dev/null +++ b/guide/objects.inv diff --git a/guide/package-maintenance.html b/guide/package-maintenance.html new file mode 100644 index 0000000..fe3b860 --- /dev/null +++ b/guide/package-maintenance.html @@ -0,0 +1,201 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Python package maintenance — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Maintenance of Python implementations" href="interpreter-maintenance.html" /> + <link rel="prev" title="Migration guides" href="migration.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="python-package-maintenance"> +<h1>Python package maintenance<a class="headerlink" href="#python-package-maintenance" title="Permalink to this headline">¶</a></h1> +<section id="support-for-python-2"> +<h2>Support for Python 2<a class="headerlink" href="#support-for-python-2" title="Permalink to this headline">¶</a></h2> +<p>Since Python 2.7 reached EOL, Gentoo is currently phasing out support +for Python 2. Unless your package or its reverse dependencies really +need it, you should omit it from <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code>. If you’re adding +a new package and it does not support Python 3, do not add it.</p> +<p>Many upstreams are removing Python 2 support from new releases of their +software. We remove it proactively whenever reverse dependencies permit +in order to anticipate this and avoid having to deal with lots +of reverse dependencies afterwards.</p> +<p>Packages that do not support Python 3 and are unlikely to start +supporting it soon are being slowly removed.</p> +</section> +<section id="which-implementations-to-test-new-packages-for"> +<h2>Which implementations to test new packages for?<a class="headerlink" href="#which-implementations-to-test-new-packages-for" title="Permalink to this headline">¶</a></h2> +<p>The absolute minimum set of targets are the current default targets +found in <code class="docutils literal notranslate"><span class="pre">profiles/base/make.defaults</span></code>. However, developers +are strongly encouraged to test at least the next Python 3 version +in order to ease future transition, and preferably all future versions.</p> +<p>Marking for PyPy3 is optional. At this moment, we do not aim for wide +coverage of PyPy3 support.</p> +</section> +<section id="adding-new-python-implementations-to-existing-packages"> +<h2>Adding new Python implementations to existing packages<a class="headerlink" href="#adding-new-python-implementations-to-existing-packages" title="Permalink to this headline">¶</a></h2> +<p>New Python implementations can generally be added to existing packages +without a revision bump. This is because the new dependencies are added +conditionally to new USE flags. Since the existing users can not have +the new flags enabled, the dependencies do not need to be proactively +added to existing installations.</p> +<p>This usually applies to stable packages as well as new Python targets +are generally <code class="docutils literal notranslate"><span class="pre">use.stable.mask</span></code>-ed. This means that stable users +will not be able to enable newly added flags and therefore the risk +of the change breaking stable systems is minimal.</p> +</section> +<section id="which-packages-can-be-co-maintained-by-the-python-project"> +<h2>Which packages can be (co-)maintained by the Python project?<a class="headerlink" href="#which-packages-can-be-co-maintained-by-the-python-project" title="Permalink to this headline">¶</a></h2> +<p>A large part of the Python ecosystem is fairly consistent, making it +feasible for (co-)maintenance by the Gentoo Python team.</p> +<p>As a rule of thumb, Python team is ready to maintain packages specific +to the Python ecosystem and useful for the general population of Python +programmers. This includes Python interpreters and tooling, packages +purely providing Python modules and extensions and utilities specific +to the Python language.</p> +<p>However, the Python team has limited manpower, therefore it may reject +packages that have high maintenance requirements. As a rule, Python +team does not accept packages without working tests.</p> +<p>If your package matches the above profile, feel free to ask a member +of the Python project whether they would like to (co-)maintain +the package. However, if you are not a member of the project, please +do not add us without asking first.</p> +</section> +<section id="porting-packages-to-a-new-eapi"> +<h2>Porting packages to a new EAPI<a class="headerlink" href="#porting-packages-to-a-new-eapi" title="Permalink to this headline">¶</a></h2> +<p>When porting packages to a new EAPI, please take care not to port +the dependencies of Portage prematurely. This generally includes +<code class="docutils literal notranslate"><span class="pre">app-portage/gemato</span></code>, <code class="docutils literal notranslate"><span class="pre">dev-python/setuptools</span></code> and their recursive +dependencies.</p> +<p>Ideally, these ebuilds carry an appropriate note above their EAPI line, +e.g.:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># please keep this ebuild at EAPI 7 -- sys-apps/portage dep</span> +<span class="n">EAPI</span><span class="o">=</span><span class="mi">7</span> +</pre></div> +</div> +<p>This does not apply to test dependencies — they are not strictly +necessary to install a new Portage version.</p> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Python package maintenance</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#support-for-python-2">Support for Python 2</a></li> +<li class="toctree-l2"><a class="reference internal" href="#which-implementations-to-test-new-packages-for">Which implementations to test new packages for?</a></li> +<li class="toctree-l2"><a class="reference internal" href="#adding-new-python-implementations-to-existing-packages">Adding new Python implementations to existing packages</a></li> +<li class="toctree-l2"><a class="reference internal" href="#which-packages-can-be-co-maintained-by-the-python-project">Which packages can be (co-)maintained by the Python project?</a></li> +<li class="toctree-l2"><a class="reference internal" href="#porting-packages-to-a-new-eapi">Porting packages to a new EAPI</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="migration.html" title="previous chapter">Migration guides</a></li> + <li>Next: <a href="interpreter-maintenance.html" title="next chapter">Maintenance of Python implementations</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/package-maintenance.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/porting.html b/guide/porting.html new file mode 100644 index 0000000..f897167 --- /dev/null +++ b/guide/porting.html @@ -0,0 +1,310 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Porting tips — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Migration guides" href="migration.html" /> + <link rel="prev" title="Integration with build systems written in Python" href="buildsys.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="porting-tips"> +<h1>Porting tips<a class="headerlink" href="#porting-tips" title="Permalink to this headline">¶</a></h1> +<p>This section highlights some of the known incompatible changes made +in Python that could break Python scripts and modules that used to work +in prior versions. The sections are split into retroactive changes made +to all Python releases, and information specific to every Python branch +(compared to the previous one).</p> +<p>This guide is by no means considered complete. If you can think +of other problems you’ve hit while porting your packages, please let me +know and I will update it.</p> +<section id="retroactive-changes"> +<h2>Retroactive changes<a class="headerlink" href="#retroactive-changes" title="Permalink to this headline">¶</a></h2> +<section id="bpo43882-urlsplit-now-strips-lf-cr-and-ht-characters"> +<h3><a class="reference external" href="https://bugs.python.org/issue43882">bpo43882</a>: urlsplit now strips LF, CR and HT characters<a class="headerlink" href="#bpo43882-urlsplit-now-strips-lf-cr-and-ht-characters" title="Permalink to this headline">¶</a></h3> +<p>Changed in: 2.7.18_p9, 3.6.13_p3, 3.7.10_p3, 3.8.9_p2, 3.9.4_p1</p> +<p>Historically, various <a class="reference external" href="https://docs.python.org/3/library/urllib.parse.html">urllib.parse</a> methods have passed special +characters such as LF, CR and HT through into the split URL components. +This could have resulted in various exploits if Python programs did not +validate the resulting components and used them verbatim.</p> +<p><a class="reference external" href="https://bugs.python.org/issue43882">bpo43882</a> attempted to address the issue by making <a class="reference external" href="https://docs.python.org/3/library/urllib.parse.html">urllib.parse</a> strip +the three aforementioned characters from the output of its functions. +This fixed one class of potential issues but at the same time opened +another can of worms. For example, URL validators that used to check +for dangerous special characters in the split URL components stopped +working correctly. In the best case, the URL were now sanitized instead +of being rejected. In the worst, the original unparsed URL with +dangerous characters started being passed through. See e.g. <a class="reference external" href="https://github.com/django/django/pull/14349">django +PR#14349</a> for an example of impact and a fix.</p> +<p>Behavior before:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">urllib</span><span class="o">.</span><span class="n">parse</span><span class="o">.</span><span class="n">urlparse</span><span class="p">(</span><span class="s1">'https://example.com/bad</span><span class="se">\n</span><span class="s1">url'</span><span class="p">)</span> +<span class="go">ParseResult(scheme='https', netloc='example.com', path='/bad\nurl', params='', query='', fragment='')</span> +</pre></div> +</div> +<p>Behavior after:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">urllib</span><span class="o">.</span><span class="n">parse</span><span class="o">.</span><span class="n">urlparse</span><span class="p">(</span><span class="s1">'https://example.com/bad</span><span class="se">\n</span><span class="s1">url'</span><span class="p">)</span> +<span class="go">ParseResult(scheme='https', netloc='example.com', path='/badurl', params='', query='', fragment='')</span> +</pre></div> +</div> +</section> +</section> +<section id="python-3-10"> +<h2>Python 3.10<a class="headerlink" href="#python-3-10" title="Permalink to this headline">¶</a></h2> +<p>See also: <a class="reference external" href="https://docs.python.org/3/whatsnew/3.10.html">what’s new in Python 3.10</a></p> +<section id="configure-no-package-python-3-1-found"> +<h3>configure: No package ‘python-3.1’ found<a class="headerlink" href="#configure-no-package-python-3-1-found" title="Permalink to this headline">¶</a></h3> +<p>automake prior to 1.16.3 wrongly recognized Python 3.10 as 3.1. +As a result, build with Python 3.10 fails:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">checking for python version... 3.1</span> +<span class="go">checking for python platform... linux</span> +<span class="go">checking for python script directory... ${prefix}/lib/python3.10/site-packages</span> +<span class="go">checking for python extension module directory... ${exec_prefix}/lib/python3.10/site-packages</span> +<span class="go">checking for PYTHON... no</span> +<span class="go">configure: error: Package requirements (python-3.1) were not met:</span> + +<span class="go">No package 'python-3.1' found</span> + +<span class="go">Consider adjusting the PKG_CONFIG_PATH environment variable if you</span> +<span class="go">installed software in a non-standard prefix.</span> + +<span class="go">Alternatively, you may set the environment variables PYTHON_CFLAGS</span> +<span class="go">and PYTHON_LIBS to avoid the need to call pkg-config.</span> +<span class="go">See the pkg-config man page for more details.</span> +<span class="go">Error: Process completed with exit code 1.</span> +</pre></div> +</div> +<p>To resolve this in ebuild, you need to autoreconf with the Gentoo +distribution of automake:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">inherit</span> <span class="n">autotools</span> + +<span class="c1"># ...</span> + +<span class="n">src_prepare</span><span class="p">()</span> <span class="p">{</span> + <span class="n">default</span> + <span class="n">eautoreconf</span> +<span class="p">}</span> +</pre></div> +</div> +<p>The upstream fix is to create new distfiles using automake-1.16.3+.</p> +</section> +<section id="distutils-sysconfig-deprecation"> +<h3>distutils.sysconfig deprecation<a class="headerlink" href="#distutils-sysconfig-deprecation" title="Permalink to this headline">¶</a></h3> +<p>Upstream intends to remove distutils by Python 3.12. Python 3.10 starts +throwing deprecation warnings for various distutils modules. +The distutils.sysconfig is usually easy to port.</p> +<p>The following table summarizes replacements for common path getters.</p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 51%" /> +<col style="width: 49%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>distutils.sysconfig call</p></th> +<th class="head"><p>sysconfig replacement</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">get_python_inc(False)</span></code></p></td> +<td><p><code class="docutils literal notranslate"><span class="pre">get_path("include")</span></code></p></td> +</tr> +<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">get_python_inc(True)</span></code></p></td> +<td><p><code class="docutils literal notranslate"><span class="pre">get_path("platinclude")</span></code></p></td> +</tr> +<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">get_python_lib(False,</span> <span class="pre">False)</span></code></p></td> +<td><p><code class="docutils literal notranslate"><span class="pre">get_path("purelib")</span></code></p></td> +</tr> +<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">get_python_lib(True,</span> <span class="pre">False)</span></code></p></td> +<td><p><code class="docutils literal notranslate"><span class="pre">get_path("platlib")</span></code></p></td> +</tr> +<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">get_python_lib(False,</span> <span class="pre">True)</span></code></p></td> +<td><p><code class="docutils literal notranslate"><span class="pre">get_path("stdlib")</span></code></p></td> +</tr> +<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">get_python_lib(True,</span> <span class="pre">True)</span></code></p></td> +<td><p><code class="docutils literal notranslate"><span class="pre">get_path("platstdlib")</span></code></p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p>For both functions, omitted parameters default to <code class="docutils literal notranslate"><span class="pre">False</span></code>. There is +no trivial replacement for the variants with <code class="docutils literal notranslate"><span class="pre">prefix</span></code> argument.</p> +</section> +</section> +<section id="python-3-9"> +<h2>Python 3.9<a class="headerlink" href="#python-3-9" title="Permalink to this headline">¶</a></h2> +<p>See also: <a class="reference external" href="https://docs.python.org/3/whatsnew/3.9.html">what’s new in Python 3.9</a></p> +<section id="base64-encodestring-base64-decodestring-removal"> +<h3>base64.encodestring / base64.decodestring removal<a class="headerlink" href="#base64-encodestring-base64-decodestring-removal" title="Permalink to this headline">¶</a></h3> +<p>Python 3.9 removes the deprecated <code class="docutils literal notranslate"><span class="pre">base64.encodestring()</span></code> +and <code class="docutils literal notranslate"><span class="pre">base64.decodestring()</span></code> functions. While they were deprecated +since Python 3.1, many packages still use them today.</p> +<p>The drop-in Python 3.1+ replacements are <code class="docutils literal notranslate"><span class="pre">base64.encodebytes()</span></code> +and <code class="docutils literal notranslate"><span class="pre">base64.decodebytes()</span></code>. Note that contrary to the names, the old +functions were simply aliases to the byte variants in Python 3 +and <em>required</em> the arguments to be <code class="docutils literal notranslate"><span class="pre">bytes</span></code> anyway.</p> +<p>If compatibility with Python 2 is still desired, then the byte variants +ought to be called on 3.1+ and string variants before that. The old +variants accept both byte and unicode strings on Python 2.</p> +<p>Example compatibility import:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span> + +<span class="k">if</span> <span class="n">sys</span><span class="o">.</span><span class="n">version_info</span> <span class="o">>=</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">):</span> + <span class="kn">from</span> <span class="nn">base64</span> <span class="kn">import</span> <span class="n">encodebytes</span> <span class="k">as</span> <span class="n">b64_encodebytes</span> +<span class="k">else</span><span class="p">:</span> + <span class="kn">from</span> <span class="nn">base64</span> <span class="kn">import</span> <span class="n">encodestring</span> <span class="k">as</span> <span class="n">b64_encodebytes</span> +</pre></div> +</div> +<p>Note that the <code class="docutils literal notranslate"><span class="pre">base64</span></code> module also provides <code class="docutils literal notranslate"><span class="pre">b64encode()</span></code> +and <code class="docutils literal notranslate"><span class="pre">b64decode()</span></code> functions that were not renamed. <code class="docutils literal notranslate"><span class="pre">b64decode()</span></code> +can be used as a drop-in replacement for <code class="docutils literal notranslate"><span class="pre">decodebytes()</span></code>. However, +<code class="docutils literal notranslate"><span class="pre">b64encode()</span></code> does not insert newlines to split the output +like <code class="docutils literal notranslate"><span class="pre">encodebytes()</span></code> does, and instead returns a single line +of base64-encoded data for any length of output.</p> +</section> +</section> +<section id="python-3-8"> +<h2>Python 3.8<a class="headerlink" href="#python-3-8" title="Permalink to this headline">¶</a></h2> +<p>See also: <a class="reference external" href="https://docs.python.org/3/whatsnew/3.8.html">what’s new in Python 3.8</a></p> +<section id="python-config-and-pkg-config-no-longer-list-python-library-by-default"> +<h3>python-config and pkg-config no longer list Python library by default<a class="headerlink" href="#python-config-and-pkg-config-no-longer-list-python-library-by-default" title="Permalink to this headline">¶</a></h3> +<p>Until Python 3.7, the <code class="docutils literal notranslate"><span class="pre">python-X.Y</span></code> pkg-config file and python-config +tool listed the Python library. Starting with 3.8, this is no longer +the case. If you are building Python extensions, this is fine (they +are not supposed to link directly to libpython).</p> +<p>If you are building programs that need to embed the Python interpreter, +new <code class="docutils literal notranslate"><span class="pre">python-X.Y-embed</span></code> pkg-config file and <code class="docutils literal notranslate"><span class="pre">--embed</span></code> parameter +are provided for the purpose.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pkg-config --libs python-3.7 +<span class="go">-lpython3.7m</span> +<span class="gp">$ </span>pkg-config --libs python-3.8 + +<span class="gp">$ </span>pkg-config --libs python-3.8-embed +<span class="go">-lpython3.8</span> +</pre></div> +</div> +<p>To achieve backwards compatibility, you should query +<code class="docutils literal notranslate"><span class="pre">python-X.Y-embed</span></code> first and fall back to <code class="docutils literal notranslate"><span class="pre">python-X.Y</span></code>.</p> +</section> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Porting tips</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#retroactive-changes">Retroactive changes</a></li> +<li class="toctree-l2"><a class="reference internal" href="#python-3-10">Python 3.10</a></li> +<li class="toctree-l2"><a class="reference internal" href="#python-3-9">Python 3.9</a></li> +<li class="toctree-l2"><a class="reference internal" href="#python-3-8">Python 3.8</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="buildsys.html" title="previous chapter">Integration with build systems written in Python</a></li> + <li>Next: <a href="migration.html" title="next chapter">Migration guides</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/porting.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/preface.html b/guide/preface.html new file mode 100644 index 0000000..25789dc --- /dev/null +++ b/guide/preface.html @@ -0,0 +1,148 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Preface — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Python interpreters" href="interpreter.html" /> + <link rel="prev" title="Gentoo Python Guide" href="index.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="preface"> +<h1>Preface<a class="headerlink" href="#preface" title="Permalink to this headline">¶</a></h1> +<p>Gentoo provides one of the best frameworks for providing Python support +in packages among operating systems. This includes support for +running multiple versions of Python (while most other distributions +avoid going beyond simultaneous support for Python 2 and one version +of Python 3), alternative implementations of Python, reliable tests, +deep QA checks. While we aim to keep things simple, this is not always +possible.</p> +<p>At the same time, the available documentation is limited and not always +up-to-date. Both the <a class="reference external" href="https://devmanual.gentoo.org/eclass-reference/index.html">built-in eclass documentation</a> and <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Python">Python +project wiki page</a> provide bits of documentation but they are mostly +in reference form and not very suitable for beginners nor people who +do not actively follow the developments within the ecosystem. This +results in suboptimal ebuilds, improper dependencies, missing tests.</p> +<p>This document aims to fill the gap by providing a good, complete, +by-topic (rather than reference-style) documentation for the ecosystem +in Gentoo and the relevant eclasses. Combined with examples, it should +help you write good ebuilds and solve common problems as simply +as possible.</p> +<p><a class="reference external" href="https://github.com/mgorny/python-guide/">Gentoo Python Guide sources</a> are available on GitHub. Suggestions +and improvements are welcome.</p> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="index.html" title="previous chapter">Gentoo Python Guide</a></li> + <li>Next: <a href="interpreter.html" title="next chapter">Python interpreters</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/preface.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/pytest.html b/guide/pytest.html new file mode 100644 index 0000000..af29942 --- /dev/null +++ b/guide/pytest.html @@ -0,0 +1,430 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>pytest recipes — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Advanced concepts" href="concept.html" /> + <link rel="prev" title="Resolving test suite problems" href="test.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="pytest-recipes"> +<h1>pytest recipes<a class="headerlink" href="#pytest-recipes" title="Permalink to this headline">¶</a></h1> +<section id="skipping-tests-based-on-markers"> +<h2>Skipping tests based on markers<a class="headerlink" href="#skipping-tests-based-on-markers" title="Permalink to this headline">¶</a></h2> +<p>A few packages use <a class="reference external" href="https://docs.pytest.org/en/stable/example/markers.html">custom pytest markers</a> to indicate e.g. tests +requiring Internet access. These markers can be used to conveniently +disable whole test groups, e.g.:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + epytest -m <span class="s1">'not network'</span> dask +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="skipping-tests-based-on-paths-names"> +<h2>Skipping tests based on paths/names<a class="headerlink" href="#skipping-tests-based-on-paths-names" title="Permalink to this headline">¶</a></h2> +<p>There are two primary methods of skipping tests based on path (and name) +in pytest: using <code class="docutils literal notranslate"><span class="pre">--ignore</span></code> and <code class="docutils literal notranslate"><span class="pre">--deselect</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">--ignore</span></code> causes pytest to entirely ignore a file or a directory +when collecting tests. This works only for skipping whole files but it +ignores missing dependencies and other failures occurring while +importing the test file.</p> +<p><code class="docutils literal notranslate"><span class="pre">--deselect</span></code> causes pytest to skip the specific test or tests. It can +be also used to select individual tests or even parametrized variants +of tests.</p> +<p>Both options can be combined to get tests to pass without having +to alter the test files. They are preferable over suggestions from +skipping problematic tests when tests are installed as part +of the package. They can also be easily applied conditionally to Python +interpreter.</p> +<p>The modern versions of eclasses provide two control variables, +<code class="docutils literal notranslate"><span class="pre">EPYTEST_IGNORE</span></code> and <code class="docutils literal notranslate"><span class="pre">EPYTEST_DESELECT</span></code> that can be used to list +test files or tests to be ignored or deselected respectively. These +variables can be used in global scope to avoid redefining +<code class="docutils literal notranslate"><span class="pre">python_test()</span></code>. However, combining them with additional conditions +requires using the local scope.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + <span class="nb">local</span> <span class="nv">EPYTEST_IGNORE</span><span class="o">=(</span> + <span class="c1"># ignore whole file with missing dep</span> + --ignore tests/test_client.py + <span class="o">)</span> + <span class="nb">local</span> <span class="nv">EPYTEST_DESELECT</span><span class="o">=(</span> + <span class="c1"># deselect a single test</span> + <span class="s1">'tests/utils/test_general.py::test_filename'</span> + <span class="c1"># deselect a parametrized test based on first param</span> + <span class="s1">'tests/test_transport.py::test_transport_works[eventlet'</span> + <span class="o">)</span> + <span class="o">[[</span> <span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span> <span class="o">==</span> python3.6 <span class="o">]]</span> <span class="o">&&</span> <span class="nv">EPYTEST_DESELECT</span><span class="o">+=(</span> + <span class="c1"># deselect a test for py3.6 only</span> + <span class="s1">'tests/utils/test_contextvars.py::test_leaks[greenlet]'</span> + <span class="o">)</span> + epytest +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="avoiding-the-dependency-on-pytest-runner"> +<h2>Avoiding the dependency on pytest-runner<a class="headerlink" href="#avoiding-the-dependency-on-pytest-runner" title="Permalink to this headline">¶</a></h2> +<p><a class="reference external" href="https://pypi.org/project/pytest-runner/">pytest-runner</a> is a package providing <code class="docutils literal notranslate"><span class="pre">pytest</span></code> command to setuptools. +While it might be convenient upstream, there is no real reason to use +it in Gentoo packages. It has no real advantage over calling pytest +directly.</p> +<p>Some packages declare the dependency on <code class="docutils literal notranslate"><span class="pre">pytest-runner</span></code> +in <code class="docutils literal notranslate"><span class="pre">setup_requires</span></code>. As a result, the dependency is enforced whenever +<code class="docutils literal notranslate"><span class="pre">setup.py</span></code> is being run, even if the user has no intention of running +tests. If this is the case, the dependency must be stripped.</p> +<p>The recommended method of stripping it is to use sed:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_prepare_all<span class="o">()</span> <span class="o">{</span> + sed -i -e <span class="s1">'/pytest-runner/d'</span> setup.py <span class="o">||</span> die + distutils-r1_python_prepare_all +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="using-pytest-xdist-to-run-tests-in-parallel"> +<h2>Using pytest-xdist to run tests in parallel<a class="headerlink" href="#using-pytest-xdist-to-run-tests-in-parallel" title="Permalink to this headline">¶</a></h2> +<p><a class="reference external" href="https://pypi.org/project/pytest-xdist/">pytest-xdist</a> is a plugin that makes it possible to run multiple tests +in parallel. This is especially useful for programs with large test +suites that take significant time to run single-threaded.</p> +<p>Not all test suites support pytest-xdist. Particularly, it requires +that the tests are written not to collide one with another.</p> +<p>Using pytest-xdist is recommended if the package in question supports it +(i.e. it does not cause semi-random test failures) and its test suite +takes significant time. When using pytest-xdist, please respect user’s +make options for the job number, e.g.:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>inherit multiprocessing + +python_test<span class="o">()</span> <span class="o">{</span> + epytest -n <span class="s2">"</span><span class="k">$(</span>makeopts_jobs <span class="s2">"</span><span class="si">${</span><span class="nv">MAKEOPTS</span><span class="si">}</span><span class="s2">"</span> <span class="s2">"</span><span class="k">$(</span>get_nproc<span class="k">)</span><span class="s2">"</span><span class="k">)</span><span class="s2">"</span> +<span class="o">}</span> +</pre></div> +</div> +<p>Please note that some upstream use pytest-xdist even if there is no real +gain from doing so. If the package’s tests take a short time to finish, +please avoid the dependency and strip it if necessary.</p> +</section> +<section id="avoiding-dependencies-on-other-pytest-plugins"> +<h2>Avoiding dependencies on other pytest plugins<a class="headerlink" href="#avoiding-dependencies-on-other-pytest-plugins" title="Permalink to this headline">¶</a></h2> +<p>There is a number of pytest plugins that have little value to Gentoo +users. They include plugins for test coverage +(<code class="docutils literal notranslate"><span class="pre">dev-python/pytest-cov</span></code>), coding style (<code class="docutils literal notranslate"><span class="pre">dev-python/pytest-flake8</span></code>) +and more. Generally, packages should avoid using those plugins.</p> +<p>In some cases, upstream packages only list them as dependencies +but do not use them automatically. In other cases, you will need +to strip options enabling them from <code class="docutils literal notranslate"><span class="pre">pytest.ini</span></code> or <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>src_prepare<span class="o">()</span> <span class="o">{</span> + sed -i -e <span class="s1">'s:--cov=wheel::'</span> setup.cfg <span class="o">||</span> die + distutils-r1_src_prepare +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="explicitly-disabling-automatic-pytest-plugins"> +<h2>Explicitly disabling automatic pytest plugins<a class="headerlink" href="#explicitly-disabling-automatic-pytest-plugins" title="Permalink to this headline">¶</a></h2> +<p>Besides plugins explicitly used by the package, there are a few pytest +plugins that enable themselves automatically for all test suites +when installed. In some cases, their presence causes tests of packages +that do not expect them, to fail.</p> +<p>An example of such package used to be <code class="docutils literal notranslate"><span class="pre">dev-python/pytest-relaxed</span></code>. +To resolve problems due to the plugin, it was necessary to disable +it explicitly:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + <span class="c1"># pytest-relaxed plugin makes our tests fail</span> + epytest -p no:relaxed +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="expert-disabling-plugin-autoloading-entirely"> +<h2>Expert: disabling plugin autoloading entirely<a class="headerlink" href="#expert-disabling-plugin-autoloading-entirely" title="Permalink to this headline">¶</a></h2> +<p>If a test suite invokes pytest recursively (this is particularly +the case when packaging other pytest plugins), the <code class="docutils literal notranslate"><span class="pre">-p</span></code> option +can be insufficient to disable problematic plugins, as it does not +get passed to the nested pytest invocations. For these packages, +the next best thing is to use environment variables.</p> +<p>Unfortunately, environment variables can only be used to disable +autoloading entirely. When doing that, you need to explicitly force +loading plugins that the test suite really needs.</p> +<p>This is done using two envvars: <code class="docutils literal notranslate"><span class="pre">PYTEST_DISABLE_PLUGIN_AUTOLOAD</span></code> +to disable autoloading plugins, and <code class="docutils literal notranslate"><span class="pre">PYTEST_PLUGINS</span></code> to specify +plugins to load. The latter takes a comma-separated list of entry point +modules. To find the correct module names, look into +the <code class="docutils literal notranslate"><span class="pre">entry_points.txt</span></code> inside the package’s <code class="docutils literal notranslate"><span class="pre">.egg-info</span></code> directory.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + <span class="nb">local</span> -x <span class="nv">PYTEST_DISABLE_PLUGIN_AUTOLOAD</span><span class="o">=</span><span class="m">1</span> + <span class="nb">local</span> -x <span class="nv">PYTEST_PLUGINS</span><span class="o">=</span>xdist.plugin,xdist.looponfail,pytest_forked + + distutils_install_for_testing + epytest +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="typeerror-make-test-flaky-got-an-unexpected-keyword-argument-reruns"> +<h2>TypeError: _make_test_flaky() got an unexpected keyword argument ‘reruns’<a class="headerlink" href="#typeerror-make-test-flaky-got-an-unexpected-keyword-argument-reruns" title="Permalink to this headline">¶</a></h2> +<p>If you see a test error resembling the following:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>TypeError: _make_test_flaky<span class="o">()</span> got an unexpected keyword argument <span class="s1">'reruns'</span> +</pre></div> +</div> +<p>This means that the tests are being run via <a class="reference external" href="https://github.com/box/flaky/">flaky</a> plugin while +the package in question expects <a class="reference external" href="https://github.com/pytest-dev/pytest-rerunfailures/">pytest-rerunfailures</a>. This is +because both plugins utilize the same <code class="docutils literal notranslate"><span class="pre">@pytest.mark.flaky</span></code> marker +but support different set of arguments.</p> +<p>To resolve the problem, explicitly disable the <code class="docutils literal notranslate"><span class="pre">flaky</span></code> plugin and make +sure to depend on <code class="docutils literal notranslate"><span class="pre">dev-python/pytest-rerunfailures</span></code>:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> test? (</span> +<span class="s2"> dev-python/dev-python/pytest-rerunfailures[</span><span class="si">${</span><span class="nv">PYTHON_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2"> )"</span> + +python_test<span class="o">()</span> <span class="o">{</span> + epytest -p no:flaky +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="importpathmismatcherror"> +<h2>ImportPathMismatchError<a class="headerlink" href="#importpathmismatcherror" title="Permalink to this headline">¶</a></h2> +<p>An <code class="docutils literal notranslate"><span class="pre">ImportPathMismatchError</span></code> generally indicates that the same Python +module (or one that supposedly looks the same) has been loaded twice +using different paths, e.g.:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>E _pytest.pathlib.ImportPathMismatchError: <span class="o">(</span><span class="s1">'path'</span>, <span class="s1">'/usr/lib/pypy3.7/site-packages/path'</span>, PosixPath<span class="o">(</span><span class="s1">'/tmp/portage/dev-python/jaraco-path-3.3.1/work/jaraco.path-3.3.1/jaraco/path.py'</span><span class="o">))</span> +</pre></div> +</div> +<p>These problems are usually caused by pytest test discovery getting +confused by namespace packages. In this case, the <code class="docutils literal notranslate"><span class="pre">jaraco</span></code> directory +is a Python 3-style namespace but pytest is treating it as a potential +test directory. Therefore, instead of loading it as <code class="docutils literal notranslate"><span class="pre">jaraco.path</span></code> +relatively to the top directory, it loads it as <code class="docutils literal notranslate"><span class="pre">path</span></code> relatively +to the <code class="docutils literal notranslate"><span class="pre">jaraco</span></code> directory.</p> +<p>The simplest way to resolve this problem is to restrict the test +discovery to the actual test directories, e.g.:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + epytest <span class="nb">test</span> +<span class="o">}</span> +</pre></div> +</div> +<p>or:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + epytest --ignore jaraco +<span class="o">}</span> +</pre></div> +</div> +</section> +<section id="fixture-not-found"> +<h2>fixture ‘…’ not found<a class="headerlink" href="#fixture-not-found" title="Permalink to this headline">¶</a></h2> +<p>Most of the time, a missing fixture indicates that some pytest plugin +is not installed. In rare cases, it can signify an incompatible pytest +version or package issue.</p> +<p>The following table maps common fixture names to their respective +plugins.</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 49%" /> +<col style="width: 51%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>Fixture name</p></th> +<th class="head"><p>Package</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>event_loop</p></td> +<td><p>dev-python/pytest-asyncio</p></td> +</tr> +<tr class="row-odd"><td><p>freezer</p></td> +<td><p>dev-python/pytest-freezegun</p></td> +</tr> +<tr class="row-even"><td><p>httpbin</p></td> +<td><p>dev-python/pytest-httpbin</p></td> +</tr> +<tr class="row-odd"><td><p>loop</p></td> +<td><p>dev-python/pytest-aiohttp</p></td> +</tr> +<tr class="row-even"><td><p>mocker</p></td> +<td><p>dev-python/pytest-mock</p></td> +</tr> +</tbody> +</table> +</section> +<section id="warnings"> +<h2>Warnings<a class="headerlink" href="#warnings" title="Permalink to this headline">¶</a></h2> +<p>pytest captures all warnings from the test suite by default, and prints +a summary of them at the end of the test suite run:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="o">===============================</span> warnings <span class="nv">summary</span> <span class="o">===============================</span> +asgiref/sync.py:135: <span class="m">1</span> warning +tests/test_local.py: <span class="m">5</span> warnings +tests/test_sync.py: <span class="m">12</span> warnings +tests/test_sync_contextvars.py: <span class="m">1</span> warning + /tmp/asgiref/asgiref/sync.py:135: DeprecationWarning: There is no current event loop + self.main_event_loop <span class="o">=</span> asyncio.get_event_loop<span class="o">()</span> +<span class="o">[</span>...<span class="o">]</span> +</pre></div> +</div> +<p>However, some projects go further and use <code class="docutils literal notranslate"><span class="pre">filterwarnings</span></code> option +to make (some) warnings fatal:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="o">====================================</span> <span class="nv">ERRORS</span> <span class="o">====================================</span> +_____________________ ERROR collecting tests/test_sync.py ______________________ +tests/test_sync.py:577: <span class="k">in</span> <module> + class ASGITest<span class="o">(</span>TestCase<span class="o">)</span>: +tests/test_sync.py:583: <span class="k">in</span> ASGITest + async def test_wrapped_case_is_collected<span class="o">(</span>self<span class="o">)</span>: +asgiref/sync.py:135: <span class="k">in</span> __init__ + self.main_event_loop <span class="o">=</span> asyncio.get_event_loop<span class="o">()</span> +E DeprecationWarning: There is no current event <span class="nv">loop</span> +<span class="o">===========================</span> short <span class="nb">test</span> summary <span class="nv">info</span> <span class="o">============================</span> +ERROR tests/test_sync.py - DeprecationWarning: There is no current event loop +!!!!!!!!!!!!!!!!!!!! Interrupted: <span class="m">1</span> error during collection !!!!!!!!!!!!!!!!!!!! +<span class="o">===============================</span> <span class="m">1</span> error <span class="k">in</span> <span class="m">0</span>.13s <span class="o">===============================</span> +</pre></div> +</div> +<p>Unfortunately, this frequently means that warnings coming from +a dependency trigger test failures in other packages. Since making +warnings fatal is relatively common in the Python world, it is +recommended to:</p> +<ol class="arabic simple"> +<li><p>Fix warnings in Python packages whenever possible, even if they +are not fatal to the package itself.</p></li> +<li><p>Do not enable new Python implementations if they trigger any new +warnings in the package.</p></li> +</ol> +<p>If the warnings come from issues in the package’s test suite rather than +the installed code, it is acceptable to make them non-fatal. This can +be done either through removing the <code class="docutils literal notranslate"><span class="pre">filterwarnings</span></code> key from +<code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code>, or adding an ignore entry. For example, the following +setting ignores <code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code> in <code class="docutils literal notranslate"><span class="pre">test</span></code> directory:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">filterwarnings</span> <span class="o">=</span> + error + ignore::DeprecationWarning:test +</pre></div> +</div> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">pytest recipes</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#skipping-tests-based-on-markers">Skipping tests based on markers</a></li> +<li class="toctree-l2"><a class="reference internal" href="#skipping-tests-based-on-paths-names">Skipping tests based on paths/names</a></li> +<li class="toctree-l2"><a class="reference internal" href="#avoiding-the-dependency-on-pytest-runner">Avoiding the dependency on pytest-runner</a></li> +<li class="toctree-l2"><a class="reference internal" href="#using-pytest-xdist-to-run-tests-in-parallel">Using pytest-xdist to run tests in parallel</a></li> +<li class="toctree-l2"><a class="reference internal" href="#avoiding-dependencies-on-other-pytest-plugins">Avoiding dependencies on other pytest plugins</a></li> +<li class="toctree-l2"><a class="reference internal" href="#explicitly-disabling-automatic-pytest-plugins">Explicitly disabling automatic pytest plugins</a></li> +<li class="toctree-l2"><a class="reference internal" href="#expert-disabling-plugin-autoloading-entirely">Expert: disabling plugin autoloading entirely</a></li> +<li class="toctree-l2"><a class="reference internal" href="#typeerror-make-test-flaky-got-an-unexpected-keyword-argument-reruns">TypeError: _make_test_flaky() got an unexpected keyword argument ‘reruns’</a></li> +<li class="toctree-l2"><a class="reference internal" href="#importpathmismatcherror">ImportPathMismatchError</a></li> +<li class="toctree-l2"><a class="reference internal" href="#fixture-not-found">fixture ‘…’ not found</a></li> +<li class="toctree-l2"><a class="reference internal" href="#warnings">Warnings</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="test.html" title="previous chapter">Resolving test suite problems</a></li> + <li>Next: <a href="concept.html" title="next chapter">Advanced concepts</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/pytest.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/search.html b/guide/search.html new file mode 100644 index 0000000..1080ab6 --- /dev/null +++ b/guide/search.html @@ -0,0 +1,142 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Search — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <script src="_static/searchtools.js"></script> + <script src="_static/language_data.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="#" /> + <script src="searchindex.js" defer></script> + + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <h1 id="search-documentation">Search</h1> + + <noscript> + <div class="admonition warning"> + <p> + Please activate JavaScript to enable the search + functionality. + </p> + </div> + </noscript> + + + <p> + Searching for multiple words only shows matches that contain + all words. + </p> + + + <form action="" method="get"> + <input type="text" name="q" aria-labelledby="search-documentation" value="" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="search" /> + <span id="search-progress" style="padding-left: 10px"></span> + </form> + + + + <div id="search-results"> + + </div> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + </ul></li> +</ul> +</div> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/searchindex.js b/guide/searchindex.js new file mode 100644 index 0000000..a70864d --- /dev/null +++ b/guide/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({docnames:["any","basic","buildsys","concept","depend","distutils","distutils-legacy","eclass","expert-multi","helper","index","interpreter","interpreter-maintenance","migration","multi","package-maintenance","porting","preface","pytest","single","test"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":4,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":3,"sphinx.domains.rst":2,"sphinx.domains.std":2,sphinx:56},filenames:["any.rst","basic.rst","buildsys.rst","concept.rst","depend.rst","distutils.rst","distutils-legacy.rst","eclass.rst","expert-multi.rst","helper.rst","index.rst","interpreter.rst","interpreter-maintenance.rst","migration.rst","multi.rst","package-maintenance.rst","porting.rst","preface.rst","pytest.rst","single.rst","test.rst"],objects:{},objnames:{},objtypes:{},terms:{"0":[0,2,3,4,5,6,8,10,12,14,18,19,20],"0420":3,"0x00007f748bc47740":20,"0x00007fb5db746740":20,"0x03000000":20,"0x03030000":11,"1":[0,2,3,4,5,6,8,9,12,18,19,20],"10":[5,8,10,12,20],"10000":2,"10_p3":16,"11":[2,20],"110":5,"117":20,"119":20,"12":[2,5,8,16,18],"13":[5,18,20],"131":5,"135":18,"13_p3":16,"14":[8,20],"143":5,"14349":16,"148":5,"16":[16,20],"17":8,"18":8,"180":20,"187":20,"18_p9":16,"193":20,"1999":[0,2,3,4,5,6,8,14,19],"2":[0,2,3,4,5,8,9,10,11,12,13,14,16,17,19,20],"20":12,"20120407":[2,8],"2017":8,"2020":[0,2,3,4,5,6,8,13,14,19],"2022":[5,13],"208":0,"23":20,"24":[2,8,20],"25":20,"26":8,"27":[2,8],"29":5,"292":5,"2934":20,"2_7":[3,4,5],"2_pkg_setup":2,"2d":14,"2to3":6,"3":[0,2,4,5,6,8,9,10,11,12,13,14,15,17,18,19,20],"30":5,"31":2,"34":20,"360":2,"38":5,"3_":[3,4],"3_6":[5,14],"3_7":[5,14],"3_8":5,"3_p30":0,"4":[0,3,5,8,9,10,11,12,14,20],"42":2,"425":5,"48":5,"4_p1":16,"5":[0,2,5,8,9,11,12,14,18,19,20],"517":[6,10,12],"54":20,"577":18,"583":18,"596":20,"5a":20,"6":[0,1,2,3,4,5,6,8,11,12,14,16,18,19,20],"655482":0,"66":20,"6e5e8a57628095d8d0c8bbb38187afb0f3a42112":2,"7":[0,1,2,3,4,5,6,8,9,10,11,12,14,15,16,18,19,20],"70":2,"717":5,"73":20,"74":20,"7m":16,"8":[0,1,2,3,4,5,6,8,9,10,11,12,19,20],"80":5,"85":20,"87":20,"9":[2,5,10,12,20],"90":[2,14],"9_p2":16,"abstract":[7,14],"boolean":5,"break":[15,16],"byte":[10,16],"case":[0,2,3,4,5,6,7,8,9,11,13,14,16,18,19,20],"catch":5,"class":[5,16,18],"default":[1,2,5,6,7,8,9,12,13,14,15,18,19,20],"do":[0,3,4,5,6,8,9,11,14,15,17,18,19,20],"export":[0,2,5,19],"final":[2,4,5,9,12,13,19,20],"function":[0,1,4,6,7,8,10,11,13,14,16,19,20],"g\u00f3rny":10,"import":[0,3,4,5,6,7,11,13,14,16,18,20],"long":[5,11,12],"micha\u0142":10,"new":[2,5,6,9,10,11,13,16,18],"null":20,"public":[0,2,3,4,5,6,8,14,19],"return":[0,2,8,16,20],"short":[13,18],"static":8,"switch":[9,12,13,20],"throw":16,"true":[0,2,5,6,8,13,16,20],"try":[1,6,8,9,11,20],"var":20,"while":[0,2,3,4,5,6,7,8,11,12,14,16,17,18,19,20],A:[0,2,4,5,6,8,10,11,15,18],As:[3,5,6,7,8,11,13,15,16,18,19,20],At:[2,5,12,15,17],But:20,By:[5,6,11],For:[0,1,2,3,4,5,6,7,8,9,11,12,13,14,16,18,20],If:[2,3,4,5,6,7,8,9,11,12,13,14,15,16,18,19,20],In:[0,2,3,4,5,7,8,10,11,12,14,16,18,19,20],It:[0,1,3,4,5,6,7,9,11,12,13,14,18,19,20],Its:12,No:[3,5],Not:18,On:11,One:20,That:[2,20],The:[0,1,2,3,4,6,7,8,9,10,11,12,13,14,15,16,18,19,20],Their:[5,6,9],Then:12,There:[3,5,8,9,16,18,20],These:[6,7,12,13,18,20],To:[5,6,8,9,12,16,18,19,20],With:[6,20],_:[5,20],_____________________:18,______________________:18,__import__:3,__init__:[3,5,9,18],__legacy__:5,__main__:20,__name__:3,__path__:3,_all:[5,8],_distribut:5,_do_pars:5,_feedparser_sgmllib:9,_get_vers:5,_hashtabl:5,_install_setup_requir:5,_lib:5,_make_test_flaki:10,_multical:20,_overridesdir:14,_pytest:[18,20],_python_all_impl:12,_python_impl_support:12,_rc:2,_run_cod:20,_run_module_as_main:20,_tslib:5,abil:[5,6],abl:[3,12,15],abort:10,about:[6,13],abov:[0,1,6,8,12,13,15,19,20],absolut:[0,1,9,15,19],accept:[0,4,5,6,9,12,15,16,18],access:[0,10,11,18],accompani:11,accord:8,account:[2,8,20],acct:2,achiev:[0,8,11,16],across:5,act:3,action:5,activ:[8,17],actual:[5,6,7,8,9,11,12,18,20],ad:[10,11,13,14,18],add:[2,5,6,8,12,15,19,20],addit:[2,4,6,8,9,10,11,12,13,18,20],addition:[1,5,11,14],addnod:3,addopt:5,address:[6,12,16],adishatz:4,adjust:[9,11,16],admin:[2,8],advanc:10,advantag:[18,20],affect:[9,14],aforement:[7,13,16],after:[5,6,9,12,13,16],afterward:[11,14,15],again:[2,20],against:[0,7,9,11,12,14,19,20],aggress:12,agnost:2,aim:[5,11,15,17],aiohttp:[5,18],alabast:[5,6],alias:16,alik:[6,11,13],all:[0,1,2,3,4,5,6,7,8,9,11,12,13,14,15,16,18,19,20],allow:[7,20],allow_test:20,alon:11,along:[2,5,6,7,11,13,19],alongsid:6,alpha:[0,2,3,4,5,6,8,12,14,19],alreadi:[5,9,12,14,20],also:[1,3,4,5,6,7,8,9,11,12,13,14,16,18,20],alter:18,altern:[3,5,6,8,10,16,17,20],altogeth:20,alwai:[5,6,8,11,13,17],am:14,amd64:[0,2,3,4,5,6,8,12,14,19],among:17,amount:[11,20],an:[0,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,19,20],analysi:[2,19],ani:[1,2,3,4,5,6,7,10,14,16,18,20],announc:12,anoth:[0,8,9,12,14,16,18,20],anticip:15,anymor:[5,8,11],anyth:9,anywai:16,anywher:5,apach:[0,2,4,5,8],apb:2,api:[0,2,7,9,10,11,13,14],app:[0,2,4,5,8,12,14,15],append:[5,14],appli:[1,4,5,6,7,12,15,18,19,20],applic:[2,4,9,12],approach:[3,5,8],appropri:[0,2,4,5,6,7,9,11,15,19],ar:[0,1,2,3,4,5,6,7,8,9,11,12,13,14,15,16,17,18,19,20],arab:19,arabey:19,arabic2tran:19,arbitrari:[2,13],arch:[2,8,12],archiv:[0,2,4,5,19,20],argcomplet:5,argpars:5,argument:[4,6,10,13,16],argv:5,arm64:[0,2,3,4,5,6,8,14,19],arm:[0,2,3,4,5,6,8,19],around:[3,5,6,12,20],artifact:5,asgiref:18,asgitest:18,ask:[12,15],assert:10,assign:1,assum:[1,5,6,9,13,19,20],async:18,asyncio:[11,18,20],attempt:[5,16,20],attr:5,attribut:[3,10],author:[0,2,3,4,5,6,8,9,10,12,14,19],autoload:10,autom:2,automak:16,automat:[3,5,6,10],autoreconf:16,autotool:[0,6,10,16,19],avail:[4,5,6,8,12,13,17],avoid:[5,6,8,10,15,16,17,20],awai:[6,7],b64_encodebyt:16,b64decod:16,b64encod:16,b:0,back:[3,6,16],backend:[4,10,12,13],backport:[4,6,10,12],backtrac:20,backward:[5,11,12,16],bad:[9,16],badurl:16,ban:13,base:[5,8,10,12,14,15,19,20],baselin:12,basemap:19,bash:[0,4,5,7,8,9,19],basi:7,basic:[9,10,20],bdepend:[0,1,2,5,6,8,12,14,18,19],becam:[4,11],becaus:[2,6,15,18,20],becom:[4,11,12],been:[6,8,11,12,13,14,18],befor:[1,3,4,8,9,10,12,14,16,20],beforehand:5,beginn:17,behav:[5,8],behavior:[8,11,16],being:[1,3,6,7,8,9,10,11,12,15,16,18,20],beings:8,belong:20,below:[4,8],besid:[2,4,6,7,11,14,18],best:[0,5,12,16,17,18],better:[3,6,11,13,14],between:[1,3,5,8,10,11,12,13],bewar:20,beyond:17,bidirect:11,big:8,bin:[1,2,7,8,9,12,19,20],binari:[9,12],bind:[0,2,5,8,14,19],bindir:8,binpkg:12,bison:8,bit:[1,12,17],bitprophet:6,bleach:5,block:[0,8,13,20],bmrblib:2,boltzmann:2,boost:[2,7],bootstrap:[5,6,10],both:[0,3,5,6,7,8,12,13,16,17,18,19,20],bottom:5,bound:[3,11],box:[11,13],brace:4,branch:[0,16,20],breakag:[5,20],broken:[3,5,6,20],brython:11,bsd:[0,2,5,6,8,14,19],bu:0,bug:[0,5,6,12,20],buggi:14,build:[1,3,9,10,11,16,20],build_config:2,build_dir:[2,3,5,14],build_ext:[5,6,20],build_meta:5,build_pdb2pka:2,buildscript:2,buildtool:[2,19],built:[0,3,5,6,7,8,11,12,14,17,19,20],builtin:2,bump:[12,15],bundl:[2,12],byte_compil:9,bz2:[2,8,19],bzip2:8,c:[2,5,6,8,9,14,20],cach:14,cachedir:20,cairo:14,calcul:2,call:[0,1,2,3,6,7,8,9,10,11,13,14,16,18,19,20],caller:20,can:[1,2,3,4,5,6,7,8,9,10,11,12,13,14,16,18,19,20],cangjian:14,cannot:[2,4,9,11,20],cantera:2,canva:14,capabl:0,captur:[18,20],care:[2,5,7,9,15],carri:[3,15],cat:[2,3,5],caus:[3,4,5,8,9,13,18,20],cc:[2,9],cc_flag:2,cd:[2,5,9,12],ceas:20,certifi:[8,12],cf:12,cffi:10,cfg:[5,6,18],cflag:[9,20],cgit:0,chang:[5,6,8,9,10,11,13,14,15,20],chapter:[2,8,9],chardet:[5,8],check:[5,6,9,12,13,16,17,20],checklist:[7,10],checkout:[5,12,20],cheetah3:2,chemic:2,chemistri:2,cherri:12,chewi:2,choic:[2,6,13,20],choos:[10,11,14],chose:13,chosen:12,chrpath:[2,8],ci:[5,20],cinnamon:0,circular:12,classifi:6,clean:[6,12,13],cleanli:[6,12],cleanup:13,clear:12,clearli:20,cli:5,client:[2,8,9,11,14],clone:12,close:5,closest:6,cmake:[0,6,19],cmake_src_configur:[9,19],cmake_src_instal:9,cmd2:5,cmd:5,co:10,code:[0,1,3,5,6,7,8,9,11,12,13,14,16,18,19,20],collada:5,collect:[6,18,20],collid:[3,18,20],collis:3,color:5,colorama:5,coloredlog:5,column:5,com:[0,2,4,5,6,8,12,14,16,20],combin:[0,2,5,10,11,12,13,17,18,19,20],come:[5,13,18],comma:18,command:[10,14,18],commit:[2,20],common:[0,3,5,6,7,10,11,12,13,16,17,18,19,20],commonli:[1,2,3,5,6,9,11],compar:16,compat:[0,2,3,4,5,6,7,9,11,12,13,16,19],compet:11,compil:[5,6,10,11],complet:[0,5,16,17],complex:[7,19],compon:[2,3,8,11,14,16],composit:19,compress:5,compris:5,conceiv:3,concept:[1,5,10],concern:3,condit:[3,6,10,18,20],condition:[0,1,2,5,7,11,14,15,18,19],conf:[5,6],config:[5,9,12],configfil:20,configur:[5,6,8,13,14,20],confirm:20,confus:18,connect:20,consid:[2,3,6,7,8,12,14,16],consist:[1,6,9,13,14,15],console_script:[5,6],construct:[2,4,8,19],consum:[4,6,20],contain:[3,4,5,6,7,12,13],content:3,context:19,continu:[8,12,20],contrari:16,control:[2,4,5,18],conveni:[5,6,18],convers:[5,6],convert:[6,8,13],convinc:20,copi:[3,5,6,9,11,19],copyright:[0,2,3,4,5,6,8,14,19],core:[2,5,20],coreutil:8,correct:[1,5,6,9,10,18,19],correctli:[0,5,6,7,9,11,13,16,20],correspond:[5,12],cost:5,could:[0,2,3,5,6,8,9,16,19],cov:[5,18],cover:[1,5,6,13],coverag:[5,15,18],cpp:2,cpython:[1,4,5,9,11,13],creat:[1,3,4,5,6,7,12,13,16],creativ:10,cropgtk:9,cruft:13,cryptic:5,cryptographi:8,csound:19,current:[0,4,5,6,11,12,13,15,18,20],custom:[2,6,10,13,18],cxx:2,cxx_flag:2,cxxflag:2,cycl:10,cyclic:12,cygwin:[5,6],cython:[2,14,19],d:[0,2,3,5,8,9,14,18],daemon:[2,8],danger:16,dash:5,dask:[5,18],data:[0,2,5,6,9,16,19,20],databas:[2,4],date:[12,17,20],dateutil:4,dbpathprefix:2,dbu:[0,2],dbuild_python_interfac:19,dbuild_python_opcod:19,deal:[2,7,8,10,15],debug:2,decid:12,declar:[0,1,2,3,5,6,8,9,12,14,18,19],declare_namespac:3,decode_usenet_chunk:20,decodebyt:16,decor:20,dedic:[5,6,14],deep:[12,17],def:[18,20],default_src_prepar:5,defin:[0,1,5,6,11,19],definit:6,delet:[2,3,14],demonstr:[0,19],dep:[0,5,13,15,18],depend:[1,3,6,7,9,10,11,12,13,15,17],deprec:[10,11,13],deprecationwarn:18,deriv:[5,6,7],desc:12,describ:[0,6,8,9],descript:[0,2,3,4,5,6,8,14,19],deselect:18,design:[1,19],desir:[13,16,20],destdir:[2,8,9],detail:[2,7,9,11,13,16,20],detect:[5,9,20],detector:5,determin:[5,6,7,11,19,20],dev:[0,2,3,4,5,6,7,8,11,12,13,14,15,18,19,20],devel:8,develop:[0,1,7,11,12,15,17,20],devic:[2,8],devmanu:20,dict2db:19,dict:[5,19],dictionari:[6,19],did:[3,13,16,20],die:[2,3,5,8,9,14,18,20],diff:12,differ:[0,1,3,5,9,10,11,18,20],dir:[5,14],direct:[6,7,14],directli:[1,5,6,7,9,11,13,16,18],directori:[3,6,9,10,11,12,13,14,16,18],disabl:[2,5,8,10,12,14,19,20],disable_tiff:5,disable_webp:5,discontinu:12,discourag:[3,6],discoveri:[5,18],disjoint:10,disk:20,dist:5,distfil:[16,19],distinguish:13,distribut:[0,2,3,4,5,6,7,8,14,16,17,19,20],distutil:[1,3,4,10,13,14,18,19],distutils_all_subphase_impl:8,distutils_arg:[5,13],distutils_enable_sphinx:[5,8],distutils_enable_test:[4,13,20],distutils_in_source_build:6,distutils_install_for_test:[6,12,13,18,20],distutils_single_impl:5,distutils_strict_entry_point:6,distutils_use_pep517:[5,13],distutils_use_setuptool:[5,13],django:[16,20],dndebug:20,doabl:3,dobin:[2,9],doc:[2,5,8,19],docinto:5,docker:12,docompress:5,document:[2,8,10,11,14,17,20],dodir:9,dodoc:[2,5],doe:[1,2,3,5,6,8,9,11,12,14,15,16,18,20],doin:9,dom:11,domain:[3,20],doman:2,don:[5,13],done:[1,5,6,8,9,12,14,18,20],doubl:19,down:11,downgrad:8,download:[0,2,8,14],downstream:20,dpython3_include_dir:13,dpython3_librari:13,dpython_dest:9,dpython_execut:9,dpython_include_dir:9,dpython_librari:9,draw:14,driver:2,drop:[11,16],duali:19,due:[10,12,14,18],dump:20,duplic:[5,14],dure:[3,6,7,12,13,18],dynam:2,e:[1,2,3,5,6,7,8,9,10,11,12,13,14,15,16,18,19],each:[5,6,7,11,14],eapi:[0,2,3,4,5,6,8,10,14,19],eappli:2,eapply_us:2,earli:[5,7,8,12],earlier:[3,13],eas:[12,15],easi:[3,5,16,20],easier:7,easiest:[5,19],easili:[5,14,18,20],eautoreconf:[14,16],ebuild:[0,1,4,5,6,7,12,13,14,15,16,17,19,20],echo:8,eclass:[0,1,2,4,5,6,8,9,10,13,14,17,18,19],econf:[5,19],econf_sourc:14,ecosystem:[15,17],ed:[2,9,15],editor:5,effect:[8,11],effici:5,egg:[5,6,18],eigen3:2,eigen:2,einstalldoc:[5,8,14],either:[1,2,5,7,8,9,11,13,18],electrostat:2,elibc_freebsd:2,elibc_glibc:8,els:[2,8,11,16],emak:[5,8,9],emb:16,embed:[2,9,11],empti:4,en:5,enabl:[0,4,6,7,8,10,11,12,14,15,18],enable_tiff:5,enable_webp:5,encod:[5,16],encodebyt:16,encourag:[5,15],end:[5,6,7,9,12,14,18,20],energi:19,enforc:[1,4,5,7,8,11,18],enough:5,ensur:[0,5,6,9,14,19],entir:[3,5,9,10,13,14,20],entri:[5,18],entropi:9,entry_point:[6,18],env:[9,12],env_var:2,environ:[0,5,6,10,11,13,14,16,18,19],envvar:18,eof:[2,3,5],eol:15,ep:5,eprefix:[2,8,9],epydoc:8,epytest:[5,6,8,12,18,20],epytest_deselect:18,epytest_ignor:18,epython:[1,2,5,8,9,12,13,18],equal:20,equival:[6,8,9,13],error:[0,2,5,9,13,16,18,20],escap:[4,13,19],escon:2,eselect:8,esetup:[5,8],especi:[5,18,20],establish:[1,5,13,20],etc:1,eutil:2,evalu:13,even:[3,8,9,11,18,20],event:[3,18],event_loop:18,eventlet:18,eventu:[4,12],everi:[5,6,8,12,14,16,20],everyth:[2,13],ex:12,exact:[5,11,19],exactli:[0,7],exampl:[0,4,5,6,7,8,9,10,11,12,16,17,18,19],except:[6,7,9,11],exclud:5,exec:[1,8,9,11,12,20],exec_prefix:16,execut:[1,5,6,7,9,11,12,13,14,20],exist:[5,7,10,11,12],exit:[16,20],expans:4,expect:[6,18,20],experiment:5,expert:[5,10,14],explain:[0,1,6],explan:20,explicit:[3,4,5,6,19,20],explicitli:[1,3,5,7,8,10,13,20],exploit:16,expos:[5,6],express:[0,4,8,13,19],ext:5,extend:[5,11,12],extend_path:3,extens:[6,7,8,9,11,14,15,16,20],extern:[2,5,6,7,11,12],extra:[5,6,10],extra_inc_dir:2,extra_opt:19,extran:5,extras_requir:5,extrem:6,ez_setup:5,f90_interfac:2,f:[2,9],face:[12,20],facil:6,facilit:[5,9],fact:5,fail:[0,2,5,8,9,11,16,18,20],failur:[5,10,18],fairli:[2,15,19],fall:[6,16],fallback:6,fals:[2,5,8,16],far:[3,19],fastdl:2,faster:5,fatal:[18,20],fdl:[0,19],feasibl:15,featur:[0,4,5,6,8,11,12,13,19,20],februari:13,feel:[5,15],fetch:[12,20],few:[2,4,6,18,20],fewest:12,fi:[0,2,5,8,14,19],file:[0,2,3,5,6,7,8,9,10,11,12,13,14,16,18,19],filesdir:2,fill:17,filterwarn:18,finalize_opt:5,find:[0,2,3,4,6,14,18,20],find_packag:5,fine:[3,5,12,16],finish:18,fionet:14,first:[4,5,6,7,11,12,15,16,18,20],firstli:20,fish:5,fit:[6,20],fix:[5,6,10,11,12,16,18,20],fixm:5,fixtur:[10,12],flag:[0,5,7,8,9,10,11,12,14,15,19,20],flake8:[5,18],flaki:[18,20],flex:8,flexibl:[5,7],flit:[6,7,12,13],flit_cor:[5,12],focu:14,folder:5,follow:[0,1,3,4,5,6,7,8,9,12,13,16,17,18,19,20],foo:7,footprint:5,forbidden:5,forc:[5,6,8,9,12,13,18,20],fordfrog:19,foreach:5,fork:[0,11,12,20],form:[1,12,17],format:[8,12],former:[5,8,13,20],fortran:2,fortran_need:2,fortran_standard:2,fortranflag:2,forward:[3,12],found:[3,5,6,9,10,15],foundat:14,four:[9,13,19],fourth:13,fragment:16,framework:[2,3,5,11,17],free:[2,15,20],freedesktop:0,freezegun:[4,18,20],freezer:18,frequent:[5,18],freshli:3,from:[0,1,2,3,4,6,7,8,10,11,12,14,15,16,18,19,20],ftp:[2,19],full:[1,2,4,5,7,13,20],fulli:[4,5,7],func:[2,8],funcsig:11,further:18,furthermor:[0,2],futur:15,g:[1,2,3,5,6,7,8,9,10,11,12,13,14,15,16,18,19],ga:14,gain:[2,18],gap:17,gaupol:8,gc:11,gemato:15,gener:[0,1,2,3,4,5,6,7,8,9,11,12,13,14,15,18,19,20],gentoo:[0,2,4,5,6,8,9,11,12,14,15,16,17,18,19,20],get:[0,5,6,13,18,20],get_event_loop:18,get_libdir:[2,8],get_nproc:18,get_path:16,get_python_inc:16,get_python_lib:16,get_udevdir:[2,8],getar:2,getcc:[2,9],getcxx:2,getfc:2,getranlib:2,getter:[9,13,16],gettext:8,gfx:2,gh:20,gi:14,git:[5,12,20],github:[0,2,4,5,6,8,12,14,17,19,20],gitlab:[2,8],give:19,given:13,glib:2,global:[0,1,5,8,13,14,18,19],gna:2,gnome2:[0,4,14],gnome2_src_configur:14,gnome2_src_instal:14,gnome2_src_prepar:14,gnome:[0,4,14],gnu:[0,2,3,4,5,6,8,14,19],go:[2,3,8,12,17,18],goal:[8,20],gobject:0,goe:[12,20],goocanva:14,good:[11,17,20],got:[10,13],gp:[2,8],gpl:[0,2,4,8,14,19],gpsd:[2,8],gpsd_group:[2,8],gpsd_user:[2,8],gpyutil:12,grab:[5,13],grace:2,gracefulli:[4,8,12],graph:12,greater:[5,7],greenlet:[10,18],grep:5,gross:13,group:[2,6,12,13,18],gtk2:19,gtk:14,guarante:[5,6],guess:20,gui_script:6,guid:[3,5,16,17],gz:[0,2,4,5,6,8,14,19,20],h:[8,9,19],ha:[2,3,5,6,7,11,12,13,14,15,18,20],hack:[5,6,7,13],had:2,hand:[11,13],handl:[4,5,6,8,13,14],handler:5,hang:8,happen:[2,3,4,6,7,8,11,12,19,20],hard:[5,8,12],hardcod:1,harder:8,hardest:0,hardwar:11,harmless:3,has_vers:[0,2,8],hashtabl:5,have:[0,2,3,4,5,6,7,8,9,11,12,14,15,16,18,19,20],header:9,heavi:6,help:[5,17,20],helper:[4,5,10,14,19],henc:[2,5,14],hepforg:19,here:[6,8,14,19],hexvers:[11,20],high:[2,12,15,19],highlight:[0,16,19],histor:[5,6,13,16],hit:16,home:[6,12,13],homepag:[0,2,3,4,5,6,8,14,19],hook:5,horrend:20,host:0,hous:11,how:[5,20],howev:[1,3,5,6,7,8,9,11,12,13,15,16,18,19,20],hppa:[0,2,3,4,5,6,8,14,19],html:[0,5,8],http:[0,2,3,4,5,6,8,9,12,14,16,19,20],httpbin:[8,18],human:8,humanfriendli:5,hybrid:10,hypothesi:[5,20],hz1jw:19,i18n:14,i:[5,6,7,11,12,14,16,18,20],ia64:[0,2,3,4,5,6,8,14,19],idea:20,ideal:[11,15,20],ident:5,idna:8,ignor:[3,4,8,18,20],imag:[5,9],imagin:8,immedi:[4,5,19],impact:16,impl:[1,5,10,13],implement:[0,1,3,4,5,6,7,10,14,17,18,19,20],impli:[2,9,11],implicit:[14,20],implicitli:[0,3,5,8,12,19],importerror:[5,6,11],importlib:[6,11],importlib_metadata:[4,5,6],importpathmismatcherror:10,improp:17,improv:[11,17],incdir:8,includ:[2,3,4,5,6,7,9,12,15,16,17,18,19,20],incompat:[3,6,11,16,18,20],inconsist:[12,20],incorrect:[5,6],increment:11,inde:13,independ:[2,6,7,14,19],index:10,indic:[1,5,6,11,12,13,18,20],indirect:5,individu:[2,5,11,18],infer_vers:5,inflect:5,info:[0,6,18],inform:[3,5,6,10,13,16,20],inherit:[0,1,2,3,4,5,6,7,8,9,13,14,16,18,19],ini:[5,12,18,20],init:5,initi:20,inject:[3,5,19],inlin:[2,7,14],inplac:6,insert:16,insid:[0,1,3,5,6,9,12,14,18,19],insinto:9,inspect:5,instal:[0,3,7,8,10,11,12,13,15,16,18],install_requir:[5,6],instanc:13,instead:[2,3,5,6,7,8,9,13,14,16,18,19,20],insuffici:18,intact:5,integr:[5,8,10,11],intend:[5,16],intent:18,interact:11,interest:[6,8,20],interfac:[3,6,11],intermedi:5,intern:10,internet:[10,18],interpret:[0,1,2,5,6,7,9,10,13,14,15,16,18,19],interrupt:18,interspers:6,interv:5,intro:8,introduc:[5,11],introspect:0,invalid:0,investig:8,invoc:18,invok:[5,18],involv:[8,13],io:[2,4,5,8,14,19],ipaddress:11,ironpython:11,irrelev:[5,20],iso:8,isol:5,isort:20,issu:[3,5,6,13,16,18,20],item:20,its:[0,1,2,3,4,5,6,7,8,11,12,15,16,18,20],itself:[3,5,6,8,9,12,18],ius:[0,2,3,4,5,8,14,19],iwdevtool:5,j1:5,januari:13,jaraco:[3,5,12,18],java:11,javascript:11,jazzband:5,job:[2,18],json:5,just:[5,6,11,13,20],jython:11,keep:[5,12,15,17],kei:[5,18,19],kept:12,kernel:14,kernel_linux:8,keyword:[0,2,3,4,5,6,8,10,14,19],kind:[3,7,9,11,20],kinet:2,kitti:9,know:[13,16,20],known:[4,6,16,20],kvm:14,la:14,lack:[9,20],lambda:20,land:9,lang:[2,8,11,12,19],languag:[2,11,15],larg:[5,15,18],last:[3,5],later:11,latest:5,latter:[2,5,8,13,18,20],layer:[5,14],layout:[3,6,13],ldap:2,ldb:2,ldflag:2,lead:20,leak:20,least:[0,8,15,20],leav:6,leftov:6,legaci:[10,13],length:16,less:20,let:[2,4,8,16,19],level:[3,5,9,11],levenshtein:8,lgpl:[0,2,5,14,19],lib64:9,lib:[2,3,5,7,9,16,18,20],libboost_python:7,libbsd:2,libcangji:14,libdir:[2,8,9],libdirnam:2,libfmt:2,libimag:9,libpcap:2,libpcr:2,libpython:[7,16],librari:[0,2,3,4,5,8,9,11,14,19],libsecret:0,libtool:14,libudev:2,libusb:2,libx11:2,libxslt:2,licens:[0,2,3,4,5,6,8,10,14,19],life:10,lightweight:[4,5],like:[0,2,4,5,6,8,11,15,16,19,20],limit:[4,6,15,17],line:[0,3,5,13,15,16,19,20],link:[5,7,9,16],linker:[5,9],linkflag:2,linux:[0,2,3,4,5,6,8,9,14,16,19,20],linux_distribut:11,linuxmint:0,list:[1,4,5,8,12,13,18],liter:[0,4,19],littl:[5,6,18],live:12,ll:[4,14],load:[3,7,9,18],local:[1,2,3,5,8,9,12,13,14,18,19,20],localize_pydatetim:5,locat:[3,5],log:5,logic:[5,6,12],lollypop:4,longer:[3,4,5,6,13],look:[0,6,8,18,19,20],lookuperror:5,loop:[2,5,18],looponfail:18,lot:[11,15],lp:20,lpython3:16,lxml:8,lzma:11,m68k:[0,3,4,5,6,8,19],m:[5,18,20],machin:14,maco:[0,3,4,5,6,8,19],made:[3,13,14,16,19],mai:[3,5,6,8,12,13,15,16,20],main:[9,20],main_event_loop:18,maintain:[5,10,11,12],mainten:10,major:[4,5,6,7,11,12,20],make:[2,3,4,5,6,7,12,13,15,16,18,19,20],make_wrapp:[2,9],makefil:14,makeopt:18,makeopts_job:[2,18],man:16,manag:[0,4,5,6,8,9,20],manbuild:[2,8],mani:[2,5,8,14,15,16,20],manipul:5,manpag:5,manpow:15,manual:[2,5,6,10,12],map:[2,5,6,8,18],march:13,mark:[15,18,20],marker:[5,10],martinblech:5,mask:[12,15],master:[5,20],match:[0,2,4,6,8,9,11,12,15,19],matplotlib:[2,5,19],max_atom:2,maximum:5,mayb:20,mayhem:[3,20],md:2,me:16,mean:[0,1,2,5,7,8,11,15,16,18,19,20],meaning:6,meant:[1,13],mechan:[7,11],media:[0,2,8],member:15,mere:[5,7],meson:[0,4,7,10],messag:[5,20],met:16,metadata:[5,6,14,19],method:[3,5,11,13,16,18,20],mgorni:12,microcontrol:11,micropython:11,might:18,migrat:[5,10],minfx:2,minim:[5,11,15],minimum:[0,15,19],minor:[11,20],mint:0,mip:[0,2,3,4,5,6,8,19],mirror:[2,4,5,6,8,14,19,20],misbehav:6,misc:[2,8],miscompil:5,miss:[3,5,6,9,10,11,12,13,17,18],mistak:5,mit:[5,6],mix:3,mkdir:[3,12],mock:[0,4,8,11,12,18,20],mocker:18,mode:[6,10,13],model:7,modern:[4,5,6,18,20],modif:5,modifi:[5,6,11,20],modul:[3,4,5,6,7,8,10,11,14,15,16,18,20],modulenotfounderror:3,modulesdir:2,molecular:2,molmol:2,moment:[5,12,13,15],mongo:2,mongodb:[2,4],more:[1,3,7,9,11,13,16,18,19,20],most:[0,1,3,5,6,9,11,13,14,17,18,19,20],mostli:17,move:[0,5,12],mozilla:5,mpi:5,mrzechonek:2,much:[2,5,7,20],multi:[1,5,10,13,19],multibuild:14,multipl:[3,4,5,7,10,14,17,18,20],multiprocess:18,music:4,must:[0,1,2,5,6,7,8,11,18,19,20],mutual:3,my_p:2,my_pn:9,mycmakearg:[9,13,19],myconf:[2,8],mydistutilsarg:13,myesconsarg:[2,8],myself:20,mysql:[4,14],n:[2,18],name:[1,2,3,5,6,7,8,9,10,11,14,16,20],namespac:[10,18],namespace_packag:3,nativ:11,natur:[2,5,8],nautilu:0,ncurs:[2,14],nd:2,nears:12,necessari:[0,2,3,5,6,8,9,11,12,13,14,15,18,19,20],need:[0,2,3,4,5,6,7,8,9,11,12,13,14,15,16,18,19,20],nemo:0,nest:18,net:[2,8,11,14,19],netloc:16,network:[5,6,18,20],never:[6,11,13],newer:[3,6,12],newli:15,newlin:16,next:[12,15,18],ninja:8,nmr:2,no_network:20,no_waf_libdir:2,non:[1,3,5,6,7,9,12,14,16,18,20],none:[2,5,6],nongnu:[2,8],nor:[11,17],normal:[0,3,5,8,9,14,19],nose:[4,5,12,20],nosetest:20,nostrip:[2,8],notabl:5,note:[3,4,5,6,7,8,9,10,11,13,14,15,16,18,19],now:[3,5,6,8,13,14,20],nowadai:[9,12,13],nox:12,number:[5,7,12,18],numdifftool:2,numpi:2,nurl:16,o0:20,o:2,object:[2,11,19],obligatori:12,obsolet:[12,13],obviou:[1,20],ocassion:9,occur:[7,18],offset:9,often:[5,12,20],old:[2,4,5,6,8,10,12,16,20],older:[4,11],omit:[5,15,16],onc:[0,4,5,8,11,12],one:[0,1,2,4,5,6,7,8,9,11,12,16,17,18,19,20],ones:12,onli:[0,1,2,3,4,5,6,7,8,9,11,12,14,18,19],opal:2,open:[2,16],openbabel:2,opendx:2,openldap:2,openvpn:9,oper:[5,17],opposit:[8,11,13],optimize_flag:2,option:[4,5,6,8,13,15,18,19],optional_packag:2,order:[0,2,4,5,7,9,12,13,14,15,19],org:[0,2,3,4,5,6,8,9,12,14,19],organ:3,orient:2,origin:[5,9,11,12,16],other:[0,2,3,4,5,7,9,10,11,12,13,14,16,17,19,20],otherwis:[3,5,6,7,8,9],ought:16,our:[6,12,18,20],out:[8,9,10,11,12,13,14,15],outdat:4,outofboundstimedelta:5,output:[5,6,9,16,20],outsid:[14,19],over:[11,12,18,19],overrid:[5,9,14,20],own:[5,12,20],p:[0,2,3,4,5,6,8,14,18,19,20],pace:11,packag:[0,1,4,7,8,9,10,11,13,17,18],page:[10,16,17],panda:5,pandas_datetime_to_datetimestruct:5,parallel:10,param:[16,18],paramet:[5,8,16],parametr:18,paremet:5,parent:[3,9],pars:16,parsed_vers:5,parseresult:16,part:[2,3,5,7,8,9,12,13,14,15,18],parti:5,partial:[3,4,9,10,13],particular:[0,1,5,6,11,20],particularli:[0,6,11,13,18,20],pass:[6,8,9,10,13,16,18,20],password:4,patch:[2,5,6,8,11,12,20],path:[1,3,5,6,9,10,12,13,16],pathlib:18,pattern:[12,13,19],pax:8,pbr:6,pch:2,pcre:2,pdepend:[2,8,12],pdm:[5,13],peopl:17,pep517:5,pep8:5,pep:[3,6,10,12],per:5,perform:[2,5,6,11,12,14,19,20],period:13,permit:[3,4,5,6,11,15],pexpect:[0,5],pf:5,phase:[0,1,6,7,8,10,13,14,15,19,20],physic:[5,19],pick:12,pillow:5,pip:[5,12,20],pipelin:[2,20],pkg:9,pkg_config:2,pkg_config_path:16,pkg_postinst:5,pkg_resourc:[3,6],pkg_setup:[0,1,2,8,19],pkgcheck:13,pkgconfig:[0,2,8,14],place:[6,11,12],placehold:13,plain:[2,5,6,13],plan:11,platform:[11,16,20],platinclud:16,platlib:16,platstdlib:16,player:[0,4],pleas:[4,5,6,8,9,12,15,16,18,19,20],plot:19,plu:[0,19],pluggi:20,plugin:[3,5,6,8,10],pm:6,pn:[0,2,4,5,6,8,9,14,19,20],pngcrush:2,poetri:[6,7,13],poetry_cor:5,point:[5,11,12,13,18,20],pointless:5,poisson:2,poissonboltzmann:2,polib:0,popd:20,popt:2,popul:[5,15],port:[5,8,10],portabl:3,portag:[3,5,8,12,14,15,18,20],posixpath:18,possibl:[0,1,2,4,5,6,7,8,9,14,17,18,20],post:[5,6,13],postgr:4,potenti:[12,16,18],power:8,pp:[2,8],ppc64:[0,2,3,4,5,6,8,14,19],ppc:[0,2,3,4,5,6,8,14,19],pr:16,practic:[8,11,12],pre:5,precis:[5,8,9],precompil:12,predict:19,prefac:10,prefer:[1,5,7,8,11,14,15,18,20],prefix:[2,8,9,16,20],pregener:5,prematur:15,prepar:[8,9,19],preprocessor:9,presenc:[3,8,18],present:[5,6],preserv:[6,11],presum:2,prevent:[10,11,19,20],previou:[5,12,13,16],previous:12,primari:18,primarili:[7,11],print:[8,14,18,20],prior:[2,6,8,13,16],privat:13,proactiv:15,probabl:[1,6,8,13,19],problem:[3,4,5,6,8,10,12,16,17,18],problemat:[3,6,10,18],process:[5,12,16,19],produc:[5,12],profil:[6,15],program:[1,2,5,6,11,16,18],programm:[0,15],progress:12,proj:5,project:[0,3,5,7,8,9,10,14,17,18],prone:0,propag:19,proper:[2,8],properli:[5,6,13],properti:20,protocol:[0,2,19],provid:[0,1,3,4,5,6,7,8,9,11,12,13,14,15,16,17,18,20],proxi:[3,14],psf:5,psql:14,psutil:2,pth:3,pub:2,pure:[0,5,6,7,8,10,11,15],purelib:16,purpos:[0,6,9,12,14,16,19],pursu:12,push:12,pushd:20,put:[1,8],pv:[0,2,4,5,8,14,19,20],pwd:12,pwman3:4,py2:[2,8,20],py3:18,py:[2,3,6,7,8,9,10,11,13,14,18,20],py_input_list:20,pybytearray_check:20,pyc:[2,9],pycodestyl:5,pycountri:8,pydiff:8,pyduali:19,pyext:19,pygit2:20,pygobject:[0,14],pyinc:9,pylib:9,pylist_getitem:20,pymol:2,pymongo:2,pynslcd:9,pyo:[2,9],pyopenssl:8,pypa:[6,20],pyperclip:5,pypi:[4,5,6,8,10,11,13],pyproject2setuppi:[5,6,13],pyproject2toml:6,pyproject:[5,7,12],pypy2:[9,11,12],pypy3:[1,3,4,5,6,8,11,12,13,15,18],pyroot:5,pyseri:5,pysock:8,pytabl:5,pytest:[0,4,8,10,12,20],pytest_cach:20,pytest_disable_plugin_autoload:18,pytest_fork:18,pytest_plugin:18,pytest_pyfunc_cal:20,python2:[2,8,9,13,19],python2_7:[2,5,6,8,13,14,19],python2_packag:2,python3:[1,3,5,9,11,12,13,16,18,20],python3_5:8,python3_6:[0,2,4,8,14],python3_7:[4,8],python3_8:3,python3_:[0,1,2,4,5,6,8,12,19],python3_cmd:2,python3_packag:2,python:[6,17,18,20],python_:[5,8],python_cflag:16,python_check_dep:[0,2,8],python_compat:[0,2,3,4,5,6,8,10,12,14,15,19],python_compile_al:[5,8],python_configur:2,python_configure_al:5,python_copy_sourc:[2,14],python_dep:[0,2,3,4,8,10,14,19],python_doex:9,python_dohead:9,python_domodul:[2,3,5,9,12,14,19],python_doscript:[9,14,19],python_export:13,python_fix_shebang:9,python_foreach_impl:[1,2,3,8,14],python_gen:13,python_gen_any_dep:[0,2,8],python_gen_cond_dep:[2,4,5,8,12,13,19],python_gen_impl_dep:4,python_gen_usedep:13,python_gen_useflag:8,python_get:13,python_get_cflag:9,python_get_includedir:[8,9,13],python_get_lib:9,python_get_library_path:[9,13],python_get_python_config:9,python_get_scriptdir:9,python_get_sitedir:[2,8,9],python_includedir:13,python_instal:[2,3,14],python_install_al:[3,5],python_is_python3:[8,13],python_lib:16,python_libpath:13,python_moduleinto:[2,5,9,14],python_multi_usedep:13,python_newex:9,python_newscript:9,python_optim:[2,8,9],python_prepare_al:[5,18],python_req_us:[2,4,5,6,8,14,19],python_required_us:[2,3,4,8,10,14,19],python_scriptinto:9,python_setup:[0,1,2,10,13,14,19],python_single_target:[7,11,12],python_single_usedep:[4,5,13,19],python_target:[5,7,8,11,12],python_test:[6,8,9,12,18,20],python_test_al:5,python_usedep:[0,2,3,4,5,8,10,12,14,18,19],python_wrapper_setup:13,pythonn:1,pythonpath:6,pythonprop:19,pythonx_i:1,pyx:5,pyyaml:2,qa:[6,9,17],qemu:14,qemu_python_instal:14,qmp:14,qsl:19,qt:0,qualifi:7,queri:[10,16],question:[0,7,14,18,20],quick:20,quickli:5,quit:[2,3,4,6,11,12],quot:[4,19],r1:[1,3,4,9,10,12],r1_:5,r1_pkg_setup:[0,2,19],r1_python_compil:5,r1_python_instal:[3,5],r1_python_install_al:[3,5],r1_python_prepare_al:[5,18],r1_src_prepar:18,r1_src_test:5,r:[2,5,9],race:10,rais:5,random:18,rang:[2,5],ranlib:2,rare:[9,18,20],rather:[6,8,17,18,20],rc:2,rdepend:[0,1,2,3,4,5,6,8,13,14,19],re:[5,8,15],reach:[12,15],read:5,readabl:20,readi:[5,12,15],readlin:[2,5,8,14],readm:[2,12],readthedoc:5,real:[3,18,20],realli:[13,15,18,20],reason:[2,4,6,11,18,20],rebas:12,rebuild:6,rebuild_swig:2,recent:[2,3,5,12,20],recip:10,recogn:[5,16],recommend:[2,3,5,7,12,13,14,18,19,20],recurs:[9,15,18],redefin:[5,18],reduc:5,reenabl:12,refer:[0,4,5,9,11,13,14,17,19],refus:11,regard:5,regener:12,regress:5,regular:[7,20],reject:[8,15,16],rel:[5,18],relat:[10,12,13,20],relax:[2,18],releas:[0,2,8,11,12,14,15,16],relev:[5,6,13,17,20],reli:[3,5,6,7,11,20],reliabl:[17,20],remain:[3,7,11,13],rememb:[3,12],remind:6,remot:[12,20],remov:[3,4,5,6,11,12,13,14,15,18,20],renam:[13,16],renamed_shared_librari:2,reorder:13,repeat:[7,14],repeatedli:12,replac:[0,5,6,11,12,13,16],replai:20,replic:14,repoman:13,report:[5,6,9,20],repositori:[0,5,6,12],repres:[3,5],reproduc:20,request:[5,8,10],requier:6,requir:[0,1,2,4,5,7,8,10,11,12,13,14,15,16,18,19],required_us:[0,1,2,3,4,8,13,14,19],rerun:10,rerunfailur:18,resembl:[8,18],reserv:5,resmok:2,resolv:[5,6,10,16,18],resourc:[6,11,12],resourcepath:5,respect:[5,12,14,18],respons:[1,5],restrict:[0,2,5,10,18,19,20],result:[5,6,8,9,12,16,17,18,20],retroact:10,reus:9,revers:[5,7,15],revis:15,rewritten:[5,19],rf:2,right:6,riscv:[6,8,19],risk:15,riverbankcomput:8,rm:[2,3,5,9],root:[0,5,6,13,19],root_numpi:5,rootdir:20,rootpi:5,roughli:[2,9,12,13],routin:14,rpath:2,rpython:11,rst:5,rsync:8,rule:[2,6,8,10,13,14,15],run:[1,2,4,6,7,8,9,10,11,12,13,14,17,20],run_in_build_dir:[2,8,14],runner:[5,10],runpi:20,runtim:[1,2,5,8,10,12,13,14],s390:[0,2,3,4,5,6,8,19],s:[2,3,5,6,7,8,9,12,13,14,16,18,19,20],sabyenc3:20,sabyenc3_wrapp:20,sabyenc:20,safe:[3,13],samba:[2,19],same:[0,2,3,4,5,6,7,8,9,11,12,13,14,16,17,18,20],sample_cod:5,sandbox:[8,20],sanit:[5,16],satisfi:[0,8,12],sbin:9,scan:13,schema:2,scheme:16,sci:[2,5,19],scipi:2,scm:5,scon:[7,8,10],scons_opt:2,scons_target:2,scons_var:2,sconstruct:[2,8],scop:0,scope:[1,5,8,13,18],scp:12,script:[2,5,6,7,8,10,11,12,14,16,19],sdist:[5,20],search:[3,10],second:[7,13],secondli:20,secret:0,section:[5,6,12,16,20],secur:12,sed:[5,8,14,18,20],see:[5,9,16,18,20],seem:20,select:[7,8,18,19],self:[5,18,20],semi:18,sens:2,separ:[2,5,6,7,8,11,14,18],seri:9,serial:[2,5,8],serv:13,server:20,servic:[0,20],session:[3,20],set:[2,4,5,6,7,10,12,14,15,16,18,19,20],setup:[1,6,7,10,13,18,20],setup_requir:[5,18],setuptool:[4,5,7,8,12,13,15,18],setuptools_scm:10,setuptools_scm_pretend_vers:5,sh:[0,2,3,4,5,6,8,19],share:[3,5],shebang:[10,11],shell:[0,5,8,14],shift:[6,11],shlinkflag:2,shorter:4,shortli:1,should:[3,5,6,7,8,9,11,12,13,14,15,16,17,18,19,20],side:[8,11],sidebar:6,signal:[19,20],signatur:11,signifi:18,signific:[12,18],silent:4,similar:[0,2,3,5,14,19,20],similarli:5,simpl:[2,7,13,14,17],simplest:[0,2,5,14,18,20],simpli:[5,16,17,20],simultan:[5,11,17,20],sinc:[2,3,4,5,6,7,11,12,13,15,16,18,20],singl:[1,3,4,6,9,10,14,16,18],sip:8,sip_api_major_nr:8,siplib:8,site:[3,5,6,9,11,16,18,20],six:[4,5,8],skip:[5,8,10,12],skipif:20,slot:[0,2,3,4,5,6,8,11,14,19],slow:11,slowli:[12,15],smaller:5,snappi:2,snapshot:[10,20],snippet:6,snowbal:2,so:[1,5,6,11,12,18,19,20],socks5:8,softwar:[0,4,8,12,14,15,16,20],solari:[0,3,5,6,19],sole:13,solut:[3,4,5,20],solv:[4,17],some:[0,1,2,3,4,5,6,7,8,11,12,13,14,16,18,19,20],someth:[8,9,20],sometim:[5,6,9,11,20],somewher:12,soon:15,sort:2,sound:19,sourc:[2,5,10,12,14,17,20],sourceforg:[14,19],space:20,sparc64:[0,3,6],sparc:[0,2,3,4,5,6,8,14,19],speak:[6,11],special:[4,5,6,16],specif:[0,1,4,5,6,7,8,9,10,11,13,14,15,16,18,19,20],specifi:[0,1,2,5,6,7,8,14,18,19,20],speed:9,spew:20,sphinx:[3,6,8,10,12],sphinx_rtd_them:8,sphinxtrain:9,split:[0,5,13,16],spulec:4,sqlite3:4,sqlite:[4,8],src:[2,9,20],src_:5,src_compil:[2,5,6,8,14],src_configur:[2,5,8,9,13,14,19],src_instal:[2,3,5,8,9,14,19],src_prepar:[2,5,8,9,14,16,18],src_test:[2,5,6,14],src_unpack:3,src_uri:[0,2,3,4,5,6,8,14,19,20],ssl:8,sspl:2,stabil:12,stabl:[12,15],stage:[5,12],stage_dir:2,stand:11,standalon:[5,12],standard:[3,4,6,7,9,10,11,14,16,20],start:[3,5,6,11,12,15,16,20],state:1,statement:5,statist:5,statsmodel:20,std:2,stdin:3,stdlib:[13,16],stemmer:2,step:[5,6,7,8,14],still:[5,6,8,11,12,13,16,20],stop:[13,16],stream:5,streamlin:13,strict:20,strictli:[3,5,6,15,20],string:[0,1,4,8,14,16,19],strip:[3,5,11,18,20],strongli:[5,6,15],structur:[12,20],stuff:13,style:[5,13,17,18],sub:[1,3,8,10,20],sub_instal:14,subdir:14,subdirectori:[6,9],submit:6,submodul:3,suboptim:17,subpackag:[3,5],subsequ:6,subset:[4,5,7,8,11,14,20],substitut:[0,4,19],subtitl:8,subtl:20,suffici:[2,5,6,7,11,14],suggest:[5,8,13,17,18,20],suit:[0,2,5,6,7,8,9,10,12,18],suitabl:[0,7,9,14,17],summar:[5,16],summari:18,sundial:2,sundri:13,superset:19,suppli:6,support:[0,1,2,3,4,5,6,7,8,10,12,13,14,17,18,19,20],suppos:16,supposedli:18,sure:[5,18,20],swig:[2,19],sy:[2,5,8,11,14,15,16,20],symbol:5,symlink:9,sync:[12,18],syntax:[4,10,11],system:[0,3,8,9,10,13,14,15,17,19,20],system_eigen:2,system_fmt:2,system_sundi:2,t:[5,7,8,11,13],tab:5,tabl:[5,13,16,18],tag:[5,12,20],take:[2,5,6,7,8,9,15,18],talloc:[2,19],tar:[0,2,4,5,6,8,12,14,19,20],tarbal:[5,12,20],target:[2,5,8,9,11,12,15,19],task:[5,8,12],tauthon:11,tc:[2,9],tcsh:5,tdb:2,team:[12,15],technic:[3,12],telepathi:0,tell:13,temp:20,templat:[0,2,4,19],temporari:[5,6],temporarili:13,term:[0,2,3,4,5,6,8,14,19],termcolor:5,termin:20,test:[0,2,3,4,8,10,12,13,17,19],test_arima:20,test_babel_with_language_:20,test_build_latex:20,test_client:18,test_contextvar:18,test_crc_pickl:20,test_decod:20,test_empty_size_pickl:20,test_filenam:18,test_gener:18,test_leak:18,test_loc:18,test_network:20,test_null_byt:20,test_polyglossia_with_language_:20,test_pytest_plugin:5,test_start_params_bug:20,test_sync:18,test_sync_contextvar:18,test_test_util:5,test_testcase_no_app:5,test_transport:18,test_transport_work:18,test_wrapped_case_is_collect:18,testbitvector:5,testcas:18,tests_requir:5,testsupport:20,tevent:2,text:[5,8],tgz:14,than:[1,2,6,7,8,11,17,18,20],thei:[1,2,3,5,6,7,8,9,11,12,13,14,15,16,17,18,20],them:[0,1,2,3,5,6,7,8,9,12,16,18,19,20],theme:[5,6,8],themselv:[6,18,20],therefor:[2,3,4,5,6,7,8,11,12,15,18],thermodynam:2,thi:[0,1,2,3,4,5,6,7,8,9,11,12,13,14,15,16,17,18,19,20],thin:[5,6],thing:[12,13,17,18],think:16,third:[5,7,13],thirdli:20,those:[5,6,7,8,9,18,20],though:[8,12],thread:[2,8,18,19,20],three:[0,3,9,13,16],through:[4,5,6,8,11,16,18],throughout:6,thumb:[6,10,13,15],tiff:5,time:[1,3,4,5,6,9,10,11,12,13,16,17,18,20],timeout:20,tip:[10,20],tmp:[3,5,9,18,20],todai:16,todo:[2,9],toml:[5,7,12],tomli:12,too:[5,12,20],tool:[1,2,5,8,14,15,16,20],toolchain:[2,8],toolkit:8,top:[3,5,9,18],topic:[3,17],toward:12,tox:[5,12,20],traceback:[3,5],tradit:3,tradition:3,train:8,trans2arab:19,transit:[13,15],translat:8,transport:2,travel:4,travi:5,treat:[2,18],tree:[5,13],tri:5,trial:13,trigger:[6,18,20],trivial:[0,3,5,12,16,19],trolliu:11,tsa:20,tslib:5,tut:2,twice:18,two:[3,5,6,8,9,11,13,18,19],txt:[5,6,12,18],type:[2,6,13],typeerror:10,typic:[1,14],ubuntu:20,udev:0,udevdir:[2,8],ugli:13,unabl:[5,20],unbundl:12,unclear:20,uncommon:5,uncondit:[2,10,13,14],unconditioanlli:20,uncondition:[0,1,2,4,5,6,8,11,19,20],undefin:5,under:[0,2,3,4,5,6,8,14,19],underli:[5,6],underscor:[5,20],understand:0,understood:12,undesir:20,unexpect:10,unexpectedli:20,unfortun:[13,18],unicod:16,uniqu:[5,14],unit:2,unittest:[5,11,20],univers:5,unless:[6,8,15],unlik:[3,6,11,15],unmask:12,unmatch:13,unnecessari:[3,14,19,20],unnecessarili:5,unpars:16,unpredict:5,unresolv:5,unset:6,unsupport:[8,11],until:16,unusu:12,up:[6,9,12,13,14,17,20],updat:[4,6,9,11,12,16],upgrad:4,upload:12,uppercas:13,upstream:[3,5,6,7,9,11,12,14,15,16,18,20],url:16,urllib3:[8,12],urllib:16,urlpars:16,us:[1,3,9,10,11,12,13,15,16,20],usabl:11,usag:10,usb:[2,8],use_en:19,use_pch:2,use_pep517:5,use_scon:[2,8],user:[2,3,5,6,7,8,11,12,15,18,19,20],userland:14,userland_gnu:8,userspac:2,usex:[2,5,19],usr:[1,2,3,5,7,8,9,18,20],usual:[5,11,13,15,16,18,20],util:[2,4,5,8,9,10,12,15,18,19,20],utils_src_configur:[2,19],uucp:[2,8],v2:[0,2,3,4,5,6,8,14,19],v3:12,v:[2,4,5,14],valid:[1,5,8,16],valu:[1,5,6,9,13,18],variabl:[0,1,5,6,8,13,14,16,18,19],variant:[10,11,16,18],variat:10,variou:[1,5,6,9,13,16],vast:12,vc:[5,20],ve:16,vendor:[12,13],venv:[5,6,13],venv_pv:20,verbatim:16,verbos:20,veri:[5,6,9,11,12,17],verifi:[0,5,6,8,13,20],version:[2,3,5,6,7,8,10,12,13,15,16,17,18,20],version_info:16,via:[1,2,4,6,7,8,9,10,11,12,13,14,18,19,20],video:8,virtual:[0,2,8,14],virtualenv:[5,6,12,20],virtualx:5,visual:2,vmd:2,vmxcap:14,voacap:19,vs:[10,13],vulnkei:9,vv:20,wa:[0,3,4,5,11,13,18,20],waf:[10,19],waf_binari:[2,19],wai:[0,3,5,6,9,12,13,18,20],wall:2,want:[5,6,8,12],warn:[2,5,10,16],wcwidth:5,we:[3,6,8,11,12,14,15,17],web:11,webencod:5,webp:5,welcom:17,well:[1,5,7,8,11,13,15],went:6,were:[0,2,3,5,8,11,12,13,16],what:16,wheel:[5,12,18],when:[0,2,3,4,5,6,7,8,9,11,12,13,14,15,18,19,20],whenev:[1,5,9,14,15,18,19],where:[0,3,5,6,9,12,14,19],whether:[0,5,6,7,15,19,20],which:[0,1,5,6,10,11,14,20],whitelist:5,who:[5,17],whole:[18,20],wholli:20,whom:20,whose:5,why:[5,6,20],wide:[15,20],wider:2,widest:5,widget:14,wiki:[0,3,4,8,9,14,17],window:11,wise:7,wish:[3,5,6],within:[3,6,12,17,20],without:[4,7,11,12,13,14,15,18],wno:2,won:8,word:5,work:[0,3,5,6,7,8,9,11,12,13,15,16,18,19,20],workaround:5,workdir:[2,20],workflow:12,world:18,worm:16,worst:[16,20],worthwhil:[1,20],would:[0,2,3,11,12,14,15,19,20],wrap:[0,5,6,9,13],wrapper:[1,5,6,9,13,14],write:[5,6,7,12,17],written:[7,10,11,18],wrong:[6,13],wrongli:[5,16],www:[0,2,8,14,19],wx_gtk_ver:[2,19],wxpython:[2,19],x11:2,x64:[0,3,4,5,6,8,19],x86:[0,2,3,4,5,6,8,12,14,19],x86_64:5,x:[1,5,16,18],xbox:2,xboxdrv:2,xdg:4,xdist:[10,12,20],xfail:20,xml:[5,6],xmltodict:5,xolox:5,xz:[0,4,12,14,19],y:[1,2,16],yaml:2,ye:2,yet:[3,8,12,19],yield:12,yml:5,yoda:19,you:[1,2,3,4,5,6,7,8,9,11,12,13,14,15,16,17,18,20],your:[2,4,5,6,7,8,11,12,15,16,20],yourself:[2,4,12,20],zip:[5,6],zlib:2,zope:3,zsi:2,zstd:2},titles:["python-any-r1 \u2014 build-time dependency","Common basics","Integration with build systems written in Python","Advanced concepts","Advanced dependencies","distutils-r1 \u2014 standard Python build systems","distutils-r1 legacy concepts","Choosing between Python eclasses","Expert python-r1 usage","Common helper functions","Gentoo Python Guide","Python interpreters","Maintenance of Python implementations","Migration guides","python-r1 \u2014 multi-impl packages","Python package maintenance","Porting tips","Preface","pytest recipes","python-single-r1 \u2014 single-impl packages","Resolving test suite problems"],titleterms:{"1":16,"10":16,"2":15,"3":[3,16],"517":[5,13],"7":13,"8":[13,16],"9":16,"byte":9,"default":16,"function":[5,9],"new":[12,15],A:[7,19],In:6,No:16,The:5,_make_test_flaki:18,abort:20,access:20,ad:[5,12,15],addit:[0,5,14],advanc:[3,4],altern:11,an:18,ani:[0,8],api:[5,8],argument:[5,18],assert:20,autodoc:5,autoload:18,automat:18,autotool:14,avoid:18,backend:5,backport:11,base64:16,base:[6,18],basic:[0,1,5,19],befor:[5,6],being:5,between:7,bootstrap:12,bpo43882:16,build:[0,2,5,6,7,8,12,13,14,19],buildapi:5,call:5,can:15,cffi:4,chang:[12,16],charact:16,checklist:20,choos:[7,20],co:15,combin:8,command:5,common:[1,9],compil:9,concept:[3,6],condit:[0,2,4,5,14,19],config:16,configur:16,content:10,correct:20,cpython:12,cr:16,custom:5,cycl:12,deal:20,decodestr:16,depend:[0,2,4,5,8,14,18,19,20],deprec:[5,16],differ:[6,8],directori:5,disabl:18,disjoint:8,distutil:[5,6,7,8,16],distutils_enable_test:5,distutils_use_setuptool:6,document:5,due:20,e:20,eapi:[13,15],eclass:[7,12],enabl:5,encodestr:16,entir:18,entri:6,environ:[1,20],exampl:20,exist:15,expert:[8,18],explicitli:18,extens:5,extra:[2,20],failur:20,file:20,fix:9,fixtur:18,flag:4,flit:5,found:[16,18],from:[5,13],g:20,gentoo:[3,10],got:18,greenlet:4,guid:[10,13],helper:9,hierarch:3,ht:16,hybrid:[2,19],impl:[2,7,14,19],implement:[8,9,11,12,15],importpathmismatcherror:18,indic:10,inform:9,initi:12,instal:[2,5,6,9,14,19,20],integr:2,internet:20,interpret:[4,8,11,12],keyword:18,legaci:[5,6],lf:16,librari:16,life:12,list:16,longer:16,maintain:15,mainten:[12,15],manual:[14,19],marker:18,masonri:5,meson:2,migrat:13,miss:20,mode:5,modul:9,more:5,multi:[2,7,14],multipl:[0,11,19],name:18,namespac:3,note:12,now:16,old:13,other:[6,18],out:6,packag:[2,3,5,6,12,14,15,16,19,20],parallel:[5,18],partial:8,pass:5,patchset:12,path:18,pep:[5,13],phase:5,pkg:16,pkgutil:3,plugin:[18,20],poetri:5,point:6,port:[12,15,16],prefac:17,prevent:5,problem:20,problemat:20,profil:12,project:[6,15],pure:[2,14],py:5,pypi:[12,20],pyproject:6,pytest:[5,18],python:[0,1,2,3,4,5,7,8,9,10,11,12,13,14,15,16,19],python_compat:1,python_compil:5,python_configur:5,python_dep:1,python_instal:5,python_prepar:5,python_required_us:1,python_setup:8,python_test:5,python_usedep:13,queri:9,r1:[0,2,5,6,7,8,13,14,19],race:5,recip:18,regular:8,relat:7,remov:16,request:4,requir:20,rerun:18,resolv:20,restrict:8,retroact:16,rule:7,run:[5,18],runner:[18,20],runtim:[6,7,19],scon:2,script:9,set:[0,8],setup:5,setuptool:[3,6],setuptools_scm:5,shebang:9,singl:[2,5,7,13,19],skip:[18,20],snapshot:5,sourc:6,specif:12,sphinx:5,standard:5,strip:16,structur:3,style:3,sub:5,suit:20,support:[11,15],syntax:13,sysconfig:16,system:[2,5,6,7,12],tabl:10,test:[5,6,15,18,20],thumb:7,time:[0,2,7,8,14,19],tip:16,toml:6,typeerror:18,uncondit:[0,19],undesir:5,unexpect:18,urlsplit:16,us:[0,2,4,5,6,7,8,14,18,19],usag:8,util:7,variant:5,variat:6,version:[4,11],via:5,vs:[6,7],waf:2,warn:18,which:15,without:5,written:2,xdist:18}})
\ No newline at end of file diff --git a/guide/single.html b/guide/single.html new file mode 100644 index 0000000..520dba1 --- /dev/null +++ b/guide/single.html @@ -0,0 +1,406 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>python-single-r1 — single-impl packages — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="python-r1 — multi-impl packages" href="multi.html" /> + <link rel="prev" title="python-any-r1 — build-time dependency" href="any.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="python-single-r1-single-impl-packages"> +<h1>python-single-r1 — single-impl packages<a class="headerlink" href="#python-single-r1-single-impl-packages" title="Permalink to this headline">¶</a></h1> +<p>The <code class="docutils literal notranslate"><span class="pre">python-single-r1</span></code> eclass is used to install single-impl packages. +It is probably the easiest eclass to use, and it is recommended over +<code class="docutils literal notranslate"><span class="pre">python-r1</span></code> whenever multi-impl support would add unnecessary +complexity. However, for packages using distutils or a similar Python +build system, <code class="docutils literal notranslate"><span class="pre">distutils-r1</span></code> eclass should be used instead.</p> +<p>Eclass reference: <a class="reference external" href="https://devmanual.gentoo.org/eclass-reference/python-single-r1.eclass/index.html">python-single-r1.eclass(5)</a></p> +<section id="basic-use-for-unconditional-python"> +<h2>Basic use for unconditional Python<a class="headerlink" href="#basic-use-for-unconditional-python" title="Permalink to this headline">¶</a></h2> +<p>The defining feature of this eclass is that it defines a <code class="docutils literal notranslate"><span class="pre">pkg_setup</span></code> +phase. It normally calls <code class="docutils literal notranslate"><span class="pre">python_setup</span></code> function in order +to determine the interpreter selected by user, and set the global +environment appropriately.</p> +<p>This means that a most trivial package using an autotools-compatible +build system along with unconditional dependency on Python could look +like the following:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + +<span class="hll"> <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 <span class="o">)</span> +</span><span class="hll"> inherit python-single-r1 +</span> + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Scripts to prepare and plot VOACAP propagation predictions"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://www.qsl.net/h/hz1jw//pythonprop/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://sourceforge/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2+"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">""</span> +<span class="hll"> <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> +</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"></span> +</span><span class="s2"> ...</span> +<span class="s2"> "</span> + <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2">"</span> +</pre></div> +</div> +<p>This ebuild demonstrates the absolute minimum working code. Only +the four highlighted lines are specific to Python eclasses, plus +the implicitly exported <code class="docutils literal notranslate"><span class="pre">pkg_setup</span></code> phase.</p> +<span class="target" id="index-0"></span><span class="target" id="index-1"></span></section> +<section id="dependencies"> +<span id="index-2"></span><h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2> +<p>When depending on other Python packages, USE dependencies need to be +declared in order to ensure that the dependencies would be built against +the Python implementation used for the package. The exact dependency +string depends on whether the target package is single-impl +or multi-impl.</p> +<p>When depending on other single-impl packages, the eclass-defined +<code class="docutils literal notranslate"><span class="pre">${PYTHON_SINGLE_USEDEP}</span></code> variable can be used to inject the correct +USE dependency:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> ...</span> +<span class="s2"> dev-python/basemap[</span><span class="si">${</span><span class="nv">PYTHON_SINGLE_USEDEP</span><span class="si">}</span><span class="s2">]</span> +<span class="s2">"</span> +</pre></div> +</div> +<p>When depending on multi-impl packages, a more complex construct must +be used. The <code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code> generator function is used +to copy the specified dependency template for all supported +implementations, and substitute <code class="docutils literal notranslate"><span class="pre">${PYTHON_USEDEP}</span></code> template inside +it:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> ...</span> +<span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +<span class="s1"> dev-python/matplotlib-python2[gtk2,${PYTHON_USEDEP}]</span> +<span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +<span class="s2">"</span> +</pre></div> +</div> +<p>Please note that in this context, <code class="docutils literal notranslate"><span class="pre">${...}</span></code> is used as a literal +template substitution key, so it must be escaped to prevent bash from +substituting it immediately. In the above example, single quotes +are used for this purpose. When other variables are used, double quotes +with explicit escapes have to be used:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> ...</span> +<span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s2">"</span> +<span class="s2"> dev-python/wxpython:</span><span class="si">${</span><span class="nv">WX_GTK_VER</span><span class="si">}</span><span class="s2">[\${PYTHON_USEDEP}]</span> +<span class="s2"> "</span><span class="k">)</span><span class="s2">"</span> +</pre></div> +</div> +<p>As demonstrated above, the USE dependency string can be combined with +other USE dependencies. <code class="docutils literal notranslate"><span class="pre">PYTHON_SINGLE_USEDEP</span></code> can be used both +inside and outside <code class="docutils literal notranslate"><span class="pre">python_gen_cond_dep</span></code>, while <code class="docutils literal notranslate"><span class="pre">PYTHON_USEDEP</span></code> only +inside it.</p> +</section> +<section id="conditional-python-use"> +<h2>Conditional Python use<a class="headerlink" href="#conditional-python-use" title="Permalink to this headline">¶</a></h2> +<p>The examples so far assumed that Python is used unconditionally. +If Python support is conditional to a USE flag, appropriate USE +conditionals need to be used in metadata variables, and <code class="docutils literal notranslate"><span class="pre">pkg_setup</span></code> +needs to be rewritten to call the default implementation conditionally:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 <span class="o">)</span> + inherit python-single-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Yet more Objects for (High Energy Physics) Data Analysis"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"http://yoda.hepforge.org/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"http://www.hepforge.org/archive/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.bz2"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-2"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0/</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86 ~amd64-linux ~x86-linux"</span> +<span class="hll"> <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"python root"</span> +</span><span class="hll"> <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"python? ( </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"> )"</span> +</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )</span> +</span><span class="hll"><span class="s2"> root? ( sci-physics/root:=[python=,</span><span class="si">${</span><span class="nv">PYTHON_SINGLE_USEDEP</span><span class="si">}</span><span class="s2">] )"</span> +</span> <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="hll"><span class="s2"> python? (</span> +</span><span class="hll"><span class="s2"> </span><span class="k">$(</span>python_gen_cond_dep <span class="s1">'</span> +</span><span class="hll"><span class="s1"> dev-python/cython[${PYTHON_USEDEP}]</span> +</span><span class="hll"><span class="s1"> '</span><span class="k">)</span><span class="s2"></span> +</span><span class="hll"><span class="s2"> )"</span> +</span> + pkg_setup<span class="o">()</span> <span class="o">{</span> +<span class="hll"> use python <span class="o">&&</span> python-single-r1_pkg_setup +</span> <span class="o">}</span> + + src_configure<span class="o">()</span> <span class="o">{</span> + econf <span class="se">\</span> +<span class="hll"> <span class="k">$(</span>use_enable python pyext<span class="k">)</span> <span class="se">\</span> +</span> <span class="k">$(</span>use_enable root<span class="k">)</span> + <span class="o">}</span> +</pre></div> +</div> +</section> +<section id="a-hybrid-build-time-conditional-runtime"> +<h2>A hybrid: build-time + conditional runtime<a class="headerlink" href="#a-hybrid-build-time-conditional-runtime" title="Permalink to this headline">¶</a></h2> +<p>A fairly common pattern is for Python to be required unconditionally +at build time but only conditionally at runtime. This happens e.g. when +the package is calling some helper scripts at build time, and optionally +installing Python bindings. In this case, the build time dependency +is expressed unconditionally, and the runtime dependency is made +USE-conditional:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> <span class="o">)</span> + <span class="nv">PYTHON_REQ_USE</span><span class="o">=</span><span class="s2">"threads(+)"</span> + + inherit waf-utils python-single-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Samba talloc library"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://talloc.samba.org/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://www.samba.org/ftp/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.gz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"GPL-3 LGPL-3+ LGPL-2"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 arm ~arm64 ~hppa ia64 ~m68k ~mips ppc ppc64 ~riscv ~s390 ~sh ~sparc x86 ~amd64-linux ~x86-linux ~x64-macos ~sparc-solaris ~x64-solaris"</span> +<span class="hll"> <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"+python"</span> +</span><span class="hll"> <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> +</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> ...</span> +<span class="hll"><span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )"</span> +</span> <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">RDEPEND</span><span class="si">}</span><span class="s2"></span> +<span class="s2"> ...</span> +<span class="hll"><span class="s2"> </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2">"</span> +</span> + <span class="nv">WAF_BINARY</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">S</span><span class="si">}</span><span class="s2">/buildtools/bin/waf"</span> + + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nb">local</span> <span class="nv">extra_opts</span><span class="o">=(</span> +<span class="hll"> <span class="k">$(</span>usex python <span class="s1">''</span> --disable-python<span class="k">)</span> +</span> <span class="o">)</span> + waf-utils_src_configure <span class="s2">"</span><span class="si">${</span><span class="nv">extra_opts</span><span class="p">[@]</span><span class="si">}</span><span class="s2">"</span> + <span class="o">}</span> +</pre></div> +</div> +<p>Note that eclass-exported <code class="docutils literal notranslate"><span class="pre">pkg_setup</span></code> is used unconditionally here.</p> +</section> +<section id="multiple-use-conditions"> +<h2>Multiple USE conditions<a class="headerlink" href="#multiple-use-conditions" title="Permalink to this headline">¶</a></h2> +<p>Finally, let’s give an example of a package where Python is needed +for two independent conditions. To make it more complex, one of them +applies to build time (tests) while the other to runtime (bindings).</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python3_<span class="o">{</span><span class="m">6</span>,7,8<span class="o">}</span> <span class="o">)</span> + inherit cmake python-single-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Sound design and signal processing system for composition and performance"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://csound.github.io/"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://dev.gentoo.org/~fordfrog/distfiles/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">-distributable.tar.xz"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"LGPL-2.1 doc? ( FDL-1.2+ )"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~amd64 ~x86"</span> +<span class="hll"> <span class="nv">IUSE</span><span class="o">=</span><span class="s2">"python test"</span> +</span> <span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"> )</span> +</span><span class="hll"><span class="s2"> test? ( </span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2"> )"</span> +</span> + <span class="nv">BDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="s2"> python? ( dev-lang/swig )</span> +<span class="hll"><span class="s2"> test? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )</span> +</span><span class="s2"> "</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span> +<span class="hll"><span class="s2"> python? ( </span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2"> )</span> +</span><span class="s2"> "</span> + + pkg_setup<span class="o">()</span> <span class="o">{</span> +<span class="hll"> <span class="k">if</span> use python <span class="o">||</span> use <span class="nb">test</span> <span class="p">;</span> <span class="k">then</span> +</span><span class="hll"> python-single-r1_pkg_setup +</span><span class="hll"> <span class="k">fi</span> +</span> <span class="o">}</span> + + src_configure<span class="o">()</span> <span class="o">{</span> + <span class="nb">local</span> <span class="nv">mycmakeargs</span><span class="o">=(</span> +<span class="hll"> -DBUILD_PYTHON_INTERFACE<span class="o">=</span><span class="k">$(</span>usex python<span class="k">)</span> +</span><span class="hll"> -DBUILD_PYTHON_OPCODES<span class="o">=</span><span class="k">$(</span>usex python<span class="k">)</span> +</span> <span class="o">)</span> + + cmake_src_configure + <span class="o">}</span> +</pre></div> +</div> +<p>Please note that in general, the condition in <code class="docutils literal notranslate"><span class="pre">pkg_setup</span></code> must match +the one in <code class="docutils literal notranslate"><span class="pre">REQUIRED_USE</span></code>, and that one is a superset of conditions +used in dependencies.</p> +</section> +<section id="manual-install"> +<h2>Manual install<a class="headerlink" href="#manual-install" title="Permalink to this headline">¶</a></h2> +<p>Some packages do not include Python files in their build systems, +or do not install all of them. In this case, the necessary files +can be installed via one of the installation helpers.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> <span class="c1"># Copyright 1999-2020 Gentoo Authors</span> + <span class="c1"># Distributed under the terms of the GNU General Public License v2</span> + + <span class="nv">EAPI</span><span class="o">=</span><span class="m">6</span> + + <span class="nv">PYTHON_COMPAT</span><span class="o">=(</span> python2_7 <span class="o">)</span> + inherit python-single-r1 + + <span class="nv">DESCRIPTION</span><span class="o">=</span><span class="s2">"Arabic dictionary based on the DICT protocol"</span> + <span class="nv">HOMEPAGE</span><span class="o">=</span><span class="s2">"https://www.arabeyes.org/Duali"</span> + <span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"mirror://sourceforge/arabeyes/</span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.tar.bz2"</span> + + <span class="nv">LICENSE</span><span class="o">=</span><span class="s2">"BSD"</span> + <span class="nv">SLOT</span><span class="o">=</span><span class="s2">"0"</span> + <span class="nv">KEYWORDS</span><span class="o">=</span><span class="s2">"~alpha amd64 ~hppa ~ia64 ~mips ~ppc ~sparc x86"</span> + <span class="nv">IUSE</span><span class="o">=</span><span class="s2">""</span> + <span class="nv">REQUIRED_USE</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_REQUIRED_USE</span><span class="si">}</span><span class="s2">"</span> + + <span class="nv">DEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">PYTHON_DEPS</span><span class="si">}</span><span class="s2">"</span> + <span class="nv">RDEPEND</span><span class="o">=</span><span class="s2">"</span><span class="si">${</span><span class="nv">DEPEND</span><span class="si">}</span><span class="s2">"</span> + + src_install<span class="o">()</span> <span class="o">{</span> +<span class="hll"> python_domodule pyduali +</span><span class="hll"> python_doscript duali dict2db trans2arabic arabic2trans +</span> <span class="o">}</span> +</pre></div> +</div> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">python-single-r1 — single-impl packages</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#basic-use-for-unconditional-python">Basic use for unconditional Python</a></li> +<li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="#conditional-python-use">Conditional Python use</a></li> +<li class="toctree-l2"><a class="reference internal" href="#a-hybrid-build-time-conditional-runtime">A hybrid: build-time + conditional runtime</a></li> +<li class="toctree-l2"><a class="reference internal" href="#multiple-use-conditions">Multiple USE conditions</a></li> +<li class="toctree-l2"><a class="reference internal" href="#manual-install">Manual install</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1"><a class="reference internal" href="test.html">Resolving test suite problems</a></li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="any.html" title="previous chapter">python-any-r1 — build-time dependency</a></li> + <li>Next: <a href="multi.html" title="next chapter">python-r1 — multi-impl packages</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/single.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file diff --git a/guide/test.html b/guide/test.html new file mode 100644 index 0000000..47ba663 --- /dev/null +++ b/guide/test.html @@ -0,0 +1,423 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Resolving test suite problems — Gentoo Python Guide documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/alabaster.css" /> + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="pytest recipes" href="pytest.html" /> + <link rel="prev" title="Advanced dependencies" href="depend.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <section id="resolving-test-suite-problems"> +<h1>Resolving test suite problems<a class="headerlink" href="#resolving-test-suite-problems" title="Permalink to this headline">¶</a></h1> +<section id="choosing-the-correct-test-runner"> +<h2>Choosing the correct test runner<a class="headerlink" href="#choosing-the-correct-test-runner" title="Permalink to this headline">¶</a></h2> +<p>There are a few modules used to run tests in Python packages. The most +common include the built-in <a class="reference external" href="https://docs.python.org/3/library/unittest.html">unittest</a> module, <a class="reference external" href="https://docs.pytest.org/en/latest/">pytest</a> and <a class="reference external" href="https://github.com/nose-devs/nose">nose</a>. There +are also some rarely used test tools and domain-specific solutions, +e.g. <a class="reference external" href="https://www.djangoproject.com/">django</a> has its own test runner. This section will help you +determining which test runner to use and depend on.</p> +<p>Firstly, it is a good idea to look at test sources. Explicit imports +clearly indicate that a particular test runner needs to be installed, +and most likely used. For example, if at least one test file has +<code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">pytest</span></code>, pytest is the obvious choice. If it has <code class="docutils literal notranslate"><span class="pre">import</span> +<span class="pre">nose</span></code>, same goes for nosetests.</p> +<p>In some rare cases the tests may use multiple test packages +simultaneously. In this case, you need to choose one of the test +runners (see other suggestions) but depend on all of them.</p> +<p>Secondly, some test suites are relying on <em>implicit</em> features of a test +runner. For example, pytest and nose have less strict naming +and structural requirements for test cases. In some cases, unittest +runner will simply be unable to find all tests.</p> +<p>Thirdly, there are cases when a particular feature of a test runner +is desired even if it is not strictly necessary to run tests. This +is particularly the case with pytest’s output capture that can make +test output much more readable with particularly verbose packages.</p> +<p>Upstream documentation, tox configuration, CI pipelines can provide tips +on the test runner to be used. However, you should establish whether +this information is wholly correct and up-to-date, and whether +the particular test tool is really desirable.</p> +<p>If the test suite requires no particular runner (i.e. works with +built-in unittest module), using it is preferable to avoid unnecessary +dependencies. However, you need to make sure that it finds all tests +correctly (i.e. runs no less tests than the alternative) and that it +does not spew too much irrelevant output.</p> +<p>If both pytest and nose seem equally good, the former is recommended +as the latter has ceased development and requires downstream patching. +If you have some free time, convincing upstream to switch from nose +to pytest is a worthwhile goal.</p> +</section> +<section id="missing-test-files-in-pypi-packages"> +<h2>Missing test files in PyPI packages<a class="headerlink" href="#missing-test-files-in-pypi-packages" title="Permalink to this headline">¶</a></h2> +<p>One of the more common test-related problems is that PyPI packages +(generated via <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">sdist</span></code>) often miss some or all test files. +The latter results in no tests being run, the former in test failures +or errors.</p> +<p>The simplest solution is to use a VCS snapshot instead of the PyPI +tarball:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># pypi tarballs are missing test data</span> +<span class="c1">#SRC_URI="mirror://pypi/${PN:0:1}/${PN}/${P}.tar.gz"</span> +<span class="nv">SRC_URI</span><span class="o">=</span><span class="s2">"https://github.com/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/</span><span class="si">${</span><span class="nv">PN</span><span class="si">}</span><span class="s2">/archive/</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span><span class="s2">.tar.gz -> </span><span class="si">${</span><span class="nv">P</span><span class="si">}</span><span class="s2">.gh.tar.gz"</span> +</pre></div> +</div> +</section> +<section id="checklist-for-dealing-with-test-failures"> +<h2>Checklist for dealing with test failures<a class="headerlink" href="#checklist-for-dealing-with-test-failures" title="Permalink to this headline">¶</a></h2> +<p>If you see some test failures but do not have a guess as to why they +would be happening, try the following for a start:</p> +<ol class="arabic simple"> +<li><p>Check upstream CI (if any). That’s a quick way of verifying that +there is no known breakage at the relevant tag.</p></li> +<li><p>Try running tests as your regular user, the way upstream suggests +(e.g. via <code class="docutils literal notranslate"><span class="pre">tox</span></code>). Try using a git checkout at the specific tag. +This is the basic way of determining whether the package is actually +broken or if it is something on our end.</p></li> +<li><p>If the tests fail at the specified tag, try upstream master branch. +Maybe there was a fix committed.</p></li> +</ol> +<p>If it seems that the issue is on our end, try the following and see +if it causes the subset of failing tests to change:</p> +<ol class="arabic"> +<li><p>Add <code class="docutils literal notranslate"><span class="pre">distutils_install_for_testing</span></code> to the test sub-phase. This +resolves majority of problems with test suite assuming the package +must already be installed.</p></li> +<li><p>Actually install the package to the system (with tests disabled). +This can confirm cases of package for whom the above function +does not work. In the worst case, you can set a test self-dependency +to force users to install the package before testing:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>test? <span class="o">(</span> ~dev-python/myself-<span class="si">${</span><span class="nv">PV</span><span class="si">}</span> <span class="o">)</span> +</pre></div> +</div> +</li> +<li><p>Try testing a different Python implementation. If a subset of tests +is failing with Python 3.6, see if it still happens with 3.7 or 3.8. +If 3.8 is passing but 3.9 is not, it’s most likely some +incompatibility upstream did not account for.</p></li> +<li><p>Run tests with <code class="docutils literal notranslate"><span class="pre">FEATURES=-network-sandbox</span></code>. Sometimes lack +of Internet access causes non-obvious failures.</p></li> +<li><p>Try a different test runner. Sometimes the subtle differences +in how tests are executed can lead to test failures. But beware: +some test runners may not run the full set of tests, so verify +that you have actually fixed them and not just caused them to +be skipped.</p></li> +</ol> +</section> +<section id="skipping-problematic-tests"> +<h2>Skipping problematic tests<a class="headerlink" href="#skipping-problematic-tests" title="Permalink to this headline">¶</a></h2> +<p>While generally it is preferable to fix tests, sometimes you will face +failures that cannot be easily resolved. This especially applies +to tests that are broken themselves rather than indicating real problems +with the software. However, in some cases you will even find yourself +ignoring minor test failures.</p> +<p>Tests that are known to fail reliably can be marked as <em>expected +failures</em>. This has the advantage that the test in question will +continue being run and the test suite will report when it unexpectedly +starts passing again.</p> +<p>Expected failures are not supported by the standard Python unittest +module. It is supported e.g. by pytest.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sed -i -e <span class="se">\</span> + <span class="s2">"/def test_start_params_bug():/i@pytest.mark.xfail(reason='Known to fail on Gentoo')"</span> <span class="se">\</span> + statsmodels/tsa/tests/test_arima.py <span class="o">||</span> die +</pre></div> +</div> +<p>Tests that cause inconsistent results, trigger errors, consume +horrendous amounts of disk space or cause another kind of undesirable +mayhem can be <em>skipped</em> instead. Skipping means that they will not be +run at all.</p> +<p>There are multiple ways to skip a test. You can patch it to use a skip +decorator, possibly with a condition:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># broken on py2.7, upstream knows</span> +sed -i -e <span class="s1">'5a\</span> +<span class="s1">import sys'</span> <span class="se">\</span> + -e <span class="s1">'/test_null_bytes/i\</span> +<span class="s1">@pytest.mark.skipif(sys.hexversion < 0x03000000, reason="broken on py2")'</span> <span class="se">\</span> + test/server.py <span class="o">||</span> die +</pre></div> +</div> +<p>The easy way to skip a test unconditioanlly is to prefix its name with +an underscore:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># tests requiring specific locales</span> +sed -i -e <span class="s1">'s:test_babel_with_language_:_&:'</span> <span class="se">\</span> + tests/test_build_latex.py <span class="o">||</span> die +sed -i -e <span class="s1">'s:test_polyglossia_with_language_:_&:'</span> <span class="se">\</span> + tests/test_build_latex.py <span class="o">||</span> die +</pre></div> +</div> +<p>Finally, if all tests in a particular file are problematic, you can +simply remove that file. If all tests belonging to the package +are broken, you can use <code class="docutils literal notranslate"><span class="pre">RESTRICT=test</span></code> to disable testing altogether.</p> +</section> +<section id="tests-requiring-internet-access"> +<h2>Tests requiring Internet access<a class="headerlink" href="#tests-requiring-internet-access" title="Permalink to this headline">¶</a></h2> +<p>One of more common causes of test failures are attempts to use Internet. +With Portage blocking network access by default, packages performing +tests against remote servers often fail.</p> +<p>Ideally, packages would use mocking or replay tests rather than using +real Internet services. Devmanual provides a detailed explanation <a class="reference external" href="https://devmanual.gentoo.org/ebuild-writing/functions/src_test/#tests-that-require-network-or-service-access">why +tests must not use Internet</a>.</p> +<p>Some packages provide explicit methods of disabling network-based tests. +For example, <code class="docutils literal notranslate"><span class="pre">dev-python/tox</span></code> provides a switch for that:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + distutils_install_for_testing + epytest --no-network +<span class="o">}</span> +</pre></div> +</div> +<p>There are packages that skip tests if they fail specifically due to +connection errors, or detect whether Internet is accessible. Ideally, +you should modify those packages to disable network tests +unconditionally. For example, <code class="docutils literal notranslate"><span class="pre">dev-python/pygit2</span></code> ebuild does this:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># unconditionally prevent it from using network</span> +sed -i -e <span class="s1">'/def no_network/a \</span> +<span class="s1"> return True'</span> test/utils.py <span class="o">||</span> die +</pre></div> +</div> +<p>In other cases, you will have to explicitly disable these tests. +In some cases, it will be reasonable to remove whole test files or even +restrict tests entirely.</p> +<p>If the package’s test suite relies on Internet access entirely and there +is no point in running even a subset of tests, please implement running +tests and combine test restriction with <code class="docutils literal notranslate"><span class="pre">PROPERTIES=test_network</span></code> +to allow interested users to run tests when possible:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># users can use ALLOW_TEST=network to override this</span> +<span class="nv">PROPERTIES</span><span class="o">=</span><span class="s2">"test_network"</span> +<span class="nv">RESTRICT</span><span class="o">=</span><span class="s2">"test"</span> + +distutils_enable_tests pytest +</pre></div> +</div> +</section> +<section id="tests-aborting-due-to-assertions"> +<h2>Tests aborting (due to assertions)<a class="headerlink" href="#tests-aborting-due-to-assertions" title="Permalink to this headline">¶</a></h2> +<p>There are cases of package’s tests terminating with an unclear error +message and backtrace similar to the following:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="o">=============================</span> <span class="nb">test</span> session <span class="nv">starts</span> <span class="o">==============================</span> +platform linux -- Python <span class="m">3</span>.7.8, pytest-6.0.1, py-1.9.0, pluggy-0.13.1 -- /usr/bin/python3.7 +cachedir: .pytest_cache +rootdir: /var/tmp/portage/dev-python/sabyenc-4.0.2/work/sabyenc-4.0.2, configfile: pytest.ini +collecting ... collected <span class="m">24</span> items + +<span class="o">[</span>...<span class="o">]</span> +tests/test_decoder.py::test_crc_pickles PASSED <span class="o">[</span> <span class="m">54</span>%<span class="o">]</span> +tests/test_decoder.py::test_empty_size_pickles Fatal Python error: Aborted + +Current thread 0x00007f748bc47740 <span class="o">(</span>most recent call first<span class="o">)</span>: + File <span class="s2">"/var/tmp/portage/dev-python/sabyenc-4.0.2/work/sabyenc-4.0.2/tests/testsupport.py"</span>, line <span class="m">74</span> <span class="k">in</span> sabyenc3_wrapper + File <span class="s2">"/var/tmp/portage/dev-python/sabyenc-4.0.2/work/sabyenc-4.0.2/tests/test_decoder.py"</span>, line <span class="m">119</span> <span class="k">in</span> test_empty_size_pickles + File <span class="s2">"/usr/lib/python3.7/site-packages/_pytest/python.py"</span>, line <span class="m">180</span> <span class="k">in</span> pytest_pyfunc_call + File <span class="s2">"/usr/lib/python3.7/site-packages/pluggy/callers.py"</span>, line <span class="m">187</span> <span class="k">in</span> _multicall + <span class="o">[</span>...<span class="o">]</span> + File <span class="s2">"/usr/lib/python-exec/python3.7/pytest"</span>, line <span class="m">11</span> <span class="k">in</span> <module> +/var/tmp/portage/dev-python/sabyenc-4.0.2/temp/environment: line <span class="m">2934</span>: <span class="m">66</span> Aborted <span class="o">(</span>core dumped<span class="o">)</span> pytest -vv +</pre></div> +</div> +<p>This usually indicates that the C code of some Python extension failed +an assertion. Since pytest does not print captured output when exiting +due to a signal, you need to disable output capture (using <code class="docutils literal notranslate"><span class="pre">-s</span></code>) +to get a more useful error, e.g.:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ python3.7 -m pytest -s +=============================================================== test session starts =============================================================== +platform linux -- Python 3.7.8, pytest-6.0.1, py-1.9.0, pluggy-0.13.1 +rootdir: /tmp/sabyenc, configfile: pytest.ini +plugins: asyncio-0.14.0, forked-1.3.0, xdist-1.34.0, hypothesis-5.23.9, mock-3.2.0, flaky-3.7.0, timeout-1.4.2, freezegun-0.4.2 +collected 25 items + +tests/test_decoder.py .............python3.7: src/sabyenc3.c:596: decode_usenet_chunks: Assertion `PyByteArray_Check(PyList_GetItem(Py_input_list, lp))' failed. +Fatal Python error: Aborted + +Current thread 0x00007fb5db746740 (most recent call first): + File "/tmp/sabyenc/tests/testsupport.py", line 73 in sabyenc3_wrapper + File "/tmp/sabyenc/tests/test_decoder.py", line 117 in test_empty_size_pickles + File "/usr/lib/python3.7/site-packages/_pytest/python.py", line 180 in pytest_pyfunc_call + File "/usr/lib/python3.7/site-packages/pluggy/callers.py", line 187 in _multicall + File "/usr/lib/python3.7/site-packages/pluggy/manager.py", line 87 in <lambda> + [...] + File "/usr/lib/python3.7/site-packages/pytest/__main__.py", line 7 in <module> + File "/usr/lib/python3.7/runpy.py", line 85 in _run_code + File "/usr/lib/python3.7/runpy.py", line 193 in _run_module_as_main +Aborted (core dumped) +</pre></div> +</div> +<p>Now the message clearly indicates the failed assertion.</p> +<p>It is also common that upstream is initially unable to reproduce +the bug. This is because Ubuntu and many other common distributions +build Python with <code class="docutils literal notranslate"><span class="pre">-DNDEBUG</span></code> and the flag leaks to extension builds. +As a result, all assertions are stripped at build time. Upstream +can work around that by explicitly setting <code class="docutils literal notranslate"><span class="pre">CFLAGS</span></code> for the build, +e.g.:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nv">CFLAGS</span><span class="o">=</span><span class="s1">'-O0 -g'</span> python setup.py build build_ext -i +$ pytest -s +</pre></div> +</div> +</section> +<section id="installing-extra-dependencies-in-test-environment-e-g-example-plugins"> +<h2>Installing extra dependencies in test environment (e.g. example plugins)<a class="headerlink" href="#installing-extra-dependencies-in-test-environment-e-g-example-plugins" title="Permalink to this headline">¶</a></h2> +<p>Rarely, the test suite expects some package being installed that +does not fit being packaged and installed system-wide. For example, +isort’s tests use a few example plugins that are not useful to end +users, or pip’s test suite still requires old virtualenv that collides +with the modern versions. These problems can be resolved by installing +the packages locally within the ebuild.</p> +<p>To do this, just use <code class="docutils literal notranslate"><span class="pre">distutils_install_for_testing</span></code> in every package +that you need to install. For example:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_test<span class="o">()</span> <span class="o">{</span> + <span class="c1"># the main package</span> + distutils_install_for_testing + <span class="c1"># additional plugins</span> + <span class="nb">local</span> p + <span class="k">for</span> p <span class="k">in</span> example*/<span class="p">;</span> <span class="k">do</span> + <span class="nb">pushd</span> <span class="s2">"</span><span class="si">${</span><span class="nv">p</span><span class="si">}</span><span class="s2">"</span> >/dev/null <span class="o">||</span> die + distutils_install_for_testing + <span class="nb">popd</span> >/dev/null <span class="o">||</span> die + <span class="k">done</span> + + epytest +<span class="o">}</span> +</pre></div> +</div> +<p>If the extra packages are not included in the main distribution tarball, +you will also need to fetch them, e.g.:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">VENV_PV</span><span class="o">=</span><span class="m">16</span>.7.10 +<span class="nv">SRC_URI</span><span class="o">+=</span><span class="s2">"</span> +<span class="s2"> test? (</span> +<span class="s2"> https://github.com/pypa/virtualenv/archive/</span><span class="si">${</span><span class="nv">VENV_PV</span><span class="si">}</span><span class="s2">.tar.gz</span> +<span class="s2"> -> virtualenv-</span><span class="si">${</span><span class="nv">VENV_PV</span><span class="si">}</span><span class="s2">.tar.gz</span> +<span class="s2"> )</span> +<span class="s2">"</span> + +python_test<span class="o">()</span> <span class="o">{</span> + distutils_install_for_testing + <span class="nb">pushd</span> <span class="s2">"</span><span class="si">${</span><span class="nv">WORKDIR</span><span class="si">}</span><span class="s2">/virtualenv-</span><span class="si">${</span><span class="nv">VENV_PV</span><span class="si">}</span><span class="s2">"</span> >/dev/null <span class="o">||</span> die + distutils_install_for_testing + <span class="nb">popd</span> >/dev/null <span class="o">||</span> die + + epytest +<span class="o">}</span> +</pre></div> +</div> +</section> +</section> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Python Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption" role="heading"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter.html">Python interpreters</a></li> +<li class="toctree-l1"><a class="reference internal" href="eclass.html">Choosing between Python eclasses</a></li> +<li class="toctree-l1"><a class="reference internal" href="basic.html">Common basics</a></li> +<li class="toctree-l1"><a class="reference internal" href="any.html">python-any-r1 — build-time dependency</a></li> +<li class="toctree-l1"><a class="reference internal" href="single.html">python-single-r1 — single-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="multi.html">python-r1 — multi-impl packages</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils.html">distutils-r1 — standard Python build systems</a></li> +<li class="toctree-l1"><a class="reference internal" href="distutils-legacy.html">distutils-r1 legacy concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="helper.html">Common helper functions</a></li> +<li class="toctree-l1"><a class="reference internal" href="depend.html">Advanced dependencies</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Resolving test suite problems</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#choosing-the-correct-test-runner">Choosing the correct test runner</a></li> +<li class="toctree-l2"><a class="reference internal" href="#missing-test-files-in-pypi-packages">Missing test files in PyPI packages</a></li> +<li class="toctree-l2"><a class="reference internal" href="#checklist-for-dealing-with-test-failures">Checklist for dealing with test failures</a></li> +<li class="toctree-l2"><a class="reference internal" href="#skipping-problematic-tests">Skipping problematic tests</a></li> +<li class="toctree-l2"><a class="reference internal" href="#tests-requiring-internet-access">Tests requiring Internet access</a></li> +<li class="toctree-l2"><a class="reference internal" href="#tests-aborting-due-to-assertions">Tests aborting (due to assertions)</a></li> +<li class="toctree-l2"><a class="reference internal" href="#installing-extra-dependencies-in-test-environment-e-g-example-plugins">Installing extra dependencies in test environment (e.g. example plugins)</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="pytest.html">pytest recipes</a></li> +<li class="toctree-l1"><a class="reference internal" href="concept.html">Advanced concepts</a></li> +<li class="toctree-l1"><a class="reference internal" href="expert-multi.html">Expert python-r1 usage</a></li> +<li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li> +<li class="toctree-l1"><a class="reference internal" href="porting.html">Porting tips</a></li> +<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration guides</a></li> +<li class="toctree-l1"><a class="reference internal" href="package-maintenance.html">Python package maintenance</a></li> +<li class="toctree-l1"><a class="reference internal" href="interpreter-maintenance.html">Maintenance of Python implementations</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="depend.html" title="previous chapter">Advanced dependencies</a></li> + <li>Next: <a href="pytest.html" title="next chapter">pytest recipes</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Michał Górny, license: CC BY 4.0. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/test.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file |
