pastclimate 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,406 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Response models. Every field is optional on purpose: a field the server omits is nil,
4
+ # and a field this version does not know about is ignored (see Model#raw).
5
+ module PastClimate
6
+ # The point you asked for and how far it was from the grid cell that supplies the data.
7
+ class RequestedPoint < Model
8
+ # Latitude you asked for.
9
+ attribute :lat, :float
10
+ # Longitude you asked for.
11
+ attribute :lon, :float
12
+ # Great-circle distance from the requested point to the snapped grid cell, in km.
13
+ attribute :distance_km, :float
14
+ end
15
+
16
+ # Span of published data for a location's country.
17
+ class LocationCoverage < Model
18
+ # First year with published data for the country.
19
+ attribute :first_year, :integer
20
+ # Last day with published data for the country.
21
+ attribute :last_date, :date
22
+ end
23
+
24
+ # The place a response is about (the "location" part of the envelope).
25
+ class Location < Model
26
+ # Location id: country code, a slash, then the place slug. Use it as the location parameter.
27
+ attribute :id, :string
28
+ # Display name.
29
+ attribute :name, :string
30
+ # Lower-case two-letter country code.
31
+ attribute :country, :string
32
+ # Latitude of the centre of the grid cell that supplies the data (0.25 degree cells, about 28 km), not of the town centre.
33
+ attribute :lat, :float
34
+ # Longitude of the centre of the grid cell that supplies the data.
35
+ attribute :lon, :float
36
+ # IANA timezone. Daily and hourly days are local calendar days in this timezone.
37
+ attribute :timezone, :string
38
+ # Present only when the location was given as lat,lon (or by /v1/locations/nearest): the point that was snapped.
39
+ attribute :requested, RequestedPoint
40
+ end
41
+
42
+ # One result of a place search.
43
+ class LocationSearchResult < Model
44
+ # Location id.
45
+ attribute :id, :string
46
+ # Display name.
47
+ attribute :name, :string
48
+ # Lower-case two-letter country code.
49
+ attribute :country, :string
50
+ # Population, used to rank results.
51
+ attribute :population, :integer
52
+ # Grid cell centre latitude. Absent when weather_available is false.
53
+ attribute :lat, :float
54
+ # Grid cell centre longitude. Absent when weather_available is false.
55
+ attribute :lon, :float
56
+ # IANA timezone. Absent when weather_available is false.
57
+ attribute :timezone, :string
58
+ # false when this place cannot be served. Asking for its data returns 422 location_blocked.
59
+ attribute :weather_available, :boolean
60
+ end
61
+
62
+ # One location by id.
63
+ class LocationDetail < Model
64
+ # Location id.
65
+ attribute :id, :string
66
+ # Display name.
67
+ attribute :name, :string
68
+ # Lower-case two-letter country code.
69
+ attribute :country, :string
70
+ # Grid cell centre latitude.
71
+ attribute :lat, :float
72
+ # Grid cell centre longitude.
73
+ attribute :lon, :float
74
+ # IANA timezone.
75
+ attribute :timezone, :string
76
+ # Population.
77
+ attribute :population, :integer
78
+ attribute :coverage, LocationCoverage
79
+ end
80
+
81
+ # The place nearest a point.
82
+ class NearestLocation < Model
83
+ # Location id.
84
+ attribute :id, :string
85
+ # Display name.
86
+ attribute :name, :string
87
+ # Lower-case two-letter country code.
88
+ attribute :country, :string
89
+ # Grid cell centre latitude.
90
+ attribute :lat, :float
91
+ # Grid cell centre longitude.
92
+ attribute :lon, :float
93
+ # IANA timezone.
94
+ attribute :timezone, :string
95
+ # Present only when the location was given as lat,lon (or by /v1/locations/nearest): the point that was snapped.
96
+ attribute :requested, RequestedPoint
97
+ # Population.
98
+ attribute :population, :integer
99
+ end
100
+
101
+ # One local calendar day of weather.
102
+ class DailyRow < Model
103
+ # The local calendar day, in the location's timezone.
104
+ attribute :date, :date
105
+ # Mean temperature of the day, deg C. With units=imperial: deg F.
106
+ attribute :daily_avg_temp, :float
107
+ # Lowest temperature of the day, deg C. With units=imperial: deg F.
108
+ attribute :daily_min_temp, :float
109
+ # Highest temperature of the day, deg C. With units=imperial: deg F.
110
+ attribute :daily_max_temp, :float
111
+ # Total precipitation of the day, mm. With units=imperial: inches.
112
+ attribute :daily_total_rain, :float
113
+ # Mean wind speed of the day, m/s. With units=imperial: mph.
114
+ attribute :daily_avg_wind, :float
115
+ # Mean cloud cover of the day, 0 to 100.
116
+ attribute :daily_avg_cloud_percent, :integer
117
+ # true when total precipitation was at least 1 mm.
118
+ attribute :rain_flag, :boolean
119
+ end
120
+
121
+ # One hour of weather.
122
+ class HourlyRow < Model
123
+ # Start of the hour, UTC.
124
+ attribute :timestamp_utc, :time
125
+ # Air temperature at 2 m, deg C. With units=imperial: deg F.
126
+ attribute :temperature, :float
127
+ # Apparent temperature (Steadman), deg C. With units=imperial: deg F.
128
+ attribute :feels_like_temperature, :float
129
+ # Dewpoint, deg C. With units=imperial: deg F.
130
+ attribute :dewpoint, :float
131
+ # Precipitation in the hour, mm. With units=imperial: inches.
132
+ attribute :precipitation, :float
133
+ # Wind speed, m/s. With units=imperial: mph.
134
+ attribute :wind_speed, :float
135
+ # Wind direction, degrees, 0 to 360.
136
+ attribute :wind_direction_deg, :float
137
+ # Relative humidity, 0 to 100, derived from temperature and dewpoint.
138
+ attribute :relative_humidity_percent, :float
139
+ # Surface pressure, hPa. With units=imperial: inHg.
140
+ attribute :pressure, :float
141
+ # Total cloud cover, 0 to 100.
142
+ attribute :cloud_cover_percent, :integer
143
+ # Solar radiation received in the hour, kWh per square metre. Not changed by units.
144
+ attribute :solar_radiation_kwh_m2, :float
145
+ end
146
+
147
+ # One calendar month (UTC) of summary values.
148
+ class MonthlyRow < Model
149
+ # Calendar year (UTC).
150
+ attribute :year, :integer
151
+ # Month, 1 to 12 (UTC).
152
+ attribute :month, :integer
153
+ # Mean hourly temperature, deg C. With units=imperial: deg F.
154
+ attribute :monthly_avg_temp, :float
155
+ # Lowest hourly temperature in the month, deg C. With units=imperial: deg F.
156
+ attribute :monthly_min_temp, :float
157
+ # Highest hourly temperature in the month, deg C. With units=imperial: deg F.
158
+ attribute :monthly_max_temp, :float
159
+ # Total precipitation, mm. With units=imperial: inches.
160
+ attribute :monthly_total_rain, :float
161
+ # Mean wind speed, m/s. With units=imperial: mph.
162
+ attribute :monthly_avg_wind, :float
163
+ # Mean surface pressure, hPa. With units=imperial: inHg.
164
+ attribute :monthly_avg_pressure, :float
165
+ # Mean cloud cover, 0 to 100.
166
+ attribute :monthly_avg_cloud_percent, :float
167
+ # Total solar radiation, joules per square metre. Not changed by units.
168
+ attribute :monthly_total_solar_j_m2, :float
169
+ # Days with at least 1 mm of precipitation.
170
+ attribute :rainy_days, :integer
171
+ # Days with at least 20 mm of precipitation.
172
+ attribute :heavy_rain_days, :integer
173
+ # Days with a maximum of at least 40 deg C. A count, not changed by units.
174
+ attribute :extreme_heat_days, :integer
175
+ # Days with a minimum of at most 0 deg C. A count, not changed by units.
176
+ attribute :extreme_cold_days, :integer
177
+ # Hourly values that went into the month.
178
+ attribute :hours, :integer
179
+ # Days that went into the day counts.
180
+ attribute :days, :integer
181
+ end
182
+
183
+ # One calendar year (UTC) of summary values.
184
+ class YearlyRow < Model
185
+ # Calendar year (UTC).
186
+ attribute :year, :integer
187
+ # Mean hourly temperature, deg C. With units=imperial: deg F.
188
+ attribute :yearly_avg_temp, :float
189
+ # Lowest hourly temperature in the year, deg C. With units=imperial: deg F.
190
+ attribute :yearly_min_temp, :float
191
+ # Highest hourly temperature in the year, deg C. With units=imperial: deg F.
192
+ attribute :yearly_max_temp, :float
193
+ # Total precipitation, mm. With units=imperial: inches.
194
+ attribute :yearly_total_rain, :float
195
+ # Mean wind speed, m/s. With units=imperial: mph.
196
+ attribute :yearly_avg_wind, :float
197
+ # Mean surface pressure, hPa. With units=imperial: inHg.
198
+ attribute :yearly_avg_pressure, :float
199
+ # Mean cloud cover, 0 to 100.
200
+ attribute :yearly_avg_cloud_percent, :float
201
+ # Total solar radiation, joules per square metre. Not changed by units.
202
+ attribute :yearly_total_solar_j_m2, :float
203
+ # Days with at least 1 mm of precipitation.
204
+ attribute :rainy_days, :integer
205
+ # Days with at least 20 mm of precipitation.
206
+ attribute :heavy_rain_days, :integer
207
+ # Days with a maximum of at least 40 deg C.
208
+ attribute :extreme_heat_days, :integer
209
+ # Days with a minimum of at most 0 deg C.
210
+ attribute :extreme_cold_days, :integer
211
+ # Hourly values that went into the year.
212
+ attribute :hours, :integer
213
+ # Days that went into the day counts.
214
+ attribute :days, :integer
215
+ # Months that went into the year (12 for a complete year).
216
+ attribute :months, :integer
217
+ end
218
+
219
+ # Climate normal for one month.
220
+ class NormalsMonthlyRow < Model
221
+ # Month, 1 to 12.
222
+ attribute :month, :integer
223
+ # Mean daily mean temperature, deg C. With units=imperial: deg F.
224
+ attribute :avg_temp, :float
225
+ # Mean daily minimum temperature, deg C. With units=imperial: deg F.
226
+ attribute :min_temp, :float
227
+ # Mean daily maximum temperature, deg C. With units=imperial: deg F.
228
+ attribute :max_temp, :float
229
+ # Mean monthly precipitation total, mm. With units=imperial: inches.
230
+ attribute :total_rain, :float
231
+ # Mean number of days with at least 1 mm of precipitation.
232
+ attribute :rainy_days, :float
233
+ # Mean wind speed, m/s. With units=imperial: mph.
234
+ attribute :avg_wind, :float
235
+ # Mean cloud cover, 0 to 100.
236
+ attribute :avg_cloud_pct, :float
237
+ # Mean daily solar radiation, kWh per square metre. Not changed by units.
238
+ attribute :avg_solar_kwh_m2, :float
239
+ # Years of data the normal is averaged over.
240
+ attribute :years_covered, :integer
241
+ # Mean relative humidity, 0 to 100.
242
+ attribute :avg_humidity_pct, :float
243
+ end
244
+
245
+ # Climate normal for one calendar day of the year.
246
+ class NormalsDayRow < Model
247
+ # Calendar day as MM-DD. 02-29 is included.
248
+ attribute :md, :string
249
+ # Mean daily mean temperature on this calendar day, deg C. With units=imperial: deg F.
250
+ attribute :avg_temp, :float
251
+ # Mean daily minimum, deg C. With units=imperial: deg F.
252
+ attribute :min_temp, :float
253
+ # Mean daily maximum, deg C. With units=imperial: deg F.
254
+ attribute :max_temp, :float
255
+ # Share of years, 0 to 1, with at least 1 mm of precipitation on this calendar day.
256
+ attribute :rain_prob, :float
257
+ end
258
+
259
+ # Monthly and day-of-year climate normals.
260
+ class NormalsData < Model
261
+ # 12 rows, or 1 when month is given.
262
+ attribute :monthly, [NormalsMonthlyRow]
263
+ # 366 rows, or the days of that month when month is given.
264
+ attribute :day_of_year, [NormalsDayRow]
265
+ end
266
+
267
+ # One extreme on record.
268
+ class RecordItem < Model
269
+ # Which extreme.
270
+ attribute :metric, :string
271
+ # The extreme value, in the unit given by unit.
272
+ attribute :value, :float
273
+ # Unit of value.
274
+ attribute :unit, :string
275
+ # The day the extreme occurred.
276
+ attribute :occurred_on, :date
277
+ end
278
+
279
+ # The plan of the account the key belongs to.
280
+ class MePlan < Model
281
+ # Plan id.
282
+ attribute :id, :string
283
+ # Plan name.
284
+ attribute :name, :string
285
+ # Whether commercial use is allowed.
286
+ attribute :commercial_use, :boolean
287
+ # Whether a visible link back is required.
288
+ attribute :attribution_link_required, :boolean
289
+ # Most days one /v1/hourly call may ask for.
290
+ attribute :hourly_max_days_per_call, :integer
291
+ # How far back hourly data goes, in months. null for full history.
292
+ attribute :hourly_max_age_months, :integer
293
+ end
294
+
295
+ # The key the call was made with.
296
+ class MeKey < Model
297
+ # Which credits this key spends first: "plan_first" or "topup_first".
298
+ attribute :spend_order, :string
299
+ end
300
+
301
+ # Credit balance and usage.
302
+ class MeCredits < Model
303
+ # One-time credits for the life of the account. They never refill. null when your plan has none.
304
+ attribute :one_time_limit, :integer
305
+ # One-time credits left. null when your plan has none.
306
+ attribute :one_time_remaining, :integer
307
+ # Credits used since the account was created, on any plan.
308
+ attribute :used_all_time, :integer
309
+ # Credits in your plan each month. null when your plan has no monthly credits.
310
+ attribute :monthly_limit, :integer
311
+ # Credits used this month (UTC).
312
+ attribute :used_this_month, :integer
313
+ # Credits left this month. null when your plan has no monthly credits.
314
+ attribute :remaining_this_month, :integer
315
+ # When the monthly allowance next renews (UTC). null when your plan has no monthly allowance.
316
+ attribute :month_resets_at, :time
317
+ # Most credits you can use in a day. null when there is no daily credit cap.
318
+ attribute :daily_cap, :integer
319
+ # Credits used today (UTC).
320
+ attribute :used_today, :integer
321
+ # Credits left today. null when there is no daily credit cap.
322
+ attribute :remaining_today, :integer
323
+ # When the daily count resets.
324
+ attribute :day_resets_at, :time
325
+ # Bought credits left. They never expire and never reset. Calls spend your plan's credits first, then these.
326
+ attribute :topup_balance, :integer
327
+ # Bought credits spent so far.
328
+ attribute :topup_used, :integer
329
+ end
330
+
331
+ # Per-minute request limit.
332
+ class MeRateLimit < Model
333
+ # Requests allowed per minute.
334
+ attribute :per_minute, :integer
335
+ # Requests left in the current minute.
336
+ attribute :remaining, :integer
337
+ end
338
+
339
+ # Your plan, credit balance and limits.
340
+ class MeData < Model
341
+ attribute :plan, MePlan
342
+ attribute :key, MeKey
343
+ attribute :credits, MeCredits
344
+ attribute :rate_limit, MeRateLimit
345
+ end
346
+
347
+ # Published coverage of one country.
348
+ class CountryCoverage < Model
349
+ # Lower-case two-letter country code.
350
+ attribute :country, :string
351
+ # First year with published data.
352
+ attribute :first_year, :integer
353
+ # Last day with published data.
354
+ attribute :last_date, :date
355
+ end
356
+
357
+ # The countries the archive serves.
358
+ class CoverageData < Model
359
+ attribute :countries, [CountryCoverage]
360
+ end
361
+
362
+ # The unit system used for the values in a response.
363
+ class MetaUnits < Model
364
+ # The unit system used for the values in this response.
365
+ attribute :system, :string
366
+ # Temperature unit.
367
+ attribute :temperature, :string
368
+ # Precipitation unit.
369
+ attribute :precipitation, :string
370
+ # Wind speed unit.
371
+ attribute :wind_speed, :string
372
+ # Pressure unit.
373
+ attribute :pressure, :string
374
+ end
375
+
376
+ # Response metadata: credits used and left, plus the fields each endpoint adds. Fields an endpoint does not send are null.
377
+ class Meta < Model
378
+ # Credits this call used. 0 on an error.
379
+ attribute :credits, :integer
380
+ # Credits the next call can spend: the plan's remaining allowance plus bought credits.
381
+ attribute :credits_remaining, :integer
382
+ # Version of the data-processing methodology. Changes only when published numbers can shift.
383
+ attribute :methodology_version, :string
384
+ # The search text.
385
+ attribute :query, :string
386
+ # The country filter, or null.
387
+ attribute :country, :string
388
+ # Results returned.
389
+ attribute :count, :integer
390
+ attribute :units, MetaUnits
391
+ # First day.
392
+ attribute :start, :date
393
+ # Last day.
394
+ attribute :end, :date
395
+ # Rows returned.
396
+ attribute :days, :integer
397
+ # First day.
398
+ attribute :date, :date
399
+ # Timezone of the local days.
400
+ attribute :timezone, :string
401
+ # Rows returned.
402
+ attribute :rows, :integer
403
+ # The month filter, or null.
404
+ attribute :month, :integer
405
+ end
406
+ end
@@ -0,0 +1,75 @@
1
+ # frozen_string_literal: true
2
+
3
+ module PastClimate
4
+ # Where to get weather for: a location id, or a latitude/longitude plus country.
5
+ #
6
+ # PastClimate::Place.id("gb/london")
7
+ # PastClimate::Place.point(lat: 51.5, lon: -0.12, country: "gb")
8
+ #
9
+ # Anywhere a place is expected you may also pass the id as a plain String.
10
+ # A point is snapped to the nearest place in that country; the server echoes
11
+ # the snapped point in +response.location.requested+.
12
+ class Place
13
+ POINT_LIKE = /\A\s*-?\d+(\.\d+)?\s*,\s*-?\d+(\.\d+)?\s*\z/.freeze
14
+
15
+ attr_reader :location, :country
16
+
17
+ def self.id(id)
18
+ text = id.to_s.strip
19
+ raise ArgumentError, "a location id is required, for example \"gb/london\"" if text.empty?
20
+ if text.match?(POINT_LIKE)
21
+ raise ArgumentError, "#{text.inspect} looks like a point; use Place.point(lat:, lon:, country:)"
22
+ end
23
+
24
+ new(text, nil)
25
+ end
26
+
27
+ def self.point(lat:, lon:, country:)
28
+ raise ArgumentError, "lat and lon must be numbers" unless finite_number?(lat) && finite_number?(lon)
29
+
30
+ cc = country.to_s.strip
31
+ raise ArgumentError, "country is required with a lat/lon point, for example \"gb\"" if cc.empty?
32
+
33
+ new("#{format_number(lat)},#{format_number(lon)}", cc)
34
+ end
35
+
36
+ # Turns a String id or a Place into a Place.
37
+ def self.coerce(value)
38
+ case value
39
+ when Place then value
40
+ when String then id(value)
41
+ else raise ArgumentError, "expected a location id String or a PastClimate::Place, got #{value.class}"
42
+ end
43
+ end
44
+
45
+ def self.finite_number?(value)
46
+ value.is_a?(Numeric) && value.to_f.finite?
47
+ end
48
+
49
+ # Plain decimal text, never scientific notation.
50
+ def self.format_number(value)
51
+ format("%.10f", value.to_f).sub(/0+\z/, "").sub(/\.\z/, "")
52
+ end
53
+
54
+ def initialize(location, country)
55
+ @location = location
56
+ @country = country
57
+ freeze
58
+ end
59
+
60
+ # Query parameters for this place.
61
+ def to_query
62
+ params = { "location" => location }
63
+ params["country"] = country if country
64
+ params
65
+ end
66
+
67
+ def to_s
68
+ country ? "#{location} (#{country})" : location
69
+ end
70
+
71
+ def inspect
72
+ "#<PastClimate::Place #{self}>"
73
+ end
74
+ end
75
+ end
@@ -0,0 +1,125 @@
1
+ # frozen_string_literal: true
2
+
3
+ module PastClimate
4
+ # Helpers for reading response headers (names are lower-cased).
5
+ module Headers
6
+ def self.normalize(headers)
7
+ result = {}
8
+ (headers || {}).each { |name, value| result[name.to_s.downcase] = value.is_a?(Array) ? value.join(", ") : value.to_s }
9
+ result
10
+ end
11
+
12
+ # An integer header, or nil when it is absent or not a whole number.
13
+ def self.integer(headers, name)
14
+ value = headers[name]
15
+ return nil if value.nil?
16
+
17
+ text = value.to_s.strip
18
+ text.match?(/\A\d+\z/) ? text.to_i : nil
19
+ end
20
+
21
+ # Retry-After in whole seconds, or nil. Only the delay-in-seconds form is read.
22
+ def self.retry_after(headers)
23
+ integer(headers, "retry-after")
24
+ end
25
+ end
26
+
27
+ # The per-minute request limit as the server reported it. Any value is nil
28
+ # when the response did not carry that header (some refusals do not).
29
+ class RateLimit
30
+ attr_reader :limit, :remaining, :reset
31
+
32
+ def initialize(limit: nil, remaining: nil, reset: nil)
33
+ @limit = limit
34
+ @remaining = remaining
35
+ @reset = reset
36
+ freeze
37
+ end
38
+
39
+ def self.from_headers(headers)
40
+ new(
41
+ limit: Headers.integer(headers, "ratelimit-limit"),
42
+ remaining: Headers.integer(headers, "ratelimit-remaining"),
43
+ reset: Headers.integer(headers, "ratelimit-reset")
44
+ )
45
+ end
46
+
47
+ def to_h
48
+ { limit: limit, remaining: remaining, reset: reset }
49
+ end
50
+
51
+ def ==(other)
52
+ other.is_a?(RateLimit) && to_h == other.to_h
53
+ end
54
+
55
+ def inspect
56
+ "#<PastClimate::RateLimit limit=#{limit.inspect} remaining=#{remaining.inspect} reset=#{reset.inspect}>"
57
+ end
58
+ end
59
+
60
+ # What every call has in common: HTTP status, headers, the rate limit and the
61
+ # credit numbers.
62
+ module ResponseInfo
63
+ attr_reader :status, :headers, :rate_limit
64
+
65
+ # Credits this call used (meta.credits, else the X-Credits-Used header), or nil.
66
+ def credits_used
67
+ from_meta = meta&.credits
68
+ from_meta.nil? ? Headers.integer(headers, "x-credits-used") : from_meta
69
+ end
70
+
71
+ # Credits you can still spend (meta.credits_remaining, else the
72
+ # X-Credits-Remaining header), or nil.
73
+ def credits_remaining
74
+ from_meta = meta&.credits_remaining
75
+ from_meta.nil? ? Headers.integer(headers, "x-credits-remaining") : from_meta
76
+ end
77
+
78
+ def meta
79
+ nil
80
+ end
81
+ end
82
+
83
+ # A JSON answer: +data+ (typed models), +location+, +meta+, plus rate-limit and credit info.
84
+ class Response
85
+ include ResponseInfo
86
+
87
+ attr_reader :data, :location, :meta
88
+
89
+ def initialize(data:, location:, meta:, status:, headers:)
90
+ @data = data
91
+ @location = location
92
+ @meta = meta
93
+ @status = status
94
+ @headers = headers
95
+ @rate_limit = RateLimit.from_headers(headers)
96
+ end
97
+
98
+ def inspect
99
+ "#<PastClimate::Response status=#{status} credits_used=#{credits_used.inspect} credits_remaining=#{credits_remaining.inspect}>"
100
+ end
101
+ end
102
+
103
+ # A CSV answer (+format: :csv+). +csv+ is the text. There is no meta in a CSV
104
+ # body, so credit numbers come from the response headers.
105
+ class CsvResponse
106
+ include ResponseInfo
107
+
108
+ attr_reader :csv
109
+
110
+ def initialize(csv:, status:, headers:)
111
+ @csv = csv
112
+ @status = status
113
+ @headers = headers
114
+ @rate_limit = RateLimit.from_headers(headers)
115
+ end
116
+
117
+ def to_s
118
+ csv
119
+ end
120
+
121
+ def inspect
122
+ "#<PastClimate::CsvResponse status=#{status} bytes=#{csv.bytesize} credits_used=#{credits_used.inspect}>"
123
+ end
124
+ end
125
+ end
@@ -0,0 +1,49 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "net/http"
4
+ require "openssl"
5
+ require "uri"
6
+
7
+ module PastClimate
8
+ # What a transport returns: HTTP status, lower-cased header names, body text.
9
+ TransportResponse = Struct.new(:status, :headers, :body, keyword_init: true)
10
+
11
+ # The default transport, built on Net::HTTP. A transport is any object with
12
+ #
13
+ # call(method:, url:, headers:, timeout:) -> TransportResponse
14
+ #
15
+ # that raises PastClimate::ConnectionError when no HTTP answer arrives. Pass
16
+ # your own to Client.new(transport: ...) to use another HTTP library or a fake.
17
+ class NetHttpTransport
18
+ NETWORK_ERRORS = [
19
+ SocketError, SystemCallError, IOError, EOFError, OpenSSL::SSL::SSLError,
20
+ Net::HTTPBadResponse, Net::ProtocolError
21
+ ].freeze
22
+
23
+ def call(method:, url:, headers:, timeout:)
24
+ raise ArgumentError, "only GET is supported" unless method == :get
25
+
26
+ uri = URI.parse(url)
27
+ http = Net::HTTP.new(uri.host, uri.port)
28
+ http.use_ssl = uri.scheme == "https"
29
+ http.open_timeout = timeout
30
+ http.read_timeout = timeout
31
+ http.write_timeout = timeout
32
+ http.max_retries = 0 # the client does its own retrying
33
+ request = Net::HTTP::Get.new(uri.request_uri, headers)
34
+ response = http.start { |connection| connection.request(request) }
35
+
36
+ response_headers = {}
37
+ response.each_header { |name, value| response_headers[name.downcase] = value }
38
+ TransportResponse.new(
39
+ status: response.code.to_i,
40
+ headers: response_headers,
41
+ body: response.body.to_s.dup.force_encoding(Encoding::UTF_8)
42
+ )
43
+ rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
44
+ raise ConnectionError.new("The request timed out (#{e.class}).", timeout: true)
45
+ rescue *NETWORK_ERRORS => e
46
+ raise ConnectionError, "Network error: #{e.class}: #{e.message}"
47
+ end
48
+ end
49
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module PastClimate
4
+ VERSION = "0.1.0"
5
+ end
@@ -0,0 +1,17 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "pastclimate/version"
4
+ require "pastclimate/response"
5
+ require "pastclimate/errors"
6
+ require "pastclimate/model"
7
+ require "pastclimate/models"
8
+ require "pastclimate/place"
9
+ require "pastclimate/transport"
10
+ require "pastclimate/client"
11
+
12
+ # Official Ruby client for the PastClimate historical weather API.
13
+ #
14
+ # client = PastClimate::Client.new # reads PASTCLIMATE_API_KEY
15
+ # client.get_me.data.plan.name
16
+ module PastClimate
17
+ end