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=u'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_root : ElementTree 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_root : ElementTree Element

Root element of the PDS4 label or label portion.

convenient_namespace_map : dict, optional

Keys are the namespace URIs and values are the prefixes for the convenient root of this label.

unmodified_namespace_map : dict, optional

Keys are the namespace URIs and values are the prefixes for the unmodified root of this label.

default_root : str 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:

key : int 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=u'convenient')[source]

Create Label from a PDS4 XML label file.

Parameters:

filename : str or unicode

Filename, including path, to XML label.

default_root : str 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.
text
Returns:Text of element.
tail
Returns:Tail of element.
tag
Returns:Tag of element.
attrib
Returns:Attributes of element.
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:

key : str or unicode

Attribute name to select.

default : optional

Value to return if no attribute matching key is found. Defaults to None.

unmodified : bool 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:

unmodified : bool 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:

match : str or unicode

XPATH search string.

namespaces : dict, optional

Dictionary with keys corresponding to prefix and values corresponding to URI for namespaces.

unmodified : bool 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_ET : bool, 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:

match : str or unicode

XPATH search string

namespaces : dict, optional

Dictionary with keys corresponding to prefix and values corresponding to URI for namespaces.

unmodified : bool 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_ET : bool, 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:

match : str or unicode

XPATH search string.

default : optional

Value to return if no match is found. Defaults to None.

namespaces : dict, optional

Dictionary with keys corresponding to prefixes and values corresponding to URIs for namespace.

unmodified : bool 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:

unmodified : bool 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_print : bool, 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:

unmodified : bool 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_attributes : bool, optional

If True, skips adding attributes from XML. Defaults to False.

cast_values : bool, 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_ignore : tuple[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:

unmodified : bool 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:

unmodified : bool, 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_ET : bool, 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

valid (bool) 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_settings : Label 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:

label : Label or ElementTree Element

The entire label for the PDS4 product containing the Display Settings.

structure_lid : str 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_structure : Label 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

valid (bool) 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_chars : Label 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:

label : Label or ElementTree Element

The entire label for the PDS4 product containing the Spectral Characteristics.

structure_lid : str 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:

label : Label or ElementTree Element

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:

label : Label or ElementTree Element

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_identifier : str or unicode

The local identifier of the data structure to which the display settings belong.

label : Label 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_identifier : str or unicode

The local identifier of the data structure to which the spectral characteristics belong.

label : Label 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.