siphon.http_util

Utility code to support making requests using HTTP.

exception siphon.http_util.BadQueryError

Exception raised when a query fails.

class siphon.http_util.DataQuery

Represent a query for data from a THREDDS server.

This object provides a clear API to formulate a query for data, including a spatial query, a time query, and possibly some variables or other parameters. These objects provide a dictionary-like interface, (items() and __iter__()) sufficient to be passed to functions expecting a dictionary representing a URL query. Instances of this object can also be turned into a string, which will yield a properly escaped string for a URL.

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

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

class siphon.http_util.HTTPEndPoint(url)

An object representing an endpoint on a server that is accessed using HTTP.

This provides a simple way to point to a URL, formulate appropriate queries and validate them, parse metadata as appropriate, and parse returns from requests.

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_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()

Create a new query object.

Returns a new DataQuery instance appropriate for this endpoint.

The default implementation returns a DataQuery instance. Subclasses can override to return a subclass specific to this endpoint.

Returns:valid – Whether query is valid. Return type:bool

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)

Validate a query.

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

The default implementation does nothing. It is presumed that subclasses implement this to do more detailed checking as appropriate.

Parameters:query (DataQuery (or subclass)) – Returns:valid – Whether query is valid. Return type:bool

class siphon.http_util.HTTPSessionManager

Manage the creation of sessions for HTTP access.

create_session()

Create a new HTTP session with our user-agent set.

Returns:session – The created session Return type:requests.Session

See also

urlopen(), set_session_options()

set_session_options(**kwargs)

Set options for created session instances.

Takes keyword arguments and sets them as attributes on the returned requests.Session instance.

See also

create_session()

urlopen(url, **kwargs)

GET a file-like object for a URL using HTTP.

This is a thin wrapper around requests.Session.get() that returns a file-like object wrapped around the resulting content.

Parameters:

• url (str) – The URL to request
• kwargs (arbitrary keyword arguments) – Additional keyword arguments to pass to requests.Session.get().

Returns:

fobj – A file-like interface to the content in the response

Return type:

file-like object

See also

requests.Session.get()

class siphon.http_util.UTC

Represent UTC timezone.

dst(dt)

Get whether the timezone uses Daylight Savings Time.

tzname(dt)

Get the name of the timezone.

utcoffset(dt)

Get the offset from UTC.

siphon.http_util.parse_iso_date(s)

Parse a string containing an ISO-8601 formatted date.

Parameters:s (str) – The string to be parsed Returns:dt – The results of parsing the string Return type:datetime.datetime