Inconsistent detection of python version in pybind11 and default cmake

[yesint]

If both python 2.7 and 3.5 are installed in Linux there is an inconsistent behavior (tested with cmake 3.5).
cmake functions find_package(PythonInterp) and find_package(PythonLibs) find 2.7 by default.
In contrast pybind11 finds 3.5 by default.
This leads to weird bugs in complex projects where pybind11 is used along with other python-related things because the order of find_package in CMakeLists.txt matters:

find_package(PythonInterp)
find_package(PythonLibs)
find_package(pybind11)
message(STATUS "Found pybind11 v${pybind11_VERSION}: ${pybind11_INCLUDE_DIRS}")

-- Found PythonInterp: /usr/bin/python (found version "2.7.12") 
-- Found PythonLibs: /usr/lib/x86_64-linux-gnu/libpython2.7.so (found version "2.7.11") 
-- Found PythonLibs: /usr/lib/x86_64-linux-gnu/libpython2.7.so
-- Performing Test HAS_CPP14_FLAG
-- Performing Test HAS_CPP14_FLAG - Success
-- Found pybind11 v2.2.dev0: /home/semen/programs/pteros/include;/usr/include/python2.7

Now the opposite way:

find_package(pybind11)
message(STATUS "Found pybind11 v${pybind11_VERSION}: ${pybind11_INCLUDE_DIRS}")
find_package(PythonInterp)
find_package(PythonLibs)

-- Found PythonInterp: /usr/bin/python3.5 (found version "3.5.2") 
-- Found PythonLibs: /usr/lib/x86_64-linux-gnu/libpython3.5m.so
-- Performing Test HAS_CPP14_FLAG
-- Performing Test HAS_CPP14_FLAG - Success
-- Found pybind11 v2.2.dev0: /home/semen/programs/pteros/include;/usr/include/python3.5m
-- Could NOT find PythonLibs (missing:  PYTHON_INCLUDE_DIRS)

This is very confusing. Imho, pybind11 should find 2.7 by default to be consistent with what one expects from default cmake behavior.
At least it worth mentioning this clearly in docs.

[wjakob]

The default find_package(PythonInterp) and find_package(PythonLibs) are terrible, it's IMO one of the worst-designed parts of CMake. I don't think we should try to follow their behavior in any way.

[yesint]

I totally agree that these things work absolutely inconsistent. However they are used often. May be just mention this in big red letters in the docs? :)

[wjakob]

Sure -- can you create a PR with your suggested wording?

[yesint]

Done. I'm hope that I did everything correctly - I'm new to github.

[Flamefire]

The module is even deprecated and find_package(Python3) should be used instead: https://cmake.org/cmake/help/v3.16/module/FindPythonInterp.html

[chaitan94]

I'm facing this issue too. Any plans to move to using find_package(Python) instead of find_package(PythonInterp)?

[henryiii]

Yep: #2370 :)