pixbr 0.1.0__py3-none-any.whl

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/_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/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)

pixbr/api.py

@@ -0,0 +1,97 @@
+"""Module-level convenience functions mirroring the pixr function names.
+
+Each call creates a short-lived :class:`~pixbr.client.PixClient`. For repeated
+requests, instantiate a ``PixClient`` once and reuse it (it keeps an HTTP
+connection pool open).
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Sequence
+
+import pandas as pd
+
+from . import aggregate
+from .client import PixClient
+
+
+def get_pix_keys(date: str, *, verbose: bool = True, **kwargs) -> pd.DataFrame:
+    with PixClient(verbose=verbose) as c:
+        return c.keys(date=date, verbose=verbose, **kwargs)
+
+
+def get_pix_keys_summary(date: str, n_top: int = 20, *, verbose: bool = True) -> pd.DataFrame:
+    with PixClient(verbose=verbose) as c:
+        return aggregate.keys_summary(c, date=date, n_top=n_top)
+
+
+def get_pix_keys_by_type(date: str, *, verbose: bool = True) -> pd.DataFrame:
+    with PixClient(verbose=verbose) as c:
+        return aggregate.keys_by_type(c, date=date)
+
+
+def get_pix_transaction_stats(database: str, *, verbose: bool = True, **kwargs) -> pd.DataFrame:
+    with PixClient(verbose=verbose) as c:
+        return c.transaction_stats(database=database, verbose=verbose, **kwargs)
+
+
+def get_pix_summary(database: str, group_by="NATUREZA", *, verbose: bool = True) -> pd.DataFrame:
+    with PixClient(verbose=verbose) as c:
+        return aggregate.transaction_summary(c, database=database, group_by=group_by)
+
+
+def get_pix_transactions_by_municipality(
+    database: str, *, verbose: bool = True, **kwargs
+) -> pd.DataFrame:
+    with PixClient(verbose=verbose) as c:
+        return c.transactions_by_municipality(database=database, verbose=verbose, **kwargs)
+
+
+def get_pix_transactions_by_state(database: str, *, verbose: bool = True) -> pd.DataFrame:
+    with PixClient(verbose=verbose) as c:
+        return aggregate.transactions_by_state(c, database=database)
+
+
+def get_pix_transactions_by_region(database: str, *, verbose: bool = True) -> pd.DataFrame:
+    with PixClient(verbose=verbose) as c:
+        return aggregate.transactions_by_region(c, database=database)
+
+
+def get_pix_fraud_stats(database: str, *, verbose: bool = True, **kwargs) -> pd.DataFrame:
+    with PixClient(verbose=verbose) as c:
+        return c.fraud_stats(database=database, verbose=verbose, **kwargs)
+
+
+def _get_multi(method_name: str, databases: Sequence[str], **kwargs) -> pd.DataFrame:
+    frames: List[pd.DataFrame] = []
+    with PixClient(verbose=False) as c:
+        method = getattr(c, method_name)
+        for db in databases:
+            try:
+                frames.append(method(database=db, verbose=False, **kwargs))
+            except Exception:  # noqa: BLE001 - keep going on per-month failures
+                frames.append(pd.DataFrame())
+    return pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+
+
+def get_pix_transaction_stats_multi(databases: Sequence[str], **kwargs) -> pd.DataFrame:
+    return _get_multi("transaction_stats", databases, **kwargs)
+
+
+def get_pix_fraud_stats_multi(databases: Sequence[str], **kwargs) -> pd.DataFrame:
+    return _get_multi("fraud_stats", databases, **kwargs)
+
+
+def pix_ping() -> pd.DataFrame:
+    with PixClient() as c:
+        return c.ping()
+
+
+def pix_query(endpoint: str, params: Optional[dict] = None, *, verbose: bool = True, **kwargs) -> pd.DataFrame:
+    with PixClient(verbose=verbose) as c:
+        return c.query(endpoint, params, verbose=verbose, **kwargs)
+
+
+def pix_url(endpoint: str, params: Optional[dict] = None, **kwargs) -> str:
+    with PixClient(verbose=False) as c:
+        return c.build_url(endpoint, params, **kwargs)

pixbr/client.py

@@ -0,0 +1,333 @@
+"""HTTP client for the BCB PIX Open Data API."""
+
+from __future__ import annotations
+
+import logging
+from typing import Mapping, Optional, Sequence
+
+import httpx
+import pandas as pd
+
+from . import _odata
+from ._odata import ParamValue
+
+logger = logging.getLogger("pixbr")
+
+# Endpoint metadata: endpoint name -> (param name, param format).
+ENDPOINTS = {
+    "ChavesPix": ("Data", "YYYY-MM-DD"),
+    "TransacoesPixPorMunicipio": ("DataBase", "YYYYMM"),
+    "EstatisticasTransacoesPix": ("Database", "YYYYMM"),
+    "EstatisticasFraudesPix": ("Database", "YYYYMM"),
+}
+
+_USER_AGENT = "pixbr Python package (https://github.com/StrategicProjects/pixbr)"
+
+
+class PixApiError(RuntimeError):
+    """Raised when the BCB PIX API returns an error or cannot be reached."""
+
+
+class PixClient:
+    """Client for the Brazilian Central Bank PIX Open Data API.
+
+    Parameters
+    ----------
+    timeout:
+        Request timeout in seconds (default 120). The BCB API can be slow for
+        large queries, so a generous timeout is recommended.
+    max_retries:
+        Number of retry attempts on transport errors (default 3).
+    verbose:
+        If True (default), log progress messages at INFO level.
+
+    Examples
+    --------
+    >>> client = PixClient()
+    >>> df = client.keys(date="2025-12-01", top=100)  # doctest: +SKIP
+    """
+
+    def __init__(
+        self,
+        timeout: float = _odata.DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+        verbose: bool = True,
+    ) -> None:
+        self.timeout = timeout
+        self.verbose = verbose
+        transport = httpx.HTTPTransport(retries=max_retries)
+        self._http = httpx.Client(
+            timeout=timeout,
+            transport=transport,
+            headers={
+                "Accept": "application/json;odata.metadata=minimal",
+                "User-Agent": _USER_AGENT,
+            },
+        )
+
+    # -- context manager / lifecycle ------------------------------------
+
+    def __enter__(self) -> "PixClient":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # -- low-level ------------------------------------------------------
+
+    def build_url(
+        self,
+        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,
+    ) -> str:
+        """Build (without sending) the URL for a request. Useful for debugging."""
+        return _odata.build_url(
+            endpoint,
+            params,
+            fmt=fmt,
+            filter=filter,
+            select=select,
+            orderby=orderby,
+            top=top,
+            skip=skip,
+        )
+
+    def query(
+        self,
+        endpoint: str,
+        params: Optional[Mapping[str, ParamValue]] = None,
+        *,
+        filter: Optional[str] = None,
+        select: Optional[Sequence[str]] = None,
+        orderby: Optional[str] = None,
+        top: Optional[int] = None,
+        skip: Optional[int] = None,
+        verbose: Optional[bool] = None,
+    ) -> pd.DataFrame:
+        """Low-level call to any PIX endpoint; returns a DataFrame.
+
+        This is the Python equivalent of ``pixr::pix_query``.
+        """
+        url = self.build_url(
+            endpoint,
+            params,
+            filter=filter,
+            select=select,
+            orderby=orderby,
+            top=top,
+            skip=skip,
+        )
+        return self._perform(url, verbose=verbose)
+
+    def _perform(self, url: str, verbose: Optional[bool] = None) -> pd.DataFrame:
+        verbose = self.verbose if verbose is None else verbose
+        if verbose:
+            logger.info("URL: %s", url)
+
+        try:
+            resp = self._http.get(url)
+        except httpx.HTTPError as exc:
+            raise PixApiError(
+                f"Connection error to BCB PIX API. Check your internet connection; "
+                f"the API may be temporarily unavailable. URL: {url}"
+            ) from exc
+
+        if resp.status_code != 200:
+            body = resp.text[:500]
+            raise PixApiError(
+                f"API request failed with status {resp.status_code} "
+                f"({resp.reason_phrase}). URL: {resp.url}. Response: {body}"
+            )
+
+        try:
+            body = resp.json()
+        except ValueError as exc:
+            raise PixApiError(
+                f"Failed to parse JSON response. Raw response: {resp.text[:500]}"
+            ) from exc
+
+        # OData responses wrap rows in a top-level 'value' field.
+        data = body.get("value", body) if isinstance(body, dict) else body
+
+        if not data:
+            if verbose:
+                logger.info("No data returned from API")
+            return pd.DataFrame()
+
+        df = pd.DataFrame(data)
+        if verbose:
+            logger.info("Retrieved %d record(s)", len(df))
+        return df
+
+    # -- typed endpoint accessors --------------------------------------
+
+    def keys(
+        self,
+        date: str,
+        *,
+        filter: Optional[str] = None,
+        columns: Optional[Sequence[str]] = None,
+        top: Optional[int] = None,
+        skip: Optional[int] = None,
+        orderby: Optional[str] = None,
+        verbose: Optional[bool] = None,
+    ) -> pd.DataFrame:
+        """PIX keys stock by participant (ChavesPix endpoint).
+
+        ``date`` is required, in YYYY-MM-DD form. The API returns data for the
+        last day of the month containing the given date.
+        """
+        valid = ["Data", "ISPB", "Nome", "NaturezaUsuario", "TipoChave", "qtdChaves"]
+        columns = _odata.validate_columns(columns, valid)
+        df = self.query(
+            "ChavesPix",
+            {"Data": _odata.parse_date_param(date)},
+            filter=filter,
+            select=columns,
+            orderby=orderby,
+            top=top,
+            skip=skip,
+            verbose=verbose,
+        )
+        return _coerce_numeric(df, ["qtdChaves"])
+
+    def transaction_stats(
+        self,
+        database: str,
+        *,
+        filter: Optional[str] = None,
+        columns: Optional[Sequence[str]] = None,
+        top: Optional[int] = None,
+        skip: Optional[int] = None,
+        orderby: Optional[str] = None,
+        verbose: Optional[bool] = None,
+    ) -> pd.DataFrame:
+        """PIX transaction statistics (EstatisticasTransacoesPix endpoint).
+
+        ``database`` is required, in YYYYMM form.
+        """
+        valid = [
+            "AnoMes", "PAG_PFPJ", "REC_PFPJ", "PAG_REGIAO", "REC_REGIAO",
+            "PAG_IDADE", "REC_IDADE", "FORMAINICIACAO", "NATUREZA",
+            "FINALIDADE", "VALOR", "QUANTIDADE",
+        ]
+        columns = _odata.validate_columns(columns, valid)
+        df = self.query(
+            "EstatisticasTransacoesPix",
+            {"Database": _odata.parse_year_month(database)},
+            filter=filter,
+            select=columns,
+            orderby=orderby,
+            top=top,
+            skip=skip,
+            verbose=verbose,
+        )
+        return _coerce_numeric(df, ["AnoMes", "VALOR", "QUANTIDADE"])
+
+    def transactions_by_municipality(
+        self,
+        database: str,
+        *,
+        filter: Optional[str] = None,
+        columns: Optional[Sequence[str]] = None,
+        top: Optional[int] = None,
+        skip: Optional[int] = None,
+        orderby: Optional[str] = None,
+        verbose: Optional[bool] = None,
+    ) -> pd.DataFrame:
+        """PIX transactions by municipality (TransacoesPixPorMunicipio endpoint).
+
+        ``database`` is required, in YYYYMM form. Note this endpoint uses the
+        ``DataBase`` parameter (capital B).
+        """
+        valid = [
+            "AnoMes", "Municipio_Ibge", "Municipio", "Estado_Ibge", "Estado",
+            "Sigla_Regiao", "Regiao",
+            "VL_PagadorPF", "QT_PagadorPF", "VL_PagadorPJ", "QT_PagadorPJ",
+            "VL_RecebedorPF", "QT_RecebedorPF", "VL_RecebedorPJ", "QT_RecebedorPJ",
+            "QT_PES_PagadorPF", "QT_PES_PagadorPJ",
+            "QT_PES_RecebedorPF", "QT_PES_RecebedorPJ",
+        ]
+        columns = _odata.validate_columns(columns, valid)
+        df = self.query(
+            "TransacoesPixPorMunicipio",
+            {"DataBase": _odata.parse_year_month(database)},
+            filter=filter,
+            select=columns,
+            orderby=orderby,
+            top=top,
+            skip=skip,
+            verbose=verbose,
+        )
+        numeric = [c for c in valid if c not in ("Municipio", "Estado", "Sigla_Regiao", "Regiao")]
+        return _coerce_numeric(df, numeric)
+
+    def fraud_stats(
+        self,
+        database: str,
+        *,
+        filter: Optional[str] = None,
+        columns: Optional[Sequence[str]] = None,
+        top: Optional[int] = None,
+        skip: Optional[int] = None,
+        orderby: Optional[str] = None,
+        verbose: Optional[bool] = None,
+    ) -> pd.DataFrame:
+        """PIX fraud statistics / MED (EstatisticasFraudesPix endpoint).
+
+        ``database`` is required, in YYYYMM form. The exact schema varies, so
+        columns are not validated; numeric-looking columns are coerced.
+        """
+        df = self.query(
+            "EstatisticasFraudesPix",
+            {"Database": _odata.parse_year_month(database)},
+            filter=filter,
+            select=columns,
+            orderby=orderby,
+            top=top,
+            skip=skip,
+            verbose=verbose,
+        )
+        if not df.empty:
+            patterns = ("QT_", "VL_", "QUANTIDADE", "VALOR", "ANOMES")
+            numeric = [c for c in df.columns if any(p in c.upper() for p in patterns)]
+            df = _coerce_numeric(df, numeric)
+        return df
+
+    def ping(self) -> pd.DataFrame:
+        """Test connectivity to all four endpoints with a single-record request."""
+        probes = {
+            "ChavesPix": {"Data": "2025-01-01"},
+            "TransacoesPixPorMunicipio": {"DataBase": "202501"},
+            "EstatisticasTransacoesPix": {"Database": "202501"},
+            "EstatisticasFraudesPix": {"Database": "202501"},
+        }
+        rows = []
+        for endpoint, params in probes.items():
+            url = self.build_url(endpoint, params, top=1)
+            try:
+                resp = self._http.get(url)
+                status = "OK" if resp.status_code == 200 else f"HTTP {resp.status_code}"
+            except httpx.HTTPError as exc:
+                status = str(exc)
+            rows.append({"endpoint": endpoint, "status": status})
+        return pd.DataFrame(rows)
+
+
+def _coerce_numeric(df: pd.DataFrame, columns: Sequence[str]) -> pd.DataFrame:
+    if df.empty:
+        return df
+    for col in columns:
+        if col in df.columns:
+            df[col] = pd.to_numeric(df[col], errors="coerce")
+    return df

pixbr/utils.py

@@ -0,0 +1,118 @@
+"""Standalone utility helpers (no network access)."""
+
+from __future__ import annotations
+
+from typing import Iterable, Union
+
+import pandas as pd
+
+from ._odata import parse_year_month  # noqa: F401  (re-exported convenience)
+
+
+def pix_endpoints() -> pd.DataFrame:
+    """Return a DataFrame describing the available BCB PIX API endpoints."""
+    return pd.DataFrame(
+        [
+            ("ChavesPix", "Data", "YYYY-MM-DD", "keys", "PIX keys stock by participant"),
+            ("TransacoesPixPorMunicipio", "DataBase", "YYYYMM",
+             "transactions_by_municipality", "PIX transactions by municipality"),
+            ("EstatisticasTransacoesPix", "Database", "YYYYMM",
+             "transaction_stats", "Transaction statistics with breakdowns"),
+            ("EstatisticasFraudesPix", "Database", "YYYYMM",
+             "fraud_stats", "Fraud statistics (MED)"),
+        ],
+        columns=["endpoint", "parameter", "param_format", "method", "description"],
+    )
+
+
+_COLUMNS = {
+    "keys": [
+        ("Data", "string", "Reference date (YYYY-MM-DD, last day of month)"),
+        ("ISPB", "string", "8-digit code identifying the financial institution"),
+        ("Nome", "string", "Name of the PIX participant (financial institution)"),
+        ("NaturezaUsuario", "string", "User type: PF (Individual) or PJ (Legal Entity)"),
+        ("TipoChave", "string", "Key type: CPF, CNPJ, Celular, e-mail, or Aleatória"),
+        ("qtdChaves", "numeric", "Number of registered keys"),
+    ],
+    "municipality": [
+        ("AnoMes", "integer", "Reference year-month (YYYYMM)"),
+        ("Municipio_Ibge", "integer", "IBGE municipality code"),
+        ("Municipio", "string", "Municipality name"),
+        ("Estado_Ibge", "integer", "IBGE state code"),
+        ("Estado", "string", "State name"),
+        ("Sigla_Regiao", "string", "Region abbreviation (NE, SE, S, CO, N)"),
+        ("Regiao", "string", "Region name"),
+        ("VL_PagadorPF", "numeric", "Value paid by individuals (BRL)"),
+        ("QT_PagadorPF", "numeric", "Count of transactions with individual payers"),
+        ("VL_PagadorPJ", "numeric", "Value paid by legal entities (BRL)"),
+        ("QT_PagadorPJ", "numeric", "Count of transactions with legal entity payers"),
+        ("VL_RecebedorPF", "numeric", "Value received by individuals (BRL)"),
+        ("QT_RecebedorPF", "numeric", "Count of transactions with individual receivers"),
+        ("VL_RecebedorPJ", "numeric", "Value received by legal entities (BRL)"),
+        ("QT_RecebedorPJ", "numeric", "Count of transactions with legal entity receivers"),
+        ("QT_PES_PagadorPF", "numeric", "Distinct individual payers"),
+        ("QT_PES_PagadorPJ", "numeric", "Distinct legal entity payers"),
+        ("QT_PES_RecebedorPF", "numeric", "Distinct individual receivers"),
+        ("QT_PES_RecebedorPJ", "numeric", "Distinct legal entity receivers"),
+    ],
+    "stats": [
+        ("AnoMes", "integer", "Reference year-month (YYYYMM)"),
+        ("PAG_PFPJ", "string", "Payer type: PF or PJ"),
+        ("REC_PFPJ", "string", "Receiver type: PF or PJ"),
+        ("PAG_REGIAO", "string", "Payer region"),
+        ("REC_REGIAO", "string", "Receiver region"),
+        ("PAG_IDADE", "string", "Payer age group"),
+        ("REC_IDADE", "string", "Receiver age group"),
+        ("FORMAINICIACAO", "string", "Initiation method (DICT, QRDN, QRES, MANU, INIC)"),
+        ("NATUREZA", "string", "Transaction nature (P2P, P2B, B2P, B2B, P2G, G2P)"),
+        ("FINALIDADE", "string", "Transaction purpose"),
+        ("VALOR", "numeric", "Total transaction value (BRL)"),
+        ("QUANTIDADE", "numeric", "Number of transactions"),
+    ],
+    "fraud": [
+        ("AnoMes", "integer", "Reference year-month (YYYYMM)"),
+        ("(varies)", "varies", "Fraud statistics columns - query the API for the full schema"),
+    ],
+}
+
+
+def pix_columns(endpoint: str = "keys") -> pd.DataFrame:
+    """Return column metadata for an endpoint.
+
+    ``endpoint`` is one of ``"keys"``, ``"municipality"``, ``"stats"``, ``"fraud"``.
+    """
+    if endpoint not in _COLUMNS:
+        raise ValueError(
+            f"Unknown endpoint {endpoint!r}. Choose one of {list(_COLUMNS)}."
+        )
+    return pd.DataFrame(_COLUMNS[endpoint], columns=["column", "type", "description"])
+
+
+def year_month_to_date(year_month: Union[str, Iterable[str]]) -> Union[pd.Timestamp, pd.DatetimeIndex]:
+    """Convert ``YYYYMM`` string(s) to date(s) at the first day of the month."""
+    if isinstance(year_month, str):
+        parse_year_month(year_month)  # validate
+        return pd.to_datetime(year_month + "01", format="%Y%m%d")
+    values = list(year_month)
+    for v in values:
+        parse_year_month(v)
+    return pd.to_datetime([v + "01" for v in values], format="%Y%m%d")
+
+
+def format_brl(
+    x: Union[float, Iterable[float]],
+    prefix: bool = True,
+    decimal_mark: str = ",",
+    big_mark: str = ".",
+) -> Union[str, list[str]]:
+    """Format number(s) as Brazilian Real currency (e.g. ``R$ 1.234.567,89``)."""
+
+    def _one(value: float) -> str:
+        # Format with US separators first, then swap to BR convention.
+        formatted = f"{round(value, 2):,.2f}"
+        formatted = formatted.replace(",", "\0").replace(".", decimal_mark).replace("\0", big_mark)
+        return f"R$ {formatted}" if prefix else formatted
+
+    if isinstance(x, (int, float)):
+        return _one(float(x))
+    return [_one(float(v)) for v in x]

pixbr-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+pixbr/__init__.py,sha256=XS7GTe-VsUkIl3AuKv-gP2HIgQ0Vwus3FwRtaQCuWug,1670
+pixbr/_odata.py,sha256=vR8tgwhSnoAOcQLeFvaADdlSjT0XQuEJiZPL_L_68HI,5530
+pixbr/aggregate.py,sha256=i-JPL2qs7paGDT4gXY_qfoOj7Ukq9LoTpVdne5eemag,4457
+pixbr/api.py,sha256=rM4LCHN7gw1UVZFx6hm2b05RzgYzcscDCZrmogawqPE,3605
+pixbr/client.py,sha256=S2O8zQNIkSbMU6NMfDBtrRp92yhxYIPKSRmk2LSbCAs,10891
+pixbr/utils.py,sha256=hxgzCdyZCe2_LixNb-u_FCcegUIqBb6wYEmJa070uQ4,5418
+pixbr-0.1.0.dist-info/METADATA,sha256=oJpsA7GReRG2lH-OA_qVlckYxHy-tirFCVbJIM7esKI,3838
+pixbr-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pixbr-0.1.0.dist-info/RECORD,,

pixbr-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