apifetch 0.1.0__py3-none-any.whl

apifetch/__init__.py

@@ -0,0 +1,55 @@
+"""apifetch — a generic toolkit for token-authenticated REST API retrieval.
+
+Quick start::
+
+    import apifetch as af
+
+    api = af.Api(
+        endpoint="https://api.example.com/v1/search",
+        service="Example",
+        auth=af.AuthBearer(),
+        pagination=af.PaginateOffset(where="query"),
+    )
+    af.store_token("reports", "my-secret-token", service="Example")
+    rows = af.fetch_all(api, "reports", chunk_size=1000)
+
+This is the Python sibling of the R package ``apifetch``.
+"""
+
+from __future__ import annotations
+
+from .api import (
+    Api,
+    Auth,
+    AuthBearer,
+    AuthHeader,
+    AuthQuery,
+    AuthRaw,
+    PaginateNone,
+    PaginateOffset,
+    Pagination,
+)
+from .fetch import ApiError, fetch, fetch_all
+from .tokens import get_token, list_tokens, remove_token, store_token
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Api",
+    "Auth",
+    "AuthRaw",
+    "AuthBearer",
+    "AuthHeader",
+    "AuthQuery",
+    "Pagination",
+    "PaginateOffset",
+    "PaginateNone",
+    "fetch",
+    "fetch_all",
+    "ApiError",
+    "store_token",
+    "get_token",
+    "remove_token",
+    "list_tokens",
+    "__version__",
+]

apifetch/_utils.py

@@ -0,0 +1,31 @@
+"""Internal helpers shared across the package."""
+
+from __future__ import annotations
+
+import math
+import unicodedata
+
+
+def sanitize_name(value: str) -> str:
+    """Transliterate to ASCII (dropping accents) and turn spaces into underscores.
+
+    This matches the contract shared by every token function so that the same
+    environment-variable name is computed everywhere.
+    """
+    nfkd = unicodedata.normalize("NFKD", value)
+    ascii_only = nfkd.encode("ascii", "ignore").decode("ascii")
+    return ascii_only.replace(" ", "_")
+
+
+def token_var(name: str, service: str) -> str:
+    """Build the environment-variable name for a token: ``<service>_<name>``."""
+    return f"{sanitize_name(service)}_{sanitize_name(name)}"
+
+
+def is_unset(value) -> bool:
+    """True for values that mean "no pagination bound": ``None``, ``<= 0``, ``inf``."""
+    if value is None:
+        return True
+    if isinstance(value, float) and math.isinf(value):
+        return True
+    return value <= 0

apifetch/api.py

@@ -0,0 +1,168 @@
+"""API profiles: authentication and pagination strategies.
+
+An :class:`Api` describes *where* to call, *how* to authenticate, and *how* to
+paginate. Auth and pagination are pluggable strategy objects, so the same fetch
+functions work against APIs with different conventions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ._utils import is_unset
+
+__all__ = [
+    "Auth",
+    "AuthRaw",
+    "AuthBearer",
+    "AuthHeader",
+    "AuthQuery",
+    "Pagination",
+    "PaginateOffset",
+    "PaginateNone",
+    "Api",
+]
+
+
+# ---- Authentication strategies -------------------------------------------
+
+
+class Auth:
+    """Base authentication strategy.
+
+    Subclasses contribute to a request's headers and/or query parameters.
+    """
+
+    def headers(self, token: str) -> dict:
+        return {}
+
+    def params(self, token: str) -> dict:
+        return {}
+
+
+@dataclass
+class AuthRaw(Auth):
+    """Send the token verbatim in a header (default ``Authorization``).
+
+    This is what the Big Data PE API expects.
+    """
+
+    header: str = "Authorization"
+
+    def headers(self, token: str) -> dict:
+        return {self.header: token}
+
+
+@dataclass
+class AuthBearer(Auth):
+    """Send ``"<prefix><token>"`` in a header (default ``Authorization: Bearer``)."""
+
+    header: str = "Authorization"
+    prefix: str = "Bearer "
+
+    def headers(self, token: str) -> dict:
+        return {self.header: f"{self.prefix}{token}"}
+
+
+@dataclass
+class AuthHeader(Auth):
+    """Send the token in an arbitrary header (e.g. ``X-API-Key``)."""
+
+    header: str = "X-API-Key"
+
+    def headers(self, token: str) -> dict:
+        return {self.header: token}
+
+
+@dataclass
+class AuthQuery(Auth):
+    """Send the token as a URL query parameter."""
+
+    param: str = "api_key"
+
+    def params(self, token: str) -> dict:
+        return {self.param: token}
+
+
+# ---- Pagination strategies -----------------------------------------------
+
+
+class Pagination:
+    """Base pagination strategy."""
+
+    def headers(self, limit, offset) -> dict:
+        return {}
+
+    def params(self, limit, offset) -> dict:
+        return {}
+
+
+@dataclass
+class PaginateOffset(Pagination):
+    """Send ``limit``/``offset`` as HTTP headers (default) or query parameters.
+
+    Non-positive, ``None`` and infinite values are omitted.
+    """
+
+    where: str = "header"  # "header" or "query"
+    limit_param: str = "limit"
+    offset_param: str = "offset"
+
+    def _values(self, limit, offset) -> dict:
+        vals = {}
+        if not is_unset(limit):
+            vals[self.limit_param] = int(limit)
+        if not is_unset(offset):
+            vals[self.offset_param] = int(offset)
+        return vals
+
+    def headers(self, limit, offset) -> dict:
+        # HTTP header values must be strings.
+        if self.where != "header":
+            return {}
+        return {k: str(v) for k, v in self._values(limit, offset).items()}
+
+    def params(self, limit, offset) -> dict:
+        return self._values(limit, offset) if self.where == "query" else {}
+
+
+@dataclass
+class PaginateNone(Pagination):
+    """Send no pagination parameters."""
+
+
+# ---- API profile ----------------------------------------------------------
+
+
+@dataclass
+class Api:
+    """Describe an API endpoint together with its auth and pagination strategies.
+
+    Args:
+        endpoint: The base API URL.
+        service: Namespace used to look up the token (see :func:`get_token`).
+        auth: An :class:`Auth` strategy. Defaults to bearer-token auth.
+        pagination: A :class:`Pagination` strategy. Defaults to offset paging
+            sent as HTTP headers.
+        drop_cols: Keys to drop from each record after parsing (e.g. a status
+            column).
+        connect_hint: Optional extra line shown on a connection error (e.g. a
+            VPN requirement).
+    """
+
+    endpoint: str
+    service: str = "apifetch"
+    auth: Auth = field(default_factory=AuthBearer)
+    pagination: Pagination = field(default_factory=PaginateOffset)
+    drop_cols: tuple[str, ...] = ()
+    connect_hint: str | None = None
+
+    def __post_init__(self):
+        if not self.endpoint:
+            raise ValueError("endpoint must be a non-empty string.")
+        if not isinstance(self.auth, Auth):
+            raise TypeError("auth must be an Auth instance (e.g. AuthBearer()).")
+        if not isinstance(self.pagination, Pagination):
+            raise TypeError(
+                "pagination must be a Pagination instance (e.g. PaginateOffset())."
+            )

apifetch/fetch.py

@@ -0,0 +1,152 @@
+"""Data fetching: single page and chunked retrieval."""
+
+from __future__ import annotations
+
+import math
+import sys
+from typing import Any, Optional
+
+import httpx
+
+from .api import Api
+from .tokens import get_token
+
+__all__ = ["fetch", "fetch_all", "ApiError"]
+
+
+class ApiError(RuntimeError):
+    """Raised when the API is unreachable or returns an HTTP error."""
+
+
+def _log(verbosity: int, message: str) -> None:
+    if verbosity > 0:
+        print(message, file=sys.stderr)
+
+
+def fetch(
+    api: Api,
+    name: str,
+    limit: Optional[float] = None,
+    offset: int = 0,
+    query: Optional[dict] = None,
+    verbosity: int = 0,
+    client: Optional[httpx.Client] = None,
+) -> list[dict[str, Any]]:
+    """Fetch a single page from ``api`` and return it as a list of records.
+
+    Args:
+        api: An :class:`Api` profile.
+        name: Token name to authenticate with (looked up via ``api.service``).
+        limit: Maximum records to request. ``None``/``inf`` means no limit.
+        offset: Starting record (omitted when ``0``).
+        query: Extra query-string filters.
+        verbosity: ``0`` silent, ``>=1`` progress messages.
+        client: Optional pre-built ``httpx.Client`` (useful for testing or
+            connection reuse). One is created and closed per call otherwise.
+
+    Returns:
+        The parsed JSON body as a list of dictionaries.
+    """
+    if not isinstance(api, Api):
+        raise TypeError("api must be an Api instance (see apifetch.Api).")
+    query = query or {}
+
+    token = get_token(name, service=api.service)
+    if token is None:
+        raise ApiError(
+            f"No token available for {name!r}; store one with apifetch.store_token()."
+        )
+
+    headers = {**api.auth.headers(token), **api.pagination.headers(limit, offset)}
+    params = {**query, **api.auth.params(token), **api.pagination.params(limit, offset)}
+
+    owns_client = client is None
+    client = client or httpx.Client()
+    try:
+        try:
+            resp = client.get(api.endpoint, headers=headers, params=params)
+        except httpx.RequestError as exc:
+            hint = f" {api.connect_hint}" if api.connect_hint else ""
+            raise ApiError(
+                f"Unable to connect to the API at {api.endpoint}. "
+                f"Check your network connection.{hint} ({exc})"
+            ) from exc
+    finally:
+        if owns_client:
+            client.close()
+
+    if resp.status_code >= 400:
+        raise ApiError(
+            f"The API returned an error (HTTP {resp.status_code} - {resp.reason_phrase}). "
+            "Try again later, and check that the endpoint and token are valid."
+        )
+
+    data = resp.json()
+    if isinstance(data, dict):
+        data = [data]
+    _log(verbosity, f"i Fetched {len(data)} records.")
+    return data
+
+
+def fetch_all(
+    api: Api,
+    name: str,
+    total_limit: Optional[float] = None,
+    chunk_size: int = 50_000,
+    query: Optional[dict] = None,
+    verbosity: int = 0,
+    client: Optional[httpx.Client] = None,
+) -> list[dict[str, Any]]:
+    """Fetch every record by paging through ``api`` in chunks.
+
+    Iteratively calls :func:`fetch` with an advancing ``offset`` until a chunk
+    comes back empty or ``total_limit`` is reached. Columns listed in
+    ``api.drop_cols`` are removed from each record.
+    """
+    if not isinstance(api, Api):
+        raise TypeError("api must be an Api instance (see apifetch.Api).")
+    if chunk_size <= 0:
+        raise ValueError("chunk_size must be a positive integer.")
+
+    total = math.inf if total_limit is None else total_limit
+    offset = 0
+    fetched = 0
+    records: list[dict[str, Any]] = []
+
+    owns_client = client is None
+    client = client or httpx.Client()
+    try:
+        while True:
+            current_limit = int(min(chunk_size, total - fetched))
+            if current_limit <= 0:
+                break
+
+            chunk = fetch(
+                api, name,
+                limit=current_limit,
+                offset=offset,
+                query=query,
+                verbosity=verbosity,
+                client=client,
+            )
+            if api.drop_cols:
+                chunk = [
+                    {k: v for k, v in row.items() if k not in api.drop_cols}
+                    for row in chunk
+                ]
+            if not chunk:
+                break
+
+            records.extend(chunk)
+            fetched += len(chunk)
+            offset += len(chunk)
+            _log(verbosity, f"i Fetched {len(chunk)} records (total: {fetched}).")
+
+            if fetched >= total:
+                break
+    finally:
+        if owns_client:
+            client.close()
+
+    _log(verbosity, f"✓ Fetching complete: {len(records)} records retrieved.")
+    return records

apifetch/tokens.py

@@ -0,0 +1,67 @@
+"""Token management via environment variables.
+
+Tokens are never written to disk; they live only in process environment
+variables named ``<service>_<name>``. ``service`` acts as a namespace so a single
+process can hold tokens for several different APIs without clashing.
+"""
+
+from __future__ import annotations
+
+import os
+
+from ._utils import sanitize_name, token_var
+
+__all__ = ["store_token", "get_token", "remove_token", "list_tokens"]
+
+
+def store_token(name: str, token: str, service: str = "apifetch") -> None:
+    """Store ``token`` for ``name`` in an environment variable.
+
+    Refuses to overwrite an existing, non-empty variable.
+    """
+    if not name:
+        raise ValueError("name must be a non-empty string.")
+    if not token:
+        raise ValueError("token must be a non-empty string.")
+
+    var = token_var(name, service)
+    if os.environ.get(var):
+        print(f"! {var} is already defined; not overwriting to avoid data loss.")
+        return
+
+    os.environ[var] = token
+    print(f"✓ Token stored in environment variable: {var}")
+
+
+def get_token(name: str, service: str = "apifetch") -> str | None:
+    """Return the token stored for ``name``/``service``, or ``None`` if missing."""
+    if not name:
+        raise ValueError("name must be a non-empty string.")
+
+    token = os.environ.get(token_var(name, service))
+    if not token:
+        print(f"! No token found for {name!r} (service {service!r}).")
+        return None
+    return token
+
+
+def remove_token(name: str, service: str = "apifetch") -> None:
+    """Remove the token stored for ``name``/``service`` if present."""
+    if not name:
+        raise ValueError("name must be a non-empty string.")
+
+    var = token_var(name, service)
+    if os.environ.get(var):
+        del os.environ[var]
+        print(f"✓ Token removed for {name!r} (service {service!r}).")
+    else:
+        print(f"! No token found for {name!r} (service {service!r}).")
+
+
+def list_tokens(service: str = "apifetch") -> list[str]:
+    """Return the names (without the ``service`` prefix) of stored tokens."""
+    prefix = f"{sanitize_name(service)}_"
+    names = [key[len(prefix):] for key in os.environ if key.startswith(prefix)]
+    if not names:
+        print(f"i No tokens found for service {service!r}.")
+    return sorted(names)

apifetch-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: apifetch
+Version: 0.1.0
+Summary: A generic toolkit for token-authenticated REST API retrieval.
+Project-URL: Homepage, https://github.com/StrategicProjects/apifetch-py
+Project-URL: Repository, https://github.com/StrategicProjects/apifetch-py
+Project-URL: R sibling, https://github.com/StrategicProjects/apifetch
+Author-email: André Leite <leite@de.ufpe.br>
+License: MIT License
+        
+        Copyright (c) 2026 André Leite
+        
+        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.
+License-File: LICENSE
+Keywords: api,client,http,pagination,rest,token
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pandas>=1.3; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/logo.png" width="200" alt="apifetch">
+</p>
+
+# apifetch (Python)
+
+`apifetch` is a small, dependency-light toolkit for talking to
+token-authenticated REST APIs. It handles three recurring chores:
+
+1. **Token management** — store/get/remove/list tokens in process environment
+   variables (never written to disk), namespaced per service.
+2. **Request building** — pluggable **authentication** and **pagination**
+   strategies, bundled into a reusable `Api` profile.
+3. **Data retrieval** — fetch one page, or fetch everything in chunks.
+
+This is the Python sibling of the R package
+[apifetch](https://github.com/StrategicProjects/apifetch). Both were extracted
+from the [BigDataPE](https://github.com/StrategicProjects/BigDataPE) package,
+which is now one *use case* (see `examples/bigdatape.py`).
+
+## Installation
+
+```bash
+pip install apifetch
+```
+
+## Usage
+
+```python
+import apifetch as af
+
+# 1. Describe the API once: where, how to authenticate, how to paginate.
+api = af.Api(
+    endpoint="https://api.example.com/v1/search",
+    service="Example",
+    auth=af.AuthBearer(),                 # "Authorization: Bearer <token>"
+    pagination=af.PaginateOffset(where="query"),
+)
+
+# 2. Store a token (kept only in this process's environment).
+af.store_token("reports", "my-secret-token", service="Example")
+
+# 3. Fetch.
+one_page = af.fetch(api, "reports", limit=50)
+everything = af.fetch_all(api, "reports", chunk_size=1000)
+
+# Optional: turn it into a DataFrame.
+# import pandas as pd; df = pd.DataFrame(everything)
+```
+
+### Strategies
+
+**Authentication:** `AuthBearer`, `AuthRaw`, `AuthHeader`, `AuthQuery`.
+
+**Pagination:** `PaginateOffset(where="header" | "query")`, `PaginateNone`.
+
+## License
+
+MIT © André Leite

apifetch-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+apifetch/__init__.py,sha256=FdebCUxfc_A1nHJQct34lQcCVe0xxlS4bDF5sdL4fCs,1133
+apifetch/_utils.py,sha256=IQtgRnd1hi4xCF1nz0JpJ1ECv_HMh5JjhBghpVPQvdY,983
+apifetch/api.py,sha256=ZSf6mUooVmbeQ-pOnLhBBMGdjDvyoy5gEzjRaEYYY_8,4502
+apifetch/fetch.py,sha256=BF7BW8JBbPJJZy-YcM-V7QRpRkuayz6weg_z_fOmHlw,4732
+apifetch/tokens.py,sha256=Ox9VAy-MfOAkDq7PmEbV-qbPm4V5c9Eb-Rym2r5-Svs,2291
+apifetch-0.1.0.dist-info/METADATA,sha256=8PIhDVkX1Djj9iTtNy6O8AGxtqcSkjNssYA3GvsoXpE,4126
+apifetch-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+apifetch-0.1.0.dist-info/licenses/LICENSE,sha256=OGxCK_IX0xDkZ7FRQynkGICKfxuVKrvLVheW4A7dQsA,1069
+apifetch-0.1.0.dist-info/RECORD,,

apifetch-0.1.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

apifetch-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 André Leite
+
+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.