ccsds_ndm.kvn_tokenizer

KVN tokenizer: convert raw KVN text into a list of classified line objects.

This module provides:

• KvnLine and its subclasses for representing each line format

• tokenize() to convert raw KVN source into KvnLine objects

Functions

tokenize(kvn_source)

Convert a raw KVN string into an ordered list of KvnLine objects.

Classes

BlankLine()	A whitespace-only (or completely empty) line.
CommentLine([text])	A COMMENT line.
CovarianceRowLine([tokens])	A space-separated row of plain numbers inside a covariance block.
KvLine([key, value, unit])	A standard KEY = value [unit] line.
KvnLine()	Abstract base class for a single tokenised KVN line.
PackedDataLine([epoch, tokens])	A space-separated data row whose first token is an epoch.
SectionMarkerLine([key])	A block-delimiter keyword.
TdmObsLine([key, epoch, value, unit])	A TDM observation line: KEY = EPOCH  value.

class BlankLine

A whitespace-only (or completely empty) line.

to_str(**kwargs)

Render this line to a KVN string (no trailing newline).

Subclasses accept keyword arguments relevant to their own format. Unknown kwargs are silently ignored, so callers can pass a common set (e.g. key_width=24) to all line types without special-casing.

Return type:

str

class CommentLine(text='')

A COMMENT line.

The comment text is stored in text with leading/trailing whitespace stripped. Both the plain (COMMENT text) and equals (COMMENT = text) variants are normalised to plain on construction; to_str always writes the plain form.

Parameters:

text (str)

to_str(**kwargs)

Render this line to a KVN string (no trailing newline).

Subclasses accept keyword arguments relevant to their own format. Unknown kwargs are silently ignored, so callers can pass a common set (e.g. key_width=24) to all line types without special-casing.

Return type:

str

class CovarianceRowLine(tokens=<factory>)

A space-separated row of plain numbers inside a covariance block.

OEM covariance matrix rows contain only numeric tokens with no epoch and no key. Each row represents one row of the lower-triangular matrix: v11, v21  v22, v31  v32  v33, …

Parameters:

tokens (list[str])

tokens

The numeric tokens on this row.

Type:

list[str]

to_str(**kwargs)

Render this line to a KVN string (no trailing newline).

Subclasses accept keyword arguments relevant to their own format. Unknown kwargs are silently ignored, so callers can pass a common set (e.g. key_width=24) to all line types without special-casing.

Return type:

str

class KvLine(key='', value='', unit='')

A standard KEY = value [unit] line.

Parameters:

• key (str)

• value (str)

• unit (str)

key

The KVN keyword (e.g. "EPOCH", "OBJECT_NAME").

Type:

str

value

The scalar value string, stripped of surrounding whitespace and units.

Type:

str

unit

Unit string extracted from the trailing [...], or empty if absent.

Type:

str

to_str(key_width=24, **kwargs)

Render this line to a KVN string (no trailing newline).

Subclasses accept keyword arguments relevant to their own format. Unknown kwargs are silently ignored, so callers can pass a common set (e.g. key_width=24) to all line types without special-casing.

Parameters:

key_width (int)

Return type:

str

class KvnLine

Abstract base class for a single tokenised KVN line.

Subclasses represent each distinct line format found in KVN files. Every subclass implements to_str() to render itself back to a canonical KVN string, making round-trip writing straightforward: build a list of KvnLine instances, call to_str() on each, and join with newlines.

abstractmethod to_str(**kwargs)

Render this line to a KVN string (no trailing newline).

Subclasses accept keyword arguments relevant to their own format. Unknown kwargs are silently ignored, so callers can pass a common set (e.g. key_width=24) to all line types without special-casing.

Return type:

str

class PackedDataLine(epoch='', tokens=<factory>)

A space-separated data row whose first token is an epoch.

Used for OEM state vectors and AEM attitude states, where an entire record is encoded on a single line with no explicit keys: EPOCH  x  y  z  x_dot  y_dot  z_dot

Parameters:

• epoch (str)

• tokens (list[str])

epoch

The epoch string (first token, also available as tokens[0]).

Type:

str

tokens

All whitespace-separated tokens on the line (epoch + numeric values).

Type:

list[str]

to_str(**kwargs)

Render this line to a KVN string (no trailing newline).

Subclasses accept keyword arguments relevant to their own format. Unknown kwargs are silently ignored, so callers can pass a common set (e.g. key_width=24) to all line types without special-casing.

Return type:

str

class SectionMarkerLine(key='')

A block-delimiter keyword.

Examples: META_START, META_STOP, DATA_START, DATA_STOP, COVARIANCE_START, COVARIANCE_STOP.

Parameters:

key (str)

to_str(**kwargs)

Render this line to a KVN string (no trailing newline).

Subclasses accept keyword arguments relevant to their own format. Unknown kwargs are silently ignored, so callers can pass a common set (e.g. key_width=24) to all line types without special-casing.

Return type:

str

class TdmObsLine(key='', epoch='', value='', unit='')

A TDM observation line: KEY = EPOCH  value.

TDM data lines carry an epoch and a numeric value in the value field, separated by whitespace, rather than a single scalar.

Parameters:

• key (str)

• epoch (str)

• value (str)

• unit (str)

key

The observation keyword (e.g. "TRANSMIT_FREQ_1").

Type:

str

epoch

The epoch token (e.g. "2007-075T11:50:43.000").

Type:

str

value

The numeric observation value as a string.

Type:

str

unit

Unit string, or empty if absent.

Type:

str

to_str(key_width=24, **kwargs)

Render this line to a KVN string (no trailing newline).

Subclasses accept keyword arguments relevant to their own format. Unknown kwargs are silently ignored, so callers can pass a common set (e.g. key_width=24) to all line types without special-casing.

Parameters:

key_width (int)

Return type:

str

tokenize(kvn_source)

Convert a raw KVN string into an ordered list of KvnLine objects.

Each input line is classified and parsed into the appropriate subclass. The rules applied in order are:

1. Strip surrounding whitespace. Empty result → BlankLine.

2. Line is in _SECTION_MARKERS → SectionMarkerLine.

3. Line starts with "COMMENT" → CommentLine. A leading "=" after "COMMENT" is stripped (handles the COMMENT = text variant).

4. Line contains "=":

   1. Split on the first "=" into key and rest.

   2. Extract a trailing [unit] from rest if present.

   3. Split remaining rest on whitespace. Two tokens where the first looks like an epoch → TdmObsLine. Otherwise → KvLine.

5. No "=" — split on whitespace:

   1. First token looks like an epoch → PackedDataLine.

   2. Otherwise → CovarianceRowLine.

Blank lines that appear before the first CCSDS_ header line are dropped so that files with a leading blank or BOM are handled cleanly.

Parameters:

kvn_source (str) – Raw KVN text (Windows or Unix line endings accepted).

Returns:

list[KvnLine] – Ordered list of classified line objects.

Return type:

list[KvnLine]