blitz-api-py 0.2.0__tar.gz → 0.4.0__tar.gz

{blitz_api_py-0.2.0 → blitz_api_py-0.4.0}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.4.0](https://github.com/api-blitz/blitz-api-py/compare/v0.3.0...v0.4.0) (2026-06-17)
+
+
+### Features
+
+* add company department distribution endpoint and response models ([b64a6d9](https://github.com/api-blitz/blitz-api-py/commit/b64a6d9bada069206c77ee11c9f86fae01ef6baa))
+
+
+### Documentation
+
+* port JS SDK README upgrade (badges, billing note, TOC, example) ([#11](https://github.com/api-blitz/blitz-api-py/issues/11)) ([2276513](https://github.com/api-blitz/blitz-api-py/commit/2276513cdae4c23d4a1b50f59366e7156bf81019))
+
+## [0.3.0](https://github.com/api-blitz/blitz-api-py/compare/v0.2.0...v0.3.0) (2026-06-04)
+
+
+### Features
+
+* generate enums from the live OpenAPI spec with offline drift guard ([#9](https://github.com/api-blitz/blitz-api-py/issues/9)) ([fee865c](https://github.com/api-blitz/blitz-api-py/commit/fee865c4d8f7c685330794fa79921dccd7556e37))
+
 ## [0.2.0](https://github.com/api-blitz/blitz-api-py/compare/v0.1.0...v0.2.0) (2026-06-02)
 
 

{blitz_api_py-0.2.0 → blitz_api_py-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blitz-api-py
-Version: 0.2.0
+Version: 0.4.0
 Summary: Typed Python SDK for the Blitz API — B2B data, search, and enrichment.
 Project-URL: Homepage, https://blitz-api.ai
 Project-URL: Documentation, https://docs.blitz-api.ai
@@ -31,6 +31,11 @@ Description-Content-Type: text/markdown
 
 # blitz-api-py
 
+[![PyPI version](https://img.shields.io/pypi/v/blitz-api-py.svg)](https://pypi.org/project/blitz-api-py/)
+[![types: py.typed](https://img.shields.io/badge/types-py.typed-blue.svg)](https://pypi.org/project/blitz-api-py/)
+[![CI](https://github.com/api-blitz/blitz-api-py/actions/workflows/ci.yml/badge.svg)](https://github.com/api-blitz/blitz-api-py/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/pypi/l/blitz-api-py.svg)](./LICENSE)
+
 The typed Python SDK for the [Blitz API](https://blitz-api.ai) — B2B data, search,
 and enrichment.
 
@@ -41,14 +46,35 @@ and enrichment.
 - **Resilient** — built-in client-side rate limiting, retries with backoff on
   `429`/`5xx`, and a typed exception hierarchy.
 - **Forward-compatible** — new fields the API adds never break deserialization.
+- **1:1 with the API** — request filters and response fields are snake_case,
+  matching [docs.blitz-api.ai](https://docs.blitz-api.ai).
 
 > Create and manage API keys at [app.blitz-api.ai](https://app.blitz-api.ai).
 
+> **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
+> loop streams every match up to the server-side limit (people: 50k results), which can be
+> a lot of credits. Bound spend with **`max_items`** (a client-side total cap on
+> `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
+> [Pagination](#pagination).
+
+## Contents
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Example: find, enrich, collect](#example-find-enrich-collect)
+- [Authentication](#authentication)
+- [Endpoints](#endpoints)
+- [Pagination](#pagination)
+- [Configuration](#configuration)
+- [Error handling](#error-handling)
+- [Forward compatibility](#forward-compatibility)
+- [Development](#development)
+
 ## Installation
 
 ```bash
 pip install blitz-api-py
-# or: uv add blitz-api-py
+# or: poetry add blitz-api-py   /   uv add blitz-api-py
 ```
 
 Requires Python 3.10+.
@@ -98,6 +124,61 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Example: find, enrich, collect
+
+A complete flow — find people, enrich each one's verified work email, collect the
+contacts. `max_items` caps the total fetched so the run can't surprise you with credits.
+
+```python
+from blitz_api import BlitzAPI
+from blitz_api.types import Industry, JobLevel
+
+client = BlitzAPI()  # reads BLITZ_API_KEY
+
+# 1. Find up to 25 VPs at software companies (typed filters, 1:1 with the API).
+leads = client.search.people(
+    company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
+    people={"job_level": [JobLevel.VP]},
+    max_results=25,
+).collect(max_items=25)  # client-side total cap — bounds credit spend
+
+# 2. Enrich each lead's verified work email from their LinkedIn profile URL.
+contacts: list[dict[str, str | None]] = []
+for person in leads:
+    if not person.linkedin_url:
+        continue
+    result = client.enrichment.email(person_linkedin_url=person.linkedin_url)
+    if result.found:
+        contacts.append({"name": person.full_name, "email": result.email})
+
+print(f"Collected {len(contacts)} contacts")
+```
+
+What comes back is typed and snake_case. A `Person` from the search above (fields are a
+**superset** — only what the profile has is populated, and unknown fields the API adds
+later are preserved):
+
+```python
+Person(
+    full_name="Jordan Lee",
+    headline="VP of Engineering at Acme",
+    linkedin_url="https://www.linkedin.com/in/example-person",
+    location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
+    experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
+    # first_name, last_name, skills, education, certifications, … also present
+)
+```
+
+And `enrichment.email(...)` returns:
+
+```python
+EmailEnrichmentResponse(
+    found=True,
+    email="jordan@acme.com",
+    all_emails=[EmailMatch(email="jordan@acme.com", email_domain="acme.com")],
+)
+```
+
 ## Authentication
 
 Pass the key explicitly or via the `BLITZ_API_KEY` environment variable:
@@ -119,7 +200,7 @@ All methods are grouped into four namespaces:
 | `client.account` | `key_info()` |
 | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
 | `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()` |
-| `client.utils` | `current_date()`, `company_employment_distribution()` |
+| `client.utils` | `current_date()`, `company_employment_distribution()`, `company_department_distribution()` |
 
 Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
 filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
@@ -131,6 +212,13 @@ The search methods return an **auto-paginating page**: iterate it and the SDK fe
 each subsequent page for you. `search.people`/`search.companies` are cursor-based;
 `search.employee_finder` is page-based — both behave identically here.
 
+> **`max_results` is the page size, not a total.** It's results per page, and the API
+> **bills 1 credit per result returned**. A bare `for person in client.search.people(...)`
+> loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
+> employee finder: 10k), which can be a lot of credits. Bound it with **`max_items`** on
+> `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
+> `break` out of the loop, or drive pages manually.
+
 ```python
 # Iterate every matching person across all pages — no cursor handling needed.
 for person in client.search.people(people={"job_level": ["VP"]}):
@@ -210,6 +298,12 @@ except BlitzError:
 but a **read timeout is not** — the server may already have processed (and billed) the
 request, so it surfaces as `APITimeoutError` rather than risking a double charge.
 
+## Forward compatibility
+
+Response models subclass a base configured with `extra="allow"`, so a field the API adds
+before this SDK models it is still present on the parsed object (via attribute access or
+`.model_extra`). Known fields stay precisely typed.
+
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, the test/type/lint

{blitz_api_py-0.2.0 → blitz_api_py-0.4.0}/README.md

@@ -1,5 +1,10 @@
 # blitz-api-py
 
+[![PyPI version](https://img.shields.io/pypi/v/blitz-api-py.svg)](https://pypi.org/project/blitz-api-py/)
+[![types: py.typed](https://img.shields.io/badge/types-py.typed-blue.svg)](https://pypi.org/project/blitz-api-py/)
+[![CI](https://github.com/api-blitz/blitz-api-py/actions/workflows/ci.yml/badge.svg)](https://github.com/api-blitz/blitz-api-py/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/pypi/l/blitz-api-py.svg)](./LICENSE)
+
 The typed Python SDK for the [Blitz API](https://blitz-api.ai) — B2B data, search,
 and enrichment.
 
@@ -10,14 +15,35 @@ and enrichment.
 - **Resilient** — built-in client-side rate limiting, retries with backoff on
   `429`/`5xx`, and a typed exception hierarchy.
 - **Forward-compatible** — new fields the API adds never break deserialization.
+- **1:1 with the API** — request filters and response fields are snake_case,
+  matching [docs.blitz-api.ai](https://docs.blitz-api.ai).
 
 > Create and manage API keys at [app.blitz-api.ai](https://app.blitz-api.ai).
 
+> **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
+> loop streams every match up to the server-side limit (people: 50k results), which can be
+> a lot of credits. Bound spend with **`max_items`** (a client-side total cap on
+> `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
+> [Pagination](#pagination).
+
+## Contents
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Example: find, enrich, collect](#example-find-enrich-collect)
+- [Authentication](#authentication)
+- [Endpoints](#endpoints)
+- [Pagination](#pagination)
+- [Configuration](#configuration)
+- [Error handling](#error-handling)
+- [Forward compatibility](#forward-compatibility)
+- [Development](#development)
+
 ## Installation
 
 ```bash
 pip install blitz-api-py
-# or: uv add blitz-api-py
+# or: poetry add blitz-api-py   /   uv add blitz-api-py
 ```
 
 Requires Python 3.10+.
@@ -67,6 +93,61 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Example: find, enrich, collect
+
+A complete flow — find people, enrich each one's verified work email, collect the
+contacts. `max_items` caps the total fetched so the run can't surprise you with credits.
+
+```python
+from blitz_api import BlitzAPI
+from blitz_api.types import Industry, JobLevel
+
+client = BlitzAPI()  # reads BLITZ_API_KEY
+
+# 1. Find up to 25 VPs at software companies (typed filters, 1:1 with the API).
+leads = client.search.people(
+    company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
+    people={"job_level": [JobLevel.VP]},
+    max_results=25,
+).collect(max_items=25)  # client-side total cap — bounds credit spend
+
+# 2. Enrich each lead's verified work email from their LinkedIn profile URL.
+contacts: list[dict[str, str | None]] = []
+for person in leads:
+    if not person.linkedin_url:
+        continue
+    result = client.enrichment.email(person_linkedin_url=person.linkedin_url)
+    if result.found:
+        contacts.append({"name": person.full_name, "email": result.email})
+
+print(f"Collected {len(contacts)} contacts")
+```
+
+What comes back is typed and snake_case. A `Person` from the search above (fields are a
+**superset** — only what the profile has is populated, and unknown fields the API adds
+later are preserved):
+
+```python
+Person(
+    full_name="Jordan Lee",
+    headline="VP of Engineering at Acme",
+    linkedin_url="https://www.linkedin.com/in/example-person",
+    location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
+    experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
+    # first_name, last_name, skills, education, certifications, … also present
+)
+```
+
+And `enrichment.email(...)` returns:
+
+```python
+EmailEnrichmentResponse(
+    found=True,
+    email="jordan@acme.com",
+    all_emails=[EmailMatch(email="jordan@acme.com", email_domain="acme.com")],
+)
+```
+
 ## Authentication
 
 Pass the key explicitly or via the `BLITZ_API_KEY` environment variable:
@@ -88,7 +169,7 @@ All methods are grouped into four namespaces:
 | `client.account` | `key_info()` |
 | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
 | `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()` |
-| `client.utils` | `current_date()`, `company_employment_distribution()` |
+| `client.utils` | `current_date()`, `company_employment_distribution()`, `company_department_distribution()` |
 
 Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
 filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
@@ -100,6 +181,13 @@ The search methods return an **auto-paginating page**: iterate it and the SDK fe
 each subsequent page for you. `search.people`/`search.companies` are cursor-based;
 `search.employee_finder` is page-based — both behave identically here.
 
+> **`max_results` is the page size, not a total.** It's results per page, and the API
+> **bills 1 credit per result returned**. A bare `for person in client.search.people(...)`
+> loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
+> employee finder: 10k), which can be a lot of credits. Bound it with **`max_items`** on
+> `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
+> `break` out of the loop, or drive pages manually.
+
 ```python
 # Iterate every matching person across all pages — no cursor handling needed.
 for person in client.search.people(people={"job_level": ["VP"]}):
@@ -179,6 +267,12 @@ except BlitzError:
 but a **read timeout is not** — the server may already have processed (and billed) the
 request, so it surfaces as `APITimeoutError` rather than risking a double charge.
 
+## Forward compatibility
+
+Response models subclass a base configured with `extra="allow"`, so a field the API adds
+before this SDK models it is still present on the parsed object (via attribute access or
+`.model_extra`). Known fields stay precisely typed.
+
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, the test/type/lint

blitz_api_py-0.4.0/src/blitz_api/_version.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"  # x-release-please-version

{blitz_api_py-0.2.0 → blitz_api_py-0.4.0}/src/blitz_api/resources/_async/utils.py

@@ -5,13 +5,18 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from ..._compat import TimeoutParam
-from ...types.utils import CompanyEmploymentDistributionResponse, CurrentDateResponse
+from ...types.utils import (
+    CompanyDepartmentDistributionResponse,
+    CompanyEmploymentDistributionResponse,
+    CurrentDateResponse,
+)
 
 if TYPE_CHECKING:
     from ..._client import AsyncBlitzAPI
 
 _CURRENT_DATE = "/v2/utils/current-date"
 _EMPLOYMENT_DISTRIBUTION = "/v2/utils/company-employment-distribution"
+_DEPARTMENT_DISTRIBUTION = "/v2/utils/company-department-distribution"
 
 
 class AsyncUtilsResource:
@@ -41,3 +46,18 @@ class AsyncUtilsResource:
             cast_to=CompanyEmploymentDistributionResponse,
             timeout=timeout,
         )
+
+    async def company_department_distribution(
+        self, *, company_linkedin_url: str, timeout: TimeoutParam = None
+    ) -> CompanyDepartmentDistributionResponse:
+        """Get a company's employee count broken down by department.
+
+        Employees with no classified department are counted under ``"Other"``.
+        """
+        return await self._client._request(
+            "POST",
+            _DEPARTMENT_DISTRIBUTION,
+            body={"company_linkedin_url": company_linkedin_url},
+            cast_to=CompanyDepartmentDistributionResponse,
+            timeout=timeout,
+        )

{blitz_api_py-0.2.0 → blitz_api_py-0.4.0}/src/blitz_api/resources/_sync/utils.py

@@ -7,13 +7,18 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from ..._compat import TimeoutParam
-from ...types.utils import CompanyEmploymentDistributionResponse, CurrentDateResponse
+from ...types.utils import (
+    CompanyDepartmentDistributionResponse,
+    CompanyEmploymentDistributionResponse,
+    CurrentDateResponse,
+)
 
 if TYPE_CHECKING:
     from ..._client import BlitzAPI
 
 _CURRENT_DATE = "/v2/utils/current-date"
 _EMPLOYMENT_DISTRIBUTION = "/v2/utils/company-employment-distribution"
+_DEPARTMENT_DISTRIBUTION = "/v2/utils/company-department-distribution"
 
 
 class UtilsResource:
@@ -43,3 +48,18 @@ class UtilsResource:
             cast_to=CompanyEmploymentDistributionResponse,
             timeout=timeout,
         )
+
+    def company_department_distribution(
+        self, *, company_linkedin_url: str, timeout: TimeoutParam = None
+    ) -> CompanyDepartmentDistributionResponse:
+        """Get a company's employee count broken down by department.
+
+        Employees with no classified department are counted under ``"Other"``.
+        """
+        return self._client._request(
+            "POST",
+            _DEPARTMENT_DISTRIBUTION,
+            body={"company_linkedin_url": company_linkedin_url},
+            cast_to=CompanyDepartmentDistributionResponse,
+            timeout=timeout,
+        )

{blitz_api_py-0.2.0 → blitz_api_py-0.4.0}/src/blitz_api/types/__init__.py

@@ -53,8 +53,10 @@ from .shared import (
     Person,
 )
 from .utils import (
+    CompanyDepartmentDistributionResponse,
     CompanyEmploymentDistributionResponse,
     CurrentDateResponse,
+    DepartmentDistributionItem,
     EmploymentDistributionItem,
 )
 
@@ -105,4 +107,6 @@ __all__ = [
     "CurrentDateResponse",
     "EmploymentDistributionItem",
     "CompanyEmploymentDistributionResponse",
+    "DepartmentDistributionItem",
+    "CompanyDepartmentDistributionResponse",
 ]

{blitz_api_py-0.2.0 → blitz_api_py-0.4.0}/src/blitz_api/types/utils.py

@@ -8,6 +8,8 @@ __all__ = [
     "CurrentDateResponse",
     "EmploymentDistributionItem",
     "CompanyEmploymentDistributionResponse",
+    "DepartmentDistributionItem",
+    "CompanyDepartmentDistributionResponse",
 ]
 
 
@@ -33,3 +35,21 @@ class CompanyEmploymentDistributionResponse(BlitzModel):
     company_linkedin_url: str | None = None
     total_employees: int | None = None
     distribution: list[EmploymentDistributionItem] = []
+
+
+class DepartmentDistributionItem(BlitzModel):
+    """Employee count for a single department (Blitz job function).
+
+    Employees with no classified department are counted under ``"Other"``.
+    """
+
+    department: str | None = None
+    count: int | None = None
+
+
+class CompanyDepartmentDistributionResponse(BlitzModel):
+    """Result of ``utils.company_department_distribution``."""
+
+    company_linkedin_url: str | None = None
+    total_employees: int | None = None
+    distribution: list[DepartmentDistributionItem] = []

blitz_api_py-0.2.0/src/blitz_api/_version.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"  # x-release-please-version