bls-api-client 1.0.0__py3-none-any.whl

bls_api_client-1.0.0.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: bls-api-client
+Version: 1.0.0
+Summary: A sync + async client for the BLS Public Data API
+Project-URL: Homepage, https://github.com/covertcast/blsapi
+Project-URL: Repository, https://github.com/covertcast/blsapi
+Project-URL: Issues, https://github.com/covertcast/blsapi/issues
+Author-email: covertcast <covertcast@proton.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,bls,bureau-of-labor-statistics,economics,labor-statistics,polars
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx2>=2.4.0
+Requires-Dist: polars>=1.42.0
+Requires-Dist: pydantic>=2.13.4
+Description-Content-Type: text/markdown
+
+# blsapi
+
+[![PyPI version](https://img.shields.io/pypi/v/blsapi.svg)](https://pypi.org/project/blsapi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/blsapi.svg)](https://pypi.org/project/blsapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A **sync + async** client inspired by `blsR` for the [U.S. Bureau of Labor Statistics
+(BLS) Public Data API](https://www.bls.gov/developers/).
+
+- **Sync and async** clients (`BLSClient`, `AsyncBLSClient`).
+- **Polars output** returns easy to use and convert Polars Dataframes.
+- **Automatic batching** over the BLS per-request limits (series count and year span).
+
+## Installation
+
+Requires Python 3.11+:
+```bash
+pip install bls-api-client
+# or
+uv add bls-api-client
+```
+
+```python
+import blsapi
+```
+
+## Quick start
+
+```python
+from blsapi import BLSClient
+
+with BLSClient() as client:
+    df = client.get_series("LNS14000000", start_year=2023, end_year=2024)
+
+print(df)
+```
+
+The result is a tidy/long DataFrame. Exporting elsewhere is
+simple:
+
+```python
+df.write_parquet("data.parquet")
+df.write_csv("data.csv")
+df.to_pandas()
+df.to_arrow()
+```
+
+### Async
+
+```python
+import anyio
+from blsapi import AsyncBLSClient
+
+async def main():
+    async with AsyncBLSClient() as client:
+        df = await client.get_series("LNS14000000", start_year=2023, end_year=2024)
+        print(df)
+
+anyio.run(main)
+```
+
+## Configuration
+
+Everything has a sensible default, so `blsapi` works out of the box.
+
+### API key
+
+A registration key is optional but raises your rate limits substantially. The key is resolved with this precedence:
+
+1. The explicit `api_key=` argument, if given.
+2. Otherwise the `BLS_API_KEY` environment variable.
+3. Otherwise no key (unauthenticated tier).
+
+### Example:
+```python
+# Explicit (highest precedence)
+client = BLSClient(api_key="your_32_char_key")
+
+# Or rely on the environment
+#   export BLS_API_KEY=your_32_char_key   (macOS/Linux)
+#   $env:BLS_API_KEY = "your_32_char_key" (PowerShell)
+client = BLSClient()
+
+client.has_key  # returns True if a key is active
+```
+
+### Other options
+
+All are keyword-only on both clients:
+
+| Argument      | Default                          | Purpose                                                        |
+| ------------- | -------------------------------- | -------------------------------------------------------------- |
+| `api_key`     | `None` -> `BLS_API_KEY`           | Registration key.                                              |
+| `base_url`    | `https://api.bls.gov/publicAPI/v2/` | API base URL.               |
+| `timeout`     | `5/30/10/5s` (connect/read/write/pool) | `httpx2.Timeout`.                            |
+| `max_retries` | `3`                              | Application-level retries for transient failures.              |
+| `auto_batch`  | `True`                           | Transparently split over the tier limits.                      |
+| `user_agent`  | `blsapi/<version>`               | Sent as `User-Agent`.     |
+| `client`      | `None`                           | Inject your own `httpx2.Client`/`AsyncClient`.|
+
+```python
+import httpx2
+from blsapi import BLSClient
+
+client = BLSClient(
+    api_key="…",
+    max_retries=5,
+    timeout=httpx2.Timeout(connect=5.0, read=60.0, write=10.0, pool=5.0),
+    user_agent="my-app/1.0 (you@example.com)",
+)
+```
+
+## Usage
+
+### Multiple series and named aliases
+
+Pass a list of ids, or a `{label: id}` mapping to relabel the output's `series_id` column:
+
+```python
+df = client.get_series(
+    {"unemployment": "LNS14000000", "cpi": "CUUR0000SA0"},
+    start_year=2020,
+    end_year=2024,
+)
+df["series_id"].unique().to_list()  # -> ["cpi", "unemployment"]
+```
+
+### Wide format
+
+Reshape the long frame to one value column per series, indexed by date:
+
+```python
+from blsapi import pivot_wide
+
+wide = pivot_wide(df)  # columns: date, unemployment, cpi
+```
+
+(Annual-average rows have no real date and are dropped by `pivot_wide`.)
+
+### Calculations and catalog
+
+```python
+df = client.get_series(
+    "LNS14000000", start_year=2023, end_year=2024, calculations=True
+)
+# adds net_change_{1,3,6,12}m and pct_change_{1,3,6,12}m columns
+
+resp = client.get_series_raw("LNS14000000", catalog=True)  # -> BLSResponse with catalog metadata
+```
+
+### Surveys and popular series
+
+```python
+client.list_surveys()        # -> DataFrame of all surveys
+client.get_survey("CU")      # -> dict of metadata for one survey
+client.get_popular()         # -> list of popular series ids
+client.get_popular("LN")     # -> popular ids within a survey
+```
+
+### Quota planning
+
+```python
+client.query_cost(["LNS14000000", "CUUR0000SA0"], 2000, 2024)  # -> number of API calls used
+```
+
+## Error handling
+
+All errors derive from `BLSError`, so you can catch broadly or narrowly:
+
+```python
+from blsapi import BLSError, BLSValidationError, BLSAPIError, BLSHTTPError
+
+try:
+    df = client.get_series("BAD_ID", start_year=2024, end_year=2023)
+except BLSValidationError:
+    ...  # bad input caught locally, before any network call
+except BLSAPIError as e:
+    ...  # BLS returned a non-success status; inspect e.status and e.messages
+except BLSHTTPError:
+    ...  # transport/HTTP failure that survived the retry loop
+except BLSError:
+    ...  # anything else from this library
+```
+
+## Tiers & limits
+
+| | Series per request | Years per request | Queries per day |
+| --- | --- | --- | --- |
+| **No key** | 25 | 10 | 25 |
+| **With key** | 50 | 20 | 500 |
+
+With `auto_batch=True` (the default), requests that exceed the per-request limits are split
+into multiple calls automatically and stitched back together. Register for a free key at
+<https://data.bls.gov/registrationEngine/>.
+
+## Development
+
+```bash
+uv sync          # install dependencies
+uv build         # build the sdist + wheel
+```
+
+## License
+
+[MIT](LICENSE)

bls_api_client-1.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+blsapi/__about__.py,sha256=l3nlRfP79jMcuBVWEOoKZ-BJRYGwRf6DSq2yGyTyekQ,73
+blsapi/__init__.py,sha256=zoWbHEj9fwLjIZUBKdn0UYpfcEsP-6gVCBWYSmAzYgA,1195
+blsapi/_core.py,sha256=2aiYuNNo1sX2HIAtL5iQ77_HRIkGn6cWce5ke_Mys7E,2203
+blsapi/_endpoints.py,sha256=Fi32WkLP_jCb4vNiV5JQKaver-Q5-0bCD5pvQMC1C1Q,803
+blsapi/_retry.py,sha256=9siSaL7mBowEUojUxKTSqrJPrlMRI5qIVGh6c7i894U,1289
+blsapi/aclient.py,sha256=ZCXMKwIv0ST7uUmm_Jvz9ZO-KCnF-zzzl1vIlwNaz9Q,6377
+blsapi/batching.py,sha256=_NLObbwvssEq4u4crjY7f3AxsdMsaGiAGNFgbrIEJBE,1904
+blsapi/client.py,sha256=8FYslVbGjygFIYdTtA676z881-DLRDCCWaFG6yJDfho,6609
+blsapi/config.py,sha256=BORa_W78VlaW83P6-M2-uVs_kCLdYY4_2cgLW9FZuJo,1741
+blsapi/enums.py,sha256=2y6zeHl_ldUAF7r2sNyLBo0NutjLRaQ0fEM74zBfqs4,671
+blsapi/exceptions.py,sha256=kCeZ1I9N99_QVXu2mmvWOpP_Q3Fw0Fm05wyC2PKNbXM,775
+blsapi/frames.py,sha256=U4q5dXEh5ej7vVBMRgc7HWPNoSV-zm2jIlbc7gviH8o,5074
+blsapi/models.py,sha256=vHQy9RcOYBGWG3YGtlk554n6-aR5q_joxegzlRpmG2Y,4774
+blsapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bls_api_client-1.0.0.dist-info/METADATA,sha256=vWC6jXGBn0xrx7Dv7V9IRZqeeZ3Hansd4WiOynMJs7I,7135
+bls_api_client-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+bls_api_client-1.0.0.dist-info/licenses/LICENSE,sha256=7Ml9vqERSFrXdwfgQj99rsL8Nwz9jskhV3xiiCrBSB8,1067
+bls_api_client-1.0.0.dist-info/RECORD,,

bls_api_client-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

bls_api_client-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 covertcast
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blsapi/__about__.py

@@ -0,0 +1,3 @@
+"""Package version for the client's useragent."""
+
+__version__ = "1.0.0"

blsapi/__init__.py

@@ -0,0 +1,44 @@
+"""blsapi - a sync + async client for the BLS Public Data API.
+
+Quick start:
+
+    from blsapi import BLSClient
+    with BLSClient() as client:                      # reads BLS_API_KEY from env if set
+        df = client.get_series("LNS14000000", start_year=2023, end_year=2024)
+
+    # async
+    from blsapi import AsyncBLSClient
+    async with AsyncBLSClient() as client:
+        df = await client.get_series("LNS14000000", start_year=2023, end_year=2024)
+
+The result is a Polars DataFrame. Exporting it to other formats is simple:
+    df.write_parquet(...), df.write_csv(...), df.to_pandas(), df.to_arrow()
+"""
+
+from .__about__ import __version__
+from .aclient import AsyncBLSClient
+from .client import BLSClient
+from .enums import PeriodType
+from .exceptions import (
+    BLSAPIError,
+    BLSError,
+    BLSHTTPError,
+    BLSValidationError,
+)
+from .frames import period_to_date, pivot_wide, series_to_frame
+from .models import BLSResponse
+
+__all__ = [
+    "AsyncBLSClient",
+    "BLSClient",
+    "BLSError",
+    "BLSValidationError",
+    "BLSAPIError",
+    "BLSHTTPError",
+    "BLSResponse",
+    "PeriodType",
+    "series_to_frame",
+    "pivot_wide",
+    "period_to_date",
+    "__version__",
+]

blsapi/_core.py

@@ -0,0 +1,58 @@
+"""Utilities for both the sync and async clients."""
+
+from .models import BLSResponse, SeriesRequest, SeriesResult
+from ._endpoints import RequestSpec, data_url
+from collections.abc import Iterable
+from . import config
+from .batching import chunk_series, year_windows
+
+
+def build_data_request(req: SeriesRequest, api_key: str | None, base_url: str) -> RequestSpec:
+    """Turn a validated SeriesRequest into a RequestSpec."""
+    return RequestSpec(
+        method="POST",
+        url=data_url(base_url),
+        json=req.to_payload(api_key),
+    )
+
+
+def parse_data_response(payload: dict) -> BLSResponse:
+    """Validate the payload. Raises typed errors on failure."""
+    return BLSResponse.model_validate(payload)
+
+
+def plan_data_requests(
+    req: SeriesRequest, api_key: str | None, base_url: str, auto_batch: bool
+) -> list[RequestSpec]:
+    """One RequestSpec per API call, splitting over the tier limits when auto_batch is enabled."""
+    if not auto_batch:
+        return [build_data_request(req, api_key, base_url)]
+
+    series_limit, year_limit, _ = config.limits_for(api_key)
+    if req.start_year is not None and req.end_year is not None:
+        windows = list(year_windows(req.start_year, req.end_year, year_limit))
+    else:
+        windows = [(req.start_year, req.end_year)]  # no year filter produces a single window
+
+    # every combination of series-chunk and year-window is one request.
+    return [
+        build_data_request(
+            req.model_copy(update={"series_ids": ids, "start_year": lo, "end_year": hi}),
+            api_key,
+            base_url,
+        )
+        for ids in chunk_series(req.series_ids, series_limit)
+        for lo, hi in windows
+    ]
+
+
+def merge_series(series_lists: Iterable[list[SeriesResult]]) -> list[SeriesResult]:
+    """Combine SeriesResults from several responses, concatenating .data by series_id."""
+    merged: dict[str, SeriesResult] = {}
+    for series in series_lists:
+        for s in series:
+            if s.series_id in merged:
+                merged[s.series_id].data.extend(s.data)  # same series, another year-window
+            else:
+                merged[s.series_id] = s  # first sighting
+    return list(merged.values())

blsapi/_endpoints.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class RequestSpec:
+    """Everything _send() needs to make a request"""
+
+    method: str
+    url: str
+    json: dict[str, Any] | None = None
+    params: dict[str, Any] | None = None
+
+
+# All builders take the client's base_url so the same code works against v1 or v2.
+
+
+def data_url(base_url: str) -> str:
+    return f"{base_url}timeseries/data/"
+
+
+def series_url(base_url: str, series_id: str) -> str:
+    return f"{base_url}timeseries/data/{series_id}"
+
+
+def popular_url(base_url: str) -> str:
+    return f"{base_url}timeseries/popular"
+
+
+def surveys_url(base_url: str, survey_abbr: str | None = None) -> str:
+    if survey_abbr is None:
+        return f"{base_url}surveys"
+    return f"{base_url}surveys/{survey_abbr}"

blsapi/_retry.py

@@ -0,0 +1,46 @@
+import random
+
+import httpx2
+
+from .config import BACKOFF_BASE, BACKOFF_MAX, RETRYABLE_STATUS
+
+
+_RETRYABLE_TRANSPORT_ERRORS: tuple[type[Exception], ...] = (
+    httpx2.ConnectError,
+    httpx2.ConnectTimeout,
+    httpx2.ReadTimeout,
+    httpx2.WriteTimeout,
+    httpx2.PoolTimeout,
+    httpx2.RemoteProtocolError,
+)
+
+
+def is_retryable(exc: Exception) -> bool:
+    """True if the client should wait and try again for this error."""
+    if isinstance(exc, _RETRYABLE_TRANSPORT_ERRORS):
+        return True
+    if isinstance(exc, httpx2.HTTPStatusError):
+        return exc.response.status_code in RETRYABLE_STATUS
+    return False
+
+
+def retry_after(exc: Exception) -> float | None:
+    """Honor a server-sent `Retry-After` header if present.
+    Returns None when there's no usable header, so the caller falls back to backoff.
+    """
+    response = getattr(exc, "response", None)
+    if response is None:
+        return None
+    value = response.headers.get("Retry-After")
+    if not value:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def backoff_delay(attempt: int) -> float:
+    """Exponential backoff, capped at BACKOFF_MAX.."""
+    ceiling = min(BACKOFF_MAX, BACKOFF_BASE * (2**attempt))
+    return random.uniform(0.0, ceiling)

blsapi/aclient.py

@@ -0,0 +1,165 @@
+"""Asynchronous BLS client."""
+
+from collections.abc import Mapping, Sequence
+
+import anyio
+import httpx2
+import polars as pl
+
+from . import batching, config
+from ._core import (
+    build_data_request,
+    merge_series,
+    parse_data_response,
+    plan_data_requests,
+)
+from ._endpoints import RequestSpec, popular_url, surveys_url
+from ._retry import backoff_delay, is_retryable, retry_after
+from .exceptions import BLSHTTPError
+from .frames import series_to_frame
+from .models import BLSResponse, SeriesRequest, normalize_series_ids
+
+
+class AsyncBLSClient:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = config.DEFAULT_BASE_URL,
+        timeout: float | httpx2.Timeout = config.DEFAULT_TIMEOUT,
+        max_retries: int = config.DEFAULT_MAX_RETRIES,
+        auto_batch: bool = True,
+        user_agent: str = config.DEFAULT_USER_AGENT,
+        client: httpx2.AsyncClient | None = None,
+    ) -> None:
+        self._api_key = config.resolve_api_key(api_key)
+        self._base_url = base_url
+        self._max_retries = max_retries
+        self._auto_batch = auto_batch
+
+        if client is not None:
+            self._http = client
+            self._owns_client = False
+        else:
+            transport = httpx2.AsyncHTTPTransport(retries=2)
+            self._http = httpx2.AsyncClient(
+                timeout=timeout, transport=transport, headers={"User-Agent": user_agent}
+            )
+            self._owns_client = True
+
+    @property
+    def has_key(self) -> bool:
+        return self._api_key is not None
+
+    async def _send(self, spec: RequestSpec) -> dict:
+        """Async implementation of BLSClient._send."""
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._http.request(
+                    spec.method, spec.url, json=spec.json, params=spec.params
+                )
+                response.raise_for_status()
+                return response.json()
+            except (httpx2.RequestError, httpx2.HTTPStatusError) as exc:
+                last_exc = exc
+                if attempt == self._max_retries or not is_retryable(exc):
+                    raise BLSHTTPError(str(exc)) from exc
+                await anyio.sleep(retry_after(exc) or backoff_delay(attempt))
+            except ValueError as exc:
+                raise BLSHTTPError(f"BLS returned a non-JSON response: {exc}") from exc
+        raise BLSHTTPError(str(last_exc)) from last_exc
+
+    async def get_series(
+        self,
+        series_ids: str | Sequence[str] | Mapping[str, str],
+        *,
+        start_year: int | None = None,
+        end_year: int | None = None,
+        catalog: bool = False,
+        calculations: bool = False,
+        annual_average: bool = False,
+        aspects: bool = False,
+        latest: bool = False,
+        parse_values: bool = True,
+    ) -> pl.DataFrame:
+        """Fetch one or more series as a tidy Polars DataFrame."""
+        bls_ids, aliases = normalize_series_ids(series_ids)
+        req = SeriesRequest(
+            series_ids=bls_ids,
+            start_year=start_year,
+            end_year=end_year,
+            catalog=catalog,
+            calculations=calculations,
+            annual_average=annual_average,
+            aspects=aspects,
+            latest=latest,
+        )
+        specs = plan_data_requests(req, self._api_key, self._base_url, self._auto_batch)
+        series = merge_series(
+            [parse_data_response(await self._send(spec)).series for spec in specs]
+        )
+        return series_to_frame(series, parse_values=parse_values, aliases=aliases)
+
+    async def get_series_raw(
+        self,
+        series_ids: str | Sequence[str] | Mapping[str, str],
+        **flags: object,
+    ) -> BLSResponse:
+        """Same inputs as get_series, but returns the validated BLSResponse (no frame)."""
+        bls_ids, _ = normalize_series_ids(series_ids)
+        req = SeriesRequest(series_ids=bls_ids, **flags)
+        spec = build_data_request(req, self._api_key, self._base_url)
+        return parse_data_response(await self._send(spec))
+
+    async def get_latest(self, series_id: str, **flags: object) -> pl.DataFrame:
+        """Most-recent data point for a single series."""
+        return await self.get_series(series_id, latest=True, **flags)
+
+    async def list_surveys(self) -> pl.DataFrame:
+        """All BLS surveys as a small DataFrame."""
+        params = {"registrationkey": self._api_key} if self._api_key else None
+        spec = RequestSpec("GET", surveys_url(self._base_url), params=params)
+        payload = await self._send(spec)
+        return pl.DataFrame(payload["Results"]["survey"])
+
+    async def get_survey(self, survey_abbr: str) -> dict:
+        """Metadata for a single survey."""
+        params = {"registrationkey": self._api_key} if self._api_key else None
+        spec = RequestSpec("GET", surveys_url(self._base_url, survey_abbr), params=params)
+        payload = await self._send(spec)
+        return payload["Results"]
+
+    async def get_popular(self, survey: str | None = None) -> list[str]:
+        """The most popular series ids, optionally scoped to one survey."""
+        params: dict[str, str] = {}
+        if survey is not None:
+            params["survey"] = survey
+        if self._api_key:
+            params["registrationkey"] = self._api_key
+        spec = RequestSpec("GET", popular_url(self._base_url), params=params or None)
+        payload = await self._send(spec)
+        return [s["seriesID"] for s in payload["Results"]["series"]]
+
+    def query_cost(
+        self,
+        series_ids: str | Sequence[str] | Mapping[str, str],
+        start_year: int | None = None,
+        end_year: int | None = None,
+    ) -> int:
+        """Calculates how many API calls get_series() would consume."""
+        bls_ids, _ = normalize_series_ids(series_ids)
+        series_limit, year_limit, _ = config.limits_for(self._api_key)
+        return batching.estimate_query_count(
+            len(bls_ids), start_year, end_year, series_limit, year_limit
+        )
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncBLSClient":
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()

blsapi/batching.py

@@ -0,0 +1,59 @@
+"""Batching helpers to help work around BLS per-request limits.
+
+BLS caps each request at N series and an M-year span (25/10 without a key, 50/20 with).
+To fetch more, the client splits into chunks, issues several requests, and stitches the
+results back together.
+"""
+
+import math
+from collections.abc import Iterator, Sequence
+
+
+def chunk_series(ids: Sequence[str], size: int) -> Iterator[list[str]]:
+    """Yield successive `size`-length chunks of series ids.
+
+    list(chunk_series(["a", "b", "c"], 2))
+    [['a', 'b'], ['c']]
+    """
+    if size < 1:
+        raise ValueError("size must be >= 1")
+    for start in range(0, len(ids), size):
+        yield list(ids[start : start + size])
+
+
+def year_windows(start: int, end: int, span: int) -> Iterator[tuple[int, int]]:
+    """Yield inclusive (lo, hi) year windows no longer than `span` years.
+
+    list(year_windows(2000, 2024, 10))
+    [(2000, 2009), (2010, 2019), (2020, 2024)]
+    """
+    if span < 1:
+        raise ValueError("span must be >= 1")
+    if start > end:
+        raise ValueError("start must be <= end")
+    lo = start
+    while lo <= end:
+        hi = min(lo + span - 1, end)
+        yield (lo, hi)
+        lo = hi + 1
+
+
+def estimate_query_count(
+    n_series: int,
+    start_year: int | None,
+    end_year: int | None,
+    series_limit: int,
+    year_limit: int,
+) -> int:
+    """How many API calls a get_series() will consume after batching.
+
+    Useful for staying under the daily quota; exposed via BLSClient.query_cost().
+    A year range only multiplies the count when BOTH years are given (otherwise BLS
+    returns its default window in a single call).
+    """
+    series_chunks = max(1, math.ceil(n_series / series_limit))
+    if start_year is None or end_year is None:
+        year_chunks = 1
+    else:
+        year_chunks = max(1, math.ceil((end_year - start_year + 1) / year_limit))
+    return series_chunks * year_chunks

blsapi/client.py

@@ -0,0 +1,169 @@
+"""Synchronous BLS client."""
+
+import time
+from collections.abc import Mapping, Sequence
+
+import httpx2
+import polars as pl
+
+from . import batching, config
+from ._core import (
+    build_data_request,
+    merge_series,
+    parse_data_response,
+    plan_data_requests,
+)
+from ._endpoints import RequestSpec, popular_url, surveys_url
+from ._retry import backoff_delay, is_retryable, retry_after
+from .exceptions import BLSHTTPError
+from .frames import series_to_frame
+from .models import BLSResponse, SeriesRequest, normalize_series_ids
+
+
+class BLSClient:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = config.DEFAULT_BASE_URL,
+        timeout: float | httpx2.Timeout = config.DEFAULT_TIMEOUT,
+        max_retries: int = config.DEFAULT_MAX_RETRIES,
+        auto_batch: bool = True,
+        user_agent: str = config.DEFAULT_USER_AGENT,
+        client: httpx2.Client | None = None,
+    ) -> None:
+        self._api_key = config.resolve_api_key(api_key)
+        self._base_url = base_url
+        self._max_retries = max_retries
+        self._auto_batch = auto_batch
+
+        if client is not None:
+            # Caller-supplied client.
+            self._http = client
+            self._owns_client = False
+        else:
+            transport = httpx2.HTTPTransport(retries=2)
+            self._http = httpx2.Client(
+                timeout=timeout, transport=transport, headers={"User-Agent": user_agent}
+            )
+            self._owns_client = True
+
+    @property
+    def has_key(self) -> bool:
+        return self._api_key is not None
+
+    def _send(self, spec: RequestSpec) -> dict:
+        """Send a request with retry/backoff, returning parsed JSON."""
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._http.request(
+                    spec.method, spec.url, json=spec.json, params=spec.params
+                )
+                response.raise_for_status()
+                return response.json()
+            except (httpx2.RequestError, httpx2.HTTPStatusError) as exc:
+                last_exc = exc
+                if attempt == self._max_retries or not is_retryable(exc):
+                    raise BLSHTTPError(str(exc)) from exc
+                time.sleep(retry_after(exc) or backoff_delay(attempt))
+            except ValueError as exc:
+                raise BLSHTTPError(f"BLS returned a non-JSON response: {exc}") from exc
+        raise BLSHTTPError(str(last_exc)) from last_exc
+
+    def get_series(
+        self,
+        series_ids: str | Sequence[str] | Mapping[str, str],
+        *,
+        start_year: int | None = None,
+        end_year: int | None = None,
+        catalog: bool = False,
+        calculations: bool = False,
+        annual_average: bool = False,
+        aspects: bool = False,
+        latest: bool = False,
+        parse_values: bool = True,
+    ) -> pl.DataFrame:
+        """Fetch one or more series as a tidy Polars DataFrame.
+
+        `series_ids` may be a single id, a sequence of ids, or a {label: id} mapping (the
+        labels then replace the ids in the output's series_id column). When auto_batch is True,
+        requests that exceed the tier limits are transparently split across multiple API
+        calls and stitched back together by series id.
+        """
+        bls_ids, aliases = normalize_series_ids(series_ids)
+        req = SeriesRequest(
+            series_ids=bls_ids,
+            start_year=start_year,
+            end_year=end_year,
+            catalog=catalog,
+            calculations=calculations,
+            annual_average=annual_average,
+            aspects=aspects,
+            latest=latest,
+        )
+        specs = plan_data_requests(req, self._api_key, self._base_url, self._auto_batch)
+        series = merge_series(parse_data_response(self._send(spec)).series for spec in specs)
+        return series_to_frame(series, parse_values=parse_values, aliases=aliases)
+
+    def get_series_raw(
+        self,
+        series_ids: str | Sequence[str] | Mapping[str, str],
+        **flags: object,
+    ) -> BLSResponse:
+        """Same inputs as get_series, but return the validated BLSResponse (no frame)."""
+        bls_ids, _ = normalize_series_ids(series_ids)
+        req = SeriesRequest(series_ids=bls_ids, **flags)
+        spec = build_data_request(req, self._api_key, self._base_url)
+        return parse_data_response(self._send(spec))
+
+    def get_latest(self, series_id: str, **flags: object) -> pl.DataFrame:
+        """Most-recent data point for a single series (get_series with latest=True)."""
+        return self.get_series(series_id, latest=True, **flags)
+
+    def list_surveys(self) -> pl.DataFrame:
+        """All BLS surveys as a small DataFrame."""
+        params = {"registrationkey": self._api_key} if self._api_key else None
+        spec = RequestSpec("GET", surveys_url(self._base_url), params=params)
+        payload = self._send(spec)
+        return pl.DataFrame(payload["Results"]["survey"])
+
+    def get_survey(self, survey_abbr: str) -> dict:
+        """Metadata for a single survey."""
+        params = {"registrationkey": self._api_key} if self._api_key else None
+        spec = RequestSpec("GET", surveys_url(self._base_url, survey_abbr), params=params)
+        return self._send(spec)["Results"]
+
+    def get_popular(self, survey: str | None = None) -> list[str]:
+        """The most popular series ids, optionally scoped to one survey."""
+        params: dict[str, str] = {}
+        if survey is not None:
+            params["survey"] = survey
+        if self._api_key:
+            params["registrationkey"] = self._api_key
+        spec = RequestSpec("GET", popular_url(self._base_url), params=params or None)
+        payload = self._send(spec)
+        return [s["seriesID"] for s in payload["Results"]["series"]]
+
+    def query_cost(
+        self,
+        series_ids: str | Sequence[str] | Mapping[str, str],
+        start_year: int | None = None,
+        end_year: int | None = None,
+    ) -> int:
+        """Calculates how many API calls a matching get_series() would consume."""
+        bls_ids, _ = normalize_series_ids(series_ids)
+        series_limit, year_limit, _ = config.limits_for(self._api_key)
+        return batching.estimate_query_count(
+            len(bls_ids), start_year, end_year, series_limit, year_limit
+        )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> "BLSClient":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()

blsapi/config.py

@@ -0,0 +1,53 @@
+"""Default configuration constants and helpers for the BLS client.
+Everything here is a sensible default that the client constructor can override.
+"""
+
+import os
+import warnings
+
+import httpx2
+
+from .__about__ import __version__
+
+# endpoints & auth
+DEFAULT_BASE_URL = "https://api.bls.gov/publicAPI/v2/"
+API_KEY_ENV_VAR = "BLS_API_KEY"
+
+# BLS asks clients to identify themselves.
+DEFAULT_USER_AGENT = f"blsapi/{__version__}"
+# Registration keys are 32 hex chars.
+EXPECTED_KEY_LENGTH = 32
+
+# timeouts
+DEFAULT_TIMEOUT = httpx2.Timeout(connect=5.0, read=30.0, write=10.0, pool=5.0)
+
+# application-level retry/backoff
+DEFAULT_MAX_RETRIES = 3
+BACKOFF_BASE = 0.5  # seconds; first backoff ceiling
+BACKOFF_MAX = 30.0  # seconds; cap so jittered backoff can't explode
+RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+# BLS tier limits: (series_per_request, years_per_request, daily_queries)
+# These are used for input validation and auto-batching. The limits differ when a registration key is present.
+LIMITS_WITH_KEY = (50, 20, 500)
+LIMITS_NO_KEY = (25, 10, 25)
+
+
+def limits_for(api_key: str | None) -> tuple[int, int, int]:
+    """Return (series_per_request, years_per_request, daily_queries) for the active tier."""
+    return LIMITS_WITH_KEY if api_key else LIMITS_NO_KEY
+
+
+def resolve_api_key(api_key: str | None) -> str | None:
+    """Resolve the effective API key.
+
+    Warns when the key isn't the expected length.
+    """
+    if api_key is None:
+        api_key = os.environ.get(API_KEY_ENV_VAR)
+    if api_key is not None and len(api_key) != EXPECTED_KEY_LENGTH:
+        warnings.warn(
+            f"BLS API key is {len(api_key)} characters; expected {EXPECTED_KEY_LENGTH}.",
+            stacklevel=3,
+        )
+    return api_key

blsapi/enums.py

@@ -0,0 +1,23 @@
+from enum import Enum
+
+
+class Status(str, Enum):
+    """Top-level `status` values BLS can return in the JSON envelope."""
+
+    SUCCEEDED = "REQUEST_SUCCEEDED"
+    NOT_PROCESSED = "REQUEST_NOT_PROCESSED"
+    FAILED = "REQUEST_FAILED"
+
+
+class PeriodType(str, Enum):
+    """Classification of a BLS period code, derived from the M/Q/S/A prefix.
+
+    ANNUAL_AVERAGE is special: M13, Q05, and S03 are *computed averages* over the year,
+    not a point in calendar time, so they get no real `date` (see frames.period_to_date).
+    """
+
+    MONTHLY = "monthly"
+    QUARTERLY = "quarterly"
+    SEMIANNUAL = "semiannual"
+    ANNUAL = "annual"
+    ANNUAL_AVERAGE = "annual_average"

blsapi/exceptions.py

@@ -0,0 +1,31 @@
+"""Exception hierarchy for the blsapi client."""
+
+
+class BLSError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class BLSValidationError(BLSError):
+    """Bad input caught locally."""
+
+
+class BLSAPIError(BLSError):
+    """BLS processed the request but returned a non-success `status`.
+
+    Carries the raw status string and the `message` list so callers can inspect them.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: str | None = None,
+        messages: list[str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.messages = messages or []
+
+
+class BLSHTTPError(BLSError):
+    """Transport- or HTTP-level failure that survived our retry loop."""

blsapi/frames.py

@@ -0,0 +1,138 @@
+"""Shape BLS results into tidy Polars DataFrames.
+
+period_to_date() handles the M/Q/S/A period-code -> calendar-date mapping, including
+the annual-average trap (M13/Q05/S03 don't have a real date). series_to_frame() runs the flatten
++ value-coercion + date-construction pipeline, and pivot_wide() reshapes the long frame to one column per series.
+"""
+
+import datetime as dt
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING
+
+import polars as pl
+
+from .enums import PeriodType
+
+if TYPE_CHECKING:
+    from .models import SeriesResult
+
+
+def period_to_date(year: int, period: str) -> tuple[PeriodType, dt.date | None]:
+    """Map a (year, BLS period code) to a (PeriodType, first-of-period date).
+
+    Annual-average codes (M13, Q05, S03) classify as ANNUAL_AVERAGE and return a None
+    date, because they're a computed average over the year, not a moment in time. Keeping
+    a None date lets callers filter them out cleanly.
+
+    Raises ValueError on an unrecognized code.
+    """
+    code = period.strip().upper()
+    kind, number = code[:1], int(code[1:])
+
+    if kind == "M":
+        if 1 <= number <= 12:
+            return PeriodType.MONTHLY, dt.date(year, number, 1)
+        if number == 13:
+            return PeriodType.ANNUAL_AVERAGE, None
+    elif kind == "Q":
+        if 1 <= number <= 4:
+            # Quarter start months: Q1->Jan, Q2->Apr, Q3->Jul, Q4->Oct.
+            return PeriodType.QUARTERLY, dt.date(year, (number - 1) * 3 + 1, 1)
+        if number == 5:
+            return PeriodType.ANNUAL_AVERAGE, None
+    elif kind == "S":
+        if number in (1, 2):
+            # Semiannual: S1->Jan (H1), S2->Jul (H2).
+            return PeriodType.SEMIANNUAL, dt.date(year, 1 if number == 1 else 7, 1)
+        if number == 3:
+            return PeriodType.ANNUAL_AVERAGE, None
+    elif kind == "A":
+        return PeriodType.ANNUAL, dt.date(year, 1, 1)
+
+    raise ValueError(f"Unrecognized BLS period code: {period!r}")
+
+
+# Stable schema for an empty result.
+_EMPTY_SCHEMA = {
+    "series_id": pl.String,
+    "year": pl.Int64,
+    "period": pl.String,
+    "period_name": pl.String,
+    "period_type": pl.String,
+    "date": pl.Date,
+    "value": pl.Float64,
+    "latest": pl.Boolean,
+    "footnotes": pl.List,
+}
+
+
+def series_to_frame(
+    series: "Sequence[SeriesResult]",
+    *,
+    parse_values: bool = True,
+    aliases: "Mapping[str, str] | None" = None,
+) -> pl.DataFrame:
+    """Flatten BLS series results into one tidy/long Polars DataFrame.
+
+    Each input SeriesResult has `.series_id` and `.data` (a list of raw BLS point dicts).
+    Output is one row per (series, period), sorted by series then date.
+
+    parse_values: when True (default) cast `value` to Float64; when False keep the raw BLS
+        strings (mirrors blsR's parse_values=FALSE).
+    aliases: optional {bls_id: label} to relabel the series_id column.
+    """
+    rows: list[dict] = []
+    for result in series:
+        for point in result.data:
+            year = int(point["year"])
+            period_type, date = period_to_date(year, point["period"])
+            row = {
+                "series_id": result.series_id,
+                "year": year,
+                "period": point["period"],
+                "period_name": point.get("periodName"),
+                "period_type": period_type.value,
+                "date": date,
+                "value": point.get("value"),
+                "latest": bool(point.get("latest", False)),
+                "footnotes": [fn for fn in point["footnotes"] if fn],
+            }
+            if "calculations" in point:
+                net = point["calculations"].get("net_changes", {})
+                pct = point["calculations"].get("pct_changes", {})
+                for p in (1, 3, 6, 12):
+                    row[f"net_change_{p}m"] = net.get(str(p))
+                    row[f"pct_change_{p}m"] = pct.get(str(p))
+            rows.append(row)
+
+    if not rows:
+        schema = dict(_EMPTY_SCHEMA)
+        if not parse_values:
+            schema["value"] = pl.String
+        return pl.DataFrame(schema=schema)
+
+    frame = pl.DataFrame(rows, infer_schema_length=None).with_columns(pl.col("date").cast(pl.Date))
+
+    if parse_values:
+        calc_cols = [c for c in frame.columns if c.startswith(("net_change_", "pct_change_"))]
+        frame = frame.with_columns(
+            pl.col("value").str.strip_chars().cast(pl.Float64, strict=False),
+            *(pl.col(c).cast(pl.Float64, strict=False) for c in calc_cols),
+        )
+
+    if aliases:
+        frame = frame.with_columns(pl.col("series_id").replace(aliases))
+    return frame.sort(["series_id", "date"], nulls_last=True)
+
+
+def pivot_wide(df: pl.DataFrame) -> pl.DataFrame:
+    """Pivot the long frame to one value-column per series, indexed by date.
+
+    Annual-average rows have a null date, so they're filtered out before pivoting; pivot on
+    (year, period) instead if you need to keep them.
+    """
+    return (
+        df.filter(pl.col("date").is_not_null())
+        .pivot(values="value", index="date", on="series_id")
+        .sort("date")
+    )

blsapi/models.py

@@ -0,0 +1,141 @@
+"""Pydantic models:
+1. SeriesRequest  - validate inputs before sending the request.
+2. BLSResponse    - validate the response and raise typed errors on failure.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .enums import Status
+from .exceptions import BLSAPIError, BLSValidationError
+
+
+def normalize_series_ids(
+    series_ids: str | Sequence[str] | Mapping[str, str],
+) -> tuple[list[str], dict[str, str] | None]:
+    """Normalize the accepted `series_ids` shapes into (bls_ids, aliases).
+
+    Accepts a single id, a sequence of ids, or a {label: id} mapping. Returns the list of
+    BLS ids to request plus an optional {bls_id: label} map (inverted from the mapping) so
+    downstream code can relabel the output. aliases is None when no mapping was given.
+
+    This mirrors blsR's named-list feature. Raises BLSValidationError on empty input, blank
+    ids, or a mapping whose ids aren't unique.
+    """
+    if isinstance(series_ids, str):
+        _check_ids([series_ids])
+        return [series_ids], None
+    if isinstance(series_ids, Mapping):
+        if not series_ids:
+            raise BLSValidationError("series_ids mapping must not be empty")
+        ids = list(series_ids.values())
+        _check_ids(ids)
+        aliases = {bls_id: label for label, bls_id in series_ids.items()}
+        if len(aliases) != len(ids):
+            raise BLSValidationError("series_ids mapping maps two labels to the same id")
+        return ids, aliases
+    ids = list(series_ids)
+    if not ids:
+        raise BLSValidationError("series_ids must not be empty")
+    _check_ids(ids)
+    return ids, None
+
+
+def _check_ids(ids: list[str]) -> None:
+    if not all(isinstance(i, str) and i.strip() for i in ids):
+        raise BLSValidationError("every series id must be a non-empty string")
+
+
+class SeriesRequest(BaseModel):
+    """Validated inputs for a POST timeseries/data request."""
+
+    series_ids: list[str]
+    start_year: int | None = None
+    end_year: int | None = None
+    catalog: bool = False
+    calculations: bool = False
+    annual_average: bool = False
+    aspects: bool = False
+    latest: bool = False
+
+    @model_validator(mode="after")
+    def _validate(self) -> "SeriesRequest":
+        if not self.series_ids:
+            raise BLSValidationError("series_ids must not be empty")
+        if (
+            self.start_year is not None
+            and self.end_year is not None
+            and self.start_year > self.end_year
+        ):
+            raise BLSValidationError("start_year must be <= end_year")
+        return self
+
+    def to_payload(self, api_key: str | None) -> dict[str, Any]:
+        """Render the minimal JSON body that the BLS API expects."""
+        payload: dict = {"seriesid": self.series_ids}
+
+        if self.catalog:
+            payload["catalog"] = True
+        if self.calculations:
+            payload["calculations"] = True
+        if self.annual_average:
+            payload["annualaverage"] = True
+        if self.aspects:
+            payload["aspects"] = True
+        if self.latest:
+            payload["latest"] = True
+        if self.start_year is not None:
+            payload["startyear"] = str(self.start_year)
+        if self.end_year is not None:
+            payload["endyear"] = str(self.end_year)
+        if api_key is not None:
+            payload["registrationkey"] = api_key
+
+        return payload
+
+
+class SeriesResult(BaseModel):
+    """One series in the response."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    series_id: str = Field(alias="seriesID")
+    catalog: dict[str, Any] | None = None
+    data: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class Results(BaseModel):
+    series: list[SeriesResult] = Field(default_factory=list)
+
+
+class BLSResponse(BaseModel):
+    """The top-level error checking"""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    status: str
+    response_time: int | None = Field(default=None, alias="responseTime")
+    message: list[str] = Field(default_factory=list)
+    results: Results | None = Field(default=None, alias="Results")
+
+    @model_validator(mode="after")
+    def validate_response(self) -> BLSResponse:
+        if self.status != Status.SUCCEEDED:
+            raise BLSAPIError(
+                "; ".join(self.message) or self.status,
+                status=self.status,
+                messages=self.message,
+            )
+        for msg in self.message:
+            warnings.warn(msg, stacklevel=2)
+        return self
+
+    @property
+    def series(self) -> list[SeriesResult]:
+        """Convenience accessor"""
+        return self.results.series if self.results is not None else []