diff --git a/README.md b/README.md index 95cdb89..934307a 100644 --- a/README.md +++ b/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). \ No newline at end of file diff --git a/conda-recipe/meta.yaml b/conda-recipe/meta.yaml index a76d501..d2f259e 100644 --- a/conda-recipe/meta.yaml +++ b/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 diff --git a/pychimera/__init__.py b/pychimera/__init__.py index cd8724b..595d0d3 100644 --- a/pychimera/__init__.py +++ b/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 diff --git a/pychimera/pychimera.py b/pychimera/pychimera.py index 0fe8473..f38ef80 100755 --- a/pychimera/pychimera.py +++ b/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! diff --git a/setup.py b/setup.py index 6e77108..cefece2 100644 --- a/setup.py +++ b/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='jaime.rogue@gmail.com',