python-r1.eclass: use python_has_version in examples of python_check_deps()

[whitslack]

The python_check_deps() examples given in the documentation of several functions and variables in python-r1.eclass and python-any-r1.eclass are incorrect. The default behavior of has_version() is to check the runtime system (RDEPEND), but python_check_deps() is meant to check that the build system (BDEPEND) has a suitable Python environment. The examples fail to do this and thus likely are leading developers to write incorrect python_check_deps() functions in their ebuilds. Thankfully, python-utils-r1.eclass supplies a python_has_version() function that defaults to checking the build system and implements some other enhancements that make it nicer for use in python_check_deps(). Change the examples to use python_has_version.

This PR fixes Bug 835462.

[gentoo-bot]

Pull Request assignment

Submitter: @whitslack
Areas affected: eclasses
Packages affected: (none)

@gentoo/github

Linked bugs

Bugs linked: 835462

New packages

This Pull Request appears to be introducing new packages only. Due to limited manpower, adding new packages is considered low priority. This does not mean that your Pull Request will not receive any attention, however, it might take quite some time for it to be reviewed. In the meantime, your new ebuild might find a home in the GURU project repository: the ebuild repository maintained collaboratively by Gentoo users. GURU offers your ebuild a place to be reviewed and improved by other Gentoo users, while making it easy for Gentoo users to install it and enjoy the software it adds.

---

In order to force reassignment and/or bug reference scan, please append [please reassign] to the pull request title.

Docs: Code of Conduct ● Copyright policy (expl.) ● Devmanual ● GitHub PRs ● Proxy-maint guide

[gentoo-repo-qa-bot]

Pull request CI report

Report generated at: 2022-03-18 23:47 UTC
Newest commit scanned: e5e2f70
Status: ✅ good

There are existing issues already. Please look into the report to make sure none of them affect the packages in question:
https://qa-reports.gentoo.org/output/gentoo-ci/95e2dbe9f2/output.html

[gentoo-repo-qa-bot]

Pull request CI report

Report generated at: 2022-03-19 00:03 UTC
Newest commit scanned: 880156e
Status: ✅ good

There are existing issues already. Please look into the report to make sure none of them affect the packages in question:
https://qa-reports.gentoo.org/output/gentoo-ci/e7e6cbf1bb/output.html

[mgorny]

I think the newer examples prefer:

use doc || return 0
python_has_version ...

[whitslack]

Okay, I'll change it to that for consistency. It's functionally identical, though, right? And what if you had multiple different sets of use flags to check?

BDEPEND="$(python_gen_any_dep '
    foo? ( dev-python/foo[${PYTHON_USEDEP}] )
    bar? ( dev-python/bar[${PYTHON_USEDEP}] )
')"

Then what would you put in python_check_deps()? I like my way because it structurally mirrors the syntax of BDEPEND.

python_check_deps() {
    { use !foo || python_has_version "dev-python/foo[${PYTHON_USEDEP}]"; } &&
    { use !bar || python_has_version "dev-python/bar[${PYTHON_USEDEP}]"; }
}

[mgorny]

But that thing is horribly hard to read. Even the foo && { bar || baz; } thing is ugly. To be honest, I'm wondering if maybe we should just remove the examples from eclassdoc and expect people to read the Guide.

[whitslack]

But that thing is horribly hard to read.

Is it? Maybe for a complete n00b of a programmer. But again, I really was asking what you would put in python_check_deps() in such a case. Would you write it all out like this?:

python_check_deps() {
    if use foo ; then
        python_has_version "dev-python/foo[${PYTHON_USEDEP}]" || return $?
    fi
    if use bar ; then
        python_has_version "dev-python/bar[${PYTHON_USEDEP}]" || return $?
    fi
}

Are you really arguing that that's less "horrible" than the compact form that I wrote using &&?

Anyway, I find the whole mechanism of python_check_deps() really awkward, as it requires duplicating the python_gen_any_dep dependencies of the package but with different syntax. It would be so much nicer if an ebuild author could write:

BDEPEND="$(python_gen_any_dep '
    foo? ( dev-python/foo[${PYTHON_SINGLE_USEDEP}] )
    || ( dev-python/bar[${PYTHON_USEDEP}]
         dev-python/baz[${PYTHON_USEDEP}] )
')"

python_get_any_deps() {
    echo "
        foo? ( dev-python/foo[${PYTHON_SINGLE_USEDEP}] )
        || ( dev-python/bar[${PYTHON_USEDEP}]
             dev-python/baz[${PYTHON_USEDEP}] )
    "
}

And then the eclass would handle parsing of the returned dependency spec, including the flag? ( … ) and || ( … ) syntaxes. This would allow a straight copy+paste of the value of the python_gen_any_dep argument to the python_get_any_deps() output, with just a change from single-quoting to double-quoting to enable variable substitution.

This solution could co-exist with python_check_deps().

---

Side note: A devilishly clever ebuild author could even avoid the copy+paste rigmarole by doing this:

python_get_any_deps() {
    echo "
        foo? ( dev-python/foo[${PYTHON_SINGLE_USEDEP}] )
        || ( dev-python/bar[${PYTHON_USEDEP}]
             dev-python/baz[${PYTHON_USEDEP}] )
    "
}

BDEPEND="$(python_gen_any_dep "$(
    PYTHON_SINGLE_USEDEP='${PYTHON_SINGLE_USEDEP}' \
    PYTHON_USEDEP='${PYTHON_USEDEP}' \
    python_get_any_deps)")"

Effectively reusing the ebuild's definition of python_get_any_deps() to construct the argument to python_gen_any_dep.

[whitslack]

I have implemented the python_get_any_deps() alternative in #24677. Please have a look there.

[mgorny]

I'm sorry, I have forgotten about this. I'll merge it now since the doc changes are good.

[thesamesam]

commit f80b0ac
Author: Matt Whitlock gentoo@mattwhitlock.name
Date: Fri Mar 18 17:44:05 2022 -0400

python{,-any}-r1.eclass: use python_has_version in examples

The python_check_deps() examples given in the documentation of several
functions and variables in python-r1.eclass and python-any-r1.eclass are
incorrect. The default behavior of has_version() is to check the
*runtime* system (RDEPEND), but python_check_deps() is meant to check
that the *build* system (BDEPEND) has a suitable Python environment. The
examples fail to do this and thus likely are leading developers to write
incorrect python_check_deps() functions in their ebuilds. Thankfully,
python-utils-r1.eclass supplies a python_has_version() function that
defaults to checking the build system and implements some other
enhancements that make it nicer for use in python_check_deps(). Change
the examples to use python_has_version.

Closes: https://bugs.gentoo.org/835462
Signed-off-by: Matt Whitlock <gentoo@mattwhitlock.name>
Signed-off-by: Michał Górny <mgorny@gentoo.org>