Try to avoid network connection during tests.

Mitigate  #13468

IPython/core/display.py

@@ -1,1277 +1,1277 b''
 # -*- coding: utf-8 -*-
 """Top-level display functions for displaying object in different formats."""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 
 from binascii import b2a_base64, hexlify
 import html
 import json
 import mimetypes
 import os
 import struct
 import warnings
 from copy import deepcopy
 from os.path import splitext
 from pathlib import Path, PurePath
 
 from IPython.utils.py3compat import cast_unicode
 from IPython.testing.skipdoctest import skip_doctest
 from . import display_functions
 
 
 __all__ = ['display_pretty', 'display_html', 'display_markdown',
            'display_svg', 'display_png', 'display_jpeg', 'display_latex', 'display_json',
            'display_javascript', 'display_pdf', 'DisplayObject', 'TextDisplayObject',
            'Pretty', 'HTML', 'Markdown', 'Math', 'Latex', 'SVG', 'ProgressBar', 'JSON',
            'GeoJSON', 'Javascript', 'Image', 'set_matplotlib_formats',
            'set_matplotlib_close',
            'Video']
 
 _deprecated_names = ["display", "clear_output", "publish_display_data", "update_display", "DisplayHandle"]
 
 __all__ = __all__ + _deprecated_names
 
 
 # ----- warn to import from IPython.display -----
 
 from warnings import warn
 
 
 def __getattr__(name):
     if name in _deprecated_names:
         warn(f"Importing {name} from IPython.core.display is deprecated since IPython 7.14, please import from IPython display", DeprecationWarning, stacklevel=2)
         return getattr(display_functions, name)
 
     if name in globals().keys():
         return globals()[name]
     else:
         raise AttributeError(f"module {__name__} has no attribute {name}")
 
 
 #-----------------------------------------------------------------------------
 # utility functions
 #-----------------------------------------------------------------------------
 
 def _safe_exists(path):
     """Check path, but don't let exceptions raise"""
     try:
         return os.path.exists(path)
     except Exception:
         return False
 
 
 def _display_mimetype(mimetype, objs, raw=False, metadata=None):
     """internal implementation of all display_foo methods
 
     Parameters
     ----------
     mimetype : str
         The mimetype to be published (e.g. 'image/png')
     *objs : object
         The Python objects to display, or if raw=True raw text data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     if metadata:
         metadata = {mimetype: metadata}
     if raw:
         # turn list of pngdata into list of { 'image/png': pngdata }
         objs = [ {mimetype: obj} for obj in objs ]
     display_functions.display(*objs, raw=raw, metadata=metadata, include=[mimetype])
 
 #-----------------------------------------------------------------------------
 # Main functions
 #-----------------------------------------------------------------------------
 
 
 def display_pretty(*objs, **kwargs):
     """Display the pretty (default) representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw text data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('text/plain', objs, **kwargs)
 
 
 def display_html(*objs, **kwargs):
     """Display the HTML representation of an object.
 
     Note: If raw=False and the object does not have a HTML
     representation, no HTML will be shown.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw HTML data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('text/html', objs, **kwargs)
 
 
 def display_markdown(*objs, **kwargs):
     """Displays the Markdown representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw markdown data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
 
     _display_mimetype('text/markdown', objs, **kwargs)
 
 
 def display_svg(*objs, **kwargs):
     """Display the SVG representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw svg data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('image/svg+xml', objs, **kwargs)
 
 
 def display_png(*objs, **kwargs):
     """Display the PNG representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw png data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('image/png', objs, **kwargs)
 
 
 def display_jpeg(*objs, **kwargs):
     """Display the JPEG representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw JPEG data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('image/jpeg', objs, **kwargs)
 
 
 def display_latex(*objs, **kwargs):
     """Display the LaTeX representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw latex data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('text/latex', objs, **kwargs)
 
 
 def display_json(*objs, **kwargs):
     """Display the JSON representation of an object.
 
     Note that not many frontends support displaying JSON.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw json data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('application/json', objs, **kwargs)
 
 
 def display_javascript(*objs, **kwargs):
     """Display the Javascript representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw javascript data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('application/javascript', objs, **kwargs)
 
 
 def display_pdf(*objs, **kwargs):
     """Display the PDF representation of an object.
 
     Parameters
     ----------
     *objs : object
         The Python objects to display, or if raw=True raw javascript data to
         display.
     raw : bool
         Are the data objects raw data or Python objects that need to be
         formatted before display? [default: False]
     metadata : dict (optional)
         Metadata to be associated with the specific mimetype output.
     """
     _display_mimetype('application/pdf', objs, **kwargs)
 
 
 #-----------------------------------------------------------------------------
 # Smart classes
 #-----------------------------------------------------------------------------
 
 
 class DisplayObject(object):
     """An object that wraps data to be displayed."""
 
     _read_flags = 'r'
     _show_mem_addr = False
     metadata = None
 
     def __init__(self, data=None, url=None, filename=None, metadata=None):
         """Create a display object given raw data.
 
         When this object is returned by an expression or passed to the
         display function, it will result in the data being displayed
         in the frontend. The MIME type of the data should match the
         subclasses used, so the Png subclass should be used for 'image/png'
         data. If the data is a URL, the data will first be downloaded
         and then displayed. If
 
         Parameters
         ----------
         data : unicode, str or bytes
             The raw data or a URL or file to load the data from
         url : unicode
             A URL to download the data from.
         filename : unicode
             Path to a local file to load the data from.
         metadata : dict
             Dict of metadata associated to be the object when displayed
         """
         if isinstance(data, (Path, PurePath)):
             data = str(data)
 
         if data is not None and isinstance(data, str):
             if data.startswith('http') and url is None:
                 url = data
                 filename = None
                 data = None
             elif _safe_exists(data) and filename is None:
                 url = None
                 filename = data
                 data = None
 
         self.url = url
         self.filename = filename
         # because of @data.setter methods in
         # subclasses ensure url and filename are set
         # before assigning to self.data
         self.data = data
 
         if metadata is not None:
             self.metadata = metadata
         elif self.metadata is None:
             self.metadata = {}
 
         self.reload()
         self._check_data()
 
     def __repr__(self):
         if not self._show_mem_addr:
             cls = self.__class__
             r = "<%s.%s object>" % (cls.__module__, cls.__name__)
         else:
             r = super(DisplayObject, self).__repr__()
         return r
 
     def _check_data(self):
         """Override in subclasses if there's something to check."""
         pass
 
     def _data_and_metadata(self):
         """shortcut for returning metadata with shape information, if defined"""
         if self.metadata:
             return self.data, deepcopy(self.metadata)
         else:
             return self.data
 
     def reload(self):
         """Reload the raw data from file or URL."""
         if self.filename is not None:
             encoding = None if "b" in self._read_flags else "utf-8"
             with open(self.filename, self._read_flags, encoding=encoding) as f:
                 self.data = f.read()
         elif self.url is not None:
             # Deferred import
             from urllib.request import urlopen
             response = urlopen(self.url)
             data = response.read()
             # extract encoding from header, if there is one:
             encoding = None
             if 'content-type' in response.headers:
                 for sub in response.headers['content-type'].split(';'):
                     sub = sub.strip()
                     if sub.startswith('charset'):
                         encoding = sub.split('=')[-1].strip()
                         break
             if 'content-encoding' in response.headers:
                 # TODO: do deflate?
                 if 'gzip' in response.headers['content-encoding']:
                     import gzip
                     from io import BytesIO
 
                     # assume utf-8 if encoding is not specified
                     with gzip.open(
                         BytesIO(data), "rt", encoding=encoding or "utf-8"
                     ) as fp:
                         encoding = None
                         data = fp.read()
 
             # decode data, if an encoding was specified
             # We only touch self.data once since
             # subclasses such as SVG have @data.setter methods
             # that transform self.data into ... well svg.
             if encoding:
                 self.data = data.decode(encoding, 'replace')
             else:
                 self.data = data
 
 
 class TextDisplayObject(DisplayObject):
     """Validate that display data is text"""
     def _check_data(self):
         if self.data is not None and not isinstance(self.data, str):
             raise TypeError("%s expects text, not %r" % (self.__class__.__name__, self.data))
 
 class Pretty(TextDisplayObject):
 
     def _repr_pretty_(self, pp, cycle):
         return pp.text(self.data)
 
 
 class HTML(TextDisplayObject):
 
     def __init__(self, data=None, url=None, filename=None, metadata=None):
         def warn():
             if not data:
                 return False
 
             #
             # Avoid calling lower() on the entire data, because it could be a
             # long string and we're only interested in its beginning and end.
             #
             prefix = data[:10].lower()
             suffix = data[-10:].lower()
             return prefix.startswith("<iframe ") and suffix.endswith("</iframe>")
 
         if warn():
             warnings.warn("Consider using IPython.display.IFrame instead")
         super(HTML, self).__init__(data=data, url=url, filename=filename, metadata=metadata)
 
     def _repr_html_(self):
         return self._data_and_metadata()
 
     def __html__(self):
         """
         This method exists to inform other HTML-using modules (e.g. Markupsafe,
         htmltag, etc) that this object is HTML and does not need things like
         special characters (<>&) escaped.
         """
         return self._repr_html_()
 
 
 class Markdown(TextDisplayObject):
 
     def _repr_markdown_(self):
         return self._data_and_metadata()
 
 
 class Math(TextDisplayObject):
 
     def _repr_latex_(self):
         s = r"$\displaystyle %s$" % self.data.strip('$')
         if self.metadata:
             return s, deepcopy(self.metadata)
         else:
             return s
 
 
 class Latex(TextDisplayObject):
 
     def _repr_latex_(self):
         return self._data_and_metadata()
 
 
 class SVG(DisplayObject):
     """Embed an SVG into the display.
 
     Note if you just want to view a svg image via a URL use `:class:Image` with
     a url=URL keyword argument.
     """
 
     _read_flags = 'rb'
     # wrap data in a property, which extracts the <svg> tag, discarding
     # document headers
     _data = None
 
     @property
     def data(self):
         return self._data
 
     @data.setter
     def data(self, svg):
         if svg is None:
             self._data = None
             return
         # parse into dom object
         from xml.dom import minidom
         x = minidom.parseString(svg)
         # get svg tag (should be 1)
         found_svg = x.getElementsByTagName('svg')
         if found_svg:
             svg = found_svg[0].toxml()
         else:
             # fallback on the input, trust the user
             # but this is probably an error.
             pass
         svg = cast_unicode(svg)
         self._data = svg
 
     def _repr_svg_(self):
         return self._data_and_metadata()
 
 class ProgressBar(DisplayObject):
     """Progressbar supports displaying a progressbar like element
     """
     def __init__(self, total):
         """Creates a new progressbar
 
         Parameters
         ----------
         total : int
             maximum size of the progressbar
         """
         self.total = total
         self._progress = 0
         self.html_width = '60ex'
         self.text_width = 60
         self._display_id = hexlify(os.urandom(8)).decode('ascii')
 
     def __repr__(self):
         fraction = self.progress / self.total
         filled = '=' * int(fraction * self.text_width)
         rest = ' ' * (self.text_width - len(filled))
         return '[{}{}] {}/{}'.format(
             filled, rest,
             self.progress, self.total,
         )
 
     def _repr_html_(self):
         return "<progress style='width:{}' max='{}' value='{}'></progress>".format(
             self.html_width, self.total, self.progress)
 
     def display(self):
         display_functions.display(self, display_id=self._display_id)
 
     def update(self):
         display_functions.display(self, display_id=self._display_id, update=True)
 
     @property
     def progress(self):
         return self._progress
 
     @progress.setter
     def progress(self, value):
         self._progress = value
         self.update()
 
     def __iter__(self):
         self.display()
         self._progress = -1 # First iteration is 0
         return self
 
     def __next__(self):
         """Returns current value and increments display by one."""
         self.progress += 1
         if self.progress < self.total:
             return self.progress
         else:
             raise StopIteration()
 
 class JSON(DisplayObject):
     """JSON expects a JSON-able dict or list
 
     not an already-serialized JSON string.
 
     Scalar types (None, number, string) are not allowed, only dict or list containers.
     """
     # wrap data in a property, which warns about passing already-serialized JSON
     _data = None
     def __init__(self, data=None, url=None, filename=None, expanded=False, metadata=None, root='root', **kwargs):
         """Create a JSON display object given raw data.
 
         Parameters
         ----------
         data : dict or list
             JSON data to display. Not an already-serialized JSON string.
             Scalar types (None, number, string) are not allowed, only dict
             or list containers.
         url : unicode
             A URL to download the data from.
         filename : unicode
             Path to a local file to load the data from.
         expanded : boolean
             Metadata to control whether a JSON display component is expanded.
         metadata : dict
             Specify extra metadata to attach to the json display object.
         root : str
             The name of the root element of the JSON tree
         """
         self.metadata = {
             'expanded': expanded,
             'root': root,
         }
         if metadata:
             self.metadata.update(metadata)
         if kwargs:
             self.metadata.update(kwargs)
         super(JSON, self).__init__(data=data, url=url, filename=filename)
 
     def _check_data(self):
         if self.data is not None and not isinstance(self.data, (dict, list)):
             raise TypeError("%s expects JSONable dict or list, not %r" % (self.__class__.__name__, self.data))
 
     @property
     def data(self):
         return self._data
 
     @data.setter
     def data(self, data):
         if isinstance(data, (Path, PurePath)):
             data = str(data)
 
         if isinstance(data, str):
             if self.filename is None and self.url is None:
                 warnings.warn("JSON expects JSONable dict or list, not JSON strings")
             data = json.loads(data)
         self._data = data
 
     def _data_and_metadata(self):
         return self.data, self.metadata
 
     def _repr_json_(self):
         return self._data_and_metadata()
 
 _css_t = """var link = document.createElement("link");
 	link.ref = "stylesheet";
 	link.type = "text/css";
 	link.href = "%s";
 	document.head.appendChild(link);
 """
 
 _lib_t1 = """new Promise(function(resolve, reject) {
 	var script = document.createElement("script");
 	script.onload = resolve;
 	script.onerror = reject;
 	script.src = "%s";
 	document.head.appendChild(script);
 }).then(() => {
 """
 
 _lib_t2 = """
 });"""
 
 class GeoJSON(JSON):
     """GeoJSON expects JSON-able dict
 
     not an already-serialized JSON string.
 
     Scalar types (None, number, string) are not allowed, only dict containers.
     """
 
     def __init__(self, *args, **kwargs):
         """Create a GeoJSON display object given raw data.
 
         Parameters
         ----------
         data : dict or list
             VegaLite data. Not an already-serialized JSON string.
             Scalar types (None, number, string) are not allowed, only dict
             or list containers.
         url_template : string
             Leaflet TileLayer URL template: http://leafletjs.com/reference.html#url-template
         layer_options : dict
             Leaflet TileLayer options: http://leafletjs.com/reference.html#tilelayer-options
         url : unicode
             A URL to download the data from.
         filename : unicode
             Path to a local file to load the data from.
         metadata : dict
             Specify extra metadata to attach to the json display object.
 
         Examples
         --------
         The following will display an interactive map of Mars with a point of
         interest on frontend that do support GeoJSON display.
 
             >>> from IPython.display import GeoJSON
 
             >>> GeoJSON(data={
             ...     "type": "Feature",
             ...     "geometry": {
             ...         "type": "Point",
             ...         "coordinates": [-81.327, 296.038]
             ...     }
             ... },
             ... url_template="http://s3-eu-west-1.amazonaws.com/whereonmars.cartodb.net/{basemap_id}/{z}/{x}/{y}.png",
             ... layer_options={
             ...     "basemap_id": "celestia_mars-shaded-16k_global",
             ...     "attribution" : "Celestia/praesepe",
             ...     "minZoom" : 0,
             ...     "maxZoom" : 18,
             ... })
             <IPython.core.display.GeoJSON object>
 
         In the terminal IPython, you will only see the text representation of
         the GeoJSON object.
 
         """
 
         super(GeoJSON, self).__init__(*args, **kwargs)
 
 
     def _ipython_display_(self):
         bundle = {
             'application/geo+json': self.data,
             'text/plain': '<IPython.display.GeoJSON object>'
         }
         metadata = {
             'application/geo+json': self.metadata
         }
         display_functions.display(bundle, metadata=metadata, raw=True)
 
 class Javascript(TextDisplayObject):
 
     def __init__(self, data=None, url=None, filename=None, lib=None, css=None):
         """Create a Javascript display object given raw data.
 
         When this object is returned by an expression or passed to the
         display function, it will result in the data being displayed
         in the frontend. If the data is a URL, the data will first be
         downloaded and then displayed.
 
         In the Notebook, the containing element will be available as `element`,
         and jQuery will be available.  Content appended to `element` will be
         visible in the output area.
 
         Parameters
         ----------
         data : unicode, str or bytes
             The Javascript source code or a URL to download it from.
         url : unicode
             A URL to download the data from.
         filename : unicode
             Path to a local file to load the data from.
         lib : list or str
             A sequence of Javascript library URLs to load asynchronously before
             running the source code. The full URLs of the libraries should
             be given. A single Javascript library URL can also be given as a
             string.
         css : list or str
             A sequence of css files to load before running the source code.
             The full URLs of the css files should be given. A single css URL
             can also be given as a string.
         """
         if isinstance(lib, str):
             lib = [lib]
         elif lib is None:
             lib = []
         if isinstance(css, str):
             css = [css]
         elif css is None:
             css = []
         if not isinstance(lib, (list,tuple)):
             raise TypeError('expected sequence, got: %r' % lib)
         if not isinstance(css, (list,tuple)):
             raise TypeError('expected sequence, got: %r' % css)
         self.lib = lib
         self.css = css
         super(Javascript, self).__init__(data=data, url=url, filename=filename)
 
     def _repr_javascript_(self):
         r = ''
         for c in self.css:
             r += _css_t % c
         for l in self.lib:
             r += _lib_t1 % l
         r += self.data
         r += _lib_t2*len(self.lib)
         return r
 
 # constants for identifying png/jpeg data
 _PNG = b'\x89PNG\r\n\x1a\n'
 _JPEG = b'\xff\xd8'
 
 def _pngxy(data):
     """read the (width, height) from a PNG header"""
     ihdr = data.index(b'IHDR')
     # next 8 bytes are width/height
     return struct.unpack('>ii', data[ihdr+4:ihdr+12])
 
 def _jpegxy(data):
     """read the (width, height) from a JPEG header"""
     # adapted from http://www.64lines.com/jpeg-width-height
 
     idx = 4
     while True:
         block_size = struct.unpack('>H', data[idx:idx+2])[0]
         idx = idx + block_size
         if data[idx:idx+2] == b'\xFF\xC0':
             # found Start of Frame
             iSOF = idx
             break
         else:
             # read another block
             idx += 2
 
     h, w = struct.unpack('>HH', data[iSOF+5:iSOF+9])
     return w, h
 
 def _gifxy(data):
     """read the (width, height) from a GIF header"""
     return struct.unpack('<HH', data[6:10])
 
 
 class Image(DisplayObject):
 
     _read_flags = 'rb'
     _FMT_JPEG = u'jpeg'
     _FMT_PNG = u'png'
     _FMT_GIF = u'gif'
     _ACCEPTABLE_EMBEDDINGS = [_FMT_JPEG, _FMT_PNG, _FMT_GIF]
     _MIMETYPES = {
         _FMT_PNG: 'image/png',
         _FMT_JPEG: 'image/jpeg',
         _FMT_GIF: 'image/gif',
     }
 
     def __init__(
         self,
         data=None,
         url=None,
         filename=None,
         format=None,
         embed=None,
         width=None,
         height=None,
         retina=False,
         unconfined=False,
         metadata=None,
         alt=None,
     ):
         """Create a PNG/JPEG/GIF image object given raw data.
 
         When this object is returned by an input cell or passed to the
         display function, it will result in the image being displayed
         in the frontend.
 
         Parameters
         ----------
         data : unicode, str or bytes
             The raw image data or a URL or filename to load the data from.
             This always results in embedded image data.
 
         url : unicode
             A URL to download the data from. If you specify `url=`,
             the image data will not be embedded unless you also specify `embed=True`.
 
         filename : unicode
             Path to a local file to load the data from.
             Images from a file are always embedded.
 
         format : unicode
             The format of the image data (png/jpeg/jpg/gif). If a filename or URL is given
             for format will be inferred from the filename extension.
 
         embed : bool
             Should the image data be embedded using a data URI (True) or be
             loaded using an <img> tag. Set this to True if you want the image
             to be viewable later with no internet connection in the notebook.
 
             Default is `True`, unless the keyword argument `url` is set, then
             default value is `False`.
 
             Note that QtConsole is not able to display images if `embed` is set to `False`
 
         width : int
             Width in pixels to which to constrain the image in html
 
         height : int
             Height in pixels to which to constrain the image in html
 
         retina : bool
             Automatically set the width and height to half of the measured
             width and height.
             This only works for embedded images because it reads the width/height
             from image data.
             For non-embedded images, you can just set the desired display width
             and height directly.
 
         unconfined : bool
             Set unconfined=True to disable max-width confinement of the image.
 
         metadata : dict
             Specify extra metadata to attach to the image.
 
         alt : unicode
             Alternative text for the image, for use by screen readers.
 
         Examples
         --------
         embedded image data, works in qtconsole and notebook
         when passed positionally, the first arg can be any of raw image data,
         a URL, or a filename from which to load image data.
         The result is always embedding image data for inline images.
 
-        >>> Image('http://www.google.fr/images/srpr/logo3w.png')
+        >>> Image('https://www.google.fr/images/srpr/logo3w.png') # doctest: +SKIP
         <IPython.core.display.Image object>
 
         >>> Image('/path/to/image.jpg')
         <IPython.core.display.Image object>
 
         >>> Image(b'RAW_PNG_DATA...')
         <IPython.core.display.Image object>
 
         Specifying Image(url=...) does not embed the image data,
         it only generates ``<img>`` tag with a link to the source.
         This will not work in the qtconsole or offline.
 
-        >>> Image(url='http://www.google.fr/images/srpr/logo3w.png')
+        >>> Image(url='https://www.google.fr/images/srpr/logo3w.png')
         <IPython.core.display.Image object>
 
         """
         if isinstance(data, (Path, PurePath)):
             data = str(data)
 
         if filename is not None:
             ext = self._find_ext(filename)
         elif url is not None:
             ext = self._find_ext(url)
         elif data is None:
             raise ValueError("No image data found. Expecting filename, url, or data.")
         elif isinstance(data, str) and (
             data.startswith('http') or _safe_exists(data)
         ):
             ext = self._find_ext(data)
         else:
             ext = None
 
         if format is None:
             if ext is not None:
                 if ext == u'jpg' or ext == u'jpeg':
                     format = self._FMT_JPEG
                 elif ext == u'png':
                     format = self._FMT_PNG
                 elif ext == u'gif':
                     format = self._FMT_GIF
                 else:
                     format = ext.lower()
             elif isinstance(data, bytes):
                 # infer image type from image data header,
                 # only if format has not been specified.
                 if data[:2] == _JPEG:
                     format = self._FMT_JPEG
 
         # failed to detect format, default png
         if format is None:
             format = self._FMT_PNG
 
         if format.lower() == 'jpg':
             # jpg->jpeg
             format = self._FMT_JPEG
 
         self.format = format.lower()
         self.embed = embed if embed is not None else (url is None)
 
         if self.embed and self.format not in self._ACCEPTABLE_EMBEDDINGS:
             raise ValueError("Cannot embed the '%s' image format" % (self.format))
         if self.embed:
             self._mimetype = self._MIMETYPES.get(self.format)
 
         self.width = width
         self.height = height
         self.retina = retina
         self.unconfined = unconfined
         self.alt = alt
         super(Image, self).__init__(data=data, url=url, filename=filename,
                 metadata=metadata)
 
         if self.width is None and self.metadata.get('width', {}):
             self.width = metadata['width']
 
         if self.height is None and self.metadata.get('height', {}):
             self.height = metadata['height']
 
         if self.alt is None and self.metadata.get("alt", {}):
             self.alt = metadata["alt"]
 
         if retina:
             self._retina_shape()
 
 
     def _retina_shape(self):
         """load pixel-doubled width and height from image data"""
         if not self.embed:
             return
         if self.format == self._FMT_PNG:
             w, h = _pngxy(self.data)
         elif self.format == self._FMT_JPEG:
             w, h = _jpegxy(self.data)
         elif self.format == self._FMT_GIF:
             w, h = _gifxy(self.data)
         else:
             # retina only supports png
             return
         self.width = w // 2
         self.height = h // 2
 
     def reload(self):
         """Reload the raw data from file or URL."""
         if self.embed:
             super(Image,self).reload()
             if self.retina:
                 self._retina_shape()
 
     def _repr_html_(self):
         if not self.embed:
             width = height = klass = alt = ""
             if self.width:
                 width = ' width="%d"' % self.width
             if self.height:
                 height = ' height="%d"' % self.height
             if self.unconfined:
                 klass = ' class="unconfined"'
             if self.alt:
                 alt = ' alt="%s"' % html.escape(self.alt)
             return '<img src="{url}"{width}{height}{klass}{alt}/>'.format(
                 url=self.url,
                 width=width,
                 height=height,
                 klass=klass,
                 alt=alt,
             )
 
     def _repr_mimebundle_(self, include=None, exclude=None):
         """Return the image as a mimebundle
 
         Any new mimetype support should be implemented here.
         """
         if self.embed:
             mimetype = self._mimetype
             data, metadata = self._data_and_metadata(always_both=True)
             if metadata:
                 metadata = {mimetype: metadata}
             return {mimetype: data}, metadata
         else:
             return {'text/html': self._repr_html_()}
 
     def _data_and_metadata(self, always_both=False):
         """shortcut for returning metadata with shape information, if defined"""
         try:
             b64_data = b2a_base64(self.data).decode('ascii')
         except TypeError as e:
             raise FileNotFoundError(
                 "No such file or directory: '%s'" % (self.data)) from e
         md = {}
         if self.metadata:
             md.update(self.metadata)
         if self.width:
             md['width'] = self.width
         if self.height:
             md['height'] = self.height
         if self.unconfined:
             md['unconfined'] = self.unconfined
         if self.alt:
             md["alt"] = self.alt
         if md or always_both:
             return b64_data, md
         else:
             return b64_data
 
     def _repr_png_(self):
         if self.embed and self.format == self._FMT_PNG:
             return self._data_and_metadata()
 
     def _repr_jpeg_(self):
         if self.embed and self.format == self._FMT_JPEG:
             return self._data_and_metadata()
 
     def _find_ext(self, s):
         base, ext = splitext(s)
 
         if not ext:
             return base
 
         # `splitext` includes leading period, so we skip it
         return ext[1:].lower()
 
 
 class Video(DisplayObject):
 
     def __init__(self, data=None, url=None, filename=None, embed=False,
                  mimetype=None, width=None, height=None, html_attributes="controls"):
         """Create a video object given raw data or an URL.
 
         When this object is returned by an input cell or passed to the
         display function, it will result in the video being displayed
         in the frontend.
 
         Parameters
         ----------
         data : unicode, str or bytes
             The raw video data or a URL or filename to load the data from.
             Raw data will require passing ``embed=True``.
 
         url : unicode
             A URL for the video. If you specify ``url=``,
             the image data will not be embedded.
 
         filename : unicode
             Path to a local file containing the video.
             Will be interpreted as a local URL unless ``embed=True``.
 
         embed : bool
             Should the video be embedded using a data URI (True) or be
             loaded using a <video> tag (False).
 
             Since videos are large, embedding them should be avoided, if possible.
             You must confirm embedding as your intention by passing ``embed=True``.
 
             Local files can be displayed with URLs without embedding the content, via::
 
                 Video('./video.mp4')
 
         mimetype : unicode
             Specify the mimetype for embedded videos.
             Default will be guessed from file extension, if available.
 
         width : int
             Width in pixels to which to constrain the video in HTML.
             If not supplied, defaults to the width of the video.
 
         height : int
             Height in pixels to which to constrain the video in html.
             If not supplied, defaults to the height of the video.
 
         html_attributes : str
             Attributes for the HTML ``<video>`` block.
             Default: ``"controls"`` to get video controls.
             Other examples: ``"controls muted"`` for muted video with controls,
             ``"loop autoplay"`` for looping autoplaying video without controls.
 
         Examples
         --------
         ::
 
             Video('https://archive.org/download/Sita_Sings_the_Blues/Sita_Sings_the_Blues_small.mp4')
             Video('path/to/video.mp4')
             Video('path/to/video.mp4', embed=True)
             Video('path/to/video.mp4', embed=True, html_attributes="controls muted autoplay")
             Video(b'raw-videodata', embed=True)
         """
         if isinstance(data, (Path, PurePath)):
             data = str(data)
 
         if url is None and isinstance(data, str) and data.startswith(('http:', 'https:')):
             url = data
             data = None
         elif data is not None and os.path.exists(data):
             filename = data
             data = None
 
         if data and not embed:
             msg = ''.join([
                 "To embed videos, you must pass embed=True ",
                 "(this may make your notebook files huge)\n",
                 "Consider passing Video(url='...')",
             ])
             raise ValueError(msg)
 
         self.mimetype = mimetype
         self.embed = embed
         self.width = width
         self.height = height
         self.html_attributes = html_attributes
         super(Video, self).__init__(data=data, url=url, filename=filename)
 
     def _repr_html_(self):
         width = height = ''
         if self.width:
             width = ' width="%d"' % self.width
         if self.height:
             height = ' height="%d"' % self.height
 
         # External URLs and potentially local files are not embedded into the
         # notebook output.
         if not self.embed:
             url = self.url if self.url is not None else self.filename
             output = """<video src="{0}" {1} {2} {3}>
       Your browser does not support the <code>video</code> element.
     </video>""".format(url, self.html_attributes, width, height)
             return output
 
         # Embedded videos are base64-encoded.
         mimetype = self.mimetype
         if self.filename is not None:
             if not mimetype:
                 mimetype, _ = mimetypes.guess_type(self.filename)
 
             with open(self.filename, 'rb') as f:
                 video = f.read()
         else:
             video = self.data
         if isinstance(video, str):
             # unicode input is already b64-encoded
             b64_video = video
         else:
             b64_video = b2a_base64(video).decode('ascii').rstrip()
 
         output = """<video {0} {1} {2}>
  <source src="data:{3};base64,{4}" type="{3}">
  Your browser does not support the video tag.
  </video>""".format(self.html_attributes, width, height, mimetype, b64_video)
         return output
 
     def reload(self):
         # TODO
         pass
 
 
 @skip_doctest
 def set_matplotlib_formats(*formats, **kwargs):
     """
     .. deprecated:: 7.23
 
        use `matplotlib_inline.backend_inline.set_matplotlib_formats()`
 
     Select figure formats for the inline backend. Optionally pass quality for JPEG.
 
     For example, this enables PNG and JPEG output with a JPEG quality of 90%::
 
         In [1]: set_matplotlib_formats('png', 'jpeg', quality=90)
 
     To set this in your config files use the following::
 
         c.InlineBackend.figure_formats = {'png', 'jpeg'}
         c.InlineBackend.print_figure_kwargs.update({'quality' : 90})
 
     Parameters
     ----------
     *formats : strs
         One or more figure formats to enable: 'png', 'retina', 'jpeg', 'svg', 'pdf'.
     **kwargs
         Keyword args will be relayed to ``figure.canvas.print_figure``.
     """
     warnings.warn(
         "`set_matplotlib_formats` is deprecated since IPython 7.23, directly "
         "use `matplotlib_inline.backend_inline.set_matplotlib_formats()`",
         DeprecationWarning,
         stacklevel=2,
     )
 
     from matplotlib_inline.backend_inline import (
         set_matplotlib_formats as set_matplotlib_formats_orig,
     )
 
     set_matplotlib_formats_orig(*formats, **kwargs)
 
 @skip_doctest
 def set_matplotlib_close(close=True):
     """
     .. deprecated:: 7.23
 
         use `matplotlib_inline.backend_inline.set_matplotlib_close()`
 
     Set whether the inline backend closes all figures automatically or not.
 
     By default, the inline backend used in the IPython Notebook will close all
     matplotlib figures automatically after each cell is run. This means that
     plots in different cells won't interfere. Sometimes, you may want to make
     a plot in one cell and then refine it in later cells. This can be accomplished
     by::
 
         In [1]: set_matplotlib_close(False)
 
     To set this in your config files use the following::
 
         c.InlineBackend.close_figures = False
 
     Parameters
     ----------
     close : bool
         Should all matplotlib figures be automatically closed after each cell is
         run?
     """
     warnings.warn(
         "`set_matplotlib_close` is deprecated since IPython 7.23, directly "
         "use `matplotlib_inline.backend_inline.set_matplotlib_close()`",
         DeprecationWarning,
         stacklevel=2,
     )
 
     from matplotlib_inline.backend_inline import (
         set_matplotlib_close as set_matplotlib_close_orig,
     )
 
     set_matplotlib_close_orig(close)

IPython/core/magics/osm.py

@@ -1,854 +1,854 b''
 """Implementation of magic functions for interaction with the OS.
 
 Note: this module is named 'osm' instead of 'os' to avoid a collision with the
 builtin.
 """
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 import io
 import os
 import re
 import sys
 from pprint import pformat
 
 from IPython.core import magic_arguments
 from IPython.core import oinspect
 from IPython.core import page
 from IPython.core.alias import AliasError, Alias
 from IPython.core.error import UsageError
 from IPython.core.magic import  (
     Magics, compress_dhist, magics_class, line_magic, cell_magic, line_cell_magic
 )
 from IPython.testing.skipdoctest import skip_doctest
 from IPython.utils.openpy import source_to_unicode
 from IPython.utils.process import abbrev_cwd
 from IPython.utils.terminal import set_term_title
 from traitlets import Bool
 from warnings import warn
 
 
 @magics_class
 class OSMagics(Magics):
     """Magics to interact with the underlying OS (shell-type functionality).
     """
 
     cd_force_quiet = Bool(False,
         help="Force %cd magic to be quiet even if -q is not passed."
     ).tag(config=True)
 
     def __init__(self, shell=None, **kwargs):
 
         # Now define isexec in a cross platform manner.
         self.is_posix = False
         self.execre = None
         if os.name == 'posix':
             self.is_posix = True
         else:
             try:
                 winext = os.environ['pathext'].replace(';','|').replace('.','')
             except KeyError:
                 winext = 'exe|com|bat|py'
             try:
                 self.execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
             except re.error:
                 warn("Seems like your pathext environmental "
                      "variable is malformed. Please check it to "
                      "enable a proper handle of file extensions "
                      "managed for your system")
                 winext = 'exe|com|bat|py'
                 self.execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
 
         # call up the chain
         super().__init__(shell=shell, **kwargs)
 
 
     def _isexec_POSIX(self, file):
         """
         Test for executable on a POSIX system
         """
         if os.access(file.path, os.X_OK):
             # will fail on maxOS if access is not X_OK
             return file.is_file()
         return False
 
 
     
     def _isexec_WIN(self, file):
         """
         Test for executable file on non POSIX system
         """
         return file.is_file() and self.execre.match(file.name) is not None
 
     def isexec(self, file):
         """
         Test for executable file on non POSIX system
         """
         if self.is_posix:
             return self._isexec_POSIX(file)
         else:
             return self._isexec_WIN(file)
 
 
     @skip_doctest
     @line_magic
     def alias(self, parameter_s=''):
         """Define an alias for a system command.
 
         '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
 
         Then, typing 'alias_name params' will execute the system command 'cmd
         params' (from your underlying operating system).
 
         Aliases have lower precedence than magic functions and Python normal
         variables, so if 'foo' is both a Python variable and an alias, the
         alias can not be executed until 'del foo' removes the Python variable.
 
         You can use the %l specifier in an alias definition to represent the
         whole line when the alias is called.  For example::
 
           In [2]: alias bracket echo "Input in brackets: <%l>"
           In [3]: bracket hello world
           Input in brackets: <hello world>
 
         You can also define aliases with parameters using %s specifiers (one
         per parameter)::
 
           In [1]: alias parts echo first %s second %s
           In [2]: %parts A B
           first A second B
           In [3]: %parts A
           Incorrect number of arguments: 2 expected.
           parts is an alias to: 'echo first %s second %s'
 
         Note that %l and %s are mutually exclusive.  You can only use one or
         the other in your aliases.
 
         Aliases expand Python variables just like system calls using ! or !!
         do: all expressions prefixed with '$' get expanded.  For details of
         the semantic rules, see PEP-215:
-        http://www.python.org/peps/pep-0215.html.  This is the library used by
+        https://www.python.org/dev/peps/pep-0215/.  This is the library used by
         IPython for variable expansion.  If you want to access a true shell
         variable, an extra $ is necessary to prevent its expansion by
         IPython::
 
           In [6]: alias show echo
           In [7]: PATH='A Python string'
           In [8]: show $PATH
           A Python string
           In [9]: show $$PATH
           /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
 
         You can use the alias facility to access all of $PATH.  See the %rehashx
         function, which automatically creates aliases for the contents of your
         $PATH.
 
         If called with no parameters, %alias prints the current alias table
         for your system.  For posix systems, the default aliases are 'cat',
         'cp', 'mv', 'rm', 'rmdir', and 'mkdir', and other platform-specific
         aliases are added.  For windows-based systems, the default aliases are
         'copy', 'ddir', 'echo', 'ls', 'ldir', 'mkdir', 'ren', and 'rmdir'.
 
         You can see the definition of alias by adding a question mark in the
         end::
 
           In [1]: cat?
           Repr: <alias cat for 'cat'>"""
 
         par = parameter_s.strip()
         if not par:
             aliases = sorted(self.shell.alias_manager.aliases)
             # stored = self.shell.db.get('stored_aliases', {} )
             # for k, v in stored:
             #     atab.append(k, v[0])
 
             print("Total number of aliases:", len(aliases))
             sys.stdout.flush()
             return aliases
 
         # Now try to define a new one
         try:
             alias,cmd = par.split(None, 1)
         except TypeError:
             print(oinspect.getdoc(self.alias))
             return
         
         try:
             self.shell.alias_manager.define_alias(alias, cmd)
         except AliasError as e:
             print(e)
     # end magic_alias
 
     @line_magic
     def unalias(self, parameter_s=''):
         """Remove an alias"""
 
         aname = parameter_s.strip()
         try:
             self.shell.alias_manager.undefine_alias(aname)
         except ValueError as e:
             print(e)
             return
         
         stored = self.shell.db.get('stored_aliases', {} )
         if aname in stored:
             print("Removing %stored alias",aname)
             del stored[aname]
             self.shell.db['stored_aliases'] = stored
 
     @line_magic
     def rehashx(self, parameter_s=''):
         """Update the alias table with all executable files in $PATH.
 
         rehashx explicitly checks that every entry in $PATH is a file
         with execute access (os.X_OK).
 
         Under Windows, it checks executability as a match against a
         '|'-separated string of extensions, stored in the IPython config
         variable win_exec_ext.  This defaults to 'exe|com|bat'.
 
         This function also resets the root module cache of module completer,
         used on slow filesystems.
         """
         from IPython.core.alias import InvalidAliasError
 
         # for the benefit of module completer in ipy_completers.py
         del self.shell.db['rootmodules_cache']
 
         path = [os.path.abspath(os.path.expanduser(p)) for p in
             os.environ.get('PATH','').split(os.pathsep)]
 
         syscmdlist = []
         savedir = os.getcwd()
 
         # Now walk the paths looking for executables to alias.
         try:
             # write the whole loop for posix/Windows so we don't have an if in
             # the innermost part
             if self.is_posix:
                 for pdir in path:
                     try:
                         os.chdir(pdir)
                     except OSError:
                         continue
 
                     # for python 3.6+ rewrite to: with os.scandir(pdir) as dirlist:
                     dirlist = os.scandir(path=pdir)
                     for ff in dirlist:
                         if self.isexec(ff):
                             fname = ff.name
                             try:
                                 # Removes dots from the name since ipython
                                 # will assume names with dots to be python.
                                 if not self.shell.alias_manager.is_alias(fname):
                                     self.shell.alias_manager.define_alias(
                                         fname.replace('.',''), fname)
                             except InvalidAliasError:
                                 pass
                             else:
                                 syscmdlist.append(fname)
             else:
                 no_alias = Alias.blacklist
                 for pdir in path:
                     try:
                         os.chdir(pdir)
                     except OSError:
                         continue
 
                     # for python 3.6+ rewrite to: with os.scandir(pdir) as dirlist:
                     dirlist = os.scandir(pdir)
                     for ff in dirlist:
                         fname = ff.name
                         base, ext = os.path.splitext(fname)
                         if self.isexec(ff) and base.lower() not in no_alias:
                             if ext.lower() == '.exe':
                                 fname = base
                                 try:
                                     # Removes dots from the name since ipython
                                     # will assume names with dots to be python.
                                     self.shell.alias_manager.define_alias(
                                         base.lower().replace('.',''), fname)
                                 except InvalidAliasError:
                                     pass
                                 syscmdlist.append(fname)
 
             self.shell.db['syscmdlist'] = syscmdlist
         finally:
             os.chdir(savedir)
 
     @skip_doctest
     @line_magic
     def pwd(self, parameter_s=''):
         """Return the current working directory path.
 
         Examples
         --------
         ::
 
           In [9]: pwd
           Out[9]: '/home/tsuser/sprint/ipython'
         """
         try:
             return os.getcwd()
         except FileNotFoundError as e:
             raise UsageError("CWD no longer exists - please use %cd to change directory.") from e
 
     @skip_doctest
     @line_magic
     def cd(self, parameter_s=''):
         """Change the current working directory.
 
         This command automatically maintains an internal list of directories
         you visit during your IPython session, in the variable ``_dh``. The
         command :magic:`%dhist` shows this history nicely formatted. You can
         also do ``cd -<tab>`` to see directory history conveniently.
         Usage:
 
           - ``cd 'dir'``: changes to directory 'dir'.
           - ``cd -``: changes to the last visited directory.
           - ``cd -<n>``: changes to the n-th directory in the directory history.
           - ``cd --foo``: change to directory that matches 'foo' in history
           - ``cd -b <bookmark_name>``: jump to a bookmark set by %bookmark
           - Hitting a tab key after ``cd -b`` allows you to tab-complete
             bookmark names.
 
           .. note::
             ``cd <bookmark_name>`` is enough if there is no directory
             ``<bookmark_name>``, but a bookmark with the name exists.
 
         Options:
 
         -q               Be quiet. Do not print the working directory after the
                          cd command is executed. By default IPython's cd
                          command does print this directory, since the default
                          prompts do not display path information.
 
         .. note::
            Note that ``!cd`` doesn't work for this purpose because the shell
            where ``!command`` runs is immediately discarded after executing
            'command'.
 
         Examples
         --------
         ::
 
           In [10]: cd parent/child
           /home/tsuser/parent/child
         """
 
         try:
             oldcwd = os.getcwd()
         except FileNotFoundError:
             # Happens if the CWD has been deleted.
             oldcwd = None
 
         numcd = re.match(r'(-)(\d+)$',parameter_s)
         # jump in directory history by number
         if numcd:
             nn = int(numcd.group(2))
             try:
                 ps = self.shell.user_ns['_dh'][nn]
             except IndexError:
                 print('The requested directory does not exist in history.')
                 return
             else:
                 opts = {}
         elif parameter_s.startswith('--'):
             ps = None
             fallback = None
             pat = parameter_s[2:]
             dh = self.shell.user_ns['_dh']
             # first search only by basename (last component)
             for ent in reversed(dh):
                 if pat in os.path.basename(ent) and os.path.isdir(ent):
                     ps = ent
                     break
 
                 if fallback is None and pat in ent and os.path.isdir(ent):
                     fallback = ent
 
             # if we have no last part match, pick the first full path match
             if ps is None:
                 ps = fallback
 
             if ps is None:
                 print("No matching entry in directory history")
                 return
             else:
                 opts = {}
 
 
         else:
             opts, ps = self.parse_options(parameter_s, 'qb', mode='string')
         # jump to previous
         if ps == '-':
             try:
                 ps = self.shell.user_ns['_dh'][-2]
             except IndexError as e:
                 raise UsageError('%cd -: No previous directory to change to.') from e
         # jump to bookmark if needed
         else:
             if not os.path.isdir(ps) or 'b' in opts:
                 bkms = self.shell.db.get('bookmarks', {})
 
                 if ps in bkms:
                     target = bkms[ps]
                     print('(bookmark:%s) -> %s' % (ps, target))
                     ps = target
                 else:
                     if 'b' in opts:
                         raise UsageError("Bookmark '%s' not found.  "
                               "Use '%%bookmark -l' to see your bookmarks." % ps)
 
         # at this point ps should point to the target dir
         if ps:
             try:
                 os.chdir(os.path.expanduser(ps))
                 if hasattr(self.shell, 'term_title') and self.shell.term_title:
                     set_term_title(self.shell.term_title_format.format(cwd=abbrev_cwd()))
             except OSError:
                 print(sys.exc_info()[1])
             else:
                 cwd = os.getcwd()
                 dhist = self.shell.user_ns['_dh']
                 if oldcwd != cwd:
                     dhist.append(cwd)
                     self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
 
         else:
             os.chdir(self.shell.home_dir)
             if hasattr(self.shell, 'term_title') and self.shell.term_title:
                 set_term_title(self.shell.term_title_format.format(cwd="~"))
             cwd = os.getcwd()
             dhist = self.shell.user_ns['_dh']
 
             if oldcwd != cwd:
                 dhist.append(cwd)
                 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
         if not 'q' in opts and not self.cd_force_quiet and self.shell.user_ns['_dh']:
             print(self.shell.user_ns['_dh'][-1])
 
     @line_magic
     def env(self, parameter_s=''):
         """Get, set, or list environment variables.
 
         Usage:\\
 
           :``%env``: lists all environment variables/values
           :``%env var``: get value for var
           :``%env var val``: set value for var
           :``%env var=val``: set value for var
           :``%env var=$val``: set value for var, using python expansion if possible
         """
         if parameter_s.strip():
             split = '=' if '=' in parameter_s else ' '
             bits = parameter_s.split(split)
             if len(bits) == 1:
                 key = parameter_s.strip()
                 if key in os.environ:
                     return os.environ[key]
                 else:
                     err = "Environment does not have key: {0}".format(key)
                     raise UsageError(err)
             if len(bits) > 1:
                 return self.set_env(parameter_s)
         env = dict(os.environ)
         # hide likely secrets when printing the whole environment
         for key in list(env):
             if any(s in key.lower() for s in ('key', 'token', 'secret')):
                 env[key] = '<hidden>'
 
         return env
 
     @line_magic
     def set_env(self, parameter_s):
         """Set environment variables.  Assumptions are that either "val" is a
         name in the user namespace, or val is something that evaluates to a
         string.
 
         Usage:\\
           %set_env var val: set value for var
           %set_env var=val: set value for var
           %set_env var=$val: set value for var, using python expansion if possible
         """
         split = '=' if '=' in parameter_s else ' '
         bits = parameter_s.split(split, 1)
         if not parameter_s.strip() or len(bits)<2:
             raise UsageError("usage is 'set_env var=val'")
         var = bits[0].strip()
         val = bits[1].strip()
         if re.match(r'.*\s.*', var):
             # an environment variable with whitespace is almost certainly
             # not what the user intended.  what's more likely is the wrong
             # split was chosen, ie for "set_env cmd_args A=B", we chose
             # '=' for the split and should have chosen ' '.  to get around
             # this, users should just assign directly to os.environ or use
             # standard magic {var} expansion.
             err = "refusing to set env var with whitespace: '{0}'"
             err = err.format(val)
             raise UsageError(err)
         os.environ[var] = val
         print('env: {0}={1}'.format(var,val))
 
     @line_magic
     def pushd(self, parameter_s=''):
         """Place the current dir on stack and change directory.
 
         Usage:\\
           %pushd ['dirname']
         """
 
         dir_s = self.shell.dir_stack
         tgt = os.path.expanduser(parameter_s)
         cwd = os.getcwd().replace(self.shell.home_dir,'~')
         if tgt:
             self.cd(parameter_s)
         dir_s.insert(0,cwd)
         return self.shell.run_line_magic('dirs', '')
 
     @line_magic
     def popd(self, parameter_s=''):
         """Change to directory popped off the top of the stack.
         """
         if not self.shell.dir_stack:
             raise UsageError("%popd on empty stack")
         top = self.shell.dir_stack.pop(0)
         self.cd(top)
         print("popd ->",top)
 
     @line_magic
     def dirs(self, parameter_s=''):
         """Return the current directory stack."""
 
         return self.shell.dir_stack
 
     @line_magic
     def dhist(self, parameter_s=''):
         """Print your history of visited directories.
 
         %dhist       -> print full history\\
         %dhist n     -> print last n entries only\\
         %dhist n1 n2 -> print entries between n1 and n2 (n2 not included)\\
 
         This history is automatically maintained by the %cd command, and
         always available as the global list variable _dh. You can use %cd -<n>
         to go to directory number <n>.
 
         Note that most of time, you should view directory history by entering
         cd -<TAB>.
 
         """
 
         dh = self.shell.user_ns['_dh']
         if parameter_s:
             try:
                 args = map(int,parameter_s.split())
             except:
                 self.arg_err(self.dhist)
                 return
             if len(args) == 1:
                 ini,fin = max(len(dh)-(args[0]),0),len(dh)
             elif len(args) == 2:
                 ini,fin = args
                 fin = min(fin, len(dh))
             else:
                 self.arg_err(self.dhist)
                 return
         else:
             ini,fin = 0,len(dh)
         print('Directory history (kept in _dh)')
         for i in range(ini, fin):
             print("%d: %s" % (i, dh[i]))
 
     @skip_doctest
     @line_magic
     def sc(self, parameter_s=''):
         """Shell capture - run shell command and capture output (DEPRECATED use !).
 
         DEPRECATED. Suboptimal, retained for backwards compatibility.
 
         You should use the form 'var = !command' instead. Example:
 
          "%sc -l myfiles = ls ~" should now be written as
 
          "myfiles = !ls ~"
 
         myfiles.s, myfiles.l and myfiles.n still apply as documented
         below.
 
         --
         %sc [options] varname=command
 
         IPython will run the given command using commands.getoutput(), and
         will then update the user's interactive namespace with a variable
         called varname, containing the value of the call.  Your command can
         contain shell wildcards, pipes, etc.
 
         The '=' sign in the syntax is mandatory, and the variable name you
         supply must follow Python's standard conventions for valid names.
 
         (A special format without variable name exists for internal use)
 
         Options:
 
           -l: list output.  Split the output on newlines into a list before
           assigning it to the given variable.  By default the output is stored
           as a single string.
 
           -v: verbose.  Print the contents of the variable.
 
         In most cases you should not need to split as a list, because the
         returned value is a special type of string which can automatically
         provide its contents either as a list (split on newlines) or as a
         space-separated string.  These are convenient, respectively, either
         for sequential processing or to be passed to a shell command.
 
         For example::
 
             # Capture into variable a
             In [1]: sc a=ls *py
 
             # a is a string with embedded newlines
             In [2]: a
             Out[2]: 'setup.py\\nwin32_manual_post_install.py'
 
             # which can be seen as a list:
             In [3]: a.l
             Out[3]: ['setup.py', 'win32_manual_post_install.py']
 
             # or as a whitespace-separated string:
             In [4]: a.s
             Out[4]: 'setup.py win32_manual_post_install.py'
 
             # a.s is useful to pass as a single command line:
             In [5]: !wc -l $a.s
               146 setup.py
               130 win32_manual_post_install.py
               276 total
 
             # while the list form is useful to loop over:
             In [6]: for f in a.l:
                ...:      !wc -l $f
                ...:
             146 setup.py
             130 win32_manual_post_install.py
 
         Similarly, the lists returned by the -l option are also special, in
         the sense that you can equally invoke the .s attribute on them to
         automatically get a whitespace-separated string from their contents::
 
             In [7]: sc -l b=ls *py
 
             In [8]: b
             Out[8]: ['setup.py', 'win32_manual_post_install.py']
 
             In [9]: b.s
             Out[9]: 'setup.py win32_manual_post_install.py'
 
         In summary, both the lists and strings used for output capture have
         the following special attributes::
 
             .l (or .list) : value as list.
             .n (or .nlstr): value as newline-separated string.
             .s (or .spstr): value as space-separated string.
         """
 
         opts,args = self.parse_options(parameter_s, 'lv')
         # Try to get a variable name and command to run
         try:
             # the variable name must be obtained from the parse_options
             # output, which uses shlex.split to strip options out.
             var,_ = args.split('=', 1)
             var = var.strip()
             # But the command has to be extracted from the original input
             # parameter_s, not on what parse_options returns, to avoid the
             # quote stripping which shlex.split performs on it.
             _,cmd = parameter_s.split('=', 1)
         except ValueError:
             var,cmd = '',''
         # If all looks ok, proceed
         split = 'l' in opts
         out = self.shell.getoutput(cmd, split=split)
         if 'v' in opts:
             print('%s ==\n%s' % (var, pformat(out)))
         if var:
             self.shell.user_ns.update({var:out})
         else:
             return out
 
     @line_cell_magic
     def sx(self, line='', cell=None):
         """Shell execute - run shell command and capture output (!! is short-hand).
 
         %sx command
 
         IPython will run the given command using commands.getoutput(), and
         return the result formatted as a list (split on '\\n').  Since the
         output is _returned_, it will be stored in ipython's regular output
         cache Out[N] and in the '_N' automatic variables.
 
         Notes:
 
         1) If an input line begins with '!!', then %sx is automatically
         invoked.  That is, while::
 
           !ls
 
         causes ipython to simply issue system('ls'), typing::
 
           !!ls
 
         is a shorthand equivalent to::
 
           %sx ls
 
         2) %sx differs from %sc in that %sx automatically splits into a list,
         like '%sc -l'.  The reason for this is to make it as easy as possible
         to process line-oriented shell output via further python commands.
         %sc is meant to provide much finer control, but requires more
         typing.
 
         3) Just like %sc -l, this is a list with special attributes:
         ::
 
           .l (or .list) : value as list.
           .n (or .nlstr): value as newline-separated string.
           .s (or .spstr): value as whitespace-separated string.
 
         This is very useful when trying to use such lists as arguments to
         system commands."""
         
         if cell is None:
             # line magic
             return self.shell.getoutput(line)
         else:
             opts,args = self.parse_options(line, '', 'out=')
             output = self.shell.getoutput(cell)
             out_name = opts.get('out', opts.get('o'))
             if out_name:
                 self.shell.user_ns[out_name] = output
             else:
                 return output
 
     system = line_cell_magic('system')(sx)
     bang = cell_magic('!')(sx)
 
     @line_magic
     def bookmark(self, parameter_s=''):
         """Manage IPython's bookmark system.
 
         %bookmark <name>       - set bookmark to current dir
         %bookmark <name> <dir> - set bookmark to <dir>
         %bookmark -l           - list all bookmarks
         %bookmark -d <name>    - remove bookmark
         %bookmark -r           - remove all bookmarks
 
         You can later on access a bookmarked folder with::
 
           %cd -b <name>
 
         or simply '%cd <name>' if there is no directory called <name> AND
         there is such a bookmark defined.
 
         Your bookmarks persist through IPython sessions, but they are
         associated with each profile."""
 
         opts,args = self.parse_options(parameter_s,'drl',mode='list')
         if len(args) > 2:
             raise UsageError("%bookmark: too many arguments")
 
         bkms = self.shell.db.get('bookmarks',{})
 
         if 'd' in opts:
             try:
                 todel = args[0]
             except IndexError as e:
                 raise UsageError(
                     "%bookmark -d: must provide a bookmark to delete") from e
             else:
                 try:
                     del bkms[todel]
                 except KeyError as e:
                     raise UsageError(
                         "%%bookmark -d: Can't delete bookmark '%s'" % todel) from e
 
         elif 'r' in opts:
             bkms = {}
         elif 'l' in opts:
             bks = sorted(bkms)
             if bks:
                 size = max(map(len, bks))
             else:
                 size = 0
             fmt = '%-'+str(size)+'s -> %s'
             print('Current bookmarks:')
             for bk in bks:
                 print(fmt % (bk, bkms[bk]))
         else:
             if not args:
                 raise UsageError("%bookmark: You must specify the bookmark name")
             elif len(args)==1:
                 bkms[args[0]] = os.getcwd()
             elif len(args)==2:
                 bkms[args[0]] = args[1]
         self.shell.db['bookmarks'] = bkms
 
     @line_magic
     def pycat(self, parameter_s=''):
         """Show a syntax-highlighted file through a pager.
 
         This magic is similar to the cat utility, but it will assume the file
         to be Python source and will show it with syntax highlighting.
 
         This magic command can either take a local filename, an url,
         an history range (see %history) or a macro as argument.
 
         If no parameter is given, prints out history of current session up to
         this point. ::
 
         %pycat myscript.py
         %pycat 7-27
         %pycat myMacro
         %pycat http://www.example.com/myscript.py
         """
         try:
             cont = self.shell.find_user_code(parameter_s, skip_encoding_cookie=False)
         except (ValueError, IOError):
             print("Error: no such file, variable, URL, history range or macro")
             return
 
         page.page(self.shell.pycolorize(source_to_unicode(cont)))
 
     @magic_arguments.magic_arguments()
     @magic_arguments.argument(
         '-a', '--append', action='store_true', default=False,
         help='Append contents of the cell to an existing file. '
              'The file will be created if it does not exist.'
     )
     @magic_arguments.argument(
         'filename', type=str,
         help='file to write'
     )
     @cell_magic
     def writefile(self, line, cell):
         """Write the contents of the cell to a file.
 
         The file will be overwritten unless the -a (--append) flag is specified.
         """
         args = magic_arguments.parse_argstring(self.writefile, line)
         if re.match(r'^(\'.*\')|(".*")$', args.filename):
             filename = os.path.expanduser(args.filename[1:-1])
         else:
             filename = os.path.expanduser(args.filename)
             
         if os.path.exists(filename):
             if args.append:
                 print("Appending to %s" % filename)
             else:
                 print("Overwriting %s" % filename)
         else:
             print("Writing %s" % filename)
         
         mode = 'a' if args.append else 'w'
         with io.open(filename, mode, encoding='utf-8') as f:
             f.write(cell)