Infraestrutura comum (_core)

Core public API for mcp-fiscal-brasil.

Settings

Bases: BaseSettings

Runtime settings loaded from environment variables or a local .env file.

FiscalConfigurationError

FiscalConfigurationError(message, detail=None)

Bases: FiscalError

Exception raised when a required fiscal integration is not configured.

Distinct from FiscalValidationError (bad input) and FiscalHTTPError (upstream reachable but failed): this means the deployment itself is missing a prerequisite (e.g. no A1 certificate configured), not a request-level or upstream failure.

FiscalError

FiscalError(message, detail=None)

Bases: Exception

Base exception for fiscal domain failures.

FiscalHTTPError

FiscalHTTPError(message, status_code, url, detail=None)

Bases: FiscalError

Exception raised for HTTP failures from external fiscal services.

FiscalNotFoundError

FiscalNotFoundError(message, resource_type, identifier, detail=None)

Bases: FiscalError

Exception raised when a requested fiscal resource is not found.

FiscalRateLimitError

FiscalRateLimitError(message, retry_after=None, detail=None)

Bases: FiscalError

Exception raised when a fiscal service rate limit is reached.

FiscalValidationError

FiscalValidationError(message, field, value, detail=None)

Bases: FiscalError

Exception raised when an input value fails fiscal validation.

HTTPClient

HTTPClient(base_url, timeout=30.0, max_retries=3, cache_ttl=300, rate_limit_per_second=10, limiter=None)

Small async JSON client for external fiscal services.

aclose async

aclose()

Close the underlying HTTP client.

get async

get(path, params=None, headers=None)

Run a GET request and return the JSON object response.

get_list async

get_list(path, params=None, headers=None)

Run a GET request and return the JSON list response.

post async

post(path, json=None, headers=None)

Run a POST request and return the JSON object response.

get_logger

get_logger(name)

Return a configured structlog logger for the current runtime environment.

config

Application configuration for mcp-fiscal-brasil.

Settings

Bases: BaseSettings

Runtime settings loaded from environment variables or a local .env file.

errors

Shared fiscal error types.

FiscalError

FiscalError(message, detail=None)

Bases: Exception

Base exception for fiscal domain failures.

FiscalHTTPError

FiscalHTTPError(message, status_code, url, detail=None)

Bases: FiscalError

Exception raised for HTTP failures from external fiscal services.

FiscalRateLimitError

FiscalRateLimitError(message, retry_after=None, detail=None)

Bases: FiscalError

Exception raised when a fiscal service rate limit is reached.

FiscalValidationError

FiscalValidationError(message, field, value, detail=None)

Bases: FiscalError

Exception raised when an input value fails fiscal validation.

FiscalNotFoundError

FiscalNotFoundError(message, resource_type, identifier, detail=None)

Bases: FiscalError

Exception raised when a requested fiscal resource is not found.

FiscalConfigurationError

FiscalConfigurationError(message, detail=None)

Bases: FiscalError

Exception raised when a required fiscal integration is not configured.

Distinct from FiscalValidationError (bad input) and FiscalHTTPError (upstream reachable but failed): this means the deployment itself is missing a prerequisite (e.g. no A1 certificate configured), not a request-level or upstream failure.

http

Async HTTP client with retries, rate limiting and short lived GET caching.

HTTPClient

HTTPClient(base_url, timeout=30.0, max_retries=3, cache_ttl=300, rate_limit_per_second=10, limiter=None)

Small async JSON client for external fiscal services.

aclose async

aclose()

Close the underlying HTTP client.

get async

get(path, params=None, headers=None)

Run a GET request and return the JSON object response.

get_list async

get_list(path, params=None, headers=None)

Run a GET request and return the JSON list response.

post async

post(path, json=None, headers=None)

Run a POST request and return the JSON object response.

logging

Structured logging helpers for the MCP Fiscal Brasil package.

get_logger

get_logger(name)

Return a configured structlog logger for the current runtime environment.