sagace.core package — sagace 2025 documentation

# sagace.core package

## Subpackages

- sagace.core.storage package
  - Submodules
  - sagace.core.storage.file_storage module
    - Descrição:
    - `FileTokenStorage`
      - `FileTokenStorage._abc_impl`
      - `FileTokenStorage.get_token()`
      - `FileTokenStorage.save_token()`
  - sagace.core.storage.memory_storage module
    - Descrição:
    - `MemoryTokenStorage`
      - `MemoryTokenStorage._abc_impl`
      - `MemoryTokenStorage.get_token()`
      - `MemoryTokenStorage.save_token()`
  - sagace.core.storage.redis_storage module
    - Descrição:
    - `RedisTokenStorage`
      - `RedisTokenStorage._abc_impl`
      - `RedisTokenStorage.get_token()`
      - `RedisTokenStorage.save_token()`
  - Module contents
    - Description:

## 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)

  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)

    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)

  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

    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)

    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)

    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)

    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)

    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)

    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:

      - TokenExpiredError – Se o token estiver expirado.

      - PermissionDeniedError – Se o usuário não tiver permissão para acessar o recurso.

      - APIRequestError – Para quaisquer outros erros da API.

## 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')

  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

    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

  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

    Recupera o token armazenado.

    Returns:

      Instância do token armazenado.

    Return type:

      Token

  abstractmethod save_token(token: Token)

    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