| Name | django-oscarbot JSON |
| Version |
0.71
JSON |
| download |
| home_page | https://oscarbot.site/ |
| Summary | Django app for create Telegram bot |
| upload_time | 2024-11-16 11:13:38 |
| maintainer | None |
| docs_url | None |
| author | Oleg Maslov |
| requires_python | >=3.11 |
| license | Copyright (c) 2023 Oleg Maslov (https://oscar-studio.com/) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
django
telegram
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
asgiref
certifi
charset-normalizer
Django
idna
psycopg2-binary
python-dotenv
pytz
requests
sqlparse
urllib3
PyYAML
typing_extensions
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
from oscarbot.response import TGResponse
# TG Core from Oscar
> Telegram bot core only for webhooks way working
Telegram bot core, created in django style with routing and views(handlers) where you
can use included builders for menu or messages
## Installing / Getting started
This is package only for using with Django project.
```shell
pip install django-oscarbot
```
### Initial Configuration
In settings.py file you need to specify application for tg use:
```python
OSCARBOT_APPS = ['main']
# set Telegram api token in your env variables TELEGRAM_API_TOKEN
TELEGRAM_API_TOKEN = '1234567890:AaBbCcDd...'
# set Telegram api url in your env variables TELEGRAM_URL
TELEGRAM_URL = 'https://api.telegram.org/bot'
# set location Bot model
OSCARBOT_BOT_MODEL = 'oscarbot.Bot'
# set location Bot User model
OSCARBOT_BOT_USER_MODEL = 'oscarbot.User'
# set the location of the TextProcessor to process user messages
TELEGRAM_TEXT_PROCESSOR = 'your_app.text_processor.handler'
# set the text of the message that the bot will send if it does not understand how to process it (not required).
NOT_UNDERSTAND_MESSAGE = 'Sorry, I do not understand you.'
# set a menu for the message that the bot will send if it does not understand how to process it (not required).
NOT_UNDERSTAND_MENU = 'your_app.menus.your_menu' # Default - None
# whether to update the message when the bot does not understand how to process the user's message (not required).
NOT_UNDERSTAND_NEED_UPDATE = False # Default - False
# Whether to delete a message if the bot does not understand how to process a user's message (not required).
NOT_UNDERSTAND_IS_DELETE_MESSAGE = True # Default - False
# set Telegram message parse mode (not required):
TELEGRAM_PARSE_MODE = 'MARKDOWN' # Default - 'HTML'
```
In root urls add include urls from library:
```python
urlpatterns = [
path('', include('oscarbot.urls'))
...
]
```
Run django server and open [localhost:8000/admin/](http://localhost:8000/admin/) and create new bot,
at least fill bot token for testing ability
## Features
* User model
```python
from oscarbot.models import User
some_user = User.objects.filter(username='@maslov_oa').first()
```
* Menu and Buttons builder
```python
from oscarbot.menu import Menu, Button
button_list = [
Button(text='Text for callback', callback='/some_callback/'),
Button(text='Text for external url', url='https://oscarbot.site/'),
Button(text='Web app view', web_app='https://oscarbot.site/'),
]
menu = Menu(button_list)
```
* Message builder
```python
from oscarbot.shortcut import QuickBot
quick_bot = QuickBot(
chat=111111111,
message='Hello from command line',
token='token can be saved in DB and not required'
)
quick_bot.send()
```
* Application with routing and views(handlers):
[example application](https://github.com/oscarbotru/oscarbot/tree/master/example/)
* Command to add or update a bot in the database
```shell
python manage.py create_bot_db
```
* Long polling server for testing
```shell
python manage.py runbot
```
* Update messages available
```python
# TODO: work in progress
```
* Set webhook for bot
```shell
python manage.py setwh
```
* Messages log
```python
# TODO: work in progress
```
* Storage for text messages
Make template of file inside any application from OSCARBOT_APPS setting
```shell
python manage.py messages
```
Collect all controllers-function which includes in router files
```shell
python manage.py messagee --collect
```
Hard reset template messages (it will clear your entered text)
```shell
python manage.py messagee --force
```
Usage:
After collecting routers you need to text your messages in messages.yaml
You can skip message at all:
```python
def start(user):
return TGResponse()
```
Or you can create custom message alias and message inside of messages.yaml:
```yaml
messages:
start: Hi!
custom_message: This is custom Hi!
```
After that you can use custom message alias though # symbol:
```python
def start(user):
return TGResponse(message='#custom_message')
```
In case you need paste arguments you can use templates strings in yaml:
```yaml
messages:
start: Hi, {1}! Is is your {2}`th visit!
custom_message: This is custom Hi, {1}!
```
And in view:
```python
def start(user):
return TGResponse(text_args=['User Name', '10'])
```
or
```python
def start(user):
return TGResponse(
messge='#custom_message',
text_args=['User Name']
)
```
## Project Structure
```
Django-project
├── first_app/
├── second_app/
├── config/
├── main
│ ├── menus
│ │ ├── __init__.py
│ │ └── start_menu.py
│ ├── views
│ │ ├── __init__.py
│ │ └── start.py
│ ├── __init__.py
│ ├── actions.py
│ ├── admin.py
│ ├── app.py
│ ├── models.py
│ ├── router.py
│ └── text_processor.py
├ manage.py
├ requirements.txt
```
### Example menus/start_menu.py
```python
from oscarbot.menu import Button, Menu
def get_start_menu() -> Menu:
"""Get start menu."""
feedback_url = 'https://example.com'
buttons = [
Button('Home', callback='/start'),
Button('Page', callback='/my_router/'),
Button('Feedback', url=feedback_url),
]
return Menu(buttons)
```
### Example views/start.py
```python
from oscarbot.response import TGResponse
from main.actions import YOUR_ACTION
from main.menus import start_menu
from users.models import TGUser
def star(user: TGUser) -> TGResponse:
"""Home."""
user.clean_state() # clean want_action and state_information
user.want_action = YOUR_ACTION
user.save()
message = 'Welcome!'
menu = start_menu.get_start_menu()
return TGResponse(message, menu, need_update=False)
```
### Example actions.py
```python
from oscarbot.response import TGResponse
from main.menus import start_menu
from users.models import TGUser
YOUR_ACTION = 'main.action__your_action'
def action__your_action(user: TGUser, message: str) -> TGResponse:
"""Action."""
user.state_information = message # your logic
user.save()
message_response = 'Your message'
menu = start_menu.get_start_menu()
return TGResponse(message_response, menu, need_update=True, is_delete_message=True)
```
# Example models.py
```python
from django.contrib.auth.models import AbstractUser
from django.db import models
from oscarbot.models import BaseUser
NULLABLE = {'blank': True, 'null': True}
class User(AbstractUser):
"""User model."""
class Meta:
verbose_name = 'user'
verbose_name_plural = 'users'
class TGUser(BaseUser):
"""Telegram user."""
user = models.OneToOneField(User, models.SET_NULL, **NULLABLE, related_name='tg_user', verbose_name='user tg')
class Meta:
verbose_name = 'profile Telegram'
verbose_name_plural = 'profiles Telegram'
def __str__(self):
return f'{self.t_id}'
```
### Example router.py
```python
from oscarbot.router import route
from main.views import start
routes = [
route('/start', start),
]
```
### Example text_processor.py
```python
from oscarbot.response import TGResponse
from main.menus import start_menu
from users.models import TGUser
def handler(user: TGUser, message: dict) -> TGResponse:
"""Handler."""
message_response = 'Your message'
menu = start_menu.get_start_menu()
return TGResponse(message_response, menu)
```
## Links
- Project homepage: https://oscarbot.site/
- Repository: https://github.com/oscarbotru/oscarbot/
## Licensing
The code in this project is licensed under MIT license.
Raw data
{
"_id": null,
"home_page": "https://oscarbot.site/",
"name": "django-oscarbot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "django, telegram",
"author": "Oleg Maslov",
"author_email": "Oleg Maslov <info@oscar-studio.com>, Evgeniy Fedorin <revike@ya.ru>",
"download_url": "https://files.pythonhosted.org/packages/46/ca/9e677cb8d9da391bfd3d642dc1f4ab6f45ce6bbf85a5618c8528d0275d25/django_oscarbot-0.71.tar.gz",
"platform": null,
"description": "from oscarbot.response import TGResponse\n\n# TG Core from Oscar\n> Telegram bot core only for webhooks way working\n\nTelegram bot core, created in django style with routing and views(handlers) where you\ncan use included builders for menu or messages \n\n## Installing / Getting started\n\nThis is package only for using with Django project.\n\n```shell\npip install django-oscarbot\n```\n\n### Initial Configuration\n\nIn settings.py file you need to specify application for tg use:\n```python\nOSCARBOT_APPS = ['main']\n\n# set Telegram api token in your env variables TELEGRAM_API_TOKEN\nTELEGRAM_API_TOKEN = '1234567890:AaBbCcDd...'\n\n# set Telegram api url in your env variables TELEGRAM_URL\nTELEGRAM_URL = 'https://api.telegram.org/bot'\n\n# set location Bot model\nOSCARBOT_BOT_MODEL = 'oscarbot.Bot'\n\n# set location Bot User model\nOSCARBOT_BOT_USER_MODEL = 'oscarbot.User'\n\n# set the location of the TextProcessor to process user messages\nTELEGRAM_TEXT_PROCESSOR = 'your_app.text_processor.handler'\n\n# set the text of the message that the bot will send if it does not understand how to process it (not required).\nNOT_UNDERSTAND_MESSAGE = 'Sorry, I do not understand you.'\n\n# set a menu for the message that the bot will send if it does not understand how to process it (not required).\nNOT_UNDERSTAND_MENU = 'your_app.menus.your_menu' # Default - None\n\n# whether to update the message when the bot does not understand how to process the user's message (not required).\nNOT_UNDERSTAND_NEED_UPDATE = False # Default - False\n\n# Whether to delete a message if the bot does not understand how to process a user's message (not required).\nNOT_UNDERSTAND_IS_DELETE_MESSAGE = True # Default - False\n\n# set Telegram message parse mode (not required):\nTELEGRAM_PARSE_MODE = 'MARKDOWN' # Default - 'HTML'\n\n```\n\nIn root urls add include urls from library:\n```python\nurlpatterns = [\n path('', include('oscarbot.urls'))\n ...\n]\n```\n\nRun django server and open [localhost:8000/admin/](http://localhost:8000/admin/) and create new bot, \nat least fill bot token for testing ability\n## Features\n* User model\n```python\n\nfrom oscarbot.models import User\n\nsome_user = User.objects.filter(username='@maslov_oa').first()\n\n```\n\n* Menu and Buttons builder\n```python\nfrom oscarbot.menu import Menu, Button\n\n\nbutton_list = [\n Button(text='Text for callback', callback='/some_callback/'),\n Button(text='Text for external url', url='https://oscarbot.site/'),\n Button(text='Web app view', web_app='https://oscarbot.site/'),\n]\n\nmenu = Menu(button_list)\n\n```\n\n* Message builder\n```python\nfrom oscarbot.shortcut import QuickBot\n\nquick_bot = QuickBot(\n chat=111111111,\n message='Hello from command line',\n token='token can be saved in DB and not required'\n)\nquick_bot.send()\n```\n\n* Application with routing and views(handlers):\n\n [example application](https://github.com/oscarbotru/oscarbot/tree/master/example/)\n\n* Command to add or update a bot in the database\n```shell\npython manage.py create_bot_db\n```\n\n* Long polling server for testing\n```shell\npython manage.py runbot\n```\n\n* Update messages available\n```python\n# TODO: work in progress\n```\n\n* Set webhook for bot\n```shell\npython manage.py setwh\n```\n\n* Messages log\n```python\n# TODO: work in progress\n```\n\n* Storage for text messages\n\nMake template of file inside any application from OSCARBOT_APPS setting\n```shell\npython manage.py messages\n```\n\nCollect all controllers-function which includes in router files\n```shell\npython manage.py messagee --collect\n```\n\nHard reset template messages (it will clear your entered text)\n```shell\npython manage.py messagee --force\n```\nUsage:\nAfter collecting routers you need to text your messages in messages.yaml\n\nYou can skip message at all:\n```python\ndef start(user):\n return TGResponse()\n```\n\nOr you can create custom message alias and message inside of messages.yaml:\n```yaml\nmessages:\n start: Hi!\n custom_message: This is custom Hi!\n```\n\nAfter that you can use custom message alias though # symbol:\n```python\ndef start(user):\n return TGResponse(message='#custom_message')\n```\n\nIn case you need paste arguments you can use templates strings in yaml:\n```yaml\nmessages:\n start: Hi, {1}! Is is your {2}`th visit!\n custom_message: This is custom Hi, {1}!\n```\n\nAnd in view:\n```python\ndef start(user):\n return TGResponse(text_args=['User Name', '10'])\n```\n\nor \n```python\ndef start(user):\n return TGResponse(\n messge='#custom_message', \n text_args=['User Name']\n )\n```\n\n## Project Structure\n```\nDjango-project\n\u251c\u2500\u2500 first_app/\n\u251c\u2500\u2500 second_app/\n\u251c\u2500\u2500 config/\n\u251c\u2500\u2500 main\n\u2502 \u251c\u2500\u2500 menus\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2514\u2500\u2500 start_menu.py\n\u2502 \u251c\u2500\u2500 views\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2514\u2500\u2500 start.py\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 actions.py \n\u2502 \u251c\u2500\u2500 admin.py \n\u2502 \u251c\u2500\u2500 app.py \n\u2502 \u251c\u2500\u2500 models.py \n\u2502 \u251c\u2500\u2500 router.py\n\u2502 \u2514\u2500\u2500 text_processor.py\n\u251c manage.py\n\u251c requirements.txt\n```\n\n### Example menus/start_menu.py\n```python\nfrom oscarbot.menu import Button, Menu\n\n\ndef get_start_menu() -> Menu:\n \"\"\"Get start menu.\"\"\"\n feedback_url = 'https://example.com'\n buttons = [\n Button('Home', callback='/start'),\n Button('Page', callback='/my_router/'),\n Button('Feedback', url=feedback_url),\n ]\n return Menu(buttons)\n```\n\n### Example views/start.py\n```python\nfrom oscarbot.response import TGResponse\n\nfrom main.actions import YOUR_ACTION\nfrom main.menus import start_menu\nfrom users.models import TGUser\n\n\ndef star(user: TGUser) -> TGResponse:\n \"\"\"Home.\"\"\"\n user.clean_state() # clean want_action and state_information\n user.want_action = YOUR_ACTION\n user.save()\n message = 'Welcome!'\n menu = start_menu.get_start_menu()\n return TGResponse(message, menu, need_update=False)\n```\n\n### Example actions.py\n```python\nfrom oscarbot.response import TGResponse\n\nfrom main.menus import start_menu\nfrom users.models import TGUser\n\nYOUR_ACTION = 'main.action__your_action'\n\n\ndef action__your_action(user: TGUser, message: str) -> TGResponse:\n \"\"\"Action.\"\"\"\n user.state_information = message # your logic\n user.save()\n message_response = 'Your message'\n menu = start_menu.get_start_menu()\n return TGResponse(message_response, menu, need_update=True, is_delete_message=True)\n```\n\n# Example models.py\n```python\nfrom django.contrib.auth.models import AbstractUser\nfrom django.db import models\nfrom oscarbot.models import BaseUser\n\nNULLABLE = {'blank': True, 'null': True}\n\n\nclass User(AbstractUser):\n \"\"\"User model.\"\"\"\n\n class Meta:\n verbose_name = 'user'\n verbose_name_plural = 'users'\n\n\nclass TGUser(BaseUser):\n \"\"\"Telegram user.\"\"\"\n user = models.OneToOneField(User, models.SET_NULL, **NULLABLE, related_name='tg_user', verbose_name='user tg')\n\n class Meta:\n verbose_name = 'profile Telegram'\n verbose_name_plural = 'profiles Telegram'\n\n def __str__(self):\n return f'{self.t_id}'\n\n```\n\n### Example router.py\n```python\nfrom oscarbot.router import route\n\nfrom main.views import start\n\nroutes = [\n route('/start', start),\n]\n```\n\n### Example text_processor.py\n```python\nfrom oscarbot.response import TGResponse\n\nfrom main.menus import start_menu\nfrom users.models import TGUser\n\n\ndef handler(user: TGUser, message: dict) -> TGResponse:\n \"\"\"Handler.\"\"\"\n message_response = 'Your message'\n menu = start_menu.get_start_menu()\n return TGResponse(message_response, menu)\n```\n\n## Links\n\n- Project homepage: https://oscarbot.site/\n- Repository: https://github.com/oscarbotru/oscarbot/\n\n## Licensing\n\nThe code in this project is licensed under MIT license.\n",
"bugtrack_url": null,
"license": "Copyright (c) 2023 Oleg Maslov (https://oscar-studio.com/) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Django app for create Telegram bot",
"version": "0.71",
"project_urls": {
"Bug Reports": "https://github.com/oscarbotru/oscarbot/issues",
"Homepage": "https://github.com/oscarbotru/oscarbot"
},
"split_keywords": [
"django",
" telegram"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "871f9e52eaabc7681399f23d9f82a4e3be512fb858ec8b8c876355bf455a466a",
"md5": "2c70fa0f1bd00e73d3ab68c33dd63b23",
"sha256": "fe551eeec35d75afa91bac4a3d3b42925d4d77b4e907e0b7bdd65ede6c5d0b9f"
},
"downloads": -1,
"filename": "django_oscarbot-0.71-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c70fa0f1bd00e73d3ab68c33dd63b23",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 94817,
"upload_time": "2024-11-16T11:13:34",
"upload_time_iso_8601": "2024-11-16T11:13:34.826708Z",
"url": "https://files.pythonhosted.org/packages/87/1f/9e52eaabc7681399f23d9f82a4e3be512fb858ec8b8c876355bf455a466a/django_oscarbot-0.71-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "46ca9e677cb8d9da391bfd3d642dc1f4ab6f45ce6bbf85a5618c8528d0275d25",
"md5": "c6dd80468720526db2c425a01a510526",
"sha256": "21799a482e61592819abe2a209de76677ea2b869c762c443152d223509cb5faa"
},
"downloads": -1,
"filename": "django_oscarbot-0.71.tar.gz",
"has_sig": false,
"md5_digest": "c6dd80468720526db2c425a01a510526",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 67857,
"upload_time": "2024-11-16T11:13:38",
"upload_time_iso_8601": "2024-11-16T11:13:38.533727Z",
"url": "https://files.pythonhosted.org/packages/46/ca/9e677cb8d9da391bfd3d642dc1f4ab6f45ce6bbf85a5618c8528d0275d25/django_oscarbot-0.71.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-16 11:13:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oscarbotru",
"github_project": "oscarbot",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "asgiref",
"specs": [
[
"==",
"3.7.2"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2023.7.22"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.3.0"
]
]
},
{
"name": "Django",
"specs": [
[
"==",
"4.2.6"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.4"
]
]
},
{
"name": "psycopg2-binary",
"specs": [
[
"==",
"2.9.9"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "pytz",
"specs": [
[
"==",
"2023.3.post1"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "sqlparse",
"specs": [
[
"==",
"0.4.4"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.0.6"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
"==",
"4.12.2"
]
]
}
],
"lcname": "django-oscarbot"
}
