wcs.parser¶

Utility methods for parsing XML into wcs.model objects.

Functions¶

`parse_describe_coverage`(xml_string)	Parses an XML string from a DescribeCoverage response into a `wcs.model.FullCoverage`.
`parse_domain_set`(domain_set_element)	Parses an XML element representing a DomainSet into corresponding objects.
`parse_range_type`(range_type_element)	Parses an XML element representing a RangeType into a `wcs.model.RangeType` object.
`parse_metadata`(metadata_element)	Parse an XML Metadata element into a dictionary. Example XML structure:
`parse_coverage_summaries`(xml_string[, only_local])	Parses CoverageSummary XML elements from a GetCapabilities XML string.
`parse_coverage_summary`(element[, only_local])	Parses an XML element representing a Coverage Summary into a BasicCoverage object.
`parse_wgs84_bounding_box`(element)	Parses an XML element representing a WGS84 bounding box into a tuple of lon/lat
`parse_bounding_box`(bbox_element[, crs])	Parses an XML element representing a bounding box into a BoundingBox object.
`parse_additional_parameters`(element)	Parses additional parameters from an XML element into a dict of key/value strings.
`parse_bounds_list`(element_text)	Parses a space-separated string of axis bounds into a list of properly
`parse_bound`(bound)	Parses a given axis bound string into its appropriate data type.
`crs_to_crs_per_axis`(crs)	Convert a single CRS to a list of CRS per axis.
`get_child`(element, tag[, throw_if_not_found])	Retrieve a child element matching a given `tag` from an XML element.
`first_child`(element[, expected_tag])	Retrieve the first child element of an XML element.
`parse_tag_name`(element)	Extract just the tag name of an XML element, removing namespace components.
`validate_tag_name`(element, expected_tag)	Validate the tag name of an XML element against an expected tag.
`element_to_string`(element)	Serialize an XML element to a string.
`element_to_dict`(t)	Convert an XML element into a nested dictionary.

Module Contents¶

parse_describe_coverage(xml_string)[source]¶

Parses an XML string from a DescribeCoverage response into a wcs.model.FullCoverage.

It extracts essential information including the coverage name, metadata, domain set, and range type. The extracted data is used to construct and return a wcs.model.FullCoverage object.

Parameters:

xml_string (Union[str, bytes]) – An XML string or bytes object containing the DescribeCoverage document. The XML should contain elements such as ‘CoverageDescription’, ‘Metadata’, ‘DomainSet’, and ‘RangeType’.

Returns:

A wcs.model.FullCoverage object constructed from the parsed XML data.

Raises:

WCSClientException – If the XML does not contain a valid ‘CoverageDescription’ element or if the parsing process encounters any other issues.
ET.ParseError – If the XML string is malformed and cannot be parsed.

Return type:

wcs.model.FullCoverage

parse_domain_set(domain_set_element)[source]¶

Parses an XML element representing a DomainSet into corresponding objects.

It extracts information about spatio-temporal regular/irregular axes, and constructs geo and grid wcs.model.BoundingBox objects. Example XML structure:

<cis11:DomainSet>
  <cis11:GeneralGrid
    srsName="https://www.opengis.net/def/crs-compound?
    1=https://www.opengis.net/def/crs/OGC/0/AnsiDate&amp;
    2=https://www.opengis.net/def/crs/EPSG/0/4326"
    axisLabels="ansi Lat Lon">
    <cis11:RegularAxis axisLabel="Lat" uomLabel="degree"
      lowerBound="-90" upperBound="90" resolution="-0.1"/>
    <cis11:RegularAxis axisLabel="Lon" uomLabel="degree"
      lowerBound="-180" upperBound="180" resolution="0.1"/>
    <cis11:IrregularAxis axisLabel="ansi" uomLabel="d">
      <cis11:C>"2000-02-01T00:00:00.000Z"</cis11:C>
      <cis11:C>"2000-03-01T00:00:00.000Z"</cis11:C>
    </cis11:IrregularAxis>
    <cis11:GridLimits
      srsName="http://www.opengis.net/def/crs/OGC/0/Index3D"
      axisLabels="i j k">
      <cis11:IndexAxis axisLabel="i"
        lowerBound="0" upperBound="184"/>
      <cis11:IndexAxis axisLabel="j"
        lowerBound="0" upperBound="1799"/>
      <cis11:IndexAxis axisLabel="k"
        lowerBound="0" upperBound="3599"/>
    </cis11:GridLimits>
  </cis11:GeneralGrid>
</cis11:DomainSet>

Parameters:: domain_set_element (Optional[xml.etree.ElementTree.Element]) – An XML element representing the DomainSet structure. It should contain one or more ‘cis11:GeneralGrid’ elements, which in turn include ‘cis11:RegularAxis’ or ‘cis11:IrregularAxis’ elements, and a ‘cis11:GridLimits’ element.
Returns:: A tuple containing geo and grid BoundingBox objects. If the input is None, the function returns (None, None).
Raises:: WCSClientException – If the provided XML does not conform to the expected structure.
Return type:: tuple[Optional[wcs.model.BoundingBox], Optional[wcs.model.BoundingBox]]

parse_range_type(range_type_element)[source]¶

Parses an XML element representing a RangeType into a wcs.model.RangeType object.

This function processes an XML element handling either ‘swe:Category’ or ‘swe:Quantity’ fields within a ‘swe:DataRecord’. It extracts fields information such as field name, definition, label, description, codespace, unit of measurement, and nil values, constructing a list of wcs.model.Field objects that are then encapsulated within a wcs.model.RangeType object.

Supported XML structures:

swe:Category field:

<cis11:RangeType>
  <swe:DataRecord>
    <swe:field name="land_use">
      <swe:Category definition="...">
        <swe:label>National Land Use</swe:label>
        <swe:description>description text</swe:description>
        <swe:nilValues>
          <swe:NilValues>
            <swe:nilValue reason="">0</swe:nilValue>
          </swe:NilValues>
        </swe:nilValues>
        <swe:codeSpace xlink:href="...."/>
      </swe:Category>
    </swe:field>
  </swe:DataRecord>
</cis11:RangeType>

swe:Quantity field:

<cis11:RangeType>
  <swe:DataRecord>
    <swe:field name="temperature">
      <swe:Quantity definition="...">
        <swe:label>Monthly temperature</swe:label>
        <swe:description>description text</swe:description>
        <swe:nilValues>
          <swe:NilValues>
            <swe:nilValue reason="">-9999</swe:nilValue>
          </swe:NilValues>
        </swe:nilValues>
        <swe:uom code="°C"/>
      </swe:Quantity>
    </swe:field>
  </swe:DataRecord>
</cis11:RangeType>

Parameters:: range_type_element (Optional[xml.etree.ElementTree.Element]) – An XML element representing the RangeType structure. It should contain one or more ‘swe:DataRecord’ elements, each with ‘swe:field’ elements that can be either ‘swe:Category’ or ‘swe:Quantity’.
Returns:: A RangeType object containing a list of Field objects. Each Field object represents either a ‘swe:Category’ or ‘swe:Quantity’ extracted from the XML, with associated metadata. If the input is None, then None is returned.
Raises:: WCSClientException – If the provided XML does not conform to the expected structure.
Return type:: Optional[wcs.model.RangeType]

parse_metadata(metadata_element)[source]¶

Parse an XML Metadata element into a dictionary. Example XML structure:

<Metadata>
  <covMetadata>
    <title>Temperature</title>
    <abstract>Monthly average air temperature.</abstract>
    <description>Description.</description>
    <keywords>climate, temperature</keywords>
  </covMetadata>
  <rasdamanCoverageMetadata>
    <catalog>
      <title>Temperature</title>
      <thumbnail>https://localhost/thumbnail.png</thumbnail>
      <description>Description.</description>
      <provenance sourceUrl="https://localhost"
        providerName="P" termsUrl="http://localhost"/>
      <ourTerms>https://localhost/#terms</ourTerms>
    </catalog>
  </rasdamanCoverageMetadata>
  <otherMetadata role="https://codelists" title="Catalog"
    href="https://localhost"/>
</Metadata>

Parameters:: metadata_element (Optional[xml.etree.ElementTree.Element]) – An XML element containing metadata information. This element is expected to have the tag ‘Metadata’.
Returns:: A dictionary representation of the metadata contained within the XML element. Nested elements are converted to nested dicts. Element attributes convert to key names starting with ‘@’. If the input is None or an empty XML element, an empty dictionary is returned.
Raises:: WCSClientException – If the root tag of metadata_element is not ‘Metadata’.
Return type:: dict

parse_coverage_summaries(xml_string, only_local=False)[source]¶

Parses CoverageSummary XML elements from a GetCapabilities XML string.

This function takes an XML string representing a GetCapabilities response, searches for the ‘Contents’ element, and extracts all ‘CoverageSummary’ elements within it. Each ‘CoverageSummary’ element is parsed into a wcs.model.BasicCoverage object using the parse_coverage_summary() function.

Parameters:

xml_string (Union[str, bytes]) – A GetCapabilities XML string, provided as either a string or bytes object.
only_local (bool) – parse only local coverages, filtering out any remote coverages.

Returns:

A list of BasicCoverage objects, each representing a parsed CoverageSummary element from the XML.

Raises:

WCSClientException – If the XML does not contain a ‘Contents’ element, indicating an invalid GetCapabilities document.

Return type:

list[wcs.model.BasicCoverage]

parse_coverage_summary(element, only_local=False)[source]¶

Parses an XML element representing a Coverage Summary into a BasicCoverage object. Example XML structure:

<wcs20:CoverageSummary>
  <wcs20:CoverageId>AverageChloroColorScaled</wcs20:CoverageId>
  <wcs20:CoverageSubtype>ReferenceableGridCoverage
  </wcs20:CoverageSubtype>
  <ows:WGS84BoundingBox>
    <ows:LowerCorner>-180 -90</ows:LowerCorner>
    <ows:UpperCorner>180 90</ows:UpperCorner>
  </ows:WGS84BoundingBox>
  <ows:BoundingBox
    crs="https://www.opengis.net/def/crs-compound?
    1=https://www.opengis.net/def/crs/OGC/0/AnsiDate&amp;
    2=https://www.opengis.net/def/crs/EPSG/0/4326"
    dimensions="3">
    <ows:LowerCorner>
        "2002-07-01T00:00:00.000Z" -90 -180
    </ows:LowerCorner>
    <ows:UpperCorner>
        "2015-05-01T00:00:00.000Z" 90 180
    </ows:UpperCorner>
  </ows:BoundingBox>
  <ows:AdditionalParameters>
    <ows:AdditionalParameter>
      <ows:Name>sizeInBytes</ows:Name>
      <ows:Value>188325000</ows:Value>
    </ows:AdditionalParameter>
    <ows:AdditionalParameter>
      <ows:Name>axisList</ows:Name>
      <ows:Value>ansi,Lat,Lon</ows:Value>
    </ows:AdditionalParameter>
  </ows:AdditionalParameters>
</wcs20:CoverageSummary>

Parameters:

element (Optional[xml.etree.ElementTree.Element]) – An XML element representing a CoverageSummary. it should contain ‘CoverageId’ and a ‘CoverageSubtype’, and optionally ‘WGS84BoundingBox’, ‘BoundingBox’, and ‘AdditionalParameters’.
only_local (bool) – parse only local coverages, filtering out any remote coverages.

Returns:

A BasicCoverage object containing coverage information extracted from the XML, or None if element is None or only_local is True and the coverage is remote.

Raises:

WCSClientException – If the coverage_summary_element does not have the expected tag, or is missing a ‘CoverageId’ element.

Return type:

Optional[wcs.model.BasicCoverage]

parse_wgs84_bounding_box(element)[source]¶

Parses an XML element representing a WGS84 bounding box into a tuple of lon/lat wcs.model.Axis objects. Example XML structure:

<ows:WGS84BoundingBox>
    <ows:LowerCorner>-180 -90</ows:LowerCorner>
    <ows:UpperCorner>180 90</ows:UpperCorner>
</ows:WGS84BoundingBox>

Parameters:: element (Optional[xml.etree.ElementTree.Element]) – A ‘WGS84BoundingBox’ XML element containing ‘LowerCorner’ and ‘UpperCorner’ elements.
Returns:: a tuple of lon/lat wcs.model.Axis objects, or None if the input element is None.
Raises:: WCSClientException – If the element tag is not ‘WGS84BoundingBox’.
Return type:: Optional[tuple[wcs.model.Axis, wcs.model.Axis]]

parse_bounding_box(bbox_element, crs=None)[source]¶

Parses an XML element representing a bounding box into a BoundingBox object. Example XML structure:

<ows:BoundingBox
  crs="https://www.opengis.net/def/crs-compound?
  1=https://www.opengis.net/def/crs/OGC/0/AnsiDate&amp;
  2=https://www.opengis.net/def/crs/EPSG/0/4326" dimensions="3">
  <ows:LowerCorner>
    "2002-07-01T00:00:00.000Z" -90 -180
  </ows:LowerCorner>
  <ows:UpperCorner>
    "2015-05-01T00:00:00.000Z" 90 180
  </ows:UpperCorner>
</ows:BoundingBox>

Parameters:

bbox_element (Optional[xml.etree.ElementTree.Element]) – An XML element representing the bounding box. It should contain ‘LowerCorner’ and ‘UpperCorner’ child elements.
crs (str) – An optional CRS identifier string. If not provided, the CRS is inferred from the ‘crs’ attribute of the bbox_element.

Returns:

A wcs.model.BoundingBox object containing the parsed CRS and axis lower/upper bounds.

Raises:

WCSClientException – If the parsing of ‘LowerCorner’ or ‘UpperCorner’ elements fails.

Return type:

Optional[wcs.model.BoundingBox]

parse_additional_parameters(element)[source]¶

Parses additional parameters from an XML element into a dict of key/value strings. Example XML structure:

<ows:AdditionalParameters>
    <ows:AdditionalParameter>
        <ows:Name>sizeInBytes</ows:Name>
        <ows:Value>188325000</ows:Value>
    </ows:AdditionalParameter>
    <ows:AdditionalParameter>
        <ows:Name>axisList</ows:Name>
        <ows:Value>ansi,Lat,Lon</ows:Value>
    </ows:AdditionalParameter>
</ows:AdditionalParameters>

Parameters:: element (xml.etree.ElementTree.Element) – An XML element containing ‘AdditionalParameter’ child elements. Each ‘AdditionalParameter’ element is expected to contain a ‘Name’ and a ‘Value’ sub-element.
Returns:: A dictionary mapping parameter names to their values.
Raises:: WCSClientException – If an unexpected element is found, or if ‘Name’ or ‘Value’ elements are missing.
Return type:: dict[str, str]

parse_bounds_list(element_text)[source]¶

Parses a space-separated string of axis bounds into a list of properly typed bound values. Each string bound is parsed with parse_bound().

Parameters:: element_text (Optional[str]) – A space-separated string containing bound values.
Returns:: A list of parsed bounds, where each bound is of type BoundType.
Raises:: WCSClientException – If any bound in the list cannot be parsed into a supported type by parse_bound().
Return type:: list[wcs.model.BoundType]

parse_bound(bound)[source]¶

Parses a given axis bound string into its appropriate data type.

The method attempts to interpret the input bound in several formats:

A string representing a datetime in ISO 8601 format.
A raw string if it starts with a “ but failed to parse as a datetime.
A string representing an integer.
A string representing a float.

Parameters:: bound (Optional[str]) – A string representing the bound value to be parsed. It can be a string datetime in ISO 8601 format (optionally in double quotes), an integer, or a float.
Returns:: The parsed bound in its appropriate data type. Returns None` if the input is None`.
Raises:: WCSClientException – If the bound` cannot be parsed into any of the supported types.
Return type:: Optional[wcs.model.BoundType]

crs_to_crs_per_axis(crs)[source]¶

Convert a single CRS to a list of CRS per axis. If crs contains crs-compound, i.e. it is a compund CRS, then it is split first into it’s component CRS. For each crs then, - it is added twice into the result list if ‘EPSG’ is contained in it - otherwise, it is added once into the result list

Returns:: a list of CRS per axis, or an empty list if crs is None.
Parameters:: crs (str)
Return type:: list[str]

get_child(element, tag, throw_if_not_found=True)[source]¶

Retrieve a child element matching a given tag from an XML element.

Parameters:

element (xml.etree.ElementTree.Element) – The XML element to search for a child with the specified tag. The tags of child elements are parsed to remove namespaces before comparison with the parse_parse_tag_name() method.
tag (str) – The tag name of the child element to search for; it should not include any namespaces.
throw_if_not_found – If True, raises an exception when no matching child is found. If False, returns None instead.

Returns:

The first child element with the specified tag, or None if not found throw_if_not_found is False.

Raises:

WCSClientException – If no child with the specified tag is found and throw_if_not_found is True.

Return type:

Optional[xml.etree.ElementTree.Element]

first_child(element, expected_tag=None)[source]¶

Retrieve the first child element of an XML element.

Optionally, it can validate the tag of the first child against an expected tag (without any namespaces). If no children are present, it raises a wcs.model.WCSClientException.

Parameters:

element (xml.etree.ElementTree.Element) – The XML element whose first child is to be retrieved.
expected_tag (str) – The expected tag name of the first child element. If provided, the function will validate the tag of the first child.

Returns:

The first child element of the given XML element.

Raises:

WCSClientException – If the element has no children or if the tag of the first child does not match the expected tag.

Return type:

Optional[xml.etree.ElementTree.Element]

parse_tag_name(element)[source]¶

Extract just the tag name of an XML element, removing namespace components. Example: “{http://www.example.com}root” -> “root”

Parameters:: element (Union[xml.etree.ElementTree.Element, str]) – An XML element from which to extract the tag name.
Returns:: The tag name of the element.
Return type:: str

validate_tag_name(element, expected_tag)[source]¶

Validate the tag name of an XML element against an expected tag.

This function checks if the tag name of the given XML element matches the expected tag. It uses the parse_tag_name() function to remove any namespaces in the tag name. If the tag names do not match, it raises a wcs.model.WCSClientException.

Parameters:

element (xml.etree.ElementTree.Element) – The XML element whose tag name is to be validated.
expected_tag (str) – The expected tag name to validate against.

Raises:

WCSClientException – If the tag name of the element does not match the expected tag.

element_to_string(element)[source]¶

Serialize an XML element to a string.

Parameters:: element (xml.etree.ElementTree.Element) – The XML element to serialize.
Returns:: A Unicode string representation of the XML element.
Return type:: str

element_to_dict(t)[source]¶

Convert an XML element into a nested dictionary.

This function recursively converts an XML element and its children into a nested dictionary. The keys of the dictionary are the tag names of the XML elements. Attributes of the XML elements are prefixed with ‘@’ in the dictionary keys, and text content is stored under a ‘#text’ key.

Parameters:

t (xml.etree.ElementTree.Element) – The XML element to convert.

Returns:

A nested dictionary representing the structure and content of the XML element.

Note:

Elements with multiple children having the same tag name are converted into lists.
Text content is only added to the dictionary if the element has children or attributes, to avoid overwriting important data with whitespace.

Return type:

dict

wcs.parser¶

Functions¶

Module Contents¶

WCS Python Client

Navigation

Related Topics