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.
@@ -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))
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"