apifetch 0.1.0__tar.gz

apifetch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q

apifetch-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,22 @@
+name: docs
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install docs deps
+        run: pip install -e ".[docs]"
+      - name: Build & deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

apifetch-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

apifetch-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+site/
+.DS_Store

apifetch-0.1.0/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.

apifetch-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,59 @@
+<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/docs/assets/favicon-src.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg"
+     viewBox="6 -6 188 212" preserveAspectRatio="xMidYMid meet"
+     role="img" aria-label="apifetch for Python">
+  <title>apifetch (Python)</title>
+  <defs>
+    <linearGradient id="hexpy" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#22357d"/>
+      <stop offset="1" stop-color="#1a2a65"/>
+    </linearGradient>
+  </defs>
+  <path d="M100,0 L186.6,50 L186.6,150 L100,200 L13.4,150 L13.4,50 Z"
+        fill="url(#hexpy)" stroke="#ffd43b" stroke-width="7" stroke-linejoin="round"/>
+  <path d="M84,46 L116,46 L116,104 L142,104 L100,150 L58,104 L84,104 Z"
+        fill="#4b8bbe" stroke="#1a2a65" stroke-width="3" stroke-linejoin="round"/>
+</svg>

apifetch-0.1.0/docs/assets/logo.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg"
+     width="246.5" height="280" viewBox="1.4 -12 197.2 224"
+     preserveAspectRatio="xMidYMid meet"
+     role="img" aria-label="apifetch for Python">
+  <title>apifetch (Python)</title>
+  <defs>
+    <style type="text/css">
+      text { font-family: 'Jost', 'Helvetica Neue', Arial, sans-serif; }
+    </style>
+    <linearGradient id="hexpy" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#22357d"/>
+      <stop offset="1" stop-color="#1a2a65"/>
+    </linearGradient>
+  </defs>
+
+  <!-- hexagon (regular: every edge length 100, uniform 5px stroke) -->
+  <path d="M100,0 L186.6,50 L186.6,150 L100,200 L13.4,150 L13.4,50 Z"
+        fill="url(#hexpy)" stroke="#ffd43b" stroke-width="5" stroke-linejoin="round"/>
+
+  <!-- fetch arrow (download = retrieve) in Python blue -->
+  <path d="M90,22 L110,22 L110,62 L126,62 L100,90 L74,62 L90,62 Z"
+        fill="#4b8bbe" stroke="#1a2a65" stroke-width="2.5" stroke-linejoin="round"/>
+
+  <!-- wordmark: textLength locks the width so font substitution can't overflow -->
+  <text x="100" y="112" text-anchor="middle" font-weight="bold"
+        fill="#ececec" font-size="28" textLength="130"
+        lengthAdjust="spacingAndGlyphs" dominant-baseline="central">apifetch</text>
+
+  <!-- "python" badge, kept in the full-width band -->
+  <text x="100" y="136" text-anchor="middle" font-weight="bold"
+        fill="#ffd43b" font-size="14" textLength="92"
+        lengthAdjust="spacingAndGlyphs" dominant-baseline="central">PYTHON</text>
+</svg>

apifetch-0.1.0/docs/bigdatape.md

@@ -0,0 +1,48 @@
+# Use case: the Big Data PE API
+
+`apifetch` was extracted from the
+[BigDataPE](https://github.com/StrategicProjects/BigDataPE) package, which wraps
+the **Big Data PE** platform — a public-data REST API run by the Government of
+the State of Pernambuco, Brazil. This page is the canonical worked example of
+configuring the package for a real API.
+
+## What is specific about Big Data PE
+
+| Convention | Strategy |
+|---|---|
+| Token sent *verbatim* in the `Authorization` header (no `Bearer`) | `AuthRaw()` |
+| `limit`/`offset` sent as **HTTP headers**, not query params | `PaginateOffset(where="header")` |
+| Responses carry a status column `"Mensagem"` to drop | `drop_cols=("Mensagem",)` |
+| Reachable only from the PE Conectado network / VPN | `connect_hint=...` |
+
+## Defining the profile
+
+```python
+import apifetch as af
+
+bigdatape = af.Api(
+    endpoint="https://www.bigdata.pe.gov.br/api/buscar",
+    service="BigDataPE",
+    auth=af.AuthRaw(),
+    pagination=af.PaginateOffset(where="header"),
+    drop_cols=("Mensagem",),
+    connect_hint="Ensure you are on the PE Conectado network or VPN.",
+)
+```
+
+## Storing a token and fetching
+
+```python
+af.store_token("dengue", "your-token-here", service="BigDataPE")
+
+# A single page of 50 records
+dengue = af.fetch(bigdatape, "dengue", limit=50)
+
+# Everything, in chunks, with a progress message per chunk
+dengue_all = af.fetch_all(bigdatape, "dengue", chunk_size=50_000, verbosity=1)
+```
+
+!!! note "On language"
+    Function and parameter names are English, but the API's response keys and
+    some values are Portuguese (e.g. `nu_notificacao`, `"BOA VIAGEM"`). That is
+    intentional — they come straight from the upstream service.

apifetch-0.1.0/docs/index.md

@@ -0,0 +1,50 @@
+<p align="center">
+  <img src="assets/logo.svg" width="200" alt="apifetch">
+</p>
+
+# apifetch
+
+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`](reference.md) 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).
+
+## Installation
+
+```bash
+pip install apifetch
+```
+
+## Quick start
+
+```python
+import apifetch as af
+
+api = af.Api(
+    endpoint="https://api.example.com/v1/search",
+    service="Example",
+    auth=af.AuthBearer(),                 # "Authorization: Bearer <token>"
+    pagination=af.PaginateOffset(where="query"),
+)
+
+af.store_token("reports", "my-secret-token", service="Example")
+
+one_page = af.fetch(api, "reports", limit=50)
+everything = af.fetch_all(api, "reports", chunk_size=1000)
+```
+
+### Strategies
+
+**Authentication:** `AuthBearer`, `AuthRaw`, `AuthHeader`, `AuthQuery`.
+
+**Pagination:** `PaginateOffset(where="header" | "query")`, `PaginateNone`.
+
+See the [BigDataPE use case](bigdatape.md) for a real-world configuration, or the
+full [API reference](reference.md).

apifetch-0.1.0/docs/reference.md

@@ -0,0 +1,41 @@
+# API reference
+
+## Fetching
+
+::: apifetch.fetch
+
+::: apifetch.fetch_all
+
+## API profile
+
+::: apifetch.Api
+
+## Authentication strategies
+
+::: apifetch.AuthRaw
+
+::: apifetch.AuthBearer
+
+::: apifetch.AuthHeader
+
+::: apifetch.AuthQuery
+
+## Pagination strategies
+
+::: apifetch.PaginateOffset
+
+::: apifetch.PaginateNone
+
+## Token management
+
+::: apifetch.store_token
+
+::: apifetch.get_token
+
+::: apifetch.remove_token
+
+::: apifetch.list_tokens
+
+## Errors
+
+::: apifetch.ApiError

apifetch-0.1.0/examples/bigdatape.py

@@ -0,0 +1,43 @@
+"""Use case: the Big Data PE API.
+
+`apifetch` was extracted from the BigDataPE package, which wraps the Big Data PE
+platform — a public-data REST API run by the Government of the State of
+Pernambuco, Brazil. This is the canonical worked example of configuring the
+package for a real API.
+
+What is specific about Big Data PE:
+
+- Authentication sends the token *verbatim* in the ``Authorization`` header
+  (no ``Bearer`` prefix)            -> ``AuthRaw()``
+- Pagination sends ``limit``/``offset`` as HTTP *headers*, not query params
+                                      -> ``PaginateOffset(where="header")``
+- Responses carry a status column ``"Mensagem"`` we drop  -> ``drop_cols``
+- The API is reachable only from the PE Conectado network or VPN -> ``connect_hint``
+"""
+
+import apifetch as af
+
+bigdatape = af.Api(
+    endpoint="https://www.bigdata.pe.gov.br/api/buscar",
+    service="BigDataPE",
+    auth=af.AuthRaw(),
+    pagination=af.PaginateOffset(where="header"),
+    drop_cols=("Mensagem",),
+    connect_hint="Ensure you are on the PE Conectado network or VPN.",
+)
+
+if __name__ == "__main__":
+    # Store your token (kept only in this process's environment).
+    af.store_token("dengue", "your-token-here", service="BigDataPE")
+
+    # A single page of 50 records.
+    dengue = af.fetch(bigdatape, "dengue", limit=50)
+    print(f"got {len(dengue)} records")
+
+    # Everything, in chunks, with a progress message per chunk.
+    dengue_all = af.fetch_all(bigdatape, "dengue", chunk_size=50_000, verbosity=1)
+    print(f"got {len(dengue_all)} records total")
+
+    # Optional: a DataFrame.
+    # import pandas as pd
+    # df = pd.DataFrame(dengue_all)

apifetch-0.1.0/mkdocs.yml

@@ -0,0 +1,45 @@
+site_name: apifetch (Python)
+site_description: A generic toolkit for token-authenticated REST API retrieval.
+site_url: https://strategicprojects.github.io/apifetch-py/
+repo_url: https://github.com/StrategicProjects/apifetch-py
+repo_name: StrategicProjects/apifetch-py
+
+theme:
+  name: material
+  logo: assets/logo.svg
+  favicon: assets/favicon.png
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.sections
+    - content.code.copy
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_source: false
+            docstring_style: google
+
+nav:
+  - Home: index.md
+  - "Use case — BigDataPE": bigdatape.md
+  - API reference: reference.md
+
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight
+  - pymdownx.superfences

apifetch-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apifetch"
+version = "0.1.0"
+description = "A generic toolkit for token-authenticated REST API retrieval."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "André Leite", email = "leite@de.ufpe.br" }]
+keywords = ["api", "rest", "http", "token", "pagination", "client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.3"]
+dev = ["pytest>=7", "respx>=0.20", "pandas>=1.3"]
+docs = ["mkdocs-material>=9", "mkdocstrings[python]>=0.24"]
+
+[project.urls]
+Homepage = "https://github.com/StrategicProjects/apifetch-py"
+Repository = "https://github.com/StrategicProjects/apifetch-py"
+"R sibling" = "https://github.com/StrategicProjects/apifetch"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apifetch"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

apifetch-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_api.py

@@ -0,0 +1,43 @@
+import math
+
+import pytest
+
+import apifetch as af
+
+
+def test_auth_strategies():
+    assert af.AuthRaw().headers("tok") == {"Authorization": "tok"}
+    assert af.AuthBearer().headers("tok") == {"Authorization": "Bearer tok"}
+    assert af.AuthHeader("X-API-Key").headers("tok") == {"X-API-Key": "tok"}
+    assert af.AuthQuery("api_key").params("tok") == {"api_key": "tok"}
+
+
+def test_pagination_offset_header():
+    p = af.PaginateOffset(where="header")
+    assert p.headers(10, 5) == {"limit": "10", "offset": "5"}  # headers are strings
+    assert p.params(10, 5) == {}
+    # inf / None / non-positive omitted
+    assert p.headers(math.inf, 0) == {}
+    assert p.headers(None, None) == {}
+
+
+def test_pagination_offset_query():
+    p = af.PaginateOffset(where="query")
+    assert p.params(10, 0) == {"limit": 10}
+    assert p.headers(10, 0) == {}
+
+
+def test_api_validation():
+    with pytest.raises(ValueError):
+        af.Api("")
+    with pytest.raises(TypeError):
+        af.Api("https://x.test", auth="nope")
+    with pytest.raises(TypeError):
+        af.Api("https://x.test", pagination="nope")
+
+
+def test_api_defaults():
+    api = af.Api("https://x.test", service="S", drop_cols=("Mensagem",))
+    assert isinstance(api.auth, af.AuthBearer)
+    assert isinstance(api.pagination, af.PaginateOffset)
+    assert api.drop_cols == ("Mensagem",)

apifetch-0.1.0/tests/test_fetch.py

@@ -0,0 +1,78 @@
+import httpx
+import pytest
+
+import apifetch as af
+
+
+def _client(handler):
+    return httpx.Client(transport=httpx.MockTransport(handler))
+
+
+def test_fetch_sends_auth_and_pagination(monkeypatch):
+    monkeypatch.delenv("T_ds", raising=False)
+    af.store_token("ds", "secret", service="T")
+    captured = {}
+
+    def handler(request):
+        captured["auth"] = request.headers.get("authorization")
+        captured["limit"] = request.headers.get("limit")
+        return httpx.Response(200, json=[{"a": 1}, {"a": 2}])
+
+    api = af.Api(
+        "https://x.test/api",
+        service="T",
+        auth=af.AuthRaw(),
+        pagination=af.PaginateOffset(where="header"),
+    )
+    rows = af.fetch(api, "ds", limit=2, client=_client(handler))
+
+    assert rows == [{"a": 1}, {"a": 2}]
+    assert captured["auth"] == "secret"
+    assert captured["limit"] == "2"
+    af.remove_token("ds", service="T")
+
+
+def test_fetch_all_pages_until_empty(monkeypatch):
+    monkeypatch.delenv("T_ds", raising=False)
+    af.store_token("ds", "secret", service="T")
+    pages = [
+        [{"x": 1, "Mensagem": "ok"}, {"x": 2, "Mensagem": "ok"}],
+        [{"x": 3, "Mensagem": "ok"}],
+        [],
+    ]
+    calls = {"n": 0}
+
+    def handler(request):
+        page = pages[calls["n"]]
+        calls["n"] += 1
+        return httpx.Response(200, json=page)
+
+    api = af.Api(
+        "https://x.test/api",
+        service="T",
+        auth=af.AuthRaw(),
+        drop_cols=("Mensagem",),
+    )
+    rows = af.fetch_all(api, "ds", chunk_size=2, client=_client(handler))
+
+    assert [r["x"] for r in rows] == [1, 2, 3]
+    assert all("Mensagem" not in r for r in rows)  # drop_cols applied
+    af.remove_token("ds", service="T")
+
+
+def test_fetch_http_error_raises():
+    af.store_token("ds", "secret", service="T")
+
+    def handler(request):
+        return httpx.Response(503, text="down")
+
+    api = af.Api("https://x.test/api", service="T", auth=af.AuthRaw())
+    with pytest.raises(af.ApiError):
+        af.fetch(api, "ds", client=_client(handler))
+    af.remove_token("ds", service="T")
+
+
+def test_fetch_missing_token_raises():
+    api = af.Api("https://x.test/api", service="Empty", auth=af.AuthRaw())
+    with pytest.raises(af.ApiError):
+        af.fetch(api, "absent")

apifetch-0.1.0/tests/test_tokens.py

@@ -0,0 +1,37 @@
+import apifetch as af
+
+
+def test_round_trip(monkeypatch):
+    monkeypatch.delenv("svc_alpha", raising=False)
+    af.store_token("alpha", "tok-123", service="svc")
+    assert af.get_token("alpha", service="svc") == "tok-123"
+    assert "alpha" in af.list_tokens(service="svc")
+    af.remove_token("alpha", service="svc")
+    assert af.get_token("alpha", service="svc") is None
+
+
+def test_no_overwrite(monkeypatch):
+    monkeypatch.delenv("svc_beta", raising=False)
+    af.store_token("beta", "first", service="svc")
+    af.store_token("beta", "second", service="svc")  # refused
+    assert af.get_token("beta", service="svc") == "first"
+
+
+def test_accents_and_spaces(monkeypatch):
+    af.store_token("São Paulo", "tok", service="svc")
+    assert af.get_token("São Paulo", service="svc") == "tok"
+    # env var name is sanitized
+    import os
+    assert "svc_Sao_Paulo" in os.environ
+
+
+def test_missing_returns_none():
+    assert af.get_token("nope", service="absent") is None
+
+
+def test_invalid_inputs():
+    import pytest
+    with pytest.raises(ValueError):
+        af.store_token("", "tok")
+    with pytest.raises(ValueError):
+        af.store_token("x", "")