pixbr 0.1.0__tar.gz

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

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest -q

pixbr-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: Build distribution
+    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: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pixbr
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC). No API token needed.
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pixbr-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.DS_Store

pixbr-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pixbr
+Version: 0.1.0
+Summary: Access Brazilian Central Bank PIX Open Data API (pandas-friendly)
+Project-URL: Homepage, https://github.com/StrategicProjects/pixbr
+Project-URL: Issues, https://github.com/StrategicProjects/pixbr/issues
+Author-email: Andre Leite <leite@castlab.org>, Marcos Wasilew <marcos.wasilew@gmail.com>, Hugo Vasconcelos <hugo.vasconcelos@ufpe.br>, Diogo Bezerra <diogo.bezerra@ufpe.br>
+License: MIT
+Keywords: banco central,bcb,brazil,odata,open data,pix
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pixbr
+
+Python client for the **Brazilian Central Bank (BCB) PIX Open Data API**
+([Olinda / OData service](https://olinda.bcb.gov.br/olinda/servico/Pix_DadosAbertos/versao/v1/aplicacao)).
+It hides the BCB's unusual OData URL syntax and returns
+[pandas](https://pandas.pydata.org/) DataFrames.
+
+This is the Python counterpart of the R package
+[`pixr`](https://github.com/StrategicProjects/pixr).
+
+## Installation
+
+```bash
+pip install pixbr        # once published
+# or, from source:
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+Reusable client (recommended for multiple requests):
+
+```python
+from pixbr import PixClient
+
+client = PixClient()
+
+# PIX keys stock by participant (date in YYYY-MM-DD)
+keys = client.keys("2025-12-01", filter="TipoChave eq 'CPF'", top=100)
+
+# Transaction statistics (database in YYYYMM)
+stats = client.transaction_stats("202509", filter="NATUREZA eq 'P2P'")
+
+# Transactions by municipality
+muni = client.transactions_by_municipality("202512", filter="Sigla_Regiao eq 'NE'")
+
+# Fraud statistics (MED)
+fraud = client.fraud_stats("202509", top=100)
+```
+
+Module-level convenience functions mirror the `pixr` names:
+
+```python
+from pixbr import get_pix_transaction_stats, get_pix_summary, format_brl
+
+df = get_pix_transaction_stats("202509")
+summary = get_pix_summary("202509", group_by="PAG_REGIAO")
+format_brl(1234567.89)   # 'R$ 1.234.567,89'
+```
+
+## Endpoints
+
+| Endpoint | Parameter | `PixClient` method | Convenience function |
+|---|---|---|---|
+| `ChavesPix` | `Data` (YYYY-MM-DD) | `.keys()` | `get_pix_keys()` |
+| `TransacoesPixPorMunicipio` | `DataBase` (YYYYMM) | `.transactions_by_municipality()` | `get_pix_transactions_by_municipality()` |
+| `EstatisticasTransacoesPix` | `Database` (YYYYMM) | `.transaction_stats()` | `get_pix_transaction_stats()` |
+| `EstatisticasFraudesPix` | `Database` (YYYYMM) | `.fraud_stats()` | `get_pix_fraud_stats()` |
+
+Use `pix_endpoints()` and `pix_columns("keys"|"municipality"|"stats"|"fraud")`
+to inspect available endpoints and columns.
+
+## OData query parameters
+
+All endpoint methods accept the common OData parameters:
+
+- `filter` — OData filter expression, e.g. `"NATUREZA eq 'P2P' and PAG_REGIAO eq 'SUDESTE'"`
+- `columns` — list of columns to select (unknown columns are dropped with a warning)
+- `orderby` — `"Column"` (asc) or `"Column desc"`
+- `top` — maximum number of records
+
+> **Note:** `skip` is **not supported** by the BCB PIX API; passing it emits a
+> warning and is ignored. Use `top` to limit results.
+
+## Notes
+
+- `PixClient(timeout=..., max_retries=..., verbose=...)` configures the HTTP
+  session. The default timeout is 120s — the BCB API can be slow for large
+  queries.
+- `client.build_url(...)` / `pix_url(...)` return the request URL without
+  sending it (handy for debugging).
+- `client.ping()` / `pix_ping()` test connectivity to all four endpoints.
+
+## License
+
+MIT

pixbr-0.1.0/README.md

@@ -0,0 +1,86 @@
+# pixbr
+
+Python client for the **Brazilian Central Bank (BCB) PIX Open Data API**
+([Olinda / OData service](https://olinda.bcb.gov.br/olinda/servico/Pix_DadosAbertos/versao/v1/aplicacao)).
+It hides the BCB's unusual OData URL syntax and returns
+[pandas](https://pandas.pydata.org/) DataFrames.
+
+This is the Python counterpart of the R package
+[`pixr`](https://github.com/StrategicProjects/pixr).
+
+## Installation
+
+```bash
+pip install pixbr        # once published
+# or, from source:
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+Reusable client (recommended for multiple requests):
+
+```python
+from pixbr import PixClient
+
+client = PixClient()
+
+# PIX keys stock by participant (date in YYYY-MM-DD)
+keys = client.keys("2025-12-01", filter="TipoChave eq 'CPF'", top=100)
+
+# Transaction statistics (database in YYYYMM)
+stats = client.transaction_stats("202509", filter="NATUREZA eq 'P2P'")
+
+# Transactions by municipality
+muni = client.transactions_by_municipality("202512", filter="Sigla_Regiao eq 'NE'")
+
+# Fraud statistics (MED)
+fraud = client.fraud_stats("202509", top=100)
+```
+
+Module-level convenience functions mirror the `pixr` names:
+
+```python
+from pixbr import get_pix_transaction_stats, get_pix_summary, format_brl
+
+df = get_pix_transaction_stats("202509")
+summary = get_pix_summary("202509", group_by="PAG_REGIAO")
+format_brl(1234567.89)   # 'R$ 1.234.567,89'
+```
+
+## Endpoints
+
+| Endpoint | Parameter | `PixClient` method | Convenience function |
+|---|---|---|---|
+| `ChavesPix` | `Data` (YYYY-MM-DD) | `.keys()` | `get_pix_keys()` |
+| `TransacoesPixPorMunicipio` | `DataBase` (YYYYMM) | `.transactions_by_municipality()` | `get_pix_transactions_by_municipality()` |
+| `EstatisticasTransacoesPix` | `Database` (YYYYMM) | `.transaction_stats()` | `get_pix_transaction_stats()` |
+| `EstatisticasFraudesPix` | `Database` (YYYYMM) | `.fraud_stats()` | `get_pix_fraud_stats()` |
+
+Use `pix_endpoints()` and `pix_columns("keys"|"municipality"|"stats"|"fraud")`
+to inspect available endpoints and columns.
+
+## OData query parameters
+
+All endpoint methods accept the common OData parameters:
+
+- `filter` — OData filter expression, e.g. `"NATUREZA eq 'P2P' and PAG_REGIAO eq 'SUDESTE'"`
+- `columns` — list of columns to select (unknown columns are dropped with a warning)
+- `orderby` — `"Column"` (asc) or `"Column desc"`
+- `top` — maximum number of records
+
+> **Note:** `skip` is **not supported** by the BCB PIX API; passing it emits a
+> warning and is ignored. Use `top` to limit results.
+
+## Notes
+
+- `PixClient(timeout=..., max_retries=..., verbose=...)` configures the HTTP
+  session. The default timeout is 120s — the BCB API can be slow for large
+  queries.
+- `client.build_url(...)` / `pix_url(...)` return the request URL without
+  sending it (handy for debugging).
+- `client.ping()` / `pix_ping()` test connectivity to all four endpoints.
+
+## License
+
+MIT

pixbr-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pixbr"
+version = "0.1.0"
+description = "Access Brazilian Central Bank PIX Open Data API (pandas-friendly)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Andre Leite", email = "leite@castlab.org" },
+    { name = "Marcos Wasilew", email = "marcos.wasilew@gmail.com" },
+    { name = "Hugo Vasconcelos", email = "hugo.vasconcelos@ufpe.br" },
+    { name = "Diogo Bezerra", email = "diogo.bezerra@ufpe.br" },
+]
+keywords = ["pix", "bcb", "banco central", "open data", "odata", "brazil"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pandas>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "respx>=0.21",
+]
+
+[project.urls]
+Homepage = "https://github.com/StrategicProjects/pixbr"
+Issues = "https://github.com/StrategicProjects/pixbr/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pixbr"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pixbr-0.1.0/src/pixbr/__init__.py

@@ -0,0 +1,69 @@
+"""pixbr — access the Brazilian Central Bank PIX Open Data API from Python.
+
+Two ways to use it:
+
+1. A reusable client (recommended for multiple requests)::
+
+       from pixbr import PixClient
+       client = PixClient()
+       df = client.transaction_stats("202509", filter="NATUREZA eq 'P2P'")
+
+2. Module-level convenience functions mirroring the R package ``pixr``::
+
+       from pixbr import get_pix_transaction_stats
+       df = get_pix_transaction_stats("202509")
+"""
+
+from __future__ import annotations
+
+from .client import ENDPOINTS, PixApiError, PixClient
+from .utils import (
+    format_brl,
+    pix_columns,
+    pix_endpoints,
+    year_month_to_date,
+)
+from .api import (
+    get_pix_fraud_stats,
+    get_pix_fraud_stats_multi,
+    get_pix_keys,
+    get_pix_keys_by_type,
+    get_pix_keys_summary,
+    get_pix_summary,
+    get_pix_transaction_stats,
+    get_pix_transaction_stats_multi,
+    get_pix_transactions_by_municipality,
+    get_pix_transactions_by_region,
+    get_pix_transactions_by_state,
+    pix_ping,
+    pix_query,
+    pix_url,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PixClient",
+    "PixApiError",
+    "ENDPOINTS",
+    # utils
+    "format_brl",
+    "pix_columns",
+    "pix_endpoints",
+    "year_month_to_date",
+    # convenience functions
+    "get_pix_keys",
+    "get_pix_keys_summary",
+    "get_pix_keys_by_type",
+    "get_pix_transaction_stats",
+    "get_pix_transaction_stats_multi",
+    "get_pix_summary",
+    "get_pix_transactions_by_municipality",
+    "get_pix_transactions_by_state",
+    "get_pix_transactions_by_region",
+    "get_pix_fraud_stats",
+    "get_pix_fraud_stats_multi",
+    "pix_ping",
+    "pix_query",
+    "pix_url",
+]

pixbr-0.1.0/src/pixbr/_odata.py

@@ -0,0 +1,168 @@
+"""URL building and parameter helpers for the BCB PIX Open Data (OData) API.
+
+The BCB Olinda API uses a non-standard OData syntax where endpoint parameters
+are passed as function arguments in the URL path *and* repeated as named query
+parameters, e.g.::
+
+    ChavesPix(Data=@Data)?$format=json&@Data='2025-12-01'&$top=10
+
+These helpers reproduce the exact URL construction used by the R package
+``pixr`` (which deliberately avoids standard percent-encoding, encoding only
+spaces as ``%20``). They are pure functions so they can be unit-tested without
+hitting the network.
+"""
+
+from __future__ import annotations
+
+import re
+import warnings
+from datetime import date, datetime
+from typing import Mapping, Optional, Sequence, Union
+
+BASE_URL = "https://olinda.bcb.gov.br/olinda/servico/Pix_DadosAbertos/versao/v1/odata"
+DEFAULT_TIMEOUT = 120
+
+ParamValue = Union[str, int, float]
+
+
+def build_url(
+    endpoint: str,
+    params: Optional[Mapping[str, ParamValue]] = None,
+    *,
+    fmt: str = "json",
+    filter: Optional[str] = None,
+    select: Optional[Sequence[str]] = None,
+    orderby: Optional[str] = None,
+    top: Optional[int] = None,
+    skip: Optional[int] = None,
+    base_url: str = BASE_URL,
+) -> str:
+    """Build a full request URL for a BCB PIX OData endpoint.
+
+    Mirrors ``pixr::pix_request`` URL construction exactly.
+    """
+    # Endpoint path, with function-style parameter declaration.
+    if params:
+        func_params = ",".join(f"{name}=@{name}" for name in params)
+        endpoint_url = f"{base_url}/{endpoint}({func_params})"
+    else:
+        endpoint_url = f"{base_url}/{endpoint}"
+
+    query_parts: list[str] = [f"$format={fmt}"]
+
+    # Endpoint parameters as @Param='value' (quoted for strings).
+    if params:
+        for name, value in params.items():
+            if isinstance(value, str):
+                query_parts.append(f"@{name}='{value}'")
+            else:
+                query_parts.append(f"@{name}={value}")
+
+    if filter:
+        # Collapse whitespace after commas and opening parens, matching pixr.
+        filter = re.sub(r",\s+", ",", filter)
+        filter = re.sub(r"\(\s+", "(", filter)
+        query_parts.append(f"$filter={filter}")
+
+    if select:
+        query_parts.append(f"$select={','.join(select)}")
+
+    if orderby:
+        query_parts.append(f"$orderby={orderby}")
+
+    if top is not None:
+        query_parts.append(f"$top={int(top)}")
+
+    if skip is not None:
+        warnings.warn(
+            "Parameter 'skip' is not supported by the BCB PIX API; "
+            "pagination with skip is not available. Use 'top' to limit results.",
+            stacklevel=2,
+        )
+
+    query_string = "&".join(query_parts)
+    # The API is picky about encoding: encode only spaces, like pixr.
+    query_string = query_string.replace(" ", "%20")
+    return f"{endpoint_url}?{query_string}"
+
+
+def parse_year_month(year_month: Union[str, int, date, None]) -> Optional[str]:
+    """Normalize a year-month to ``YYYYMM`` string form."""
+    if year_month is None:
+        return None
+    if isinstance(year_month, (date, datetime)):
+        return year_month.strftime("%Y%m")
+    s = str(year_month)
+    if not re.fullmatch(r"\d{6}", s):
+        raise ValueError(
+            f"Invalid year_month format: {s!r}. "
+            "Expected YYYYMM (e.g. '202312' for December 2023)."
+        )
+    return s
+
+
+def parse_date_param(value: Union[str, date, None]) -> Optional[str]:
+    """Normalize a date to ``YYYY-MM-DD`` string form (for the ChavesPix endpoint)."""
+    if value is None:
+        return None
+    if isinstance(value, (date, datetime)):
+        return value.strftime("%Y-%m-%d")
+    s = str(value)
+    if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", s):
+        raise ValueError(
+            f"Invalid date format: {s!r}. Expected YYYY-MM-DD (e.g. '2025-12-01')."
+        )
+    return s
+
+
+def validate_columns(
+    columns: Optional[Sequence[str]], valid_columns: Sequence[str]
+) -> Optional[list[str]]:
+    """Drop unknown column names (with a warning), preserving order."""
+    if columns is None:
+        return None
+    valid_set = set(valid_columns)
+    invalid = [c for c in columns if c not in valid_set]
+    if invalid:
+        warnings.warn(
+            f"Unknown column(s) ignored: {invalid}. Valid columns: {list(valid_columns)}",
+            stacklevel=2,
+        )
+    kept = [c for c in columns if c in valid_set]
+    return kept or None
+
+
+def format_orderby(
+    orderby: Optional[str], valid_columns: Optional[Sequence[str]] = None
+) -> Optional[str]:
+    """Format an orderby spec into the OData ``"Column asc|desc"`` form.
+
+    Accepts a leading ``-`` for descending order, or an already-formatted
+    ``"Column desc"`` string (passed through after validation).
+    """
+    if not orderby:
+        return None
+
+    if orderby.startswith("-"):
+        col, direction = orderby[1:], "desc"
+    elif " " in orderby:
+        # Already "Column asc/desc" form.
+        col = orderby.split(" ", 1)[0]
+        if valid_columns is not None and col not in valid_columns:
+            warnings.warn(
+                f"Invalid orderby column {col!r}; orderby will be ignored.",
+                stacklevel=2,
+            )
+            return None
+        return orderby
+    else:
+        col, direction = orderby, "asc"
+
+    if valid_columns is not None and col not in valid_columns:
+        warnings.warn(
+            f"Invalid orderby column {col!r}; orderby will be ignored.",
+            stacklevel=2,
+        )
+        return None
+
+    return f"{col} {direction}"

pixbr-0.1.0/src/pixbr/aggregate.py

@@ -0,0 +1,119 @@
+"""Convenience aggregations over the raw endpoint data (pandas-based).
+
+These mirror the dplyr-based summaries in ``pixr`` (get_pix_summary,
+get_pix_keys_summary, get_pix_transactions_by_state, etc.).
+"""
+
+from __future__ import annotations
+
+from typing import List, Sequence, Union
+
+import pandas as pd
+
+from .client import PixClient
+
+
+def keys_summary(client: PixClient, date: str, n_top: int = 20) -> pd.DataFrame:
+    """Total keys by institution, sorted descending, limited to ``n_top``."""
+    data = client.keys(date=date)
+    if data.empty:
+        return data
+    agg = (
+        data.groupby(["Nome", "ISPB"])
+        .agg(
+            total_keys=("qtdChaves", "sum"),
+            n_key_types=("TipoChave", "nunique"),
+        )
+        .reset_index()
+    )
+    pf = data[data["NaturezaUsuario"] == "PF"].groupby(["Nome", "ISPB"])["qtdChaves"].sum()
+    pj = data[data["NaturezaUsuario"] == "PJ"].groupby(["Nome", "ISPB"])["qtdChaves"].sum()
+    agg["pf_keys"] = agg.set_index(["Nome", "ISPB"]).index.map(pf).fillna(0).to_numpy()
+    agg["pj_keys"] = agg.set_index(["Nome", "ISPB"]).index.map(pj).fillna(0).to_numpy()
+    return agg.sort_values("total_keys", ascending=False).head(n_top).reset_index(drop=True)
+
+
+def keys_by_type(client: PixClient, date: str) -> pd.DataFrame:
+    """Total keys grouped by key type and user nature."""
+    data = client.keys(date=date)
+    if data.empty:
+        return data
+    return (
+        data.groupby(["TipoChave", "NaturezaUsuario"])
+        .agg(total_keys=("qtdChaves", "sum"), n_institutions=("ISPB", "nunique"))
+        .reset_index()
+        .sort_values("total_keys", ascending=False)
+        .reset_index(drop=True)
+    )
+
+
+def transaction_summary(
+    client: PixClient, database: str, group_by: Union[str, Sequence[str]] = "NATUREZA"
+) -> pd.DataFrame:
+    """Aggregate transaction statistics by one or more grouping columns."""
+    data = client.transaction_stats(database=database)
+    if data.empty:
+        return data
+    keys = [group_by] if isinstance(group_by, str) else list(group_by)
+    grouped = data.groupby(keys)
+    out = grouped.agg(
+        total_value=("VALOR", "sum"),
+        total_count=("QUANTIDADE", "sum"),
+        n_records=("VALOR", "size"),
+    ).reset_index()
+    out["avg_value"] = out["total_value"] / out["total_count"]
+    return out.sort_values("total_value", ascending=False).reset_index(drop=True)
+
+
+_MUNI_SUM_COLS = [
+    "VL_PagadorPF", "QT_PagadorPF", "VL_PagadorPJ", "QT_PagadorPJ",
+    "VL_RecebedorPF", "QT_RecebedorPF", "VL_RecebedorPJ", "QT_RecebedorPJ",
+]
+
+
+def _muni_lower(col: str) -> str:
+    return col.lower().replace("pagadorpf", "pagador_pf").replace("pagadorpj", "pagador_pj") \
+        .replace("recebedorpf", "recebedor_pf").replace("recebedorpj", "recebedor_pj")
+
+
+def transactions_by_state(client: PixClient, database: str) -> pd.DataFrame:
+    """Aggregate municipality data to the state level."""
+    return _aggregate_geo(
+        client, database,
+        keys=["AnoMes", "Estado_Ibge", "Estado", "Sigla_Regiao", "Regiao"],
+        count_name="n_municipalities",
+        count_kind="size",
+    )
+
+
+def transactions_by_region(client: PixClient, database: str) -> pd.DataFrame:
+    """Aggregate municipality data to the region level."""
+    data = client.transactions_by_municipality(database=database)
+    if data.empty:
+        return data
+    agg = {c: "sum" for c in _MUNI_SUM_COLS if c in data.columns}
+    out = data.groupby(["AnoMes", "Sigla_Regiao", "Regiao"]).agg(
+        n_states=("Estado_Ibge", "nunique"),
+        n_municipalities=("Estado_Ibge", "size"),
+        **{_muni_lower(c): (c, "sum") for c in _MUNI_SUM_COLS if c in data.columns},
+    ).reset_index()
+    sort_col = "vl_pagador_pf" if "vl_pagador_pf" in out.columns else out.columns[-1]
+    return out.sort_values(sort_col, ascending=False).reset_index(drop=True)
+
+
+def _aggregate_geo(
+    client: PixClient,
+    database: str,
+    keys: List[str],
+    count_name: str,
+    count_kind: str,
+) -> pd.DataFrame:
+    data = client.transactions_by_municipality(database=database)
+    if data.empty:
+        return data
+    out = data.groupby(keys).agg(
+        **{count_name: ("AnoMes", count_kind)},
+        **{_muni_lower(c): (c, "sum") for c in _MUNI_SUM_COLS if c in data.columns},
+    ).reset_index()
+    sort_col = "vl_pagador_pf" if "vl_pagador_pf" in out.columns else out.columns[-1]
+    return out.sort_values(sort_col, ascending=False).reset_index(drop=True)