Bug#791345: python-apt: apt_pkg.Dependency: Documentation for smart_target_pkg is plain wrong
Package: python-apt
Version: 1.0.0~beta3
Severity: minor
Hi everyone,
The documentation for apt_pkg.Dependency.smart_target_pkg is plain
wrong. The current documentation is:
"Return a Version object of a package which satisfies the dependency and
does not conflict with installed packages (the ‘natural target’)."
The python-apt code in question is here:
----------------------------------------
https://anonscm.debian.org/cgit/apt/python-apt.git/tree/doc/source/library/apt_pkg.rst?id=fdd173dd444098ed533cbcd541a7f10f228bc47e#n1015
https://anonscm.debian.org/cgit/apt/python-apt.git/tree/python/cache.cc?id=fdd173dd444098ed533cbcd541a7f10f228bc47e#n1344
https://anonscm.debian.org/cgit/apt/python-apt.git/tree/python/cache.cc?id=fdd173dd444098ed533cbcd541a7f10f228bc47e#n1385
https://anonscm.debian.org/cgit/apt/python-apt.git/tree/python/cache.cc?id=fdd173dd444098ed533cbcd541a7f10f228bc47e#n1485
The Apt code in question is here:
---------------------------------
https://anonscm.debian.org/cgit/apt/apt.git/tree/apt-pkg/pkgcache.cc?id=439b024abe8fd6b8227a8b2869aab65a1186cfda#n559
Issues with the documentation:
------------------------------
1) The method returns an apt_pkg.Package object (or None) and not an
apt_pkg.Version object as documented.
2) smart_target_pkg returns for most dependencies None which is
unexpected as the apt_pkg.Dependency.all_targets method returns in
nearly all cases apt_pkg.Version objects even if smart_target_pkg
returns None. Once I had a look on the Apt's C++ code it was obvious
that smart_target_pkg returns None for all target packages that have an
empty provides list. The documentation for smart_target_pkg doesn't
even mention the word "provides" though.
3) Looking at Apt's C++ code the SmartTargetPkg method then it is
obvious that it doesn't necessarily return a package that satisfies the
dependency because there are not enough checks for that and it
absolutely doesn't check anything with regards to conflicts.
4) If all_targets for a dependency returns an empty list it is still
possible for smart_target_pkg to return a Package object that is on
closer inspection not suitable to satisfy the dependency. This is rare
but nevertheless there should be a warning in the documentation that
smart_target_pkg can return an unsuitable package because of lack of checks.
5) Looking at the C++ code the first best package which meets the view
criteria is retured and the rest aren't even looked at. Hardly a
‘natural target’ if you ask me.
My conclusion:
--------------
To me it looks like smart_target_pkg is a very special helper function
within Apt and not useful for python-apt at all. smart_target_pkg
itself is only twice used within the whole Apt codebase:
https://anonscm.debian.org/cgit/apt/apt.git/tree/apt-pkg/algorithms.cc?id=439b024abe8fd6b8227a8b2869aab65a1186cfda#n580
https://anonscm.debian.org/cgit/apt/apt.git/tree/apt-private/private-output.cc?id=439b024abe8fd6b8227a8b2869aab65a1186cfda#n680
IMHO smart_target_pkg should be removed as all_targets is the better
alternative. If smart_target_pkg should stay then I recommend to fix
its documentation and to add target_pkg as well.
Best,
Michael Schaller
Reply to: