Better default locations for downloads and for searching for pandoc binary

The default download path is now set to a platform specific path:

* ~/bin on Linux
* ~\AppData\Local\Pandoc on windows (also the default install location for pandoc)
* ~/Applications/pandoc on Mac OS X

In addition to these paths we also look into ~/.bin on linux and the python
script/bin path. The last ensures that pandoc can be installed into a virtual
env and is found even if the env is not activated (only run a python directly
from that path).

Together these changes ensure that

* conda packages can be created for pandoc and these pandoc installs are found.
* even if a default pandoc install wasn't added to the PATH on windows, it will
  be found.
* On all platforms, we have a proper default install location if a user will use
  `pypandoc.pandoc_download.download_pandoc()`

Author: jankatins

pypandoc/__init__.py

@@ -9,10 +9,13 @@
 
 from .py3compat import string_types, cast_bytes, cast_unicode
 
+from pypandoc.pandoc_download import DEFAULT_TARGET_FOLDER, download_pandoc
+
 __author__ = u'Juho Vepsäläinen'
 __version__ = '1.1.3'
 __license__ = 'MIT'
-__all__ = ['convert', 'get_pandoc_formats', 'get_pandoc_version', 'get_pandoc_path']
+__all__ = ['convert', 'get_pandoc_formats', 'get_pandoc_version',
+           'get_pandoc_path', 'download_pandoc']
 
 
 def convert(source, to, format=None, extra_args=(), encoding='utf-8',
@@ -262,7 +265,8 @@ def get_pandoc_path():
     to be callable (i.e. we could get version information from `pandoc --version`).
     If `PYPANDOC_PANDOC` is set and valid, it will return that value. If the environment
     variable is not set, either the full path to the included pandoc or the pandoc in
-    `PATH` (whatever is the higher version) will be returned.
+    `PATH` or a pandoc in some of the more usual (platform specific) install locations
+    (whatever is the higher version) will be returned.
 
     If a cached path is found, it will return the cached path and stop probing Pandoc
     (unless :func:`clean_pandocpath_cache()` is called).
@@ -280,12 +284,32 @@ def _ensure_pandoc_path():
         included_pandoc = os.path.join(os.path.dirname(os.path.realpath(__file__)),
                                        "files", "pandoc")
         search_paths = ["pandoc",  included_pandoc]
+        pf = "linux" if sys.platform.startswith("linux") else sys.platform
+        try:
+            search_paths.append(os.path.join(DEFAULT_TARGET_FOLDER[pf], "pandoc"))
+        except:
+            # not one of the know platforms...
+            pass
+        if pf == "linux":
+            # Currently we install into ~/bin, but this is equally likely...
+            search_paths.append("~/.bin/pandoc")
+        # Also add the interpreter script path, as that's where pandoc could be
+        # installed if it's an environment and the environment wasn't activated
+        if pf == "win32":
+            search_paths.append(os.path.join(sys.exec_prefix, "Scripts"))
+            # on windows, Library\bin could also be used, but that's already in
+            # path by the interpreter!
+        else:
+            search_paths.append(os.path.join(sys.exec_prefix, "bin"))
         # If a user added the complete path to pandoc to an env, use that as the
         # only way to get pandoc so that a user can overwrite even a higher
         # version in some other places.
         if os.getenv('PYPANDOC_PANDOC', None):
             search_paths = [os.getenv('PYPANDOC_PANDOC')]
         for path in search_paths:
+            # Needed for windows and subprocess which can't expand it on it's
+            # own...
+            path = os.path.expanduser(path)
             curr_version = [0, 0, 0]
             version_string = "0.0.0"
             try:
@@ -334,7 +358,8 @@ def _ensure_pandoc_path():
 
             """))
             raise OSError("No pandoc was found: either install pandoc and add it\n"
-                          "to your PATH or install pypandoc wheels with included pandoc.")
+                          "to your PATH or or call pypandoc.download_pandoc(...) or\n"
+                          "install pypandoc wheels with included pandoc.")
 
 
 # -----------------------------------------------------------------------------

pypandoc/pandoc_download.py

@@ -23,6 +23,12 @@
     "darwin": "https://github.com/jgm/pandoc/releases/download/1.16.0.2/pandoc-1.16.0.2-osx.pkg"
 }
 
+DEFAULT_TARGET_FOLDER = {
+    "win32": "~\\AppData\\Local\\Pandoc",
+    "linux": "~/bin",
+    "darwin": "~/Applications/pandoc"
+}
+
 
 def _handle_linux(filename, targetfolder):
 
@@ -45,7 +51,7 @@ def _handle_linux(filename, targetfolder):
             print("* Copying %s to %s ..." % (exe, targetfolder))
             shutil.copyfile(src, dst)
         src = os.path.join(tempfolder, "usr", "share", "doc", "pandoc", "copyright")
-        dst = os.path.join(targetfolder, "copyright")
+        dst = os.path.join(targetfolder, "copyright.pandoc")
         print("* Copying copyright to %s ..." % (targetfolder))
         shutil.copyfile(src, dst)
     finally:
@@ -102,17 +108,33 @@ def _handle_win32(filename, targetfolder):
 
 
 def download_pandoc(url=None, targetfolder=None):
+    """Download and unpack pandoc
+
+    Downloads prebuild binaries for pandoc from `url` and unpacks it into
+    `targetfolder`.
+
+    :param str url: URL for the to be downloaded pandoc binary distribution for
+        the platform under which this python runs. If no `url` is give, uses
+        the latest available release at the time pypandoc was released.
+
+    :param str targetfolder: directory, where the binaries should be installed
+        to. If no `targetfolder` is give, uses a platform specific user
+        location: `~/bin` on Linux, `~/Applications/pandoc` on Mac OS X, and
+        `~\\AppData\\Local\\Pandoc` on Windows.
+    """
     pf = sys.platform
+
     # compatibility with py3
     if pf.startswith("linux"):
         pf = "linux"
-        assert platform.architecture()[0] == "64bit", "Linux pandoc is only compiled for 64bit."
+        if platform.architecture()[0] != "64bit":
+            raise RuntimeError("Linux pandoc is only compiled for 64bit.")
+
+    if pf not in PANDOC_URLS:
+        raise RuntimeError("Can't handle your platform (only Linux, Mac OS X, Windows).")
 
     if url is None:
-        try:
-            url = PANDOC_URLS[pf]
-        except:
-            raise Exception("No prebuilt pandoc available or not yet implemented for your platform")
+        url = PANDOC_URLS[pf]
 
     filename = url.split("/")[-1]
     if os.path.isfile(filename):
@@ -123,8 +145,10 @@ def download_pandoc(url=None, targetfolder=None):
         response = urlopen(url)
         with open(filename, 'wb') as out_file:
             shutil.copyfileobj(response, out_file)
+
     if targetfolder is None:
-        targetfolder = os.path.join(os.path.dirname(os.path.realpath(__file__)), "pypandoc", "files")
+        targetfolder = DEFAULT_TARGET_FOLDER[pf]
+    targetfolder = os.path.expanduser(targetfolder)
 
     # Make sure target folder exists...
     try:

setup.py

@@ -15,7 +15,7 @@
 try:
     long_description = pypandoc.convert('README.md', 'rst')
     long_description = long_description.replace("\r","")
-except OSError:
+except OSError as e:
     print("\n\n!!! pandoc not found, long_description is bad, don't upload this to PyPI !!!\n\n")
     import io
     # pandoc is not installed, fallback to using raw contents