pypix_api package

pypix-api: Biblioteca Python para integracao com APIs bancarias do PIX.

Esta biblioteca facilita a integracao com APIs de bancos brasileiros, fornecendo uma interface simples e consistente para operacoes PIX.

class pypix_api.BBPixAPI(oauth, sandbox_mode=False)[source]

Bases: PixBBMethods, BankPixAPIBase

Implementação da API PIX do Banco do Brasil.

Parameters:

oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação
sandbox_mode (bool) – Se True, usa ambiente de sandbox (default: False)

BASE_URL: URL da API de produção

SANDBOX_BASE_URL: URL da API de sandbox

TOKEN_URL: URL para obtenção de token OAuth2

SCOPES: Scopes necessários para autenticação

BASE_URL: str | None = 'https://api-pix.bb.com.br/pix/v2'

SANDBOX_BASE_URL = 'https://api-pix.hm.bb.com.br/pix/v2'

TOKEN_URL: str | None = 'https://oauth.bb.com.br/oauth/token'

get_bank_code()[source]

Return type:: str

get_base_url()[source]

Obtém a URL base da API de acordo com o modo de operação.

Returns:: URL base da API (produção ou sandbox)
Return type:: str

Note

O modo sandbox é controlado pelo parâmetro sandbox_mode passado no construtor

class pypix_api.OAuth2Client(token_url, client_id=None, cert=None, pvk=None, cert_pfx=None, pwd_pfx=None, sandbox_mode=False)[source]

Bases: object

Cliente OAuth2 para autenticação com a API

__init__(token_url, client_id=None, cert=None, pvk=None, cert_pfx=None, pwd_pfx=None, sandbox_mode=False)[source]

Inicializa o cliente OAuth2

Parameters:

token_url (str) – URL de autenticação OAuth2
client_id (str | None) – Client ID para autenticação OAuth2
cert (str | None) – Path para o certificado PEM (opcional)
pvk (str | None) – Path para a chave privada PEM (opcional)
cert_pfx (str | bytes | BinaryIO | None) – Path ou dados do certificado PFX (opcional)
pwd_pfx (str | None) – Senha do certificado PFX (opcional)
sandbox_mode (bool) – Se True, não requer certificado (default: False)

get_token(scope=None)[source]

Obtém ou renova o token de acesso para o escopo especificado

Parameters:: scope (str | None) – Escopo(s) necessário(s) para a API. Exemplos: - Cobrança por Boleto: “boletos_inclusao boletos_consulta boletos_alteracao webhooks_alteracao webhooks_consulta webhooks_inclusao” - Conta Corrente: “cco_consulta cco_transferencias openid” - Recebimento no PIX: “cob.write cob.read cobv.write cobv.read lotecobv.write lotecobv.read pix.write pix.read webhook.read webhook.write payloadlocation.write payloadlocation.read”
Returns:: Token de acesso válido para o escopo solicitado
Return type:: str

class pypix_api.PixCobranca(txid, valor, status, chave)[source]

Bases: object

__init__(txid, valor, status, chave)

txid: str

valor: float

status: str

chave: str

class pypix_api.SicoobPixAPI(oauth, sandbox_mode=False)[source]

Bases: BankPixAPIBase

Implementação da API PIX do Sicoob.

Parameters:

oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação
sandbox_mode (bool) – Se True, usa ambiente de sandbox (default: False)

BASE_URL: URL da API de produção

SANDBOX_BASE_URL: URL da API de sandbox

TOKEN_URL: URL para obtenção de token OAuth2

SCOPES: Scopes necessários para autenticação

BASE_URL: str | None = 'https://api.sicoob.com.br/pix/api/v2'

SANDBOX_BASE_URL = 'https://sandbox.sicoob.com.br/sicoob/sandbox/pix/api/v2'

TOKEN_URL: str | None = 'https://auth.sicoob.com.br/auth/realms/cooperado/protocol/openid-connect/token'

get_bank_code()[source]

Return type:: str

get_base_url()[source]

Obtém a URL base da API de acordo com o modo de operação.

Returns:: URL base da API (produção ou sandbox)
Return type:: str

Note

O modo sandbox é controlado pelo parâmetro sandbox_mode passado no construtor

exception pypix_api.APIError(message, status_code=None, response_body=None, **kwargs)[source]

Bases: PIXError

Raised when API call fails.

__init__(message, status_code=None, response_body=None, **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

exception pypix_api.AuthenticationError(message='Authentication failed', **kwargs)[source]

Bases: PIXError

Raised when authentication fails.

__init__(message='Authentication failed', **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

class pypix_api.MetricsCollector[source]

Bases: object

Coletor central de metricas.

__init__()[source]: Initialize metrics collector.

static __new__(cls)[source]: Singleton pattern for metrics collector.

clear_metrics()[source]

Clear all collected metrics.

Return type:: None

flush_metrics(export_path=None)[source]

Flush metrics to storage/export.

Return type:: bool

gauge(name, value, tags=None)[source]

Set a gauge metric value.

Return type:: None

get_summary()[source]

Get metrics summary.

Return type:: dict[str, Any]

histogram(name, value, tags=None)[source]

Record a histogram value.

Return type:: None

increment(name, value=1, tags=None)[source]

Increment a counter metric.

Return type:: None

record_api_call(method, endpoint, status_code, response_time, bank, error=None)[source]

Record API call metrics.

Return type:: None

timing(name, duration, tags=None)[source]

Record timing metric in seconds.

Return type:: None

exception pypix_api.PIXError(message, error_code=None, details=None, cause=None)[source]

Bases: Exception

Base exception class for pypix-api errors.

__init__(message, error_code=None, details=None, cause=None)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code (str | None) – Machine-readable error code
details (dict[str, Any] | None) – Additional error context
cause (Exception | None) – Original exception that caused this error

__str__()[source]

String representation of error.

Return type:: str

to_dict()[source]

Convert error to dictionary representation.

Return type:: dict[str, Any]

class pypix_api.PIXLogger(name='pypix_api')[source]

Bases: object

Logger principal para operacoes PIX.

__init__(name='pypix_api')[source]

Initialize PIX logger.

static __new__(cls, name='pypix_api')[source]

Singleton pattern para loggers.

add_context(**kwargs)[source]

Add context to all subsequent log messages.

Return type:: None

clear_context()[source]

Clear logging context.

Return type:: None

critical(message, **kwargs)[source]

Log critical message.

Return type:: None

debug(message, **kwargs)[source]

Log debug message.

Return type:: None

error(message, **kwargs)[source]

Log error message.

Return type:: None

info(message, **kwargs)[source]

Log info message.

Return type:: None

warning(message, **kwargs)[source]

Log warning message.

Return type:: None

exception pypix_api.ValidationError(message='Validation failed', field=None, **kwargs)[source]

Bases: PIXError

Raised when data validation fails.

__init__(message='Validation failed', field=None, **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

pypix_api.configure_observability(config=None)[source]

Configure global observability settings.

pypix_api.get_metrics_summary()[source]

Get current metrics summary.

Return type:: dict[str, Any]

pypix_api.get_observability_status()[source]

Get current observability system status.

Return type:: dict[str, Any]

pypix_api.setup_logging(level='INFO', log_file=None, structured=False)[source]

Configure global logging for pypix-api.

Parameters:

level (str) – Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
log_file (str | None) – Optional file path for logging
structured (bool) – Use structured JSON logging

Return type:

PIXLogger

Returns:

Configured PIXLogger instance

Subpackages

pypix_api.scopes package

Submodules

pypix_api.error_handling module

Sistema avancado de tratamento de erros para pypix-api.

Este modulo fornece classes de erro especializadas, context managers para tratamento robusto de erros e utilitarios para debugging avancado.

exception pypix_api.error_handling.APIError(message, status_code=None, response_body=None, **kwargs)[source]

Bases: PIXError

Raised when API call fails.

__init__(message, status_code=None, response_body=None, **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

exception pypix_api.error_handling.AuthenticationError(message='Authentication failed', **kwargs)[source]

Bases: PIXError

Raised when authentication fails.

__init__(message='Authentication failed', **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

exception pypix_api.error_handling.AuthorizationError(message='Authorization failed', **kwargs)[source]

Bases: PIXError

Raised when authorization/permission fails.

__init__(message='Authorization failed', **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

exception pypix_api.error_handling.BankSpecificError(message, bank_code=None, bank_error_code=None, **kwargs)[source]

Bases: PIXError

Raised for bank-specific errors.

__init__(message, bank_code=None, bank_error_code=None, **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

exception pypix_api.error_handling.CertificateError(message='Certificate error', **kwargs)[source]

Bases: PIXError

Raised when certificate handling fails.

__init__(message='Certificate error', **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

exception pypix_api.error_handling.ConfigurationError(message='Configuration error', **kwargs)[source]

Bases: PIXError

Raised when configuration is invalid.

__init__(message='Configuration error', **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

class pypix_api.error_handling.ErrorContext(operation, context=None, handler=None, reraise=True)[source]

Bases: object

Context manager for robust error handling.

__init__(operation, context=None, handler=None, reraise=True)[source]

Initialize error context.

Parameters:

operation (str) – Name of operation being performed
context (dict | None) – Additional context for error handling
handler (ErrorHandler | None) – Custom error handler
reraise (bool) – Whether to reraise handled errors

__enter__()[source]: Enter error context.

__exit__(exc_type, exc_val, exc_tb)[source]: Handle any exception that occurred.

class pypix_api.error_handling.ErrorHandler(logger=None)[source]

Bases: object

Advanced error handler with logging and metrics integration.

__init__(logger=None)[source]

Initialize error handler.

classify_error(error, context=None)[source]

Classify a generic exception as a specific PIX error.

Return type:: PIXError

handle_error(error, context=None, reraise=True)[source]

Handle an error with logging and metrics.

Return type:: PIXError | None

class pypix_api.error_handling.ErrorRecovery[source]

Bases: object

Utilities for error recovery and retry logic.

static should_retry(error, max_retries=3)[source]

Determine if an operation should be retried.

Return type:: bool

static get_retry_delay(attempt, base_delay=1.0)[source]

Calculate retry delay using exponential backoff.

Return type:: float

static retry_with_backoff(func, max_retries=3, base_delay=1.0, logger=None)[source]

Retry function with exponential backoff.

Return type:: Any

exception pypix_api.error_handling.NetworkError(message='Network communication failed', **kwargs)[source]

Bases: PIXError

Raised when network communication fails.

__init__(message='Network communication failed', **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

exception pypix_api.error_handling.PIXError(message, error_code=None, details=None, cause=None)[source]

Bases: Exception

Base exception class for pypix-api errors.

__init__(message, error_code=None, details=None, cause=None)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code (str | None) – Machine-readable error code
details (dict[str, Any] | None) – Additional error context
cause (Exception | None) – Original exception that caused this error

to_dict()[source]

Convert error to dictionary representation.

Return type:: dict[str, Any]

__str__()[source]

String representation of error.

Return type:: str

exception pypix_api.error_handling.PIXTransactionError(message, txid=None, operation=None, **kwargs)[source]

Bases: PIXError

Raised when PIX transaction fails.

__init__(message, txid=None, operation=None, **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

exception pypix_api.error_handling.RateLimitError(message='Rate limit exceeded', retry_after=None, **kwargs)[source]

Bases: PIXError

Raised when API rate limit is exceeded.

__init__(message='Rate limit exceeded', retry_after=None, **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

exception pypix_api.error_handling.ValidationError(message='Validation failed', field=None, **kwargs)[source]

Bases: PIXError

Raised when data validation fails.

__init__(message='Validation failed', field=None, **kwargs)[source]

Initialize PIX error.

Parameters:

message (str) – Human-readable error message
error_code – Machine-readable error code
details – Additional error context
cause – Original exception that caused this error

pypix_api.error_handling.create_error_report(error, include_system_info=True)[source]

Create comprehensive error report for debugging.

Return type:: dict[str, Any]

pypix_api.error_handling.handle_errors(operation, context=None, reraise=True, logger=None)[source]

Decorator for automatic error handling.

pypix_api.logging module

Sistema de logging estruturado para pypix-api.

Este modulo fornece funcionalidades de logging estruturado com suporte a diferentes formatos de saida, contexto e metricas de performance.

class pypix_api.logging.APICallLogger(logger=None)[source]

Bases: object

Logger especializado para chamadas de API.

__init__(logger=None)[source]

Initialize API call logger.

log_request(method, url, headers=None, body=None, **kwargs)[source]

Log API request with sanitized data.

Return type:: str

log_response(request_id, status_code, response_time, response_body=None, **kwargs)[source]

Log API response.

Return type:: None

class pypix_api.logging.PIXLogger(name='pypix_api')[source]

Bases: object

Logger principal para operacoes PIX.

static __new__(cls, name='pypix_api')[source]

Singleton pattern para loggers.

__init__(name='pypix_api')[source]

Initialize PIX logger.

add_context(**kwargs)[source]

Add context to all subsequent log messages.

Return type:: None

clear_context()[source]

Clear logging context.

Return type:: None

debug(message, **kwargs)[source]

Log debug message.

Return type:: None

info(message, **kwargs)[source]

Log info message.

Return type:: None

warning(message, **kwargs)[source]

Log warning message.

Return type:: None

error(message, **kwargs)[source]

Log error message.

Return type:: None

critical(message, **kwargs)[source]

Log critical message.

Return type:: None

class pypix_api.logging.StructuredFormatter(include_trace=True)[source]

Bases: Formatter

Formatador para logs estruturados em JSON.

__init__(include_trace=True)[source]

Initialize structured formatter.

Parameters:: include_trace (bool) – Include trace information in logs

format(record)[source]

Format log record as JSON.

Return type:: str

pypix_api.logging.log_authentication(client_id, scope, success, **kwargs)[source]

Log authentication attempt.

Return type:: None

pypix_api.logging.log_bank_operation(operation, bank, **kwargs)[source]

Log bank operation with context.

Return type:: None

pypix_api.logging.log_performance(logger=None, threshold=1.0)[source]

Decorator para medir e logar performance de funcoes.

Parameters:

logger (PIXLogger | None) – Logger instance to use
threshold (float) – Log warning if execution time exceeds threshold (seconds)

pypix_api.logging.log_pix_transaction(txid, operation_type, amount=None, **kwargs)[source]

Log PIX transaction with context.

Return type:: None

pypix_api.logging.setup_logging(level='INFO', log_file=None, structured=False)[source]

Configure global logging for pypix-api.

Parameters:

level (str) – Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
log_file (str | None) – Optional file path for logging
structured (bool) – Use structured JSON logging

Return type:

PIXLogger

Returns:

Configured PIXLogger instance

pypix_api.metrics module

Sistema de metricas e telemetria para pypix-api.

Este modulo coleta e reporta metricas de uso da biblioteca para monitoramento e otimizacao de performance.

class pypix_api.metrics.APICallMetric(method, endpoint, status_code, response_time, timestamp, bank, error=None)[source]

Bases: object

Metrica para chamadas de API.

method: str

endpoint: str

status_code: int

response_time: float

timestamp: datetime

bank: str

error: str | None = None

__init__(method, endpoint, status_code, response_time, timestamp, bank, error=None)

class pypix_api.metrics.MetricEntry(name, value, timestamp, tags=<factory>, unit='count')[source]

Bases: object

Entrada de metrica individual.

name: str

value: float

timestamp: datetime

tags: dict[str, str]

unit: str = 'count'

__init__(name, value, timestamp, tags=<factory>, unit='count')

class pypix_api.metrics.MetricsCollector[source]

Bases: object

Coletor central de metricas.

static __new__(cls)[source]: Singleton pattern for metrics collector.

__init__()[source]: Initialize metrics collector.

increment(name, value=1, tags=None)[source]

Increment a counter metric.

Return type:: None

gauge(name, value, tags=None)[source]

Set a gauge metric value.

Return type:: None

histogram(name, value, tags=None)[source]

Record a histogram value.

Return type:: None

timing(name, duration, tags=None)[source]

Record timing metric in seconds.

Return type:: None

record_api_call(method, endpoint, status_code, response_time, bank, error=None)[source]

Record API call metrics.

Return type:: None

get_summary()[source]

Get metrics summary.

Return type:: dict[str, Any]

flush_metrics(export_path=None)[source]

Flush metrics to storage/export.

Return type:: bool

clear_metrics()[source]

Clear all collected metrics.

Return type:: None

class pypix_api.metrics.PerformanceTracker(operation_name, tags=None)[source]

Bases: object

Context manager para tracking de performance.

__init__(operation_name, tags=None)[source]

Initialize performance tracker.

__enter__()[source]: Start tracking.

__exit__(exc_type, exc_val, exc_tb)[source]: End tracking and record metrics.

pypix_api.metrics.clear_metrics()[source]

Clear all metrics.

Return type:: None

pypix_api.metrics.export_metrics(file_path=None)[source]

Export metrics to file or console.

Return type:: bool

pypix_api.metrics.get_metrics_summary()[source]

Get current metrics summary.

Return type:: dict[str, Any]

pypix_api.metrics.timed_function(metric_name=None, tags=None)[source]

Decorator to automatically time function execution.

pypix_api.metrics.track_api_call(method, endpoint)[source]

Track API call performance.

Return type:: PerformanceTracker

pypix_api.metrics.track_bank_operation(bank, operation)[source]

Track bank operation performance.

Return type:: PerformanceTracker

pypix_api.observability module

Modulo de observabilidade integrado para pypix-api.

Este modulo combina logging, metricas e tratamento de erros em uma interface unificada para monitoramento completo da biblioteca.

class pypix_api.observability.HealthCheck[source]

Bases: object

Health check utilities for monitoring system status.

__init__()[source]: Initialize health check.

check_system_health()[source]

Perform comprehensive system health check.

Return type:: dict[str, Any]

class pypix_api.observability.ObservabilityConfig[source]

Bases: object

Configuracao centralizada de observabilidade.

__init__()[source]: Initialize observability configuration.

classmethod from_dict(config)[source]

Create configuration from dictionary.

Return type:: ObservabilityConfig

setup_global_observability()[source]: Setup global observability based on configuration.

class pypix_api.observability.ObservabilityMixin(*args, **kwargs)[source]

Bases: object

Mixin para adicionar observabilidade a classes da API.

__init__(*args, **kwargs)[source]

Initialize observability components.

observe_operation(operation, **context)[source]

Context manager for observing operations with full telemetry.

observe_api_call(method, url, **kwargs)[source]

Decorator/context for observing API calls.

pypix_api.observability.configure_observability(config=None)[source]

Configure global observability settings.

pypix_api.observability.create_observability_report()[source]

Create comprehensive observability report.

Return type:: dict[str, Any]

pypix_api.observability.get_observability_status()[source]

Get current observability system status.

Return type:: dict[str, Any]

pypix_api.observability.observable_method(operation_name=None, track_performance=True)[source]

Decorator para tornar metodos observaveis automaticamente.