Merge branch 'history-access'

docs/examples/core/ipython-get-history.py

@@ -0,0 +1,38 b''
+#!/usr/bin/env python
+"""Extract a session from the IPython input history.
+
+Usage:
+  ipython-get-history.py sessionnumber [outputfile]
+
+If outputfile is not given, the relevant history is written to stdout. If
+outputfile has a .py extension, the translated history (without IPython's
+special syntax) will be extracted.
+
+Example:
+  ./ipython-get-history.py 57 record.ipy
+
+
+This script is a simple demonstration of HistoryAccessor. It should be possible
+to build much more flexible and powerful tools to browse and pull from the
+history database.
+"""
+import sys
+import codecs
+
+from IPython.core.history import HistoryAccessor
+
+session_number = int(sys.argv[1])
+if len(sys.argv) > 2:
+    dest = open(sys.argv[2], "w")
+    raw = not sys.argv[2].endswith('.py')
+else:
+    dest = sys.stdout
+    raw = True
+dest.write("# coding: utf-8\n")
+
+# Profiles other than 'default' can be specified here with a profile= argument:
+hist = HistoryAccessor()
+
+for session, lineno, cell in hist.get_range(session=session_number, raw=raw):
+    # To use this in Python 3, remove the .encode() here:
+    dest.write(cell.encode('utf-8') + '\n')

IPython/core/history.py

@@ -1,835 +1,909 b''
 """ History related magics and functionality """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010 The IPython Development Team.
 #
 #  Distributed under the terms of the BSD License.
 #
 #  The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 from __future__ import print_function
 
 # Stdlib imports
 import atexit
 import datetime
 import os
 import re
 import sqlite3
 import threading
 
 # Our own packages
 from IPython.config.configurable import Configurable
 
 from IPython.testing.skipdoctest import skip_doctest
 from IPython.utils import io
+from IPython.utils.path import locate_profile
 from IPython.utils.traitlets import Bool, Dict, Instance, Int, CInt, List, Unicode
 from IPython.utils.warn import warn
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
-class HistoryManager(Configurable):
-    """A class to organize all history-related functionality in one place.
-    """
-    # Public interface
-
-    # An instance of the IPython shell we are attached to
-    shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
-    # Lists to hold processed and raw history. These start with a blank entry
-    # so that we can index them starting from 1
-    input_hist_parsed = List([""])
-    input_hist_raw = List([""])
-    # A list of directories visited during session
-    dir_hist = List()
-    def _dir_hist_default(self):
-        try:
-            return [os.getcwdu()]
-        except OSError:
-            return []
-
-    # A dict of output history, keyed with ints from the shell's
-    # execution count.
-    output_hist = Dict()
-    # The text/plain repr of outputs.
-    output_hist_reprs = Dict()
-
+class HistoryAccessor(Configurable):
+    """Access the history database without adding to it.
+    
+    This is intended for use by standalone history tools. IPython shells use
+    HistoryManager, below, which is a subclass of this."""
     # String holding the path to the history file
     hist_file = Unicode(config=True)
 
     # The SQLite database
     db = Instance(sqlite3.Connection)
-    # The number of the current session in the history database
-    session_number = CInt()
-    # Should we log output to the database? (default no)
-    db_log_output = Bool(False, config=True)
-    # Write to database every x commands (higher values save disk access & power)
-    #  Values of 1 or less effectively disable caching.
-    db_cache_size = Int(0, config=True)
-    # The input and output caches
-    db_input_cache = List()
-    db_output_cache = List()
-
-    # History saving in separate thread
-    save_thread = Instance('IPython.core.history.HistorySavingThread')
-    try:               # Event is a function returning an instance of _Event...
-        save_flag = Instance(threading._Event)
-    except AttributeError:         # ...until Python 3.3, when it's a class.
-        save_flag = Instance(threading.Event)
-
-    # Private interface
-    # Variables used to store the three last inputs from the user.  On each new
-    # history update, we populate the user's namespace with these, shifted as
-    # necessary.
-    _i00 = Unicode(u'')
-    _i = Unicode(u'')
-    _ii = Unicode(u'')
-    _iii = Unicode(u'')
-
-    # A regex matching all forms of the exit command, so that we don't store
-    # them in the history (it's annoying to rewind the first entry and land on
-    # an exit call).
-    _exit_re = re.compile(r"(exit|quit)(\s*\(.*\))?$")
-
-    def __init__(self, shell, config=None, **traits):
-        """Create a new history manager associated with a shell instance.
+    
+    def __init__(self, profile='default', hist_file=u'', shell=None, config=None, **traits):
+        """Create a new history accessor.
+        
+        Parameters
+        ----------
+        profile : str
+          The name of the profile from which to open history.
+        hist_file : str
+          Path to an SQLite history database stored by IPython. If specified,
+          hist_file overrides profile.
+        shell :
+          InteractiveShell object, for use by HistoryManager subclass
+        config :
+          Config object. hist_file can also be set through this.
         """
         # We need a pointer back to the shell for various tasks.
-        super(HistoryManager, self).__init__(shell=shell, config=config,
-            **traits)
+        super(HistoryAccessor, self).__init__(shell=shell, config=config,
+                                              hist_file=hist_file, **traits)
 
         if self.hist_file == u'':
             # No one has set the hist_file, yet.
-            histfname = 'history'
-            self.hist_file = os.path.join(shell.profile_dir.location, histfname + '.sqlite')
+            self.hist_file = self._get_hist_file_name(profile)
 
         try:
             self.init_db()
         except sqlite3.DatabaseError:
             if os.path.isfile(self.hist_file):
                 # Try to move the file out of the way.
                 newpath = os.path.join(self.shell.profile_dir.location, "hist-corrupt.sqlite")
                 os.rename(self.hist_file, newpath)
                 print("ERROR! History file wasn't a valid SQLite database.",
                 "It was moved to %s" % newpath, "and a new file created.")
                 self.init_db()
             else:
                 # The hist_file is probably :memory: or something else.
                 raise
-
-        self.save_flag = threading.Event()
-        self.db_input_cache_lock = threading.Lock()
-        self.db_output_cache_lock = threading.Lock()
-        self.save_thread = HistorySavingThread(self)
-        self.save_thread.start()
-
-        self.new_session()
-
-
+    
+    def _get_hist_file_name(self, profile='default'):
+        """Find the history file for the given profile name.
+        
+        This is overridden by the HistoryManager subclass, to use the shell's
+        active profile.
+        
+        Parameters
+        ----------
+        profile : str
+          The name of a profile which has a history file.
+        """
+        return os.path.join(locate_profile(profile), 'history.sqlite')
+    
     def init_db(self):
         """Connect to the database, and create tables if necessary."""
         # use detect_types so that timestamps return datetime objects
         self.db = sqlite3.connect(self.hist_file, detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
         self.db.execute("""CREATE TABLE IF NOT EXISTS sessions (session integer
                         primary key autoincrement, start timestamp,
                         end timestamp, num_cmds integer, remark text)""")
         self.db.execute("""CREATE TABLE IF NOT EXISTS history
                 (session integer, line integer, source text, source_raw text,
                 PRIMARY KEY (session, line))""")
         # Output history is optional, but ensure the table's there so it can be
         # enabled later.
         self.db.execute("""CREATE TABLE IF NOT EXISTS output_history
                         (session integer, line integer, output text,
                         PRIMARY KEY (session, line))""")
         self.db.commit()
 
-    def new_session(self, conn=None):
-        """Get a new session number."""
-        if conn is None:
-            conn = self.db
-
-        with conn:
-            # N.B. 'insert into' here is lower case because of a bug in the
-            # sqlite3 module that affects the Turkish locale. This should be
-            # fixed for Python 2.7.3 and 3.2.3, as well as 3.3 onwards.
-            # http://bugs.python.org/issue13099
-            cur = conn.execute("""insert into sessions VALUES (NULL, ?, NULL,
-                            NULL, "") """, (datetime.datetime.now(),))
-            self.session_number = cur.lastrowid
-
-    def end_session(self):
-        """Close the database session, filling in the end time and line count."""
-        self.writeout_cache()
-        with self.db:
-            self.db.execute("""UPDATE sessions SET end=?, num_cmds=? WHERE
-                            session==?""", (datetime.datetime.now(),
-                            len(self.input_hist_parsed)-1, self.session_number))
-        self.session_number = 0
-
-    def name_session(self, name):
-        """Give the current session a name in the history database."""
-        with self.db:
-            self.db.execute("UPDATE sessions SET remark=? WHERE session==?",
-                            (name, self.session_number))
-
-    def reset(self, new_session=True):
-        """Clear the session history, releasing all object references, and
-        optionally open a new session."""
-        self.output_hist.clear()
-        # The directory history can't be completely empty
-        self.dir_hist[:] = [os.getcwdu()]
-
-        if new_session:
-            if self.session_number:
-                self.end_session()
-            self.input_hist_parsed[:] = [""]
-            self.input_hist_raw[:] = [""]
-            self.new_session()
+    def writeout_cache(self):
+        """Overridden by HistoryManager to dump the cache before certain
+        database lookups."""
+        pass
 
     ## -------------------------------
     ## Methods for retrieving history:
     ## -------------------------------
     def _run_sql(self, sql, params, raw=True, output=False):
         """Prepares and runs an SQL query for the history database.
 
         Parameters
         ----------
         sql : str
           Any filtering expressions to go after SELECT ... FROM ...
         params : tuple
           Parameters passed to the SQL query (to replace "?")
         raw, output : bool
           See :meth:`get_range`
 
         Returns
         -------
         Tuples as :meth:`get_range`
         """
         toget = 'source_raw' if raw else 'source'
         sqlfrom = "history"
         if output:
             sqlfrom = "history LEFT JOIN output_history USING (session, line)"
             toget = "history.%s, output_history.output" % toget
         cur = self.db.execute("SELECT session, line, %s FROM %s " %\
                                 (toget, sqlfrom) + sql, params)
         if output:    # Regroup into 3-tuples, and parse JSON
             return ((ses, lin, (inp, out)) for ses, lin, inp, out in cur)
         return cur
 
-
     def get_session_info(self, session=0):
         """get info about a session
 
         Parameters
         ----------
 
         session : int
             Session number to retrieve. The current session is 0, and negative
             numbers count back from current session, so -1 is previous session.
 
         Returns
         -------
 
         (session_id [int], start [datetime], end [datetime], num_cmds [int], remark [unicode])
 
         Sessions that are running or did not exit cleanly will have `end=None`
         and `num_cmds=None`.
 
         """
 
         if session <= 0:
             session += self.session_number
 
         query = "SELECT * from sessions where session == ?"
         return self.db.execute(query, (session,)).fetchone()
 
-
     def get_tail(self, n=10, raw=True, output=False, include_latest=False):
         """Get the last n lines from the history database.
 
         Parameters
         ----------
         n : int
           The number of lines to get
         raw, output : bool
           See :meth:`get_range`
         include_latest : bool
           If False (default), n+1 lines are fetched, and the latest one
           is discarded. This is intended to be used where the function
           is called by a user command, which it should not return.
 
         Returns
         -------
         Tuples as :meth:`get_range`
         """
         self.writeout_cache()
         if not include_latest:
             n += 1
         cur = self._run_sql("ORDER BY session DESC, line DESC LIMIT ?",
                                 (n,), raw=raw, output=output)
         if not include_latest:
             return reversed(list(cur)[1:])
         return reversed(list(cur))
 
     def search(self, pattern="*", raw=True, search_raw=True,
                                                         output=False):
         """Search the database using unix glob-style matching (wildcards
         * and ?).
 
         Parameters
         ----------
         pattern : str
           The wildcarded pattern to match when searching
         search_raw : bool
           If True, search the raw input, otherwise, the parsed input
         raw, output : bool
           See :meth:`get_range`
 
         Returns
         -------
         Tuples as :meth:`get_range`
         """
         tosearch = "source_raw" if search_raw else "source"
         if output:
             tosearch = "history." + tosearch
         self.writeout_cache()
         return self._run_sql("WHERE %s GLOB ?" % tosearch, (pattern,),
                                     raw=raw, output=output)
-
-    def _get_range_session(self, start=1, stop=None, raw=True, output=False):
-        """Get input and output history from the current session. Called by
-        get_range, and takes similar parameters."""
-        input_hist = self.input_hist_raw if raw else self.input_hist_parsed
-
-        n = len(input_hist)
-        if start < 0:
-            start += n
-        if not stop or (stop > n):
-            stop = n
-        elif stop < 0:
-            stop += n
-
-        for i in range(start, stop):
-            if output:
-                line = (input_hist[i], self.output_hist_reprs.get(i))
-            else:
-                line = input_hist[i]
-            yield (0, i, line)
-
-    def get_range(self, session=0, start=1, stop=None, raw=True,output=False):
+    
+    def get_range(self, session, start=1, stop=None, raw=True,output=False):
         """Retrieve input by session.
 
         Parameters
         ----------
         session : int
-            Session number to retrieve. The current session is 0, and negative
-            numbers count back from current session, so -1 is previous session.
+            Session number to retrieve.
         start : int
             First line to retrieve.
         stop : int
             End of line range (excluded from output itself). If None, retrieve
             to the end of the session.
         raw : bool
             If True, return untranslated input
         output : bool
             If True, attempt to include output. This will be 'real' Python
             objects for the current session, or text reprs from previous
             sessions if db_log_output was enabled at the time. Where no output
             is found, None is used.
 
         Returns
         -------
         An iterator over the desired lines. Each line is a 3-tuple, either
         (session, line, input) if output is False, or
         (session, line, (input, output)) if output is True.
         """
-        if session == 0 or session==self.session_number:   # Current session
-            return self._get_range_session(start, stop, raw, output)
-        if session < 0:
-            session += self.session_number
-
         if stop:
             lineclause = "line >= ? AND line < ?"
             params = (session, start, stop)
         else:
             lineclause = "line>=?"
             params = (session, start)
 
         return self._run_sql("WHERE session==? AND %s""" % lineclause,
                                     params, raw=raw, output=output)
 
     def get_range_by_str(self, rangestr, raw=True, output=False):
         """Get lines of history from a string of ranges, as used by magic
         commands %hist, %save, %macro, etc.
 
         Parameters
         ----------
         rangestr : str
           A string specifying ranges, e.g. "5 ~2/1-4". See
           :func:`magic_history` for full details.
         raw, output : bool
           As :meth:`get_range`
 
         Returns
         -------
         Tuples as :meth:`get_range`
         """
         for sess, s, e in extract_hist_ranges(rangestr):
             for line in self.get_range(sess, s, e, raw=raw, output=output):
                 yield line
 
+
+class HistoryManager(HistoryAccessor):
+    """A class to organize all history-related functionality in one place.
+    """
+    # Public interface
+
+    # An instance of the IPython shell we are attached to
+    shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
+    # Lists to hold processed and raw history. These start with a blank entry
+    # so that we can index them starting from 1
+    input_hist_parsed = List([""])
+    input_hist_raw = List([""])
+    # A list of directories visited during session
+    dir_hist = List()
+    def _dir_hist_default(self):
+        try:
+            return [os.getcwdu()]
+        except OSError:
+            return []
+
+    # A dict of output history, keyed with ints from the shell's
+    # execution count.
+    output_hist = Dict()
+    # The text/plain repr of outputs.
+    output_hist_reprs = Dict()
+
+    # The number of the current session in the history database
+    session_number = CInt()
+    # Should we log output to the database? (default no)
+    db_log_output = Bool(False, config=True)
+    # Write to database every x commands (higher values save disk access & power)
+    #  Values of 1 or less effectively disable caching. 
+    db_cache_size = Int(0, config=True)
+    # The input and output caches
+    db_input_cache = List()
+    db_output_cache = List()
+    
+    # History saving in separate thread
+    save_thread = Instance('IPython.core.history.HistorySavingThread')
+    try:               # Event is a function returning an instance of _Event...
+        save_flag = Instance(threading._Event)
+    except AttributeError:         # ...until Python 3.3, when it's a class.
+        save_flag = Instance(threading.Event)
+    
+    # Private interface
+    # Variables used to store the three last inputs from the user.  On each new
+    # history update, we populate the user's namespace with these, shifted as
+    # necessary.
+    _i00 = Unicode(u'')
+    _i = Unicode(u'')
+    _ii = Unicode(u'')
+    _iii = Unicode(u'')
+
+    # A regex matching all forms of the exit command, so that we don't store
+    # them in the history (it's annoying to rewind the first entry and land on
+    # an exit call).
+    _exit_re = re.compile(r"(exit|quit)(\s*\(.*\))?$")
+
+    def __init__(self, shell=None, config=None, **traits):
+        """Create a new history manager associated with a shell instance.
+        """
+        # We need a pointer back to the shell for various tasks.
+        super(HistoryManager, self).__init__(shell=shell, config=config,
+            **traits)
+        self.save_flag = threading.Event()
+        self.db_input_cache_lock = threading.Lock()
+        self.db_output_cache_lock = threading.Lock()
+        self.save_thread = HistorySavingThread(self)
+        self.save_thread.start()
+
+        self.new_session()
+    
+    def _get_hist_file_name(self, profile=None):
+        """Get default history file name based on the Shell's profile.
+        
+        The profile parameter is ignored, but must exist for compatibility with
+        the parent class."""
+        profile_dir = self.shell.profile_dir.location
+        return os.path.join(profile_dir, 'history.sqlite')
+    
+    def new_session(self, conn=None):
+        """Get a new session number."""
+        if conn is None:
+            conn = self.db
+        
+        with conn:
+            cur = conn.execute("""INSERT INTO sessions VALUES (NULL, ?, NULL,
+                            NULL, "") """, (datetime.datetime.now(),))
+            self.session_number = cur.lastrowid
+            
+    def end_session(self):
+        """Close the database session, filling in the end time and line count."""
+        self.writeout_cache()
+        with self.db:
+            self.db.execute("""UPDATE sessions SET end=?, num_cmds=? WHERE
+                            session==?""", (datetime.datetime.now(),
+                            len(self.input_hist_parsed)-1, self.session_number))
+        self.session_number = 0
+                            
+    def name_session(self, name):
+        """Give the current session a name in the history database."""
+        with self.db:
+            self.db.execute("UPDATE sessions SET remark=? WHERE session==?",
+                            (name, self.session_number))
+                            
+    def reset(self, new_session=True):
+        """Clear the session history, releasing all object references, and
+        optionally open a new session."""
+        self.output_hist.clear()
+        # The directory history can't be completely empty
+        self.dir_hist[:] = [os.getcwdu()]
+        
+        if new_session:
+            if self.session_number:
+                self.end_session()
+            self.input_hist_parsed[:] = [""]
+            self.input_hist_raw[:] = [""]
+            self.new_session()
+    
+    # ------------------------------
+    # Methods for retrieving history
+    # ------------------------------
+    def _get_range_session(self, start=1, stop=None, raw=True, output=False):
+        """Get input and output history from the current session. Called by
+        get_range, and takes similar parameters."""
+        input_hist = self.input_hist_raw if raw else self.input_hist_parsed
+            
+        n = len(input_hist)
+        if start < 0:
+            start += n
+        if not stop or (stop > n):
+            stop = n
+        elif stop < 0:
+            stop += n
+        
+        for i in range(start, stop):
+            if output:
+                line = (input_hist[i], self.output_hist_reprs.get(i))
+            else:
+                line = input_hist[i]
+            yield (0, i, line)
+    
+    def get_range(self, session=0, start=1, stop=None, raw=True,output=False):
+        """Retrieve input by session.
+        
+        Parameters
+        ----------
+        session : int
+            Session number to retrieve. The current session is 0, and negative
+            numbers count back from current session, so -1 is previous session.
+        start : int
+            First line to retrieve.
+        stop : int
+            End of line range (excluded from output itself). If None, retrieve
+            to the end of the session.
+        raw : bool
+            If True, return untranslated input
+        output : bool
+            If True, attempt to include output. This will be 'real' Python
+            objects for the current session, or text reprs from previous
+            sessions if db_log_output was enabled at the time. Where no output
+            is found, None is used.
+            
+        Returns
+        -------
+        An iterator over the desired lines. Each line is a 3-tuple, either
+        (session, line, input) if output is False, or
+        (session, line, (input, output)) if output is True.
+        """
+        if session <= 0:
+            session += self.session_number
+        if session==self.session_number:          # Current session
+            return self._get_range_session(start, stop, raw, output)
+        return super(HistoryManager, self).get_range(session, start, stop, raw, output)
+
     ## ----------------------------
     ## Methods for storing history:
     ## ----------------------------
     def store_inputs(self, line_num, source, source_raw=None):
         """Store source and raw input in history and create input cache
         variables _i*.
 
         Parameters
         ----------
         line_num : int
           The prompt number of this input.
 
         source : str
           Python input.
 
         source_raw : str, optional
           If given, this is the raw input without any IPython transformations
           applied to it.  If not given, ``source`` is used.
         """
         if source_raw is None:
             source_raw = source
         source = source.rstrip('\n')
         source_raw = source_raw.rstrip('\n')
 
         # do not store exit/quit commands
         if self._exit_re.match(source_raw.strip()):
             return
 
         self.input_hist_parsed.append(source)
         self.input_hist_raw.append(source_raw)
 
         with self.db_input_cache_lock:
             self.db_input_cache.append((line_num, source, source_raw))
             # Trigger to flush cache and write to DB.
             if len(self.db_input_cache) >= self.db_cache_size:
                 self.save_flag.set()
 
         # update the auto _i variables
         self._iii = self._ii
         self._ii = self._i
         self._i = self._i00
         self._i00 = source_raw
 
         # hackish access to user namespace to create _i1,_i2... dynamically
         new_i = '_i%s' % line_num
         to_main = {'_i': self._i,
                    '_ii': self._ii,
                    '_iii': self._iii,
                    new_i : self._i00 }
         self.shell.user_ns.update(to_main)
 
     def store_output(self, line_num):
         """If database output logging is enabled, this saves all the
         outputs from the indicated prompt number to the database. It's
         called by run_cell after code has been executed.
 
         Parameters
         ----------
         line_num : int
           The line number from which to save outputs
         """
         if (not self.db_log_output) or (line_num not in self.output_hist_reprs):
             return
         output = self.output_hist_reprs[line_num]
 
         with self.db_output_cache_lock:
             self.db_output_cache.append((line_num, output))
         if self.db_cache_size <= 1:
             self.save_flag.set()
 
     def _writeout_input_cache(self, conn):
         with conn:
             for line in self.db_input_cache:
                 conn.execute("INSERT INTO history VALUES (?, ?, ?, ?)",
                                 (self.session_number,)+line)
 
     def _writeout_output_cache(self, conn):
         with conn:
             for line in self.db_output_cache:
                 conn.execute("INSERT INTO output_history VALUES (?, ?, ?)",
                                 (self.session_number,)+line)
 
     def writeout_cache(self, conn=None):
         """Write any entries in the cache to the database."""
         if conn is None:
             conn = self.db
 
         with self.db_input_cache_lock:
             try:
                 self._writeout_input_cache(conn)
             except sqlite3.IntegrityError:
                 self.new_session(conn)
                 print("ERROR! Session/line number was not unique in",
                       "database. History logging moved to new session",
                                                 self.session_number)
                 try: # Try writing to the new session. If this fails, don't recurse
                     self._writeout_input_cache(conn)
                 except sqlite3.IntegrityError:
                     pass
             finally:
                 self.db_input_cache = []
 
         with self.db_output_cache_lock:
             try:
                 self._writeout_output_cache(conn)
             except sqlite3.IntegrityError:
                 print("!! Session/line number for output was not unique",
                       "in database. Output will not be stored.")
             finally:
                 self.db_output_cache = []
 
 
 class HistorySavingThread(threading.Thread):
     """This thread takes care of writing history to the database, so that
     the UI isn't held up while that happens.
 
     It waits for the HistoryManager's save_flag to be set, then writes out
     the history cache. The main thread is responsible for setting the flag when
     the cache size reaches a defined threshold."""
     daemon = True
     stop_now = False
     def __init__(self, history_manager):
         super(HistorySavingThread, self).__init__()
         self.history_manager = history_manager
         atexit.register(self.stop)
 
     def run(self):
         # We need a separate db connection per thread:
         try:
             self.db = sqlite3.connect(self.history_manager.hist_file)
             while True:
                 self.history_manager.save_flag.wait()
                 if self.stop_now:
                     return
                 self.history_manager.save_flag.clear()
                 self.history_manager.writeout_cache(self.db)
         except Exception as e:
             print(("The history saving thread hit an unexpected error (%s)."
                    "History will not be written to the database.") % repr(e))
 
     def stop(self):
         """This can be called from the main thread to safely stop this thread.
 
         Note that it does not attempt to write out remaining history before
         exiting. That should be done by calling the HistoryManager's
         end_session method."""
         self.stop_now = True
         self.history_manager.save_flag.set()
         self.join()
 
 
 # To match, e.g. ~5/8-~2/3
 range_re = re.compile(r"""
 ((?P<startsess>~?\d+)/)?
 (?P<start>\d+)                    # Only the start line num is compulsory
 ((?P<sep>[\-:])
  ((?P<endsess>~?\d+)/)?
  (?P<end>\d+))?
 $""", re.VERBOSE)
 
 def extract_hist_ranges(ranges_str):
     """Turn a string of history ranges into 3-tuples of (session, start, stop).
 
     Examples
     --------
     list(extract_input_ranges("~8/5-~7/4 2"))
     [(-8, 5, None), (-7, 1, 4), (0, 2, 3)]
     """
     for range_str in ranges_str.split():
         rmatch = range_re.match(range_str)
         if not rmatch:
             continue
         start = int(rmatch.group("start"))
         end = rmatch.group("end")
         end = int(end) if end else start+1   # If no end specified, get (a, a+1)
         if rmatch.group("sep") == "-":       # 1-3 == 1:4 --> [1, 2, 3]
             end += 1
         startsess = rmatch.group("startsess") or "0"
         endsess = rmatch.group("endsess") or startsess
         startsess = int(startsess.replace("~","-"))
         endsess = int(endsess.replace("~","-"))
         assert endsess >= startsess
 
         if endsess == startsess:
             yield (startsess, start, end)
             continue
         # Multiple sessions in one range:
         yield (startsess, start, None)
         for sess in range(startsess+1, endsess):
             yield (sess, 1, None)
         yield (endsess, 1, end)
 
 def _format_lineno(session, line):
     """Helper function to format line numbers properly."""
     if session == 0:
         return str(line)
     return "%s#%s" % (session, line)
 
 @skip_doctest
 def magic_history(self, parameter_s = ''):
     """Print input history (_i<n> variables), with most recent last.
 
     %history       -> print at most 40 inputs (some may be multi-line)\\
     %history n     -> print at most n inputs\\
     %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
 
     By default, input history is printed without line numbers so it can be
     directly pasted into an editor. Use -n to show them.
 
     Ranges of history can be indicated using the syntax:
     4      : Line 4, current session
     4-6    : Lines 4-6, current session
     243/1-5: Lines 1-5, session 243
     ~2/7   : Line 7, session 2 before current
     ~8/1-~6/5 : From the first line of 8 sessions ago, to the fifth line
                 of 6 sessions ago.
     Multiple ranges can be entered, separated by spaces
 
     The same syntax is used by %macro, %save, %edit, %rerun
 
     Options:
 
       -n: print line numbers for each input.
       This feature is only available if numbered prompts are in use.
 
       -o: also print outputs for each input.
 
       -p: print classic '>>>' python prompts before each input.  This is useful
        for making documentation, and in conjunction with -o, for producing
        doctest-ready output.
 
       -r: (default) print the 'raw' history, i.e. the actual commands you typed.
 
       -t: print the 'translated' history, as IPython understands it.  IPython
       filters your input and converts it all into valid Python source before
       executing it (things like magics or aliases are turned into function
       calls, for example). With this option, you'll see the native history
       instead of the user-entered version: '%cd /' will be seen as
       'get_ipython().magic("%cd /")' instead of '%cd /'.
 
       -g: treat the arg as a pattern to grep for in (full) history.
       This includes the saved history (almost all commands ever written).
       Use '%hist -g' to show full saved history (may be very long).
 
       -l: get the last n lines from all sessions. Specify n as a single arg, or
       the default is the last 10 lines.
 
       -f FILENAME: instead of printing the output to the screen, redirect it to
        the given file.  The file is always overwritten, though IPython asks for
        confirmation first if it already exists.
 
     Examples
     --------
     ::
 
       In [6]: %hist -n 4 6
       4:a = 12
       5:print a**2
 
     """
 
     if not self.shell.displayhook.do_full_cache:
         print('This feature is only available if numbered prompts are in use.')
         return
     opts,args = self.parse_options(parameter_s,'noprtglf:',mode='string')
 
     # For brevity
     history_manager = self.shell.history_manager
 
     def _format_lineno(session, line):
         """Helper function to format line numbers properly."""
         if session in (0, history_manager.session_number):
             return str(line)
         return "%s/%s" % (session, line)
 
     # Check if output to specific file was requested.
     try:
         outfname = opts['f']
     except KeyError:
         outfile = io.stdout  # default
         # We don't want to close stdout at the end!
         close_at_end = False
     else:
         if os.path.exists(outfname):
             if not io.ask_yes_no("File %r exists. Overwrite?" % outfname):
                 print('Aborting.')
                 return
 
         outfile = open(outfname,'w')
         close_at_end = True
 
     print_nums = 'n' in opts
     get_output = 'o' in opts
     pyprompts = 'p' in opts
     # Raw history is the default
     raw = not('t' in opts)
 
     default_length = 40
     pattern = None
 
     if 'g' in opts:         # Glob search
         pattern = "*" + args + "*" if args else "*"
         hist = history_manager.search(pattern, raw=raw, output=get_output)
         print_nums = True
     elif 'l' in opts:       # Get 'tail'
         try:
             n = int(args)
         except ValueError, IndexError:
             n = 10
         hist = history_manager.get_tail(n, raw=raw, output=get_output)
     else:
         if args:            # Get history by ranges
             hist = history_manager.get_range_by_str(args, raw, get_output)
         else:               # Just get history for the current session
             hist = history_manager.get_range(raw=raw, output=get_output)
 
     # We could be displaying the entire history, so let's not try to pull it
     # into a list in memory. Anything that needs more space will just misalign.
     width = 4
 
     for session, lineno, inline in hist:
         # Print user history with tabs expanded to 4 spaces.  The GUI clients
         # use hard tabs for easier usability in auto-indented code, but we want
         # to produce PEP-8 compliant history for safe pasting into an editor.
         if get_output:
             inline, output = inline
         inline = inline.expandtabs(4).rstrip()
 
         multiline = "\n" in inline
         line_sep = '\n' if multiline else ' '
         if print_nums:
             print('%s:%s' % (_format_lineno(session, lineno).rjust(width),
                     line_sep),  file=outfile, end='')
         if pyprompts:
             print(">>> ", end="", file=outfile)
             if multiline:
                 inline = "\n... ".join(inline.splitlines()) + "\n..."
         print(inline, file=outfile)
         if get_output and output:
             print(output, file=outfile)
 
     if close_at_end:
         outfile.close()
 
 
 def magic_rep(self, arg):
     r"""Repeat a command, or get command to input line for editing. %recall and
     %rep are equivalent.
 
     - %recall (no arguments):
 
     Place a string version of last computation result (stored in the special '_'
     variable) to the next input prompt. Allows you to create elaborate command
     lines without using copy-paste::
 
          In[1]: l = ["hei", "vaan"]
          In[2]: "".join(l)
         Out[2]: heivaan
          In[3]: %rep
          In[4]: heivaan_ <== cursor blinking
 
     %recall 45
 
     Place history line 45 on the next input prompt. Use %hist to find
     out the number.
 
     %recall 1-4
 
     Combine the specified lines into one cell, and place it on the next
     input prompt. See %history for the slice syntax.
 
     %recall foo+bar
 
     If foo+bar can be evaluated in the user namespace, the result is
     placed at the next input prompt. Otherwise, the history is searched
     for lines which contain that substring, and the most recent one is
     placed at the next input prompt.
     """
     if not arg:                 # Last output
         self.set_next_input(str(self.shell.user_ns["_"]))
         return
                                 # Get history range
     histlines = self.history_manager.get_range_by_str(arg)
     cmd = "\n".join(x[2] for x in histlines)
     if cmd:
         self.set_next_input(cmd.rstrip())
         return
 
     try:                        # Variable in user namespace
         cmd = str(eval(arg, self.shell.user_ns))
     except Exception:           # Search for term in history
         histlines = self.history_manager.search("*"+arg+"*")
         for h in reversed([x[2] for x in histlines]):
             if 'rep' in h:
                 continue
             self.set_next_input(h.rstrip())
             return
     else:
         self.set_next_input(cmd.rstrip())
     print("Couldn't evaluate or find in history:", arg)
 
 def magic_rerun(self, parameter_s=''):
     """Re-run previous input
 
     By default, you can specify ranges of input history to be repeated
     (as with %history). With no arguments, it will repeat the last line.
 
     Options:
 
       -l <n> : Repeat the last n lines of input, not including the
       current command.
 
       -g foo : Repeat the most recent line which contains foo
     """
     opts, args = self.parse_options(parameter_s, 'l:g:', mode='string')
     if "l" in opts:         # Last n lines
         n = int(opts['l'])
         hist = self.history_manager.get_tail(n)
     elif "g" in opts:       # Search
         p = "*"+opts['g']+"*"
         hist = list(self.history_manager.search(p))
         for l in reversed(hist):
             if "rerun" not in l[2]:
                 hist = [l]     # The last match which isn't a %rerun
                 break
         else:
             hist = []          # No matches except %rerun
     elif args:              # Specify history ranges
         hist = self.history_manager.get_range_by_str(args)
     else:                   # Last line
         hist = self.history_manager.get_tail(1)
     hist = [x[2] for x in hist]
     if not hist:
         print("No lines in history match specification")
         return
     histlines = "\n".join(hist)
     print("=== Executing: ===")
     print(histlines)
     print("=== Output: ===")
     self.run_cell("\n".join(hist), store_history=False)
 
 
 def init_ipython(ip):
     ip.define_magic("rep", magic_rep)
     ip.define_magic("recall", magic_rep)
     ip.define_magic("rerun", magic_rerun)
     ip.define_magic("hist",magic_history)    # Alternative name
     ip.define_magic("history",magic_history)
 
     # XXX - ipy_completers are in quarantine, need to be updated to new apis
     #import ipy_completers
     #ipy_completers.quick_completer('%hist' ,'-g -t -r -n')

IPython/core/tests/test_history.py

@@ -1,118 +1,124 b''
 # coding: utf-8
 """Tests for the IPython tab-completion machinery.
 """
 #-----------------------------------------------------------------------------
 # Module imports
 #-----------------------------------------------------------------------------
 
 # stdlib
 import os
 import sys
 import unittest
 from datetime import datetime
 # third party
 import nose.tools as nt
 
 # our own packages
 from IPython.utils.tempdir import TemporaryDirectory
 from IPython.core.history import HistoryManager, extract_hist_ranges
 from IPython.utils import py3compat
 
 def setUp():
     nt.assert_equal(sys.getdefaultencoding(), "utf-8" if py3compat.PY3 else "ascii")
 
 def test_history():
     ip = get_ipython()
     with TemporaryDirectory() as tmpdir:
         hist_manager_ori = ip.history_manager
         hist_file = os.path.join(tmpdir, 'history.sqlite')
         try:
             ip.history_manager = HistoryManager(shell=ip, hist_file=hist_file)
             hist = ['a=1', 'def f():\n    test = 1\n    return test', u"b='€Æ¾÷ß'"]
             for i, h in enumerate(hist, start=1):
                 ip.history_manager.store_inputs(i, h)
 
             ip.history_manager.db_log_output = True
             # Doesn't match the input, but we'll just check it's stored.
             ip.history_manager.output_hist_reprs[3] = "spam"
             ip.history_manager.store_output(3)
 
             nt.assert_equal(ip.history_manager.input_hist_raw, [''] + hist)
+            
+            # Detailed tests for _get_range_session
+            grs = ip.history_manager._get_range_session
+            nt.assert_equal(list(grs(start=2,stop=-1)), zip([0], [2], hist[1:-1]))
+            nt.assert_equal(list(grs(start=-2)), zip([0,0], [2,3], hist[-2:]))
+            nt.assert_equal(list(grs(output=True)), zip([0,0,0], [1,2,3], zip(hist, [None,None,'spam'])))
 
             # Check whether specifying a range beyond the end of the current
             # session results in an error (gh-804)
             ip.magic('%hist 2-500')
 
             # New session
             ip.history_manager.reset()
             newcmds = ["z=5","class X(object):\n    pass", "k='p'"]
             for i, cmd in enumerate(newcmds, start=1):
                 ip.history_manager.store_inputs(i, cmd)
             gothist = ip.history_manager.get_range(start=1, stop=4)
             nt.assert_equal(list(gothist), zip([0,0,0],[1,2,3], newcmds))
             # Previous session:
             gothist = ip.history_manager.get_range(-1, 1, 4)
             nt.assert_equal(list(gothist), zip([1,1,1],[1,2,3], hist))
 
             # Check get_hist_tail
             gothist = ip.history_manager.get_tail(4, output=True,
                                                     include_latest=True)
             expected = [(1, 3, (hist[-1], "spam")),
                         (2, 1, (newcmds[0], None)),
                         (2, 2, (newcmds[1], None)),
                         (2, 3, (newcmds[2], None)),]
             nt.assert_equal(list(gothist), expected)
 
             gothist = ip.history_manager.get_tail(2)
             expected = [(2, 1, newcmds[0]),
                         (2, 2, newcmds[1])]
             nt.assert_equal(list(gothist), expected)
 
             # Check get_hist_search
             gothist = ip.history_manager.search("*test*")
             nt.assert_equal(list(gothist), [(1,2,hist[1])] )
             gothist = ip.history_manager.search("b*", output=True)
             nt.assert_equal(list(gothist), [(1,3,(hist[2],"spam"))] )
 
             # Cross testing: check that magic %save can get previous session.
             testfilename = os.path.realpath(os.path.join(tmpdir, "test.py"))
             ip.magic_save(testfilename + " ~1/1-3")
             with py3compat.open(testfilename) as testfile:
                 nt.assert_equal(testfile.read(),
                                         u"# coding: utf-8\n" + u"\n".join(hist))
 
             # Duplicate line numbers - check that it doesn't crash, and
             # gets a new session
             ip.history_manager.store_inputs(1, "rogue")
             ip.history_manager.writeout_cache()
             nt.assert_equal(ip.history_manager.session_number, 3)
         finally:
             # Restore history manager
             ip.history_manager = hist_manager_ori
 
 
 def test_extract_hist_ranges():
     instr = "1 2/3 ~4/5-6 ~4/7-~4/9 ~9/2-~7/5"
     expected = [(0, 1, 2),  # 0 == current session
                 (2, 3, 4),
                 (-4, 5, 7),
                 (-4, 7, 10),
                 (-9, 2, None),  # None == to end
                 (-8, 1, None),
                 (-7, 1, 6)]
     actual = list(extract_hist_ranges(instr))
     nt.assert_equal(actual, expected)
 
 def test_magic_rerun():
     """Simple test for %rerun (no args -> rerun last line)"""
     ip = get_ipython()
     ip.run_cell("a = 10")
     ip.run_cell("a += 1")
     nt.assert_equal(ip.user_ns["a"], 11)
     ip.run_cell("%rerun")
     nt.assert_equal(ip.user_ns["a"], 12)
 
 def test_timestamp_type():
     ip = get_ipython()
     info = ip.history_manager.get_session_info()
     nt.assert_true(isinstance(info[1], datetime))

IPython/utils/path.py

@@ -1,509 +1,521 b''
 # encoding: utf-8
 """
 Utilities for path handling.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import os
 import sys
 import tempfile
 import warnings
 from hashlib import md5
 
 import IPython
 from IPython.utils.process import system
 from IPython.utils.importstring import import_item
 from IPython.utils import py3compat
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 fs_encoding = sys.getfilesystemencoding()
 
 def _get_long_path_name(path):
     """Dummy no-op."""
     return path
 
 def _writable_dir(path):
     """Whether `path` is a directory, to which the user has write access."""
     return os.path.isdir(path) and os.access(path, os.W_OK)
 
 if sys.platform == 'win32':
     def _get_long_path_name(path):
         """Get a long path name (expand ~) on Windows using ctypes.
 
         Examples
         --------
 
         >>> get_long_path_name('c:\\docume~1')
         u'c:\\\\Documents and Settings'
 
         """
         try:
             import ctypes
         except ImportError:
             raise ImportError('you need to have ctypes installed for this to work')
         _GetLongPathName = ctypes.windll.kernel32.GetLongPathNameW
         _GetLongPathName.argtypes = [ctypes.c_wchar_p, ctypes.c_wchar_p,
             ctypes.c_uint ]
 
         buf = ctypes.create_unicode_buffer(260)
         rv = _GetLongPathName(path, buf, 260)
         if rv == 0 or rv > 260:
             return path
         else:
             return buf.value
 
 
 def get_long_path_name(path):
     """Expand a path into its long form.
 
     On Windows this expands any ~ in the paths. On other platforms, it is
     a null operation.
     """
     return _get_long_path_name(path)
 
 
 def unquote_filename(name, win32=(sys.platform=='win32')):
     """ On Windows, remove leading and trailing quotes from filenames.
     """
     if win32:
         if name.startswith(("'", '"')) and name.endswith(("'", '"')):
             name = name[1:-1]
     return name
 
 
 def get_py_filename(name, force_win32=None):
     """Return a valid python filename in the current directory.
 
     If the given name is not a file, it adds '.py' and searches again.
     Raises IOError with an informative message if the file isn't found.
 
     On Windows, apply Windows semantics to the filename. In particular, remove
     any quoting that has been applied to it. This option can be forced for
     testing purposes.
     """
 
     name = os.path.expanduser(name)
     if force_win32 is None:
         win32 = (sys.platform == 'win32')
     else:
         win32 = force_win32
     name = unquote_filename(name, win32=win32)
     if not os.path.isfile(name) and not name.endswith('.py'):
         name += '.py'
     if os.path.isfile(name):
         return name
     else:
         raise IOError,'File `%s` not found.' % name
 
 
 def filefind(filename, path_dirs=None):
     """Find a file by looking through a sequence of paths.
 
     This iterates through a sequence of paths looking for a file and returns
     the full, absolute path of the first occurence of the file.  If no set of
     path dirs is given, the filename is tested as is, after running through
     :func:`expandvars` and :func:`expanduser`.  Thus a simple call::
 
         filefind('myfile.txt')
 
     will find the file in the current working dir, but::
 
         filefind('~/myfile.txt')
 
     Will find the file in the users home directory.  This function does not
     automatically try any paths, such as the cwd or the user's home directory.
 
     Parameters
     ----------
     filename : str
         The filename to look for.
     path_dirs : str, None or sequence of str
         The sequence of paths to look for the file in.  If None, the filename
         need to be absolute or be in the cwd.  If a string, the string is
         put into a sequence and the searched.  If a sequence, walk through
         each element and join with ``filename``, calling :func:`expandvars`
         and :func:`expanduser` before testing for existence.
 
     Returns
     -------
     Raises :exc:`IOError` or returns absolute path to file.
     """
 
     # If paths are quoted, abspath gets confused, strip them...
     filename = filename.strip('"').strip("'")
     # If the input is an absolute path, just check it exists
     if os.path.isabs(filename) and os.path.isfile(filename):
         return filename
 
     if path_dirs is None:
         path_dirs = ("",)
     elif isinstance(path_dirs, basestring):
         path_dirs = (path_dirs,)
 
     for path in path_dirs:
         if path == '.': path = os.getcwdu()
         testname = expand_path(os.path.join(path, filename))
         if os.path.isfile(testname):
             return os.path.abspath(testname)
 
     raise IOError("File %r does not exist in any of the search paths: %r" %
                   (filename, path_dirs) )
 
 
 class HomeDirError(Exception):
     pass
 
 
 def get_home_dir():
     """Return the closest possible equivalent to a 'home' directory.
 
     * On POSIX, we try $HOME.
     * On Windows we try:
       - %HOMESHARE%
       - %HOMEDRIVE\%HOMEPATH%
       - %USERPROFILE%
       - Registry hack for My Documents
       - %HOME%: rare, but some people with unix-like setups may have defined it
     * On Dos C:\
 
     Currently only Posix and NT are implemented, a HomeDirError exception is
     raised for all other OSes.
     """
 
     env = os.environ
 
     # first, check py2exe distribution root directory for _ipython.
     # This overrides all. Normally does not exist.
 
     if hasattr(sys, "frozen"): #Is frozen by py2exe
         if '\\library.zip\\' in IPython.__file__.lower():#libraries compressed to zip-file
             root, rest = IPython.__file__.lower().split('library.zip')
         else:
             root=os.path.join(os.path.split(IPython.__file__)[0],"../../")
         root=os.path.abspath(root).rstrip('\\')
         if _writable_dir(os.path.join(root, '_ipython')):
             os.environ["IPYKITROOT"] = root
         return py3compat.cast_unicode(root, fs_encoding)
 
     if os.name == 'posix':
         # Linux, Unix, AIX, OS X
         try:
             homedir = env['HOME']
         except KeyError:
             # Last-ditch attempt at finding a suitable $HOME, on systems where
             # it may not be defined in the environment but the system shell
             # still knows it - reported once as:
             # https://github.com/ipython/ipython/issues/154
             from subprocess import Popen, PIPE
             homedir = Popen('echo $HOME', shell=True,
                             stdout=PIPE).communicate()[0].strip()
             if homedir:
                 return py3compat.cast_unicode(homedir, fs_encoding)
             else:
                 raise HomeDirError('Undefined $HOME, IPython cannot proceed.')
         else:
             return py3compat.cast_unicode(homedir, fs_encoding)
     elif os.name == 'nt':
         # Now for win9x, XP, Vista, 7?
         # For some strange reason all of these return 'nt' for os.name.
         # First look for a network home directory. This will return the UNC
         # path (\\server\\Users\%username%) not the mapped path (Z:\). This
         # is needed when running IPython on cluster where all paths have to
         # be UNC.
         try:
             homedir = env['HOMESHARE']
         except KeyError:
             pass
         else:
             if _writable_dir(homedir):
                 return py3compat.cast_unicode(homedir, fs_encoding)
 
         # Now look for a local home directory
         try:
             homedir = os.path.join(env['HOMEDRIVE'],env['HOMEPATH'])
         except KeyError:
             pass
         else:
             if _writable_dir(homedir):
                 return py3compat.cast_unicode(homedir, fs_encoding)
 
         # Now the users profile directory
         try:
             homedir = os.path.join(env['USERPROFILE'])
         except KeyError:
             pass
         else:
             if _writable_dir(homedir):
                 return py3compat.cast_unicode(homedir, fs_encoding)
 
         # Use the registry to get the 'My Documents' folder.
         try:
             import _winreg as wreg
             key = wreg.OpenKey(
                 wreg.HKEY_CURRENT_USER,
                 "Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders"
             )
             homedir = wreg.QueryValueEx(key,'Personal')[0]
             key.Close()
         except:
             pass
         else:
             if _writable_dir(homedir):
                 return py3compat.cast_unicode(homedir, fs_encoding)
 
         # A user with a lot of unix tools in win32 may have defined $HOME.
         # Try this as a last ditch option.
         try:
             homedir = env['HOME']
         except KeyError:
             pass
         else:
             if _writable_dir(homedir):
                 return py3compat.cast_unicode(homedir, fs_encoding)
 
         # If all else fails, raise HomeDirError
         raise HomeDirError('No valid home directory could be found')
     elif os.name == 'dos':
         # Desperate, may do absurd things in classic MacOS. May work under DOS.
         return u'C:\\'
     else:
         raise HomeDirError('No valid home directory could be found for your OS')
 
 def get_xdg_dir():
     """Return the XDG_CONFIG_HOME, if it is defined and exists, else None.
 
     This is only for posix (Linux,Unix,OS X, etc) systems.
     """
 
     env = os.environ
 
     if os.name == 'posix':
         # Linux, Unix, AIX, OS X
         # use ~/.config if not set OR empty
         xdg = env.get("XDG_CONFIG_HOME", None) or os.path.join(get_home_dir(), '.config')
         if xdg and _writable_dir(xdg):
             return py3compat.cast_unicode(xdg, fs_encoding)
 
     return None
 
 
 def get_ipython_dir():
     """Get the IPython directory for this platform and user.
 
     This uses the logic in `get_home_dir` to find the home directory
     and then adds .ipython to the end of the path.
     """
 
     env = os.environ
     pjoin = os.path.join
 
 
     ipdir_def = '.ipython'
     xdg_def = 'ipython'
 
     home_dir = get_home_dir()
     xdg_dir = get_xdg_dir()
     # import pdb; pdb.set_trace()  # dbg
     ipdir = env.get('IPYTHON_DIR', env.get('IPYTHONDIR', None))
     if ipdir is None:
         # not set explicitly, use XDG_CONFIG_HOME or HOME
         home_ipdir = pjoin(home_dir, ipdir_def)
         if xdg_dir:
             # use XDG, as long as the user isn't already
             # using $HOME/.ipython and *not* XDG/ipython
 
             xdg_ipdir = pjoin(xdg_dir, xdg_def)
 
             if _writable_dir(xdg_ipdir) or not _writable_dir(home_ipdir):
                 ipdir = xdg_ipdir
 
         if ipdir is None:
             # not using XDG
             ipdir = home_ipdir
 
     ipdir = os.path.normpath(os.path.expanduser(ipdir))
 
     if os.path.exists(ipdir) and not _writable_dir(ipdir):
         # ipdir exists, but is not writable
         warnings.warn("IPython dir '%s' is not a writable location,"
                         " using a temp directory."%ipdir)
         ipdir = tempfile.mkdtemp()
     elif not os.path.exists(ipdir):
         parent = ipdir.rsplit(os.path.sep, 1)[0]
         if not _writable_dir(parent):
             # ipdir does not exist and parent isn't writable
             warnings.warn("IPython parent '%s' is not a writable location,"
                         " using a temp directory."%parent)
             ipdir = tempfile.mkdtemp()
 
     return py3compat.cast_unicode(ipdir, fs_encoding)
 
 
 def get_ipython_package_dir():
     """Get the base directory where IPython itself is installed."""
     ipdir = os.path.dirname(IPython.__file__)
     return py3compat.cast_unicode(ipdir, fs_encoding)
 
 
 def get_ipython_module_path(module_str):
     """Find the path to an IPython module in this version of IPython.
 
     This will always find the version of the module that is in this importable
     IPython package. This will always return the path to the ``.py``
     version of the module.
     """
     if module_str == 'IPython':
         return os.path.join(get_ipython_package_dir(), '__init__.py')
     mod = import_item(module_str)
     the_path = mod.__file__.replace('.pyc', '.py')
     the_path = the_path.replace('.pyo', '.py')
     return py3compat.cast_unicode(the_path, fs_encoding)
 
+def locate_profile(profile='default'):
+    """Find the path to the folder associated with a given profile.
+    
+    I.e. find $IPYTHON_DIR/profile_whatever.
+    """
+    from IPython.core.profiledir import ProfileDir, ProfileDirError
+    try:
+        pd = ProfileDir.find_profile_dir_by_name(get_ipython_dir(), profile)
+    except ProfileDirError:
+        # IOError makes more sense when people are expecting a path
+        raise IOError("Couldn't find profile %r" % profile)
+    return pd.location
 
 def expand_path(s):
     """Expand $VARS and ~names in a string, like a shell
 
     :Examples:
 
        In [2]: os.environ['FOO']='test'
 
        In [3]: expand_path('variable FOO is $FOO')
        Out[3]: 'variable FOO is test'
     """
     # This is a pretty subtle hack. When expand user is given a UNC path
     # on Windows (\\server\share$\%username%), os.path.expandvars, removes
     # the $ to get (\\server\share\%username%). I think it considered $
     # alone an empty var. But, we need the $ to remains there (it indicates
     # a hidden share).
     if os.name=='nt':
         s = s.replace('$\\', 'IPYTHON_TEMP')
     s = os.path.expandvars(os.path.expanduser(s))
     if os.name=='nt':
         s = s.replace('IPYTHON_TEMP', '$\\')
     return s
 
 
 def target_outdated(target,deps):
     """Determine whether a target is out of date.
 
     target_outdated(target,deps) -> 1/0
 
     deps: list of filenames which MUST exist.
     target: single filename which may or may not exist.
 
     If target doesn't exist or is older than any file listed in deps, return
     true, otherwise return false.
     """
     try:
         target_time = os.path.getmtime(target)
     except os.error:
         return 1
     for dep in deps:
         dep_time = os.path.getmtime(dep)
         if dep_time > target_time:
             #print "For target",target,"Dep failed:",dep # dbg
             #print "times (dep,tar):",dep_time,target_time # dbg
             return 1
     return 0
 
 
 def target_update(target,deps,cmd):
     """Update a target with a given command given a list of dependencies.
 
     target_update(target,deps,cmd) -> runs cmd if target is outdated.
 
     This is just a wrapper around target_outdated() which calls the given
     command if target is outdated."""
 
     if target_outdated(target,deps):
         system(cmd)
 
 def filehash(path):
     """Make an MD5 hash of a file, ignoring any differences in line
     ending characters."""
     with open(path, "rU") as f:
         return md5(py3compat.str_to_bytes(f.read())).hexdigest()
 
 # If the config is unmodified from the default, we'll just delete it.
 # These are consistent for 0.10.x, thankfully. We're not going to worry about
 # older versions.
 old_config_md5 = {'ipy_user_conf.py': 'fc108bedff4b9a00f91fa0a5999140d3',
                   'ipythonrc': '12a68954f3403eea2eec09dc8fe5a9b5'}
 
 def check_for_old_config(ipython_dir=None):
     """Check for old config files, and present a warning if they exist.
 
     A link to the docs of the new config is included in the message.
 
     This should mitigate confusion with the transition to the new
     config system in 0.11.
     """
     if ipython_dir is None:
         ipython_dir = get_ipython_dir()
 
     old_configs = ['ipy_user_conf.py', 'ipythonrc', 'ipython_config.py']
     warned = False
     for cfg in old_configs:
         f = os.path.join(ipython_dir, cfg)
         if os.path.exists(f):
             if filehash(f) == old_config_md5.get(cfg, ''):
                 os.unlink(f)
             else:
                 warnings.warn("Found old IPython config file %r (modified by user)"%f)
                 warned = True
 
     if warned:
         warnings.warn("""
   The IPython configuration system has changed as of 0.11, and these files will
   be ignored. See http://ipython.github.com/ipython-doc/dev/config for details
   of the new config system.
   To start configuring IPython, do `ipython profile create`, and edit
   `ipython_config.py` in <ipython_dir>/profile_default.
   If you need to leave the old config files in place for an older version of
   IPython and want to suppress this warning message, set
   `c.InteractiveShellApp.ignore_old_config=True` in the new config.""")
 
 def get_security_file(filename, profile='default'):
     """Return the absolute path of a security file given by filename and profile
     
     This allows users and developers to find security files without
     knowledge of the IPython directory structure. The search path
     will be ['.', profile.security_dir]
     
     Parameters
     ----------
     
     filename : str
         The file to be found. If it is passed as an absolute path, it will
         simply be returned.
     profile : str [default: 'default']
         The name of the profile to search.  Leaving this unspecified
         The file to be found. If it is passed as an absolute path, fname will
         simply be returned.
     
     Returns
     -------
     Raises :exc:`IOError` if file not found or returns absolute path to file.
     """
     # import here, because profiledir also imports from utils.path
     from IPython.core.profiledir import ProfileDir
     try:
         pd = ProfileDir.find_profile_dir_by_name(get_ipython_dir(), profile)
     except Exception:
         # will raise ProfileDirError if no such profile
         raise IOError("Profile %r not found")
     return filefind(filename, ['.', pd.security_dir])