degreedays.geo

Classes for handling geographic information like longitude/latitude positions and distances.

Class summaries

Distance	Defines a distance in terms of its numeric value and its unit of measurement (e.g. 20 miles).
DistanceUnit	Defines the units of distance measurement with constants to represent metres, kilometres, feet, and miles.
LongLat	Defines a geographic position in terms of its longitude and latitude coordinates (take care not to mix these up in the constructor).

degreedays.geo

Classes for handling geographic information like longitude/latitude positions and distances.

class degreedays.geo.Distance(value: float, unit: DistanceUnit)

Defines a distance in terms of its numeric value and its unit of measurement (e.g. 20 miles).

To create a Distance object, it’s usually easiest to use the class methods: metres, kilometres, feet, and miles. For example:

twentyMiles = Distance.miles(20)

It’s easy to convert between units:

twentyMilesInMetres = twentyMiles.inMetres()

static feet(value: float) → Distance

Returns a Distance object with the specified value and DistanceUnit.FEET as the unit of measurement.

Parameters:

value (int|float) – the number of feet that the returned Distance should represent.

Raises:

• TypeError – if value is not a numeric type.

• ValueError – if value is NaN or infinite.

inFeet() → Distance

Returns a Distance object that represents this Distance converted into feet.

inKilometres() → Distance

Returns a Distance object that represents this Distance converted into kilometres.

inMetres() → Distance

Returns a Distance object that represents this Distance converted into metres.

inMiles() → Distance

Returns a Distance object that represents this Distance converted into miles.

in_(unit: DistanceUnit) → Distance

Returns a Distance object that represents this Distance converted into the specified unit of measurement.

For example, Distance.metres(1000).in_(DistanceUnit.KILOMETRES) will return a Distance that is equal to Distance.kilometres(1).

Parameters:

unit (DistanceUnit) – the unit of measurement that the returned Distance should have.

Raises:

TypeError – if unit is not a DistanceUnit.

static kilometres(value: float) → Distance

Returns a Distance object with the specified value and DistanceUnit.KILOMETRES as the unit of measurement.

Parameters:

value (int|float) – the number of kilometres that the returned Distance should represent.

Raises:

• TypeError – if value is not a numeric type.

• ValueError – if value is NaN or infinite.

static metres(value: float) → Distance

Returns a Distance object with the specified value and DistanceUnit.METRES as the unit of measurement.

Parameters:

value (int|float) – the number of metres that the returned Distance should represent.

Raises:

• TypeError – if value is not a numeric type.

• ValueError – if value is NaN or infinite.

static miles(value: float) → Distance

Returns a Distance object with the specified value and DistanceUnit.MILES as the unit of measurement.

Parameters:

value (int|float) – the number of miles that the returned Distance should represent.

Raises:

• TypeError – if value is not a numeric type.

• ValueError – if value is NaN or infinite.

property unit

The DistanceUnit of this Distance object.

property value

The numeric value of this Distance object.

class degreedays.geo.DistanceUnit

Defines the units of distance measurement with constants to represent metres, kilometres, feet, and miles.

FEET: DistanceUnit

For the imperial unit the foot (ft).

Access via: DistanceUnit.FEET

KILOMETRES: DistanceUnit

For the metric unit the kilometre (km); 1 kilometre = 1000 metres.

Access via: DistanceUnit.KILOMETRES

METRES: DistanceUnit

For the SI base unit of length, the metre (m).

Access via: DistanceUnit.METRES

MILES: DistanceUnit

For the imperial unit the mile (mi); 1 mile = 5280 feet.

Access via: DistanceUnit.MILES

class degreedays.geo.LongLat(longitude: float, latitude: float)

Defines a geographic position in terms of its longitude and latitude coordinates (take care not to mix these up in the constructor).

Parameters:

• longitude (float) – a number between -180 and 180 (both inclusive) representing the West/East coordinate. A zero longitude value represents a line passing to the rear of the Royal Observatory, Greenwich (near London in the UK). Negative values are to the West of that line (e.g. locations in the US all have negative longitude values), and positive values are to the East of that line.

• latitude (float) – a number between -90 and 90 (both inclusive) representing the South/North coordinate. -90 represents the South Pole, 90 represents the North Pole, and 0 represents the equator.

Raises:

• TypeError – if either the longitude or latitude is not a numeric type.

• ValueError – if either the longitude or latitude is NaN or outside of its allowed range.

property latitude: float

The latitude of this LongLat object: a number between -90 and 90 (both inclusive) representing the South/North coordinate. -90 represents the South Pole, 90 represents the North Pole, and 0 represents the equator.

property longitude: float

The longitude of this LongLat object: a number between -180 and 180 (both inclusive) representing the West/East coordinate, zeroed on a line passing to the rear of the Royal Observatory, Greenwich (near London in the UK). Negative values are to the West of that line (e.g. locations in the US all have negative longitude values); positive values are to the East of that line.