[gentoo-dev] PYTHON_DEPEND in EAPI >=4, PYTHON_BDEPEND

[Arfrever Frehtes Taifersar Arahesis]

I would like to introduce incompatible improvements in syntax of PYTHON_DEPEND variable in
EAPI >=4. The new syntax will depend on whether given package supports installation for
multiple Python ABIs. The extended functionality will replace PYTHON_USE_WITH* variables.

================================================================================================
PYTHON_DEPEND in EAPI <=3, PYTHON_USE_WITH*

(It's a reminder. No changes will occur here.)

PYTHON_DEPEND has 2 possible forms:
  PYTHON_DEPEND="${range_of_versions}"
  PYTHON_DEPEND="${USE_flag}? ${range_of_versions}"

This syntax doesn't allow to specify conditions depending on more than 1 USE flag.

PYTHON_USE_WITH and PYTHON_USE_WITH_OR specify USE dependencies. PYTHON_USE_WITH_OPT is used
to make PYTHON_USE_WITH or PYTHON_USE_WITH_OR conditional under a USE flag. It doesn't allow
to specify more complicated conditions (e.g. USE="A" enables dependency on Python[tk], while
USE="B" enables dependency on Python[xml]).

================================================================================================
PYTHON_DEPEND in EAPI >=4 in packages not supporting installation for multiple Python ABIs

Syntax of "${range_of_versions}" will remain the same as in EAPI <=3. The new syntax of
PYTHON_DEPEND will support USE conditionals and USE dependencies in {,R,P}DEPEND-style.
If PYTHON_DEPEND contains only 1 "${range_of_versions}", then no other elements in value of
whole PYTHON_DEPEND will be required. Otherwise each "${range_of_versions}" should be included
between "<<" and ">>" markers. Potential USE dependencies should be included between "[" and "]"
markers directly after given "${range_of_versions}".

Examples:
  # Dependency on Python 2.7 or 2.6.
  PYTHON_DEPEND="2:2.6"

  # 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 with "berkdb" or "gdbm" USE flag.
  PYTHON_DEPEND="|| ( <<2[berkdb]>> <<2[gdbm]>> )"

  # Dependency on Python 2 with "berkdb" or "gdbm" USE flag when "A" USE flag is enabled.
  PYTHON_DEPEND="A? ( || ( <<2[berkdb]>> <<2[gdbm]>> ) )"

The last 2 examples present replacement for PYTHON_USE_WITH_OR. PYTHON_USE_WITH_OR is used by
only 1 package and it's unlikely that there will be many other packages, so I don't plan to
introduce special, shorter syntax for specifying of USE flags of which at least one must be
enabled.

USE dependencies specified between "[" and "]" will be used literally in generated DEPEND and
RDEPEND.

Appropriate has_version() checks in python_pkg_setup() will be generated from PYTHON_DEPEND.
(They are generated from PYTHON_USE_WITH/PYTHON_USE_WITH_OR in EAPI <=3.)

If PYTHON_DEPEND is empty or unset, then no dependency on Python will be generated.

PYTHON_USE_WITH* variables will be banned in EAPI >=4.

================================================================================================
PYTHON_DEPEND in EAPI >=4 in packages supporting installation for multiple Python ABIs

Changes presented in this section can occur only if EAPI="4" contains support for dots in USE
flags.

The list of supported Python versions will depend only on RESTRICT_PYTHON_ABIS variable.
The new syntax of PYTHON_DEPEND will support USE conditionals and USE dependencies in
{,R,P}DEPEND-style. "<<>>" marker will be used to indicate dependencies on Python. Potential
USE dependencies should be included between "[" and "]" markers between "<<" and ">>".

If PYTHON_DEPEND is unset, then it will be treated as PYTHON_DEPEND="<<>>".
If PYTHON_DEPEND is set and empty, then no dependency on Python will be generated.

Examples:
  # No dependency on Python.
  PYTHON_DEPEND=""

  # Dependency on Python.
  # Unset PYTHON_DEPEND

  # 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 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 "berkdb" or "gdbm" USE flag.
  PYTHON_DEPEND="|| ( <<[berkdb]>> <<[gdbm]>> )"

  # Dependency on Python with "berkdb" or "gdbm" USE flag when "A" USE flag is enabled.
  PYTHON_DEPEND="A? ( || ( <<[berkdb]>> <<[gdbm]>> ) )"

Each "<<>>" will be replaced in generated DEPEND and RDEPEND by something similar to:
  python_abis_2.4? ( dev-lang/python:2.4 )
  python_abis_2.5? ( dev-lang/python:2.5 )
  python_abis_2.6? ( dev-lang/python:2.6 )
  python_abis_2.7? ( dev-lang/python:2.7 )
  python_abis_3.0? ( dev-lang/python:3.0 )
  python_abis_3.1? ( dev-lang/python:3.1 )
  python_abis_3.2? ( dev-lang/python:3.2 )
  python_abis_2.5-jython? ( dev-java/jython:2.5 )

If USE dependencies have been specified in PYTHON_DEPEND, then they will be used literally
in generated DEPEND and RDEPEND:
  python_abis_2.4? ( dev-lang/python:2.4[threads,xml] )
  python_abis_2.5? ( dev-lang/python:2.5[threads,xml] )
  ...

No has_version() checks in python_pkg_setup() will be generated from PYTHON_DEPEND.

PYTHON_USE_WITH* variables will be banned in EAPI >=4.

Appropriate REQUIRED_USE will be generated from PYTHON_DEPEND.

Examples:
  # Unset PYTHON_DEPEND or PYTHON_DEPEND="<<>>" can generate:
  REQUIRED_USE="|| ( python_abis_2.4 python_abis_2.5 python_abis_2.6 python_abis_2.7 python_abis_3.0 python_abis_3.0 python_abis_3.1 python_abis_3.2 python_abis_2.5-jython )"

  # PYTHON_DEPEND="A? ( B? ( <<[ncurses,threads]>> ) )" can generate:
  REQUIRED_USE="A? ( B? ( || ( python_abis_2.4 python_abis_2.5 python_abis_2.6 python_abis_2.7 python_abis_3.0 python_abis_3.0 python_abis_3.1 python_abis_3.2 python_abis_2.5-jython ) ) )"

================================================================================================
PYTHON_BDEPEND

I would also like to introduce PYTHON_BDEPEND variable, which will affect only DEPEND without
RDEPEND. PYTHON_BDEPEND will have the same syntax as PYTHON_DEPEND in given EAPI and type of
package. PYTHON_BDEPEND maybe won't affect REQUIRED_USE and has_version() checks in
python_pkg_setup(). PYTHON_BDEPEND won't affect PYTHON_DEPEND's influence on DEPEND
(dependencies will be concatenated). PYTHON_BDEPEND probably will be used mainly in packages
not supporting installation for multiple Python ABIs. In packages supporting installation for
multiple Python ABIs, PYTHON_BDEPEND can be useful only to specify USE dependencies (e.g. USE
dependencies conditional on "test" USE flag). Unset PYTHON_BDEPEND won't affect DEPEND.

-- 
Arfrever Frehtes Taifersar Arahesis