gates-sdk 0.1.4

SDK em Python para integrar com o Gates para autenticação via Cognito e gestão de usuários

Gates SDK (Python)

SDK em Python para autenticação de usuários com tokens JWT do AWS Cognito e integração com o backend do Gates para gerenciamento de perfis. Estruturado para publicação no PyPI.

Características

• ✅ Autenticação com tokens JWT do AWS Cognito
• ✅ Validação de grupos de usuários
• ✅ Cache automático de chaves públicas
• ✅ Cliente HTTP assíncrono para API do Gates
• ✅ Suporte a profiles de usuário personalizados
• ✅ Tratamento robusto de erros
• ✅ Type hints completos
• ✅ Testes unitários abrangentes

Instalação

pip install gates-sdk

Instalação para desenvolvimento

# Clone o repositório
git clone https://github.com/intelicity/gates-python-sdk.git
cd gates-python-sdk

# Crie um ambiente virtual
python -m venv venv

# Ative o ambiente virtual (Windows)
venv\Scripts\activate
# ou Linux/Mac:
# source venv/bin/activate

# Instale em modo de desenvolvimento
pip install -e ".[dev]"

Uso

Autenticação

from gates_sdk import AuthService

auth = AuthService(
    region="sa-east-1",
    user_pool_id="sa-east-1_xxxxxxxxx",
    audience="your-client-id",
    required_group=["admin", "user"],  # opcional
)

try:
    user = auth.verify_token(token)
    print("Usuário autenticado", user)
    print("É membro do grupo?", auth.is_member_of(user.groups or []))
except Exception as exc:
    print("Falha ao autenticar:", exc)

Serviço de usuários

from gates_sdk import UserService

user_service = UserService(
    base_url="https://api.example.com",
    system="your-system-name",
)

users = user_service.get_all_users(id_token)
print(users.profiles, users.total)

profile = user_service.get_profile(id_token)
print(profile)

Variáveis de ambiente

export GATES_REGION=sa-east-1
export GATES_USER_POOL_ID=sa-east-1_xxxxxxxxx
export GATES_CLIENT_ID=your-cognito-client-id
export GATES_BACKEND_URL=https://your-backend-api.com
export GATES_SYSTEM_NAME=your-system-name

Também é possível instanciar os serviços lendo essas variáveis com os.getenv.

Desenvolvimento

Configuração inicial

# Instalar dependências de desenvolvimento
pip install -e ".[dev]"

# Configurar pre-commit hooks (opcional)
pre-commit install

Comandos úteis

# Executar testes
pytest

# Testes com cobertura
pytest --cov=src --cov-report=html

# Formatação de código
black src tests
isort src tests

# Verificar formatação sem modificar
black --check src tests
isort --check-only src tests

# Lint
flake8 src tests

# Verificação de tipos
mypy src

# Executar todas as verificações
pytest && black --check src tests && isort --check-only src tests && flake8 src tests && mypy src

Usando o Makefile (Linux/Mac)

make help          # Mostra todos os comandos disponíveis
make install-dev    # Instala dependências de desenvolvimento
make test          # Executa testes
make format        # Formata código
make check         # Executa todas as verificações
make build         # Constrói o pacote
make upload-test   # Publica no TestPyPI

Usando o script PowerShell (Windows)

# Publicar no TestPyPI
.\publish.ps1 -Target test

# Publicar no PyPI (produção)
.\publish.ps1 -Target prod

# Pular testes durante publicação
.\publish.ps1 -SkipTests

# Forçar publicação sem confirmação
.\publish.ps1 -Force

Estrutura do projeto

gates-python-sdk/
├── src/
│   ├── __init__.py          # Exports principais
│   ├── auth.py              # Serviço de autenticação
│   ├── cache.py             # Sistema de cache
│   ├── errors.py            # Exceções customizadas
│   ├── models.py            # Modelos de dados
│   ├── user.py              # Serviço de usuários
│   └── py.typed             # Marcador de type hints
├── tests/
│   ├── test_auth.py         # Testes de autenticação
│   ├── test_cache.py        # Testes de cache
│   └── test_user.py         # Testes de usuários
├── .github/workflows/       # GitHub Actions
├── pyproject.toml          # Configuração do projeto
├── CHANGELOG.md            # Histórico de mudanças
├── LICENSE                 # Licença MIT
├── MANIFEST.in             # Arquivos para incluir no pacote
├── Makefile               # Comandos para Unix/Linux
├── publish.ps1            # Script de publicação para Windows
├── publish.py             # Script de publicação Python
└── README.md              # Este arquivo

Publicação

1. Atualizar versão em pyproject.toml
2. Atualizar CHANGELOG.md
3. Executar testes: pytest
4. Testar no TestPyPI: .\publish.ps1 -Target test
5. Publicar no PyPI: .\publish.ps1 -Target prod

Testes

O projeto inclui testes unitários abrangentes:

# Executar todos os testes
pytest

# Executar com cobertura
pytest --cov=src

# Executar testes específicos
pytest tests/test_auth.py

# Executar com output verboso
pytest -v

Integração Contínua

O projeto está configurado com GitHub Actions para:

• ✅ Testes automatizados em Python 3.9-3.12
• ✅ Verificação de formatação e lint
• ✅ Verificação de tipos com mypy
• ✅ Build e verificação do pacote
• ✅ Publicação automática no PyPI via releases

Requisitos

• Python ≥ 3.9
• pyjwt[crypto] ≥ 2.8
• httpx ≥ 0.27

Licença

MIT - veja o arquivo LICENSE para detalhes.

Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -am 'Adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request

Suporte

Para questões e suporte, abra uma issue no GitHub.