`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¶: NCSSDataset – 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.

variables¶: set(str) – Names of all variables available in this dataset

unit_handler¶: callable – 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().

__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

static unit_handler(data, units=None)

Handle units in the default manner.

Ignores units and just returns numpy.array().

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 DataQuery.

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 (one or more strings passed as keyword arguments) – 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 (one or more strings) – 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(l)[source]¶: Combine a list of dictionaries into single one.

siphon.ncss.combine_xml_points(l, 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(l)[source]¶: If list contains only 1 element, return it instead.

siphon.ncss¶

`siphon.ncss`¶