Metadata-Version: 2.4
Name: pimcord
Version: 0.6.2
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

O release 0.6.2 já cobre conexão Gateway básica, heartbeat, Identify, reconexão inicial, REST com tentativas, comandos prefixados, intents completos, eventos automáticos, slash commands básicos, follow-ups, respostas efêmeras, Views e moderação de mensagens. Ainda estão em expansão o resume completo, a cobertura integral de eventos e modelos do Discord, rate limits globais distribuídos, voz, supervisor de sharding distribuído e compatibilidade total com todos os recursos avançados do discord.py. Esses limites são documentados sem simular recursos ausentes.

## Testes

```bash
python -m pytest
```

## Licença

MIT. Consulte `LICENSE`.


## Release 0.6.2

A versão 0.6.2 consolida a base de paridade do Pimcord: `Intents.all()` e `Intents.todos()`, eventos com `@bot.evento` sem parênteses, follow-ups de interações, respostas efêmeras, edição e exclusão da resposta original, Views com registro automático, canais e overwrites em português, histórico, purge e o alias `Mensagem.deletar()`. Também atualiza os metadados de empacotamento, o User-Agent REST e a instalação limpa do wheel.

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