Basic Anatomy: "sample.py"

PyTioga files are Python programs of a particular form and content. The overall form is described in this section. Some details of the content are discussed in the rest of the tutorial.

We will use a very simple case to illustrate the general form: a file that defines two figures, one that fills the frame with blue and one that fills it with red. The file will define a class, "FigureMaker", and create an instance of it. We will start with those operations, then add bit-by-bit until we have a complete definition.

    from pytioga import FigureMaker

    t = FigureMaker()

The class FigureMaker has the methods to create the figures. It needs to be imported from the top-level module "pytioga". (from ... import tells Python to import the required item from a module/package, if it has not already been imported.)

In this and the following, we will use ">>" to mark the newly added lines. At the end, we will give a complete listing without any of those marks which are not really part of the code.

The "FigureMaker()" command is asking Python to create an instance of the FigureMaker class. The command does not automatically make the figures at the time the class object is created. The figures get constructed in response to user requests that will be forwarded from the front end to the figure maker and then on to our routines. But all that comes later.

Now we can use "t." to talk to our instance of the FigureMaker.

The "." in "t." is part of the "object.name" idiom in Python. It refers to the named attribute or method in the given object. In turn, the object can come from some other evaluation.

When we write something like "t.line_width", we are talking about the thing referenced by the name "line_width" in the object that is returned by evaluating our object called "t". It sounds complicated, but you can safely forget the details and just remember this:

: "t." is talking to PyTioga.

The next step is to add to the initialize routine to tell the

    from pytioga import FigureMaker

    t = FigureMaker()

>>  t.def_figure('Blue', blue)
>>  t.def_figure('Red', red)

The figures are defined to call routines "blue" and "red", we will add these next.

    from pytioga import FigureMaker
>>  from pytioga.color_constants import *

>>  def blue(t):
>>      t.fill_color = Blue
>>      t.fill_frame()

>>  def red(t):
>>      t.fill_color = Red
>>      t.fill_frame()

    t = FigureMaker()

    t.def_figure('Blue', blue)
    t.def_figure('Red', red)

The line 'from pytioga.color_constants import *' is necessary for using the predefined constants for colors, Blue and Red.

We could use the file as it is now, but we like to have the output files go in a subdirectory rather than cluttering up the top level folder where the definition file lives. We can specify a "save directory" by setting the FigureMaker "save_dir" attribute. That will be our last addition. Here is the final version of "sample.py".

    from pytioga import FigureMaker
    from pytioga.color_constants import *

    def blue(t):
        t.fill_color = Blue
        t.fill_frame()

    def red(t):
        t.fill_color = Red
        t.fill_frame()

    t = FigureMaker()

    t.def_figure('Blue', blue)
    t.def_figure('Red', red)

    t.save_dir = 'figures_out'

Now let us see about putting PyTioga to work to create the PDFs for these figures — next stop: Command Line.