`siphon.ncss`

Support making data requests to the NetCDF subset service (NCSS) on a TDS.

This includes forming proper queries as well as parsing the returned data.

class siphon.ncss.NCSS(url)[source]

Wrap access to the NetCDF Subset Service (NCSS) on a THREDDS server.

Simplifies access via HTTP to the NCSS endpoint. Parses the metadata, provides data download and parsing based on the appropriate query.

metadata

Contains the result of parsing the NCSS endpoint’s dataset.xml. This has information about the time and space coverage, as well as full information about all of the variables.

Type:: NCSSDataset

variables

Names of all variables available in this dataset

Type:: set(str)

unit_handler

Function to handle units that come with CSV/XML data. Should be a callable that takes a list of string values and unit str (can be None), and returns the desired representation of values. Defaults to ignoring units and returning numpy.array().

Type:: callable

__init__(url)

Create an HTTPEndPoint instance.

Parameters:: url (str) – The base URL for the endpoint

get(path, params=None)

Make a GET request, optionally including a parameters, to a path.

The path of the request is the full URL.

Parameters:

path (str) – The URL to request
params (DataQuery, optional) – The query to pass when making the request

Returns:

resp – The server’s response to the request

Return type:

requests.Response

Raises:

HTTPError – If the server returns anything other than a 200 (OK) code

See also

get_query, get

get_data(query)[source]

Fetch parsed data from a THREDDS server using NCSS.

Requests data from the NCSS endpoint given the parameters in query and handles parsing of the returned content based on the mimetype.

Parameters:

query (NCSSQuery) – The parameters to send to the NCSS endpoint

Returns:

Parsed data response from the server. Exact format depends on the format of the
response.

See also

get_data_raw

get_data_raw(query)[source]

Fetch raw data from a THREDDS server using NCSS.

Requests data from the NCSS endpoint given the parameters in query and returns the raw bytes of the response.

Parameters:: query (NCSSQuery) – The parameters to send to the NCSS endpoint
Returns:: content – The raw, un-parsed, data returned by the server
Return type:: bytes

See also

get_data

get_path(path, query=None)

Make a GET request, optionally including a query, to a relative path.

The path of the request includes a path on top of the base URL assigned to the endpoint.

Parameters:

path (str) – The path to request, relative to the endpoint
query (DataQuery, optional) – The query to pass when making the request

Returns:

resp – The server’s response to the request

Return type:

requests.Response

See also

get_query, get, url_path

get_query(query)

Make a GET request, including a query, to the endpoint.

The path of the request is to the base URL assigned to the endpoint.

Parameters:: query (DataQuery) – The query to pass when making the request
Returns:: resp – The server’s response to the request
Return type:: requests.Response

See also

get_path, get

query()[source]

Return a new query for NCSS.

Returns:: query – The newly created query
Return type:: NCSSQuery

url_path(path)

Assemble the full url to a path.

Given a path relative to the base URL, assemble the full URL.

Parameters:: path (str) – The path, relative to the endpoint
Returns:: url – The full URL to path
Return type:: str

See also

get_path

validate_query(query)[source]

Validate a query.

Determines whether query is well-formed. This includes checking for all required parameters, as well as checking parameters for valid values.

Parameters:: query (NCSSQuery) – The query to validate
Returns:: valid – Whether query is valid.
Return type:: bool

class siphon.ncss.NCSSQuery[source]

Represent a query to the NetCDF Subset Service (NCSS).

Expands on the queries supported by DataQuery to add queries specific to NCSS.

__init__(): Construct an empty class representing a query for data.

accept(fmt)[source]

Set format for data returned from NCSS.

This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

Parameters:: fmt (str) – The format to send to the server.
Returns:: self – Returns self for chaining calls
Return type:: NCSSQuery

add_lonlat(value=True)[source]

Set whether NCSS should add latitude/longitude to returned data.

This is only used on grid requests. Used to make returned data CF-compliant. This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

Parameters:: value (bool, optional) – Whether to add latitude/longitude information. Defaults to True.
Returns:: self – Returns self for chaining calls
Return type:: NCSSQuery

add_query_parameter(**kwargs)

Add arbitrary query element (name=value) to the request.

This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

Parameters:: kwargs – Names and values of parameters to add to the query
Returns:: self – Returns self for chaining calls
Return type:: DataQuery

all_times()

Add a request for all times to the query.

This adds a request for all times (temporal=all). This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

This replaces any existing temporal queries that have been set.

Returns:: self – Returns self for chaining calls
Return type:: DataQuery

items()

Return the various name=value pairs that compose the query.

Returns:: items – Sequence of tuples of name, value representing the query.
Return type:: iterator

lonlat_box(west, east, south, north)

Add a latitude/longitude bounding box to the query.

This adds a request for a spatial bounding box, bounded by (‘north’, ‘south’) for latitude and (‘east’, ‘west’) for the longitude. This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

This replaces any existing spatial queries that have been set.

Parameters:

west (float) – The bounding longitude to the west, in degrees east of the prime meridian
east (float) – The bounding longitude to the east, in degrees east of the prime meridian
south (float) – The bounding latitude to the south, in degrees north of the equator
north (float) – The bounding latitude to the north, in degrees north of the equator

Returns:

self – Returns self for chaining calls

Return type:

DataQuery

lonlat_point(lon, lat)

Add a latitude/longitude point to the query.

This adds a request for a (lon, lat) point. This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

This replaces any existing spatial queries that have been set.

Parameters:

lon (float) – The longitude to request
lat (float) – The latitude to request

Returns:

self – Returns self for chaining calls

Return type:

DataQuery

projection_box(min_x, min_y, max_x, max_y)[source]

Add a bounding box in projected (native) coordinates to the query.

This adds a request for a spatial bounding box, bounded by (min_x, max_x) for x direction and (min_y, max_y) for the y direction. This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

This replaces any existing spatial queries that have been set.

Parameters:

min_x (float) – The left edge of the bounding box
min_y (float) – The bottom edge of the bounding box
max_x (float) – The right edge of the bounding box
max_y (float) – The top edge of the bounding box

Returns:

self – Returns self for chaining calls

Return type:

NCSSQuery

strides(time=None, spatial=None)[source]

Set time and/or spatial (horizontal) strides.

This is only used on grid requests. Used to skip points in the returned data. This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

Parameters:

time (int, optional) – Stride for times returned. Defaults to None, which is equivalent to 1.
spatial (int, optional) – Stride for horizontal grid. Defaults to None, which is equivalent to 1.

Returns:

self – Returns self for chaining calls

Return type:

NCSSQuery

time(time)

Add a request for a specific time to the query.

This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

This replaces any existing temporal queries that have been set.

Parameters:: time (datetime.datetime) – The time to request
Returns:: self – Returns self for chaining calls
Return type:: DataQuery

time_range(start, end)

Add a request for a time range to the query.

This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

This replaces any existing temporal queries that have been set.

Parameters:

start (datetime.datetime) – The start of the requested time range
end (datetime.datetime) – The end of the requested time range

Returns:

self – Returns self for chaining calls

Return type:

DataQuery

variables(*var_names)

Specify one or more variables for the query.

This function ensures that variable names are not repeated.

This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

Parameters:: var_names (str) – One or more names of variables to request. Use ‘all’ to request all.
Returns:: self – Returns self for chaining calls
Return type:: DataQuery

vertical_level(level)[source]

Set vertical level for which data should be retrieved.

The value depends on the coordinate values for the vertical dimension of the requested variable.

This modifies the query in-place, but returns self so that multiple queries can be chained together on one line.

Parameters:: level (float) – The value of the desired level
Returns:: self – Returns self for chaining calls
Return type:: NCSSQuery

class siphon.ncss.ResponseRegistry[source]

Register functions to be called based on the mimetype in the response headers.

__init__()[source]: Initialize the registry.

static default(content, units)[source]: Handle a mimetype when no function is registered.

register(mimetype)[source]: Register a function to handle a particular mimetype.

siphon.ncss.combine_dicts(seq)[source]: Combine a list of dictionaries into single one.

siphon.ncss.combine_xml_points(seq, units, handle_units)[source]: Combine multiple Point tags into an array.

siphon.ncss.default_unit_handler(data, units=None)[source]

Handle units in the default manner.

Ignores units and just returns numpy.array().

siphon.ncss.deletetempfile(fname)[source]

Delete a temporary file.

Warn on any exceptions.

siphon.ncss.parse_csv_dataset(data, handle_units)[source]: Parse CSV data into a netCDF-like dataset.

siphon.ncss.parse_csv_header(line)[source]: Parse the CSV header returned by TDS.

siphon.ncss.parse_csv_response(data, unit_handler)[source]: Handle CSV-formatted HTTP responses.

siphon.ncss.parse_xml(data, handle_units)[source]: Parse XML data returned by NCSS.

siphon.ncss.parse_xml_dataset(elem, handle_units)[source]: Create a netCDF-like dataset from XML data.

siphon.ncss.parse_xml_point(elem)[source]: Parse an XML point tag.

siphon.ncss.read_netcdf(data, handle_units)[source]: Handle HTTP responses in netCDF format.

siphon.ncss.squish(seq)[source]: If list contains only 1 element, return it instead.

siphon.ncss

`siphon.ncss`