blitz-api-py 2.1.0__tar.gz → 3.0.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.
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/CHANGELOG.md +18 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/PKG-INFO +47 -13
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/README.md +45 -11
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/__init__.py +5 -2
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_base_client.py +7 -5
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_client_async.py +13 -2
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_client_sync.py +13 -2
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_exceptions.py +54 -4
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_pagination_async.py +1 -1
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_pagination_base.py +8 -3
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_pagination_sync.py +1 -1
- blitz_api_py-3.0.0/src/blitz_api/_version.py +1 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/__init__.py +8 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/account.py +1 -1
- blitz_api_py-3.0.0/src/blitz_api/resources/_async/changelog.py +53 -0
- blitz_api_py-3.0.0/src/blitz_api/resources/_async/company.py +55 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/account.py +1 -1
- blitz_api_py-3.0.0/src/blitz_api/resources/_sync/changelog.py +55 -0
- blitz_api_py-3.0.0/src/blitz_api/resources/_sync/company.py +57 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/__init__.py +14 -0
- blitz_api_py-3.0.0/src/blitz_api/types/_models.py +74 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/account.py +5 -3
- blitz_api_py-3.0.0/src/blitz_api/types/changelog.py +58 -0
- blitz_api_py-3.0.0/src/blitz_api/types/company.py +31 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/enrichment.py +10 -10
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/filters.py +23 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/search.py +2 -2
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/utils.py +2 -2
- blitz_api_py-2.1.0/src/blitz_api/_version.py +0 -1
- blitz_api_py-2.1.0/src/blitz_api/types/_models.py +0 -23
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/.gitignore +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/LICENSE +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/pyproject.toml +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_client.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_compat.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_constants.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_rate_limit.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_rate_limit_async.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_rate_limit_sync.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/py.typed +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/__init__.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/enrichment.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/jobs.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/search.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/utils.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/enrichment.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/search.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/utils.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/enums.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/jobs.py +0 -0
- {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/shared.py +0 -0
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [3.0.0](https://github.com/api-blitz/blitz-api-py/compare/v2.2.0...v3.0.0) (2026-09-02)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### ⚠ BREAKING CHANGES
|
|
7
|
+
|
|
8
|
+
* `KeyInfo.remaining_credits` is renamed to `KeyInfo.records_remaining`.
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
* records vocabulary rename + fair_usage envelope on every response ([698fd6d](https://github.com/api-blitz/blitz-api-py/commit/698fd6dc95bbe6120c55064255820898b708da42))
|
|
13
|
+
|
|
14
|
+
## [2.2.0](https://github.com/api-blitz/blitz-api-py/compare/v2.1.0...v2.2.0) (2026-08-13)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
### Features
|
|
18
|
+
|
|
19
|
+
* add company and changelog resources with new endpoints ([0dd4ae0](https://github.com/api-blitz/blitz-api-py/commit/0dd4ae0df510352c72143f00431e66b947409758))
|
|
20
|
+
|
|
3
21
|
## [2.1.0](https://github.com/api-blitz/blitz-api-py/compare/v2.0.0...v2.1.0) (2026-07-23)
|
|
4
22
|
|
|
5
23
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: blitz-api-py
|
|
3
|
-
Version:
|
|
3
|
+
Version: 3.0.0
|
|
4
4
|
Summary: Typed Python SDK for the Blitz API — B2B data, search, and enrichment.
|
|
5
5
|
Project-URL: Homepage, https://blitz-api.ai
|
|
6
6
|
Project-URL: Documentation, https://docs.blitz-api.ai
|
|
@@ -53,7 +53,7 @@ and enrichment.
|
|
|
53
53
|
|
|
54
54
|
> **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
|
|
55
55
|
> loop streams every match up to the server-side limit (people: 50k results), which can be
|
|
56
|
-
> a lot of
|
|
56
|
+
> a lot of records. Bound spend with **`max_items`** (a client-side total cap on
|
|
57
57
|
> `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
|
|
58
58
|
> [Pagination](#pagination).
|
|
59
59
|
|
|
@@ -65,6 +65,7 @@ and enrichment.
|
|
|
65
65
|
- [Authentication](#authentication)
|
|
66
66
|
- [Endpoints](#endpoints)
|
|
67
67
|
- [Pagination](#pagination)
|
|
68
|
+
- [Usage & rate limit (`fair_usage`)](#usage--rate-limit-fair_usage)
|
|
68
69
|
- [Configuration](#configuration)
|
|
69
70
|
- [Error handling](#error-handling)
|
|
70
71
|
- [Forward compatibility](#forward-compatibility)
|
|
@@ -89,7 +90,7 @@ from blitz_api.types import Industry, JobLevel
|
|
|
89
90
|
with BlitzAPI() as client:
|
|
90
91
|
# Health-check the key before a batch job.
|
|
91
92
|
info = client.account.key_info()
|
|
92
|
-
print(info.valid, info.
|
|
93
|
+
print(info.valid, info.records_remaining, info.max_requests_per_seconds)
|
|
93
94
|
|
|
94
95
|
# LinkedIn profile URL -> verified work email.
|
|
95
96
|
email = client.enrichment.email(
|
|
@@ -117,7 +118,7 @@ from blitz_api import AsyncBlitzAPI
|
|
|
117
118
|
async def main() -> None:
|
|
118
119
|
async with AsyncBlitzAPI() as client:
|
|
119
120
|
result = await client.enrichment.company(
|
|
120
|
-
company_linkedin_url="https://www.linkedin.com/company/
|
|
121
|
+
company_linkedin_url="https://www.linkedin.com/company/placeholder-co",
|
|
121
122
|
)
|
|
122
123
|
print(result.company.name if result.company else None)
|
|
123
124
|
|
|
@@ -127,7 +128,7 @@ asyncio.run(main())
|
|
|
127
128
|
## Example: find, enrich, collect
|
|
128
129
|
|
|
129
130
|
A complete flow — find people, enrich each one's verified work email, collect the
|
|
130
|
-
contacts. `max_items` caps the total fetched so the run can't surprise you with
|
|
131
|
+
contacts. `max_items` caps the total fetched so the run can't surprise you with records.
|
|
131
132
|
|
|
132
133
|
```python
|
|
133
134
|
from blitz_api import BlitzAPI
|
|
@@ -140,7 +141,7 @@ leads = client.search.people(
|
|
|
140
141
|
company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
|
|
141
142
|
people={"job_level": [JobLevel.VP]},
|
|
142
143
|
max_results=25,
|
|
143
|
-
).collect(max_items=25) # client-side total cap — bounds
|
|
144
|
+
).collect(max_items=25) # client-side total cap — bounds record spend
|
|
144
145
|
|
|
145
146
|
# 2. Enrich each lead's verified work email from their LinkedIn profile URL.
|
|
146
147
|
contacts: list[dict[str, str | None]] = []
|
|
@@ -193,15 +194,17 @@ always call the API from your backend.
|
|
|
193
194
|
|
|
194
195
|
## Endpoints
|
|
195
196
|
|
|
196
|
-
All methods are grouped into
|
|
197
|
+
All methods are grouped into seven namespaces:
|
|
197
198
|
|
|
198
199
|
| Namespace | Methods |
|
|
199
200
|
| --- | --- |
|
|
200
201
|
| `client.account` | `key_info()` |
|
|
201
202
|
| `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
|
|
202
203
|
| `client.jobs` | `search()`, `company()` |
|
|
204
|
+
| `client.company` | `tam_by_jobs()` |
|
|
203
205
|
| `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
|
|
204
206
|
| `client.utils` | `current_date()` |
|
|
207
|
+
| `client.changelog` | `list()` |
|
|
205
208
|
|
|
206
209
|
Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
|
|
207
210
|
filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
|
|
@@ -215,9 +218,9 @@ fetches each subsequent page for you. `search.people`/`search.companies` and
|
|
|
215
218
|
all behave identically here.
|
|
216
219
|
|
|
217
220
|
> **`max_results` is the page size, not a total.** It's results per page, and the API
|
|
218
|
-
> **bills 1
|
|
221
|
+
> **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
|
|
219
222
|
> loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
|
|
220
|
-
> employee finder: 10k; jobs: 5k), which can be a lot of
|
|
223
|
+
> employee finder: 10k; jobs: 5k), which can be a lot of records. Bound it with **`max_items`** on
|
|
221
224
|
> `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
|
|
222
225
|
> `break` out of the loop, or drive pages manually.
|
|
223
226
|
|
|
@@ -254,6 +257,37 @@ nxt = page.get_next_page() # None once exhausted
|
|
|
254
257
|
The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
|
|
255
258
|
exported from `blitz_api`.
|
|
256
259
|
|
|
260
|
+
## Usage & rate limit (`fair_usage`)
|
|
261
|
+
|
|
262
|
+
Every `/v2` response carries a `fair_usage` block: what the call cost, what's left on
|
|
263
|
+
the plan, your rate-limit headroom, and a request id to quote to support. It's on every
|
|
264
|
+
response model and on every page, so you can meter a long run without extra `key_info()`
|
|
265
|
+
calls.
|
|
266
|
+
|
|
267
|
+
```python
|
|
268
|
+
result = client.enrichment.email(person_linkedin_url="https://www.linkedin.com/in/example")
|
|
269
|
+
if result.fair_usage is not None:
|
|
270
|
+
print(result.fair_usage.records_used) # what this call cost
|
|
271
|
+
print(result.fair_usage.records_remaining) # a number, or "unlimited"
|
|
272
|
+
print(result.fair_usage.next_reset_at) # None on an unlimited plan
|
|
273
|
+
print(result.fair_usage.request_id) # quote this to support
|
|
274
|
+
if result.fair_usage.rate_limit is not None: # absent on account.key_info()
|
|
275
|
+
print(result.fair_usage.rate_limit.remaining_this_second)
|
|
276
|
+
|
|
277
|
+
# Pages carry the block of the request that fetched them.
|
|
278
|
+
for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pages=5):
|
|
279
|
+
print(page.fair_usage.records_used if page.fair_usage else None)
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
`InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
|
|
283
|
+
resets without a second call:
|
|
284
|
+
|
|
285
|
+
```python
|
|
286
|
+
except InsufficientRecordsError as err:
|
|
287
|
+
if err.fair_usage is not None:
|
|
288
|
+
print("resets at", err.fair_usage.next_reset_at)
|
|
289
|
+
```
|
|
290
|
+
|
|
257
291
|
## Configuration
|
|
258
292
|
|
|
259
293
|
```python
|
|
@@ -286,15 +320,15 @@ client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
|
|
|
286
320
|
|
|
287
321
|
```python
|
|
288
322
|
from blitz_api import (
|
|
289
|
-
BlitzError, AuthenticationError,
|
|
323
|
+
BlitzError, AuthenticationError, InsufficientRecordsError,
|
|
290
324
|
NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
|
|
291
325
|
APITimeoutError, APIResponseValidationError,
|
|
292
326
|
)
|
|
293
327
|
|
|
294
328
|
try:
|
|
295
329
|
client.enrichment.email(person_linkedin_url="...")
|
|
296
|
-
except
|
|
297
|
-
... # 402 — out of
|
|
330
|
+
except InsufficientRecordsError as err:
|
|
331
|
+
... # 402 — out of records; err.fair_usage.next_reset_at
|
|
298
332
|
except AuthenticationError:
|
|
299
333
|
... # 401 — bad key
|
|
300
334
|
except APIStatusError as err:
|
|
@@ -22,7 +22,7 @@ and enrichment.
|
|
|
22
22
|
|
|
23
23
|
> **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
|
|
24
24
|
> loop streams every match up to the server-side limit (people: 50k results), which can be
|
|
25
|
-
> a lot of
|
|
25
|
+
> a lot of records. Bound spend with **`max_items`** (a client-side total cap on
|
|
26
26
|
> `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
|
|
27
27
|
> [Pagination](#pagination).
|
|
28
28
|
|
|
@@ -34,6 +34,7 @@ and enrichment.
|
|
|
34
34
|
- [Authentication](#authentication)
|
|
35
35
|
- [Endpoints](#endpoints)
|
|
36
36
|
- [Pagination](#pagination)
|
|
37
|
+
- [Usage & rate limit (`fair_usage`)](#usage--rate-limit-fair_usage)
|
|
37
38
|
- [Configuration](#configuration)
|
|
38
39
|
- [Error handling](#error-handling)
|
|
39
40
|
- [Forward compatibility](#forward-compatibility)
|
|
@@ -58,7 +59,7 @@ from blitz_api.types import Industry, JobLevel
|
|
|
58
59
|
with BlitzAPI() as client:
|
|
59
60
|
# Health-check the key before a batch job.
|
|
60
61
|
info = client.account.key_info()
|
|
61
|
-
print(info.valid, info.
|
|
62
|
+
print(info.valid, info.records_remaining, info.max_requests_per_seconds)
|
|
62
63
|
|
|
63
64
|
# LinkedIn profile URL -> verified work email.
|
|
64
65
|
email = client.enrichment.email(
|
|
@@ -86,7 +87,7 @@ from blitz_api import AsyncBlitzAPI
|
|
|
86
87
|
async def main() -> None:
|
|
87
88
|
async with AsyncBlitzAPI() as client:
|
|
88
89
|
result = await client.enrichment.company(
|
|
89
|
-
company_linkedin_url="https://www.linkedin.com/company/
|
|
90
|
+
company_linkedin_url="https://www.linkedin.com/company/placeholder-co",
|
|
90
91
|
)
|
|
91
92
|
print(result.company.name if result.company else None)
|
|
92
93
|
|
|
@@ -96,7 +97,7 @@ asyncio.run(main())
|
|
|
96
97
|
## Example: find, enrich, collect
|
|
97
98
|
|
|
98
99
|
A complete flow — find people, enrich each one's verified work email, collect the
|
|
99
|
-
contacts. `max_items` caps the total fetched so the run can't surprise you with
|
|
100
|
+
contacts. `max_items` caps the total fetched so the run can't surprise you with records.
|
|
100
101
|
|
|
101
102
|
```python
|
|
102
103
|
from blitz_api import BlitzAPI
|
|
@@ -109,7 +110,7 @@ leads = client.search.people(
|
|
|
109
110
|
company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
|
|
110
111
|
people={"job_level": [JobLevel.VP]},
|
|
111
112
|
max_results=25,
|
|
112
|
-
).collect(max_items=25) # client-side total cap — bounds
|
|
113
|
+
).collect(max_items=25) # client-side total cap — bounds record spend
|
|
113
114
|
|
|
114
115
|
# 2. Enrich each lead's verified work email from their LinkedIn profile URL.
|
|
115
116
|
contacts: list[dict[str, str | None]] = []
|
|
@@ -162,15 +163,17 @@ always call the API from your backend.
|
|
|
162
163
|
|
|
163
164
|
## Endpoints
|
|
164
165
|
|
|
165
|
-
All methods are grouped into
|
|
166
|
+
All methods are grouped into seven namespaces:
|
|
166
167
|
|
|
167
168
|
| Namespace | Methods |
|
|
168
169
|
| --- | --- |
|
|
169
170
|
| `client.account` | `key_info()` |
|
|
170
171
|
| `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
|
|
171
172
|
| `client.jobs` | `search()`, `company()` |
|
|
173
|
+
| `client.company` | `tam_by_jobs()` |
|
|
172
174
|
| `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
|
|
173
175
|
| `client.utils` | `current_date()` |
|
|
176
|
+
| `client.changelog` | `list()` |
|
|
174
177
|
|
|
175
178
|
Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
|
|
176
179
|
filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
|
|
@@ -184,9 +187,9 @@ fetches each subsequent page for you. `search.people`/`search.companies` and
|
|
|
184
187
|
all behave identically here.
|
|
185
188
|
|
|
186
189
|
> **`max_results` is the page size, not a total.** It's results per page, and the API
|
|
187
|
-
> **bills 1
|
|
190
|
+
> **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
|
|
188
191
|
> loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
|
|
189
|
-
> employee finder: 10k; jobs: 5k), which can be a lot of
|
|
192
|
+
> employee finder: 10k; jobs: 5k), which can be a lot of records. Bound it with **`max_items`** on
|
|
190
193
|
> `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
|
|
191
194
|
> `break` out of the loop, or drive pages manually.
|
|
192
195
|
|
|
@@ -223,6 +226,37 @@ nxt = page.get_next_page() # None once exhausted
|
|
|
223
226
|
The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
|
|
224
227
|
exported from `blitz_api`.
|
|
225
228
|
|
|
229
|
+
## Usage & rate limit (`fair_usage`)
|
|
230
|
+
|
|
231
|
+
Every `/v2` response carries a `fair_usage` block: what the call cost, what's left on
|
|
232
|
+
the plan, your rate-limit headroom, and a request id to quote to support. It's on every
|
|
233
|
+
response model and on every page, so you can meter a long run without extra `key_info()`
|
|
234
|
+
calls.
|
|
235
|
+
|
|
236
|
+
```python
|
|
237
|
+
result = client.enrichment.email(person_linkedin_url="https://www.linkedin.com/in/example")
|
|
238
|
+
if result.fair_usage is not None:
|
|
239
|
+
print(result.fair_usage.records_used) # what this call cost
|
|
240
|
+
print(result.fair_usage.records_remaining) # a number, or "unlimited"
|
|
241
|
+
print(result.fair_usage.next_reset_at) # None on an unlimited plan
|
|
242
|
+
print(result.fair_usage.request_id) # quote this to support
|
|
243
|
+
if result.fair_usage.rate_limit is not None: # absent on account.key_info()
|
|
244
|
+
print(result.fair_usage.rate_limit.remaining_this_second)
|
|
245
|
+
|
|
246
|
+
# Pages carry the block of the request that fetched them.
|
|
247
|
+
for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pages=5):
|
|
248
|
+
print(page.fair_usage.records_used if page.fair_usage else None)
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
`InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
|
|
252
|
+
resets without a second call:
|
|
253
|
+
|
|
254
|
+
```python
|
|
255
|
+
except InsufficientRecordsError as err:
|
|
256
|
+
if err.fair_usage is not None:
|
|
257
|
+
print("resets at", err.fair_usage.next_reset_at)
|
|
258
|
+
```
|
|
259
|
+
|
|
226
260
|
## Configuration
|
|
227
261
|
|
|
228
262
|
```python
|
|
@@ -255,15 +289,15 @@ client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
|
|
|
255
289
|
|
|
256
290
|
```python
|
|
257
291
|
from blitz_api import (
|
|
258
|
-
BlitzError, AuthenticationError,
|
|
292
|
+
BlitzError, AuthenticationError, InsufficientRecordsError,
|
|
259
293
|
NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
|
|
260
294
|
APITimeoutError, APIResponseValidationError,
|
|
261
295
|
)
|
|
262
296
|
|
|
263
297
|
try:
|
|
264
298
|
client.enrichment.email(person_linkedin_url="...")
|
|
265
|
-
except
|
|
266
|
-
... # 402 — out of
|
|
299
|
+
except InsufficientRecordsError as err:
|
|
300
|
+
... # 402 — out of records; err.fair_usage.next_reset_at
|
|
267
301
|
except AuthenticationError:
|
|
268
302
|
... # 401 — bad key
|
|
269
303
|
except APIStatusError as err:
|
|
@@ -23,7 +23,8 @@ from ._exceptions import (
|
|
|
23
23
|
APITimeoutError,
|
|
24
24
|
AuthenticationError,
|
|
25
25
|
BlitzError,
|
|
26
|
-
InsufficientCreditsError,
|
|
26
|
+
InsufficientCreditsError, # pyright: ignore[reportDeprecated]
|
|
27
|
+
InsufficientRecordsError,
|
|
27
28
|
NotFoundError,
|
|
28
29
|
RateLimitError,
|
|
29
30
|
ServerError,
|
|
@@ -54,10 +55,12 @@ __all__ = [
|
|
|
54
55
|
"APIResponseValidationError",
|
|
55
56
|
"APIStatusError",
|
|
56
57
|
"AuthenticationError",
|
|
57
|
-
"
|
|
58
|
+
"InsufficientRecordsError",
|
|
58
59
|
"NotFoundError",
|
|
59
60
|
"RateLimitError",
|
|
60
61
|
"ServerError",
|
|
62
|
+
# deprecated alias (removed in 3.0.0)
|
|
63
|
+
"InsufficientCreditsError",
|
|
61
64
|
# commonly-used types (full set under blitz_api.types)
|
|
62
65
|
"Industry",
|
|
63
66
|
"CompanyFilter",
|
|
@@ -16,7 +16,7 @@ from typing import Any, TypeVar, cast
|
|
|
16
16
|
from urllib.parse import urljoin
|
|
17
17
|
|
|
18
18
|
import httpx
|
|
19
|
-
from pydantic import ValidationError
|
|
19
|
+
from pydantic import BaseModel, ValidationError
|
|
20
20
|
|
|
21
21
|
from . import _constants as C
|
|
22
22
|
from ._exceptions import (
|
|
@@ -24,20 +24,22 @@ from ._exceptions import (
|
|
|
24
24
|
APIStatusError,
|
|
25
25
|
AuthenticationError,
|
|
26
26
|
BlitzError,
|
|
27
|
-
|
|
27
|
+
InsufficientRecordsError,
|
|
28
28
|
NotFoundError,
|
|
29
29
|
RateLimitError,
|
|
30
30
|
ServerError,
|
|
31
31
|
)
|
|
32
|
-
from .types._models import BlitzModel
|
|
33
32
|
|
|
34
|
-
|
|
33
|
+
# Bound to ``pydantic.BaseModel`` (not ``BlitzModel``) so the request pipeline can also
|
|
34
|
+
# validate a ``RootModel`` — used for ``changelog.list``'s top-level JSON array
|
|
35
|
+
# (``ChangelogResponse``), which is a ``BaseModel`` but not a ``BlitzModel``.
|
|
36
|
+
ResponseT = TypeVar("ResponseT", bound=BaseModel)
|
|
35
37
|
|
|
36
38
|
# Status code -> exception class. Anything not listed that is still non-2xx
|
|
37
39
|
# falls back to a generic APIStatusError (or ServerError for any 5xx).
|
|
38
40
|
_STATUS_EXCEPTIONS: dict[int, type[APIStatusError]] = {
|
|
39
41
|
401: AuthenticationError,
|
|
40
|
-
402:
|
|
42
|
+
402: InsufficientRecordsError,
|
|
41
43
|
404: NotFoundError,
|
|
42
44
|
429: RateLimitError,
|
|
43
45
|
}
|
|
@@ -16,6 +16,8 @@ from ._pagination_base import BasePage
|
|
|
16
16
|
from ._rate_limit import AsyncRateLimiter
|
|
17
17
|
from .resources import (
|
|
18
18
|
AsyncAccountResource,
|
|
19
|
+
AsyncChangelogResource,
|
|
20
|
+
AsyncCompanyResource,
|
|
19
21
|
AsyncEnrichmentResource,
|
|
20
22
|
AsyncJobsResource,
|
|
21
23
|
AsyncSearchResource,
|
|
@@ -86,6 +88,7 @@ class AsyncBlitzAPI(BaseClient):
|
|
|
86
88
|
*,
|
|
87
89
|
body: Any | None,
|
|
88
90
|
cast_to: type[ResponseT],
|
|
91
|
+
params: dict[str, Any] | None = None,
|
|
89
92
|
timeout: TimeoutParam = None,
|
|
90
93
|
) -> ResponseT:
|
|
91
94
|
url = self._build_url(path)
|
|
@@ -98,11 +101,11 @@ class AsyncBlitzAPI(BaseClient):
|
|
|
98
101
|
try:
|
|
99
102
|
if timeout is None:
|
|
100
103
|
response = await self._http_client.request(
|
|
101
|
-
method, url, headers=headers, json=json_body
|
|
104
|
+
method, url, headers=headers, json=json_body, params=params
|
|
102
105
|
)
|
|
103
106
|
else:
|
|
104
107
|
response = await self._http_client.request(
|
|
105
|
-
method, url, headers=headers, json=json_body, timeout=timeout
|
|
108
|
+
method, url, headers=headers, json=json_body, params=params, timeout=timeout
|
|
106
109
|
)
|
|
107
110
|
except httpx.TimeoutException as exc:
|
|
108
111
|
if self._should_retry_exception(exc) and attempt < self.max_retries:
|
|
@@ -160,6 +163,10 @@ class AsyncBlitzAPI(BaseClient):
|
|
|
160
163
|
def jobs(self) -> AsyncJobsResource:
|
|
161
164
|
return AsyncJobsResource(self)
|
|
162
165
|
|
|
166
|
+
@cached_property
|
|
167
|
+
def company(self) -> AsyncCompanyResource:
|
|
168
|
+
return AsyncCompanyResource(self)
|
|
169
|
+
|
|
163
170
|
@cached_property
|
|
164
171
|
def enrichment(self) -> AsyncEnrichmentResource:
|
|
165
172
|
return AsyncEnrichmentResource(self)
|
|
@@ -167,3 +174,7 @@ class AsyncBlitzAPI(BaseClient):
|
|
|
167
174
|
@cached_property
|
|
168
175
|
def utils(self) -> AsyncUtilsResource:
|
|
169
176
|
return AsyncUtilsResource(self)
|
|
177
|
+
|
|
178
|
+
@cached_property
|
|
179
|
+
def changelog(self) -> AsyncChangelogResource:
|
|
180
|
+
return AsyncChangelogResource(self)
|
|
@@ -18,6 +18,8 @@ from ._pagination_base import BasePage
|
|
|
18
18
|
from ._rate_limit import RateLimiter
|
|
19
19
|
from .resources import (
|
|
20
20
|
AccountResource,
|
|
21
|
+
ChangelogResource,
|
|
22
|
+
CompanyResource,
|
|
21
23
|
EnrichmentResource,
|
|
22
24
|
JobsResource,
|
|
23
25
|
SearchResource,
|
|
@@ -88,6 +90,7 @@ class BlitzAPI(BaseClient):
|
|
|
88
90
|
*,
|
|
89
91
|
body: Any | None,
|
|
90
92
|
cast_to: type[ResponseT],
|
|
93
|
+
params: dict[str, Any] | None = None,
|
|
91
94
|
timeout: TimeoutParam = None,
|
|
92
95
|
) -> ResponseT:
|
|
93
96
|
url = self._build_url(path)
|
|
@@ -100,11 +103,11 @@ class BlitzAPI(BaseClient):
|
|
|
100
103
|
try:
|
|
101
104
|
if timeout is None:
|
|
102
105
|
response = self._http_client.request(
|
|
103
|
-
method, url, headers=headers, json=json_body
|
|
106
|
+
method, url, headers=headers, json=json_body, params=params
|
|
104
107
|
)
|
|
105
108
|
else:
|
|
106
109
|
response = self._http_client.request(
|
|
107
|
-
method, url, headers=headers, json=json_body, timeout=timeout
|
|
110
|
+
method, url, headers=headers, json=json_body, params=params, timeout=timeout
|
|
108
111
|
)
|
|
109
112
|
except httpx.TimeoutException as exc:
|
|
110
113
|
if self._should_retry_exception(exc) and attempt < self.max_retries:
|
|
@@ -162,6 +165,10 @@ class BlitzAPI(BaseClient):
|
|
|
162
165
|
def jobs(self) -> JobsResource:
|
|
163
166
|
return JobsResource(self)
|
|
164
167
|
|
|
168
|
+
@cached_property
|
|
169
|
+
def company(self) -> CompanyResource:
|
|
170
|
+
return CompanyResource(self)
|
|
171
|
+
|
|
165
172
|
@cached_property
|
|
166
173
|
def enrichment(self) -> EnrichmentResource:
|
|
167
174
|
return EnrichmentResource(self)
|
|
@@ -169,3 +176,7 @@ class BlitzAPI(BaseClient):
|
|
|
169
176
|
@cached_property
|
|
170
177
|
def utils(self) -> UtilsResource:
|
|
171
178
|
return UtilsResource(self)
|
|
179
|
+
|
|
180
|
+
@cached_property
|
|
181
|
+
def changelog(self) -> ChangelogResource:
|
|
182
|
+
return ChangelogResource(self)
|
|
@@ -8,20 +8,46 @@
|
|
|
8
8
|
├── APIResponseValidationError # a 2xx body was not valid JSON / not the expected shape
|
|
9
9
|
└── APIStatusError # a non-2xx HTTP response was received
|
|
10
10
|
├── AuthenticationError # 401
|
|
11
|
-
├──
|
|
11
|
+
├── InsufficientRecordsError # 402
|
|
12
12
|
├── NotFoundError # 404
|
|
13
13
|
├── RateLimitError # 429 (after retries are exhausted)
|
|
14
14
|
└── ServerError # 5xx (after retries are exhausted)
|
|
15
15
|
|
|
16
16
|
Catch :class:`BlitzError` to handle anything this SDK raises.
|
|
17
|
+
|
|
18
|
+
``InsufficientCreditsError`` remains available as a deprecated alias of
|
|
19
|
+
:class:`InsufficientRecordsError`; it is scheduled for removal in 3.0.0.
|
|
17
20
|
"""
|
|
18
21
|
|
|
19
22
|
from __future__ import annotations
|
|
20
23
|
|
|
21
|
-
from typing import TYPE_CHECKING, Any
|
|
24
|
+
from typing import TYPE_CHECKING, Any, cast
|
|
25
|
+
|
|
26
|
+
from pydantic import ValidationError
|
|
27
|
+
|
|
28
|
+
from .types._models import FairUsage
|
|
22
29
|
|
|
23
30
|
if TYPE_CHECKING:
|
|
24
31
|
import httpx
|
|
32
|
+
from typing_extensions import deprecated
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _parse_fair_usage(body: Any) -> FairUsage | None:
|
|
36
|
+
"""Pull the ``fair_usage`` block out of an error body, if the API sent one.
|
|
37
|
+
|
|
38
|
+
The API attaches it to ``402`` responses, so a caller who runs out of records can
|
|
39
|
+
read ``next_reset_at`` off the exception. Never raises: a malformed block just
|
|
40
|
+
yields ``None`` rather than masking the original API error.
|
|
41
|
+
"""
|
|
42
|
+
if not isinstance(body, dict):
|
|
43
|
+
return None
|
|
44
|
+
raw = cast("dict[str, Any]", body).get("fair_usage")
|
|
45
|
+
if not isinstance(raw, dict):
|
|
46
|
+
return None
|
|
47
|
+
try:
|
|
48
|
+
return FairUsage.model_validate(raw)
|
|
49
|
+
except ValidationError:
|
|
50
|
+
return None
|
|
25
51
|
|
|
26
52
|
|
|
27
53
|
class BlitzError(Exception):
|
|
@@ -75,6 +101,8 @@ class APIStatusError(BlitzError):
|
|
|
75
101
|
body: The parsed JSON body, or the raw text if it was not JSON.
|
|
76
102
|
message: A human-readable message extracted from the body when present.
|
|
77
103
|
request_id: The value of the ``x-request-id`` response header, if any.
|
|
104
|
+
fair_usage: The :class:`~blitz_api.types.FairUsage` block from the body, when
|
|
105
|
+
the API sent one (it does on ``402``); ``None`` otherwise.
|
|
78
106
|
response: The underlying :class:`httpx.Response`.
|
|
79
107
|
"""
|
|
80
108
|
|
|
@@ -91,14 +119,19 @@ class APIStatusError(BlitzError):
|
|
|
91
119
|
self.status_code = response.status_code
|
|
92
120
|
self.body = body
|
|
93
121
|
self.request_id = response.headers.get("x-request-id")
|
|
122
|
+
self.fair_usage = _parse_fair_usage(body)
|
|
94
123
|
|
|
95
124
|
|
|
96
125
|
class AuthenticationError(APIStatusError):
|
|
97
126
|
"""401 — the API key is missing or invalid."""
|
|
98
127
|
|
|
99
128
|
|
|
100
|
-
class
|
|
101
|
-
"""402 — the key is valid but the account is out of
|
|
129
|
+
class InsufficientRecordsError(APIStatusError):
|
|
130
|
+
"""402 — the key is valid but the account is out of records.
|
|
131
|
+
|
|
132
|
+
The API attaches the usage block to this response, so :attr:`~APIStatusError.fair_usage`
|
|
133
|
+
tells you when the balance resets (``fair_usage.next_reset_at``).
|
|
134
|
+
"""
|
|
102
135
|
|
|
103
136
|
|
|
104
137
|
class NotFoundError(APIStatusError):
|
|
@@ -111,3 +144,20 @@ class RateLimitError(APIStatusError):
|
|
|
111
144
|
|
|
112
145
|
class ServerError(APIStatusError):
|
|
113
146
|
"""5xx — the API failed (raised only after retries are exhausted)."""
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
# --- Deprecated aliases ------------------------------------------------------
|
|
150
|
+
|
|
151
|
+
if TYPE_CHECKING:
|
|
152
|
+
|
|
153
|
+
@deprecated(
|
|
154
|
+
"InsufficientCreditsError is renamed to InsufficientRecordsError and will be "
|
|
155
|
+
"removed in 3.0.0."
|
|
156
|
+
)
|
|
157
|
+
class InsufficientCreditsError(InsufficientRecordsError):
|
|
158
|
+
"""Deprecated alias for :class:`InsufficientRecordsError`."""
|
|
159
|
+
|
|
160
|
+
else:
|
|
161
|
+
# A true alias, not a subclass: the client raises ``InsufficientRecordsError``, so a
|
|
162
|
+
# subclass here would stop ``except InsufficientCreditsError`` from catching it.
|
|
163
|
+
InsufficientCreditsError = InsufficientRecordsError
|
|
@@ -54,7 +54,7 @@ class AsyncPaginator(BasePage, Generic[ItemT]):
|
|
|
54
54
|
"""Drain every item across all pages into a list, optionally capped at ``max_items``.
|
|
55
55
|
|
|
56
56
|
Convenience over a manual iteration loop; pair with ``max_items`` so an unbounded result
|
|
57
|
-
set can't exhaust memory — or
|
|
57
|
+
set can't exhaust memory — or records, since the API bills per result returned.
|
|
58
58
|
"""
|
|
59
59
|
items: list[ItemT] = []
|
|
60
60
|
async for item in self._auto_paging_items(max_items):
|
|
@@ -13,11 +13,16 @@ from typing import Any
|
|
|
13
13
|
|
|
14
14
|
from pydantic import PrivateAttr
|
|
15
15
|
|
|
16
|
-
from .types._models import
|
|
16
|
+
from .types._models import BlitzResponse
|
|
17
17
|
|
|
18
18
|
|
|
19
|
-
class BasePage(
|
|
20
|
-
"""Common pagination context. Subclasses add the page fields + iteration.
|
|
19
|
+
class BasePage(BlitzResponse):
|
|
20
|
+
"""Common pagination context. Subclasses add the page fields + iteration.
|
|
21
|
+
|
|
22
|
+
Inherits ``fair_usage`` from :class:`~blitz_api.types._models.BlitzResponse`: each
|
|
23
|
+
page carries the usage block of the request that fetched *it*, so during
|
|
24
|
+
auto-pagination ``page.fair_usage`` reflects that page, not the whole walk.
|
|
25
|
+
"""
|
|
21
26
|
|
|
22
27
|
# Bound by the client after a page is parsed, so the page can fetch the next one.
|
|
23
28
|
_client: Any = PrivateAttr(default=None)
|
|
@@ -56,7 +56,7 @@ class Paginator(BasePage, Generic[ItemT]):
|
|
|
56
56
|
"""Drain every item across all pages into a list, optionally capped at ``max_items``.
|
|
57
57
|
|
|
58
58
|
Convenience over a manual iteration loop; pair with ``max_items`` so an unbounded result
|
|
59
|
-
set can't exhaust memory — or
|
|
59
|
+
set can't exhaust memory — or records, since the API bills per result returned.
|
|
60
60
|
"""
|
|
61
61
|
items: list[ItemT] = []
|
|
62
62
|
for item in self._auto_paging_items(max_items):
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "3.0.0" # x-release-please-version
|
|
@@ -7,11 +7,15 @@ The ``Async*`` classes are hand-written in ``resources/_async``; the sync classe
|
|
|
7
7
|
from __future__ import annotations
|
|
8
8
|
|
|
9
9
|
from ._async.account import AsyncAccountResource
|
|
10
|
+
from ._async.changelog import AsyncChangelogResource
|
|
11
|
+
from ._async.company import AsyncCompanyResource
|
|
10
12
|
from ._async.enrichment import AsyncEnrichmentResource
|
|
11
13
|
from ._async.jobs import AsyncJobsResource
|
|
12
14
|
from ._async.search import AsyncSearchResource
|
|
13
15
|
from ._async.utils import AsyncUtilsResource
|
|
14
16
|
from ._sync.account import AccountResource
|
|
17
|
+
from ._sync.changelog import ChangelogResource
|
|
18
|
+
from ._sync.company import CompanyResource
|
|
15
19
|
from ._sync.enrichment import EnrichmentResource
|
|
16
20
|
from ._sync.jobs import JobsResource
|
|
17
21
|
from ._sync.search import SearchResource
|
|
@@ -24,8 +28,12 @@ __all__ = [
|
|
|
24
28
|
"AsyncSearchResource",
|
|
25
29
|
"JobsResource",
|
|
26
30
|
"AsyncJobsResource",
|
|
31
|
+
"CompanyResource",
|
|
32
|
+
"AsyncCompanyResource",
|
|
27
33
|
"EnrichmentResource",
|
|
28
34
|
"AsyncEnrichmentResource",
|
|
29
35
|
"UtilsResource",
|
|
30
36
|
"AsyncUtilsResource",
|
|
37
|
+
"ChangelogResource",
|
|
38
|
+
"AsyncChangelogResource",
|
|
31
39
|
]
|
|
@@ -18,7 +18,7 @@ class AsyncAccountResource:
|
|
|
18
18
|
self._client = client
|
|
19
19
|
|
|
20
20
|
async def key_info(self, *, timeout: TimeoutParam = None) -> KeyInfo:
|
|
21
|
-
"""Check the API key's validity,
|
|
21
|
+
"""Check the API key's validity, record balance, and rate limit.
|
|
22
22
|
|
|
23
23
|
A cheap health check to run before a batch job.
|
|
24
24
|
"""
|