Preparing v0.1.0-beta

README.md

@@ -1,6 +1,31 @@
-pychimera - Use UCSF Chimera Python API in a standard interpreter
-=================================================================
+PyChimera
+=========
 
+Use [UCSF Chimera](https://www.cgl.ucsf.edu/chimera/) packages in any Python 2.7 interpreter 
+
+With PyChimera you can...
+
+* Enable `import chimera` in interactive coding sessions (console, notebooks) __outside Chimera__. 
+Just call `enable_chimera()`. _Careful! Call it prior to other code or you'll lose your previous work._
+* You can also launch Chimera-preenabled IPython sessions or Notebooks with `pychimera ipython` and 
+`pychimera notebook` respectively.
+* Run scripts depending on chimera __from CLI__ with either `pychimera` or `python -m chimera`. This 
+includes modules (`-m` flag) and strings (`-c` flag).
+
+I hope it's useful! Feedback is appreciated!
+
+Installation
+------------
+First, if you haven't already, install [latest UCSF Chimera](http://www.cgl.ucsf.edu/chimera/download.html).
+
+Then, install PyChimera via pip, conda or setup.py:
+
+    pip install pychimera
+    conda install -c insilichem pychimera
+    git clone https://github.com/insilichem/pychimera.git && python pychimera/setup.py install
+
+Usage
+-----
 Run `pychimera -h` for quick help.
 
 To start an interactive Python session:
@@ -27,7 +52,7 @@ To execute one or more scripts:
 
 For developers
 --------------
-`pychimera` provides access to Chimera's modules from any Python 2.x interpreter. This is achieved
+PyChimera provides access to Chimera's modules from any Python 2.x interpreter. This is achieved
 in two steps:
 
 1. `patch_environ()` patches environment variables with proper paths (packages and libraries).
@@ -36,9 +61,9 @@ packages with Chimera. This call restarts Python to inject a new `os.environ` wi
 
 2. `load_chimera()` initializes Chimera. This is done through their own routines (`chimeraInit`).
 
-You can call those two routines in your scripts to access Chimera packages.
+However, you may call the alias function `enable_chimera()` without worrying on the steps.
 
-pychimera also offers its interface through python `-m`. Add `-i` for interactive mode:
+PyChimera also offers its interface through python `-m`. Add `-i` for interactive mode:
 
     python -[i]m pychimera [-m another_module | -c "string" | script.py | ipython | notebook]
 
@@ -53,12 +78,16 @@ to run `pychimera ipython` and then call `%run path/to/file.py` inside the inter
 
 Notes
 -----
-Obviously, you need to install Chimera in your computer. `pychimera` will do its best to find the
+Obviously, you need to install Chimera in your computer. PyChimera will do its best to find the
 installation path automagically in the standard locations. If somehow it doesn't succeed,
 you can always set an environment variable called `CHIMERADIR` in your `.bashrc`, or similar.
 
     export CHIMERADIR="~/.local/UCSF-Chimera"
 
+Chimera bundles its own distribution of some popular packages, like numpy, and those are loaded before
+your env packages for compatibility reasons. Be warned if you use specific versions for your project,
+because you can face strange bugs if you don't take this into account.
+
 Acknowledgments
 ---------------
 Largely based on ideas by [Greg Couch at chimera-users](http://www.cgl.ucsf.edu/pipermail/chimera-users/2015-January/010647.html).

conda-recipe/meta.yaml

@@ -1,6 +1,6 @@
 package:
   name: pychimera
-  version: "0.0.8"
+  version: "0.1.0-beta"
 
 about:
   home: https://github.com/insilichem/pychimera

pychimera/__init__.py

@@ -1,4 +1,4 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-from pychimera import main, patch_environ, load_chimera
+from pychimera import main, patch_environ, load_chimera, enable_chimera

pychimera/pychimera.py

@@ -18,13 +18,17 @@
 import subprocess
 
 __author__ = "Jaime Rodríguez-Guerra"
-__version_info__ = (0, 0, 8)
+__version_info__ = (0, 1, 0)
 __version__ = '.'.join(map(str, __version_info__))
 
 
 def patch_environ():
     """
-    Patch current environment variables so Chimera can start up and we can import its modules
+    Patch current environment variables so Chimera can start up and we can import its modules.
+
+    Be warned that calling this function WILL restart your interpreter. Otherwise, Python
+    won't catch the new LD_LIBRARY_PATH (or platform equivalent) and Chimera won't find its
+    libraries during import.
     """
     if 'CHIMERA' not in os.environ:
         os.environ['TERM'] = "xterm-256color"
@@ -54,12 +58,21 @@ def patch_environ():
         os.execve(sys.executable, [sys.executable] + sys.argv, os.environ)
 
 
-def load_chimera():
+def load_chimera(verbose=False):
     """
     Bypass script loading and initialize Chimera in nogui mode.
+
+    Parameters
+    ----------
+    verbose : bool, optional, default=False
+        If True, let Chimera speak freely. It can be _very_ verbose.
     """
     import chimeraInit
-    chimeraInit.init(['', '--nostatus', '--silent', '--script', os.devnull],
+    if verbose:
+        verbosity = ['--debug']
+    else:
+        verbosity = ['--nostatus', '--silent']
+    chimeraInit.init([''] + verbosity + ['--script', os.devnull],
                      nogui=True, eventloop=False, exitonquit=False)
     del chimeraInit
 
@@ -91,6 +104,24 @@ def guess_chimera_path():
 
 
 def search_chimera(binary, directories, prefix):
+    """
+    Try running ``chimera --root`` in Chimera happens to be in PATH, otherwise
+    traverse usual installation locations to find the Chimera root path.
+
+    Parameters
+    ----------
+    binary : str
+        Name of the chimera executable in this platform
+    directories: list of str
+        Usual installation locations in this platform
+    prefix : str
+        Root directory prefix name in this platform
+
+    Returns
+    -------
+    paths : list of str
+        Sorted list of Chimera paths
+    """
     try:
         return subprocess.check_output([binary, '--root']).decode('utf-8').strip()
     except (OSError, subprocess.CalledProcessError, RuntimeError):
@@ -137,6 +168,9 @@ def run_cli_options():
 
 
 def check_ipython():
+    """
+    Check if an IPython launch has been requested from CLI
+    """
     global args, more_args
     if args.command == 'ipython':
         launch_ipython(more_args)
@@ -145,6 +179,9 @@ def check_ipython():
 
 
 def launch_ipython(argv=None):
+    """
+    Launch IPython from this interpreter with custom args if needed
+    """
     try:
         from IPython.terminal.ipapp import launch_new_instance
     except ImportError:
@@ -168,15 +205,19 @@ def in_ipython():
 def interactive_mode():
     """
     Check if we need to relaunch Python in interactive mode:
-
-    - sys.flags.interactive: First Python interpreter was called with -i
-    - len(sys.argv) <= 1: python or pychimera bare call
-    - -i* in sys.argv: pychimera has a -i flag in its call!
     """
     global args
     return any([args.interactive, sys.flags.interactive, len(sys.argv) <= 1])
 
 
+def enable_chimera(warn=True):
+    """
+    A simple alias to be called from interactive sessions, like IPython notebooks.
+    """
+    patch_environ()
+    load_chimera()
+
+
 def main():
     """
     1. Patch the environment with Python and libraries paths. This relaunches Python!

setup.py

@@ -4,7 +4,7 @@
 from setuptools import setup
 import os
 
-VERSION = "0.0.8"
+VERSION = "0.1.0-beta"
 
 
 def read(fname):
@@ -14,7 +14,7 @@ def read(fname):
     name='pychimera',
     version=VERSION,
     url='https://github.com/insilichem/pychimera',
-    download_url='https://github.com/insilichem/pychimera/tarball/' + VERSION,
+    download_url='https://github.com/insilichem/pychimera/tarball/v' + VERSION,
     license='LGPL',
     author="Jaime Rodríguez-Guerra",
     author_email='[email protected]',