modified:   eppy/results/fasthtml.py
# http://opensource.org/licenses/MIT)
# =======================================================================
# -*- coding: utf-8 -*-
-"""do stuff with the energyplus output html"""
+"""functions to do a fast read from the E+ HTML table file"""
# TODO : move this to eppy.readhtml
# TODO Document it in user documentation.
import copy
@@ -44,7 +44,20 @@ def _decodeline(line, encoding="utf-8"):
def getnexttable(fhandle):
- """get the next table in the file"""
+ """get the next table in the html file
+
+ Continues to read the file line by line and collects lines from the start of the next table until the end of the table
+
+ Parameters
+ ----------
+ fhandle : file like object
+ A file handle to the E+ HTML table file
+
+ Returns
+ -------
+ table : str
+ The table in HTML format
+ """
lines = fhandle
tablelines = []
for line in lines:
@@ -61,7 +74,24 @@ def getnexttable(fhandle):
def tablebyname(filehandle, header):
- """fast extraction of the table with header"""
+ """fast extraction of the table using the header to identify the table
+
+ This function reads only one table from the HTML file. This is in contrast to `results.readhtml.titletable` that will read all the tables into memory and allows you to interactively look thru them. The function `results.readhtml.titletable` can be very slow on large HTML files.
+
+ This function is useful when you know which file you are looking for. It looks for the title line that is in bold just before the table. Some tables don't have such a title in bold. This function will not work for tables that don't have a title in bold
+
+ Parameters
+ ----------
+ fhandle : file like object
+ A file handle to the E+ HTML table file
+ header: str
+ This is the title of the table you are looking for
+
+ Returns
+ -------
+ titleandtable : (str, str)
+ `Title` and `table in HTML format`
+ """
htmlheader = f"<b>{header}</b><br><br>"
with filehandle:
@@ -81,8 +111,20 @@ def tablebyname(filehandle, header):
def get_upto_nexttable(fhandle):
- """get the next table in the file and all lines before it"""
- # unteseted pseudocode
+ """get all lines from the present location in fhandle to the end of the next table
+
+ This function is used by `tablebyindex` to find the title for the table, which is in the lines before the table. Then it can return the title and the table
+
+ Parameters
+ ----------
+ fhandle : file like object
+ A file handle to the E+ HTML table file
+
+ Returns
+ -------
+ lines_and_table : str
+ The table in HTML format with lines before it.
+ """
lines = fhandle
tablelines = []
for line in lines:
@@ -94,7 +136,24 @@ def get_upto_nexttable(fhandle):
def tablebyindex(filehandle, index):
- """fast extraction of html table with index"""
+ """fast extraction of the table using the index to identify the table
+
+ This function reads only one table from the HTML file. This is in contrast to `results.readhtml.titletable` that will read all the tables into memory and allows you to interactively look thru them. The function `results.readhtml.titletable` can be very slow on large HTML files.
+
+ This function is useful when you know which file you are looking for. It does not work with negative indices, like you can in a list. If you know a way to make negative indices work, do a pull request :-)
+
+ Parameters
+ ----------
+ fhandle : file like object
+ A file handle to the E+ HTML table file
+ index: int
+ This is the index of the table you are looking for
+
+ Returns
+ -------
+ titleandtable : (str, str)
+ `Title` and `table in HTML format`
+ """
with filehandle:
tableindex = 0
for i in range(index + 1):
