From 9902cb2c6447e58ef12438ac711addc192b8f1f5 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Wed, 21 Mar 2018 14:41:30 -0400 Subject: Added back in preference for gnureadline if it is present Now that the crash bug in the gnureadline Python module which statically links against a compatible version of GNU Readline has been fixed for macOS, we added back in the top-level import boilerplate to prefer it if it is available. Also updated some documentation in relation to getting readline installed for macOS. --- cmd2.py | 14 +++++++++----- docs/index.rst | 7 ++++--- docs/install.rst | 31 +++++++++++++++++++++++++++++-- 3 files changed, 42 insertions(+), 10 deletions(-) diff --git a/cmd2.py b/cmd2.py index 525c0dac..8f137aaf 100755 --- a/cmd2.py +++ b/cmd2.py @@ -88,13 +88,17 @@ try: except ImportError: ipython_available = False -# Try to import readline, but allow failure for convenience in Windows unit testing -# Note: If this actually fails, you should install readline on Linux or Mac or pyreadline on Windows +# Prefer statically linked gnureadline if available (for macOS compatibility due to issues with libedit) try: - # noinspection PyUnresolvedReferences - import readline + import gnureadline as readline except ImportError: - pass + # Try to import readline, but allow failure for convenience in Windows unit testing + # Note: If this actually fails, you should install readline on Linux or Mac or pyreadline on Windows + try: + # noinspection PyUnresolvedReferences + import readline + except ImportError: + pass # BrokenPipeError and FileNotFoundError exist only in Python 3. Use IOError for Python 2. if six.PY3: diff --git a/docs/index.rst b/docs/index.rst index 2f2a8dad..b034dafd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,9 +35,10 @@ The basic use of ``cmd2`` is identical to that of cmd_. The tab-completion feature provided by cmd_ relies on underlying capability provided by GNU readline or an equivalent library. Linux distros will almost always come with the required library installed. - For macOS, we recommend using the `Homebrew `_ package manager to install the ``readline`` package; - alternatively for macOS the ``conda`` package manager that comes with the Anaconda Python distro can be used to - install ``readline`` (preferably from conda-forge). + For macOS, we recommend using the `gnureadline `_ Python module which includes + a statically linked version of GNU readline. Alternatively on macOS the ``conda`` package manager that comes + with the Anaconda Python distro can be used to install ``readline`` (preferably from conda-forge) or the + `Homebrew `_ package manager can be used to to install the ``readline`` package. For Windows, we recommend installing the `pyreadline `_ Python module. Resources diff --git a/docs/install.rst b/docs/install.rst index 2c247a3e..b6ee0aff 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,5 +1,4 @@ -========================= Installation Instructions ========================= @@ -138,5 +137,33 @@ Extra requirement for Python 2.7 only If you want to be able to pipe the output of commands to a shell command on Python 2.7, then you will need one additional package installed: - * subprocess32 + * subprocess32gNU + +Extra requirement for macOS +=========================== +macOS comes with the `libedit `_ library which is similar, but not identical, to GNU Readline. +Tab-completion for ``cmd2`` applications is only tested against GNU Readline. + +There are several ways GNU Readline can be installed within a Python environment on a Mac, detailed in the following subsections. + +gnureadline Python module +------------------------- +Install the `gnureadline `_ Python module which is statically linked against a specific compatible version of GNU Readline:: + + pip install -U gnureadline + +readline via conda +------------------ +Install the **readline** package using the ``conda`` package manager included with the Anaconda Python distribution:: + + conda install readline + +readline via brew +----------------- +Install the **readline** package using the Homebrew package manager (compiles from source):: + + brew install openssl + brew install pyenv + brew install readline +Then use pyenv to compile Python and link against the installed readline -- cgit v1.2.1