pds4_tools.reader.header_objects module

Classes

HeaderStructure([structure_data, ...])	Stores a single PDS4 header data structure.
Meta_HeaderStructure	Meta data about a PDS4 header data structure.
HeaderParser([header_structure])	Provides a base class for parsers of any PDS Header object.
HeaderPlainTextParser([header_structure])	A generic parser for any plain-text header.
HeaderFITSParser([header_structure])	A parser for FITS headers.

Details

class HeaderStructure(structure_data=None, structure_meta_data=None, structure_label=None, full_label=None, parent_filename=None, structure_id=None)

Bases: pds4_tools.reader.general_objects.Structure

Stores a single PDS4 header data structure.

Contains the header’s data, meta data and label portion.

See Structure’s and pds4_read’s docstrings for attributes, properties and usage instructions of this object.

Inherits all Attributes, Parameters and Properties from Structure. Overrides info, data and from_file methods to implement them.

classmethod from_file(data_filename, structure_label, full_label, lazy_load=False, no_scale=None, decode_strings=None)

Create an header structure from relevant labels and file for the data.

Parameters

data_filenamestr or unicode

Filename of the data file that contained the data for this array structure.

structure_labelLabel

The segment of the label describing only this array structure.

full_labelLabel

The entire label describing the PDS4 product this structure originated from.

lazy_loadbool, optional

If True, does not read-in the data of this structure until the first attempt to access it. Defaults to False.

no_scaleNone, optional

Has no effect because Headers do not contain data that can be scaled. Defaults to None.

decode_stringsbool, optional

Has no effect because Headers are not necessarily plain-text. See parser method instead. Defaults to None.

Returns

HeaderStructure

An object representing the PDS4 header structure; contains its label, data and meta data.

classmethod from_bytes(input, **structure_kwargs)

Create an header structure from PDS-compliant data.

Parameters

inputbytes, str or unicode

A string or bytes containing the data for header.

structure_kwargsdict, optional

Keywords that are passed directly to the HeaderStructure constructor.

Returns

HeaderStructure

An object representing the PDS4 header structure. The data attribute will contain input. Other attributes may be specified via structure_kwargs.

info(abbreviated=False, output=None)

Prints a summary of this data structure.

Contains the type and dimensions of the Array, and if abbreviated is False then also outputs the name and number of elements of each axis in the array.

Parameters

abbreviatedbool, optional

Has no effect on header data structures.

outputfile, bool or None, optional

A file-like object to write the output to. If set to False then instead of outputting to a file a list representing the summary parameters for the Structure is returned. Writes to sys.stdout by default.

Returns

None or list

If output is False, then returns a list representing the summary parameters for the Structure. Otherwise returns None.

data

All data in the PDS4 header data structure.

This property is implemented as a thread-safe cacheable attribute. Once it is run for the first time, it replaces itself with an attribute having the exact data that was originally returned.

Unlike normal properties, this property/attribute is settable without a __set__ method. To never run the read-in routine inside this property, you need to manually create the the .data attribute prior to ever invoking this method (or pass in the data to the constructor on object instantiation, which does this for you).

Returns

str, unicode or bytes

The header described by this data structure.

parser()

Obtain a parser for the data in the header.

Returns

HeaderParser

A parser for the header.

property data_loaded

Returns

bool

True if the data attribute has been set (e.g. data has been read from file or set), False otherwise.

property id

Returns

str or unicode

The ID (either local identifier if given, or name if given) of this data structure. If neither was given, an ID was likely assigned.

is_array()

Returns

bool

True if this Structure is a form of a PDS4 array, false otherwise.

is_header()

Returns

bool

True if this Structure is a form of a PDS4 header, false otherwise.

is_table()

Returns

bool

True if this Structure is a form of a PDS4 table, false otherwise.

property type

Returns

str, unicode or None

The official PDS4 data structure type name for this structure.

class Meta_HeaderStructure

Bases: pds4_tools.reader.general_objects.Meta_Structure

Meta data about a PDS4 header data structure.

Meta data stored in this class is accessed in dict-like fashion. Normally this meta data originates from the label (e.g., if this is a Header then everything from the opening tag of Header to its closing tag will be stored in this object), via the from_label method.

Inherits all Attributes, Parameters and Properties from Meta_Structure.

Examples

Supposing the following Header definition from a label:

<Header>
  <local_identifier>header</local_identifier>
  <offset unit="byte">0</offset>
  <object_length unit="byte">2880</object_length>
  <parsing_standard_id>FITS 3.0</parsing_standard_id>
</Header>

>>> meta_array = Meta_HeaderStructure.from_label(header_xml)

>>> print(meta_array['local_identifier'])
header

>>> print(meta_array['parsing_standard_id']
FITS 3.0

id

Returns

str or unicode

The local_identifier of the PDS4 data structure if it exists, otherwise the name if it exists. If neither was specified in the label, None is returned.

classmethod from_label(xml_header)

Create a Meta_HeaderStructure from the XML portion describing it in the label.

Parameters

xml_headerLabel or ElementTree Element

Portion of label that defines the Header data structure.

Returns

Meta_HeaderStructure

Instance containing meta data about the header structure, as taken from the XML label.

Raises

PDS4StandardsException

Raised if required meta data is absent.

is_plain_text()

Obtain whether a Header is in plain text.

Under the definition of plain-text taken here, this includes all data that contains “only characters of readable material but not its graphical representation nor other objects (images, etc).”

Returns

bool

True if the Header’s data is plain text, False otherwise.

class HeaderParser(header_structure=None)

Bases: object

Provides a base class for parsers of any PDS Header object.

Parsers for specific header objects should inherit from this class. Where a specific parser is not available, this object may serve as a general parser.

Parameters

header_structureHeaderStructure, optional

The header structure to provide parsing capability for.

Attributes

structureHeaderStructure or None

The header structure to provide parsing capability for.

static get_parser(header_structure)

Factory method to obtain the most specific parser for the data.

Parameters

header_structureHeaderStructure, optional

The header structure to provide a parser for.

Returns

HeaderParser

A parser (whether specific, if available, or generic) for the header.

class HeaderPlainTextParser(header_structure=None)

Bases: pds4_tools.reader.header_objects.HeaderParser

A generic parser for any plain-text header.

to_string()

Returns

str or unicode

An unmodified version of the plain-text string that forms the header.

class HeaderFITSParser(header_structure=None)

Bases: pds4_tools.reader.header_objects.HeaderPlainTextParser

A parser for FITS headers.

to_string()

Returns

str or unicode

A human-readable representation of the FITS header, which leaves it unmodified except for splitting each CARD (80 characters) into their own lines and removing padding.