From 468512a8cdbd6211667c45ea1898c72668f4ca80 Mon Sep 17 00:00:00 2001 From: Jim Hall Date: Thu, 8 Oct 2020 08:21:34 -0400 Subject: [PATCH 1/2] Language added to confirm proper installation of ghostscript libraries --- docs/user/install-deps.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/user/install-deps.rst b/docs/user/install-deps.rst index f0ce2ae..fb37806 100755 --- a/docs/user/install-deps.rst +++ b/docs/user/install-deps.rst @@ -72,3 +72,31 @@ Or for Windows 32-bit:: C:\> gswin32c.exe -version If you have ghostscript, you should see the ghostscript version and copyright information. + +If you choose not to install ghostscript using the Camelot `OS-specific +instructions`_, there is risk of an incomplete installation (for example, +the choosen distribution only installs the ghostscript ``gs`` binary and not +the libraries). + +.. _OS-specific instructions: #os-specific-instructions + +If the ghostscript application libraries are not installed correctly, the +attempt to use ``read_pdf`` (using the example on the Camelot home page) will +fail as follows (Traceback truncated - full example stack trace available +`here`_):: + + >>> import camelot + >>> tables = camelot.read_pdf('foo.pdf') + OSError: dlopen(libgs.so, 6): image not found + +.. _here: https://github.com/camelot-dev/camelot/issues/193 + +A correct installation of ghostscript will result in the example returning a +TableList object:: + + >>> import camelot + >>> tables = camelot.read_pdf('foo.pdf') + >>> tables + + + From de6faa7af1211a6bd1efc26dcde896d8734420dc Mon Sep 17 00:00:00 2001 From: Vinayak Mehta Date: Sun, 18 Oct 2020 03:13:21 +0530 Subject: [PATCH 2/2] Add new checks --- docs/user/install-deps.rst | 111 ++++++++++++------------------------- docs/user/install.rst | 33 +++++------ 2 files changed, 48 insertions(+), 96 deletions(-) diff --git a/docs/user/install-deps.rst b/docs/user/install-deps.rst index fb37806..461a1d3 100755 --- a/docs/user/install-deps.rst +++ b/docs/user/install-deps.rst @@ -3,100 +3,59 @@ Installation of dependencies ============================ -The dependencies `Tkinter`_ and `ghostscript`_ can be installed using your system's package manager. You can run one of the following, based on your OS. - -.. _Tkinter: https://wiki.python.org/moin/TkInter -.. _ghostscript: https://www.ghostscript.com +The dependencies `Ghostscript `_ and `Tkinter `_ can be installed using your system's package manager or by running their installer. OS-specific instructions ------------------------ -For Ubuntu -^^^^^^^^^^ +Ubuntu +^^^^^^ :: - $ apt install python-tk ghostscript + $ apt install ghostscript python3-tk -Or for Python 3:: - - $ apt install python3-tk ghostscript - -For macOS -^^^^^^^^^ +MacOS +^^^^^ :: - $ brew install tcl-tk ghostscript + $ brew install ghostscript tcl-tk -For Windows -^^^^^^^^^^^ +Windows +^^^^^^^ -For Tkinter, you can download the `ActiveTcl Community Edition`_ from ActiveState. For ghostscript, you can get the installer at the `ghostscript downloads page`_. +For Ghostscript, you can get the installer at their `downloads page `_. And for Tkinter, you can download the `ActiveTcl Community Edition `_ from ActiveState. -.. _ActiveTcl Community Edition: https://www.activestate.com/activetcl/downloads -.. _ghostscript downloads page: https://www.ghostscript.com/download/gsdnld.html -.. _as shown here: https://java.com/en/download/help/path.xml +Checks to see if dependencies are installed correctly +----------------------------------------------------- -Checks to see if dependencies were installed correctly ------------------------------------------------------- +You can run the following checks to see if the dependencies were installed correctly. -You can do the following checks to see if the dependencies were installed correctly. +For Ghostscript +^^^^^^^^^^^^^^^ + +Open the Python REPL and run the following: + +For Ubuntu/MacOS:: + + >>> from ctypes.util import find_library + >>> find_library("gs") + "libgs.so.9" + +For Windows:: + + >>> from ctypes.util import find_library + >>> find_library("".join(("gsdll", str(ctypes.sizeof(ctypes.c_voidp) * 8), ".dll")) + + +**Check:** The output of the ``find_library`` function should not be empty. + +If the output is empty, then it's possible that the Ghostscript library is not available one of the ``LD_LIBRARY_PATH``/``DYLD_LIBRARY_PATH``/``PATH`` variables depending on your operating system. In this case, you may have to modify one of those path variables. For Tkinter ^^^^^^^^^^^ -Launch Python, and then at the prompt, type:: - - >>> import Tkinter - -Or in Python 3:: +Launch Python and then import Tkinter:: >>> import tkinter -If you have Tkinter, Python will not print an error message, and if not, you will see an ``ImportError``. - -For ghostscript -^^^^^^^^^^^^^^^ - -Run the following to check the ghostscript version. - -For Ubuntu/macOS:: - - $ gs -version - -For Windows:: - - C:\> gswin64c.exe -version - -Or for Windows 32-bit:: - - C:\> gswin32c.exe -version - -If you have ghostscript, you should see the ghostscript version and copyright information. - -If you choose not to install ghostscript using the Camelot `OS-specific -instructions`_, there is risk of an incomplete installation (for example, -the choosen distribution only installs the ghostscript ``gs`` binary and not -the libraries). - -.. _OS-specific instructions: #os-specific-instructions - -If the ghostscript application libraries are not installed correctly, the -attempt to use ``read_pdf`` (using the example on the Camelot home page) will -fail as follows (Traceback truncated - full example stack trace available -`here`_):: - - >>> import camelot - >>> tables = camelot.read_pdf('foo.pdf') - OSError: dlopen(libgs.so, 6): image not found - -.. _here: https://github.com/camelot-dev/camelot/issues/193 - -A correct installation of ghostscript will result in the example returning a -TableList object:: - - >>> import camelot - >>> tables = camelot.read_pdf('foo.pdf') - >>> tables - - - +**Check:** Importing ``tkinter`` should not raise an import error. diff --git a/docs/user/install.rst b/docs/user/install.rst index 422f118..e7bf89e 100644 --- a/docs/user/install.rst +++ b/docs/user/install.rst @@ -5,42 +5,35 @@ Installation of Camelot This part of the documentation covers the steps to install Camelot. -Using conda ------------ +After :ref:`installing the dependencies `, which include `Ghostscript `_ and `Tkinter `_, you can use one of the following methods to install Camelot: -The easiest way to install Camelot is to install it with `conda`_, which is a package manager and environment management system for the `Anaconda`_ distribution. -:: +.. warning:: The ``lattice`` flavor will fail to run if Ghostscript is not installed. You may run into errors as shown in `issue #193 `_. - $ conda install -c conda-forge camelot-py +pip +--- -.. note:: Camelot is available for Python 2.7, 3.5, 3.6 and 3.7 on Linux, macOS and Windows. For Windows, you will need to install ghostscript which you can get from their `downloads page`_. - -.. _conda: https://conda.io/docs/ -.. _Anaconda: http://docs.continuum.io/anaconda/ -.. _downloads page: https://www.ghostscript.com/download/gsdnld.html -.. _conda-forge: https://conda-forge.org/ - -Using pip ---------- - -After :ref:`installing the dependencies `, which include `Tkinter`_ and `ghostscript`_, you can simply use pip to install Camelot:: +To install Camelot from PyPI using ``pip``, please include the extra ``cv`` requirement as shown:: $ pip install "camelot-py[cv]" -.. _Tkinter: https://wiki.python.org/moin/TkInter -.. _ghostscript: https://www.ghostscript.com +conda +----- + +`conda`_ is a package manager and environment management system for the `Anaconda `_ distribution. It can be used to install Camelot from the ``conda-forge`` channel:: + + $ conda install -c conda-forge camelot-py From the source code -------------------- -After :ref:`installing the dependencies `, you can install from the source by: +After :ref:`installing the dependencies `, you can install Camelot from source by: 1. Cloning the GitHub repository. :: $ git clone https://www.github.com/camelot-dev/camelot -2. Then simply using pip again. +2. And then simply using pip again. :: $ cd camelot