add docs and typing to _translates

pandas-dev · jreback · May 12, 2021 · May 9, 2021 · May 11, 2021 · May 11, 2021
commit 08b51740cff7eaeda52dc3f6c56a8fd62de6334c
diff --git a/pandas/io/formats/style_render.py b/pandas/io/formats/style_render.py
@@ -132,10 +132,27 @@ def _compute(self):
  r = func(self)(*args, **kwargs)
  return r
 
- def _translate(self, sparsify_index=None, sparsify_cols=None):
+ def _translate(
+ self, sparsify_index: bool | None = None, sparsify_cols: bool | None = None
+ ):
  """
- Convert the DataFrame in `self.data` and the attrs from `_build_styles`
- into a dictionary of {head, body, uuid, cellstyle}.
+ Process Styler data and settings into a dict for template rendering.
+
+ Convert data and settings from ``Styler`` attributes such as ``self.data``,
+ ``self.tooltips`` including applying any methods in ``self._todo``.
+
+ Parameters
+ ----------
+ sparsify_index : bool, optional
+ Whether to sparsify the index or print all hierarchical index elements
+ sparsify_cols : bool, optional
+ Whether to sparsify the columns or print all hierarchical column elements
+
+ Returns
+ -------
+ d : dict
+ The following structure: {uuid, table_styles, caption, head, body,
+ cellstyle, table_attributes}
  """
  if sparsify_index is None:
  sparsify_index = get_option("display.multi_sparse")
@@ -191,21 +208,41 @@ def _translate(self, sparsify_index=None, sparsify_cols=None):
 
  def _translate_header(
  self,
- blank_class,
- blank_value,
- index_name_class,
- col_heading_class,
- sparsify_cols,
+ blank_class: str,
+ blank_value: str,
+ index_name_class: str,
+ col_heading_class: str,
+ sparsify_cols: bool,
  ):
  """
- Build each <tr> within table <head>, using the structure:
+ Build each <tr> within table <head> as a list
+
+ Using the structure:
  +----------------------------+---------------+---------------------------+
  | index_blanks ... | column_name_0 | column_headers (level_0) |
  1) | .. | .. | .. |
  | index_blanks ... | column_name_n | column_headers (level_n) |
  +----------------------------+---------------+---------------------------+
  2) | index_names (level_0 to level_n) ... | column_blanks ... |
  +----------------------------+---------------+---------------------------+
+
+ Parameters
+ ----------
+ blank_class : str
+ CSS class added to elements within blank sections of the structure.
+ blank_value : str
+ HTML display value given to elements within blank sections of the structure.
+ index_name_class : str
+ CSS class added to elements within the index_names section of the structure.
+ col_heading_class : str
+ CSS class added to elements within the column_names section of structure.
+ sparsify_cols : bool
+ Whether column_headers section will add colspan attributes (>1) to elements.
+
+ Returns
+ -------
+ head : list
+ The associated HTML elements needed for template rendering.
  """
  # for sparsifying a MultiIndex
  col_lengths = _get_level_lengths(
@@ -280,15 +317,33 @@ def _translate_header(
 
  return head
 
- def _translate_body(self, data_class, row_heading_class, sparsify_index):
+ def _translate_body(
+ self, data_class: str, row_heading_class: str, sparsify_index: bool
+ ):
  """
- Build each <tr> in table <body> in the following format:
+ Build each <tr> within table <body> as a list
+
+ Use the following structure:
  +--------------------------------------------+---------------------------+
  | index_header_0 ... index_header_n | data_by_column |
  +--------------------------------------------+---------------------------+
 
  Also add elements to the cellstyle_map for more efficient grouped elements in
  <style></style> block
+
+ Parameters
+ ----------
+ data_class : str
+ CSS class added to elements within data_by_column sections of the structure.
+ row_heading_class : str
+ CSS class added to elements within the index_header section of structure.
+ sparsify_index : bool
+ Whether index_headers section will add rowspan attributes (>1) to elements.
+
+ Returns
+ -------
+ body : list
+ The associated HTML elements needed for template rendering.
  """
  # for sparsifying a MultiIndex
  idx_lengths = _get_level_lengths(self.index, sparsify_index)