XLP Literate Program Template

A.J.Hurst

Version 0.8.4

20200817:133040

Table of Contents

1. Introduction

This program suite provides an interactive web-based interface to the wine database.

There are several programs in this suite:

1. The wine module file wineModule.py. Defines all parameters associated with a given wine in the collection (the wineClass), together with a catalog of all known wines (the wineCatalog class).
2. The wine web program wine.py. This program is called from web pages, and renders various views of the wine database.
3. The wine edit program wineEdit.py. This program is called from the web page generated by wine.py when it is desired to edit a wine record. It returns to wine.py when finished.

2. The Wine Module

The wineModule provides importable definitions of the wineClass and the wineCatalog. When invoked as a standalone program, it reads the catalog, prints it out, and then saves it (unchanged). This is for testing purposes.

2.1 Imports

The main thing to note here is that this program saves its database in an XML format, and we use the lxml element tree library to handle translation of the database to and from the internal representation (described later).

2.2 define the wineHeaders routine

2.3 Define the Wine Class

The wineClass class encapsulates all working data associated with identifying a given wine and its properties.

2.3.1 Define the wineClass Initialization

Most of these fields are self explanatory, except perhaps self.stash. It will need to hold multiple instances of locations of the wine, together with the number of bottles in each location. Suggest an array of tuples '(location,number)'? An integrity constraint is that self.quantity should at all times equal the sum of each number in the stash array. Suggest also some form of location shorthand for bottles across a set of contiguous locations 'a01-06'

The field drunk is intended to capture information about a bottle of this wine being drunk. This will include the date of drinking/opening, and any comments to be made about the wine. There may be zero or more instances of such detail, and hence an array of tuples sounds like the best way to structure this.

The internal data structure of the wineClass is

label

A (perhaps shortened form of the) wine label. It is intended to be a unique key to the wine itself. It is a text string of arbitrary length, although some usages may restrict the amount displayed.

vintage

The vintage year of the wine. Non-vintage wines have a vintage year of 0. This must be an integer (although this property is never tested or utilized). It should be consistent with any vintage indication in the label, although again, this is never checked for consistency.

quantity

The total number of bottles held in stock. This must be consistent with the various stash amounts (see below). It must be an integer.

type

The type of the wine, whether sparking, red, white, fortified, etc.. A text string.

variety

The grape variety used in making the wine. A text string.

company

The wine making company. A text string. This value is not currently used, and will be added to the database at a future date.

cost

The cost of the wine. A real number. This is assumed to be fixed across all instances of purchase, although it is acknowledged that possible variations may occur. This anomaly will be addressed in future versions.

stash

A list of the various locations where the wine is held. Each entry in the list is a tuple (quantity,location) where quantity (an integer) is the number of bottles held in the particular location (a text string). A shorthand exists where several bottles may be held in adjacent locations, which takes the form loc{start}-{finish}, where start and finish are integers identifying a contiguous set of locations, and loc is the base location of this particular stash.

drunk

A list of dates when the wine was drunk, along with a comment (possibly empty) for each occasion. Each entry in the list is a tuple (d,c), where d is the date and c is the comment.

2.3.2 Define the wineClass String Representation

This is a simple transliteration of the wine values into a text string. Intended for debugging and not much else.

2.3.3 Define the wineClass toHTML Function

{Note 2.7.1}

See the second paragraph below

{Note 2.7.2}

See the second paragraph below

The toHTML function is responsible for generating an HTML page that allows editing of a wine. It does this by creating a form containing several INPUT style HTML elements, one for each data component of a wine. These are structured three to a line, except for the longer components, especially the drinking data, where one line per drink record is used. The last line of this collection is always blank, to allow new drink records to be created.

Note that when the SAVE button is pressed, a call on the wineEdit script is made, and the current request that brought us to this point is also passed to the script as the request parameter. This is so that the editing script has a pathway to return to the original invoking script.

2.3.3.1 generate toHTML line 1

2.3.3.2 generate toHTML line 2

2.3.3.3 generate toHTML line 3

2.3.3.4 generate toHTML line 4

2.3.4 Define the wineClass Update Procedure

2.3.4.1 wineClass Update each field

This fragment is invoked for each wine field in the upper level for loop. stash is a special case, because of the multiple values within the field, but otherwise the new field values are copied into the eponymously label field via the class dictionary.

keys is a list variable containing all keys that are to be updated.

2.3.4.2 wineClass Update the drunk fields

The handling of drunk values is complicated by the fact that there are an arbitrary number of them, each with their own name field in the web form. We have to process each such name separately.

2.4 Define the Wine Catalog Class

The following definition is pinched straight from the first prototype. It is being modified to suit. Remove this comment once that is complete.

The wineCatalog class holds multiple instances of wine objects. Besides the initialization routine, there are methods to load and save the catalog of wines from the external file representation, to render the catalog into an HTML version, and several methods to make a catalog object an iterable over all wines stored therein.

2.4.1 Define the loadCatalog Routine

Open the XML database file and parse the contents as a DOM tree (held in variable winetree). Extract the wine entries from the list defined in the root of this tree (labelled winecatalog2 in the XML file). If this succeeds, we iterate through the list root, and process each wine entry found there.

2.4.1.1 get details for this wine entry

2.4.1.2 add wine labelled label to catalog

We now have all the information pertaining to the next wine entry. We need to check if this wine is held already, and if so, add the wines in the new entry to the existing holdings. This will then appear as a single entry when the catalog is next saved. If the wine is not known, add it as a new entry in the catalog.

2.4.1.3 Get Box Details from Database

2.4.2 Define the saveCatalog Routine

2.4.3 Render as HTML

We start making an HTML rendering of all the wines by first extracting any filter specification.

Define the comparision routine for sorting the wines. This is given by the sort parameter, which specifies which field of a wine entry is the sort key. Because this is dynamically specified, we need to use an eval to determine which field is to be used.

Loop over all wines in the catalog, generating an HTML table line for each one that is specified by the filter.

Generate a single HTML table line for this wine. Note that only wines that pass the filter are included, and wines that have no holdings (quantity=0) are not included (this will be subject to further refinement).

The line is built up in the text string thiswine, which is added to the generated HTML string only if the count for this wine thiscount is non-zero. A wine that does not pass the filter is excluded early in the cycle by the continue statements, and no text string for this wine is added.

2.4.4 define the displayRack2 routine

2.4.5 define the displayDrunks routine

Print a list of wines for which stocks are no longer held. These are sorted in ascending order of date drunk.

The local function mostrecent is used to compute the most recent date of drinking. This is done on the assumption that the date is given in the form YYYYMMDD, which when converted to an integer and sorted, sorts into chronological order. Wines for which no date of drinking is given are given a drinking date of 0, and hence sort first.

2.4.6 Define the nextWine Generator

2.4.7 define the loadWineRack routine

2.5 Define the Wine Rack Class

The wineRack module takes responsibility for defining all the wine rack related features. A first pass "back of the envelope" analysis suggests a rectangular array of bottle slots, with the following parameters:

RackWidth

the width of the rack array

RackHeight

the height of the rack array

WineArray

the rectangular array itself, with elements of type wineClass.

NoSlot

an object of type wineClass indicating no bottle can be stored in this location. This allows non-rectangular subsets of the WineArray.

initWineArray

a procedure called by the __init__ method that inserts NoSlot entries into the WineArray as required.

2.6 Define the Wine Box Class

The WineBoxClass takes responsibility for organizing where each wine box is, along with its contents. It is intended to be invoked by the cgi action of "Wine Boxes", akin to the Wine Rack operations.

WineBoxes

A dictionary indexed by box number, with each entry a list of WineClass objects defining what wines the box contains

For the purposes of collecting all wines on offer, the stash location 'dining' is also regarded as a box, and warrants special treatment.

3. The wine Program

Start the HTML output conventions. Note that we use a specific css style sheet.

3.1 define the doWine routine

The doWine routine performs various management functions on the database. At the moment, the only such function is to add a new wine template to the database. The user is then prompted to fill out the fields for this wine before saving it to the database.

Other possible functions are to delete a wine, or move a wine record to the historical list (given, for example, that no further stocks of the wine are currently held). These functions are yet to be implemented.

3.2 define the editWine routine

3.3 define the displayRack routine

3.4 The wine.py Main Program

3.4.1 wine.py Determine the Server and Host Names

3.4.2 Determine the Server and Host Names

3.4.3 Integrity and Debug Tests

Ensure that this cgi script is only called from within the local network, on known servers.

3.4.4 create and load the wine catalog

Create and load the wine catalog

3.4.5 Collect Invocation Parameters

Get the parameters presented with this invocation. At this point, only the debug request is analysed and extracted. If the debug request is there (debug=true), the debugFlag is set, and the form entry removed, to avoid confusion with other potential parameters.

3.4.6 Process Request String

We grab the request string so that if some subsidary action takes place (such as editing an entry), we can return to the original framework in which that subsidary action took place.

3.4.7 Determine Action to be Performed

4. The wineEdit Program

This code is derived from a similar program for the family tree. Once we determine the context of invocation, and collect the parameters, it is simply a case of loading the wine catalog, collecting the desired wine, and generating the editing HTML. Once this is done, we exit (the saveCatalog is rather redundant, since nothing has changed yet).

5. TODOs

1. move winerack into wineModule, and integrate handling of NoSlot wine placeholder.

6. The Makefile

Define your Makefile here.

7. Document History

8. Indices

8.1 Files

8.2 Chunks

8.3 Identifiers