Overview

Creation of reports within the mining world is a common occurrence, with the creation of reports using Python, MineSight® Grail (MSGRAIL) and MineSight® Interactive Planner (MSIP) being no exception.

Some goals of the reportlib are,

1. Provide a neutral means of storing tabular data that is independent of presentation. This also provides a means of organizing and stylizing the data prior to presentation.

2. Produce a useful Python module within our MSGRAIL library for generating reports in whatever MineSight® context the script writer may be in. Allowing the script writer to transfrom their tabular data into some common and useful presentations.

3. Provide a module that will start to store all the tools necessary for composing mining/exploration related reports.

The typical workflow for the report lib module will be,

1. Create a Table object.
2. Populate the Table object with data.
3. Transform content of Table object into a useful presentation.

Using the reportlib

As our first example will will build a memory resident table and present that table via a GView. This example will create a GView with a "Cut Name" and "Tonnes" header cells, and then iterate through all the cuts generating and filling in the tonnes for the two columns.

The to_gview function will read the Table object and compose the appropriate GView. With a GView one is able to set background colors on a particular cell. The style dictionary used above illustrates what colors should be applied when a particular cell style is encountered within the Table object during GView composition.

The following example illustrates the ability to continuously write to the Table object. With the write_row function, one is able to simply send out rows of data, and be confident that the Table object is capable of writing to the correct row number.

This generally allows you to stylize the table easily and efficiently while you are computing your report data. If we took the above table and applied the to_xhtml_table transformation like this,

we would get the following output Extended HyperText Markup Language (XHTML) string [1],

which you could then write to an XHMTL file and stylize according to your own Cascading Style Sheet (CSS) definition. Off course you can also use the to_xhtml transformation function to compose a complete, simple document containing your Table object's data (see Generating a Complete XHTML Document).

Table Class

The Table object and its functions and properties are discussed below.

class Table([default_value, default_style])

The Table class provides one with the ability to store information in format that is independent of the actual presentation. This allows you to separate the composition of the report from the actual presentation of the report.

Arguments:

default_value

If a there is no value available for a given table cell, then this is what will be returned by get_value. The default is value is a blank string ("").

default_style

If there is no style available for a given table cell, then this is what will be returned by get_style. The default style is the Python None.

Properties:

num_columns

Equivalent to the largest column value written to the Table.

num_rows

Equivalent to the largest row value written to the Table.

current_write_row

This is the current writing row. In otherwords, this is where the next write_row will be positioned.

previous_write_row

Provided for convenience. This is the last row written to by write_row. This is always equivalent to current_write_row - 1. The previous_write_row is convenient if you want to stylize some cell written in a previous script instruction. For example,

table = Table()
table.write_row("Column 1", "Column 2", "Column 3")
table.set_style(table.previous_write_row, 0, "column1style")

get_alias_value(alias)

Returns a value that is located at the cell with the given alias. You can set an alias either via the alias keyword in set_value or via the set_alias function.

An example of using get_alias_value would be,

table = reportlib.Table()
table.set_value(1, 1, met_volume, alias="Met Volume")

# ... later ...

value = table.get_alias_value("Met Volume")

In this way you can essentially store and retrieve values within the table that are aliased with useful names. In effect, the Table object becomes your data storage object during report generation.

This function will generate a KeyError if the given alias has not been previously defined for this table.

get_style(row, column)

Returns the style defined for the given row and column. If no style was defined, then the default_style will be returned.

get_value(row, column)

Returns the value defined for the given row and column. If no value was defined, then the default_value will be returned.

max_column_width(column)

Examines each row within the given column, attempts to convert the data into a string, and returns the length of the largest string within the column.

minimize([when_value])

Walks through the table and will minimize the overall dimensions of the table. This will look at each cell, and determine if the cell's content is equivalent to when_value. If the cell's contents are equivalent to when_value, then the dimensions of the table will be reset.

The default value for when_value is the Python None. If the default value is None, then the value used throughout the minimization operation will be equivalent to the default value defined for the Table object. In otherwords, if you do not specify a when_value the minimize operation will attempt to do the right thing.

This function can be best explained through an example,

from grail import reportlib

table = reportlib.Table(default_value=None)
table.set_value(1, 1, "Contents")
# at this point max row and max column are 1 and 1.

table.set_value(10, 10, "Bigger")
# at this point max row and max column are 10 and 10.

# We decide to "delete"
table.set_value(10, 10, None)
# at this point max row and max column are still 10 and 10.

table.minimize(when_value=None)
# at this point max row and max column are now 1 and 1.

The minimize function will realize that everything outside of 1 by 1 table is equivalent to the when_value, and minimize the table to the smallest dimensions possible.

set_alias(row, column, alias)

Allows you to set an alias for a given row and column. You can retrieve the value at the given alias using the get_alias_value function on the Table object.

set_column(start_row, column, *args[, style])

Accepts a start row, column index and argument a variable argument list of row contents. This will write the contents of the variable list argument into the given row starting at the given starting column. For example,

table = Table()
table.set_column(5, 1, "a", "b", "c")

Is equivalent to writing out,

table = Table()
table.set_value(5, 1, "a")
table.set_value(6, 1, "b")
table.set_value(7, 1, "c")

If your data is a Python list, you can use the "*" operator to pass in your list in lieu of a variable argument list. To extend the current example, you could also,

data = ["a", "b", "c"]
table = Table()
table.set_column(5, 1, *data)

and you will get the exactly the same results.

The default style will be applied to each cell if no style is defined.

set_row(row, start_column, *args[, style])

The same as set_column, except this function will write out the contents of the variable argument list into the given row starting at the given start column.

The default style will be applied to each cell if no style is defined.

set_style(row, column, style)

Sets a style for the given row and column.

set_value(row, column, value[, style, alias])

Sets a value for a given row and column. Optionally will set a style for the given row and column. The default style will be applied to the cell if no style is defined.

The alias allows you to give the row and column a useful name that can be referenced later via get_alias_value. This allows you to effectively tag and reference values within the Table object for later reference.

write_row(*args[, style])

Utility function that allows you write variable argument lists in sequence to a Table object. Each call to the write_row will increment an internal pointer to the current row (current_write_row). If you want to write a list of data, instead of arguments them selves you can use the "*" operator as in,

data = ["1", "2", "3"]
table = Table()
table.write_row(*data)

If no style is defined, the default style for the table will be appplied to each cell written to by the write_row function.

Style Class

Style([precision, width, justify, top_border, bottom_border, right_border, left_border, background, foreground])

The Style class is used by the various transformations to help define how a cell is layed out.

The Style object is instaintiated with style attributes. These attributes are read during the transformation process.

Each of the style attributes are as follows,

Arguments:

justify

Either reportlib.CENTER, reportlib.RIGHT or reportlib.LEFT. See Constants. The default is reportlib.RIGHT.

precision : integer

Indicates the number of decimal places to use for any floating point values found within a cell. The default is 6.

width : integer

Indicates the width of a given cell. If the cells contents exceed the given width, the contents are truncated. The default is 10.

top_border : string

A character to use when you wish to have a top border for a cell. The default is a blank string ("").

bottom_border : string

A character to use when you wish to have a bottom border for a cell. The default is a blank string ("").

right_border : string

A character to use when you wish to have a right border for a cell. The default is a blank string ("").

left_border : string

A character to use when you wish to have a left border for a cell. The default is a blank string ("").

background : tuple

A 3 value tuple specifying the RGB value of the background color. For example: (red, green, blue). Black is (0, 0, 0), and white is (255, 255, 255). The default is white, (255, 255, 255).

foreground : tuple

A 3 value tuple specifying the RGB value of the foreground color. For example: (red, green, blue). Black is (0, 0, 0), and white is (255, 255, 255). The default is black, (0, 0, 0).

Properties:

precision

Read only. Number of decimal places to use for any floating point.

width

Read only. Width in characters of a given cell.

justify

Read only. Indicates the justification for a given cell.

top_border

Read only. A character to use when you wish to have a top border for a cell.

bottom_border

Read only. A character to use when you wish to have a bottom border for a cell.

right_border

Read only. A character to use when you wish to have a right border for a cell.

left_border

Read only. A character to use when you wish to have a left border for a cell.

background

Read only. A 3 value tuple specifying the RGB value of the background color. For example: (red, green, blue). Black is (0, 0, 0), and white is (255, 255, 255).

foreground

Read only. A 3 value tuple specifying the RGB value of the foreground color. For example: (red, green, blue). Black is (0, 0, 0), and white is (255, 255, 255).

Transformations

All transformations are accomplished through the Transfrom singleton, which is accessible via reportlib.transform. For example, consider the case of transforming your Table object into a plain text representation. For example,

The reportlib.transform.to_text function reads the contents of the table and generates a simple text representation of that data.

All available transformations are discussed below.

to_csv(table[, replace_char])

Works like the to_text transformation. This transformation will transform the contents of the Table object into a comma delimited string. The string can either be displayed or written to a file. Each row will be terminated with a newline character.

The replace_char is used to replace any "," found in within a Table object's cell.

to_gview(table, title, filename, windownum[, style])

Will create a GView file with given window number and filename based on the contents of the table and a style dictionary. The style dictionary defines how each cell is stylized via the Style object (see Style Class).

If a style is found in the Table object that is not defined in the style dictionary, the reportlib.DEFAULT_STYLE will be applied.

This function will return the handle to the closed window. You will have to execute gview.DisplayStdGrid on the handle to display the window.

See Using the reportlib for an example of using the to_gview transformation.

Warning

The initial release of the this transformation in 3.40-00 defined a style as a 3 value tuple only. Althougth this will continue to be usable with the transformation, it is recommended that you use the Style object with the background attribute instead.

to_text(table)

Will generate a standard text table based on the contents of the Table object. The only formatting that will take place is an attempt to align columns, and space them by maximum width of the strings in each column. If you wish to have more control over your table layout consider using to_stylized_text.

Returns a string that can either be displayed or written to a file. Each row will be terminated with a newline character.

to_stylized_text(table[, style])

Generates a text table that can take styles according to the style argument. This table can generate a nicer layout than the basic to_text transformation.

Styles are specified via the Style class and are stored within the style dictionary object. As the transformation is processed, each cell within the table is queried to determine its Style.

An example would be as follows,

# Create our table.
table = reportlib.Table(default_style="default")
table.write_row("Column 1", "Column 2", "Column 3", style="header")
table.write_row(1.2, 1.234, 1.2345)

# Specify our styles. The header style will generate "=" around
# each header. The default_style is display all cells with
# precision 2, and place an empty space (" ") on the right border.
header_style = reportlib.Style(justify=reportlib.CENTER,
                               width=15,
                               top_border="=",
                               bottom_border="=",
                               right_border=" ")
default_style = reportlib.Style(precision=2,
                                width=15,
                                justify=reportlib.LEFT,
                                right_border=" ")

# Create our style dictionary.
styles = {"header":header_style,  # cells with "header" styles
          "default":default_style # all other styles
         }

# Generate our output.
text = reportlib.transform.to_stylized_text(table, styles)

The above example will generate a table that appears like,

=============== =============== ===============
   Column 1        Column 2        Column 3
=============== =============== ===============
1.20            1.23            1.23

You can specify other text formating options using the Style objects as shown above. See Style Class for more information.

Note

When specifying the text width via the Style object be careful that you finally report is consistent down each column.

to_xhtml_table(table[, hclass, summary])

This will read the Table object and generate the appropriate Extended HyperText Markup Language (XHTML) table. The style will be applied to each cell as an XHTML class. The hclass parameter will be used to define the class for the <table> entity itself. The summary parameter is used for the summary attribute on the <table> entity.

The return value will be a string that can then be inserted into your own XHTML document.

The <table> entity will be composed according the XHTML 1.0 standards [1], which rely on the HTML 4.01 standards for definitions of elements [2].

def to_tab(table)
  text = ""
  for row in range(table.num_rows):
     for col in range(table.num_columns):
        value = str(table.get_value(row, col))
        value.replace("\t", "     ") # avoid tabs in values.
        text += "%s" % (value)
        if col != table.num_columns-1:
           text += "\t" # avoid a tab at the very end.
     text += "\n" # new line at the end of each row.
  return text

Constants

CENTER, RIGHT, LEFT

Defines the type of justification to use with the Style class. See Style Class.

DEFAULT_STYLE

The default stylization used by the the transformations that require style definitions.