SPECIFICATION OF DEPENDENCIES
[Progress Overlay]

1. PYTHON_DEPEND in newer EAPIs

	PYTHON_DEPEND has new syntax in:
		EAPI="4" + PYTHON_ECLASS_API="1"
		EAPI="4-python"

	PYTHON_DEPEND is a dependency string with <<>> markers.
	Dependency string can contain USE conditionals, which have the same syntax as in DEPEND, PDEPEND and RDEPEND.
	<<>> marker is a template of group of atoms of Python implementational packages.
	<<>> marker can contain USE dependencies, which have the same syntax as in DEPEND, PDEPEND and RDEPEND.

	In packages supporting installation for multiple Python ABIs:
		PYTHON_DEPEND="<<>>" is set by default.
		<<>> marker cannot contain versions range.
		PYTHON_RESTRICTED_ABIS affects expansion of <<>> markers.

	In packages not supporting installation for multiple Python ABIs:
		PYTHON_DEPEND is unset by default.
		<<>> marker must contain versions range.
		Versions ranges have the same syntax as in PYTHON_DEPEND in older EAPIs.
		If both versions range and USE dependencies are needed, then versions range must be specified before USE dependencies.
		Versions ranges affect expansion of <<>> markers.

	Examples in packages supporting installation for multiple Python ABIs:
		# No dependency on Python.
		PYTHON_DEPEND=""

		# Dependency on Python.
		# PYTHON_DEPEND unset

		# Dependency on Python.
		PYTHON_DEPEND="<<>>"

		# Dependency on Python when "A" USE flag is enabled.
		PYTHON_DEPEND="A? ( <<>> )"

		# Dependency on Python when "A" and "B" USE flags are enabled.
		PYTHON_DEPEND="A? ( B? ( <<>> ) )"

		# Dependency on Python when "A" and "B" USE flags are enabled and "C" USE flag is disabled.
		PYTHON_DEPEND="A? ( B? ( !C? ( <<>> ) ) )"

		# Dependency on Python when "A" or "B" USE flag is enabled.
		PYTHON_DEPEND="A? ( <<>> ) B? ( <<>> )"

		# Dependency on Python with "ncurses" USE flag.
		PYTHON_DEPEND="<<[ncurses]>>"

		# Dependency on Python with "ncurses", "threads" and "xml" USE flags.
		PYTHON_DEPEND="<<[ncurses,threads,xml]>>"

		# Dependency on Python with "ncurses" and "threads" USE flags, and "xml" USE flag when "xml" USE flag is enabled.
		PYTHON_DEPEND="<<[ncurses,threads,xml?]>>"

		# Dependency on Python with "ncurses" and "threads" USE flags, and "xml" USE flag when "A" USE flag is enabled.
		PYTHON_DEPEND="<<[ncurses,threads]>> A? ( <<[xml]>> )"

		# Dependency on Python with enabled "ncurses" USE flag and disabled "threads" USE flag.
		PYTHON_DEPEND="<<[ncurses,-threads]>>"

		# Dependency on Python with "ncurses", "threads" and "xml" USE flags when "A" USE flag is enabled.
		PYTHON_DEPEND="A? ( <<[ncurses,threads,xml]>> )"

		# Dependency on Python with "ncurses", "threads" and "xml" USE flags when "A" and "B" USE flags are enabled.
		PYTHON_DEPEND="A? ( B? ( <<[ncurses,threads,xml]>> ) )"

		# Dependency on Python always.
		# Dependency on Python with "ncurses" USE flag when "A" USE flag is enabled.
		# Dependency on Python with "xml" USE flag when "B" USE flag is enabled.
		PYTHON_DEPEND="<<>> A? ( <<[ncurses]>> ) B? ( <<[xml]>> )"

	Examples in packages not supporting installation for multiple Python ABIs:
		# Dependency on Python 2.7 or 2.6.
		PYTHON_DEPEND="<<2:2.6>>"

		# Dependency on Python 2.7 or 2.6 when "A" USE flag is enabled.
		PYTHON_DEPEND="A? ( <<2:2.6>> )"

		# Dependency on Python 2.7 or 2.6 when "A" and "B" USE flags are enabled.
		PYTHON_DEPEND="A? ( B? ( <<2:2.6>> ) )"

		# Dependency on Python 2.7 or 2.6 when "A" and "B" USE flags are enabled and "C" USE flag is disabled.
		PYTHON_DEPEND="A? ( B? ( !C? ( <<2:2.6>> ) ) )"

		# Dependency on Python 2 always, and 2.7 or 2.6 when "A" USE flag is enabled.
		PYTHON_DEPEND="<<2>> A? ( <<2:2.6>> )"

		# Dependency on Python 2 and 3. (It will probably never be used.)
		PYTHON_DEPEND="<<2>> <<3>>"

		# Dependency on Python 2 when "python2" USE flag is enabled, and Python 3 when "python3" USE flag is enabled.
		PYTHON_DEPEND="python2? ( <<2>> ) python3? ( <<3>> )"

		# Dependency on Python 2.7 or 2.6 with "ncurses", "threads" and "xml" USE flags.
		PYTHON_DEPEND="<<2:2.6[ncurses,threads,xml]>>"

		# Dependency on Python 2.7 or 2.6 with "ncurses" and "threads" USE flags, and "xml" USE flag when "xml" USE flag is enabled.
		PYTHON_DEPEND="<<2:2.6[ncurses,threads,xml?]>>"

		# Dependency on Python 2.7 or 2.6 with "ncurses" and "threads" USE flags, and "xml" USE flag when "A" USE flag is enabled.
		PYTHON_DEPEND="<<2:2.6[ncurses,threads]>> A? ( <<2:2.6[xml]>> )"

		# Dependency on Python 2.7 or 2.6 with enabled "ncurses" USE flag and disabled "threads" USE flag.
		PYTHON_DEPEND="<<2:2.6[ncurses,-threads]>>"

		# Dependency on Python 3.1, 2.6 or 2.5 with "ncurses" and "threads" USE flags.
		PYTHON_DEPEND="<<2:2.5:2.6 3:3.1:3.1[ncurses,threads]>>"

		# Dependency on Python 2.7 or 2.6 with "ncurses", "threads" and "xml" USE flags when "A" USE flag is enabled.
		PYTHON_DEPEND="A? ( <<2:2.6[ncurses,threads,xml]>> )"

		# Dependency on Python 2.7 or 2.6 with "ncurses", "threads" and "xml" USE flags when "A" and "B" USE flags are enabled.
		PYTHON_DEPEND="A? ( B? ( <<2:2.6[ncurses,threads,xml]>> ) )"

		# Dependency on Python 2.7 or 2.6 always.
		# Dependency on Python 2.7 or 2.6 with "ncurses" USE flag when "A" USE flag is enabled.
		# Dependency on Python 2.7 or 2.6 with "xml" USE flag when "B" USE flag is enabled.
		PYTHON_DEPEND="<<2:2.6>> A? ( <<2:2.6[ncurses]>> ) B? ( <<2:2.6[xml]>> )"

	Examples of expansion of <<>> marker:
		In packages supporting installation for multiple Python ABIs in EAPI="4-python":
			EAPI="4-python"
			PYTHON_DEPEND="A? ( B? ( <<[ssl,xml]>> ) )"
			PYTHON_MULTIPLE_ABIS="1"
			PYTHON_RESTRICTED_ABIS="3.*"

			Generated DEPEND and RDEPEND contain:
			A? ( B? (
				python_abis_2.4? ( dev-lang/python:2.4[ssl,xml] )
				python_abis_2.5? ( dev-lang/python:2.5[ssl,xml] )
				python_abis_2.6? ( dev-lang/python:2.6[ssl,xml] )
				python_abis_2.7? ( dev-lang/python:2.7[ssl,xml] )
				python_abis_2.5-jython? ( dev-java/jython:2.5[ssl,xml] )
				python_abis_2.6-jython? ( dev-java/jython:2.6[ssl,xml] )
				python_abis_2.7-pypy-1.7? ( dev-python/pypy:1.7[ssl,xml] )
			) )

			Generated REQUIRED_USE contains:
			A? ( B? ( || (
				python_abis_2.4
				python_abis_2.5
				python_abis_2.6
				python_abis_2.7
				python_abis_2.5-jython
				python_abis_2.6-jython
				python_abis_2.7-pypy-1.7
			) ) )"

			(Actual whitespace in generated DEPEND, RDEPEND and REQUIRED_USE is different.)

		In packages supporting installation for multiple Python ABIs in EAPI="4" + PYTHON_ECLASS_API="1":
			EAPI="4"
			PYTHON_ECLASS_API="1"
			PYTHON_DEPEND="A? ( B? ( <<[ssl,xml]>> ) )"
			PYTHON_MULTIPLE_ABIS="1"
			PYTHON_RESTRICTED_ABIS="3.*"

			Generated DEPEND and RDEPEND contain:
			A? ( B? ( || (
				dev-lang/python:2.7[ncurses,xml]
				dev-lang/python:2.6[ncurses,xml]
				dev-lang/python:2.5[ncurses,xml]
				dev-lang/python:2.4[ncurses,xml]
			) ) )

			(Actual whitespace in generated DEPEND and RDEPEND is different.)

			Generated checks code variables (python_pkg_setup() evaluates _PYTHON_USE_FLAGS_CHECKS_CODE):
			_PYTHON_DEPEND_CHECKS_CODE="if use A; then if use B; then return 0; fi; fi"
			_PYTHON_USE_FLAGS_CHECKS_CODE="if use A; then if use B; then if [[ \"\${PYTHON_ABI}\" == \"2.4\" ]] && ! has_version \"\$(python_get_implementational_package)[ssl,xml]\"; then die \"\$(python_get_implementational_package)[ssl,xml] not installed in ROOT=\\\"\${ROOT}\\\"\"; fi; if [[ \"\${PYTHON_ABI}\" == \"2.5\" ]] && ! has_version \"\$(python_get_implementational_package)[ssl,xml]\"; then die \"\$(python_get_implementational_package)[ssl,xml] not installed in ROOT=\\\"\${ROOT}\\\"\"; fi; if [[ \"\${PYTHON_ABI}\" == \"2.6\" ]] && ! has_version \"\$(python_get_implementational_package)[ssl,xml]\"; then die \"\$(python_get_implementational_package)[ssl,xml] not installed in ROOT=\\\"\${ROOT}\\\"\"; fi; if [[ \"\${PYTHON_ABI}\" == \"2.7\" ]] && ! has_version \"\$(python_get_implementational_package)[ssl,xml]\"; then die \"\$(python_get_implementational_package)[ssl,xml] not installed in ROOT=\\\"\${ROOT}\\\"\"; fi; if [[ \"\${PYTHON_ABI}\" == \"2.5-jython\" ]] && ! has_version \"\$(python_get_implementational_package)[ssl,xml]\"; then die \"\$(python_get_implementational_package)[ssl,xml] not installed in ROOT=\\\"\${ROOT}\\\"\"; fi; if [[ \"\${PYTHON_ABI}\" == \"2.6-jython\" ]] && ! has_version \"\$(python_get_implementational_package)[ssl,xml]\"; then die \"\$(python_get_implementational_package)[ssl,xml] not installed in ROOT=\\\"\${ROOT}\\\"\"; fi; if [[ \"\${PYTHON_ABI}\" == \"2.7-pypy-1.7\" ]] && ! has_version \"\$(python_get_implementational_package)[ssl,xml]\"; then die \"\$(python_get_implementational_package)[ssl,xml] not installed in ROOT=\\\"\${ROOT}\\\"\"; fi; fi; fi"

		In packages not supporting installation for multiple Python ABIs in EAPI="4" + PYTHON_ECLASS_API="1":
			EAPI="4"
			PYTHON_ECLASS_API="1"
			PYTHON_DEPEND="A? ( B? ( <<2[ssl,xml]>> ) )"

			Generated DEPEND and RDEPEND contain:
			A? ( B? ( =dev-lang/python-2*[ssl,xml] ) )

			Generated checks code variables (python_pkg_setup() evaluates _PYTHON_USE_FLAGS_CHECKS_CODE):
			_PYTHON_DEPEND_CHECKS_CODE="if use A; then if use B; then return 0; fi; fi"
			_PYTHON_USE_FLAGS_CHECKS_CODE="if use A; then if use B; then if ! has_version \"\$(python_get_implementational_package)[ssl,xml]\"; then die \"\$(python_get_implementational_package)[ssl,xml] not installed in ROOT=\\\"\${ROOT}\\\"\"; fi; fi; fi"

2. PYTHON_BDEPEND

	PYTHON_BDEPEND specifies build-time dependency on Python.
	PYTHON_BDEPEND has the same syntax as PYTHON_DEPEND in given EAPI and PYTHON_ECLASS_API.

================================================================================================
MIGRATION OF EBUILDS FROM EAPI="3" TO EAPI="4" + PYTHON_ECLASS_API="0"
[gentoo-x86 and Progress Overlay]

1. python_pkg_setup()

	python_pkg_setup() is unconditionally exported in EAPI >=4.
	If a different eclass exports ${ECLASS}_pkg_setup(), then it might be necessary to define explicit pkg_setup().

	Example:
		pkg_setup() {
			fortran-2_pkg_setup
			python_pkg_setup
		}

	Calling (at least implicit) of python_pkg_setup() is mandatory in EAPI >=4.

2. python_src_install()

	Internal behavior of python_src_install() is improved in EAPI >=4. This change should not affect 99% of packages.
	Installed scripts should be checked after changing of EAPI from <=3 to >=4.
	If any unwanted changes occurred, then PYTHON_VERSIONED_SCRIPTS / PYTHON_VERSIONED_EXECUTABLES / PYTHON_NONVERSIONED_EXECUTABLES
	should be properly defined.

3. DISTUTILS_GLOBAL_OPTIONS

	Syntax of each element of DISTUTILS_GLOBAL_OPTIONS should be changed from "${global_option}" to "${Python_ABIs_pattern} ${global_option}".

	Example:
		DISTUTILS_GLOBAL_OPTIONS=("* --some-option")

4. distutils_src_install(): *-nspkg.pth files

	distutils_src_install() no longer installs *-nspkg.pth files in EAPI >=4.
	distutils_src_install() prints information about required Python namespaces.

================================================================================================
MIGRATION OF EBUILDS FROM EAPI="4" + PYTHON_ECLASS_API="0" TO EAPI="4" + PYTHON_ECLASS_API="1"
[Progress Overlay]

1. Dependencies (PYTHON_DEPEND, PYTHON_BDEPEND, PYTHON_USE_WITH*)

	...

2. SUPPORT_PYTHON_ABIS, RESTRICT_PYTHON_ABIS

	SUPPORT_PYTHON_ABIS should be renamed to PYTHON_MULTIPLE_ABIS.
	RESTRICT_PYTHON_ABIS should be renamed to PYTHON_RESTRICTED_ABIS.
	If PYTHON_RESTRICTED_ABIS is needed, then it should be set before inheriting of python.eclass.

================================================================================================
MIGRATION OF EBUILDS FROM EAPI="4" + PYTHON_ECLASS_API="1" TO EAPI="4-python"
[Progress Overlay]

1. python_abi_depend()

	...

================================================================================================
DEPENDENCIES ON MODULES PRESENT BOTH IN STANDARD LIBRARY AND EXTERNAL PACKAGES
[Progress Overlay]

1. argparse

	Packages should depend on virtual/python-argparse.

	Example:
		RDEPEND="$(python_abi_depend virtual/python-argparse)"

2. simplejson / json

	dev-python/simplejson contains simplejson module.
	Python >=2.6 contains json module.

	If a package supports both simplejson and json modules and firstly tries to import simplejson module,
	then this package should depend on virtual/python-json[external].

	Example:
		RDEPEND="$(python_abi_depend virtual/python-json[external])"

	If a package supports both simplejson and json modules and firstly tries to import json module,
	then this package should depend on virtual/python-json.

	Example:
		RDEPEND="$(python_abi_depend virtual/python-json)"

3. pysqlite2 / sqlite3

	dev-python/pysqlite:2 contains pysqlite2 module.
	CPython >=2.5 contains sqlite3 module.

	If a package supports both pysqlite2 and sqlite3 modules and firstly tries to import pysqlite2 module,
	then this package should depend on virtual/python-sqlite[external].

	Example:
		RDEPEND="$(python_abi_depend virtual/python-sqlite[external])"

	If a package supports both pysqlite2 and sqlite3 modules and firstly tries to import sqlite3 module,
	then this package should depend on virtual/python-sqlite.

	Example:
		RDEPEND="$(python_abi_depend virtual/python-sqlite)"

================================================================================================
SETTING PREPROCESSOR/COMPILER/LINKER FLAGS SPECIFIC TO PYTHON ABIS
[gentoo-x86 and Progress Overlay]

1. Addition of flags

	...

2. Deletion of flags

	...