reformat rest of ipython

IPython/external/qt_loaders.py

@@ -1,399 +1,397 b''
 """
 This module contains factory functions that attempt
 to return Qt submodules from the various python Qt bindings.
 
 It also protects against double-importing Qt with different
 bindings, which is unstable and likely to crash
 
 This is used primarily by qt and qt_for_kernel, and shouldn't
 be accessed directly from the outside
 """
 import importlib.abc
 import sys
 import types
 from functools import partial, lru_cache
 import operator
 
 # ### Available APIs.
 # Qt6
 QT_API_PYQT6 = "pyqt6"
 QT_API_PYSIDE6 = "pyside6"
 
 # Qt5
 QT_API_PYQT5 = 'pyqt5'
 QT_API_PYSIDE2 = 'pyside2'
 
 # Qt4
 QT_API_PYQT = "pyqt"  # Force version 2
 QT_API_PYQTv1 = "pyqtv1"  # Force version 2
 QT_API_PYSIDE = "pyside"
 
 QT_API_PYQT_DEFAULT = "pyqtdefault"  # use system default for version 1 vs. 2
 
 api_to_module = {
     # Qt6
     QT_API_PYQT6: "PyQt6",
     QT_API_PYSIDE6: "PySide6",
     # Qt5
     QT_API_PYQT5: "PyQt5",
     QT_API_PYSIDE2: "PySide2",
     # Qt4
     QT_API_PYSIDE: "PySide",
     QT_API_PYQT: "PyQt4",
     QT_API_PYQTv1: "PyQt4",
     # default
     QT_API_PYQT_DEFAULT: "PyQt6",
 }
 
 
 class ImportDenier(importlib.abc.MetaPathFinder):
     """Import Hook that will guard against bad Qt imports
     once IPython commits to a specific binding
     """
 
     def __init__(self):
         self.__forbidden = set()
 
     def forbid(self, module_name):
         sys.modules.pop(module_name, None)
         self.__forbidden.add(module_name)
 
     def find_spec(self, fullname, path, target=None):
         if path:
             return
         if fullname in self.__forbidden:
             raise ImportError(
                 """
     Importing %s disabled by IPython, which has
     already imported an Incompatible QT Binding: %s
     """ % (fullname, loaded_api()))
 
 
 ID = ImportDenier()
 sys.meta_path.insert(0, ID)
 
 
 def commit_api(api):
     """Commit to a particular API, and trigger ImportErrors on subsequent
-       dangerous imports"""
+    dangerous imports"""
     modules = set(api_to_module.values())
 
     modules.remove(api_to_module[api])
     for mod in modules:
         ID.forbid(mod)
 
 
 def loaded_api():
     """Return which API is loaded, if any
 
     If this returns anything besides None,
     importing any other Qt binding is unsafe.
 
     Returns
     -------
     None, 'pyside6', 'pyqt6', 'pyside2', 'pyside', 'pyqt', 'pyqt5', 'pyqtv1'
     """
     if sys.modules.get("PyQt6.QtCore"):
         return QT_API_PYQT6
     elif sys.modules.get("PySide6.QtCore"):
         return QT_API_PYSIDE6
     elif sys.modules.get("PyQt5.QtCore"):
         return QT_API_PYQT5
     elif sys.modules.get("PySide2.QtCore"):
         return QT_API_PYSIDE2
     elif sys.modules.get("PyQt4.QtCore"):
         if qtapi_version() == 2:
             return QT_API_PYQT
         else:
             return QT_API_PYQTv1
     elif sys.modules.get("PySide.QtCore"):
         return QT_API_PYSIDE
 
     return None
 
 
 def has_binding(api):
     """Safely check for PyQt4/5, PySide or PySide2, without importing submodules
 
-        Parameters
-        ----------
-        api : str [ 'pyqtv1' | 'pyqt' | 'pyqt5' | 'pyside' | 'pyside2' | 'pyqtdefault']
-             Which module to check for
+    Parameters
+    ----------
+    api : str [ 'pyqtv1' | 'pyqt' | 'pyqt5' | 'pyside' | 'pyside2' | 'pyqtdefault']
+        Which module to check for
 
-        Returns
-        -------
-        True if the relevant module appears to be importable
-     """
+    Returns
+    -------
+    True if the relevant module appears to be importable
+    """
     module_name = api_to_module[api]
     from importlib.util import find_spec
 
     required = ['QtCore', 'QtGui', 'QtSvg']
     if api in (QT_API_PYQT5, QT_API_PYSIDE2, QT_API_PYQT6, QT_API_PYSIDE6):
         # QT5 requires QtWidgets too
         required.append('QtWidgets')
 
     for submod in required:
         try:
             spec = find_spec('%s.%s' % (module_name, submod))
         except ImportError:
             # Package (e.g. PyQt5) not found
             return False
         else:
             if spec is None:
                 # Submodule (e.g. PyQt5.QtCore) not found
                 return False
 
     if api == QT_API_PYSIDE:
         # We can also safely check PySide version
         import PySide
 
         return PySide.__version_info__ >= (1, 0, 3)
 
     return True
 
 
 def qtapi_version():
     """Return which QString API has been set, if any
 
     Returns
     -------
     The QString API version (1 or 2), or None if not set
     """
     try:
         import sip
     except ImportError:
         # as of PyQt5 5.11, sip is no longer available as a top-level
         # module and needs to be imported from the PyQt5 namespace
         try:
             from PyQt5 import sip
         except ImportError:
             return
     try:
         return sip.getapi('QString')
     except ValueError:
         return
 
 
 def can_import(api):
     """Safely query whether an API is importable, without importing it"""
     if not has_binding(api):
         return False
 
     current = loaded_api()
     if api == QT_API_PYQT_DEFAULT:
         return current in [QT_API_PYQT6, None]
     else:
         return current in [api, None]
 
 
 def import_pyqt4(version=2):
     """
     Import PyQt4
 
     Parameters
     ----------
     version : 1, 2, or None
-      Which QString/QVariant API to use. Set to None to use the system
-      default
-
+        Which QString/QVariant API to use. Set to None to use the system
+        default
     ImportErrors raised within this function are non-recoverable
     """
     # The new-style string API (version=2) automatically
     # converts QStrings to Unicode Python strings. Also, automatically unpacks
     # QVariants to their underlying objects.
     import sip
 
     if version is not None:
         sip.setapi('QString', version)
         sip.setapi('QVariant', version)
 
     from PyQt4 import QtGui, QtCore, QtSvg
 
     if QtCore.PYQT_VERSION < 0x040700:
         raise ImportError("IPython requires PyQt4 >= 4.7, found %s" %
                           QtCore.PYQT_VERSION_STR)
 
     # Alias PyQt-specific functions for PySide compatibility.
     QtCore.Signal = QtCore.pyqtSignal
     QtCore.Slot = QtCore.pyqtSlot
 
     # query for the API version (in case version == None)
     version = sip.getapi('QString')
     api = QT_API_PYQTv1 if version == 1 else QT_API_PYQT
     return QtCore, QtGui, QtSvg, api
 
 
 def import_pyqt5():
     """
     Import PyQt5
 
     ImportErrors raised within this function are non-recoverable
     """
 
     from PyQt5 import QtCore, QtSvg, QtWidgets, QtGui
 
     # Alias PyQt-specific functions for PySide compatibility.
     QtCore.Signal = QtCore.pyqtSignal
     QtCore.Slot = QtCore.pyqtSlot
 
     # Join QtGui and QtWidgets for Qt4 compatibility.
     QtGuiCompat = types.ModuleType('QtGuiCompat')
     QtGuiCompat.__dict__.update(QtGui.__dict__)
     QtGuiCompat.__dict__.update(QtWidgets.__dict__)
 
     api = QT_API_PYQT5
     return QtCore, QtGuiCompat, QtSvg, api
 
 
 def import_pyqt6():
     """
     Import PyQt6
 
     ImportErrors raised within this function are non-recoverable
     """
 
     from PyQt6 import QtCore, QtSvg, QtWidgets, QtGui
 
     # Alias PyQt-specific functions for PySide compatibility.
     QtCore.Signal = QtCore.pyqtSignal
     QtCore.Slot = QtCore.pyqtSlot
 
     # Join QtGui and QtWidgets for Qt4 compatibility.
     QtGuiCompat = types.ModuleType("QtGuiCompat")
     QtGuiCompat.__dict__.update(QtGui.__dict__)
     QtGuiCompat.__dict__.update(QtWidgets.__dict__)
 
     api = QT_API_PYQT6
     return QtCore, QtGuiCompat, QtSvg, api
 
 
 def import_pyside():
     """
     Import PySide
 
     ImportErrors raised within this function are non-recoverable
     """
     from PySide import QtGui, QtCore, QtSvg
     return QtCore, QtGui, QtSvg, QT_API_PYSIDE
 
 def import_pyside2():
     """
     Import PySide2
 
     ImportErrors raised within this function are non-recoverable
     """
     from PySide2 import QtGui, QtCore, QtSvg, QtWidgets, QtPrintSupport
 
     # Join QtGui and QtWidgets for Qt4 compatibility.
     QtGuiCompat = types.ModuleType('QtGuiCompat')
     QtGuiCompat.__dict__.update(QtGui.__dict__)
     QtGuiCompat.__dict__.update(QtWidgets.__dict__)
     QtGuiCompat.__dict__.update(QtPrintSupport.__dict__)
 
     return QtCore, QtGuiCompat, QtSvg, QT_API_PYSIDE2
 
 
 def import_pyside6():
     """
     Import PySide6
 
     ImportErrors raised within this function are non-recoverable
     """
     from PySide6 import QtGui, QtCore, QtSvg, QtWidgets, QtPrintSupport
 
     # Join QtGui and QtWidgets for Qt4 compatibility.
     QtGuiCompat = types.ModuleType("QtGuiCompat")
     QtGuiCompat.__dict__.update(QtGui.__dict__)
     QtGuiCompat.__dict__.update(QtWidgets.__dict__)
     QtGuiCompat.__dict__.update(QtPrintSupport.__dict__)
 
     return QtCore, QtGuiCompat, QtSvg, QT_API_PYSIDE6
 
 
 def load_qt(api_options):
     """
     Attempt to import Qt, given a preference list
     of permissible bindings
 
     It is safe to call this function multiple times.
 
     Parameters
     ----------
-    api_options: List of strings
+    api_options : List of strings
         The order of APIs to try. Valid items are 'pyside', 'pyside2',
         'pyqt', 'pyqt5', 'pyqtv1' and 'pyqtdefault'
 
     Returns
     -------
-
     A tuple of QtCore, QtGui, QtSvg, QT_API
     The first three are the Qt modules. The last is the
     string indicating which module was loaded.
 
     Raises
     ------
     ImportError, if it isn't possible to import any requested
     bindings (either because they aren't installed, or because
     an incompatible library has already been installed)
     """
     loaders = {
         # Qt6
         QT_API_PYQT6: import_pyqt6,
         QT_API_PYSIDE6: import_pyside6,
         # Qt5
         QT_API_PYQT5: import_pyqt5,
         QT_API_PYSIDE2: import_pyside2,
         # Qt4
         QT_API_PYSIDE: import_pyside,
         QT_API_PYQT: import_pyqt4,
         QT_API_PYQTv1: partial(import_pyqt4, version=1),
         # default
         QT_API_PYQT_DEFAULT: import_pyqt6,
     }
 
     for api in api_options:
 
         if api not in loaders:
             raise RuntimeError(
                 "Invalid Qt API %r, valid values are: %s" %
                 (api, ", ".join(["%r" % k for k in loaders.keys()])))
 
         if not can_import(api):
             continue
 
         #cannot safely recover from an ImportError during this
         result = loaders[api]()
         api = result[-1]  # changed if api = QT_API_PYQT_DEFAULT
         commit_api(api)
         return result
     else:
         raise ImportError("""
     Could not load requested Qt binding. Please ensure that
     PyQt4 >= 4.7, PyQt5, PySide >= 1.0.3 or PySide2 is available,
     and only one is imported per session.
 
     Currently-imported Qt library:                              %r
     PyQt4 available (requires QtCore, QtGui, QtSvg):            %s
     PyQt5 available (requires QtCore, QtGui, QtSvg, QtWidgets): %s
     PySide >= 1.0.3 installed:                                  %s
     PySide2 installed:                                          %s
     Tried to load:                                              %r
     """ % (loaded_api(),
            has_binding(QT_API_PYQT),
            has_binding(QT_API_PYQT5),
            has_binding(QT_API_PYSIDE),
            has_binding(QT_API_PYSIDE2),
            api_options))
 
 
 def enum_factory(QT_API, QtCore):
     """Construct an enum helper to account for PyQt5 <-> PyQt6 changes."""
 
     @lru_cache(None)
     def _enum(name):
         # foo.bar.Enum.Entry (PyQt6) <=> foo.bar.Entry (non-PyQt6).
         return operator.attrgetter(
             name if QT_API == QT_API_PYQT6 else name.rpartition(".")[0]
         )(sys.modules[QtCore.__package__])
 
     return _enum

IPython/lib/backgroundjobs.py

@@ -1,491 +1,491 b''
 # -*- coding: utf-8 -*-
 """Manage background (threaded) jobs conveniently from an interactive shell.
 
 This module provides a BackgroundJobManager class.  This is the main class
 meant for public usage, it implements an object which can create and manage
 new background jobs.
 
 It also provides the actual job classes managed by these BackgroundJobManager
 objects, see their docstrings below.
 
 
 This system was inspired by discussions with B. Granger and the
 BackgroundCommand class described in the book Python Scripting for
 Computational Science, by H. P. Langtangen:
 
 http://folk.uio.no/hpl/scripting
 
 (although ultimately no code from this text was used, as IPython's system is a
 separate implementation).
 
 An example notebook is provided in our documentation illustrating interactive
 use of the system.
 """
 
 #*****************************************************************************
 #       Copyright (C) 2005-2006 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 # Code begins
 import sys
 import threading
 
 from IPython import get_ipython
 from IPython.core.ultratb import AutoFormattedTB
 from logging import error, debug
 
 
 class BackgroundJobManager(object):
     """Class to manage a pool of backgrounded threaded jobs.
 
     Below, we assume that 'jobs' is a BackgroundJobManager instance.
     
     Usage summary (see the method docstrings for details):
 
       jobs.new(...) -> start a new job
       
       jobs() or jobs.status() -> print status summary of all jobs
 
       jobs[N] -> returns job number N.
 
       foo = jobs[N].result -> assign to variable foo the result of job N
 
       jobs[N].traceback() -> print the traceback of dead job N
 
       jobs.remove(N) -> remove (finished) job N
 
       jobs.flush() -> remove all finished jobs
       
     As a convenience feature, BackgroundJobManager instances provide the
     utility result and traceback methods which retrieve the corresponding
     information from the jobs list:
 
       jobs.result(N) <--> jobs[N].result
       jobs.traceback(N) <--> jobs[N].traceback()
 
     While this appears minor, it allows you to use tab completion
     interactively on the job manager instance.
     """
 
     def __init__(self):
         # Lists for job management, accessed via a property to ensure they're
         # up to date.x
         self._running  = []
         self._completed = []
         self._dead = []
         # A dict of all jobs, so users can easily access any of them
         self.all = {}
         # For reporting
         self._comp_report = []
         self._dead_report = []
         # Store status codes locally for fast lookups
         self._s_created   = BackgroundJobBase.stat_created_c
         self._s_running   = BackgroundJobBase.stat_running_c
         self._s_completed = BackgroundJobBase.stat_completed_c
         self._s_dead      = BackgroundJobBase.stat_dead_c
         self._current_job_id = 0
 
     @property
     def running(self):
         self._update_status()
         return self._running
 
     @property
     def dead(self):
         self._update_status()
         return self._dead
 
     @property
     def completed(self):
         self._update_status()
         return self._completed
 
     def new(self, func_or_exp, *args, **kwargs):
         """Add a new background job and start it in a separate thread.
 
         There are two types of jobs which can be created:
 
         1. Jobs based on expressions which can be passed to an eval() call.
         The expression must be given as a string.  For example:
 
           job_manager.new('myfunc(x,y,z=1)'[,glob[,loc]])
 
         The given expression is passed to eval(), along with the optional
         global/local dicts provided.  If no dicts are given, they are
         extracted automatically from the caller's frame.
-        
+
         A Python statement is NOT a valid eval() expression.  Basically, you
         can only use as an eval() argument something which can go on the right
         of an '=' sign and be assigned to a variable.
 
         For example,"print 'hello'" is not valid, but '2+3' is.
 
         2. Jobs given a function object, optionally passing additional
         positional arguments:
 
           job_manager.new(myfunc, x, y)
 
         The function is called with the given arguments.
 
         If you need to pass keyword arguments to your function, you must
         supply them as a dict named kw:
 
           job_manager.new(myfunc, x, y, kw=dict(z=1))
 
         The reason for this asymmetry is that the new() method needs to
         maintain access to its own keywords, and this prevents name collisions
         between arguments to new() and arguments to your own functions.
 
         In both cases, the result is stored in the job.result field of the
         background job object.
 
         You can set `daemon` attribute of the thread by giving the keyword
         argument `daemon`.
 
         Notes and caveats:
 
         1. All threads running share the same standard output.  Thus, if your
         background jobs generate output, it will come out on top of whatever
         you are currently writing.  For this reason, background jobs are best
         used with silent functions which simply return their output.
 
         2. Threads also all work within the same global namespace, and this
         system does not lock interactive variables.  So if you send job to the
         background which operates on a mutable object for a long time, and
         start modifying that same mutable object interactively (or in another
         backgrounded job), all sorts of bizarre behaviour will occur.
 
         3. If a background job is spending a lot of time inside a C extension
         module which does not release the Python Global Interpreter Lock
         (GIL), this will block the IPython prompt.  This is simply because the
         Python interpreter can only switch between threads at Python
         bytecodes.  While the execution is inside C code, the interpreter must
         simply wait unless the extension module releases the GIL.
 
         4. There is no way, due to limitations in the Python threads library,
         to kill a thread once it has started."""
         
         if callable(func_or_exp):
             kw  = kwargs.get('kw',{})
             job = BackgroundJobFunc(func_or_exp,*args,**kw)
         elif isinstance(func_or_exp, str):
             if not args:
                 frame = sys._getframe(1)
                 glob, loc = frame.f_globals, frame.f_locals
             elif len(args)==1:
                 glob = loc = args[0]
             elif len(args)==2:
                 glob,loc = args
             else:
                 raise ValueError(
                       'Expression jobs take at most 2 args (globals,locals)')
             job = BackgroundJobExpr(func_or_exp, glob, loc)
         else:
             raise TypeError('invalid args for new job')
 
         if kwargs.get('daemon', False):
             job.daemon = True
         job.num = self._current_job_id
         self._current_job_id += 1
         self.running.append(job)
         self.all[job.num] = job
         debug('Starting job # %s in a separate thread.' % job.num)
         job.start()
         return job
 
     def __getitem__(self, job_key):
         num = job_key if isinstance(job_key, int) else job_key.num
         return self.all[num]
 
     def __call__(self):
         """An alias to self.status(),
 
         This allows you to simply call a job manager instance much like the
         Unix `jobs` shell command."""
 
         return self.status()
 
     def _update_status(self):
         """Update the status of the job lists.
 
         This method moves finished jobs to one of two lists:
           - self.completed: jobs which completed successfully
           - self.dead: jobs which finished but died.
 
         It also copies those jobs to corresponding _report lists.  These lists
         are used to report jobs completed/dead since the last update, and are
         then cleared by the reporting function after each call."""
 
         # Status codes
         srun, scomp, sdead = self._s_running, self._s_completed, self._s_dead
         # State lists, use the actual lists b/c the public names are properties
         # that call this very function on access
         running, completed, dead = self._running, self._completed, self._dead
 
         # Now, update all state lists
         for num, job in enumerate(running):
             stat = job.stat_code
             if stat == srun:
                 continue
             elif stat == scomp:
                 completed.append(job)
                 self._comp_report.append(job)
                 running[num] = False
             elif stat == sdead:
                 dead.append(job)
                 self._dead_report.append(job)
                 running[num] = False
         # Remove dead/completed jobs from running list
         running[:] = filter(None, running)
 
     def _group_report(self,group,name):
         """Report summary for a given job group.
 
         Return True if the group had any elements."""
 
         if group:
             print('%s jobs:' % name)
             for job in group:
                 print('%s : %s' % (job.num,job))
             print()
             return True
 
     def _group_flush(self,group,name):
         """Flush a given job group
 
         Return True if the group had any elements."""
 
         njobs = len(group)
         if njobs:
             plural = {1:''}.setdefault(njobs,'s')
             print('Flushing %s %s job%s.' % (njobs,name,plural))
             group[:] = []
             return True
         
     def _status_new(self):
         """Print the status of newly finished jobs.
 
         Return True if any new jobs are reported.
 
         This call resets its own state every time, so it only reports jobs
         which have finished since the last time it was called."""
 
         self._update_status()
         new_comp = self._group_report(self._comp_report, 'Completed')
         new_dead = self._group_report(self._dead_report,
                                       'Dead, call jobs.traceback() for details')
         self._comp_report[:] = []
         self._dead_report[:] = []
         return new_comp or new_dead
                 
     def status(self,verbose=0):
         """Print a status of all jobs currently being managed."""
 
         self._update_status()
         self._group_report(self.running,'Running')
         self._group_report(self.completed,'Completed')
         self._group_report(self.dead,'Dead')
         # Also flush the report queues
         self._comp_report[:] = []
         self._dead_report[:] = []
 
     def remove(self,num):
         """Remove a finished (completed or dead) job."""
 
         try:
             job = self.all[num]
         except KeyError:
             error('Job #%s not found' % num)
         else:
             stat_code = job.stat_code
             if stat_code == self._s_running:
                 error('Job #%s is still running, it can not be removed.' % num)
                 return
             elif stat_code == self._s_completed:
                 self.completed.remove(job)
             elif stat_code == self._s_dead:
                 self.dead.remove(job)
 
     def flush(self):
         """Flush all finished jobs (completed and dead) from lists.
 
         Running jobs are never flushed.
 
         It first calls _status_new(), to update info. If any jobs have
         completed since the last _status_new() call, the flush operation
         aborts."""
 
         # Remove the finished jobs from the master dict
         alljobs = self.all
         for job in self.completed+self.dead:
             del(alljobs[job.num])
 
         # Now flush these lists completely
         fl_comp = self._group_flush(self.completed, 'Completed')
         fl_dead = self._group_flush(self.dead, 'Dead')
         if not (fl_comp or fl_dead):
             print('No jobs to flush.')
 
     def result(self,num):
         """result(N) -> return the result of job N."""
         try:
             return self.all[num].result
         except KeyError:
             error('Job #%s not found' % num)
 
     def _traceback(self, job):
         num = job if isinstance(job, int) else job.num
         try:
             self.all[num].traceback()
         except KeyError:
             error('Job #%s not found' % num)
 
     def traceback(self, job=None):
         if job is None:
             self._update_status()
             for deadjob in self.dead:
                 print("Traceback for: %r" % deadjob)
                 self._traceback(deadjob)
                 print()
         else:
             self._traceback(job)
 
 
 class BackgroundJobBase(threading.Thread):
     """Base class to build BackgroundJob classes.
 
     The derived classes must implement:
 
     - Their own __init__, since the one here raises NotImplementedError.  The
       derived constructor must call self._init() at the end, to provide common
       initialization.
 
     - A strform attribute used in calls to __str__.
 
     - A call() method, which will make the actual execution call and must
       return a value to be held in the 'result' field of the job object.
     """
 
     # Class constants for status, in string and as numerical codes (when
     # updating jobs lists, we don't want to do string comparisons).  This will
     # be done at every user prompt, so it has to be as fast as possible
     stat_created   = 'Created'; stat_created_c = 0
     stat_running   = 'Running'; stat_running_c = 1
     stat_completed = 'Completed'; stat_completed_c = 2
     stat_dead      = 'Dead (Exception), call jobs.traceback() for details'
     stat_dead_c = -1
 
     def __init__(self):
         """Must be implemented in subclasses.
 
         Subclasses must call :meth:`_init` for standard initialisation.
         """
         raise NotImplementedError("This class can not be instantiated directly.")
 
     def _init(self):
         """Common initialization for all BackgroundJob objects"""
         
         for attr in ['call','strform']:
             assert hasattr(self,attr), "Missing attribute <%s>" % attr
         
         # The num tag can be set by an external job manager
         self.num = None
       
         self.status    = BackgroundJobBase.stat_created
         self.stat_code = BackgroundJobBase.stat_created_c
         self.finished  = False
         self.result    = '<BackgroundJob has not completed>'
         
         # reuse the ipython traceback handler if we can get to it, otherwise
         # make a new one
         try:
             make_tb = get_ipython().InteractiveTB.text
         except:
             make_tb = AutoFormattedTB(mode = 'Context',
                                       color_scheme='NoColor',
                                       tb_offset = 1).text
         # Note that the actual API for text() requires the three args to be
         # passed in, so we wrap it in a simple lambda.
         self._make_tb = lambda : make_tb(None, None, None)
 
         # Hold a formatted traceback if one is generated.
         self._tb = None
         
         threading.Thread.__init__(self)
 
     def __str__(self):
         return self.strform
 
     def __repr__(self):
         return '<BackgroundJob #%d: %s>' % (self.num, self.strform)
 
     def traceback(self):
         print(self._tb)
         
     def run(self):
         try:
             self.status    = BackgroundJobBase.stat_running
             self.stat_code = BackgroundJobBase.stat_running_c
             self.result    = self.call()
         except:
             self.status    = BackgroundJobBase.stat_dead
             self.stat_code = BackgroundJobBase.stat_dead_c
             self.finished  = None
             self.result    = ('<BackgroundJob died, call jobs.traceback() for details>')
             self._tb       = self._make_tb()
         else:
             self.status    = BackgroundJobBase.stat_completed
             self.stat_code = BackgroundJobBase.stat_completed_c
             self.finished  = True
 
 
 class BackgroundJobExpr(BackgroundJobBase):
     """Evaluate an expression as a background job (uses a separate thread)."""
 
     def __init__(self, expression, glob=None, loc=None):
         """Create a new job from a string which can be fed to eval().
 
         global/locals dicts can be provided, which will be passed to the eval
         call."""
 
         # fail immediately if the given expression can't be compiled
         self.code = compile(expression,'<BackgroundJob compilation>','eval')
                 
         glob = {} if glob is None else glob
         loc = {} if loc is None else loc
         self.expression = self.strform = expression
         self.glob = glob
         self.loc = loc
         self._init()
         
     def call(self):
         return eval(self.code,self.glob,self.loc)
 
 
 class BackgroundJobFunc(BackgroundJobBase):
     """Run a function call as a background job (uses a separate thread)."""
 
     def __init__(self, func, *args, **kwargs):
         """Create a new job from a callable object.
 
         Any positional arguments and keyword args given to this constructor
         after the initial callable are passed directly to it."""
 
         if not callable(func):
             raise TypeError(
                 'first argument to BackgroundJobFunc must be callable')
         
         self.func = func
         self.args = args
         self.kwargs = kwargs
         # The string form will only include the function passed, because
         # generating string representations of the arguments is a potentially
         # _very_ expensive operation (e.g. with large arrays).
         self.strform = str(func)
         self._init()
 
     def call(self):
         return self.func(*self.args, **self.kwargs)

IPython/lib/demo.py

@@ -1,672 +1,672 b''
 """Module for interactive demos using IPython.
 
 This module implements a few classes for running Python scripts interactively
 in IPython for demonstrations.  With very simple markup (a few tags in
 comments), you can control points where the script stops executing and returns
 control to IPython.
 
 
 Provided classes
 ----------------
 
 The classes are (see their docstrings for further details):
 
  - Demo: pure python demos
 
  - IPythonDemo: demos with input to be processed by IPython as if it had been
    typed interactively (so magics work, as well as any other special syntax you
    may have added via input prefilters).
 
  - LineDemo: single-line version of the Demo class.  These demos are executed
    one line at a time, and require no markup.
 
  - IPythonLineDemo: IPython version of the LineDemo class (the demo is
    executed a line at a time, but processed via IPython).
 
  - ClearMixin: mixin to make Demo classes with less visual clutter.  It
    declares an empty marquee and a pre_cmd that clears the screen before each
    block (see Subclassing below).
 
  - ClearDemo, ClearIPDemo: mixin-enabled versions of the Demo and IPythonDemo
    classes.
 
 Inheritance diagram:
 
 .. inheritance-diagram:: IPython.lib.demo
    :parts: 3
 
 Subclassing
 -----------
 
 The classes here all include a few methods meant to make customization by
 subclassing more convenient.  Their docstrings below have some more details:
 
   - highlight(): format every block and optionally highlight comments and
     docstring content.
 
   - marquee(): generates a marquee to provide visible on-screen markers at each
     block start and end.
 
   - pre_cmd(): run right before the execution of each block.
 
   - post_cmd(): run right after the execution of each block.  If the block
     raises an exception, this is NOT called.
 
 
 Operation
 ---------
 
 The file is run in its own empty namespace (though you can pass it a string of
 arguments as if in a command line environment, and it will see those as
 sys.argv).  But at each stop, the global IPython namespace is updated with the
 current internal demo namespace, so you can work interactively with the data
 accumulated so far.
 
 By default, each block of code is printed (with syntax highlighting) before
 executing it and you have to confirm execution.  This is intended to show the
 code to an audience first so you can discuss it, and only proceed with
 execution once you agree.  There are a few tags which allow you to modify this
 behavior.
 
 The supported tags are:
 
 # <demo> stop
 
   Defines block boundaries, the points where IPython stops execution of the
   file and returns to the interactive prompt.
 
   You can optionally mark the stop tag with extra dashes before and after the
   word 'stop', to help visually distinguish the blocks in a text editor:
 
   # <demo> --- stop ---
 
 
 # <demo> silent
 
   Make a block execute silently (and hence automatically).  Typically used in
   cases where you have some boilerplate or initialization code which you need
   executed but do not want to be seen in the demo.
 
 # <demo> auto
 
   Make a block execute automatically, but still being printed.  Useful for
   simple code which does not warrant discussion, since it avoids the extra
   manual confirmation.
 
 # <demo> auto_all
 
   This tag can _only_ be in the first block, and if given it overrides the
   individual auto tags to make the whole demo fully automatic (no block asks
   for confirmation).  It can also be given at creation time (or the attribute
   set later) to override what's in the file.
 
 While _any_ python file can be run as a Demo instance, if there are no stop
 tags the whole file will run in a single block (no different that calling
 first %pycat and then %run).  The minimal markup to make this useful is to
 place a set of stop tags; the other tags are only there to let you fine-tune
 the execution.
 
 This is probably best explained with the simple example file below.  You can
 copy this into a file named ex_demo.py, and try running it via::
 
     from IPython.lib.demo import Demo
     d = Demo('ex_demo.py')
     d()
 
 Each time you call the demo object, it runs the next block.  The demo object
 has a few useful methods for navigation, like again(), edit(), jump(), seek()
 and back().  It can be reset for a new run via reset() or reloaded from disk
 (in case you've edited the source) via reload().  See their docstrings below.
 
 Note: To make this simpler to explore, a file called "demo-exercizer.py" has
 been added to the "docs/examples/core" directory.  Just cd to this directory in
 an IPython session, and type::
 
   %run demo-exercizer.py
 
 and then follow the directions.
 
 Example
 -------
 
 The following is a very simple example of a valid demo file.
 
 ::
 
     #################### EXAMPLE DEMO <ex_demo.py> ###############################
     '''A simple interactive demo to illustrate the use of IPython's Demo class.'''
 
     print 'Hello, welcome to an interactive IPython demo.'
 
     # The mark below defines a block boundary, which is a point where IPython will
     # stop execution and return to the interactive prompt. The dashes are actually
     # optional and used only as a visual aid to clearly separate blocks while
     # editing the demo code.
     # <demo> stop
 
     x = 1
     y = 2
 
     # <demo> stop
 
     # the mark below makes this block as silent
     # <demo> silent
 
     print 'This is a silent block, which gets executed but not printed.'
 
     # <demo> stop
     # <demo> auto
     print 'This is an automatic block.'
     print 'It is executed without asking for confirmation, but printed.'
     z = x+y
 
     print 'z=',x
 
     # <demo> stop
     # This is just another normal block.
     print 'z is now:', z
 
     print 'bye!'
     ################### END EXAMPLE DEMO <ex_demo.py> ############################
 """
 
 
 #*****************************************************************************
 #     Copyright (C) 2005-2006 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #
 #*****************************************************************************
 
 import os
 import re
 import shlex
 import sys
 import pygments
 from pathlib import Path
 
 from IPython.utils.text import marquee
 from IPython.utils import openpy
 from IPython.utils import py3compat
 __all__ = ['Demo','IPythonDemo','LineDemo','IPythonLineDemo','DemoError']
 
 class DemoError(Exception): pass
 
 def re_mark(mark):
     return re.compile(r'^\s*#\s+<demo>\s+%s\s*$' % mark,re.MULTILINE)
 
 class Demo(object):
 
     re_stop     = re_mark(r'-*\s?stop\s?-*')
     re_silent   = re_mark('silent')
     re_auto     = re_mark('auto')
     re_auto_all = re_mark('auto_all')
 
     def __init__(self,src,title='',arg_str='',auto_all=None, format_rst=False,
                  formatter='terminal', style='default'):
         """Make a new demo object.  To run the demo, simply call the object.
 
         See the module docstring for full details and an example (you can use
         IPython.Demo? in IPython to see it).
 
         Inputs:
 
           - src is either a file, or file-like object, or a
               string that can be resolved to a filename.
 
         Optional inputs:
 
           - title: a string to use as the demo name.  Of most use when the demo
             you are making comes from an object that has no filename, or if you
             want an alternate denotation distinct from the filename.
 
           - arg_str(''): a string of arguments, internally converted to a list
             just like sys.argv, so the demo script can see a similar
             environment.
 
           - auto_all(None): global flag to run all blocks automatically without
             confirmation.  This attribute overrides the block-level tags and
             applies to the whole demo.  It is an attribute of the object, and
             can be changed at runtime simply by reassigning it to a boolean
             value.
 
           - format_rst(False): a bool to enable comments and doc strings
             formatting with pygments rst lexer
 
           - formatter('terminal'): a string of pygments formatter name to be
             used. Useful values for terminals: terminal, terminal256,
             terminal16m
 
           - style('default'): a string of pygments style name to be used.
-          """
+        """
         if hasattr(src, "read"):
              # It seems to be a file or a file-like object
             self.fname = "from a file-like object"
             if title == '':
                 self.title = "from a file-like object"
             else:
                 self.title = title
         else:
              # Assume it's a string or something that can be converted to one
             self.fname = src
             if title == '':
                 (filepath, filename) = os.path.split(src)
                 self.title = filename
             else:
                 self.title = title
         self.sys_argv = [src] + shlex.split(arg_str)
         self.auto_all = auto_all
         self.src = src
 
         try:
             ip = get_ipython()  # this is in builtins whenever IPython is running
             self.inside_ipython = True
         except NameError:
             self.inside_ipython = False
 
         if self.inside_ipython:
             # get a few things from ipython.  While it's a bit ugly design-wise,
             # it ensures that things like color scheme and the like are always in
             # sync with the ipython mode being used.  This class is only meant to
             # be used inside ipython anyways,  so it's OK.
             self.ip_ns       = ip.user_ns
             self.ip_colorize = ip.pycolorize
             self.ip_showtb   = ip.showtraceback
             self.ip_run_cell = ip.run_cell
             self.shell       = ip
 
         self.formatter = pygments.formatters.get_formatter_by_name(formatter,
                                                                    style=style)
         self.python_lexer = pygments.lexers.get_lexer_by_name("py3")
         self.format_rst = format_rst
         if format_rst:
             self.rst_lexer = pygments.lexers.get_lexer_by_name("rst")
 
         # load user data and initialize data structures
         self.reload()
 
     def fload(self):
         """Load file object."""
         # read data and parse into blocks
         if hasattr(self, 'fobj') and self.fobj is not None:
            self.fobj.close()
         if hasattr(self.src, "read"):
              # It seems to be a file or a file-like object
             self.fobj = self.src
         else:
              # Assume it's a string or something that can be converted to one
             self.fobj = openpy.open(self.fname)
 
     def reload(self):
         """Reload source from disk and initialize state."""
         self.fload()
 
         self.src     = "".join(openpy.strip_encoding_cookie(self.fobj))
         src_b        = [b.strip() for b in self.re_stop.split(self.src) if b]
         self._silent = [bool(self.re_silent.findall(b)) for b in src_b]
         self._auto   = [bool(self.re_auto.findall(b)) for b in src_b]
 
         # if auto_all is not given (def. None), we read it from the file
         if self.auto_all is None:
             self.auto_all = bool(self.re_auto_all.findall(src_b[0]))
         else:
             self.auto_all = bool(self.auto_all)
 
         # Clean the sources from all markup so it doesn't get displayed when
         # running the demo
         src_blocks = []
         auto_strip = lambda s: self.re_auto.sub('',s)
         for i,b in enumerate(src_b):
             if self._auto[i]:
                 src_blocks.append(auto_strip(b))
             else:
                 src_blocks.append(b)
         # remove the auto_all marker
         src_blocks[0] = self.re_auto_all.sub('',src_blocks[0])
 
         self.nblocks = len(src_blocks)
         self.src_blocks = src_blocks
 
         # also build syntax-highlighted source
         self.src_blocks_colored = list(map(self.highlight,self.src_blocks))
 
         # ensure clean namespace and seek offset
         self.reset()
 
     def reset(self):
         """Reset the namespace and seek pointer to restart the demo"""
         self.user_ns     = {}
         self.finished    = False
         self.block_index = 0
 
     def _validate_index(self,index):
         if index<0 or index>=self.nblocks:
             raise ValueError('invalid block index %s' % index)
 
     def _get_index(self,index):
         """Get the current block index, validating and checking status.
 
         Returns None if the demo is finished"""
 
         if index is None:
             if self.finished:
                 print('Demo finished.  Use <demo_name>.reset() if you want to rerun it.')
                 return None
             index = self.block_index
         else:
             self._validate_index(index)
         return index
 
     def seek(self,index):
         """Move the current seek pointer to the given block.
 
         You can use negative indices to seek from the end, with identical
         semantics to those of Python lists."""
         if index<0:
             index = self.nblocks + index
         self._validate_index(index)
         self.block_index = index
         self.finished = False
 
     def back(self,num=1):
         """Move the seek pointer back num blocks (default is 1)."""
         self.seek(self.block_index-num)
 
     def jump(self,num=1):
         """Jump a given number of blocks relative to the current one.
 
         The offset can be positive or negative, defaults to 1."""
         self.seek(self.block_index+num)
 
     def again(self):
         """Move the seek pointer back one block and re-execute."""
         self.back(1)
         self()
 
     def edit(self,index=None):
         """Edit a block.
 
         If no number is given, use the last block executed.
 
         This edits the in-memory copy of the demo, it does NOT modify the
         original source file.  If you want to do that, simply open the file in
         an editor and use reload() when you make changes to the file.  This
         method is meant to let you change a block during a demonstration for
         explanatory purposes, without damaging your original script."""
 
         index = self._get_index(index)
         if index is None:
             return
         # decrease the index by one (unless we're at the very beginning), so
         # that the default demo.edit() call opens up the sblock we've last run
         if index>0:
             index -= 1
 
         filename = self.shell.mktempfile(self.src_blocks[index])
         self.shell.hooks.editor(filename, 1)
         with open(Path(filename), "r") as f:
             new_block = f.read()
         # update the source and colored block
         self.src_blocks[index] = new_block
         self.src_blocks_colored[index] = self.highlight(new_block)
         self.block_index = index
         # call to run with the newly edited index
         self()
 
     def show(self,index=None):
         """Show a single block on screen"""
 
         index = self._get_index(index)
         if index is None:
             return
 
         print(self.marquee('<%s> block # %s (%s remaining)' %
                            (self.title,index,self.nblocks-index-1)))
         print(self.src_blocks_colored[index])
         sys.stdout.flush()
 
     def show_all(self):
         """Show entire demo on screen, block by block"""
 
         fname = self.title
         title = self.title
         nblocks = self.nblocks
         silent = self._silent
         marquee = self.marquee
         for index,block in enumerate(self.src_blocks_colored):
             if silent[index]:
                 print(marquee('<%s> SILENT block # %s (%s remaining)' %
                               (title,index,nblocks-index-1)))
             else:
                 print(marquee('<%s> block # %s (%s remaining)' %
                               (title,index,nblocks-index-1)))
             print(block, end=' ')
         sys.stdout.flush()
 
     def run_cell(self,source):
         """Execute a string with one or more lines of code"""
 
         exec(source, self.user_ns)
 
     def __call__(self,index=None):
         """run a block of the demo.
 
         If index is given, it should be an integer >=1 and <= nblocks.  This
         means that the calling convention is one off from typical Python
         lists.  The reason for the inconsistency is that the demo always
         prints 'Block n/N, and N is the total, so it would be very odd to use
         zero-indexing here."""
 
         index = self._get_index(index)
         if index is None:
             return
         try:
             marquee = self.marquee
             next_block = self.src_blocks[index]
             self.block_index += 1
             if self._silent[index]:
                 print(marquee('Executing silent block # %s (%s remaining)' %
                               (index,self.nblocks-index-1)))
             else:
                 self.pre_cmd()
                 self.show(index)
                 if self.auto_all or self._auto[index]:
                     print(marquee('output:'))
                 else:
                     print(marquee('Press <q> to quit, <Enter> to execute...'), end=' ')
                     ans = py3compat.input().strip()
                     if ans:
                         print(marquee('Block NOT executed'))
                         return
             try:
                 save_argv = sys.argv
                 sys.argv = self.sys_argv
                 self.run_cell(next_block)
                 self.post_cmd()
             finally:
                 sys.argv = save_argv
 
         except:
             if self.inside_ipython:
                 self.ip_showtb(filename=self.fname)
         else:
             if self.inside_ipython:
                 self.ip_ns.update(self.user_ns)
 
         if self.block_index == self.nblocks:
             mq1 = self.marquee('END OF DEMO')
             if mq1:
                 # avoid spurious print if empty marquees are used
                 print()
                 print(mq1)
                 print(self.marquee('Use <demo_name>.reset() if you want to rerun it.'))
             self.finished = True
 
     # These methods are meant to be overridden by subclasses who may wish to
     # customize the behavior of of their demos.
     def marquee(self,txt='',width=78,mark='*'):
         """Return the input string centered in a 'marquee'."""
         return marquee(txt,width,mark)
 
     def pre_cmd(self):
         """Method called before executing each block."""
         pass
 
     def post_cmd(self):
         """Method called after executing each block."""
         pass
 
     def highlight(self, block):
         """Method called on each block to highlight it content"""
         tokens = pygments.lex(block, self.python_lexer)
         if self.format_rst:
             from pygments.token import Token
             toks = []
             for token in tokens:
                 if token[0] == Token.String.Doc and len(token[1]) > 6:
                     toks += pygments.lex(token[1][:3], self.python_lexer)
                     # parse doc string content by rst lexer
                     toks += pygments.lex(token[1][3:-3], self.rst_lexer)
                     toks += pygments.lex(token[1][-3:], self.python_lexer)
                 elif token[0] == Token.Comment.Single:
                     toks.append((Token.Comment.Single, token[1][0]))
                     # parse comment content by rst lexer
                     # remove the extra newline added by rst lexer
                     toks += list(pygments.lex(token[1][1:], self.rst_lexer))[:-1]
                 else:
                     toks.append(token)
             tokens = toks
         return pygments.format(tokens, self.formatter)
 
 
 class IPythonDemo(Demo):
     """Class for interactive demos with IPython's input processing applied.
 
     This subclasses Demo, but instead of executing each block by the Python
     interpreter (via exec), it actually calls IPython on it, so that any input
     filters which may be in place are applied to the input block.
 
     If you have an interactive environment which exposes special input
     processing, you can use this class instead to write demo scripts which
     operate exactly as if you had typed them interactively.  The default Demo
     class requires the input to be valid, pure Python code.
     """
 
     def run_cell(self,source):
         """Execute a string with one or more lines of code"""
 
         self.shell.run_cell(source)
 
 class LineDemo(Demo):
     """Demo where each line is executed as a separate block.
 
     The input script should be valid Python code.
 
     This class doesn't require any markup at all, and it's meant for simple
     scripts (with no nesting or any kind of indentation) which consist of
     multiple lines of input to be executed, one at a time, as if they had been
     typed in the interactive prompt.
 
     Note: the input can not have *any* indentation, which means that only
     single-lines of input are accepted, not even function definitions are
     valid."""
 
     def reload(self):
         """Reload source from disk and initialize state."""
         # read data and parse into blocks
         self.fload()
         lines           = self.fobj.readlines()
         src_b           = [l for l in lines if l.strip()]
         nblocks         = len(src_b)
         self.src        = ''.join(lines)
         self._silent    = [False]*nblocks
         self._auto      = [True]*nblocks
         self.auto_all   = True
         self.nblocks    = nblocks
         self.src_blocks = src_b
 
         # also build syntax-highlighted source
         self.src_blocks_colored = list(map(self.highlight,self.src_blocks))
 
         # ensure clean namespace and seek offset
         self.reset()
 
 
 class IPythonLineDemo(IPythonDemo,LineDemo):
     """Variant of the LineDemo class whose input is processed by IPython."""
     pass
 
 
 class ClearMixin(object):
     """Use this mixin to make Demo classes with less visual clutter.
 
     Demos using this mixin will clear the screen before every block and use
     blank marquees.
 
     Note that in order for the methods defined here to actually override those
     of the classes it's mixed with, it must go /first/ in the inheritance
     tree.  For example:
 
         class ClearIPDemo(ClearMixin,IPythonDemo): pass
 
     will provide an IPythonDemo class with the mixin's features.
     """
 
     def marquee(self,txt='',width=78,mark='*'):
         """Blank marquee that returns '' no matter what the input."""
         return ''
 
     def pre_cmd(self):
         """Method called before executing each block.
 
         This one simply clears the screen."""
         from IPython.utils.terminal import _term_clear
         _term_clear()
 
 class ClearDemo(ClearMixin,Demo):
     pass
 
 
 class ClearIPDemo(ClearMixin,IPythonDemo):
     pass
 
 
 def slide(file_path, noclear=False, format_rst=True, formatter="terminal",
           style="native", auto_all=False, delimiter='...'):
     if noclear:
         demo_class = Demo
     else:
         demo_class = ClearDemo
     demo = demo_class(file_path, format_rst=format_rst, formatter=formatter,
                       style=style, auto_all=auto_all)
     while not demo.finished:
         demo()
         try:
             py3compat.input('\n' + delimiter)
         except KeyboardInterrupt:
             exit(1)
 
 if __name__ == '__main__':
     import argparse
     parser = argparse.ArgumentParser(description='Run python demos')
     parser.add_argument('--noclear', '-C', action='store_true',
                         help='Do not clear terminal on each slide')
     parser.add_argument('--rst', '-r', action='store_true',
                         help='Highlight comments and dostrings as rst')
     parser.add_argument('--formatter', '-f', default='terminal',
                         help='pygments formatter name could be: terminal, '
                         'terminal256, terminal16m')
     parser.add_argument('--style', '-s', default='default',
                         help='pygments style name')
     parser.add_argument('--auto', '-a', action='store_true',
                         help='Run all blocks automatically without'
                         'confirmation')
     parser.add_argument('--delimiter', '-d', default='...',
                         help='slides delimiter added after each slide run')
     parser.add_argument('file', nargs=1,
                         help='python demo file')
     args = parser.parse_args()
     slide(args.file[0], noclear=args.noclear, format_rst=args.rst,
           formatter=args.formatter, style=args.style, auto_all=args.auto,
           delimiter=args.delimiter)

IPython/lib/display.py

@@ -1,677 +1,677 b''
 """Various display related classes.
 
 Authors : MinRK, gregcaporaso, dannystaple
 """
 from html import escape as html_escape
 from os.path import exists, isfile, splitext, abspath, join, isdir
 from os import walk, sep, fsdecode
 
 from IPython.core.display import DisplayObject, TextDisplayObject
 
 from typing import Tuple, Iterable
 
 __all__ = ['Audio', 'IFrame', 'YouTubeVideo', 'VimeoVideo', 'ScribdDocument',
            'FileLink', 'FileLinks', 'Code']
 
 
 class Audio(DisplayObject):
     """Create an audio object.
 
     When this object is returned by an input cell or passed to the
     display function, it will result in Audio controls being displayed
     in the frontend (only works in the notebook).
 
     Parameters
     ----------
     data : numpy array, list, unicode, str or bytes
         Can be one of
 
           * Numpy 1d array containing the desired waveform (mono)
           * Numpy 2d array containing waveforms for each channel.
             Shape=(NCHAN, NSAMPLES). For the standard channel order, see
             http://msdn.microsoft.com/en-us/library/windows/hardware/dn653308(v=vs.85).aspx
           * List of float or integer representing the waveform (mono)
           * String containing the filename
           * Bytestring containing raw PCM data or
           * URL pointing to a file on the web.
 
         If the array option is used, the waveform will be normalized.
 
         If a filename or url is used, the format support will be browser
         dependent.
     url : unicode
         A URL to download the data from.
     filename : unicode
         Path to a local file to load the data from.
     embed : boolean
         Should the audio data be embedded using a data URI (True) or should
         the original source be referenced. Set this to True if you want the
         audio to playable later with no internet connection in the notebook.
 
         Default is `True`, unless the keyword argument `url` is set, then
         default value is `False`.
     rate : integer
         The sampling rate of the raw data.
         Only required when data parameter is being used as an array
     autoplay : bool
         Set to True if the audio should immediately start playing.
         Default is `False`.
     normalize : bool
         Whether audio should be normalized (rescaled) to the maximum possible
         range. Default is `True`. When set to `False`, `data` must be between
         -1 and 1 (inclusive), otherwise an error is raised.
         Applies only when `data` is a list or array of samples; other types of
         audio are never normalized.
 
     Examples
     --------
 
     >>> import pytest
     >>> np = pytest.importorskip("numpy")
 
     Generate a sound
 
     >>> import numpy as np
     >>> framerate = 44100
     >>> t = np.linspace(0,5,framerate*5)
     >>> data = np.sin(2*np.pi*220*t) + np.sin(2*np.pi*224*t)
     >>> Audio(data, rate=framerate)
     <IPython.lib.display.Audio object>
 
     Can also do stereo or more channels
 
     >>> dataleft = np.sin(2*np.pi*220*t)
     >>> dataright = np.sin(2*np.pi*224*t)
     >>> Audio([dataleft, dataright], rate=framerate)
     <IPython.lib.display.Audio object>
 
     From URL:
 
     >>> Audio("http://www.nch.com.au/acm/8k16bitpcm.wav")  # doctest: +SKIP
     >>> Audio(url="http://www.w3schools.com/html/horse.ogg")  # doctest: +SKIP
 
     From a File:
 
     >>> Audio('/path/to/sound.wav')  # doctest: +SKIP
     >>> Audio(filename='/path/to/sound.ogg')  # doctest: +SKIP
 
     From Bytes:
 
     >>> Audio(b'RAW_WAV_DATA..')  # doctest: +SKIP
     >>> Audio(data=b'RAW_WAV_DATA..')  # doctest: +SKIP
 
     See Also
     --------
     ipywidgets.Audio
     
          AUdio widget with more more flexibility and options.
     
     """
     _read_flags = 'rb'
 
     def __init__(self, data=None, filename=None, url=None, embed=None, rate=None, autoplay=False, normalize=True, *,
                  element_id=None):
         if filename is None and url is None and data is None:
             raise ValueError("No audio data found. Expecting filename, url, or data.")
         if embed is False and url is None:
             raise ValueError("No url found. Expecting url when embed=False")
 
         if url is not None and embed is not True:
             self.embed = False
         else:
             self.embed = True
         self.autoplay = autoplay
         self.element_id = element_id
         super(Audio, self).__init__(data=data, url=url, filename=filename)
 
         if self.data is not None and not isinstance(self.data, bytes):
             if rate is None:
                 raise ValueError("rate must be specified when data is a numpy array or list of audio samples.")
             self.data = Audio._make_wav(data, rate, normalize)
 
     def reload(self):
         """Reload the raw data from file or URL."""
         import mimetypes
         if self.embed:
             super(Audio, self).reload()
 
         if self.filename is not None:
             self.mimetype = mimetypes.guess_type(self.filename)[0]
         elif self.url is not None:
             self.mimetype = mimetypes.guess_type(self.url)[0]
         else:
             self.mimetype = "audio/wav"
 
     @staticmethod
     def _make_wav(data, rate, normalize):
         """ Transform a numpy array to a PCM bytestring """
         from io import BytesIO
         import wave
 
         try:
             scaled, nchan = Audio._validate_and_normalize_with_numpy(data, normalize)
         except ImportError:
             scaled, nchan = Audio._validate_and_normalize_without_numpy(data, normalize)
 
         fp = BytesIO()
         waveobj = wave.open(fp,mode='wb')
         waveobj.setnchannels(nchan)
         waveobj.setframerate(rate)
         waveobj.setsampwidth(2)
         waveobj.setcomptype('NONE','NONE')
         waveobj.writeframes(scaled)
         val = fp.getvalue()
         waveobj.close()
 
         return val
 
     @staticmethod
     def _validate_and_normalize_with_numpy(data, normalize) -> Tuple[bytes, int]:
         import numpy as np
 
         data = np.array(data, dtype=float)
         if len(data.shape) == 1:
             nchan = 1
         elif len(data.shape) == 2:
             # In wave files,channels are interleaved. E.g.,
             # "L1R1L2R2..." for stereo. See
             # http://msdn.microsoft.com/en-us/library/windows/hardware/dn653308(v=vs.85).aspx
             # for channel ordering
             nchan = data.shape[0]
             data = data.T.ravel()
         else:
             raise ValueError('Array audio input must be a 1D or 2D array')
         
         max_abs_value = np.max(np.abs(data))
         normalization_factor = Audio._get_normalization_factor(max_abs_value, normalize)
         scaled = data / normalization_factor * 32767
         return scaled.astype("<h").tobytes(), nchan
 
     @staticmethod
     def _validate_and_normalize_without_numpy(data, normalize):
         import array
         import sys
 
         data = array.array('f', data)
 
         try:
             max_abs_value = float(max([abs(x) for x in data]))
         except TypeError as e:
             raise TypeError('Only lists of mono audio are '
                 'supported if numpy is not installed') from e
 
         normalization_factor = Audio._get_normalization_factor(max_abs_value, normalize)
         scaled = array.array('h', [int(x / normalization_factor * 32767) for x in data])
         if sys.byteorder == 'big':
             scaled.byteswap()
         nchan = 1
         return scaled.tobytes(), nchan
 
     @staticmethod
     def _get_normalization_factor(max_abs_value, normalize):
         if not normalize and max_abs_value > 1:
             raise ValueError('Audio data must be between -1 and 1 when normalize=False.')
         return max_abs_value if normalize else 1
 
     def _data_and_metadata(self):
         """shortcut for returning metadata with url information, if defined"""
         md = {}
         if self.url:
             md['url'] = self.url
         if md:
             return self.data, md
         else:
             return self.data
 
     def _repr_html_(self):
         src = """
                 <audio {element_id} controls="controls" {autoplay}>
                     <source src="{src}" type="{type}" />
                     Your browser does not support the audio element.
                 </audio>
               """
         return src.format(src=self.src_attr(), type=self.mimetype, autoplay=self.autoplay_attr(),
                           element_id=self.element_id_attr())
 
     def src_attr(self):
         import base64
         if self.embed and (self.data is not None):
             data = base64=base64.b64encode(self.data).decode('ascii')
             return """data:{type};base64,{base64}""".format(type=self.mimetype,
                                                             base64=data)
         elif self.url is not None:
             return self.url
         else:
             return ""
 
     def autoplay_attr(self):
         if(self.autoplay):
             return 'autoplay="autoplay"'
         else:
             return ''
     
     def element_id_attr(self):
         if (self.element_id):
             return 'id="{element_id}"'.format(element_id=self.element_id)
         else:
             return ''
 
 class IFrame(object):
     """
     Generic class to embed an iframe in an IPython notebook
     """
 
     iframe = """
         <iframe
             width="{width}"
             height="{height}"
             src="{src}{params}"
             frameborder="0"
             allowfullscreen
             {extras}
         ></iframe>
         """
 
     def __init__(self, src, width, height, extras: Iterable[str] = None, **kwargs):
         if extras is None:
             extras = []
 
         self.src = src
         self.width = width
         self.height = height
         self.extras = extras
         self.params = kwargs
 
     def _repr_html_(self):
         """return the embed iframe"""
         if self.params:
             from urllib.parse import urlencode
             params = "?" + urlencode(self.params)
         else:
             params = ""
         return self.iframe.format(
             src=self.src,
             width=self.width,
             height=self.height,
             params=params,
             extras=" ".join(self.extras),
         )
 
 
 class YouTubeVideo(IFrame):
     """Class for embedding a YouTube Video in an IPython session, based on its video id.
 
     e.g. to embed the video from https://www.youtube.com/watch?v=foo , you would
     do::
 
         vid = YouTubeVideo("foo")
         display(vid)
 
     To start from 30 seconds::
 
         vid = YouTubeVideo("abc", start=30)
         display(vid)
 
     To calculate seconds from time as hours, minutes, seconds use
     :class:`datetime.timedelta`::
 
         start=int(timedelta(hours=1, minutes=46, seconds=40).total_seconds())
 
     Other parameters can be provided as documented at
     https://developers.google.com/youtube/player_parameters#Parameters
     
     When converting the notebook using nbconvert, a jpeg representation of the video
     will be inserted in the document.
     """
 
     def __init__(self, id, width=400, height=300, allow_autoplay=False, **kwargs):
         self.id=id
         src = "https://www.youtube.com/embed/{0}".format(id)
         if allow_autoplay:
             extras = list(kwargs.get("extras", [])) + ['allow="autoplay"']
             kwargs.update(autoplay=1, extras=extras)
         super(YouTubeVideo, self).__init__(src, width, height, **kwargs)
 
     def _repr_jpeg_(self):
         # Deferred import
         from urllib.request import urlopen
 
         try:
             return urlopen("https://img.youtube.com/vi/{id}/hqdefault.jpg".format(id=self.id)).read()
         except IOError:
             return None
 
 class VimeoVideo(IFrame):
     """
     Class for embedding a Vimeo video in an IPython session, based on its video id.
     """
 
     def __init__(self, id, width=400, height=300, **kwargs):
         src="https://player.vimeo.com/video/{0}".format(id)
         super(VimeoVideo, self).__init__(src, width, height, **kwargs)
 
 class ScribdDocument(IFrame):
     """
     Class for embedding a Scribd document in an IPython session
 
     Use the start_page params to specify a starting point in the document
     Use the view_mode params to specify display type one off scroll | slideshow | book
 
     e.g to Display Wes' foundational paper about PANDAS in book mode from page 3
 
     ScribdDocument(71048089, width=800, height=400, start_page=3, view_mode="book")
     """
 
     def __init__(self, id, width=400, height=300, **kwargs):
         src="https://www.scribd.com/embeds/{0}/content".format(id)
         super(ScribdDocument, self).__init__(src, width, height, **kwargs)
 
 class FileLink(object):
     """Class for embedding a local file link in an IPython session, based on path
 
     e.g. to embed a link that was generated in the IPython notebook as my/data.txt
 
     you would do::
 
         local_file = FileLink("my/data.txt")
         display(local_file)
 
     or in the HTML notebook, just::
 
         FileLink("my/data.txt")
     """
 
     html_link_str = "<a href='%s' target='_blank'>%s</a>"
 
     def __init__(self,
                  path,
                  url_prefix='',
                  result_html_prefix='',
                  result_html_suffix='<br>'):
         """
         Parameters
         ----------
         path : str
             path to the file or directory that should be formatted
         url_prefix : str
             prefix to be prepended to all files to form a working link [default:
             '']
         result_html_prefix : str
             text to append to beginning to link [default: '']
         result_html_suffix : str
             text to append at the end of link [default: '<br>']
         """
         if isdir(path):
             raise ValueError("Cannot display a directory using FileLink. "
               "Use FileLinks to display '%s'." % path)
         self.path = fsdecode(path)
         self.url_prefix = url_prefix
         self.result_html_prefix = result_html_prefix
         self.result_html_suffix = result_html_suffix
 
     def _format_path(self):
         fp = ''.join([self.url_prefix, html_escape(self.path)])
         return ''.join([self.result_html_prefix,
                         self.html_link_str % \
                             (fp, html_escape(self.path, quote=False)),
                         self.result_html_suffix])
 
     def _repr_html_(self):
         """return html link to file
         """
         if not exists(self.path):
             return ("Path (<tt>%s</tt>) doesn't exist. "
                     "It may still be in the process of "
                     "being generated, or you may have the "
                     "incorrect path." % self.path)
 
         return self._format_path()
 
     def __repr__(self):
         """return absolute path to file
         """
         return abspath(self.path)
 
 class FileLinks(FileLink):
     """Class for embedding local file links in an IPython session, based on path
 
     e.g. to embed links to files that were generated in the IPython notebook
     under ``my/data``, you would do::
 
         local_files = FileLinks("my/data")
         display(local_files)
 
     or in the HTML notebook, just::
 
         FileLinks("my/data")
     """
     def __init__(self,
                  path,
                  url_prefix='',
                  included_suffixes=None,
                  result_html_prefix='',
                  result_html_suffix='<br>',
                  notebook_display_formatter=None,
                  terminal_display_formatter=None,
                  recursive=True):
         """
         See :class:`FileLink` for the ``path``, ``url_prefix``,
         ``result_html_prefix`` and ``result_html_suffix`` parameters.
 
         included_suffixes : list
           Filename suffixes to include when formatting output [default: include
           all files]
 
         notebook_display_formatter : function
           Used to format links for display in the notebook. See discussion of
           formatter functions below.
 
         terminal_display_formatter : function
           Used to format links for display in the terminal. See discussion of
           formatter functions below.
 
         Formatter functions must be of the form::
 
             f(dirname, fnames, included_suffixes)
 
         dirname : str
           The name of a directory
         fnames : list
           The files in that directory
         included_suffixes : list
           The file suffixes that should be included in the output (passing None
           meansto include all suffixes in the output in the built-in formatters)
         recursive : boolean
           Whether to recurse into subdirectories. Default is True.
 
         The function should return a list of lines that will be printed in the
         notebook (if passing notebook_display_formatter) or the terminal (if
         passing terminal_display_formatter). This function is iterated over for
         each directory in self.path. Default formatters are in place, can be
         passed here to support alternative formatting.
 
         """
         if isfile(path):
             raise ValueError("Cannot display a file using FileLinks. "
               "Use FileLink to display '%s'." % path)
         self.included_suffixes = included_suffixes
         # remove trailing slashes for more consistent output formatting
         path = path.rstrip('/')
 
         self.path = path
         self.url_prefix = url_prefix
         self.result_html_prefix = result_html_prefix
         self.result_html_suffix = result_html_suffix
 
         self.notebook_display_formatter = \
              notebook_display_formatter or self._get_notebook_display_formatter()
         self.terminal_display_formatter = \
              terminal_display_formatter or self._get_terminal_display_formatter()
 
         self.recursive = recursive
 
     def _get_display_formatter(self,
                                dirname_output_format,
                                fname_output_format,
                                fp_format,
                                fp_cleaner=None):
         """ generate built-in formatter function
 
-           this is used to define both the notebook and terminal built-in
-            formatters as they only differ by some wrapper text for each entry
-
-           dirname_output_format: string to use for formatting directory
-            names, dirname will be substituted for a single "%s" which
-            must appear in this string
-           fname_output_format: string to use for formatting file names,
-            if a single "%s" appears in the string, fname will be substituted
-            if two "%s" appear in the string, the path to fname will be
-             substituted for the first and fname will be substituted for the
-             second
-           fp_format: string to use for formatting filepaths, must contain
-            exactly two "%s" and the dirname will be substituted for the first
-            and fname will be substituted for the second
+        this is used to define both the notebook and terminal built-in
+         formatters as they only differ by some wrapper text for each entry
+
+        dirname_output_format: string to use for formatting directory
+         names, dirname will be substituted for a single "%s" which
+         must appear in this string
+        fname_output_format: string to use for formatting file names,
+         if a single "%s" appears in the string, fname will be substituted
+         if two "%s" appear in the string, the path to fname will be
+          substituted for the first and fname will be substituted for the
+          second
+        fp_format: string to use for formatting filepaths, must contain
+         exactly two "%s" and the dirname will be substituted for the first
+         and fname will be substituted for the second
         """
         def f(dirname, fnames, included_suffixes=None):
             result = []
             # begin by figuring out which filenames, if any,
             # are going to be displayed
             display_fnames = []
             for fname in fnames:
                 if (isfile(join(dirname,fname)) and
                        (included_suffixes is None or
                         splitext(fname)[1] in included_suffixes)):
                       display_fnames.append(fname)
 
             if len(display_fnames) == 0:
                 # if there are no filenames to display, don't print anything
                 # (not even the directory name)
                 pass
             else:
                 # otherwise print the formatted directory name followed by
                 # the formatted filenames
                 dirname_output_line = dirname_output_format % dirname
                 result.append(dirname_output_line)
                 for fname in display_fnames:
                     fp = fp_format % (dirname,fname)
                     if fp_cleaner is not None:
                         fp = fp_cleaner(fp)
                     try:
                         # output can include both a filepath and a filename...
                         fname_output_line = fname_output_format % (fp, fname)
                     except TypeError:
                         # ... or just a single filepath
                         fname_output_line = fname_output_format % fname
                     result.append(fname_output_line)
             return result
         return f
 
     def _get_notebook_display_formatter(self,
                                         spacer="&nbsp;&nbsp;"):
         """ generate function to use for notebook formatting
         """
         dirname_output_format = \
          self.result_html_prefix + "%s/" + self.result_html_suffix
         fname_output_format = \
          self.result_html_prefix + spacer + self.html_link_str + self.result_html_suffix
         fp_format = self.url_prefix + '%s/%s'
         if sep == "\\":
             # Working on a platform where the path separator is "\", so
             # must convert these to "/" for generating a URI
             def fp_cleaner(fp):
                 # Replace all occurrences of backslash ("\") with a forward
                 # slash ("/") - this is necessary on windows when a path is
                 # provided as input, but we must link to a URI
                 return fp.replace('\\','/')
         else:
             fp_cleaner = None
 
         return self._get_display_formatter(dirname_output_format,
                                            fname_output_format,
                                            fp_format,
                                            fp_cleaner)
 
     def _get_terminal_display_formatter(self,
                                         spacer="  "):
         """ generate function to use for terminal formatting
         """
         dirname_output_format = "%s/"
         fname_output_format = spacer + "%s"
         fp_format = '%s/%s'
 
         return self._get_display_formatter(dirname_output_format,
                                            fname_output_format,
                                            fp_format)
 
     def _format_path(self):
         result_lines = []
         if self.recursive:
             walked_dir = list(walk(self.path))
         else:
             walked_dir = [next(walk(self.path))]
         walked_dir.sort()
         for dirname, subdirs, fnames in walked_dir:
             result_lines += self.notebook_display_formatter(dirname, fnames, self.included_suffixes)
         return '\n'.join(result_lines)
 
     def __repr__(self):
         """return newline-separated absolute paths
         """
         result_lines = []
         if self.recursive:
             walked_dir = list(walk(self.path))
         else:
             walked_dir = [next(walk(self.path))]
         walked_dir.sort()
         for dirname, subdirs, fnames in walked_dir:
             result_lines += self.terminal_display_formatter(dirname, fnames, self.included_suffixes)
         return '\n'.join(result_lines)
 
 
 class Code(TextDisplayObject):
     """Display syntax-highlighted source code.
 
     This uses Pygments to highlight the code for HTML and Latex output.
 
     Parameters
     ----------
     data : str
         The code as a string
     url : str
         A URL to fetch the code from
     filename : str
         A local filename to load the code from
     language : str
         The short name of a Pygments lexer to use for highlighting.
         If not specified, it will guess the lexer based on the filename
         or the code. Available lexers: http://pygments.org/docs/lexers/
     """
     def __init__(self, data=None, url=None, filename=None, language=None):
         self.language = language
         super().__init__(data=data, url=url, filename=filename)
 
     def _get_lexer(self):
         if self.language:
             from pygments.lexers import get_lexer_by_name
             return get_lexer_by_name(self.language)
         elif self.filename:
             from pygments.lexers import get_lexer_for_filename
             return get_lexer_for_filename(self.filename)
         else:
             from pygments.lexers import guess_lexer
             return guess_lexer(self.data)
 
     def __repr__(self):
         return self.data
 
     def _repr_html_(self):
         from pygments import highlight
         from pygments.formatters import HtmlFormatter
         fmt = HtmlFormatter()
         style = '<style>{}</style>'.format(fmt.get_style_defs('.output_html'))
         return style + highlight(self.data, self._get_lexer(), fmt)
 
     def _repr_latex_(self):
         from pygments import highlight
         from pygments.formatters import LatexFormatter
         return highlight(self.data, self._get_lexer(), LatexFormatter())

IPython/lib/latextools.py

@@ -1,247 +1,246 b''
 # -*- coding: utf-8 -*-
 """Tools for handling LaTeX."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from io import BytesIO, open
 import os
 import tempfile
 import shutil
 import subprocess
 from base64 import encodebytes
 import textwrap
 
 from pathlib import Path, PurePath
 
 from IPython.utils.process import find_cmd, FindCmdError
 from traitlets.config import get_config
 from traitlets.config.configurable import SingletonConfigurable
 from traitlets import List, Bool, Unicode
 from IPython.utils.py3compat import cast_unicode
 
 
 class LaTeXTool(SingletonConfigurable):
     """An object to store configuration of the LaTeX tool."""
     def _config_default(self):
         return get_config()
 
     backends = List(
         Unicode(), ["matplotlib", "dvipng"],
         help="Preferred backend to draw LaTeX math equations. "
         "Backends in the list are checked one by one and the first "
         "usable one is used.  Note that `matplotlib` backend "
         "is usable only for inline style equations.  To draw  "
         "display style equations, `dvipng` backend must be specified. ",
         # It is a List instead of Enum, to make configuration more
         # flexible.  For example, to use matplotlib mainly but dvipng
         # for display style, the default ["matplotlib", "dvipng"] can
         # be used.  To NOT use dvipng so that other repr such as
         # unicode pretty printing is used, you can use ["matplotlib"].
         ).tag(config=True)
 
     use_breqn = Bool(
         True,
         help="Use breqn.sty to automatically break long equations. "
         "This configuration takes effect only for dvipng backend.",
         ).tag(config=True)
 
     packages = List(
         ['amsmath', 'amsthm', 'amssymb', 'bm'],
         help="A list of packages to use for dvipng backend. "
         "'breqn' will be automatically appended when use_breqn=True.",
         ).tag(config=True)
 
     preamble = Unicode(
         help="Additional preamble to use when generating LaTeX source "
         "for dvipng backend.",
         ).tag(config=True)
 
 
 def latex_to_png(s, encode=False, backend=None, wrap=False, color='Black',
                  scale=1.0):
     """Render a LaTeX string to PNG.
 
     Parameters
     ----------
     s : str
         The raw string containing valid inline LaTeX.
     encode : bool, optional
         Should the PNG data base64 encoded to make it JSON'able.
     backend : {matplotlib, dvipng}
         Backend for producing PNG data.
     wrap : bool
         If true, Automatically wrap `s` as a LaTeX equation.
     color : string
         Foreground color name among dvipsnames, e.g. 'Maroon' or on hex RGB
         format, e.g. '#AA20FA'.
     scale : float
         Scale factor for the resulting PNG.
-
     None is returned when the backend cannot be used.
 
     """
     s = cast_unicode(s)
     allowed_backends = LaTeXTool.instance().backends
     if backend is None:
         backend = allowed_backends[0]
     if backend not in allowed_backends:
         return None
     if backend == 'matplotlib':
         f = latex_to_png_mpl
     elif backend == 'dvipng':
         f = latex_to_png_dvipng
         if color.startswith('#'):
             # Convert hex RGB color to LaTeX RGB color.
             if len(color) == 7:
                 try:
                     color = "RGB {}".format(" ".join([str(int(x, 16)) for x in
                                                       textwrap.wrap(color[1:], 2)]))
                 except ValueError as e:
                     raise ValueError('Invalid color specification {}.'.format(color)) from e
             else:
                 raise ValueError('Invalid color specification {}.'.format(color))
     else:
         raise ValueError('No such backend {0}'.format(backend))
     bin_data = f(s, wrap, color, scale)
     if encode and bin_data:
         bin_data = encodebytes(bin_data)
     return bin_data
 
 
 def latex_to_png_mpl(s, wrap, color='Black', scale=1.0):
     try:
         from matplotlib import figure, font_manager, mathtext
         from matplotlib.backends import backend_agg
         from pyparsing import ParseFatalException
     except ImportError:
         return None
 
     # mpl mathtext doesn't support display math, force inline
     s = s.replace('$$', '$')
     if wrap:
         s = u'${0}$'.format(s)
 
     try:
         prop = font_manager.FontProperties(size=12)
         dpi = 120 * scale
         buffer = BytesIO()
 
         # Adapted from mathtext.math_to_image
         parser = mathtext.MathTextParser("path")
         width, height, depth, _, _ = parser.parse(s, dpi=72, prop=prop)
         fig = figure.Figure(figsize=(width / 72, height / 72))
         fig.text(0, depth / height, s, fontproperties=prop, color=color)
         backend_agg.FigureCanvasAgg(fig)
         fig.savefig(buffer, dpi=dpi, format="png", transparent=True)
         return buffer.getvalue()
     except (ValueError, RuntimeError, ParseFatalException):
         return None
 
 
 def latex_to_png_dvipng(s, wrap, color='Black', scale=1.0):
     try:
         find_cmd('latex')
         find_cmd('dvipng')
     except FindCmdError:
         return None
     try:
         workdir = Path(tempfile.mkdtemp())
         tmpfile = workdir.joinpath("tmp.tex")
         dvifile = workdir.joinpath("tmp.dvi")
         outfile = workdir.joinpath("tmp.png")
 
         with tmpfile.open("w", encoding="utf8") as f:
             f.writelines(genelatex(s, wrap))
 
         with open(os.devnull, 'wb') as devnull:
             subprocess.check_call(
                 ["latex", "-halt-on-error", "-interaction", "batchmode", tmpfile],
                 cwd=workdir, stdout=devnull, stderr=devnull)
 
             resolution = round(150*scale)
             subprocess.check_call(
                 [
                     "dvipng",
                     "-T",
                     "tight",
                     "-D",
                     str(resolution),
                     "-z",
                     "9",
                     "-bg",
                     "Transparent",
                     "-o",
                     outfile,
                     dvifile,
                     "-fg",
                     color,
                 ],
                 cwd=workdir,
                 stdout=devnull,
                 stderr=devnull,
             )
 
         with outfile.open("rb") as f:
             return f.read()
     except subprocess.CalledProcessError:
         return None
     finally:
         shutil.rmtree(workdir)
 
 
 def kpsewhich(filename):
     """Invoke kpsewhich command with an argument `filename`."""
     try:
         find_cmd("kpsewhich")
         proc = subprocess.Popen(
             ["kpsewhich", filename],
             stdout=subprocess.PIPE, stderr=subprocess.PIPE)
         (stdout, stderr) = proc.communicate()
         return stdout.strip().decode('utf8', 'replace')
     except FindCmdError:
         pass
 
 
 def genelatex(body, wrap):
     """Generate LaTeX document for dvipng backend."""
     lt = LaTeXTool.instance()
     breqn = wrap and lt.use_breqn and kpsewhich("breqn.sty")
     yield r'\documentclass{article}'
     packages = lt.packages
     if breqn:
         packages = packages + ['breqn']
     for pack in packages:
         yield r'\usepackage{{{0}}}'.format(pack)
     yield r'\pagestyle{empty}'
     if lt.preamble:
         yield lt.preamble
     yield r'\begin{document}'
     if breqn:
         yield r'\begin{dmath*}'
         yield body
         yield r'\end{dmath*}'
     elif wrap:
         yield u'$${0}$$'.format(body)
     else:
         yield body
     yield u'\\end{document}'
 
 
 _data_uri_template_png = u"""<img src="data:image/png;base64,%s" alt=%s />"""
 
 def latex_to_html(s, alt='image'):
     """Render LaTeX to HTML with embedded PNG data using data URIs.
 
     Parameters
     ----------
     s : str
         The raw string containing valid inline LateX.
     alt : str
         The alt text to use for the HTML.
     """
     base64_data = latex_to_png(s, encode=True).decode('ascii')
     if base64_data:
         return _data_uri_template_png  % (base64_data, alt)