Pymerase Docs - Pymweb Manual

Brandon King
Copyright © 2003 California Institute of Technology

Version 0.1.3
May 29, 2003

1 Introduction
    1.1 Description
    1.2 Installation
2 Using Pymweb
    2.1 Overview
    2.2 Schema
        2.2.1 UML/XMI
        2.2.2 table.dtd XML
    2.3 Input Module
    2.4 Output Module
    2.5 Output File/Dir Name
        2.5.1 CreateDBAPI
        2.5.2 CreatePyTkWidgets & CreatePyTkDBWidgets
    2.6 Compression Type
    2.7 Launch
3 Pymweb Output
    3.1 Succesful Output
    3.2 Pymweb Failure / Debugging

1 Introduction

1.1 Description

Pymweb is a web front end for Pymerase. The goal of Pymweb is to provide a method of allowing multiple people to use Pymerase without having to install Pymerase on their computer.

1.2 Installation

You can download directions on how to install and configure Pymweb. You will find the document called "Pymerase Docs - Pymweb Install".

2 Using Pymweb

2.1 Overview

Figure 1: Pymweb - Pymerase Web Front End

If you have installed Pymweb on your local machine you should be able to point your web browser to http://localhost/pymweb.html to begin using Pymerase.

In Figure 1, you will find a screenshot of the Pymweb which you can reference as I briefly describe it's use. I will go into more detail in subsequent sections. There a five things you need to provide for Pymerase to work properly. First, you need to provide a schema. Second, choose which input module you would like to use based on the format in which you supplied your schema. Third, you need to decide what you would like to have generated (Output Module). Some examples are SQL for a database, DBAPI for accessing your database, and/or a GUI widget library. Fourth, pick a destination file name or directory name depending on the output module you choose. And last but not least, you should choose what type of compression do you want Pymweb to use on your output file.

2.2 Schema

In Pymerase, there are currently two methods you can use for defining a schema; UML or XML.

2.2.1 UML/XMI

If you have decided to use Poseidon UML or ArgoUML, they will provide you with a .zargo file. This file is a gziped file containing a .xmi file which Pymerase knows how to parse. In the current version of Pymerase, you have to extract the .xmi file and provide it to Pymerase for processing. In the near future, you will be able to provide the .zargo file. If you have gzip installed you can use the following command to extract the .zargo file.

gunzip nameOfZargoFile.zargo

Once you have extracted the .xmi file, goto Pymweb in your browser and click on the browse button to the right of the schema input field. Find the .xmi and choose it as your schema.

2.2.2 table.dtd XML

If you have decided to use the table.dtd XML format, things will be a little bit more complicate when using Pymweb, but it's still manageable.

What you need to do is put all of your table.dtd XML file, for a given schema, in a single directory. You will then need to tar and gzip the the directory that contains the XML files. The .tar.gz file should be of the same name as the folder. For example, if the directory containing the XML is called 'schema', then the .tar.gz file should be called 'schema.tar.gz'.

In case I have managed to confuse some people, here is a ficitious directory tree that I will us as an example.

project/
  schema/
    tableOne.xml
    tableTwo.xml
    tableThree.xml

In this example, in order to tar and gzip the files in such a way that Pymweb knows how to handle them, we need to move into the project/ directory. In that directory type the following command.

tar cvzf schema.tar.gz schema/

Once you have a .tar.gz file, goto Pymweb in your browser and click on the browse button to the right of the schema input field. Find the .tar.gz file and choose it as your schema.

2.3 Input Module

Currently you have two choices for an input module. If you made your schema with UML/XMI mentioned in section 2.2.1, you choose 'parseXMI'. If you made your schema with the table.dtd XML format mentioned in section 2.2.2, you choose 'parseGenexSchemaXML'.

2.4 Output Module

Here's where the power of Pymerase comes from. You have the choice of many different types of output from Pymerase. It's a modular design, so if Pymerase doesn't have an output module you want or need, you can write it yourself, or submit a feature request on the pymerase web site at http://pymerase.sf.net/. Below is a table of current output modules, a short description, and the type of output file or directory.

Output Module	Description	Output Format
CreateDBAPI	Python Database API	Directory (Python Package)
CreateGraphvizUML	UML like diagrams from Graphviz	File (.dot)
CreatePyTkDBWidgets	Python Tk DBAPI Aware Widgets Lib	Directory (Python Package)
CreatePyTkWidgets	Python Tk Widget Lib for GUI Building	Directory (Python Package)
CreateReport	Report text file describing your model	File (.txt)
CreateSQL	SQL statements for creating a database	File (.sql)
CreateTableXML	Generates Table.dtd XML files	Directory (schema/)

2.5 Output File/Dir Name

Every output module has a different type of output, so you need to give a proper output name for them work correctly. If you take a look at the 'Output' format column in section 2.4, you will see what type of output each module generates. This table should by mostly sufficiant in guiding you in choosing a File or Directory name. Although a few output modules are a little sensitive to the names you choose. Below is more information you will need to know about the output modules and their output.

2.5.1 CreateDBAPI

CreateDBAPI creates a Python package (directory of python files) that need to know about the name of their package.

If you are using UML/XMI, it's currently defined as the namespace, or package. So, if you followed 'Pymerase Docs - ArgoUML for Pymerase', there is a step where you change the name of the namespace. What ever you entered as the name of the namespace, is the name you should use as the output directory name in Pymweb. If you do not do this, you will likely get an error while trying to use the generated DBAPI.

If you decided to use table.dtd XML file format, what ever the name of the output directory you choose will be the name of the package.

Note: Renaming the generated package directory name without changing any of the Python code may cause an error. The easiest way to rename the package is to regenerate it with the proper name.

In future versions of Pymerase, this particular issue should be less of a problem. We plan to implement a 'Package' system which should simplify the output file naming.

2.5.2 CreatePyTkWidgets & CreatePyTkDBWidgets

CreatePyTkWidgets generates a Python Tkinter library based on your schema. These widgets allow you to write your own custom applications quickly. The Entry Widgets are designed to be sub-classed so you can override their save() and load() functions. Without this, they won't do very much.

CreatePyTkDBWidgets generates sub-classed Entry widgets that know how to load and save data to your generated database via the generated DBAPI. To get this widgets to work, you need to put them in the same directory as your file from CreatePyTkWidgets. Also, you need to copy a generated DBAPI package into the widget library directory. Once that is complete you should be able to launch any of the DbEntry widgets and start accessing data from your database.

Note: Only one-to-one and many-to-one associations have been implemented in the current CreatePyTkDBWidgets. One-to-many and many-to-many associations need to be implemented before it will be complete. I can still be useful in it's current state, and you can always sub-class the Entry library files to implement your own features.

2.6 Compression Type

Pymweb currently offers the following three types of compression.

Compression	Extraction Command
Tar & Gzip	tar xvzf fileName.tar.gz
Zip	unzip fileName.zip
None	None

Tar & Gzip is most common on Linux/Unix based systems. Zip is most common on Windows systems. None is offered to make downloads easier for single file downloads, and for debuging.

2.7 Launch

Once you've made your choices, press the submit button and hope for the best.

3 Pymweb Output

3.1 Succesful Output

Figure 2: Pymweb - Succesful Output

Assuming everything went smoothly, you should get an output like the one showed in Figure 2. Below is a table describing what you should see when Pymweb ran successfully.

Item	Description
Version	Pymerase and Pymweb CGI script version numebers
Session	Link to session directory for returning and Session ID
Input	Name of input module used
Output	Name of output module used
Schema	Schema file uploaded
Destination	Name of output file or directory
Compression	Compression type used
Generation Complete	Tells you that generation was successful
Download	Link to the generated file

3.2 Pymweb Failure / Debugging

Pymweb, as of v0.1.15, now displays debugging output in the web browser. If you have trouble understanding the error messages, you may copy and paste them into an e-mail to the pymerase-devel mailing list, or post them to the Pymerase Support Request Tracker.

If you believe you have found a bug, feel free to post it to the Pymerase Bug Tracker.

Note, that in addition to the debugging message, you can always goto '/tmp/pymweb/@sessionNumber/' and check on the files located in that directory. You may also wish to look at the Apache error logs located at '/var/log/apache/error.log'.

If you have any trouble with Pymweb, please join the pymerase-devel mailing list and send an e-mail to the list asking for help. Please visit http://pymerase.sf.net and click on the "Mail Lists" if you wish to join the mailing list.

Please send an e-mail to the pymerase-devel mailing list if you find a simple or common mistakes people make when using Pymweb, and I will add it to this documentation.

File translated from T_EX by T_TH, version 3.33.
On 29 May 2003, 20:02.