-
Notifications
You must be signed in to change notification settings - Fork 4
Methods
To use Plumage, first create a TSDRReq object as follows.
Plumage-py:
t = plumage.TSDRReq()Plumage-dotnet (C#; see Basic examples for other .NET languages):
Plumage.TSDRReq t = new Plumage.TSDRReq();The resulting TSDRReq object can then be used to obtain data from the PTO; and to indicate how it is to be processed.
In the following examples, it is assumed that t is a TSDRReq object. The phrase "None/null" refers to None in Plumage-py and null in Plumage-dotnet.
t.getTSDRInfo(identifier[, tmtype])
Obtain TSDR information for the identifier identifier (string), which is interpreted depending on the value for tmtype (string).
If tmtype is "s", identifier must be an 8-digit application serial number. If tmtype is "r", identifier must be an 7-digit registration number.
If tmtype is omitted (or None/null), identifier is the pathname of a local file. This form is normally used only for testing.
getTSDRInfo is the standard way of using Plumage, and will nearly always be the only method you will need to call after creating the TSDRReq object.
getTSDRInfo is the equivalent of successive calls to the getXMLData, getCSVData and getTSDRData methods. It sets each of the members listed in the descriptions for those methods. If you have some unusual processing requirements, you may wish to call the methods individually; for example, if you only need the result from a particular method (i.e., just the XML or CSV data). You may also want to use the individual methods if you are providing your own data rather than fetching from the PTO, or modifying data from the PTO between steps.
If you are using Plumage other than through getTSDRInfo, be aware that additional errors may result; see Errors and exceptions.
t.getXMLData(identifier[, tmtype])
Obtain raw TSDR data for the identifier identifier (string), which is interpreted depending on the value of tmtype (string). The data obtained depends on the value set by the setPTOFormat method and includes at least the XML data, stored in t.XMLData. If the data is in ZIP format, t.ZipData is set. If the ZIP file contains image data, t.ImageThumb and t.ImageFull are set to that data; otherwise to None/null.
If tmtype is "s", identifier must be an 8-digit application serial number. If tmtype is "r", identifier must be an 7-digit registration number. Any value for tmtype other than "s" or "r" raises an error. If tmtype is omitted (or None/null), identifier is the pathname of a local file. This form is normally used only for testing.
getXMLData calls either getXMLDataFromPTO or getXMLDataFromFile to actually obtain data.
Members set:
t.XMLDatat.XMLDataIsValid-
t.ZipData(optional) -
self.ImageThumb(optional) -
self.ImageFull(optional)
t.getXMLDataFromFile(filename)
Obtain raw TSDR data from the local file whose path name is filename (string). getXMLDataFromFile sets the same members as getXMLData. Generally, getXMLData is used instead of this method, which is provided primarily for testing.
t.getXMLDataFromPTO(identifier, tmtype)
Obtain raw TSDR data from PTO for the identifier identifier (string), which is interpreted depending on the value of tmtype (string). tmtype must be either "r" or "s"; any other value raises an error. identifier indicates the number of the record to be retrieved from the PTO. See getXMLData for details on input parameters. getXMLDataFromPTO sets the same members as getXMLData.
Generally, getXMLData is used instead of this method.
t.getCSVData()
Transform the XML TSDR data in t.XMLData into a list of name-value pairs. getCSVData ordinarily will determine the XML format (ST66 or ST96) and use the appropriate transform supplied as part of Plumage. However, if an XSLT transform was set with setXSLT, that transform will be used instead, overriding the supplied transforms.
Either getXMLDataFromPTO or getXMLDataFromFile must be successfully invoked (generally indirectly via getXMLData) before using this method.
Members set:
t.CSVDatat.CSVDataIsValid
t.getTSDRData()
Refactor key/data pairs in t.CSVData into a TSDRData object containing the dictionaries t.TSDRData.TSDRSingle and t.TSDRData.TSDRMulti.
See Data members for detail on the structure of t.TSDRData, and TSDRData contents for a list of its elements.
getCSVData must be successfully invoked before using this method.
t.resetXMLData()
Clear t.XMLData and all other data obtained via getXMLData, and invoke resetCSVData (and indirectly, resetTSDRData) to clear data derived from t.XMLData.
t.resetCSVData()
Clear t.CSVData and invoke resetTSDRData to clear data derived from t.CSVData.
t.resetTSDRData()
Clear t.TSDRData.
t.setPTOFormat(format)
Set the format of the data to be retrieved from the PTO via getXMLDataFromPTO according to string format. Valid values for format are "ST66" (for ST.66-format XML); "ST96" (for ST.96-format XML); and "zip" (for a ZIP file containing XML in PTO-determined format, as well as other data). An invalid or omitted format will raise an exception; see Errors and exceptions.
If not set, "zip" will be used.
t.unsetPTOFormat()
Return the PTO format to default ("zip"), resetting any previous calls to setPTOFormat.
t.setXSLT(template)
Specify text of an XSLT transform template to be used to transform the PTO-supplied XML data into key-value pairs. template is a string of XSLT that performs the transform. If not set (default), Plumage will determine the appropriate template, supplied with Plumage, to transform the XML.
setXSLT is intended to allow you to write your own transforms to extract additional or different fields from the XML than is extracted by the default transforms. It can also be used to substitute replacement transforms if the PTO changes XML data formats and the supplied transforms no longer work correctly.
t.unsetXSLT()
Return the XSLT transform template to the default (Plumage-supplied), resetting any previous calls to setXSLT.
t.reset()
Resets the TSDRReq object t to an initial state. Equivalent to unsetXMLData, unsetPTOFormat and unsetXSLT.