pastclimate 0.1.0__py3-none-any.whl
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.
- pastclimate/__init__.py +117 -0
- pastclimate/_http.py +138 -0
- pastclimate/_version.py +1 -0
- pastclimate/client.py +558 -0
- pastclimate/errors.py +216 -0
- pastclimate/models.py +498 -0
- pastclimate/py.typed +0 -0
- pastclimate-0.1.0.dist-info/METADATA +302 -0
- pastclimate-0.1.0.dist-info/RECORD +11 -0
- pastclimate-0.1.0.dist-info/WHEEL +4 -0
- pastclimate-0.1.0.dist-info/licenses/LICENSE +21 -0
pastclimate/__init__.py
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
"""Official Python client for the PastClimate API.
|
|
2
|
+
|
|
3
|
+
from pastclimate import Client
|
|
4
|
+
|
|
5
|
+
client = Client() # reads PASTCLIMATE_API_KEY
|
|
6
|
+
resp = client.get_daily("gb/london", start="2024-01-01", end="2024-01-31")
|
|
7
|
+
print(resp.data[0].daily_max_temp, resp.credits_used, resp.credits_remaining)
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from ._http import HTTPRequest, HTTPResponse, RateLimit, Transport
|
|
11
|
+
from ._version import __version__
|
|
12
|
+
from .client import API_KEY_ENV_VAR, DEFAULT_BASE_URL, USER_AGENT, Client
|
|
13
|
+
from .errors import (
|
|
14
|
+
ApiError,
|
|
15
|
+
AuthenticationError,
|
|
16
|
+
InvalidRequestError,
|
|
17
|
+
NetworkError,
|
|
18
|
+
NotFoundError,
|
|
19
|
+
PastClimateError,
|
|
20
|
+
PlanRequiredError,
|
|
21
|
+
QuotaExceededError,
|
|
22
|
+
RateLimitError,
|
|
23
|
+
ServerError,
|
|
24
|
+
)
|
|
25
|
+
from .models import (
|
|
26
|
+
ApiResponse,
|
|
27
|
+
Coverage,
|
|
28
|
+
CountryCoverage,
|
|
29
|
+
CsvResponse,
|
|
30
|
+
DailyMeta,
|
|
31
|
+
DailyRow,
|
|
32
|
+
HourlyMeta,
|
|
33
|
+
HourlyRow,
|
|
34
|
+
Location,
|
|
35
|
+
LocationCoverage,
|
|
36
|
+
LocationDetail,
|
|
37
|
+
LocationSearchResult,
|
|
38
|
+
Me,
|
|
39
|
+
MeCredits,
|
|
40
|
+
MeKey,
|
|
41
|
+
MePlan,
|
|
42
|
+
MeRateLimit,
|
|
43
|
+
Meta,
|
|
44
|
+
MonthlyRow,
|
|
45
|
+
NearestLocation,
|
|
46
|
+
Normals,
|
|
47
|
+
NormalsDayRow,
|
|
48
|
+
NormalsMeta,
|
|
49
|
+
NormalsMonthlyRow,
|
|
50
|
+
OutputFormat,
|
|
51
|
+
RecordItem,
|
|
52
|
+
RecordsMeta,
|
|
53
|
+
Requested,
|
|
54
|
+
RowsMeta,
|
|
55
|
+
SearchMeta,
|
|
56
|
+
UnitSystem,
|
|
57
|
+
Units,
|
|
58
|
+
YearlyRow,
|
|
59
|
+
)
|
|
60
|
+
|
|
61
|
+
__all__ = [
|
|
62
|
+
"__version__",
|
|
63
|
+
"Client",
|
|
64
|
+
"DEFAULT_BASE_URL",
|
|
65
|
+
"API_KEY_ENV_VAR",
|
|
66
|
+
"USER_AGENT",
|
|
67
|
+
# transport
|
|
68
|
+
"HTTPRequest",
|
|
69
|
+
"HTTPResponse",
|
|
70
|
+
"Transport",
|
|
71
|
+
"RateLimit",
|
|
72
|
+
# errors
|
|
73
|
+
"PastClimateError",
|
|
74
|
+
"ApiError",
|
|
75
|
+
"AuthenticationError",
|
|
76
|
+
"InvalidRequestError",
|
|
77
|
+
"NotFoundError",
|
|
78
|
+
"PlanRequiredError",
|
|
79
|
+
"RateLimitError",
|
|
80
|
+
"QuotaExceededError",
|
|
81
|
+
"ServerError",
|
|
82
|
+
"NetworkError",
|
|
83
|
+
# response wrappers and models
|
|
84
|
+
"ApiResponse",
|
|
85
|
+
"CsvResponse",
|
|
86
|
+
"UnitSystem",
|
|
87
|
+
"OutputFormat",
|
|
88
|
+
"Units",
|
|
89
|
+
"Requested",
|
|
90
|
+
"Location",
|
|
91
|
+
"LocationSearchResult",
|
|
92
|
+
"LocationCoverage",
|
|
93
|
+
"LocationDetail",
|
|
94
|
+
"NearestLocation",
|
|
95
|
+
"DailyRow",
|
|
96
|
+
"HourlyRow",
|
|
97
|
+
"MonthlyRow",
|
|
98
|
+
"YearlyRow",
|
|
99
|
+
"NormalsMonthlyRow",
|
|
100
|
+
"NormalsDayRow",
|
|
101
|
+
"Normals",
|
|
102
|
+
"RecordItem",
|
|
103
|
+
"CountryCoverage",
|
|
104
|
+
"Coverage",
|
|
105
|
+
"MePlan",
|
|
106
|
+
"MeKey",
|
|
107
|
+
"MeCredits",
|
|
108
|
+
"MeRateLimit",
|
|
109
|
+
"Me",
|
|
110
|
+
"Meta",
|
|
111
|
+
"SearchMeta",
|
|
112
|
+
"DailyMeta",
|
|
113
|
+
"HourlyMeta",
|
|
114
|
+
"RowsMeta",
|
|
115
|
+
"NormalsMeta",
|
|
116
|
+
"RecordsMeta",
|
|
117
|
+
]
|
pastclimate/_http.py
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
"""HTTP plumbing: the transport interface, header parsing and retry timing.
|
|
2
|
+
|
|
3
|
+
Nothing here knows about PastClimate endpoints. The default transport uses only
|
|
4
|
+
the standard library; pass your own callable as ``Client(transport=...)`` to use
|
|
5
|
+
``requests``, ``httpx`` or a test double instead.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import email.utils
|
|
11
|
+
import http.client
|
|
12
|
+
import socket
|
|
13
|
+
import time
|
|
14
|
+
import urllib.error
|
|
15
|
+
import urllib.request
|
|
16
|
+
from dataclasses import dataclass, field
|
|
17
|
+
from typing import Callable, Dict, Mapping, Optional
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"HTTPRequest",
|
|
21
|
+
"HTTPResponse",
|
|
22
|
+
"Transport",
|
|
23
|
+
"RateLimit",
|
|
24
|
+
"urllib_transport",
|
|
25
|
+
"parse_retry_after",
|
|
26
|
+
"parse_rate_limit",
|
|
27
|
+
"TRANSPORT_ERRORS",
|
|
28
|
+
"is_timeout",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True)
|
|
33
|
+
class HTTPRequest:
|
|
34
|
+
"""One outgoing request, as handed to a transport."""
|
|
35
|
+
|
|
36
|
+
method: str
|
|
37
|
+
url: str
|
|
38
|
+
headers: Dict[str, str]
|
|
39
|
+
timeout: Optional[float]
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@dataclass(frozen=True)
|
|
43
|
+
class HTTPResponse:
|
|
44
|
+
"""One incoming answer. ``headers`` must have lower-cased names."""
|
|
45
|
+
|
|
46
|
+
status: int
|
|
47
|
+
headers: Dict[str, str] = field(default_factory=dict)
|
|
48
|
+
body: bytes = b""
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
Transport = Callable[[HTTPRequest], HTTPResponse]
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass(frozen=True)
|
|
55
|
+
class RateLimit:
|
|
56
|
+
"""The ``RateLimit-*`` headers of a response. ``None`` when a header is absent."""
|
|
57
|
+
|
|
58
|
+
limit: Optional[int] = None
|
|
59
|
+
remaining: Optional[int] = None
|
|
60
|
+
reset: Optional[int] = None
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
# Exceptions a transport may raise for "no answer arrived". urllib.error.URLError
|
|
64
|
+
# and socket.timeout are OSError subclasses.
|
|
65
|
+
TRANSPORT_ERRORS = (OSError, http.client.HTTPException)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _to_int(value: Optional[str]) -> Optional[int]:
|
|
69
|
+
if value is None:
|
|
70
|
+
return None
|
|
71
|
+
try:
|
|
72
|
+
return int(value.strip())
|
|
73
|
+
except ValueError:
|
|
74
|
+
return None
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def parse_rate_limit(headers: Mapping[str, str]) -> RateLimit:
|
|
78
|
+
return RateLimit(
|
|
79
|
+
limit=_to_int(headers.get("ratelimit-limit")),
|
|
80
|
+
remaining=_to_int(headers.get("ratelimit-remaining")),
|
|
81
|
+
reset=_to_int(headers.get("ratelimit-reset")),
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def parse_retry_after(value: Optional[str], now: Optional[float] = None) -> Optional[float]:
|
|
86
|
+
"""Seconds to wait from a ``Retry-After`` header, or ``None`` if absent or unreadable.
|
|
87
|
+
|
|
88
|
+
Accepts a number of seconds or an HTTP date.
|
|
89
|
+
"""
|
|
90
|
+
if value is None:
|
|
91
|
+
return None
|
|
92
|
+
text = value.strip()
|
|
93
|
+
if not text:
|
|
94
|
+
return None
|
|
95
|
+
try:
|
|
96
|
+
seconds = float(text)
|
|
97
|
+
except ValueError:
|
|
98
|
+
try:
|
|
99
|
+
when = email.utils.parsedate_to_datetime(text)
|
|
100
|
+
except (TypeError, ValueError):
|
|
101
|
+
return None
|
|
102
|
+
current = time.time() if now is None else now
|
|
103
|
+
return max(0.0, when.timestamp() - current)
|
|
104
|
+
if seconds != seconds or seconds < 0 or seconds == float("inf"):
|
|
105
|
+
return None
|
|
106
|
+
return seconds
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def urllib_transport(request: HTTPRequest) -> HTTPResponse:
|
|
110
|
+
"""Default transport, built on ``urllib.request``."""
|
|
111
|
+
req = urllib.request.Request(request.url, headers=request.headers, method=request.method)
|
|
112
|
+
try:
|
|
113
|
+
# The URL scheme is checked by Client (http or https only).
|
|
114
|
+
with urllib.request.urlopen(req, timeout=request.timeout) as resp: # noqa: S310
|
|
115
|
+
return HTTPResponse(
|
|
116
|
+
status=resp.status,
|
|
117
|
+
headers={k.lower(): v for k, v in resp.headers.items()},
|
|
118
|
+
body=resp.read(),
|
|
119
|
+
)
|
|
120
|
+
except urllib.error.HTTPError as exc:
|
|
121
|
+
# Non-2xx answers are normal data for us, not exceptions.
|
|
122
|
+
try:
|
|
123
|
+
body = exc.read()
|
|
124
|
+
finally:
|
|
125
|
+
exc.close()
|
|
126
|
+
return HTTPResponse(
|
|
127
|
+
status=exc.code,
|
|
128
|
+
headers={k.lower(): v for k, v in exc.headers.items()} if exc.headers else {},
|
|
129
|
+
body=body,
|
|
130
|
+
)
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def is_timeout(exc: BaseException) -> bool:
|
|
134
|
+
"""True when ``exc`` (as raised by a transport) means the request timed out."""
|
|
135
|
+
if isinstance(exc, (socket.timeout, TimeoutError)):
|
|
136
|
+
return True
|
|
137
|
+
reason = getattr(exc, "reason", None)
|
|
138
|
+
return isinstance(reason, (socket.timeout, TimeoutError))
|
pastclimate/_version.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|