Metadata-Version: 2.4
Name: pimcord
Version: 0.6.0
Summary: Biblioteca assíncrona em português para bots Discord
Author: Projeto Pimcord
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4,>=3.9
Provides-Extra: testes
Requires-Dist: pytest>=8; extra == "testes"
Requires-Dist: pytest-asyncio>=0.23; extra == "testes"
Provides-Extra: voz
Requires-Dist: PyNaCl>=1.5; extra == "voz"
Dynamic: license-file

# Pimcord

Pimcord é uma biblioteca Python assíncrona, com API em português brasileiro, para construir bots Discord. Esta versão inicial contém um núcleo executável e extensível, sem copiar código de outras bibliotecas.

## Instalação local

Requer Python 3.11 ou superior. No diretório do projeto, execute:

```bash
python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install .
```

Para desenvolvimento e testes: `python -m pip install ".[testes]"`.

## Primeiro bot

```python
import pimcord

bot = pimcord.Bot(prefixo="!")

@bot.comando("ola", aliases=["oi"])
async def ola(ctx):
    await ctx.responder("Olá!")

@bot.evento("pronto")
async def pronto():
    print("Bot configurado.")

# Use DISCORD_TOKEN no ambiente; nunca salve o token no código.
bot.iniciar()
```

A versão atual já possui conexão real básica: consulta o Gateway, abre WebSocket, responde ao heartbeat, envia Identify, recebe `MESSAGE_CREATE`, processa comandos prefixados e responde pelo REST. Para ler o conteúdo das mensagens, ative **Message Content Intent** no Developer Portal do Discord e use `conteudo_mensagens=True`.

```python
import os
import pimcord

intents = pimcord.Intents(mensagens=True, conteudo_mensagens=True)
bot = pimcord.Bot(prefixo="!", intents=intents)

@bot.comando("ola")
async def ola(ctx):
    await ctx.responder("opa")

@bot.evento("pronto")
async def pronto():
    print("Bot online de verdade.")

bot.iniciar(os.environ["DISCORD_TOKEN"])
```

Antes de executar, crie uma aplicação e um Bot no [Discord Developer Portal](https://discord.com/developers/applications), copie o token para uma variável de ambiente e convide o bot para o servidor com os escopos `bot` e `applications.commands` e as permissões necessárias, incluindo enviar mensagens. Não publique nem compartilhe o token.

## Recursos disponíveis

A versão 0.2.0 implementa `Bot`, registro de comandos e aliases, conexão real básica com Gateway, heartbeat, Identify, eventos de mensagens, resposta REST, despacho de eventos, contexto, permissões por bitmask, intents, embeds serializáveis, botões e views básicos, cache em memória, tarefas periódicas, configuração por ambiente e banco SQLite. O manual detalhado está em `docs_GUIA_COMPLETO.md`.

```python
embed = pimcord.Embed(titulo="Status", descricao="Tudo certo", cor=0x5865F2)
embed.adicionar_campo("Versão", pimcord.__version__, inline=True)

banco = pimcord.BancoSQLite("dados.db")
banco.executar("CREATE TABLE IF NOT EXISTS notas (texto TEXT)")
banco.executar("INSERT INTO notas VALUES (?)", ["Olá"])
banco.commit()
```

## Limitações atuais

A conexão real básica cobre Gateway, heartbeat, Identify, eventos de mensagem, reconexão simples e envio de mensagens. Ainda faltam resume completo, tratamento detalhado de códigos de fechamento, rate limits globais e por bucket em produção, sincronização de slash commands, objetos completos de servidor/membro/canal, voz, webhooks e componentes interativos persistentes. Esses recursos não são simulados nem apresentados como funcionais.

## Testes

```bash
python -m pytest
```

## Licença

MIT. Consulte `LICENSE`.


## Superversão 0.4.0

A versão 0.4.0 adiciona uma base mais completa para projetos reais: argumentos tipados em comandos, checks, cooldowns, grupos e subcomandos, Views serializáveis com botões, extensões carregáveis, diagnóstico operacional, métricas de mensagens/comandos/eventos e uma CLI pública.

### CLI

Depois de instalar o pacote, use:

```bash
pimcord diagnostico
pimcord versao
pimcord novo meu-bot
```

O comando `novo` cria um projeto inicial com `bot.py`, `.env.example` e README.

### Checks e cooldowns

```python
import pimcord

bot = pimcord.Bot(prefixo="!")

@pimcord.verificar(lambda ctx: True)
@pimcord.limitar(chamadas=2, por=60)
@bot.comando("status")
async def status(ctx):
    await ctx.responder("Tudo certo")
```

### Grupos

```python
@bot.grupo("admin")
async def admin(ctx):
    pass

@admin.subcomando("limpar")
async def limpar(ctx, quantidade: int = 10):
    await ctx.responder(f"Limpando {quantidade}")
```

### Views e botões

```python
view = pimcord.View()

@view.botao("confirmar", texto="Confirmar", estilo="sucesso")
async def confirmar(interacao):
    await interacao.responder("Confirmado")

payload = view.para_componentes()
```

### Diagnóstico

```python
print(bot.diagnostico())
```

A biblioteca ainda está em evolução. Recursos como voz completa, sharding de produção, componentes persistentes após reinício, autocomplete avançado e modelos completos de todos os objetos Discord devem ser considerados etapas posteriores, não recursos já concluídos.
