Rewrite FindBoostPython.cmake for correctness and stability

1. Return compile check (see BoostPython_TRY_COMPILE() macro), it's
needed for some cases. Say, default Python in system is Python 3.3, and
it gets picked up. But Boost 1.53 python library could not work with it
and requires Python 2.x. Without compile check you'll pick up
uncompatible Python version.

2. find_package(PkgConfig) moved under corresponding if(...) and
if(PKG_CONFIG_FOUND) is checked after. While it's spread enough, there
is no guarantee you'll have pkg-config on that system. Also,
PYTHON_VERSIONS moved closer to the scope where it's used to improve
readability.

3. Use standard CMake find_package_handle_standard_args() and
cmake_push_check_state()/cmake_pop_check_state() instead of rolling own
equivalent logic. The latter logic was ever wrong, making
HAVE_BOOST_SHARED_PTR_HPP check fail.

4. BoostPython_INCLUDE_DIRS and BoostPython_LIBRARIES are saved in
cache, as other CMake modules do. This unbreaks the situation when CMake
detects that it should be re-run (for example, some CMakeLists.txt file
was modified), and runs through modules again - in this case, if
BoostPython_INCLUDE_DIRS and BoostPython_LIBRARIES are not in cache, all
tests will be run again, and probably fail now.

BUG: 320807
FIXED-IN: 4.12
REVIEW: 110954