Documentation
¶
Overview ¶
Package weather turns third-party weather observations into one stable vocabulary.
It is the sibling of go-astronomy and differs from it in one way worth stating first: go-astronomy computes and go-weather observes. Where the Sun is follows from a date and a coordinate, with no truth outside the arithmetic. Whether it is raining is a measurement somebody took, so it can only come from a feed.
That difference is the whole shape of the package. The core here is pure -- the vocabulary, and the judgement that maps a provider's values onto it -- and every network call lives in an optional adapter subpackage the core does not import. A consumer that already has an observation never touches the network at all, and the core's tests run with nothing listening.
The package stores nothing and schedules nothing. Every observation carries the provider's own expiry where the provider states one, and what a consumer does with that is the consumer's business: a library that reaches for a cache has opinions about deployment that a library has no business having.
It is stateless and concurrency-safe. time.Time is always a parameter and never captured at construction.
Index ¶
Constants ¶
const ( // CodeInvalidCoordinate marks a latitude outside [-90, 90] or a longitude // outside [-180, 180]. CodeInvalidCoordinate = 8001 // CodeUnknownProviderCode marks a provider vocabulary value this library // has no mapping for. It is a real condition rather than a bug: providers // add codes, and answering "unknown" is honest where guessing is not. CodeUnknownProviderCode = 8002 // that answered with a non-success status. CodeProviderUnavailable = 8003 // CodeMalformedResponse marks a provider response that parsed as transport // but not as the shape this library expects. CodeMalformedResponse = 8004 )
Stable numeric error codes for the module. Each error-returning function wraps its cause with one of these via go-apperr, so a caller can recover the code with apperr.Code and branch on it without matching error strings. The values are part of the public contract: never renumber a code, only add new ones.
const ErrorServiceDigit = 8
ErrorServiceDigit is the leading digit that every go-weather error code shares, so a code is attributable to this module at a glance. It is the go-apperr service prefix for the module's code namespace. go-astronomy owns 7; this module owns 8.
Variables ¶
var ( // ErrInvalidCoordinate is the cause behind CodeInvalidCoordinate. ErrInvalidCoordinate = errors.New("weather: coordinate out of range") // ErrUnknownProviderCode is the cause behind CodeUnknownProviderCode. ErrUnknownProviderCode = errors.New("weather: unmapped provider code") ErrProviderUnavailable = errors.New("weather: provider unavailable") // ErrMalformedResponse is the cause behind CodeMalformedResponse. ErrMalformedResponse = errors.New("weather: malformed provider response") )
Sentinel causes, so a caller can use errors.Is as well as read the code.
Functions ¶
func Errors ¶
Errors returns the module's go-apperr registry: the stable code table plus the presentation and logging policy around it. A consumer renders a coded error at its edge with Registry.Present (or PresentContext, which also drives the wired go-log logger) to obtain a sanitized, quotable message, looks a code up with Registry.Describe, or emits the whole table as Markdown with Registry.Markdown. The registry is built once and is safe for concurrent use.
Types ¶
type Condition ¶
type Condition string
Condition is what the sky is doing, as one of eight values.
The grade is part of the condition rather than a separate number, because the providers grade it: WMO codes 61, 63 and 65 are slight, moderate and heavy rain, which is why a phone says "light rain" rather than "rain". Rain and RainHeavy are different facts, not different drawings of one fact.
There is deliberately no blizzard and no whiteout. The published definition of a blizzard requires the conditions to hold for three hours, which makes it a diagnosis applied in retrospect rather than something anybody can see happening -- and heavy snow with a high wind, which is what a person standing outside actually sees, is already expressible as SnowHeavy with a Wind beside it.
const ( Clear Condition = "CLEAR" Cloudy Condition = "CLOUDY" Fog Condition = "FOG" Rain Condition = "RAIN" RainHeavy Condition = "RAIN_HEAVY" Snow Condition = "SNOW" SnowHeavy Condition = "SNOW_HEAVY" Thunderstorm Condition = "THUNDERSTORM" )
The eight conditions.
func ConditionFromWMO ¶
func ConditionFromWMO(code int, q Quantities) (Condition, error)
ConditionFromWMO maps a provider's WMO interpretation code onto the vocabulary, letting visibility overrule it where the two disagree.
Returns a CodeUnknownProviderCode error for a code with no mapping.
A zero VisibilityMetres is read as "not reported" rather than as zero visibility. The alternative would fog every sky whose provider omitted the field, which is the more damaging reading of an absent number.
type Coordinate ¶
type Coordinate struct {
// Lat is degrees north, in [-90, 90].
Lat float64
// Lng is degrees east, in [-180, 180].
Lng float64
}
Coordinate is a place to ask about.
func (Coordinate) Validate ¶
func (c Coordinate) Validate() error
Validate reports whether the coordinate is on the globe.
Checked before any request is made, because a bad coordinate is the caller's bug and should not cost a round trip to discover.
type Observation ¶
type Observation struct {
// At is the instant the observation describes.
At time.Time
// ExpiresAt is when the provider says its answer goes stale. Zero means
// the provider did not say, and this library will not invent a value on
// its behalf.
ExpiresAt time.Time
// Condition is the headline: one of eight.
Condition Condition
// Quantities are what a renderer draws from.
Quantities Quantities
// Wind is beside the condition, never inside it.
Wind Wind
// ElevationMetres is the ground height the provider answered for. Carried
// because it arrives free with the observation and because an astronomy
// consumer wants it: the horizon dips with height, which moves sunrise by
// minutes. This library does nothing with it.
ElevationMetres float64
}
Observation is one answer about one place at one instant.
func (Observation) Stale ¶
func (o Observation) Stale(now time.Time) bool
Stale reports whether the provider's own expiry has passed.
An observation whose provider stated no expiry is never stale. Answering otherwise would mean choosing a TTL, and that is the consumer's decision: it knows how often it polls and how wrong it can afford to be.
type Quantities ¶
type Quantities struct {
// CloudCover is 0 to 1, not a percentage.
CloudCover float64
// PrecipitationMMPerHour is liquid equivalent, so snow appears here too.
PrecipitationMMPerHour float64
// SnowfallCMPerHour is depth rather than liquid equivalent. Both are
// carried because their ratio is how dry powder is told from wet snow,
// and the same wind moves the two completely differently.
SnowfallCMPerHour float64
// VisibilityMetres is how far can be seen.
VisibilityMetres float64
}
Quantities are the continuous values a renderer actually draws from.
Beside the condition rather than derived from it, because eight discrete states can only be cut between and numbers can be interpolated. That is the difference between weather that changes and weather that jumps, and it is what lets a consumer stay a renderer: it is handed values to draw rather than a category to interpret.
type Wind ¶
type Wind struct {
// SpeedMPH is the sustained speed. Zero is calm.
SpeedMPH float64
// GustMPH is the peak gust, which can far exceed the sustained speed and
// is what actually moves a branch.
GustMPH float64
// FromDegrees is the bearing the wind blows *from*, the meteorological
// convention: 270 comes out of the west and pushes towards the east, so
// something leaning in it leans away from this bearing.
FromDegrees float64
}
Wind is how hard it is blowing and which way from.
Beside the condition and never inside it: any condition can be calm or blowing hard. Clear covers a still morning and a gale under a blue sky, and deriving a nominal speed per condition would collapse that distinction permanently -- every consumer would grow its own table and disagree with the next one.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package alert carries official weather warnings, unedited.
|
Package alert carries official weather warnings, unedited. |
|
nws
Package nws fetches official alerts from the United States National Weather Service.
|
Package nws fetches official alerts from the United States National Weather Service. |
|
provider
|
|
|
openmeteo
Package openmeteo fetches observations from Open-Meteo.
|
Package openmeteo fetches observations from Open-Meteo. |
|
Package space carries geomagnetic activity.
|
Package space carries geomagnetic activity. |
|
swpc
Package swpc fetches geomagnetic activity from NOAA's Space Weather Prediction Center.
|
Package swpc fetches geomagnetic activity from NOAA's Space Weather Prediction Center. |