openwec 0.2.4__tar.gz → 0.3.0__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: openwec
3
- Version: 0.2.4
3
+ Version: 0.3.0
4
4
  Summary: Python SDK for endurance racing data — WEC, ELMS, ALMS, Le Mans Cup, IMSA
5
5
  Author: Paloma C.
6
6
  License-Expression: MIT
@@ -108,7 +108,7 @@ session.plot_gap_to_leader(car_class="HYPERCAR")
108
108
  | Le Mans Cup | 2017–2026 |
109
109
  | IMSA | 2014–2026 |
110
110
 
111
- **1.96M+ laps** across all series.
111
+ **2M+ laps** across all series.
112
112
 
113
113
  ---
114
114
 
@@ -121,6 +121,48 @@ Lap-by-lap data and analytics endpoints require a free API key.
121
121
 
122
122
  ---
123
123
 
124
+ ## Errors and rate limits
125
+
126
+ Reads made without a key share a per-minute budget. A sweep over many sessions
127
+ will reach it, and the API answers `429` with a `Retry-After`. Every failure
128
+ mode has its own exception, so you can tell them apart:
129
+
130
+ | Status | Exception | What it means |
131
+ |--------|-----------|---------------|
132
+ | 401 | `OpenWECAuthError` | no key, and this endpoint needs one |
133
+ | 403 | `OpenWECPermissionError` | the key is valid but not allowed here |
134
+ | 404 | `OpenWECNotFoundError` | no such session, driver or team |
135
+ | 429 | `OpenWECRateLimitError` | budget spent — carries `.retry_after` |
136
+ | 5xx | `OpenWECServerError` | the API failed; the request was fine |
137
+
138
+ All of them derive from `OpenWECError`.
139
+
140
+ ```python
141
+ from openwec import OpenWECRateLimitError
142
+ import time
143
+
144
+ try:
145
+ laps = session.laps()
146
+ except OpenWECRateLimitError as e:
147
+ time.sleep(e.retry_after or 60) # None means the API did not say
148
+ laps = session.laps()
149
+ ```
150
+
151
+ Or let the SDK wait for you. It is **off by default** — a library should not
152
+ block your notebook without being asked:
153
+
154
+ ```python
155
+ openwec.configure(max_retries=3) # wait out up to three 429s
156
+ openwec.configure(retry_max_wait=30) # but never sleep more than 30s at once
157
+ ```
158
+
159
+ A `Retry-After` longer than `retry_max_wait` raises instead of sleeping, and a
160
+ `429` without a `Retry-After` always raises — there is nothing to wait for.
161
+
162
+ Configuring a key raises your budget and removes the shared one.
163
+
164
+ ---
165
+
124
166
  ## Session methods
125
167
 
126
168
  | Method | Description | Key required |
@@ -73,7 +73,7 @@ session.plot_gap_to_leader(car_class="HYPERCAR")
73
73
  | Le Mans Cup | 2017–2026 |
74
74
  | IMSA | 2014–2026 |
75
75
 
76
- **1.96M+ laps** across all series.
76
+ **2M+ laps** across all series.
77
77
 
78
78
  ---
79
79
 
@@ -86,6 +86,48 @@ Lap-by-lap data and analytics endpoints require a free API key.
86
86
 
87
87
  ---
88
88
 
89
+ ## Errors and rate limits
90
+
91
+ Reads made without a key share a per-minute budget. A sweep over many sessions
92
+ will reach it, and the API answers `429` with a `Retry-After`. Every failure
93
+ mode has its own exception, so you can tell them apart:
94
+
95
+ | Status | Exception | What it means |
96
+ |--------|-----------|---------------|
97
+ | 401 | `OpenWECAuthError` | no key, and this endpoint needs one |
98
+ | 403 | `OpenWECPermissionError` | the key is valid but not allowed here |
99
+ | 404 | `OpenWECNotFoundError` | no such session, driver or team |
100
+ | 429 | `OpenWECRateLimitError` | budget spent — carries `.retry_after` |
101
+ | 5xx | `OpenWECServerError` | the API failed; the request was fine |
102
+
103
+ All of them derive from `OpenWECError`.
104
+
105
+ ```python
106
+ from openwec import OpenWECRateLimitError
107
+ import time
108
+
109
+ try:
110
+ laps = session.laps()
111
+ except OpenWECRateLimitError as e:
112
+ time.sleep(e.retry_after or 60) # None means the API did not say
113
+ laps = session.laps()
114
+ ```
115
+
116
+ Or let the SDK wait for you. It is **off by default** — a library should not
117
+ block your notebook without being asked:
118
+
119
+ ```python
120
+ openwec.configure(max_retries=3) # wait out up to three 429s
121
+ openwec.configure(retry_max_wait=30) # but never sleep more than 30s at once
122
+ ```
123
+
124
+ A `Retry-After` longer than `retry_max_wait` raises instead of sleeping, and a
125
+ `429` without a `Retry-After` always raises — there is nothing to wait for.
126
+
127
+ Configuring a key raises your budget and removes the shared one.
128
+
129
+ ---
130
+
89
131
  ## Session methods
90
132
 
91
133
  | Method | Description | Key required |
@@ -31,10 +31,18 @@ Usage:
31
31
  session.plot_gap_to_leader()
32
32
  """
33
33
 
34
- from .client import configure, OpenWECError, OpenWECNotFoundError, OpenWECAuthError
34
+ from .client import (
35
+ configure,
36
+ OpenWECError,
37
+ OpenWECNotFoundError,
38
+ OpenWECAuthError,
39
+ OpenWECPermissionError,
40
+ OpenWECRateLimitError,
41
+ OpenWECServerError,
42
+ )
35
43
  from .session import Session
36
44
 
37
- __version__ = "0.2.4"
45
+ __version__ = "0.3.0"
38
46
 
39
47
  __all__ = [
40
48
  "Session",
@@ -42,4 +50,7 @@ __all__ = [
42
50
  "OpenWECError",
43
51
  "OpenWECNotFoundError",
44
52
  "OpenWECAuthError",
53
+ "OpenWECPermissionError",
54
+ "OpenWECRateLimitError",
55
+ "OpenWECServerError",
45
56
  ]
@@ -0,0 +1,193 @@
1
+ """
2
+ OpenWEC SDK — Client configuration and HTTP wrapper.
3
+ """
4
+
5
+ import email.utils
6
+ import time
7
+
8
+ import httpx
9
+
10
+
11
+ # A 429 carries Retry-After. Waiting longer than this is not a retry, it is a
12
+ # hang, so the SDK refuses to sleep past it and raises instead.
13
+ _RETRY_MAX_WAIT_SECONDS = 60.0
14
+
15
+
16
+ class _Config:
17
+ base_url: str = "https://api.openwec.com/api/v1"
18
+ api_key: str | None = None
19
+ max_retries: int = 0
20
+ retry_max_wait: float = _RETRY_MAX_WAIT_SECONDS
21
+
22
+
23
+ _config = _Config()
24
+
25
+
26
+ def configure(
27
+ base_url: str | None = None,
28
+ api_key: str | None = None,
29
+ max_retries: int | None = None,
30
+ retry_max_wait: float | None = None,
31
+ ):
32
+ """
33
+ Configure the SDK.
34
+
35
+ Args:
36
+ base_url: API base URL (default: https://api.openwec.com/api/v1)
37
+ api_key: API key for protected endpoints (laps, pace, pit-window)
38
+ max_retries: how many times to wait out a 429 before raising.
39
+ Default 0 — a rate-limited call raises OpenWECRateLimitError
40
+ immediately, and you decide what to do. Set it to 2 or 3 in a
41
+ notebook that sweeps many sessions.
42
+ retry_max_wait: never sleep longer than this for one retry, in
43
+ seconds (default 60). A Retry-After above it raises instead.
44
+ """
45
+ if base_url:
46
+ _config.base_url = base_url.rstrip("/")
47
+ if api_key:
48
+ _config.api_key = api_key
49
+ if max_retries is not None:
50
+ if max_retries < 0:
51
+ raise ValueError("max_retries must be zero or more")
52
+ _config.max_retries = max_retries
53
+ if retry_max_wait is not None:
54
+ if retry_max_wait <= 0:
55
+ raise ValueError("retry_max_wait must be positive")
56
+ _config.retry_max_wait = retry_max_wait
57
+
58
+
59
+ def _headers() -> dict:
60
+ headers = {}
61
+ if _config.api_key:
62
+ headers["X-API-Key"] = _config.api_key
63
+ return headers
64
+
65
+
66
+ def _retry_after(resp: httpx.Response) -> float | None:
67
+ """
68
+ Seconds to wait, from the Retry-After header.
69
+
70
+ The header is either a number of seconds or an HTTP date; both are legal
71
+ and the API has used both over time. Anything else, or a date already in
72
+ the past, reads as None — the caller then has no guidance, which is
73
+ different from being told to wait zero.
74
+ """
75
+ bruto = resp.headers.get("Retry-After")
76
+ if not bruto:
77
+ return None
78
+
79
+ bruto = bruto.strip()
80
+ try:
81
+ return max(0.0, float(bruto))
82
+ except ValueError:
83
+ pass
84
+
85
+ try:
86
+ quando = email.utils.parsedate_to_datetime(bruto)
87
+ except (TypeError, ValueError):
88
+ return None
89
+ if quando is None:
90
+ return None
91
+ espera = quando.timestamp() - time.time()
92
+ return espera if espera > 0 else None
93
+
94
+
95
+ def _get(path: str, params: dict | None = None) -> dict | list:
96
+ """Performs a GET request to the OpenWEC API. Raises on error."""
97
+ url = f"{_config.base_url}{path}"
98
+ tentativas = 0
99
+
100
+ while True:
101
+ resp = httpx.get(url, params=params, headers=_headers(), timeout=30)
102
+
103
+ if resp.status_code == 404:
104
+ raise OpenWECNotFoundError(f"Not found: {path} ({resp.text})")
105
+
106
+ if resp.status_code == 401:
107
+ raise OpenWECAuthError(
108
+ "Unauthorized — this endpoint requires an API key. "
109
+ "Call openwec.configure(api_key='...') first."
110
+ )
111
+
112
+ if resp.status_code == 403:
113
+ raise OpenWECPermissionError(
114
+ f"Forbidden — the key is valid but not allowed here: {path}"
115
+ )
116
+
117
+ if resp.status_code == 429:
118
+ espera = _retry_after(resp)
119
+ podemos = (
120
+ tentativas < _config.max_retries
121
+ and espera is not None
122
+ and espera <= _config.retry_max_wait
123
+ )
124
+ if not podemos:
125
+ raise OpenWECRateLimitError(
126
+ _mensagem_de_limite(path, espera), retry_after=espera
127
+ )
128
+ time.sleep(espera)
129
+ tentativas += 1
130
+ continue
131
+
132
+ if resp.status_code >= 500:
133
+ raise OpenWECServerError(
134
+ f"Server error {resp.status_code} from {path}. "
135
+ "This is the API's problem, not the request's — retry later."
136
+ )
137
+
138
+ resp.raise_for_status()
139
+ return resp.json()
140
+
141
+
142
+ def _mensagem_de_limite(path: str, espera: float | None) -> str:
143
+ quando = (
144
+ f"Retry after {espera:.0f}s." if espera is not None
145
+ else "The response gave no Retry-After."
146
+ )
147
+ chave = (
148
+ "Reads without a key share a per-minute budget; configure(api_key=...) "
149
+ "raises it." if not _config.api_key else
150
+ "This key's own per-minute budget is spent."
151
+ )
152
+ return (
153
+ f"Rate limited on {path}. {quando} {chave} "
154
+ "Pass max_retries= to configure() to wait automatically."
155
+ )
156
+
157
+
158
+ class OpenWECError(Exception):
159
+ """Base exception for OpenWEC SDK errors."""
160
+
161
+
162
+ class OpenWECNotFoundError(OpenWECError):
163
+ """Raised when a resource is not found (404)."""
164
+
165
+
166
+ class OpenWECAuthError(OpenWECError):
167
+ """Raised when an API key is required but missing/invalid (401)."""
168
+
169
+
170
+ class OpenWECPermissionError(OpenWECError):
171
+ """Raised when the key is accepted but not allowed here (403)."""
172
+
173
+
174
+ class OpenWECRateLimitError(OpenWECError):
175
+ """
176
+ Raised when the API returns 429.
177
+
178
+ `retry_after` is the seconds the API asked for, or None when it did not
179
+ say. Catch this rather than sleeping blind:
180
+
181
+ try:
182
+ laps = session.laps()
183
+ except OpenWECRateLimitError as e:
184
+ time.sleep(e.retry_after or 60)
185
+ """
186
+
187
+ def __init__(self, message: str, retry_after: float | None = None):
188
+ super().__init__(message)
189
+ self.retry_after = retry_after
190
+
191
+
192
+ class OpenWECServerError(OpenWECError):
193
+ """Raised on 5xx — the API failed, the request was fine."""
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: openwec
3
- Version: 0.2.4
3
+ Version: 0.3.0
4
4
  Summary: Python SDK for endurance racing data — WEC, ELMS, ALMS, Le Mans Cup, IMSA
5
5
  Author: Paloma C.
6
6
  License-Expression: MIT
@@ -108,7 +108,7 @@ session.plot_gap_to_leader(car_class="HYPERCAR")
108
108
  | Le Mans Cup | 2017–2026 |
109
109
  | IMSA | 2014–2026 |
110
110
 
111
- **1.96M+ laps** across all series.
111
+ **2M+ laps** across all series.
112
112
 
113
113
  ---
114
114
 
@@ -121,6 +121,48 @@ Lap-by-lap data and analytics endpoints require a free API key.
121
121
 
122
122
  ---
123
123
 
124
+ ## Errors and rate limits
125
+
126
+ Reads made without a key share a per-minute budget. A sweep over many sessions
127
+ will reach it, and the API answers `429` with a `Retry-After`. Every failure
128
+ mode has its own exception, so you can tell them apart:
129
+
130
+ | Status | Exception | What it means |
131
+ |--------|-----------|---------------|
132
+ | 401 | `OpenWECAuthError` | no key, and this endpoint needs one |
133
+ | 403 | `OpenWECPermissionError` | the key is valid but not allowed here |
134
+ | 404 | `OpenWECNotFoundError` | no such session, driver or team |
135
+ | 429 | `OpenWECRateLimitError` | budget spent — carries `.retry_after` |
136
+ | 5xx | `OpenWECServerError` | the API failed; the request was fine |
137
+
138
+ All of them derive from `OpenWECError`.
139
+
140
+ ```python
141
+ from openwec import OpenWECRateLimitError
142
+ import time
143
+
144
+ try:
145
+ laps = session.laps()
146
+ except OpenWECRateLimitError as e:
147
+ time.sleep(e.retry_after or 60) # None means the API did not say
148
+ laps = session.laps()
149
+ ```
150
+
151
+ Or let the SDK wait for you. It is **off by default** — a library should not
152
+ block your notebook without being asked:
153
+
154
+ ```python
155
+ openwec.configure(max_retries=3) # wait out up to three 429s
156
+ openwec.configure(retry_max_wait=30) # but never sleep more than 30s at once
157
+ ```
158
+
159
+ A `Retry-After` longer than `retry_max_wait` raises instead of sleeping, and a
160
+ `429` without a `Retry-After` always raises — there is nothing to wait for.
161
+
162
+ Configuring a key raises your budget and removes the shared one.
163
+
164
+ ---
165
+
124
166
  ## Session methods
125
167
 
126
168
  | Method | Description | Key required |
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "openwec"
7
- version = "0.2.4"
7
+ version = "0.3.0"
8
8
  description = "Python SDK for endurance racing data — WEC, ELMS, ALMS, Le Mans Cup, IMSA"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -1,62 +0,0 @@
1
- """
2
- OpenWEC SDK — Client configuration and HTTP wrapper.
3
- """
4
-
5
- import httpx
6
-
7
-
8
- class _Config:
9
- base_url: str = "https://api.openwec.com/api/v1"
10
- api_key: str | None = None
11
-
12
-
13
- _config = _Config()
14
-
15
-
16
- def configure(base_url: str | None = None, api_key: str | None = None):
17
- """
18
- Configure the SDK.
19
-
20
- Args:
21
- base_url: API base URL (default: https://api.openwec.com/api/v1)
22
- api_key: API key for protected endpoints (laps, analytics)
23
- """
24
- if base_url:
25
- _config.base_url = base_url.rstrip("/")
26
- if api_key:
27
- _config.api_key = api_key
28
-
29
-
30
- def _headers() -> dict:
31
- headers = {}
32
- if _config.api_key:
33
- headers["X-API-Key"] = _config.api_key
34
- return headers
35
-
36
-
37
- def _get(path: str, params: dict | None = None) -> dict | list:
38
- """Performs a GET request to the OpenWEC API. Raises on error."""
39
- url = f"{_config.base_url}{path}"
40
- resp = httpx.get(url, params=params, headers=_headers(), timeout=30)
41
-
42
- if resp.status_code == 404:
43
- raise OpenWECNotFoundError(f"Not found: {path} ({resp.text})")
44
- if resp.status_code == 401:
45
- raise OpenWECAuthError(
46
- "Unauthorized — this endpoint requires an API key. "
47
- "Call openwec.configure(api_key='...') first."
48
- )
49
- resp.raise_for_status()
50
- return resp.json()
51
-
52
-
53
- class OpenWECError(Exception):
54
- """Base exception for OpenWEC SDK errors."""
55
-
56
-
57
- class OpenWECNotFoundError(OpenWECError):
58
- """Raised when a resource is not found (404)."""
59
-
60
-
61
- class OpenWECAuthError(OpenWECError):
62
- """Raised when an API key is required but missing/invalid (401)."""
File without changes
File without changes
File without changes
File without changes