Metadata-Version: 2.4
Name: pimcord
Version: 0.6.9
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"
Requires-Dist: cryptography>=42; extra == "voz"
Requires-Dist: opuslib>=3.0; 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 0.6.5 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.

## Diferenciais próprios do Pimcord

O Pimcord não é apenas uma tradução de outra biblioteca. A API principal usa nomes em português, enquanto alguns aliases em inglês existem somente para compatibilidade opcional. O projeto inclui um simulador local de Gateway, mensagens e interações que funciona sem token, sem WebSocket e sem requisições externas, além de diagnóstico automático de configuração, intents, comandos, Views e saúde do Gateway.

```python
import pimcord

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

@bot.comando("ola")
async def ola(ctx):
    await ctx.responder("Olá pelo ambiente simulado")

# Em testes assíncronos:
# await simulador.iniciar()
# await simulador.mensagem("!ola")

relatorio = bot.diagnostico_saude()
print(relatorio.aprovado)
print(relatorio.para_dict())
```

O diagnóstico não expõe tokens e permite detectar problemas antes de conectar. O simulador registra eventos, mensagens e respostas para facilitar testes determinísticos, tutoriais offline e desenvolvimento em Pydroid ou Termux.

## Recursos disponíveis

A versão 0.6.5 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.5 cobre conexão Gateway, heartbeat, Identify, reconexão inicial, REST com tentativas, comandos prefixados, intents, eventos automáticos, slash commands básicos, follow-ups, respostas efêmeras, Views, moderação, simulador offline e diagnóstico de saúde. Ainda estão em expansão voz completa, supervisor distribuído de sharding, rate limits globais distribuídos e paridade integral com todos os recursos avançados do Discord. Esses limites são documentados sem simular recursos ausentes.

## Voz e áudio

O Pimcord agora possui a primeira camada de voz em português: `SessaoVoz`, `InformacoesVoz`, `PacoteRTP`, `TransporteUDP`, seleção de modo, heartbeat com `seq_ack`, construção de RTP e os atalhos `bot.entrar_em_voz()`, `bot.voz_do_servidor()` e `bot.sair_da_voz()`. O transporte é modular e aceita codec e criptografia por injeção, o que mantém a instalação leve em Pydroid e Termux.

Para habilitar os backends opcionais de áudio, use `python -m pip install "pimcord[voz]"`. Esse extra declara `PyNaCl`, `cryptography` e `opuslib`. A instalação básica não exige dependências nativas; XChaCha20/DAVE continuam exigindo um backend compatível específico e nunca são simulados.

```python
sessao = await bot.entrar_em_voz("ID_DO_SERVIDOR", "ID_DO_CANAL")
print(sessao.estado)
# await bot.sair_da_voz("ID_DO_SERVIDOR")
```

A camada de voz já é testada offline, com PCM/WAV, fila, RTP, IP Discovery, reconexão e cifras opcionais AES-GCM/XSalsa20. Opus depende do extra de voz; FFmpeg, DAVE/MLS e a recuperação completa de todas as fases do Voice Gateway continuam sendo marcos de implementação e não devem ser tratados como concluídos neste release.

## Tarefas, filas e extensões

O Pimcord inclui `Agendador`, `TarefaAgendada`, `PoliticaRetentativa` e `FilaAssincrona`. Esses componentes oferecem backoff, jitter, limite de fila, consumidores concorrentes, cancelamento e estatísticas sem exigir um serviço externo.

```python
agendador = pimcord.Agendador()
agendador.registrar("sincronizacao", sincronizar, intervalo=60).iniciar()

# Ou integrado ao ciclo de vida do Bot:
@bot.agendar("sincronizacao", intervalo=60)
async def sincronizar_periodicamente():
    ...

fila = pimcord.FilaAssincrona(limite=100)
```

Extensões podem declarar dependências, ser carregadas em lote, recarregadas com estado de saúde e revertidas quando um lote falhar por configuração inválida. O Bot expõe `carregar_extensao`, `descarregar_extensao` e `recarregar_extensao` como operações portuguesas.

## Gerador assistido por IA e bot_pronto

O Pimcord possui uma IA integrada para transformar linguagem natural em um plano seguro de bot. A chamada principal não exige OpenAI nem outra biblioteca externa:

```python
import pimcord

bot = pimcord.bot_pronto("crie um bot de economia completo", iniciar=False)
```

Sem configuração de IA, o fallback local funciona offline para prompts comuns e pode gerar um projeto inicial completo. Para usar um endpoint compatível sem instalar SDK, configure `PIMCORD_IA_URL`, `PIMCORD_IA_CHAVE` e, opcionalmente, `PIMCORD_IA_MODELO`. A DSL declarativa anterior continua compatível:

Para criar arquivos, cogs, comandos híbridos, configuração, README e SQLite quando o prompt pedir economia, informe um diretório:

```python
bot = pimcord.bot_pronto(
    "crie um bot de economia completo",
    iniciar=False,
    diretorio="./meu_bot",
)
bot.rodar("SEU_TOKEN_REAL")
```

O projeto salvo contém `bot.py`, `cogs/geral.py`, `cogs/economia.py`, `.env.example` e configuração por ambiente. O token não é gravado nos arquivos.

```python
bot = pimcord.bot_pronto("""
Prefixo: !
Comando: ola
Resposta: Olá, mundo!
Aliases: oi
""", iniciar=False)
```

Para o gerador avançado opcional:

```python
from openai import OpenAI
import pimcord

gerador = pimcord.GeradorPlanoIA(OpenAI(), modelo="gpt-5-mini")
bot = pimcord.bot_pronto("Crie um bot de saudação com ola e ajuda.", gerador=gerador, iniciar=False)
```

O contrato completo, o schema e as limitações estão em [`docs/IA_E_BOT_PRONTO.md`](docs/IA_E_BOT_PRONTO.md).

Para uma descrição livre, como “crie um bot de economia completo”, use o gerador de projeto. Ele gera arquivos em uma pasta, valida a árvore e não executa nada automaticamente:

```python
import os
import pimcord
from openai import OpenAI

projeto = pimcord.criar_projeto_ia(
    "Crie um bot de economia completo com saldo, diária, ranking e SQLite local.",
    OpenAI(),
    "./economia_bot",
)
# Revise os arquivos antes de executar.
projeto.executar("./economia_bot", token=os.environ["DISCORD_TOKEN"])
```

A função bloqueia traversal, Python inválido, `eval`, `exec`, imports perigosos e segredos literais. A execução é explícita e o token fica fora do prompt e dos arquivos.

## Testes

```bash
python -m pytest
```

## Licença

MIT. Consulte `LICENSE`.


## Release 0.6.5

A versão 0.6.5 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 e autocomplete avançado devem ser considerados etapas posteriores, não recursos já concluídos. O simulador offline e o diagnóstico de saúde já estão disponíveis.


## APIs do marco 0.6.5

O release 0.6.5 adiciona uma camada mais expressiva para projetos novos. `Intents.todos()` e `Intents.all()` permitem solicitar todos os intents modelados; `@bot.evento` pode inferir o evento pelo nome da função; e `@bot.comando_hibrido(...)` registra um único callback para prefixo e slash.

```python
@bot.comando_hibrido("perfil", descricao="Mostra o perfil")
async def perfil(ctx):
    await ctx.responder(f"Perfil de {ctx.autor}")
```

Interações também podem ser adiadas, responder com View, usar follow-ups e editar ou apagar a resposta original:

```python
@bot.comando_slash("processar", descricao="Processa uma tarefa")
async def processar(interacao):
    await interacao.adiar(ephemeral=True)
    await interacao.editar_resposta("Processamento concluído.")
    await interacao.followup("Resultado disponível.", ephemeral=True)
```

O repositório inclui exemplos em `exemplos/`, testes sem rede externa, matriz de arquitetura, changelog, workflow de CI e política de segurança. A implementação continua declarando limites: voz completa, supervisor distribuído de sharding, cobertura integral de eventos e paridade total com todas as APIs de bibliotecas externas permanecem áreas de expansão.


> **Status da distribuição 0.6.5:** este arquivo é um build experimental para testes e feedback. A interoperabilidade DAVE/MLS e a observação completa de Voice Gateway/UDP ainda estão em validação; não use esta nota como alegação de superioridade comprovada em relação a outras bibliotecas.
