3.1. routeutils package

3.1.1. Submodules

3.1.2. routeutils.routing module

Routing Webservice for EIDA

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

Copyright:

2014-2023 Helmholtz Centre Potsdam GFZ German Research Centre for Geosciences, Potsdam, Germany

License:

GPLv3

Platform:

Linux

Module author: Javier Quinteros <javier@gfz-potsdam.de>, GEOFON, GFZ Potsdam

routeutils.routing.ConvertDictToXml(listdict)

Convert a list with dictionaries to an XML ElementTree Element.

Parameters:

listdict (list) – Dictionaries

Returns:

XML Tree with the dictionaries received as parameter.

Return type:

xml.etree.cElementTree.Element

routeutils.routing.applyFormat(resultRM: RequestMerge, outFormat: str = 'xml') str

Apply the format specified to the RequestMerge object received.

Parameters:
  • resultRM (RequestMerge) – List with the result of a query.

  • outFormat (string) – Output format for the result.

Return type:

string

Returns:

Transformed version of the input in the desired format

routeutils.routing.lsNSLC(net: list, sta: list, loc: list, cha: list) Tuple

Iterator providing NSLC tuples from comma separated components.

Parameters:
  • net (list) – Network code(s) in comma-separated format.

  • sta (list) – Station code(s) in comma-separated format.

  • loc (list) – Location code(s) in comma-separated format.

  • cha (list) – Channel code(s) in comma-separated format.

Return type:

tuple

Returns:

NSLC tuples

3.1.3. routeutils.unittestTools module

Classes to be used in the tests.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

Copyright:

2014-2023 Helmholtz Centre Potsdam GFZ German Research Centre for Geosciences, Potsdam, Germany

License:

GPLv3

Platform:

Linux

Module author: Javier Quinteros <javier@gfz-potsdam.de>, GEOFON, GFZ Potsdam

class routeutils.unittestTools.WITestResult(testRunner, mode=1)

Bases: TestResult

A test result class that prints in colours to the console.

addError(test, err)

Wrapper to add a faulty test and customize the output.

addFailure(test, err)

Wrapper to add a test with failure and customize the output.

addSuccess(test)

Wrapper to add a successful test and customize the output.

printErrorList(errorType, errors)

Wrapper to print a list of errors customizing the output.

printErrors()

Wrapper to print a summary of errors customizing the output.

startTest(test)

Wrapper to start the test and customize the output.

class routeutils.unittestTools.WITestRunner(outStream=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, mode=1)

Bases: object

Class in charge of running the tests.

run(test)

Run the given test case.

write(message)

Redirect output to the stream.

3.1.4. routeutils.utils module

Classes to be used by the Routing WS for EIDA.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

Copyright:

2014-2023 Helmholtz Centre Potsdam GFZ German Research Centre for Geosciences, Potsdam, Germany

License:

GPLv3

Platform:

Linux

Module author: Javier Quinteros <javier@gfz-potsdam.de>, GEOFON, GFZ Potsdam

class routeutils.utils.FDSNRules(rm: RequestMerge = None, eidadcs: list = None)

Bases: dict

Based on a dict, but all functionality is in the datacentres list

which groups data from many requests by datacenter.

Platform:

Any

append(service: str, url: str, priority: int, stream: Stream, tw: TW)

Append a new Route without repeating the datacenter.

Overrides the append method of the inherited list. If another route for the datacenter was already added, the remaining attributes are appended in datasets for the datacenter. If this is the first Route for the datacenter, everything is added.

Parameters:
  • service (str) – Service name (f.i., ‘dataselect’)

  • url (str) – URL for the service (f.i., ‘http://server/path/query’)

  • priority (int) – Priority of the Route (1: highest priority)

  • stream (Stream) – Stream(s) associated with the Route

  • tw (TW) – Start date for the Route

extend(listReqM: RequestMerge)

Append all the items in RequestMerge grouped by datacenter.

Overrides the extend method of the inherited list. If another route for the datacenter was already added, the remaining attributes are appended in params for the datacenter. If this is the first Route for the datacenter, everything is added.

Parameters:

listReqM (list of RequestMerge) – Requests from (possibly) different datacenters to be added

index(service: str, url: str) Tuple[int, int]

Given a service and url returns the index on the list where the routes/rules should be added. If the data centre is still not in the list returns a KeyError with an index to the eidaDCs list. That is the DC to add. If both searches fail an Exception is raised.

class routeutils.utils.GeoRectangle(minlat, maxlat, minlon, maxlon)

Bases: GeoRectangle

Namedtuple representing a geographical rectangle.

minlat: minimum latitude maxlat: maximum latitude minlon: minimum longitude maxlon: maximum longitude

Platform:

Any

contains(lat: Number, lon: Number) bool

Check if the point belongs to the rectangle.

class routeutils.utils.RequestMerge(iterable=(), /)

Bases: list

Extend a list to group data from many requests by datacenter.

Platform:

Any

append(service: str, url: str, priority: int, stream: Stream, tw: TW)

Append a new Route without repeating the datacenter.

Overrides the append method of the inherited list. If another route for the datacenter was already added, the remaining attributes are appended in params for the datacenter. If this is the first Route for the datacenter, everything is added.

Parameters:
  • service (str) – Service name (f.i., ‘dataselect’)

  • url (str) – URL for the service (f.i., ‘http://server/path/query’)

  • priority (int) – Priority of the Route (1: highest priority)

  • stream (Stream) – Stream(s) associated with the Route

  • tw (TW) – Time window for the Route

extend(listreqm: RequestMerge)

Append all the items in RequestMerge grouped by datacenter.

Overrides the extend method of the inherited list. If another route for the datacenter was already added, the remaining attributes are appended in params for the datacenter. If this is the first Route for the datacenter, everything is added.

Parameters:

listreqm (list of RequestMerge) – Requests from (posibly) different datacenters to be added

index(service: str, url: str) int

Check for the service and url specified in the parameters.

This overrides the index method of the inherited list.

Parameters:
  • service (str) – Requests from (possibly) different datacenters to be added

  • url (str) – Address of the service provided by a datacenter

Returns:

position in the list where the service and url specified can be found

Return type:

int

Raises:

ValueError

class routeutils.utils.Route(service, address, tw, priority)

Bases: Route

Namedtuple defining a Route.

The attributes are

service: service name address: a URL tw: timewindow priority: priority of the route

Platform:

Any

overlap(otherroute: Route) bool

Check if there is an overlap between this route and otherroute.

Parameters:

otherroute (Route) – Route which should be checked for overlaps

Returns:

Value specifying whether there is an overlap between this stream and the one passed as a parameter

Return type:

Bool

toxml(namespace: str = 'ns0', level: int = 2) str

Export the Route to an XML representation.

class routeutils.utils.RoutingCache(routingfile: str = None, config: str = 'routing.cfg')

Bases: object

Manage routing information of streams read from an Arclink-XML file.

Platform:

Linux (maybe also Windows)

endpoints() str

Read the list of endpoints from the configuration file.

Returns:

List of URLs from endpoints including this RS instance

Return type:

str

getRoute(stream: Stream, tw: TW, service: str = 'dataselect', geoloc: GeoRectangle = None, alternative: bool = False) RequestMerge

Return routes to request data for the stream and timewindow provided.

Based on a stream(s) and a timewindow returns all the needed information (URLs and parameters) to do the requests to different datacenters (if needed) and be able to merge the returned data avoiding duplication.

Parameters:
  • stream (Stream) – Stream definition including wildcards

  • tw (TW) – Timewindow

  • service (str) – Comma-separated list of services to get information from

  • geoloc (GeoRectangle) – Rectangle to filter stations

  • alternative (bool) – Specifies whether alternative routes should be included

Returns:

URLs and parameters to request the data

Return type:

RequestMerge

Raises:

RoutingException

getRouteDS(service: str, stream: Stream, tw: TW, geolocation: GeoRectangle = None, alternative: bool = False) RequestMerge

Return routes to request data for the parameters specified.

Based on a Stream and a timewindow (TW) returns all the needed information (URLs and parameters) to request waveforms from different datacenters (if needed) and be able to merge it avoiding duplication.

Parameters:
  • service (str) – Specifies the service is being looked for

  • stream (Stream) – Stream definition including wildcards

  • tw (TW) – Timewindow

  • geolocation (GeoRectangle) – Rectangle restricting the location of the station

  • alternative (bool) – Specifies whether alternative routes should be included

Returns:

URLs and parameters to request the data

Return type:

RequestMerge

Raises:

RoutingException, ValueError

globalConfig(fmt: str = 'fdsn') str

Return the global routing configuration.

Returns:

Global routing information in FDSN format

Return type:

str

localConfig(fmt: str = 'xml') str

Return the local routing configuration.

Returns:

Local routing information in Arclink-XML format

Return type:

str

toXML(foutput: str, namespace: str = 'ns0')

Export the RoutingCache to an XML representation.

update()

Read the routing data from the file saved by the off-line process.

All the routing information is read into a dictionary. Only the necessary attributes are stored. This relies on the idea that some other agent should update the routing data at a regular period of time.

updateAll()

Read the two sources of routing information.

updateVN()

Read the virtual networks defined.

Stations listed in each virtual network are read into a dictionary. Only the necessary attributes are stored. This relies on the idea that some other agent should update the routing file at a regular period of time.

virtualNets() str

Return the virtual networks defined in the system

Returns:

Virtual networks in this system in JSON format

Return type:

str

vn2real(stream: Stream, tw: TW) list

Transform from a virtual network code to a list of streams.

Parameters:
  • stream (Stream) – requested stream including virtual network code.

  • tw (TW) – time window requested.

Returns:

Streams and time windows of real network-station codes.

Return type:

list

exception routeutils.utils.RoutingException

Bases: Exception

Exception raised to flag a problem when searching for routes.

class routeutils.utils.Station(name, latitude, longitude, start, end)

Bases: Station

Namedtuple representing a Station.

This is the minimum information which needs to be cached from a station in order to be able to apply a proper filter to the inventory when queries f.i. do not include the network name.

name: station name latitude: latitude longitude: longitude

Platform:

Any

class routeutils.utils.Stream(n, s, l, c)

Bases: Stream

Namedtuple representing a Stream.

It includes methods to calculate matching and overlapping of streams including (or not) wildcards. Components are the usual to determine a stream:

n: network s: station l: location c: channel

Platform:

Any

overlap(other: Stream) bool

Check if there is an overlap between this stream and other one.

Parameters:

other (Stream) – Stream which should be checked for overlaps

Returns:

Value specifying whether there is an overlap between this stream and the one passed as a parameter

Return type:

Bool

strictmatch(other: Stream) Stream

Return a reduction of this stream to match what’s been received.

Parameters:

other (Stream) – Stream which should be checked for overlaps

Returns:

reduced version of this Stream to match the one passed in the parameter

Return type:

Stream

Raises:

Exception

toxmlclose(namespace: str = 'ns0', level: int = 1) str

Close the XML representation of a route given by toxmlopen.

toxmlopen(namespace: str = 'ns0', level: int = 1) str

Export the stream to XML representing a route.

XML representation is incomplete and needs to be closed by the method toxmlclose.

class routeutils.utils.TW(start, end)

Bases: TW

Namedtuple with methods to perform calculations on timewindows.

Attributes are:

start: Start datetime end: End datetime

Platform:

Any

difference(othertw: TW) List[TW]

Substract othertw from this TW.

The result is a list of TW. This operation does not modify the data in the current timewindow.

Parameters:

othertw (TW) – timewindow which should be substracted from this one

Returns:

Difference between this timewindow and the one in the parameter

Return type:

list of TW

intersection(othertw: TW) TW

Calculate the intersection between othertw and this TW.

This operation does not modify the data in the current timewindow.

Parameters:

othertw (TW) – timewindow which should be intersected with this one

Returns:

Intersection between this timewindow and the one in the parameter

Return type:

TW

overlap(othertw: TW) bool

Check if the othertw is contained in this TW.

Parameters:

othertw (TW) – timewindow which should be checked for overlapping

Returns:

Value specifying whether there is an overlap between this timewindow and the one in the parameter

Return type:

Bool

Raises:

ValueError if start is greater than end

Examples

>>> y2011 = datetime.datetime(2011, 1, 1)
>>> y2012 = datetime.datetime(2012, 1, 1)
>>> y2013 = datetime.datetime(2013, 1, 1)
>>> y2014 = datetime.datetime(2014, 1, 1)
>>> TW(y2011, y2014).overlap(TW(y2012, y2013))
True
>>> TW(y2012, y2014).overlap(TW(y2011, y2013))
True
>>> TW(y2012, y2013).overlap(TW(y2011, y2014))
True
>>> TW(y2011, y2012).overlap(TW(y2013, y2014))
False
routeutils.utils.addremote(filename: str, url: str, method: str = 'localconfig')

Read the routing file from a remote datacenter and store it in memory.

All the routing information is read into a dictionary. Only the necessary attributes are stored.

Parameters:
  • filename (str) – file where the routes should be saved

  • url (str) – Base URL from the Routing Service at the remote datacenter

  • method (str) – Method from the remote RS to be called

Raise:

Exception

routeutils.utils.addroutes(filename: str, **kwargs) dict

Read the routing file in XML format and store it in memory.

All the routing information is read into a dictionary. Only the necessary attributes are stored. This relies on the idea that some other agent should update the routing file at regular periods of time.

Parameters:
  • filename (str) – File with routes to add the the routing table.

  • **kwargs

    See below

Returns:

Updated routing table containing routes from the input file.

Return type:

dict

Keyword Arguments:
  • routingtable (dict) Routing Table where routes should be added to.

routeutils.utils.addvirtualnets(filename: str, **kwargs) dict

Read the routing file in XML format and store its VNs in memory.

All information related to virtual networks is read into a dictionary. Only the necessary attributes are stored. This relies on the idea that some other agent should update the routing file at regular periods of time.

Parameters:
  • filename (str) – File with virtual networks to add to the routing table.

  • **kwargs

    See below

Returns:

Updated table containing aliases from the input file.

Return type:

dict

Keyword Arguments:
  • vnTable (dict) Table with virtual networks where aliases should be added.

routeutils.utils.cachestations(routingtable: dict, stationtable: dict)

Loop for all station-WS and cache all station names and locations.

Parameters:
  • routingtable (dict) – Routing table.

  • stationtable (dict) – Cache with names and locations of stations.

routeutils.utils.checkOverlap(str1: Stream, routelist: list, str2: Stream, route: Route) bool

Check overlap of routes from stream str1 and a route from str2.

Parameters:
  • str1 (Stream) – First stream

  • routelist (list) – List of routes already present

  • str2 (Stream) – Second stream

  • route (Route) – Route to be checked

Return type:

boolean

Returns:

Value indicating if routes overlap for both streams

routeutils.utils.getStationCache(st: Stream, rt: Route) List[Station]

Retrieve station name and location from a particular station service.

Parameters:
  • st (Stream) – Stream for which a cache should be saved.

  • rt (Route) – Route where this stream is archived.

Returns:

Stations found in this route for this stream pattern.

Return type:

list

routeutils.utils.replacelast(s: str, old: str, new: str)
routeutils.utils.str2date(dstr: str) datetime

Transform a string to a datetime.

Parameters:

dstr (string) – A datetime in ISO format.

Returns:

A datetime represented the converted input.

Return type:

datetime

3.1.5. routeutils.wsgicomm module

Functions and resources to communicate via a WSGI module

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

Copyright:

2014-2023 Helmholtz Centre Potsdam GFZ German Research Centre for Geosciences, Potsdam, Germany

License:

GPLv3

Platform:

Linux

Module author: Javier Quinteros <javier@gfz-potsdam.de>, GEOFON, GFZ Potsdam

class routeutils.wsgicomm.Logs(level=2, outstr=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Bases: object

Given a log level and a stream, redirect the output to the proper place.

Platform:

Linux

setLevel(level)

Set the level of the log.

Parameters:

level (int) – Log level (1: Error, 2: Warning, 3: Info, 4: Debug)

exception routeutils.wsgicomm.PlsRedirect(url)

Bases: Exception

Exception to signal that the web client must be redirected to a URL.

The constructor of the class receives a string, which is the URL where the web browser is going to be redirected.

exception routeutils.wsgicomm.WIClientError(*args, **kwargs)

Bases: WIError

Exception to signal that an invalid request was received (400).

Platform:

Linux

exception routeutils.wsgicomm.WIContentError(*args, **kwargs)

Bases: WIError

Exception to signal that no content was found (204).

Platform:

Linux

exception routeutils.wsgicomm.WIError(status, body, verbosity=1)

Bases: Exception

Exception to signal that an error occurred.

Platform:

Linux

exception routeutils.wsgicomm.WIInternalError(*args, **kwargs)

Bases: WIError

Exception to signal that an internal server error occurred (500).

Platform:

Linux

exception routeutils.wsgicomm.WIServiceError(*args, **kwargs)

Bases: WIError

Exception to signal that the service is unavailable (503).

Platform:

Linux

exception routeutils.wsgicomm.WIURIError(*args, **kwargs)

Bases: WIError

Exception to signal that the URI is beyond the allowed limit (414).

Platform:

Linux

routeutils.wsgicomm.redirect_page(url, start_response)

Tell the web client through the WSGI module to redirect to a URL.

Platform:

Linux

routeutils.wsgicomm.send_dynamicfile_response(status, body, start_response)

Send a file (or file-like) object.

Caller must set the filename, size and content_type attributes of body.

Platform:

Linux

routeutils.wsgicomm.send_error_response(status, body, start_response)

Send a plain response in WSGI style.

Platform:

Linux

routeutils.wsgicomm.send_file_response(status, body, start_response)

Send a file (or file-like) object.

Caller must set the filename, size and content_type attributes of body.

Platform:

Linux

routeutils.wsgicomm.send_html_response(status, body, start_response)

Send an HTML response in WSGI style.

Platform:

Linux

routeutils.wsgicomm.send_json_response(status, body, start_response)

Send a JSON response in WSGI style.

Platform:

Linux

routeutils.wsgicomm.send_nobody_response(status, start_response)

Send a plain response without body in WSGI style.

Platform:

Linux

routeutils.wsgicomm.send_plain_response(status, body, start_response)

Send a plain response in WSGI style.

Platform:

Linux

routeutils.wsgicomm.send_xml_response(status, body, start_response)

Send an XML response in WSGI style.

Platform:

Linux

3.1.6. Module contents