sagace.core package

Subpackages

Submodules

sagace.core.api_client module


Descrição:

Este módulo define uma interface para clientes API autenticados dentro do sistema SAGACE. A classe APIClient fornece uma estrutura base para requisições autenticadas, garantindo que qualquer implementação específica siga um contrato comum.

Principais funcionalidades:

  • Gerenciamento da URL base da API.

  • Armazenamento e recuperação do token de autenticação.

  • Definição de um método abstrato para requisições autenticadas.

Classes:

  • APIClient: Interface para clientes autenticados.

Exemplo de uso:

from sagace.infrastructure.api_client import APIClient
from sagace.core import TokenStorage

class MyAPIClient(APIClient):
    def request(self, method: str, endpoint: str, **kwargs):
        # Implementação específica da requisição
        pass

api_client = MyAPIClient("https://api.sagace.online", TokenStorage())

Autor: Diego Yosiura Última Atualização: 27/02/2025 16:20 Criado em: 27/02/2025 16:20 Copyright: (c) Ampere Consultoria Ltda Projeto Original: sagace-v2-package IDE: PyCharm

class sagace.core.api_client.APIClient(base_url: str, token_storage: TokenStorage)[source]

Bases: ABC

Interface para clientes API autenticados.

Esta classe serve como base para a implementação de clientes API que necessitam de autenticação.

Princípios aplicados:

  • Liskov Substitution (L - SOLID): Qualquer classe que herde de APIClient deve poder ser utilizada sem alterar o comportamento esperado.

  • Dependency Inversion (D - SOLID): Depende da abstração de um armazenamento de tokens (TokenStorage).

Parameters:
  • base_url (str) – URL base da API.

  • token_storage (TokenStorage) – Instância responsável pelo armazenamento do token.

_abc_impl = <_abc._abc_data object>
abstractmethod request(method: str, endpoint: str, **kwargs)[source]

Realiza uma requisição autenticada à API.

Este método deve ser implementado pelas classes concretas que herdam de APIClient.

Parameters:
  • method (str) – Método HTTP a ser utilizado (GET, POST, etc.).

  • endpoint (str) – Caminho do endpoint na API.

  • kwargs – Parâmetros adicionais para a requisição.

Returns:

Resposta da API.

sagace.core.http_api_client module


Descrição:

Este módulo fornece uma implementação concreta de um cliente HTTP autenticado dentro do sistema SAGACE. A classe HTTPAPIClient herda de APIClient, garantindo que todas as requisições sejam autenticadas e sigam um contrato unificado.

Principais funcionalidades:

  • Realiza requisições HTTP autenticadas (GET, POST, PUT, DELETE).

  • Gerencia o armazenamento e recuperação do token JWT.

  • Lança exceções adequadas em caso de erro na API.

Classes:

  • HTTPAPIClient: Implementação concreta de APIClient utilizando requests.

Exemplo de uso:

from sagace.infrastructure.http_api_client import HTTPAPIClient
from sagace.core import TokenStorage

api_client = HTTPAPIClient("https://api.sagace.online", TokenStorage())
response = api_client.get("/usuario/dados")
print(response)

Autor: Diego Yosiura Última Atualização: 27/02/2025 16:30 Criado em: 27/02/2025 16:30 Copyright: (c) Ampere Consultoria Ltda Projeto Original: sagace-v2-package IDE: PyCharm

class sagace.core.http_api_client.HTTPAPIClient(base_url: str, token_storage: TokenStorage)[source]

Bases: APIClient

Implementação concreta de APIClient utilizando requests.

Esta classe fornece uma implementação real para comunicação com APIs via HTTP, garantindo que todas as requisições sejam autenticadas.

Princípios aplicados: - Liskov Substitution (L - SOLID): HTTPAPIClient pode ser utilizada no lugar de APIClient sem alterar o comportamento esperado. - Open/Closed (O - SOLID): A classe pode ser estendida para novos métodos HTTP sem modificação do código existente.

_abc_impl = <_abc._abc_data object>
_get_headers() dict[source]

Retorna os headers padrão com autenticação JWT.

Returns:

Dicionário de headers HTTP contendo o token JWT.

Return type:

dict

delete(endpoint: str, **kwargs)[source]

Método DELETE autenticado.

Parameters:
  • endpoint (str) – Caminho relativo dentro da API.

  • kwargs – Parâmetros adicionais para a requisição.

Returns:

Resposta JSON da API.

Return type:

dict

get(endpoint: str, **kwargs)[source]

Método GET autenticado.

Parameters:
  • endpoint (str) – Caminho relativo dentro da API.

  • kwargs – Parâmetros adicionais para a requisição.

Returns:

Resposta JSON da API.

Return type:

dict

post(endpoint: str, **kwargs)[source]

Método POST autenticado.

Parameters:
  • endpoint (str) – Caminho relativo dentro da API.

  • kwargs – Parâmetros adicionais para a requisição.

Returns:

Resposta JSON da API.

Return type:

dict

put(endpoint: str, **kwargs)[source]

Método PUT autenticado.

Parameters:
  • endpoint (str) – Caminho relativo dentro da API.

  • kwargs – Parâmetros adicionais para a requisição.

Returns:

Resposta JSON da API.

Return type:

dict

request(method: str, endpoint: str, **kwargs)[source]

Método genérico para requisições HTTP autenticadas.

Parameters:
  • method (str) – Método HTTP a ser utilizado (GET, POST, PUT, DELETE).

  • endpoint (str) – Caminho relativo dentro da API.

  • kwargs – Parâmetros adicionais para requests.request().

Returns:

Resposta JSON da API.

Return type:

dict

Raises:

sagace.core.token module


Descrição:

Este módulo define uma estrutura para gerenciamento de tokens de autenticação dentro do sistema SAGACE. A classe Token fornece um modelo estruturado para manipulação de tokens de acesso JWT.

Principais funcionalidades:

  • Armazena e gerencia informações sobre o token JWT.

  • Gera cabeçalhos de autenticação padronizados para requisições HTTP.

Classes:

  • Token: Representa um token de autenticação utilizado no sistema.

Exemplo de uso:

from sagace.core import Token

token = Token(
    base_url="https://api.sagace.online",
    access_token="abc123",
    application_name="Meu App",
    description="Token de acesso para integração."
)
headers = token.get_auth_header()
print(headers)

Autor: Diego Yosiura Última Atualização: 27/02/2025 15:30 Criado em: 27/02/2025 15:30 Copyright: (c) Ampere Consultoria Ltda Projeto Original: sagace-v2-package IDE: PyCharm

class sagace.core.token.Token(base_url: str, access_token: str, application_name: str, description: str, token_type: str = 'JWT')[source]

Bases: object

Representa um token de autenticação utilizado no sistema SAGACE.

A classe Token encapsula informações sobre tokens JWT, garantindo que as requisições API possuam autenticação padronizada.

Princípios aplicados: - Single Responsibility (S - SOLID): A classe é responsável apenas pelo gerenciamento de tokens. - Encapsulamento: Centraliza o controle dos tokens dentro da aplicação.

Parameters:
  • base_url (str) – URL base da API autenticada.

  • access_token (str) – Token de acesso JWT.

  • application_name (str) – Nome da aplicação associada ao token.

  • description (str) – Descrição do token.

  • token_type (str, optional) – Tipo do token (por padrão, JWT).

access_token: str
application_name: str
base_url: str
description: str
get_auth_header() dict[source]

Retorna um cabeçalho HTTP contendo o token de autenticação.

Este método é utilizado para garantir que todas as requisições HTTP realizadas dentro do sistema incluam a autenticação necessária.

Returns:

Dicionário contendo o cabeçalho de autorização.

Return type:

dict

token_type: str = 'JWT'

sagace.core.token_storage module


Descrição:

Este módulo define uma estrutura para gerenciamento de tokens de autenticação dentro do sistema SAGACE. A interface TokenStorage estabelece um contrato para armazenamento e recuperação de tokens de forma desacoplada, permitindo diferentes implementações conforme a necessidade do sistema.

Principais funcionalidades:

  • Definição de uma interface para armazenamento seguro de tokens de autenticação.

  • Permite a implementação de diferentes estratégias de persistência (memória, arquivos, banco de dados, etc.).

Princípios de Design Aplicados:

  • Single Responsibility Principle (SRP - SOLID): Cada classe tem uma única responsabilidade clara.

  • Open/Closed Principle (OCP - SOLID): A interface TokenStorage pode ser estendida sem modificar seu código-fonte.

  • Dependency Inversion Principle (DIP - SOLID): TokenStorage define uma abstração para armazenamento de tokens, permitindo que implementações concretas sejam facilmente substituídas.

Classes:

  • TokenStorage: Interface abstrata para armazenar e recuperar tokens.

Exemplo de uso:

from sagace.core import Token, TokenStorage

class MemoryTokenStorage(TokenStorage):
    # Implementação de TokenStorage que armazena o token em memória.
    def __init__(self):
        self._token = None

    def save_token(self, token: Token):
        self._token = token

    def get_token(self) -> Token:
        return self._token

token_storage = MemoryTokenStorage()
token = Token(
    base_url="https://api.sagace.online",
    access_token="abc123",
    application_name="Meu App",
    description="Token de acesso para integração."
)
token_storage.save_token(token)
retrieved_token = token_storage.get_token()
print(retrieved_token.get_auth_header())

Autor: Diego Yosiura Última Atualização: 27/02/2025 16:22 Criado em: 27/02/2025 16:22 Copyright: (c) Ampere Consultoria Ltda Projeto Original: sagace-v2-package IDE: PyCharm

class sagace.core.token_storage.TokenStorage[source]

Bases: ABC

Interface para armazenar e recuperar tokens de autenticação.

Essa classe define um contrato para qualquer implementação de armazenamento de tokens, permitindo diferentes abordagens, como armazenamento em memória, arquivos ou banco de dados.

Princípios aplicados: - Dependency Inversion (D - SOLID): Permite substituir implementações sem modificar consumidores da interface. - Open/Closed (O - SOLID): Pode ser estendida sem modificar o código existente.

_abc_impl = <_abc._abc_data object>
abstractmethod get_token() Token[source]

Recupera o token armazenado.

Returns:

Instância do token armazenado.

Return type:

Token

abstractmethod save_token(token: Token)[source]

Armazena o token de autenticação.

Parameters:

token (Token) – Token a ser armazenado.

Module contents


Description:

Obs.:

Author: @diego.yosiura Last Update: 27/02/2025 16:20 Created: 27/02/2025 16:20 Copyright: (c) Ampere Consultoria Ltda Original Project: sagace-v2-package IDE: PyCharm