fixup! ENH: Add blocks to Styler template

Author: TomAugspurger

MANIFEST.in

@@ -25,3 +25,4 @@ global-exclude *.png
 # recursive-include LICENSES *
 include versioneer.py
 include pandas/_version.py
+include pandas/formats/templates/*.tpl

doc/source/style.ipynb

@@ -883,7 +883,8 @@
    "outputs": [],
    "source": [
     "from jinja2 import Environment, ChoiceLoader, FileSystemLoader\n",
-    "from IPython.display import HTML"
+    "from IPython.display import HTML\n",
+    "from pandas.io.api import Styler"
    ]
   },
   {
@@ -983,7 +984,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For convenience, we provide the `styler_factory` function that does the same as the custom subclass."
+    "For convenience, we provide the `Styler.from_custom_template` method that does the same as the custom subclass."
    ]
   },
   {

doc/source/template_structure.html

@@ -43,9 +43,17 @@
     <pre>&lt;table ...&gt;</pre>
     <div class="template_block">caption</div>
 
-    <div class="template_block" >thead</div>
-
-    <div class="template_block" >tbody</div>
+    <div class="template_block" >thead
+        <div class="template_block" >before_head_rows</div>
+        <div class="template_block">head_tr (loop over headers)</div>
+        <div class="template_block" >after_head_rows</div>
+    </div>
+
+    <div class="template_block" >tbody
+        <div class="template_block" >before_rows</div>
+        <div class="template_block">tr (loop over data rows)</div>
+        <div class="template_block" >after_rows</div>
+    </div>
     <pre>&lt;/table&gt;</pre>
 </div><!-- /table -->
 

pandas/__init__.py

@@ -56,7 +56,6 @@
 from pandas.util.print_versions import show_versions
 from pandas.io.api import *
 from pandas.util._tester import test
-from pandas.formats.style import Styler
 
 # extension module deprecations
 from pandas.util.depr_module import _DeprecatedModule

pandas/api/io/__init__.py

@@ -0,0 +1,2 @@
+""" Public IO API """
+from pandas.formats.style import Styler  # noqa

pandas/formats/style.py

@@ -370,6 +370,11 @@ def render(self, **kwargs):
         -------
         rendered: str
             the rendered HTML
+        **kwargs:
+            Any additional keyword arguments are passed through
+            to ``self.template.render``. This is useful when you
+            need to provide additional variables for a custom
+            template.
 
         Notes
         -----
@@ -378,6 +383,19 @@ def render(self, **kwargs):
         last item in a Notebook cell. When calling ``Styler.render()``
         directly, wrap the result in ``IPython.display.HTML`` to view
         the rendered HTML in the notebook.
+
+        Pandas uses the following keys in render. Arguments passed
+        in ``**kwargs`` take precedence, so think carefuly if you want
+        to override them:
+
+        * head
+        * cellstyle
+        * body
+        * uuid
+        * precision
+        * table_styles
+        * caption
+        * table_attributes
         """
         self._compute()
         # TODO: namespace all the pandas keys

pandas/formats/templates/html.tpl

@@ -1,3 +1,4 @@
+{# Update the template_structure.html document too #}
 {%- block before_style -%}{%- endblock before_style -%}
 {% block style %}
 <style  type="text/css" >
@@ -32,28 +33,36 @@
 {%- endblock caption %} 
 {%- block thead %} 
 <thead> 
+    {%- block before_head_rows %}{% endblock %}
     {%- for r in head %} 
+    {%- block head_tr scoped %}
     <tr> 
         {%- for c in r %} 
         {%- if c.is_visible != False %} 
         <{{ c.type }} class="{{c.class}}" {{ c.attributes|join(" ") }}>{{c.value}}</{{ c.type }}>
         {%- endif %} 
         {%- endfor %} 
     </tr> 
+    {%- endblock head_tr %}
     {%- endfor %} 
+    {%- block after_head_rows %}{% endblock %}
 </thead> 
 {%- endblock thead %} 
 {%- block tbody %} 
 <tbody> 
+    {%- block before_rows %}{%- endblock before_rows %}
     {%- for r in body %} 
+    {%- block tr scoped %}
     <tr> 
         {%- for c in r %} 
         {%- if c.is_visible != False %} 
         <{{ c.type }} id="T_{{ uuid }}{{ c.id }}" class="{{ c.class }}" {{ c.attributes|join(" ") }}>{{ c.display_value }}</{{ c.type }}>
         {%- endif %} 
         {%- endfor %} 
     </tr> 
+    {%- endblock tr %}
     {%- endfor %} 
+    {%- block after_rows %}{%- endblock after_rows %}
 </tbody> 
 {%- endblock tbody %} 
 </table> 

pandas/io/api.py

@@ -17,6 +17,10 @@
 from pandas.io.pickle import read_pickle, to_pickle
 from pandas.io.packers import read_msgpack, to_msgpack
 from pandas.io.gbq import read_gbq
+try:
+    from pandas.formats.style import Styler
+except:
+    pass
 
 # deprecation, xref #13790
 def Term(*args, **kwargs):

pandas/tests/api/test_api.py

@@ -48,7 +48,7 @@ class TestPDApi(Base, tm.TestCase):
                'Grouper', 'HDFStore', 'Index', 'Int64Index', 'MultiIndex',
                'Period', 'PeriodIndex', 'RangeIndex', 'UInt64Index',
                'Series', 'SparseArray', 'SparseDataFrame',
-               'SparseSeries', 'Styler', 'TimeGrouper', 'Timedelta',
+               'SparseSeries', 'TimeGrouper', 'Timedelta',
                'TimedeltaIndex', 'Timestamp']
 
     # these are already deprecated; awaiting removal
@@ -127,6 +127,12 @@ def test_api(self):
         self.check(api, self.allowed)
 
 
+class TestApiIO(Base, tm.TestCase):
+
+    def test_api(self):
+        self.check(api.io, self.allowed)
+
+
 class TestDatetoolsDeprecation(tm.TestCase):
 
     def test_deprecation_access_func(self):

pandas/tests/formats/test_style.py

@@ -725,7 +725,8 @@ def test_block_names():
     expected = {
         'before_style', 'style', 'table_styles', 'before_cellstyle',
         'cellstyle', 'before_table', 'table', 'caption', 'thead', 'tbody',
-        'after_table',
+        'after_table', 'before_head_rows', 'head_tr', 'after_head_rows',
+        'before_rows', 'tr', 'after_rows',
     }
     result = set(Styler.template.blocks)
     assert result == expected

setup.py

@@ -699,7 +699,8 @@ def pxd(name):
                                         'data/html_encoding/*.html',
                                         'json/data/*.json'],
                     'pandas.tests.tools': ['data/*.csv'],
-                    'pandas.tests.tseries': ['data/*.pickle']
+                    'pandas.tests.tseries': ['data/*.pickle'],
+                    'pandas.formats': ['templates/*.tpl']
                     },
       ext_modules=extensions,
       maintainer_email=EMAIL,