pds4_tools.reader.label_objects module¶

Classes¶

`Label`([convenient_root, unmodified_root, ...])	Stores a PDS4 label or a portion of a PDS4 label.
`Meta_DisplaySettings`(args, *kwds)	Stores PDS4 Display Settings meta data for a single PDS4 data structure.
`Meta_SpectralCharacteristics`(args, *kwds)	Stores PDS4 Spectral Characteristics meta data for a single PDS4 data structure.

Functions¶

`get_mission_area`(label)	Search a PDS4 label for a Mission_Area.
`get_discipline_area`(label)	Search a PDS4 label for a Discipline_Area.
`get_display_settings_for_lid`(...)	Search a PDS4 label for Display_Settings of a data structure with local_identifier.
`get_spectral_characteristics_for_lid`(...)	Search a PDS4 label for Spectral_Characteristics of a data structure with local_identifier.

Details¶

class Label(convenient_root=None, unmodified_root=None, convenient_namespace_map=None, unmodified_namespace_map=None, default_root='convenient')[source]¶

Bases: object

Stores a PDS4 label or a portion of a PDS4 label.

This class is similar to an ElementTree Element; most of the basic attributes and methods for Element will also work here. Some additional convenience methods and features are provided to make it easier to work with PDS4 labels.

Parameters

(in general `from_file` should be used instead of using __init__)
convenient_rootElementTree Element: Root element of the PDS4 label or label portion, modified to normalize whitespace in all element and attribute values containing a single non-whitespace line, to strip the default namespace, and to use the default PDS4 prefixes for known namespaces.
unmodified_rootElementTree Element: Root element of the PDS4 label or label portion.
convenient_namespace_mapdict, optional: Keys are the namespace URIs and values are the prefixes for the convenient root of this label.
unmodified_namespace_mapdict, optional: Keys are the namespace URIs and values are the prefixes for the unmodified root of this label.
default_rootstr or unicode, optional: Specifies whether the root element used by default when calling methods and attributes in this object will be the convenient_root or unmodified_root. Must be one of ‘convenient’ or ‘unmodified’. Defaults to convenient.

Examples

To load a label from file,

>>> lbl = Label.from_file('/path/to/label.xml')

To search the entire label for logical_identifier (of which only one is allowed),

>>> lbl.find('.//logical_identifier')

To search the entire label for Display Settings in the ‘disp’ namespace (of which there could be multiple),

>>> display_settings = lbl.findall('.//disp:Display_Settings')

To search the Display Settings for the top-level element, Display_Direction,

>>> display_settings.find('disp:Display_Direction')

See method descriptions for more info.

__getitem__(key)[source]¶

Obtain subelement.

Parameters

keyint or slice: Specifies which subelement to select.

Returns

Label: Subelement of label.

__len__()[source]¶

Returns

int: Number of (direct) subelements this label has.

classmethod from_file(filename, default_root='convenient')[source]¶

Create Label from a PDS4 XML label file.

Parameters

filenamestr or unicode: Filename, including path, to XML label.
default_rootstr or unicode, optional: Specifies whether the root element used by default when calling methods and attributes in this object will be the convenient_root or unmodified_root. Must be one of convenient|unmodified. Defaults to convenient.

Returns

Label: Instance, with the contents being taken from filename.

property text¶

Returns

Text of element.

property tail¶

Returns

Tail of element.

property tag¶

Returns

Tag of element.

property attrib¶

Returns

Attributes of element.

property default_root¶

Returns

str or unicode: Either ‘convenient’ or ‘unmodified’. Specifies whether the root element used by default when calling methods and attributes in this object will be the convenient_root or unmodified_root.

get(key, default=None, unmodified=None)[source]¶

Gets the element attribute named key.

Uses the same format as ElementTree.get.

Parameters

keystr or unicode: Attribute name to select.
defaultoptional: Value to return if no attribute matching key is found. Defaults to None.
unmodifiedbool or None: Looks for key in unmodified ElementTree root if True, or the convenient one if False. Defaults to None, which uses Label.default_root to decide.

Returns

Value of the attribute named key if it exists, or default otherwise.

getroot(unmodified=None)[source]¶

Obtains ElementTree root Element instance underlying this object.

Parameters

unmodifiedbool or None or None, optional: If True, returns the unmodified (see Label docstring for meaning) ElementTree Element. If False, returns convenient root. Defaults to None, which uses Label.default_root to decide.

Returns

Element instance: The ElementTree root element backing this Label.

find(match, namespaces=None, unmodified=None, return_ET=False)[source]¶

Search for the first matching subelement.

Uses the same format as ElementTree.find. See Label docstring or ElementTree.find documentation for examples and supported XPATH description.

The namespaces found in the label, and those contained in the PDS4_NAMESPACES constant are registered automatically. If match contains other namespace prefixes then you must pass in namespaces parameter specifying the URI for each prefix. In case of duplicate prefixes for the same URI, prefixes in the label overwrite those in PDS4_NAMESPACES, and prefixes in namespaces overwrite both.

Parameters

matchstr or unicode: XPATH search string.
namespacesdict, optional: Dictionary with keys corresponding to prefix and values corresponding to URI for namespaces.
unmodifiedbool or None, optional: Searches unmodified ElementTree root if True, or the convenient one if False. Defaults to None, which uses Label.default_root to decide.
return_ETbool, optional: Returns an ElementTree Element instead of a Label if True. Defaults to False.

Returns

Label, ElementTree Element or None: Matched subelement, or None if there is no match.

findall(match, namespaces=None, unmodified=None, return_ET=False)[source]¶

Search for all matching subelements.

Uses the same format as ElementTree.findall. See Label docstring or ElementTree.findall documentation for examples and supported XPATH description.

The namespaces found in the label, and those contained in the PDS4_NAMESPACES constant are registered automatically. If match contains other namespace prefixes then you must pass in namespaces parameter specifying the URI for each prefix. In case of duplicate prefixes for the same URI, prefixes in the label overwrite those in PDS4_NAMESPACES, and prefixes in namespaces overwrite both.

Parameters

matchstr or unicode: XPATH search string
namespacesdict, optional: Dictionary with keys corresponding to prefix and values corresponding to URI for namespaces.
unmodifiedbool or None, optional: Searches unmodified ElementTree root if True, or the convenient one if False. Defaults to None, which uses Label.default_root to decide.
return_ETbool, optional: Returned list contains ElementTree Elements instead of Labels if True. Defaults to False.

Returns

List[Label or ElementTree Element]: Matched subelements, or [] if there are no matches.

findtext(match, default=None, namespaces=None, unmodified=None)[source]¶

Finds text for the first subelement matching match.

Uses the same format as ElementTree.findtext. See Label docstring or ElementTree.findtext documentation for examples and supported XPATH description.

The namespaces found in the label, and those contained in the PDS4_NAMESPACES constant are registered automatically. If match contains other namespace prefixes then you must pass in namespaces parameter specifying the URI for each prefix. In case of duplicate prefixes for the same URI, prefixes in the label overwrite those in PDS4_NAMESPACES, and prefixes in namespaces overwrite both.

Parameters

matchstr or unicode: XPATH search string.
defaultoptional: Value to return if no match is found. Defaults to None.
namespacesdict, optional: Dictionary with keys corresponding to prefixes and values corresponding to URIs for namespace.
unmodifiedbool or None, optional: Searches unmodified ElementTree root if True, or the convenient one if False. Defaults to None, which uses Label.default_root to decide.

Returns

Text of the first matched element, or default otherwise.

to_string(unmodified=True, pretty_print=False)[source]¶

Generate a string representation of XML label.

Parameters

unmodifiedbool or None, optional: Generates representation of unmodified ElementTree root if True, or the convenient one if False. None uses Label.default_root to decide. Defaults to True.
pretty_printbool, optional: String representation is pretty-printed if True. Defaults to False.

Returns

unicode or str: String representation of Label.

to_dict(unmodified=None, skip_attributes=True, cast_values=False, cast_ignore=())[source]¶

Generate an OrderedDict representation of XML label.

Parameters

unmodifiedbool or None, optional: Generates representation of unmodified ElementTree root if True, or the convenient one if False. Defaults to None, which uses Label.default_root to decide.
skip_attributesbool, optional: If True, skips adding attributes from XML. Defaults to False.
cast_valuesbool, optional: If True, float and int compatible values of element text and attribute values will be cast as such in the output dictionary. Defaults to False.
cast_ignoretuple[str or unicode], optional: If given, then a tuple of element tags and/or attribute names. If cast_values is True, then for elements and attributes matching exactly the values in this tuple, values will not be cast. Attribute names must be prepended by an ‘@’. Empty by default.

Returns

OrderedDict: A dictionary representation of Label.

get_namespace_map(unmodified=None)[source]¶

Obtain namespace map.

Parameters

unmodifiedbool or None, optional: If True, returns the namespace map for the unmodified (see Label docstring) label. If False, it uses the convenient label. Defaults to None, which uses Label.default_root to decide.

Returns

dict: A dict with keys being the namespace URIs and values being the namespace prefixes for this label.

copy(unmodified=None, return_ET=False)[source]¶

Obtain a deepcopy of this Label.

Parameters

unmodifiedbool, optional: If return_ET is True, then setting this to True will return a copy of the unmodified ElementTree root, or the convenient one if False. Defaults to None, which uses Label.default_root to decide.
return_ETbool, optional: Returned value is a ElementTree Element instead of Label if True. Defaults to False.

Returns

Label or ElementTree Element

class Meta_DisplaySettings(*args, **kwds)[source]¶

Bases: pds4_tools.reader.general_objects.Meta_Class

Stores PDS4 Display Settings meta data for a single PDS4 data structure.

Meta data stored in this class is accessed in dict-like fashion. Normally this meta data originates from the label (from the beginning of the Display_Settings tag, to its closing tag), via the from_label or from_full_label methods.

Attributes

validbool: True if Display Settings conform to supported PDS4 Standards, False otherwise.

classmethod from_label(xml_display_settings)[source]¶

Create a Meta_DisplaySettings from the XML portion describing it.

Parameters

xml_display_settingsLabel or ElementTree Element: The portion of the label describing the Display_Settings.

Returns

Meta_SpectralCharacteristics: Instance containing display settings meta data.

classmethod from_full_label(label, structure_lid)[source]¶

Loads meta data into self from XML.

Parameters

labelLabel or ElementTree Element: The entire label for the PDS4 product containing the Display Settings.
structure_lidstr or unicode: The local_identifier for the Array data structure which uses the Display Settings.

Returns

Meta_DisplaySettings: Instance containing display settings meta data for a particular data structure.

Raises

KeyError: Raised if Display Settings do not exist for the specified structure_lid.
PDS4StandardsException: Raised if a data structure having the local_identifier structure_lid was not found.

is_valid(xml_structure=None, raise_on_error=False)[source]¶

Checks if the the Display Settings to conform to supported PDS4 Standards.

Parameters

xml_structureLabel or ElementTree Element, optional: Portion of label describing the Array data structure which uses the Display Settings. If given, will validate that the Array data structure has the axes referred to by the Display Settings.
raise_on_error: bool, optional: If True, raised if Display Settings found are invalid or unsupported. Defaults to False.

Returns

bool: True if Display Settings are both valid and supported, False otherwise.

Raises

PDS4StandardsException: Raised if raise_on_error is True and if the Display Settings are invalid or unsupported.

class Meta_SpectralCharacteristics(*args, **kwds)[source]¶

Bases: pds4_tools.reader.general_objects.Meta_Class

Stores PDS4 Spectral Characteristics meta data for a single PDS4 data structure.

Meta data stored in this class is accessed in dict-like fashion. Normally this meta data originates from the label (from the beginning of the Spectral_Characteristics tag, to its closing tag), via the from_label or from_full_label methods.

Attributes

validbool: True if the Spectral Characteristics conform to supported PDS4 Standards, False otherwise.

classmethod from_label(xml_spectral_chars)[source]¶

Create a Meta_SpectralCharacteristics from the XML portion describing it.

Parameters

xml_spectral_charsLabel or ElementTree Element: The portion of the label describing the Spectral_Characteristics.

Returns

Meta_SpectralCharacteristics: Instance containing spectral characteristics meta data.

classmethod from_full_label(label, structure_lid)[source]¶

Loads meta data into self from XML.

Parameters

labelLabel or ElementTree Element: The entire label for the PDS4 product containing the Spectral Characteristics.
structure_lidstr or unicode: The local_identifier for the Array data structure which uses the Spectral Characteristics.

Returns

Meta_SpectralCharacteristics: Instance containing spectral characteristics meta data for a particular data structure.

Raises

KeyError: Raised if Spectral Characteristics do not exist for the specified structure_lid
PDS4StandardsException: Raised if a data structure having the local_identifier structure_lid was not found

is_valid(xml_structure=None, raise_on_error=False)[source]¶

get_mission_area(label)[source]¶

Search a PDS4 label for a Mission_Area.

Parameters

labelLabel or ElementTree Element: Full label for a PDS4 product with-in which to look for a mission area.

Returns

Label, ElementTree Element or None: Found Mission_Area section with same return type as label, or None if not found.

get_discipline_area(label)[source]¶

Search a PDS4 label for a Discipline_Area.

Parameters

labelLabel or ElementTree Element: Full label for a PDS4 product with-in which to look for a discipline area.

Returns

Label, ElementTree Element or None: Found Discipline_Area section with same return type as label, or None if not found.

get_display_settings_for_lid(local_identifier, label)[source]¶

Search a PDS4 label for Display_Settings of a data structure with local_identifier.

Parameters

local_identifierstr or unicode: The local identifier of the data structure to which the display settings belong.
labelLabel or ElementTree Element: Label for a PDS4 product with-in which to look for the display settings.

Returns

Label, ElementTree Element or None: Found Display_Settings section with same return type as label, or None if not found.

get_spectral_characteristics_for_lid(local_identifier, label)[source]¶

Search a PDS4 label for Spectral_Characteristics of a data structure with local_identifier.

Parameters

local_identifierstr or unicode: The local identifier of the data structure to which the spectral characteristics belong.
labelLabel or ElementTree Element: Label for a PDS4 product with-in which to look for the spectral characteristics.

Returns

Label, ElementTree Element or None: Found Spectral_Characteristics section with same return type as label, or None if not found.

pds4_tools.reader.label_objects module¶

Classes¶

Functions¶

Details¶

Table of Contents

Previous topic

Next topic

This Page