diff --git a/dtale/templates/dtale/popup.html b/dtale/templates/dtale/popup.html
new file mode 100644
index 00000000..0f7d41e9
--- /dev/null
+++ b/dtale/templates/dtale/popup.html
@@ -0,0 +1,15 @@
+{% extends "dtale/base.html" %}
+
+{% block title %}{{ title }}{% endblock %}
+
+{% block full_content %}
+
+
+
+{% endblock %}
+
+{% set js_file = 'dist/' + js_prefix + '_popup_bundle.js' %}
+{% block js %}
+
+{% endblock %}
diff --git a/dtale/utils.py b/dtale/utils.py
index 3853279f..5ca9258d 100644
--- a/dtale/utils.py
+++ b/dtale/utils.py
@@ -56,9 +56,9 @@ def build_shutdown_url(port):
def get_str_arg(r, name, default=None):
"""
- Retrieve argument from flask request object and convert to string
+ Retrieve argument from :attr:`flask:flask.request` and convert to string
- :param r: :meth:`flask.request`
+ :param r: :attr:`flask:flask.request`
:param name: argument name
:type: str
:param default: default value if parameter is non-existent, defaults to None
@@ -76,9 +76,9 @@ def get_str_arg(r, name, default=None):
def get_int_arg(r, name, default=None):
"""
- Retrieve argument from flask request object and convert to integer
+ Retrieve argument from :attr:`flask:flask.request` and convert to integer
- :param r: :meth:`flask.request`
+ :param r: :attr:`flask:flask.request`
:param name: argument name
:type: str
:param default: default value if parameter is non-existent, defaults to None
@@ -96,9 +96,9 @@ def get_int_arg(r, name, default=None):
def get_float_arg(r, name, default=None):
"""
- Retrieve argument from flask request object and convert to float
+ Retrieve argument from :attr:`flask:flask.request` and convert to float
- :param r: :meth:`flask.request`
+ :param r: :attr:`flask:flask.request`
:param name: argument name
:type: str
:param default: default value if parameter is non-existent, defaults to None
@@ -116,9 +116,9 @@ def get_float_arg(r, name, default=None):
def get_bool_arg(r, name):
"""
- Retrieve argument from flask request object and convert to boolean
+ Retrieve argument from :attr:`flask:flask.request` and convert to boolean
- :param r: :meth:`flask.request`
+ :param r: :attr:`flask:flask.request`
:param name: argument name
:type: str
:return: `True` if lowercase value equals 'true', `False` otherwise
@@ -131,7 +131,7 @@ def json_string(x, nan_display=''):
convert value to string to be used within JSON output
:param x: value to be converted to string
- :param nan_display: if `x` is nan then return this value
+ :param nan_display: if `x` is :attr:`numpy:numpy.nan` then return this value
:return: string value
:rtype: str
"""
@@ -145,7 +145,7 @@ def json_int(x, nan_display='', as_string=False):
Convert value to integer to be used within JSON output
:param x: value to be converted to integer
- :param nan_display: if `x` is nan then return this value
+ :param nan_display: if `x` is :attr:`numpy:numpy.nan` then return this value
:param as_string: return integer as a formatted string (EX: 1,000,000)
:return: integer value
:rtype: int
@@ -170,7 +170,7 @@ def json_float(x, precision=2, nan_display='nan', as_string=False):
:param x: value to be converted to integer
:param precision: precision of float to be returned
- :param nan_display: if `x` is nan then return this value
+ :param nan_display: if `x` is :attr:`numpy:numpy.nan` then return this value
:param as_string: return float as a formatted string (EX: 1,234.5643)
:return: float value
:rtype: float
@@ -194,7 +194,7 @@ def json_date(x, fmt='%Y-%m-%d %H:%M:%S', nan_display=''):
:param x: value to be converted to date string
:param fmt: the data string formatting to be applied
- :param nan_display: if `x` is nan then return this value
+ :param nan_display: if `x` is :attr:`numpy:numpy.nan` then return this value
:return: date string value
:rtype: str (YYYY-MM-DD)
"""
@@ -214,7 +214,7 @@ def json_timestamp(x, nan_display=''):
Convert value to timestamp (milliseconds) to be used within JSON output
:param x: value to be converted to milliseconds
- :param nan_display: if `x` is nan then return this value
+ :param nan_display: if `x` is :attr:`numpy:numpy.nan` then return this value
:return: millisecond value
:rtype: bigint
"""
@@ -280,7 +280,7 @@ def format_dicts(self, lsts):
def classify_type(type_name):
"""
- :param type_name: string label for value from :meth:`pandas.DataFrame.dtypes`
+ :param type_name: string label for value from :meth:`pandas:pandas.DataFrame.dtypes`
:return: shortened string label for dtype
S = str
B = bool
@@ -308,9 +308,9 @@ def classify_type(type_name):
def retrieve_grid_params(req, props=None):
"""
- Pull out grid parameters from :meth:`flask.request` arguments and return as a `dict`
+ Pull out grid parameters from :attr:`flask:flask.request` arguments and return as a `dict`
- :param req: :meth:`flask.request`
+ :param req: :attr:`flask:flask.request`
:param props: argument names
:type props: list
:return: dictionary of argument/value pairs
@@ -354,11 +354,11 @@ def sort_df_for_grid(df, params):
}
:param df: dataframe
- :type df: :class:`pandas.DataFrame`
- :param params: arguments from flask request
+ :type df: :class:`pandas:pandas.DataFrame`
+ :param params: arguments from :attr:`flask:flask.request`
:type params: dict
:return: sorted dataframe
- :rtype: :class:`pandas.DataFrame`
+ :rtype: :class:`pandas:pandas.DataFrame`
"""
if 'sort' in params:
cols, dirs = [], []
@@ -421,11 +421,11 @@ def filter_df_for_grid(df, params):
}
:param df: dataframe
- :type df: :class:`pandas.DataFrame`
- :param params: arguments from flask request
+ :type df: :class:`pandas:pandas.DataFrame`
+ :param params: arguments from :attr:`flask:flask.request`
:type params: dict
:return: filtering dataframe
- :rtype: :class:`pandas.DataFrame`
+ :rtype: :class:`pandas:pandas.DataFrame`
"""
data_type_info = get_dtypes(df)
for col, filter_cfg in params.get('filters', {}).items():
@@ -465,7 +465,7 @@ def filter_df_for_grid(df, params):
def get_dtypes(df):
"""
- Build dictionary of column/dtype name pairs from :class:`pandas.DataFrame`
+ Build dictionary of column/dtype name pairs from :class:`pandas:pandas.DataFrame`
"""
def _load():
for col, dtype in df.dtypes.to_dict().items():
@@ -478,7 +478,7 @@ def _load():
def grid_columns(df):
"""
- Build list of {name, dtype} dictionaries for columns in :class:`pandas.DataFrame`
+ Build list of {name, dtype} dictionaries for columns in :class:`pandas:pandas.DataFrame`
"""
data_type_info = get_dtypes(df)
return [dict(name=c, dtype=data_type_info[c]) for c in df.columns]
@@ -505,7 +505,7 @@ def find_dtype_formatter(dtype):
def grid_formatter(col_types, nan_display='', overrides=None):
"""
- Build :class:`dtale.utils.JSONFormatter` from :class:`pandas.DataFrame`
+ Build :class:`dtale.utils.JSONFormatter` from :class:`pandas:pandas.DataFrame`
"""
f = JSONFormatter(nan_display)
mappings = dict_merge(DF_MAPPINGS, overrides or {})
@@ -518,7 +518,7 @@ def grid_formatter(col_types, nan_display='', overrides=None):
def format_grid(df):
"""
- Translate :class:`pandas.DataFrame` to well-formed JSON. Structure is as follows:
+ Translate :class:`pandas:pandas.DataFrame` to well-formed JSON. Structure is as follows:
{
results: [
{col1: val1_row1,...,colN: valN_row1},
@@ -533,7 +533,7 @@ def format_grid(df):
}
:param df: dataframe
- :type df: :class:`pandas.DataFrame`
+ :type df: :class:`pandas:pandas.DataFrame`
:return: JSON
"""
col_types = grid_columns(df)
@@ -555,9 +555,9 @@ def jsonify(return_data={}, **kwargs):
"""
Overriding Flask's jsonify method to account for extra error handling
- :param return_data: dictionary of data to be passed to :meth:`flask.jsonify`
+ :param return_data: dictionary of data to be passed to :meth:`flask:flask.jsonify`
:param kwargs: Optional keyword arguments merged into return_data
- :return: output of :meth:`flask.jsonify`
+ :return: output of :meth:`flask:flask.jsonify`
"""
if isinstance(return_data, dict) and return_data.get('error'):
handle_error(return_data)
@@ -574,7 +574,7 @@ def find_selected_column(data, col):
in which case we want the last column
:param data: dataframe
- :type data: :class:`pandas.DataFrame`
+ :type data: :class:`pandas:pandas.DataFrame`
:param col: column name
:type col: str
:return: column name if it exists within the dataframe's columns, the last column within the dataframe otherwise
diff --git a/dtale/views.py b/dtale/views.py
index 0855360d..646a2adc 100644
--- a/dtale/views.py
+++ b/dtale/views.py
@@ -1,5 +1,6 @@
from __future__ import absolute_import, division
+import time
import traceback
import webbrowser
from builtins import map, range, str, zip
@@ -29,6 +30,23 @@
DTYPES = {}
SETTINGS = {}
METADATA = {}
+IDX_COL = str('dtale_index')
+
+
+def in_ipython_frontend():
+ """
+ Helper function which is variation of :meth:`pandas:pandas.io.formats.console.in_ipython_frontend` which
+ checks to see if we are inside an IPython zmq frontend
+
+ :return: `True` if D-Tale is being invoked within ipython notebook, `False` otherwise
+ """
+ try:
+ from IPython import get_ipython
+ ip = get_ipython()
+ return 'zmq' in str(type(ip)).lower()
+ except BaseException:
+ pass
+ return False
class DtaleData(object):
@@ -54,28 +72,132 @@ class DtaleData(object):
def __init__(self, port):
self._port = port
self._url = build_url(port)
+ self._notebook_handle = None
@property
def data(self):
+ """
+ Property which is a reference to the globally stored data associated with this instance
+
+ """
return DATA[self._port]
@data.setter
def data(self, data):
+ """
+ Setter which will go through all standard formatting to make sure changes will be handled correctly by D-Tale
+
+ """
startup(data=data, port=self._port)
def kill(self):
+ """
+ This function fires a request to this instance's 'shutdown' route to kill it
+
+ """
requests.get(build_shutdown_url(self._port))
def open_browser(self):
+ """
+ This function uses the :mod:`python:webbrowser` library to try and automatically open server's default browser
+ to this D-Tale instance
+ """
webbrowser.get().open(self._url)
+ def is_up(self):
+ """
+ This function checks to see if instance's :mod:`flask:flask.Flask` process is up by hitting 'health' route
+
+ :return: `True` if :mod:`flask:flask.Flask` process is up and running, `False` otherwise
+ """
+ try:
+ return requests.get(self._url + '/health').ok
+ except BaseException:
+ return False
+
+ def __str__(self):
+ """
+ Will try to create an :class:`ipython:IPython.display.IFrame` if being invoked from within ipython notebook
+ otherwise simply returns the output of running :meth:`pandas:pandas.DataFrame.__str__` on the data associated
+ with this instance
+
+ """
+ if in_ipython_frontend():
+ self.notebook()
+ return ''
+ return self.data.__str__()
+
+ def __repr__(self):
+ """
+ Will try to create an :class:`ipython:IPython.display.IFrame` if being invoked from within ipython notebook
+ otherwise simply returns the output of running :meth:`pandas:pandas.DataFrame.__repr__` on the data for
+ this instance
+
+ """
+ if in_ipython_frontend():
+ self.notebook()
+ return ''
+ return self.data.__repr__()
+
+ def _build_iframe(self, width='100%', height=350):
+ """
+ Helper function to build an :class:`ipython:IPython.display.IFrame` if that module exists within
+ your environment
+
+ :param width: width of the ipython cell
+ :param height: height of the ipython cell
+ :return: :class:`ipython:IPython.display.IFrame`
+ """
+ try:
+ from IPython.display import IFrame
+ except ImportError:
+ logger.info('in order to use this function, please install IPython')
+ return None
+ return IFrame('{}/dtale/iframe'.format(self._url), width=width, height=height)
+
+ def notebook(self, width='100%', height=350):
+ """
+ Helper function which checks to see if :mod:`flask:flask.Flask` process is up and running and then tries to
+ build an :class:`ipython:IPython.display.IFrame` and run :meth:`ipython:IPython.display.display` on it so
+ it will be displayed in the ipython notebook which invoked it.
+
+ A reference to the :class:`ipython:IPython.display.DisplayHandle` is stored in _notebook_handle for
+ updating if you are running ipython>=5.0
+
+ :param width: width of the ipython cell
+ :param height: height of the ipython cell
+ """
+ try:
+ from IPython.display import display
+ except ImportError:
+ logger.info('in order to use this function, please install IPython')
+ return self.data.__repr__()
+
+ while not self.is_up():
+ time.sleep(0.01)
+
+ self._notebook_handle = display(self._build_iframe(width=width, height=height), display_id=True)
+
+ def adjust_cell_dimensions(self, width='100%', height=350):
+ """
+ If you are running ipython>=5.0 then this will update the most recent notebook cell you displayed D-Tale in
+ for this instance with the height/width properties you have passed in as input
+
+ :param width: width of the ipython cell
+ :param height: height of the ipython cell
+ """
+ if self._notebook_handle is not None:
+ self._notebook_handle.update(self._build_iframe(width=width, height=height))
+ else:
+ logger.debug('You must ipython>=5.0 installed to use this functionality')
+
def build_dtypes_state(data):
"""
Helper function to build globally managed state pertaining to a D-Tale instances columns & data types
:param data: dataframe to build data type information for
- :type data: pandas.DataFrame
+ :type data: :class:`pandas:pandas.DataFrame`
:return: a list of dictionaries containing column names, indexes and data types
"""
dtypes = get_dtypes(data)
@@ -94,6 +216,17 @@ def _format_dtype(col_index, col):
def format_data(data):
+ """
+ Helper function to build globally managed state pertaining to a D-Tale instances data. Some updates being made:
+ - convert all column names to strings
+ - drop any indexes back into the dataframe so what we are left is a natural index [0,1,2,...,n]
+ - convert inputs that are indexes into dataframes
+
+ :param data: dataframe to build data type information for
+ :type data: :class:`pandas:pandas.DataFrame`
+ :return: formatted :class:`pandas:pandas.DataFrame` and a list of strings constituting what columns were originally
+ in the index
+ """
if isinstance(data, (pd.DatetimeIndex, pd.MultiIndex)):
data = data.to_frame(index=False)
@@ -107,12 +240,12 @@ def format_data(data):
def startup(data=None, data_loader=None, port=None, name=None):
"""
Loads and stores data globally
- - If data has indexes then it will lock save those columns as locked on the front-end
- - If data has column named index it will be dropped so that it won't collide with row numbering (dtale_index)
- - Create location in memory for storing settings which can be manipulated from the front-end (sorts, filter, ...)
+ - If data has indexes then it will lock save those columns as locked on the front-end
+ - If data has column named index it will be dropped so that it won't collide with row numbering (dtale_index)
+ - Create location in memory for storing settings which can be manipulated from the front-end (sorts, filter, ...)
- :param data: pandas.DataFrame or pandas.Series
- :param data_loader: function which returns pandas.DataFrame
+ :param data: :class:`pandas:pandas.DataFrame` or :class:`pandas:pandas.Series`
+ :param data_loader: function which returns :class:`pandas:pandas.DataFrame`
:param port: integer port for running Flask process
:param name: string label to apply to your session
"""
@@ -167,9 +300,48 @@ def cleanup(port):
def get_port():
+ """
+ Helper function to grab port information (SERVER_PORT) from Flask.request.environ
+
+ """
return get_str_arg(request, 'port', request.environ.get('SERVER_PORT', 'curr'))
+def base_render_template(template, **kwargs):
+ """
+ Overriden version of Flask.render_template which will also include vital instance information
+ - settings
+ - version
+ - processes
+ """
+ port = get_port()
+ curr_settings = SETTINGS.get(port, {})
+ _, version = retrieve_meta_info_and_version('dtale')
+ return render_template(
+ template,
+ settings=json.dumps(curr_settings),
+ version=str(version),
+ processes=len(DATA),
+ **kwargs
+ )
+
+
+def _view_main(iframe=False):
+ """
+ Helper function rendering main HTML which will also build title and store whether we are viewing from an