`pdstemplate` Module

PDS Ring-Moon Systems Node, SETI Institute

pdstemplate is a Python module that defines the PdsTemplate class, which is used to generate PDS labels based on template files. Both PDS3 and PDS4 (xml) labels are supported. Although specifically designed to facilitate data deliveries by PDS data providers, the template system is generic and can be used to generate files from templates for other purposes.

Getting Started

The general procedure is as follows:

1. Create a template object by calling the PdsTemplate() constructor to read a template file:

from pdstemplate import PdsTemplate
template = PdsTemplate(template_file_path)

Create a dictionary that contains the parameter values to use inside the label.
Construct the label using method write() as follows:
```
template.write(dictionary, label_file)
```

This will create a new label of the given name, using the values in the given dictionary. Once the template has been constructed, steps 2 and 3 can be repeated any number of times.

Alternatively, you can obtain the content of a label without writing it to a file using method generate().

pdstemplate employs the RMS Node’s rms-filecache module and its FCPath class to support the handling of files at a website or in the cloud. You can refer to a remote file by URL and the PdsTemplate will treat it as if it were a local file. See filecache’s documentation for further details.

Template Syntax

A template file will look generally like a label file, except for certain embedded expressions that will be replaced when the template’s write() or generate() method is called.

Substitutions

In general, everything between dollar signs “$” in the template is interpreted as a Python expression to be evaluated. The result of this expression then replaces it inside the label. For example, if dictionary['INSTRUMENT_ID'] == 'ISSWA', then:

<instrument_id>$INSTRUMENT_ID$</instrument_id>

in the template will become:

<instrument_id>ISSWA</instrument_id>

in the label. The expression between “$” in the template can include indexes, function calls, or just about any other Python expression. As another example, using the same dictionary above:

<camera_fov>$"Narrow" if INSTRUMENT_ID == "ISSNA" else "Wide"$</camera_fov>

in the template will become this in the label:

<camera_fov>Wide</camera_fov>

An expression in the template of the form $name=expression$ , where the name is a valid Python variable name, will also also have the side-effect of defining this variable so that it can be re-used later in the template. For example, if this appears as an expression:

$cruise_or_saturn=('cruise' if START_TIME < 2004 else 'saturn')$

then later in the template, one can write:

<lid_reference>
urn:nasa:pds:cassini_iss_$cruise_or_saturn$:data_raw:cum-index
</lid_reference>

To embed a literal “$” inside a label, enter “$$” into the template.

Headers

Headers provide even more sophisticaed control over the content of a label. A header appears alone on a line of the template and begins with “$” as the first non-blank character. It determines whether or how subsequent text of the template will appear in the file, from here up to the next header line.

FOR and END_FOR

You can include one or more repetitions of the same text using FOR and END_FOR. The format is:

$FOR(expression)
    <template text>
$END_FOR

where expression evaluates to a Python iterable. Within the template text, these new variable names are assigned:

VALUE = the current value of the iterator;
INDEX = the index of this iteration, starting from zero;
LENGTH = the total number of iterations.

For example, if:

dictionary["targets"] = ["Jupiter", "Io", "Europa"]
dictionary["naif_ids"] = [599, 501, 502]

then:

$FOR(targets)
    <target_name>$VALUE (naif_ids[INDEX])$</target_name>
$END_FOR

in the template will become this in the label:

<target_name>Jupiter (599)</target_name>
<target_name>Io (501)</target_name>
<target_name>Europa (502)</target_name>

Instead of using the names VALUE, INDEX, and LENGTH, you can customize the variable names by listing up to three comma-separated names and an equal sign “=” before the iterable expression. For example, this will produce the same results as the example above:

$FOR(name, k=targets)
    <target_name>$name (naif_ids[k])$</target_name>
$END_FOR

IF, ELSE_IF, ELSE, and END_IF

You can use IF, ELSE_IF, ELSE, and END_IF to select among alternative blocks of text in the template:

IF(expression): Evaluate expression and include the next lines of the template if it is logically True (e.g., boolean True, a nonzero number, a non-empty list or string, etc.).
ELSE_IF(expression): Include the next lines of the template if expression is logically True and every previous expression was logically false.
ELSE: Include the next lines of the template only if all prior expressions were logically False.
END_IF: This marks the end of the set of if/else alternatives.

As with other substitutions, you can define a new variable of a specified name by using name=expression inside the parentheses of IF() and ELSE_IF().

Note that headers can be nested arbitrarily inside the template.

ONCE

ONCE is a header that simply includes the content that follows it one time. However, it is useful for its side-effect, which is that ONCE(expression) allows the embedded expression to be evaluated without writing new text into the label. You can use this capability to define variables internally without affecting the content of the label produced. For example:

$ONCE(date = big_dictionary["key"]["date"])

will assign the value of the variable named date for subsequent use within the template.

INCLUDE

This header will read the content of another file and insert its content into the template here:

$INCLUDE(filename)

Using the environment variable PDSTEMPLATE_INCLUDES, you can define one or more directories that will be searched for a file to be included. If multiple directories are to be searched, they should be separated by colons. You can also specify one or more directories to search in the PdsTemplate() constructor using the includes input parameter.

Include files are handled somewhat differently from other headers. When INCLUDE references a file as a literal string rather than as an expression to evaluate, it is processed at the time that the PdsTemplate is constructed. However, if the filename is given as an expression, it is not evaluated until write`() or generate`() is called for each label.

NOTE and END_NOTE

You can use NOTE and END_NOTE to embed any arbitrary comment block into the template. Any text between these headers does not appear in the label:

$NOTE
Here is an extended comment about the templae
$END_NOTE

You can also use $NOTE: for an in-line comment. This text, and any blanks before it, are not included in the label:

<filter>$FILTER$</filter>   $NOTE: This is where we identify the filter

Pre-defined Functions

The following pre-defined functions can be used inside any expression in the template.

BASENAME(): The basename of a filepath, with leading directory path removed.
BOOL() Return one of two strings based on a boolean input.
COUNTER() The current value of a counter.
CURRENT_TIME() The current date or time in the local time zone as a string of the form “yyyy-mm-dd” or “yyyy-mm-ddThh:mm:sss”.
CURRENT_ZULU() The current UTC date or time as a string of the form “yyyy-mm-dd” or “yyyy-mm-ddThh:mm:sssZ”.
DATETIME() Convert a time to an ISO time string with the date expressed as “yyyy-mm-dd”.
DATETIME_DOY() Convert a time to an ISO time string with the date expressed as “yyyy-ddd”.
DAYSECS() Convert a time to the number of elapsed seconds since the most recent midnight.
FILE_BYTES() The size in bytes of a specified file.
FILE_MD5() The MD5 checksum of a specified file.
FILE_RECORDS() The number of records in a specified file.
FILE_TIME() The modification time in the local time zone of the specified file.
FILE_ZULU() The UTC modification time of a specified by file.
GETENV() The value of any environment variable.
LABEL_PATH() The file path of the label being written.
LOG() Write a message to the current log.
NOESCAPE() If the template is XML, evaluated expressions are “escaped” to ensure that they are suitable for embedding in a PDS4 label. For example, “>” inside a string will be replaced by “>”. This function prevents text from being escaped in the label, allowing it to contain literal XML.
QUOTE_IF() Quote the given text if it requires quotes within a PDS3 label.
RAISE() Raise an exception with a given class and text message.
RECORD_BYTES() The maximum number of bytes in any record of a specified file, including line terminators.
REPLACE_NA() Return either a given string or an indication that it is “not applicable”.
REPLACE_UNK() Return either a given string or an indication that it is “unknown”.
TEMPLATE_PATH() The directory path to the template file.
VERSION_ID() Version ID of this module using two digits, e.g., “v1.0”.
WRAP() Wrap the given text to a specified indentation and width.

These functions can also be used directly by the programmer within a template; they are static functions of class PdsTemplate.

Logging and Exception Handling

pdstemplate employs the RMS Node’s rms-pdslogger module to handle logging. By default, the logger is a PdsLogger object, although any logging.Logger object will work. See pdslogger’s documentation for further details.

You can override the default Logger using static method set_logger(). You can also set the logging level (“info”, “warning”, “error”, etc.) using set_log_level() and can select among many log formatting options using set_log_format(). Use get_logger() to obtain the current Logger.

By default, exceptions during a call to write() or generate() are handled as follows:

They are written to the log.
The expression that triggered the exception is replaced by the error text in the label, surrounded by “[[[” and “]]]” to make it easier to find.
The attributes fatal_count, error_count, and warning_count of the PdsTemplate contain the number of messages logged by each category.
The exception is otherwise suppressed.

This behavior can be modified using raise_exceptions=True in the call to write() or generate(); in this case, the exception will be raised, label generation will stop, and the label will not be written.

Pre-processors

A pre-processor is a function that takes the text of a template file as input and returns a new template as output. As described above, INCLUDE headers that contain an explicit file name (rather than an expression to be evaluated) are handled by a pre-processor.

You may define your own functions to pre-process the content of a template. They must have this call signature:

func(path: str | Path | FCPath, content: str, *args, **kwargs) -> str

where

path is the path to the template file (used here just for error logging).
content is the content of a template represented by a single string with <LF> line terminators.
*args is for any additional positional arguments to func.
**kwargs is for any additional keyword arguments to func.

When you invoke the PdsTemplate() constructor, one of the optional inputs is preprocess, which takes either a single function or a list of functions to apply after the INCLUDE pre-processor. For the first of these, the args and kwargs inputs can be provided as additional inputs to the constructor. Subsequent pre-processors cannot take additional arguments; define them using lambda notation instead.

Note that a PdsTemplate object has an attribute content, which contains the full content of the template after all pre-processing has been performed. You can examine this attribute to see the final result of all processing. Note also that when line numbers appear in an error message, they refer to the line number of the template after pre-processing, not before.

class pdstemplate.PdsTemplate(template, content='', *, xml=None, crlf=None, upper_e=False, includes=[], preprocess=None, args=(), kwargs={}, postprocess=None)[source]

Bases: object

Class to generate PDS labels based on a template.

See https://rms-pdstemplate.readthedocs.io/en/latest/module.html for details.

__init__(template, content='', *, xml=None, crlf=None, upper_e=False, includes=[], preprocess=None, args=(), kwargs={}, postprocess=None)[source]

Construct a PdsTemplate object from the contents of a template file.

Parameters:

template (str, Path, or FCPath) – Path of the input template file.
content (str or list[str], optional) – Alternative source of the template content rather than reading it from a file.
xml (bool, optional) – Use True to indicate that the template is in xml format; False otherwise. If not specified, an attempt is made to detect the format from the template.
upper_e (bool, optional) – True to force the “E” in the exponents of floating-point numbers to be upper case.
crlf (bool, optional) – True to indicate that the line termination should be <CR><LF>; False for <LF> only. If not specified, the line termination is inferred from the template.
includes (str, Path, FCPath, or list) – One or more directory paths where template include files can be found. The directory containing template is always searched first. Note that include paths can also be specified using the environment variable PDSTEMPLATE_INCLUDES, which should contain one or more directory paths separated by colons. Any directories specified here are searched before those defined by PDSTEMPLATE_INCLUDES.
preprocess (function or list[function], optional) –
An optional function or list of functions that transform the content of a template into a new template. The call signature is:
```
func(path, content, *args, **kwargs) -> str
```
where path is the path of the template file (used here just for error reporting), content is the template’s content, provided as a single string with <LF> line terminators, and args and kwargs are additional inputs. Note that any pre-processor after the first cannot have args or kwargs as inputs; use lambda notation if later functions require inputs.
args (tuple or list) – Any arguments to be passed to the first preprocess function after the template’s content.
kwargs (dict) – Any keywords=value arguments to be passed to the first preprocess function.
postprocess (function, optional) –
An optional function to apply after label content has been generated. This could be used to transform the content or to apply further validation. The call signature is:
```
func(content: str) -> str
```
For example, use postprocess=ps3_syntax_checker to ensure a generated label strictly conforms to the PDS3 standard.

generate(dictionary, label_path='', *, raise_exceptions=False, hide_warnings=False, abort_on_error=False)[source]

Generate the content of one label based on the template and dictionary.

Parameters:

dictionary (dict) – The dictionary of parameters to replace in the template.
label_path (str, Path, or FCPath, optional) – The output label file path. Although a file is not written, this path is used in error messages.
raise_exceptions (bool, optional) – True to raise any exceptions encountered; False to log them and embed the error message into the label surrounded by “[[[” and “]]]”.
hide_warnings (bool, optional) – True to hide warning messages.
abort_on_error (bool, optional) – True to abort the generation process if a validation error is encountered. If raise_exceptions is True, an exception will be raised; otherwise, the error will logged and an empty string will be returned.

Returns:

The generated content.

Return type:

str

write(dictionary, label_path, *, mode='save', backup=False, raise_exceptions=False, handler=None)[source]

Write one label based on the template, dictionary, and output filename.

Parameters:

dictionary (dict) – The dictionary of parameters to replace in the template.
label_path (str, Path, or FCPath, optional) – The output label file path.
mode (str, optional) – “save” to save the new label content regardless of any warnings or errors; “repair” to save the new label if warnings occurred but no errors; “validate” to log errors and warnings but never save the new label file.
backup (bool, optional) – If True and an existing file of the same name as label_path already exists, that file is renamed with a suffix indicating its original modification date. The format is “_yyyy-mm-ddThh-mm-ss” and it appears after the file stem, before the extension.
raise_exceptions (bool, optional) – True to raise any exceptions encountered; False to log them and embed the error message into the label surrounded by “[[[” and “]]]”.
handler (str, Path, FCPath, or logger.Handler, optional) – Define a handler to use exclusively during the generation of this label. If it is a string, Path, or FCPath, a logger.FileHandler using this path is constructed. However, if the string begins with “.” is instead interpreted as the file extension to use, where the path up to the extension is defined by label_path; for example, if handler=”.log”, then when writing “path/to/123.lbl”, the log created will be “path/to/123.log”. This log is automatically closed once the label is written.

Returns:

Number of errors issued. int: Number of warnings issued.

Return type:

int

static log(level, message, filepath='', *, force=False)[source]

Send a message to the current logger.

This allows external modules to issue warnings and other messages.

Parameters:

level (int or str) – Level of the message: ‘info’, ‘error’, ‘warn’, etc.
message (str) – Text of the warning message.
filepath (str, Path, or FCPath, optional) – File path to include in the message.
force (bool, optional) – True to force the logging of the message regardless of the level.

static define_global(name, value)[source]

Define a new global symbol.

This allows external modules to define new symbols during template generation.

Parameters:

name (str) – Name of global symbol as it will appear inside the template.
value (any) – Value of the symbol.

static BASENAME(filepath)[source]

The basename of filepath, with the leading directory path removed.

Parameters:: filepath (Path | FCPath | str) – The filepath.
Returns:: The basename of the filepath (the final filename).
Return type:: str

static BOOL(value, true='true', false='false')[source]

Return true if value evaluates to Boolean True; otherwise, return false.

Parameters:

value (truthy) – The expression to evaluate for truthy-ness.
true (str, optional) – The value to return for a True expression.
false (str, optional) – The value to return for a False expression.

Returns:

“true” or “false”, or the given values in the true and/or false parameters.

Return type:

str

static COUNTER(name, reset=False)[source]

The value of a counter identified by name, starting at 1.

Parameters:

name (str) – The name of the counter. If the counter has not been used before, it will start with a value of 1.
reset (bool, optional) – If True, reset the counter to a value of zero and return the value 0. The next time this counter is referenced, it will have the value 1.

Returns:

The value of the counter.

Return type:

int

static CURRENT_TIME(date_only=False)[source]

The current date/time in the local time zone.

Parameters:: date_only (bool, optional) – Return only the date without the time.
Returns:: The current date/time in the local time zone as a formatted string of the form “yyyy-mm-ddThh:mm:sss” if date_only=False or “yyyy-mm-dd” if date_only=True.
Return type:: str

static CURRENT_ZULU(date_only=False)[source]

The current UTC date/time.

Parameters:: date_only (bool, optional) – Return only the date without the time.
Returns:: The current date/time in UTC as a formatted string of the form “yyyy-mm-ddThh:mm:sssZ” if date_only=False or “yyyy-mm-dd” if date_only=True.
Return type:: str

static DATETIME(time, offset=0, digits=None)[source]

Convert time to an ISO date of the form “yyyy-mm-ddThh:mm:ss[.fff]Z”.

Parameters:

time (str or float) – The time as an arbitrary date/time string or TDB seconds. If time is “UNK”, then “UNK” is returned.
offset (float, optional) – The offset, in seconds, to add to the time.
digits (int, optional) – The number of digits after the decimal point in the seconds field to return. If not specified, the appropriate number of digits for the time is used.

Returns:

The time in the format “yyyy-mm-ddThh:mm:ss[.fff]Z”.

Return type:

str

static DATETIME_DOY(time, offset=0, digits=None)[source]

Convert time to an ISO date of the form “yyyy-dddThh:mm:ss[.fff]Z”.

Parameters:

time (str or float) – The time as an arbitrary date/time string or TDB seconds. If time is “UNK”, then “UNK” is returned.
offset (float, optional) – The offset, in seconds, to add to the time.
digits (int, optional) – The number of digits after the decimal point in the seconds field to return. If not specified, the appropriate number of digits for the time is used.

Returns:

The time in the format “yyyy-dddThh:mm:ss[.fff]Z”.

Return type:

str

static DAYSECS(time)[source]

The number of elapsed seconds since the most recent midnight.

Parameters:: time (str or float) – The time as an arbitrary date/time string or TDB seconds. If time is “UNK”, then “UNK” is returned.
Returns:: The number of elapsed seconds since the most recent midnight.
Return type:: float

static FILE_BYTES(filepath)[source]

The size in bytes of the file specified by filepath.

Parameters:: filepath (Path | FCPath | str) – The filepath.
Returns:: The size in bytes of the file.
Return type:: int

static FILE_MD5(filepath)[source]

The MD5 checksum of the file specified by filepath.

Parameters:: filepath (Path | FCPath | str) – The filepath.
Returns:: The MD5 checksum of the file.
Return type:: str

static FILE_RECORDS(filepath)[source]

The number of records in the the file specified by filepath.

Parameters:: filepath (Path | FCPath | str) – The filepath.
Returns:: The number of records in the file if it is ASCII; 0 if the file is binary.
Return type:: int

static FILE_TIME(filepath)[source]

The modification time in the local time zone of a file.

Parameters:: filepath (Path | FCPath | str) – The filepath.
Returns:: The modification time in the local time zone of the file specified by filepath in the form “yyyy-mm-ddThh:mm:ss”.
Return type:: str

static FILE_ZULU(filepath)[source]

The UTC modification time of a file.

Parameters:: filepath (Path | FCPath | str) – The filepath.
Returns:: The UTC modification time of the file specified by filepath in the form “yyyy-mm-ddThh:mm:ssZ”.
Return type:: str

static GETENV(name, default='')[source]

The value of the specified environment variable.

Parameters:

name (str) – Name of the environment variable.
default (str) – Value to return if the environment variable is undefined.

Returns:

The value of the variable or else the default.

Return type:

str

static LABEL_PATH()[source]

The path to the current label file being generated.

Returns:: Path string to the label file.
Return type:: str

static LOG(level, message, filepath='', *, force=False)[source]

Send a message to the logger; nothing is returned.

This allows a template to issue warnings and other messages.

Parameters:

level (int or str) – Level of the message: ‘info’, ‘error’, ‘warn’, etc.
message (str) – Text of the warning message.
filepath (str, Path, or FCPath, optional) – File path to include in the message.
force (bool, optional) – True to force the logging of the message regardless of the level.

static NOESCAPE(text)[source]

Prevent the given text from being escaped in the XML.

If the template is XML, evaluated expressions are “escaped” to ensure that they are suitable for embedding in a PDS label. For example, “>” inside a string will be replaced by “>”. This function prevents text from being escaped in the label, allowing it to contain literal XML.

Parameters:: text (str) – The text that should not be escaped.
Returns:: The text marked so that it won’t be escaped.
Return type:: str

static QUOTE_IF(text)[source]

Place the given text in quotes if it is not a valid upper-case identifier.

An empty string and a string starting with a digit is also quoted. A string that is already enclosed in quotes or apostrophes is not quoted (but quote balancing is not checked). Other values are returned unchanged.

Parameters:: text (str) – Text to possibly quote.
Returns:: The text with quotes if necessary.
Return type:: str

static RAISE(exception, message)[source]

Raise an exception with the given class exception and the message.

Parameters:

exception (type) – The class of the exception to raise, e.g., ValueError.
message (str) – The message to include in the exception.

Raises:

Exception – The specified exception.

static RECORD_BYTES(filepath)[source]

The maximum number of bytes in any record of the specified file, including line terminators.

Parameters:: filepath (Path | FCPath | str) – The filepath.

static REPLACE_NA(value, na_value, flag='N/A')[source]

Return na_value if value equals “N/A”; otherwise, return value.

Parameters:

value (str or int or float or bool) – The input value.
flag (str or int or float or bool, optional) – The value that means N/A. Defaults to the string “N/A”.

Returns:

The original value if it is not equal to flag, otherwise na_value.

Return type:

str or int or float or bool

static REPLACE_UNK(value, unk_value)[source]

Return unk_value if value equals “UNK”; otherwise, return value.

Parameters:: value (str or int or float or bool) – The input value.
Returns:: The original value if it is not equal to “UNK”, otherwise unk_value.
Return type:: str or int or float or bool

static TEMPLATE_PATH()[source]

The path to this template file.

Returns:: Path string to this template file.
Return type:: str

static VERSION_ID()[source]

The PdsTemplate version ID using two digits, e.g., “v1.0”.

Returns:: The version ID.
Return type:: str

static WRAP(left, right, text, preserve_single_newlines=True)[source]

Format text to fit between the left and right column numbers.

The first line is not indented, so the text will begin in the column where “$WRAP” first appears in the template.

Parameters:

left (int) – The starting column number, numbered from 0.
right (int) – the ending column number, numbered from 0.
text (str) – The text to wrap.
preserve_single_newlines (bool, optional) – If True, single newlines are preserved. If False, single newlines are just considered to be wrapped text and do not cause a break in the flow.

Returns:

The wrapped text.

Return type:

str

get_logger(): The global PdsLogger for PdsTemplate and associated tools.

set_log_format()

Set the formatting and other properties of the logger.

Parameters:

level (int or str, optional) – The minimum level of level name for a record to enter the log.
timestamps (bool, optional) – True or False, defining whether to include a timestamp in each log record.
digits (int, optional) – Number of fractional digits in the seconds field of the timestamp.
lognames (bool, optional) – True or False, defining whether to include the name of the logger in each log record.
pid (bool, optional) – True or False, defining whether to include the process ID in each log record.
indent (bool, optional) – True or False, defining whether to include a sequence of dashes in each log record to provide a visual indication of the tier in a logging hierarchy.
blanklines (bool, optional) – True or False, defining whether to include a blank line in log files when a tier in the hierarchy is closed.
colors (bool, optional) – True or False, defining whether to color-code the log files generated, for Macintosh only.
maxdepth (int, optional) – Maximum depth of the logging hierarchy, needed to prevent unlimited recursion.

set_log_level()

Set the minimum level for messages to be logged.

Parameters:: level (int or str, optional) – The minimum level of level name for a record to enter the log. Use an integer 1-50 or a level name, one of “debug”=10, “info”=20, “warning”=30, “error”=40, or “fatal”=50.

set_logger()

Define the global logger for PdsTemplate and associated tools.

Parameters:: logger (PdsLogger or logging.Logger) – Logger to use, replacing the default.
Returns:: The new PdsLogger. If the input was a logging.Logger, it is converted to a PdsLogger.
Return type:: PdsLogger

pdstemplate.utils

Utility functions and classes.

exception pdstemplate.utils.TemplateError(message, filepath='', *, force=False, level='error', stacktrace=False)[source]

Bases: LoggerError

Class for all template parsing exceptions.

exception pdstemplate.utils.TemplateAbort(message, filepath='', *, force=False, level='error', stacktrace=False)[source]

Bases: TemplateError

Raise this class to abort processing a template if the situation is hopeless.

When raising this exception, pass it the exact text to appear in the log. It will appear as a FATAL message with four asterisks followed by the given text, and the file path if any.

pdstemplate.utils.set_logger(logger)[source]

Define the global logger for PdsTemplate and associated tools.

Parameters:: logger (PdsLogger or logging.Logger) – Logger to use, replacing the default.
Returns:: The new PdsLogger. If the input was a logging.Logger, it is converted to a PdsLogger.
Return type:: PdsLogger

pdstemplate.utils.get_logger()[source]: The global PdsLogger for PdsTemplate and associated tools.

pdstemplate.utils.set_log_level(level)[source]

Set the minimum level for messages to be logged.

Parameters:: level (int or str, optional) – The minimum level of level name for a record to enter the log. Use an integer 1-50 or a level name, one of “debug”=10, “info”=20, “warning”=30, “error”=40, or “fatal”=50.

pdstemplate.utils.set_log_format(**kwargs)[source]

Set the formatting and other properties of the logger.

Parameters:

level (int or str, optional) – The minimum level of level name for a record to enter the log.
timestamps (bool, optional) – True or False, defining whether to include a timestamp in each log record.
digits (int, optional) – Number of fractional digits in the seconds field of the timestamp.
lognames (bool, optional) – True or False, defining whether to include the name of the logger in each log record.
pid (bool, optional) – True or False, defining whether to include the process ID in each log record.
indent (bool, optional) – True or False, defining whether to include a sequence of dashes in each log record to provide a visual indication of the tier in a logging hierarchy.
blanklines (bool, optional) – True or False, defining whether to include a blank line in log files when a tier in the hierarchy is closed.
colors (bool, optional) – True or False, defining whether to color-code the log files generated, for Macintosh only.
maxdepth (int, optional) – Maximum depth of the logging hierarchy, needed to prevent unlimited recursion.

pdstemplate.pds3table

pds3table is a plug-in module to automate the generation and validation of PDS3 labels for ASCII tables. It works in concert with the pdstemplate.asciitable module, which analyzes the content of ASCII table files. It is used by stand-alone program tablelabel to validate and repair existing PDS3 labels as well as to generate new labels; if tablelabel meets your needs, you can avoid any programming in Python.

To import:

import pdstemplate.pds3table

Once imported, the following pre-defined functions become available for use within a PdsTemplate:

ANALYZE_PDS3_LABEL() analyzes the content of a PDS3 label or template, gathering information about the names and other properties of its TABLE and COLUMN objects. Once it is called, the following functions become available.
ANALYZE_TABLE() (from pdstemplate.asciitable) takes the path to an existing ASCII table and analyzes its content, inferring details about the content and formats of all the columns.
VALIDATE_PDS3_LABEL() issues a warning message for any errors found in the label or template. Optionally, it can abort the generation of the label if it encounters an irrecoverable incompatibility with the ASCII table.
LABEL_VALUE() returns correct and valid PDS3 values for many of the attributes of PDS3 TABLE and COLUMN objects, based on its analysis of the table.
OLD_LABEL_VALUE() returns the current (although possibly incorrect or missing) values for many of the same PDS3 TABLE and COLUMN attributes.

For example, consider a template that contains this content:

$ONCE(ANALYZE_TABLE(LABEL_PATH().replace('.lbl', '.tab')))
$ONCE(ANALYZE_PDS3_LABEL(TEMPLATE_PATH()))
...
OBJECT              = TABLE
  ...
  ROWS              = $LABEL_VALUE('ROWS')$
  COLUMNS           = $LABEL_VALUE('COLUMNS')$

  OBJECT            = COLUMN
    NAME            = FILE_NAME
    COLUMN_NUMBER   = $LABEL_VALUE("COLUMN_NUMBER", "FILE_NAME")$
    DATA_TYPE       = $LABEL_VALUE("DATA_TYPE", "FILE_NAME")$
    START_BYTE      = $LABEL_VALUE("START_BYTE", "FILE_NAME")$
    BYTES           = $LABEL_VALUE("BYTES", "FILE_NAME")$
    FORMAT          = $LABEL_VALUE("FORMAT", "FILE_NAME")$
    MINIMUM_VALUE   = $LABEL_VALUE("MINIMUM_VALUE", "FILE_NAME")$
    MAXIMUM_VALUE   = $LABEL_VALUE("MAXIMUM_VALUE", "FILE_NAME")$
    DESCRIPTION     = "Name of file in the directory"
  END_OBJECT        = COLUMN
...

The initial calls to ANALYZE_TABLE() and ANALYZE_PDS3_LABEL() are embedded inside a ONCE directive because they return no content. The first call analyzes the content and structure of the ASCII table, and the second analyzes the template. The subsequent calls to LABEL_VALUE() fill in the correct values for the specified quantities.

Optionally, you could include this as the third line in the template:

$ONCE(VALIDATE_PDS3_LABEL())

This function logs a warnings and errors for any incorrect TABLE and COLUMN values currently in the template.

This module also provides a pre-processor, which can be used to validate or repair an exising PDS3 label. The function pds3_table_preprocessor(), when used as the preprocess input to the PdsTemplate() constructor, transforms an existing PDS3 label into a new template by replacing all needed TABLE and COLUMN attributes with calls to LABEL_VALUE(). The effect is that when the label is generated, it is guaranteed to contain correct information where the earlier label might have been incorrect. In this case, your program would look something like this:

from pdstemplate import PdsTemplate
from pdstemplate.pds3table import pds3_table_preprocessor

template = PdsTemplate(label_path, crlf=True, ...
                       preprocess=pds3_table_preprocessor, kwargs={...})
template.write({}, label_path, ...)

The constructor invokes pds3_table_preprocessor() to transform the label into a template. You can use the kwargs input dictionary to provide inputs to the pre-processor, such as adding a requirement that each column contain FORMAT, COLUMN_NUMBER, MINIMUM/MAXIMUM_VALUEs, etc., and designating how warnings and errors are to be handled.

Afterward, the call to the template’s write() method will validate the label and/or write a new label, depending on its input parameters.

For example, suppose the label contains this:

PDS_VERSION_ID          = PDS3
RECORD_TYPE             = FIXED_LENGTH
RECORD_BYTES            = 1089
FILE_RECORDS            = 1711
^INDEX_TABLE            = "COVIMS_0094_index.tab"

OBJECT                  = INDEX_TABLE
  INTERCHANGE_FORMAT    = ASCII
  ROWS                  = 1711
  COLUMNS               = 61
  ROW_BYTES             = 1089
  DESCRIPTION           = "This Cassini VIMS image index ...."

  OBJECT                = COLUMN
    NAME                = FILE_NAME
    DATA_TYPE           = CHARACTER
    START_BYTE          = 2
    BYTES               = 25
    DESCRIPTION         = "Name of file in the directory"
  END_OBJECT            = COLUMN
...

You then execute this:

template = PdsTemplate(label_path, crlf=True,
                       preprocess=pds3_table_preprocessor,
                       kwargs={'numbers': True, 'formats': True})

After the call, you can look at the template’s content attribute, which contains the template’s content after pre-processing. Its value is this:

$ONCE(ANALYZE_TABLE(LABEL_PATH().replace(".lbl",".tab").replace(".LBL",".TAB"), crlf=True))
$ONCE(VALIDATE_PDS3_LABEL(hide_warnings, abort_on_error))
PDS_VERSION_ID          = PDS3
RECORD_TYPE             = $LABEL_VALUE("RECORD_TYPE")$
RECORD_BYTES            = $LABEL_VALUE("RECORD_BYTES")$
FILE_RECORDS            = $LABEL_VALUE("FILE_RECORDS")$

OBJECT                  = INDEX_TABLE
  INTERCHANGE_FORMAT    = $LABEL_VALUE("INTERCHANGE_FORMAT")$
  ROWS                  = $LABEL_VALUE("ROWS")$
  COLUMNS               = $LABEL_VALUE("COLUMNS")$
  ROW_BYTES             = $LABEL_VALUE("ROW_BYTES")$
  DESCRIPTION           = "This Cassini VIMS image index ...."

  OBJECT                = COLUMN
    NAME                = FILE_NAME
    COLUMN_NUMBER       = $LABEL_VALUE("COLUMN_NUMBER", 1)$
    DATA_TYPE           = $LABEL_VALUE("DATA_TYPE", 1)$
    START_BYTE          = $LABEL_VALUE("START_BYTE", 1)$
    BYTES               = $LABEL_VALUE("BYTES", 1)$
    FORMAT              = $QUOTE_IF(LABEL_VALUE("FORMAT", 1))$
    DESCRIPTION         = "Name of file in the directory"
  END_OBJECT            = COLUMN
...

The TABLE and COLUMN attributes defining table format and structure have been replaced by calls to LABEL_VALUE(), which will provide the correct value whether or not the value in the original label was correct. Also, COLUMN_NUMBER and FORMAT have been added to the COLUMN object because of the pre-processor inputs numbers=True and formats=True.

Another application of the preprocessor is to simplify the construction of a template for an ASCII table. Within a template, the only required attributes of a COLUMN object are NAME and DESCRIPTION. Optionally, you can also specify any special constants, VALID_MINIMUM/MAXIMUM values, OFFSET and SCALING_FACTOR, and the number of ITEMS if the COLUMN object describes more than one. All remaining information about the column, such as DATA_TYPE, START_BYTE, BYTES, etc., will be filled in by the pre-processor. Inputs to the preprocessor let you indicate whether to include FORMATs, COLUMN_NUMBERs, and the MINIMUM/MAXIMUM_VALUEs attributes automatically.

pdstemplate.pds3table.ANALYZE_PDS3_LABEL(labelpath, *, validate=True)[source]

Analyze the current template as applied to the most recently analyzed ASCII table.

After this call, LABEL_VALUE() can be used anywhere in the template to fill in values derived from the table.

Parameters:

labelpath (str, Path, or FCPath) – Path to the current label.
validate (bool, optional) – If True, a warning or error message will be logged for every problem found in the template. Otherwise, warnings will be corrected silently.

pdstemplate.pds3table.VALIDATE_PDS3_LABEL(hide_warnings=False, abort_on_error=True)[source]

Log a warning for every error found when generating this PDS3 label.

ANALYZE_PDS3_LABEL() must be called first.

Parameters:: abort_on_error (bool) – If True and a validation error occurs, further evaluation of the template will be aborted.
Returns:: The number of errors issued. int: The number of warnings issued.
Return type:: int

pdstemplate.pds3table.LABEL_VALUE(name, column=0)[source]

Lookup function returning information about the PDS3 label after it has been analyzed or pre-processed and after the ASCII table has been analyzed.

Each of the following function calls returns a valid PDS3 parameter value. Columns can be identified by name or by number starting from 1.

LABEL_VALUE(“PATH”)
LABEL_VALUE(“BASENAME”)
LABEL_VALUE(“RECORD_TYPE”)
LABEL_VALUE(“RECORD_BYTES”)
LABEL_VALUE(“FILE_RECORDS”)
LABEL_VALUE(“INTERCHANGE_FORMAT”)
LABEL_VALUE(“ROWS”)
LABEL_VALUE(“COLUMNS”)
LABEL_VALUE(“ROW_BYTES”)
LABEL_VALUE(“DATA_TYPE”, <column>)
LABEL_VALUE(“START_BYTE”, <column>)
LABEL_VALUE(“BYTES”, <column>)
LABEL_VALUE(“COLUMN_NUMBER”, <column>)
LABEL_VALUE(“FORMAT”, <column>)
LABEL_VALUE(“UNIT”, <column>)
LABEL_VALUE(“MINIMUM_VALUE”, <column>)
LABEL_VALUE(“MAXIMUM_VALUE”, <column>)
LABEL_VALUE(“DERIVED_MINIMUM”, <column>)
LABEL_VALUE(“DERIVED_MAXIMUM”, <column>)

It also provides these values derived from the existing template or label: “NAME”, “ITEMS”, “SCALING_FACTOR”, “OFFSET”, “INVALID_CONSTANT”, “MISSING_CONSTANT”, “NOT_APPLICABLE_CONSTANT”, “NULL_CONSTANT”, “UNKNOWN_CONSTANT”, “VALID_MINIMUM”, and “VALID_MAXIMUM”.

In addition, these options are supported:

LABEL_VALUE(“TABLE_PATH”): full path to the associated ASCII table file.
LABEL_VALUE(“TABLE_BASENAME”): basename of the associated ASCII table file.
LABEL_VALUE(“FIRST”, <column>): value from the first row of this column.
LABEL_VALUE(“LAST”, <column>): value from the last row of this column.

Parameters:

name (str) – Name of a parameter.
column (str or int, optional) – The name or COLUMN_NUMBER (starting at 1) for a column; use 0 for general parameters.

Returns:

The correct value for the specified parameter.

Return type:

int, float, str, or None

pdstemplate.pds3table.OLD_LABEL_VALUE(name, column=0)[source]

Lookup function returning information about the current content of the PDS3 label, whether or not it is correct.

Available top-level keywords are “RECORD_TYPE”, “RECORD_BYTES”, “FILE_RECORDS”, “INTERCHANGE_FORMAT”, “ROWS”, “COLUMNS”, and “ROW_BYTES”.

Available column-level keywords are “NAME”, “COLUMN_NUMBER”, “DATA_TYPE”, “START_BYTE”, “BYTES”, “FORMAT”, “ITEMS”, “ITEM_BYTES”, “ITEM_OFFSET”, “SCALING_FACTOR”, “OFFSET”, “INVALID_CONSTANT”, “MISSING_CONSTANT”, “NOT_APPLICABLE_CONSTANT”, “NULL_CONSTANT”, “UNKNOWN_CONSTANT”, “VALID_MAXIMUM”, “VALID_MINIMUM”, “MINIMUM_VALUE”, “MAXIMUM_VALUE”, “DERIVED_MINIMUM”, and “DERIVED_MAXIMUM”.

Parameters:

name (str) – Name of a parameter.
column (str or int, optional) – The name or COLUMN_NUMBER (starting at 1) for a column; use 0 for general parameters.

Returns:

The correct value for the specified parameter.

Return type:

int, float, str, or None

pdstemplate.pds3table.pds3_table_preprocessor(labelpath, content, *, validate=True, numbers=False, formats=False, units=False, minmax=(), derived=(), edits=[], reals=[])[source]

A pre-processor function for use in the :meth:~pdstemplate.PdsTemplate` constructor.

This function receives a PDS3 label or template describing an ASCII table and returns a revised template in which the supported TABLE and COLUMN attributes have been replaced by calls to LABEL_VALUE. This ensures that the generated label will contain a complete and accurate set of values.

Parameters:

labelpath (str, Path, or FCPath) – The path to the PDS3 label or template file.
content (str) – The full content of the template as a single string with a newline character after each line.
validate (bool, optional) – If True, a warning will be issued for each error found when the label is generated; otherwise, errors will be repaired silently.
numbers (bool, optional) – True to include COLUMN_NUMBER into each COLUMN object if it is not already there.
formats (bool, optional) – True to include FORMAT into each COLUMN object if it is not already there.
units (bool, optional) – True to repair units to conform to the options in the PDS3 Data Dictionary.
minmax (str, tuple[str], or list[str], optional) – Zero or more names of columns for which to include the MINIMUM_VALUE and MAXIMUM_VALUE. In addition or as an alternative, use “float” to include these values for all floating-point columns and/or “int” to include these values for all integer columns.
derived (str, tuple[str], or list[str], optional) – Zero or more names of columns for which to include the DERIVED_MINIMUM and DERIVED_MAXIMUM. In addition or as an alternative, use “float” to include these values for all floating-point columns.
edits (list[str]), optional) – A list of strings of the form “column:name = value”, which should be used to insert or replace values currently in the label.
reals (str, tuple[str], or list[str]), optional) – Names of columns that should be treated as ASCII_REAL even if thee column only contains integers.

Returns:

The revised content for the template.

Return type:

str

class pdstemplate.pds3table.Pds3Table(labelpath, label='', *, validate=True, analyze_only=False, crlf=None, numbers=False, formats=False, units=False, minmax=(), derived=(), edits=[], reals=[])[source]

Bases: object

Class encapsulating a label or template that describes a PDS3 label containing a TABLE object.

__init__(labelpath, label='', *, validate=True, analyze_only=False, crlf=None, numbers=False, formats=False, units=False, minmax=(), derived=(), edits=[], reals=[])[source]

Constructor for a Pds3Table object. It analyzes the content of a PDS3 label or template and saves the info for validation or possible repair.

Parameters:

labelpath (str, Path, or FCPath) – The path to a PDS3 label or template file.
label (str, optional) – The full content of the template as a single string or list of strings, one per record (including line terminators).
validate (bool, optional) – True to issue a warning for each error in the label or template when the label is generated; False to correct errors silently.
analyze_only (bool, optional) – True to prevent the generating an alternative label for purposes of repair. This step can be slow for large labels so it should be avoided if it is not needed.
crlf (bool, optional) – True to raise an error if the line terminators are not <CR><LF>; False to raise an error if the line terminator is not <LF> alone; None to accept either line terminator.
numbers (bool, optional) – True to include COLUMN_NUMBER into each COLUMN object if it is not already there.
formats (bool, optional) – True to include FORMAT into each COLUMN object if it is not already there.
units (bool, optional) – True to repair units to conform to the options in the PDS3 Data Dictionary.
minmax (str, tuple[str], or list[str], optional) – Zero or more names of columns for which to include the MINIMUM_VALUE and MAXIMUM_VALUE. In addition or as an alternative, use “float” to include these values for all floating-point columns and/or “int” to include these values for all integer columns.
derived (str, tuple[str], or list[str], optional) – Zero or more names of columns for which to include the DERIVED_MINIMUM and DERIVED_MAXIMUM. In addition or as an alternative, use “float” to include these values for all floating-point columns.
edits (str or list[str]), optional) – Expressions of the form “column:name = value”, which should be used to insert or replace values currently in the label.
reals (str, tuple[str], or list[str]), optional) – Names of columns that should be treated as ASCII_REAL even if thee column only contains integers.

assign_to(table=None)[source]

Assign this PDS3 label to the given ASCII table.

Parameters:: table (AsciiTable, optional) – Table to which this PDS3 label should apply. If not specified, the table defined by AsciiTable._latest_ascii_table() is used.

get_table_basename()[source]

The table basename in the template or label, if present.

If the TABLE value in the template is a variable name or expression, an empty string is returned instead.

get_table_path()[source]

The file path to the table described by this label.

If the TABLE value in the template is a variable name or expression, an empty string is returned instead.

Returns:: Path to the table file if defined in the label; otherwise, an empty string.
Return type:: FCPath

validate(table=None)[source]

Compare this object to the given AsciiTable object and issue a warning for each erroneous value identified.

Parameters:: table (AsciiTable, optional) – The AsciiTable assigned to this label. If this is specified and is different from the currently assigned table, it becomes the assigned table.
Returns:: The number of warning messages issued.
Return type:: int

lookup(name, column=0)[source]

Lookup function returning information about the PDS3 label as it has been applied to the current table.

Each of the following function calls returns a valid PDS3 parameter value. Columns can be identified by name or by number starting from 1.

lookup(“PATH”)
lookup(“BASENAME”)
lookup(“RECORD_TYPE”)
lookup(“RECORD_BYTES”)
lookup(“FILE_RECORDS”)
lookup(“INTERCHANGE_FORMAT”)
lookup(“ROWS”)
lookup(“COLUMNS”)
lookup(“ROW_BYTES”)
lookup(“DATA_TYPE”, <column>)
lookup(“START_BYTE”, <column>)
lookup(“BYTES”, <column>)
lookup(“COLUMN_NUMBER”, <column>)
lookup(“FORMAT”, <column>)
lookup(“UNIT”, <colnum>)
lookup(“MINIMUM_VALUE”, <column>)
lookup(“MAXIMUM_VALUE”, <column>)
lookup(“DERIVED_MINIMUM”, <column>)
lookup(“DERIVED_MAXIMUM”, <column>)

It also provides these values derived from the existing template or label: “NAME”, “ITEMS”, “SCALING_FACTOR”, “OFFSET”, “INVALID_CONSTANT”, “MISSING_CONSTANT”, “NOT_APPLICABLE_CONSTANT”, “NULL_CONSTANT”, “UNKNOWN_CONSTANT”, “VALID_MINIMUM”, and “VALID_MAXIMUM”.

In addition, these options are supported:

lookup(“TABLE_PATH”): full path to the associated ASCII table file.
lookup(“TABLE_BASENAME”): basename of the associated ASCII table file.
lookup(“FIRST”, <column>): value from the first row of this column.
lookup(“LAST”, <column>): value from the last row of this column.

Parameters:

name (str) – Name of a parameter.
column (str or int, optional) – The name or COLUMN_NUMBER (starting at 1) for a column; use 0 for general parameters.

Returns:

The correct PDS3-formatted value for the specified parameter.

Return type:

str

old_lookup(name, column=0)[source]

Lookup function returning information about the current content of the PDS3 label, whether or not it is correct.

Available top-level keywords are “RECORD_TYPE”, “RECORD_BYTES”, “FILE_RECORDS”, “INTERCHANGE_FORMAT”, “ROWS”, “COLUMNS”, and “ROW_BYTES”.

Available column-level keywords are “NAME”, “COLUMN_NUMBER”, “DATA_TYPE”, “START_BYTE”, “BYTES”, “FORMAT”, “ITEMS”, “ITEM_BYTES”, “ITEM_OFFSET”, “SCALING_FACTOR”, “OFFSET”, “UNIT”, “INVALID_CONSTANT”, “MISSING_CONSTANT”, “NOT_APPLICABLE_CONSTANT”, “NULL_CONSTANT”, “UNKNOWN_CONSTANT”, “VALID_MAXIMUM”, “VALID_MINIMUM”, “MINIMUM_VALUE”, “MAXIMUM_VALUE”, “DERIVED_MINIMUM”, and “DERIVED_MAXIMUM”.

Parameters:

name (str) – Name of a parameter.
column (str or int, optional) – The name or COLUMN_NUMBER (starting at 1) for a column; use 0 for general parameters.

Returns:

The current value of the specified parameter; None if it is not found in the label.

Return type:

int, float, str, or None

LABEL_VALUE(name, column=0)

Lookup function returning information about the PDS3 label as it has been applied to the current table.

Each of the following function calls returns a valid PDS3 parameter value. Columns can be identified by name or by number starting from 1.

lookup(“PATH”)
lookup(“BASENAME”)
lookup(“RECORD_TYPE”)
lookup(“RECORD_BYTES”)
lookup(“FILE_RECORDS”)
lookup(“INTERCHANGE_FORMAT”)
lookup(“ROWS”)
lookup(“COLUMNS”)
lookup(“ROW_BYTES”)
lookup(“DATA_TYPE”, <column>)
lookup(“START_BYTE”, <column>)
lookup(“BYTES”, <column>)
lookup(“COLUMN_NUMBER”, <column>)
lookup(“FORMAT”, <column>)
lookup(“UNIT”, <colnum>)
lookup(“MINIMUM_VALUE”, <column>)
lookup(“MAXIMUM_VALUE”, <column>)
lookup(“DERIVED_MINIMUM”, <column>)
lookup(“DERIVED_MAXIMUM”, <column>)

It also provides these values derived from the existing template or label: “NAME”, “ITEMS”, “SCALING_FACTOR”, “OFFSET”, “INVALID_CONSTANT”, “MISSING_CONSTANT”, “NOT_APPLICABLE_CONSTANT”, “NULL_CONSTANT”, “UNKNOWN_CONSTANT”, “VALID_MINIMUM”, and “VALID_MAXIMUM”.

In addition, these options are supported:

lookup(“TABLE_PATH”): full path to the associated ASCII table file.
lookup(“TABLE_BASENAME”): basename of the associated ASCII table file.
lookup(“FIRST”, <column>): value from the first row of this column.
lookup(“LAST”, <column>): value from the last row of this column.

Parameters:

name (str) – Name of a parameter.
column (str or int, optional) – The name or COLUMN_NUMBER (starting at 1) for a column; use 0 for general parameters.

Returns:

The correct PDS3-formatted value for the specified parameter.

Return type:

str

OLD_LABEL_VALUE(name, column=0)

Lookup function returning information about the current content of the PDS3 label, whether or not it is correct.

Available top-level keywords are “RECORD_TYPE”, “RECORD_BYTES”, “FILE_RECORDS”, “INTERCHANGE_FORMAT”, “ROWS”, “COLUMNS”, and “ROW_BYTES”.

Available column-level keywords are “NAME”, “COLUMN_NUMBER”, “DATA_TYPE”, “START_BYTE”, “BYTES”, “FORMAT”, “ITEMS”, “ITEM_BYTES”, “ITEM_OFFSET”, “SCALING_FACTOR”, “OFFSET”, “UNIT”, “INVALID_CONSTANT”, “MISSING_CONSTANT”, “NOT_APPLICABLE_CONSTANT”, “NULL_CONSTANT”, “UNKNOWN_CONSTANT”, “VALID_MAXIMUM”, “VALID_MINIMUM”, “MINIMUM_VALUE”, “MAXIMUM_VALUE”, “DERIVED_MINIMUM”, and “DERIVED_MAXIMUM”.

Parameters:

name (str) – Name of a parameter.
column (str or int, optional) – The name or COLUMN_NUMBER (starting at 1) for a column; use 0 for general parameters.

Returns:

The current value of the specified parameter; None if it is not found in the label.

Return type:

int, float, str, or None

pdstemplate.asciitable

asciitable is a plug-in module to assist with the labeling of ASCII tables in PDS3 and PDS4. It supports the pdstemplate.pds3table module and the tablelabel tool, and will also be used by a future pds4table tool. To import:

import pdstemplate.asciitable

This import creates two new pds-defined functions, which can be accessed within any template.

ANALYZE_TABLE() takes the path to an existing ASCII table and analyzes its content, inferring details about the content and formats of all the columns.
TABLE_VALUE() returns information about the content of the table for use within the label to be generated.

For example, consider a template that contains this content:

$ONCE(ANALYZE_TABLE(LABEL_PATH().replace('.lbl', '.tab')))
...
OBJECT              = TABLE
  ...
  ROWS              = $TABLE_VALUE('ROWS')$
  COLUMNS           = $TABLE_VALUE('COLUMNS')$

  OBJECT            = COLUMN
    NAME            = FILE_NAME
    DATA_TYPE       = $TABLE_VALUE("PDS3_DATA_TYPE", 1)$
    START_BYTE      = $TABLE_VALUE("START_BYTE", 1)$
    BYTES           = $TABLE_VALUE("BYTES", 1)$
    FORMAT          = $TABLE_VALUE("PDS3_FORMAT", 1))$
    MINIMUM_VALUE   = $TABLE_VALUE("MINIMUM", 1))$
    MAXIMUM_VALUE   = $TABLE_VALUE("MAXIMUM", 1))$
    DESCRIPTION     = "Name of file in the directory"
  END_OBJECT        = COLUMN
...

The initial call to ANALYZE_TABLE() is embedded inside a ONCE directive because it returns no content. However, it reads the table file and assembles a database of what it has found. The subsequent calls to it can be used for multiple labels and each label will always contain the correct numbers of ROWS and COLUMNS. TABLE_VALUE() can also retrieve information about the content and format about each of the table’s columns.

pdstemplate.asciitable.ANALYZE_TABLE(filepath, *, separator=',', crlf=None, escape='')[source]

Analyze the given table and define it as the default table for subsequent calls to TABLE_VALUE() inside a template.

Parameters:

filepath (str, Path, or FCPath) – The path to an ASCII table file.
separator (str, optional) – The column separator character, typically a comma. Other options are semicolon, tab, and vertical bar (“|”).
crlf (bool, optional) – True to raise an error if the line terminators are not <CR><LF>; False to raise an error if the line terminator is not <LF> alone; None to accept either line terminator.
escape (str, optional) – The character to appear before a quote (‘”’) if the quote is to be taken as a literal part of the string. Options are ‘”’ for a doubled quote and ‘' for a backslash. If not specified, quote characters inside quoted strings are disallowed.

pdstemplate.asciitable.TABLE_VALUE(name, column=0)[source]

Lookup function for information about the table analyzed in the most recent call to ANALYZE_TABLE().

These are all the options; a column is indicated by an integer starting from zero:

TABLE_VALUE(“PATH”) = full path to the table file.
TABLE_VALUE(“BASENAME”) = basename of the table file.
TABLE_VALUE(“ROWS”) = number of rows.
TABLE_VALUE(“ROW_BYTES”) = bytes per row.
TABLE_VALUE(“COLUMNS”) = number of columns.
TABLE_VALUE[“TERMINATORS”] = length of terminator: 1 for <LF>, 2 for <CR><LF>.
TABLE_VALUE(“WIDTH”, <column>) = width of the column in bytes.
TABLE_VALUE(“PDS3_FORMAT”, <column>) = a string containing the format for PDS3, e.g.,”I7”, “A23”, or “F12.4”.
TABLE_VALUE(“PDS4_FORMAT”, <column>) = a string containing the format for PDS4, e.g., “%7d”, “%23s”, or “%12.4f”.
‘TABLE_VALUE(“PDS3_DATA_TYPE”, <column>)` = PDS3 data type, one of CHARACTER, “ASCII_REAL”, “ASCII_INTEGER”, or “TIME”.
‘TABLE_VALUE(“PDS4_DATA_TYPE”, <column>)` = PDS3 data type, e.g., “ASCII_Text_Preserved”, “ASCII_Real”, or “ASCII_Date_YMD”.
‘TABLE_VALUE(“QUOTES”, <column>)` = number of quotes before field value, 0 or 1.
‘TABLE_VALUE(“START_BYTE”, <column>)` = start byte of column, starting from 1.
‘TABLE_VALUE(“BYTES”, <column>)` = number of bytes in column, excluding quotes.
‘TABLE_VALUE(“VALUES”, <column>)` = a list of all the values found in the column.
‘TABLE_VALUE(“MINIMUM”, <column>)` = the minimum value in the column.
‘TABLE_VALUE(“MAXIMUM”, <column>)` = the maximum value in the column.
‘TABLE_VALUE(“FIRST”, <column>)` = the first value in the column.
‘TABLE_VALUE(“LAST”, <column>)` = the last value in the column.

Parameters:

name (str) – Name of a parameter.
column (int, optional) – The index of the column, starting from zero.

Returns:

The value of the specified parameter as inferred from the ASCII table.

Return type:

str, int, float, or bool

Raises:

TemplateAbort – If no ASCII Table was successfully analyzed.
TemplateError – A wrapper for any other exception.

class pdstemplate.asciitable.AsciiTable(filepath, content=[], *, separator=',', crlf=None, escape='')[source]

Bases: object

__init__(filepath, content=[], *, separator=',', crlf=None, escape='')[source]

Constructor for an AsciiTable.

Parameters:

filepath (str, Path, or FCPath) – The path to an ASCII table file.
content (bytes or list[bytes], optional) – The table file content as a byte string or sequence of byte strings. If this input is empty, the file will be read; otherwise, this content is used without reading the file. Line terminators must be included.
separator (str, optional) – The column separator character, typically a comma. Other options are semicolon, tab, and vertical bar (“|”).
crlf (bool, optional) – True to raise an error if the line terminators are not <CR><LF>; False to raise an error if the line terminator is not <LF> alone; None to accept either line terminator.
escape (str, optional) – The character to appear before a quote (‘”’) if the quote is to be taken as a literal part of the string. Options are ‘”’ for a doubled quote and ‘' for a backslash. If not specified, quote characters inside quoted strings are disallowed.

lookup(name, column=0)[source]

Lookup function for information about this AsciiTable.

These are all the options; a column is indicated by an integer starting from zero:

lookup(“PATH”) = full path to the table file.
lookup(“BASENAME”) = basename of the table file.
lookup(“ROWS”) = number of rows.
lookup(“ROW_BYTES”) = bytes per row.
lookup(“COLUMNS”) = number of columns.
lookup[“TERMINATORS”] = length of terminator: 1 for <LF>, 2 for <CR><LF>.
lookup(“WIDTH”, <column>) = width of the column in bytes.
lookup(“PDS3_FORMAT”, <column>) = a string containing the format for PDS3, e.g.,”I7”, “A23”, or “F12.4”.
lookup(“PDS4_FORMAT”, <column>) = a string containing the format for PDS4, e.g., “%7d”, “%23s”, or “%12.4f”.
lookup(“PDS3_DATA_TYPE”, <column>) = PDS3 data type, one of “CHARACTER”, “ASCII_REAL”, “ASCII_INTEGER”, or “TIME”.
lookup(“PDS4_DATA_TYPE”, <column>) = PDS3 data type, e.g., “ASCII_Text_Preserved”, “ASCII_Real”, or “ASCII_Date_YMD”.
lookup(“QUOTES”, <column>) = number of quotes before field value, 0 or 1.
lookup(“START_BYTE”, <column>) = start byte of column, starting from 1.
lookup(“BYTES”, <column>) = number of bytes in column, excluding quotes.
lookup(“VALUES”, <column>) = a list of all the values found in the column.
lookup(“MINIMUM”, <column>) = the minimum value in the column.
lookup(“MAXIMUM”, <column>) = the maximum value in the column.
lookup(“FIRST”, <column>) = the first value in the column.
lookup(“LAST”, <column>) = the last value in the column.

Parameters:

name (str) – Name of a parameter.
column (int, optional) – The index of the column, starting from zero.

Returns:

The value of the specified parameter as inferred: from the table.

Return type:

(str, int, float, or bool)

TABLE_VALUE(name, column=0)

Lookup function for information about this AsciiTable.

These are all the options; a column is indicated by an integer starting from zero:

lookup(“PATH”) = full path to the table file.
lookup(“BASENAME”) = basename of the table file.
lookup(“ROWS”) = number of rows.
lookup(“ROW_BYTES”) = bytes per row.
lookup(“COLUMNS”) = number of columns.
lookup[“TERMINATORS”] = length of terminator: 1 for <LF>, 2 for <CR><LF>.
lookup(“WIDTH”, <column>) = width of the column in bytes.
lookup(“PDS3_FORMAT”, <column>) = a string containing the format for PDS3, e.g.,”I7”, “A23”, or “F12.4”.
lookup(“PDS4_FORMAT”, <column>) = a string containing the format for PDS4, e.g., “%7d”, “%23s”, or “%12.4f”.
lookup(“PDS3_DATA_TYPE”, <column>) = PDS3 data type, one of “CHARACTER”, “ASCII_REAL”, “ASCII_INTEGER”, or “TIME”.
lookup(“PDS4_DATA_TYPE”, <column>) = PDS3 data type, e.g., “ASCII_Text_Preserved”, “ASCII_Real”, or “ASCII_Date_YMD”.
lookup(“QUOTES”, <column>) = number of quotes before field value, 0 or 1.
lookup(“START_BYTE”, <column>) = start byte of column, starting from 1.
lookup(“BYTES”, <column>) = number of bytes in column, excluding quotes.
lookup(“VALUES”, <column>) = a list of all the values found in the column.
lookup(“MINIMUM”, <column>) = the minimum value in the column.
lookup(“MAXIMUM”, <column>) = the maximum value in the column.
lookup(“FIRST”, <column>) = the first value in the column.
lookup(“LAST”, <column>) = the last value in the column.

Parameters:

name (str) – Name of a parameter.
column (int, optional) – The index of the column, starting from zero.

Returns:

The value of the specified parameter as inferred: from the table.

Return type:

(str, int, float, or bool)

pdstemplate.pds3_syntax_checker

pds3_syntax_checker is a function that raises an exception if the given label string does not strictly conform to the PDS3 standard. It can be used as a postprocessor input to the PdsTemplate constructor and will ensure that each newly-generated PDS3 label is free of syntax errors.

To use:

from pdstemplate._pds3_syntax_checker import pds3_syntax_checker

In the template constructor, specify:

template = PdsTemplate(..., postprocess=pds3_syntax_checker)

pdstemplate.pds3_syntax_checker.pds3_syntax_checker(content)[source]

Post-processer to raise a TemplateAbort on a PDS3 parser error; otherwise, return content as is.

Parameters:: content (str) – The content of a label as a string with newlines as line terminators.
Returns:: The original content of the label, unchanged.
Raises:: TemplateAbort – If the pdsparser module identifies a syntax error.

pdstemplate Module

Getting Started

Template Syntax

Substitutions

Headers

FOR and END_FOR

IF, ELSE_IF, ELSE, and END_IF

ONCE

INCLUDE

NOTE and END_NOTE

Pre-defined Functions

Logging and Exception Handling

Pre-processors

pdstemplate.utils

pdstemplate.pds3table

pdstemplate.asciitable

pdstemplate.pds3_syntax_checker

`pdstemplate` Module