#  Dicgram
Dicgram é um Framework simples para criação de bots para o Telegram em Python
## Instalação
`pip install dicgram` ou `python setup.py install`
O uso dele é bem simples, basta criar um arquivo principal e importar o Dicgram, e criar uma instância do Bot.
### Classe `Bot`
A classe `Bot` é a classe principal do módulo `dicgram.cliente`.
Ela é responsável por fazer a conexão com o Telegram e gerenciar os eventos.
Parâmetros:
* **token** (`str`) - O token do bot que você recebeu do BotFather.
* **polling** (`bool`, _opcional_) - Se o bot deve receber atualizações de novas mensagens. Padrão é `True`.
* **polling_rate** (`float` | `int`, _opcional_) - O tempo de espera, em segundos, para receber uma resposta do Telegram. Padrão é `0.5`.
* **webhook_url** (`str`, _opcional_) - A URL do webhook. Padrão é `None`.
* **webhook_port** (`int`, _opcional_) - A porta do server para o webhook. Padrão é `8000`.
### Comandos
Os comandos são criados em um dicionário, onde a chave é o comando e o valor é uma string
que será enviada como resposta ao comando enviado pelo usuário.
### Exemplo de uso básico
```python
from dicgram import Bot
bot = Bot('<TOKEN>')
# Responde aos comandos no privado
bot.privado = {
'/start': 'Olá, mundo! Eu sou um bot!',
'/help': 'Em que posso ajudar? :)',
}
# Responde aos comandos em canais e grupos
bot.publico = {
'/start': 'Olá, mundo! (publico)',
'/help': 'Em que posso ajudar, (publico)?',
}
# Usuário privado: /start
# Bot: Olá, mundo! Eu sou um bot!
# Usuário público: /start
# Bot: Olá, mundo! (publico)
# Usuário privado: /help
# Bot: Em que posso ajudar? :)
# Usuário público: /help
# Bot: Em que posso ajudar, (publico)?
````
Além disso, é possível criar comandos com parâmetros, que serão passados como argumentos para a função manipuladora.
### Exemplo de uso intermediário
```python
from dicgram import Bot
bot = Bot('<TOKEN>')
def soma(mim, msg, args):
return sum(map(int, args))
bot.privado = {
'/soma': soma,
}
# Usuário: /soma 1 2 3
# Bot: 6
# Usuário: /soma 1 2 3 4 5 6 7 8 9 10
# Bot: 55
# Usuário: /soma 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
# Bot: 210
```
Quer tornar seu bot mais dinâmico? Existem dois argumentos de fluxo opcionais para a função manipuladora, `mim` e `msg`.
O primeiro é um objeto da classe `Bot`, que contém informações do seu bot e métodos da API do Telegram para enviar mensagens, arquivos, etc.
O segundo é um objeto da classe `Mensagem`, que contém informações sobre a mensagem enviada pelo usuário,
como o ID do usuário, o nome do usuário, o ID do chat, o tipo do chat, etc.
### Exemplo de uso intermediário ||
```python
from dicgram import Bot
bot = Bot('<TOKEN>')
def consultar_cotacao(mim, msg, args):
if not args:
mim.send_message(chat_id=msg.from_user.id, text='Você precisa informar o nome da moeda.')
return 'Uma mensagem foi enviada para você no privado.'
moeda = args[0].upper()
if moeda not in ('USD', 'EUR', 'BTC'):
bot.send_message(chat_id=msg.from_user.id, text='Moeda inválida.')
return 'Enviei uma mensagem para você no privado.'
cotacao = {
'USD': 3.75,
'EUR': 4.20,
'BTC': 50000.00,
}[moeda]
return f'A cotação do {moeda} é {cotacao}.'
bot.privado['/start'] = 'Olá, mundo! Eu sou um bot!'
bot.publico['/cotacao'] = consultar_cotacao
# Usuário público: /cotacao
# Bot privado: Você precisa informar o nome da moeda.
# Bot público: Uma mensagem foi enviada para você no privado.
# Usuário público: /cotacao usd
# Bot publico: A cotação do USD é 3.75.
# Usuário público: /cotacao xyz
# Bot privado: Moeda inválida.
# Bot público: Enviei uma mensagem para você no privado.
# Usuário privado: /start
# Bot: Olá, mundo! Eu sou um bot!
```
Tem certos momentos em que você quer que o bot responda a uma mensagem específica, sem que seja necessário um comando.
Para isso, você pode usar chaves de eventos para o dicionário de comandos.
No momento, existem três chaves de eventos:
- `@mensagem`
- `@edit`
- `@chat`
A chave `@mensagem` é usada para responder a eventos de mensagens novas.
A chave `@chat` é usada para responder a eventos do
que acontece no chat, como um novo usuário entrando no grupo, um usuário saindo do grupo, etc.
A chave `@edit` é usada para
responder a eventos de mensagens editadas pelo usuário.
### Exemplo de uso avançado
```python
from dicgram import Bot
bot = Bot(token='<TOKEN>')
usuarios = {}
chat = None
def contador_de_mensagens(mim, msg, args):
global chat
chat = msg.chat.id
if msg.from_user.id not in usuarios:
usuarios[msg.from_user.id] = 1
else:
usuarios[msg.from_user.id] += 1
def mostrar_contagem(mim, msg, args):
if msg.from_user.id in usuarios:
nome = msg.from_user.first_name
return f'{nome}, você já mandou {usuarios[msg.from_user.id]} mensagens'
else:
return 'Você ainda não mandou nenhuma mensagem'
def desligar_contador(mim, msg, args):
mim.publico.pop('@mensagem', None)
usuarios.clear()
mim.send_message(chat_id=chat,
text='Pessoas, o contador de mensagens foi desligado pelo admin')
return 'Contador de mensagens desligado!'
bot.publico = {
'@mensagem': contador_de_mensagens,
'/contagem': mostrar_contagem,
}
bot.privado['/desligar'] = desligar_contador
# Usuário1 público: /contagem
# Bot público: Você ainda não mandou nenhuma mensagem
# Usuário1 público: Olá, mundo!
# Usuário1 público: /contagem
# Bot público: Dev, você já mandou 1 mensagens
# Usuário privdao: /desligar
# Bot privado: Contador de mensagens desligado!
# Bot público: Pessoas, o contador de mensagens foi desligado pelo admin
```
Os métodos da API do Telegram são acessados através da instância da classe `Bot`.
Por exemplo, o método send_message é acessado através de `bot.send_message`.
O nome dos métodos é o mesmo da API do Telegram, mas em snake_case.
A documentação da API do Telegram pode ser encontrada [aqui](https://core.telegram.org/bots/api#available-methods).
### Exemplo de uso de métodos da API do Telegram
```python
from dicgram import Bot
bot = Bot(token='<TOKEN>', update=False)
bot.set_chat_title(chat_id='<ID DO GRUPO>', title='Novo título do grupo')
bot.send_location(chat_id='<ID DO GRUPO>', latitude=-23.5505, longitude=-46.6333)
# etc...
```
### Projeto feito por [Marcelo](https://github.com/marcellobatiista)
* [Telegram](https://t.me/@SP4CNE)
### Licença
MIT License
Raw data
{
"_id": null,
"home_page": "https://github.com/marcellobatiista/dicgram",
"name": "dicgram",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "telegram chat messenger api client library python",
"author": "Marcelo Batista",
"author_email": "batista.marcelo34@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0f/36/9ffaf23232ee9544d692e6a125814a54ccbd81c1016c6b6291d2c898bf90/dicgram-2.1.2.tar.gz",
"platform": null,
"description": "#  Dicgram\n\nDicgram \u00e9 um Framework simples para cria\u00e7\u00e3o de bots para o Telegram em Python\n\n## Instala\u00e7\u00e3o \n\n`pip install dicgram` ou `python setup.py install`\n\nO uso dele \u00e9 bem simples, basta criar um arquivo principal e importar o Dicgram, e criar uma inst\u00e2ncia do Bot.\n\n### Classe `Bot`\n\nA classe `Bot` \u00e9 a classe principal do m\u00f3dulo `dicgram.cliente`.\nEla \u00e9 respons\u00e1vel por fazer a conex\u00e3o com o Telegram e gerenciar os eventos.\n\nPar\u00e2metros:\n\n* **token** (`str`) - O token do bot que voc\u00ea recebeu do BotFather.\n* **polling** (`bool`, _opcional_) - Se o bot deve receber atualiza\u00e7\u00f5es de novas mensagens. Padr\u00e3o \u00e9 `True`.\n* **polling_rate** (`float` | `int`, _opcional_) - O tempo de espera, em segundos, para receber uma resposta do Telegram. Padr\u00e3o \u00e9 `0.5`.\n* **webhook_url** (`str`, _opcional_) - A URL do webhook. Padr\u00e3o \u00e9 `None`.\n* **webhook_port** (`int`, _opcional_) - A porta do server para o webhook. Padr\u00e3o \u00e9 `8000`.\n\n\n### Comandos\n\nOs comandos s\u00e3o criados em um dicion\u00e1rio, onde a chave \u00e9 o comando e o valor \u00e9 uma string \nque ser\u00e1 enviada como resposta ao comando enviado pelo usu\u00e1rio.\n\n\n### Exemplo de uso b\u00e1sico\n\n```python\nfrom dicgram import Bot\n\nbot = Bot('<TOKEN>')\n\n# Responde aos comandos no privado\nbot.privado = {\n '/start': 'Ol\u00e1, mundo! Eu sou um bot!',\n '/help': 'Em que posso ajudar? :)',\n}\n\n# Responde aos comandos em canais e grupos\nbot.publico = {\n '/start': 'Ol\u00e1, mundo! (publico)',\n '/help': 'Em que posso ajudar, (publico)?',\n}\n\n# Usu\u00e1rio privado: /start \n# Bot: Ol\u00e1, mundo! Eu sou um bot!\n\n# Usu\u00e1rio p\u00fablico: /start\n# Bot: Ol\u00e1, mundo! (publico)\n\n# Usu\u00e1rio privado: /help\n# Bot: Em que posso ajudar? :)\n\n# Usu\u00e1rio p\u00fablico: /help\n# Bot: Em que posso ajudar, (publico)?\n````\n\nAl\u00e9m disso, \u00e9 poss\u00edvel criar comandos com par\u00e2metros, que ser\u00e3o passados como argumentos para a fun\u00e7\u00e3o manipuladora.\n\n### Exemplo de uso intermedi\u00e1rio\n\n```python\nfrom dicgram import Bot\n\nbot = Bot('<TOKEN>')\n\ndef soma(mim, msg, args):\n return sum(map(int, args))\n\nbot.privado = {\n '/soma': soma,\n}\n\n# Usu\u00e1rio: /soma 1 2 3\n# Bot: 6\n\n# Usu\u00e1rio: /soma 1 2 3 4 5 6 7 8 9 10\n# Bot: 55\n\n# Usu\u00e1rio: /soma 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20\n# Bot: 210\n```\n\nQuer tornar seu bot mais din\u00e2mico? Existem dois argumentos de fluxo opcionais para a fun\u00e7\u00e3o manipuladora, `mim` e `msg`.\n\nO primeiro \u00e9 um objeto da classe `Bot`, que cont\u00e9m informa\u00e7\u00f5es do seu bot e m\u00e9todos da API do Telegram para enviar mensagens, arquivos, etc.\n\nO segundo \u00e9 um objeto da classe `Mensagem`, que cont\u00e9m informa\u00e7\u00f5es sobre a mensagem enviada pelo usu\u00e1rio,\ncomo o ID do usu\u00e1rio, o nome do usu\u00e1rio, o ID do chat, o tipo do chat, etc. \n\n\n### Exemplo de uso intermedi\u00e1rio ||\n\n```python\nfrom dicgram import Bot\n\nbot = Bot('<TOKEN>')\n\ndef consultar_cotacao(mim, msg, args):\n if not args:\n mim.send_message(chat_id=msg.from_user.id, text='Voc\u00ea precisa informar o nome da moeda.')\n return 'Uma mensagem foi enviada para voc\u00ea no privado.'\n\n moeda = args[0].upper()\n if moeda not in ('USD', 'EUR', 'BTC'):\n bot.send_message(chat_id=msg.from_user.id, text='Moeda inv\u00e1lida.')\n return 'Enviei uma mensagem para voc\u00ea no privado.'\n\n cotacao = {\n 'USD': 3.75,\n 'EUR': 4.20,\n 'BTC': 50000.00,\n }[moeda]\n\n return f'A cota\u00e7\u00e3o do {moeda} \u00e9 {cotacao}.'\n\n\nbot.privado['/start'] = 'Ol\u00e1, mundo! Eu sou um bot!'\nbot.publico['/cotacao'] = consultar_cotacao\n\n\n# Usu\u00e1rio p\u00fablico: /cotacao\n# Bot privado: Voc\u00ea precisa informar o nome da moeda.\n# Bot p\u00fablico: Uma mensagem foi enviada para voc\u00ea no privado.\n\n# Usu\u00e1rio p\u00fablico: /cotacao usd\n# Bot publico: A cota\u00e7\u00e3o do USD \u00e9 3.75.\n\n# Usu\u00e1rio p\u00fablico: /cotacao xyz\n# Bot privado: Moeda inv\u00e1lida.\n# Bot p\u00fablico: Enviei uma mensagem para voc\u00ea no privado.\n\n# Usu\u00e1rio privado: /start\n# Bot: Ol\u00e1, mundo! Eu sou um bot!\n```\n\nTem certos momentos em que voc\u00ea quer que o bot responda a uma mensagem espec\u00edfica, sem que seja necess\u00e1rio um comando.\nPara isso, voc\u00ea pode usar chaves de eventos para o dicion\u00e1rio de comandos.\n\nNo momento, existem tr\u00eas chaves de eventos: \n\n - `@mensagem`\n - `@edit`\n - `@chat`\n\nA chave `@mensagem` \u00e9 usada para responder a eventos de mensagens novas.\n\nA chave `@chat` \u00e9 usada para responder a eventos do \nque acontece no chat, como um novo usu\u00e1rio entrando no grupo, um usu\u00e1rio saindo do grupo, etc. \n\nA chave `@edit` \u00e9 usada para \nresponder a eventos de mensagens editadas pelo usu\u00e1rio.\n\n### Exemplo de uso avan\u00e7ado\n\n```python\nfrom dicgram import Bot\n\nbot = Bot(token='<TOKEN>')\n\nusuarios = {}\nchat = None\n\n\ndef contador_de_mensagens(mim, msg, args):\n global chat\n chat = msg.chat.id\n\n if msg.from_user.id not in usuarios:\n usuarios[msg.from_user.id] = 1\n else:\n usuarios[msg.from_user.id] += 1\n\n\ndef mostrar_contagem(mim, msg, args):\n if msg.from_user.id in usuarios:\n nome = msg.from_user.first_name\n return f'{nome}, voc\u00ea j\u00e1 mandou {usuarios[msg.from_user.id]} mensagens'\n else:\n return 'Voc\u00ea ainda n\u00e3o mandou nenhuma mensagem'\n\n\ndef desligar_contador(mim, msg, args):\n mim.publico.pop('@mensagem', None)\n usuarios.clear()\n mim.send_message(chat_id=chat,\n text='Pessoas, o contador de mensagens foi desligado pelo admin')\n return 'Contador de mensagens desligado!'\n\n\nbot.publico = {\n '@mensagem': contador_de_mensagens,\n '/contagem': mostrar_contagem,\n}\nbot.privado['/desligar'] = desligar_contador\n\n# Usu\u00e1rio1 p\u00fablico: /contagem\n# Bot p\u00fablico: Voc\u00ea ainda n\u00e3o mandou nenhuma mensagem\n\n# Usu\u00e1rio1 p\u00fablico: Ol\u00e1, mundo!\n\n# Usu\u00e1rio1 p\u00fablico: /contagem\n# Bot p\u00fablico: Dev, voc\u00ea j\u00e1 mandou 1 mensagens\n\n# Usu\u00e1rio privdao: /desligar\n# Bot privado: Contador de mensagens desligado!\n# Bot p\u00fablico: Pessoas, o contador de mensagens foi desligado pelo admin\n```\n\nOs m\u00e9todos da API do Telegram s\u00e3o acessados atrav\u00e9s da inst\u00e2ncia da classe `Bot`.\nPor exemplo, o m\u00e9todo send_message \u00e9 acessado atrav\u00e9s de `bot.send_message`.\nO nome dos m\u00e9todos \u00e9 o mesmo da API do Telegram, mas em snake_case.\n\nA documenta\u00e7\u00e3o da API do Telegram pode ser encontrada [aqui](https://core.telegram.org/bots/api#available-methods).\n\n### Exemplo de uso de m\u00e9todos da API do Telegram\n\n```python\nfrom dicgram import Bot\n\n\nbot = Bot(token='<TOKEN>', update=False)\n\nbot.set_chat_title(chat_id='<ID DO GRUPO>', title='Novo t\u00edtulo do grupo')\nbot.send_location(chat_id='<ID DO GRUPO>', latitude=-23.5505, longitude=-46.6333)\n# etc...\n```\n\n### Projeto feito por [Marcelo](https://github.com/marcellobatiista)\n\n* [Telegram](https://t.me/@SP4CNE)\n\n### Licen\u00e7a\n\nMIT License\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Framework para criar bots do Telegram",
"version": "2.1.2",
"project_urls": {
"Homepage": "https://github.com/marcellobatiista/dicgram"
},
"split_keywords": [
"telegram",
"chat",
"messenger",
"api",
"client",
"library",
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d53fc9d7f86ad1fcd2327b67385e238ca1d31c272fae82e2134c17c2f589077a",
"md5": "a3a5972f24f3ea87f953ed8f7da1c3a4",
"sha256": "0b3d75732502834638d958af2edb1fa595a203d9991f4516e777158cdb05e513"
},
"downloads": -1,
"filename": "dicgram-2.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a3a5972f24f3ea87f953ed8f7da1c3a4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 11097,
"upload_time": "2023-12-02T23:01:04",
"upload_time_iso_8601": "2023-12-02T23:01:04.861106Z",
"url": "https://files.pythonhosted.org/packages/d5/3f/c9d7f86ad1fcd2327b67385e238ca1d31c272fae82e2134c17c2f589077a/dicgram-2.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0f369ffaf23232ee9544d692e6a125814a54ccbd81c1016c6b6291d2c898bf90",
"md5": "8048e80164a2f6a97721e46e3e9093d1",
"sha256": "59cd934049603bc1d474e789c763b51fa060c8b7bf47b2d205eab41cfb677db9"
},
"downloads": -1,
"filename": "dicgram-2.1.2.tar.gz",
"has_sig": false,
"md5_digest": "8048e80164a2f6a97721e46e3e9093d1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11120,
"upload_time": "2023-12-02T23:01:07",
"upload_time_iso_8601": "2023-12-02T23:01:07.375455Z",
"url": "https://files.pythonhosted.org/packages/0f/36/9ffaf23232ee9544d692e6a125814a54ccbd81c1016c6b6291d2c898bf90/dicgram-2.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-02 23:01:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "marcellobatiista",
"github_project": "dicgram",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "dicgram"
}
JSON
