caveats: recommend Python .pth file instead.

This is better than PYTHONPATH as it doesn't mess with incompatible
versions of Python.

Closes Homebrew#27138.

Library/Homebrew/caveats.rb

@@ -46,17 +46,22 @@ def zsh_completion_caveats
   end
 
   def python_caveats
+    return unless keg
+    return unless keg.python_site_packages_installed?
+    return if Formula["python"].installed?
     site_packages = if f.keg_only?
       "#{f.opt_prefix}/lib/python2.7/site-packages"
     else
       "#{HOMEBREW_PREFIX}/lib/python2.7/site-packages"
     end
-    if keg and keg.python_site_packages_installed? \
-      and !ENV['PYTHONPATH'].to_s.include? site_packages
-      <<-EOS.undent
-        Set PYTHONPATH if you need Python to find the installed site-packages:
-          export PYTHONPATH=#{site_packages}:$PYTHONPATH
-      EOS
+    dir = "~/Library/Python/2.7/lib/python/site-packages"
+    dir_path = Pathname.new(dir).expand_path
+    file = "#{dir}/homebrew.pth"
+    file_path = Pathname.new(file).expand_path
+    if !file_path.readable? || !file_path.read.include?(site_packages)
+      s = "If you need Python to find the installed site-packages:\n"
+      s += "  mkdir -p #{dir}\n" unless dir_path.exist?
+      s += "  echo '#{site_packages}' >> #{file}"
     end
   end