ampere-core-sdk 0.1.1

SDK Python para Ampere Core (hexagonal: domain/application/infrastructure).

ampere-core-sdk

SDK Python (3.12+) para consumir a API Ampere Core.

---

DEVs

Sempre que iniciar o desenvolvimento rode

uv sync --dev
uv run pre-commit install
uv run pre-commit install --hook-type pre-push
uv run pre-commit install --hook-type pre-commit

# Teste inicial
uv run pre-commit run --all-files

---

Uso

1) Instalação

Via pip

pip install ampere-core-sdk

Via uv

uv add ampere-core-sdk

---

2) Conceitos

• A API usa tokens (access_token + refresh_token) com expiração.

• No login, o campo password deve ser enviado codificado (SHA-256 + base64url sem padding).

• O SDK tem:

  • AuthHttpAdapter / AsyncAuthHttpAdapter → faz login e refresh.
  • TokenManager → garante token válido (login/refresh sob demanda) e usa uma TokenStore (memória/arquivo/sua implementação).
  • Config HTTP com suporte a proxy e debug detalhado.

---

3) Configuração mínima (variáveis de ambiente)

Os exemplos e este README usam estas env vars:

• AMPERE_BASE_URL - A URL sempre será https://core.ampereconsultoria.com.br, apenas em casos de debug e testes que a URL pode ser alterada sob orientação da equipe de TI da Ampere Consultoria.
• AMPERE_USERNAME
• AMPERE_PASSWORD (senha crua; o exemplo transforma para o formato exigido)

Linux/macOS:

export AMPERE_BASE_URL="https://core.ampereconsultoria.com.br"
export AMPERE_USERNAME="seu-user"
export AMPERE_PASSWORD="sua-senha"

Windows (PowerShell):

$env:AMPERE_BASE_URL = "https://core.ampereconsultoria.com.br"
$env:AMPERE_USERNAME = "seu-user"
$env:AMPERE_PASSWORD = "sua-senha"

---

4) Uso

4.1 Login + Refresh (sync)

from ampere_core.config import AmpereCoreConfig
from ampere_core.infrastructure.iam.http import AuthHttpAdapter
from ampere_core.domain.iam.security.password_encoding import sha256_base64url

cfg = AmpereCoreConfig(base_url="https://core.ampereconsultoria.com.br")
auth = AuthHttpAdapter(config=cfg)

pair = auth.login(username="users", password=sha256_base64url("senha-crua"))
print(pair.expires_at)

pair2 = auth.refresh(refresh_token=pair.refresh_token)
print(pair2.expires_at)

4.2 TokenManager (refresh automático sob demanda)

O TokenManager é o modo recomendado: ele chama login/refresh quando precisa.

from ampere_core.application.iam.services import Credentials, TokenManager
from ampere_core.config import AmpereCoreConfig
from ampere_core.infrastructure.iam.http import AuthHttpAdapter
from ampere_core.infrastructure.iam.mock.in_memory_token_store import InMemoryTokenStore
from ampere_core.domain.iam.security.password_encoding import sha256_base64url

cfg = AmpereCoreConfig(base_url="https://core.ampereconsultoria.com.br")
auth_api = AuthHttpAdapter(config=cfg)
store = InMemoryTokenStore()

creds = Credentials(username="users", password=sha256_base64url("senha-crua"))
manager = TokenManager(auth_api=auth_api, store=store, credentials=creds)

headers = manager.auth_header()  # {"Authorization": "Bearer ..."}
print(headers)

---

5) Proxy corporativo

5.1 Via variáveis de ambiente (mais comum em empresas)

export HTTPS_PROXY="http://usuario:[e-mail]:3128"
export HTTP_PROXY="http://usuario:[e-mail]:3128"
export NO_PROXY="localhost,127.0.0.1,.empresa"

Por padrão trust_env=True, então funciona sem mudar código.

5.2 Proxy explícito no config

from ampere_core.config import AmpereCoreConfig, HttpClientOptions

cfg = AmpereCoreConfig(
    base_url="https://core.ampereconsultoria.com.br",
    http=HttpClientOptions(proxy="http://proxy.empresa:3128", trust_env=False),
)

---

6) Debug detalhado (sem vazar tokens)

O SDK tem logs HTTP no logger ampere_core.http com redaction de headers sensíveis.

import logging

from ampere_core.config import AmpereCoreConfig, HttpClientOptions, HttpDebugOptions
from ampere_core.infrastructure.iam.http import AuthHttpAdapter

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("ampere_core.http").setLevel(logging.DEBUG)

cfg = AmpereCoreConfig(
    base_url="https://core.ampereconsultoria.com.br",
    http=HttpClientOptions(
        debug=HttpDebugOptions(
            enabled=True,
            log_request_headers=True,
            log_request_body=False,
            log_response_headers=True,
            log_response_body=True,
            max_body_chars=2000,
        )
    ),
)

auth = AuthHttpAdapter(config=cfg)

---

7) Cliente httpx customizado (quando a empresa exige algo especial)

Se você precisa de CA corporativa, mTLS, proxy diferente, timeouts, transport custom, etc:

import httpx

from ampere_core.config import AmpereCoreConfig
from ampere_core.infrastructure.iam.http import AuthHttpAdapter

cfg = AmpereCoreConfig(base_url="https://core.ampereconsultoria.com.br")

with httpx.Client(
    base_url=cfg.base_url,
    timeout=cfg.timeout_seconds,
    trust_env=True,
    # verify="/path/ca_bundle.pem",
    # proxy="http://proxy.empresa:3128",
) as client:
    auth = AuthHttpAdapter(config=cfg, client=client)

---

8) Rodando os exemplos do repositório

uv run python examples/_01_auth_sync_basic.py
uv run python examples/_04_auth_sync_debug.py
uv run python examples/_06_token_manager_memory.py
uv run python examples/_08_auth_async_basic.py

8.1 Exemplos de Módulos (Nuvem, DI, etc)

# Cloud Manager
uv run python examples/cloud/_01_list_authentications.py

# Data Ingestion (DI)
uv run python examples/di/_00_create_json.py

# Dimensions
uv run python examples/dimensions/_01_list_dimensions.py

---

9) Documentação adicional

Autenticação e Tokens

• Cloud Manager
• Data Ingestion (DI)
• Dimensions
• FSARH (Recursos Hídricos)
• IAM (Identity & Access Management)
• Products (IPDO)
• Usinas