{"id":16243671,"url":"https://github.com/mhthies/qaqabot","last_synced_at":"2026-03-07T07:32:35.342Z","repository":{"id":95230872,"uuid":"259051420","full_name":"mhthies/QAQAbot","owner":"mhthies","description":"Telegram bot for playing the question-answer-question-answer party game in Telegram.","archived":false,"fork":false,"pushed_at":"2020-07-19T16:38:23.000Z","size":858,"stargazers_count":5,"open_issues_count":17,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T05:24:52.054Z","etag":null,"topics":["cherrypy","games","python","sqlalchemy","telegram-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mhthies.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-26T14:30:29.000Z","updated_at":"2024-01-16T16:26:29.000Z","dependencies_parsed_at":"2023-07-24T10:30:19.496Z","dependency_job_id":null,"html_url":"https://github.com/mhthies/QAQAbot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mhthies/QAQAbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhthies%2FQAQAbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhthies%2FQAQAbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhthies%2FQAQAbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhthies%2FQAQAbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mhthies","download_url":"https://codeload.github.com/mhthies/QAQAbot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhthies%2FQAQAbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30209731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cherrypy","games","python","sqlalchemy","telegram-bot"],"created_at":"2024-10-10T14:15:51.761Z","updated_at":"2026-03-07T07:32:35.328Z","avatar_url":"https://github.com/mhthies.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Telegram Question-Answer-Question-Answer game bot\n\nA Telegram bot for playing the question-answer-question-answer party game, written in Python 3 and based on the *Python Telegram Bot*, *SQLAlchemy* and *CherryPy* libraries.\n\n## The Game / Features\n\nThe original game is played with pen and paper:\nEach player gets a sheet of paper and writes down an arbitrary question.\nThen, they pass the sheet to the next player, who writes down an answer to the question and fold the sheet to hide the original question.\nThe sheet is passed on to the next player, the task of whom is to find a question that is answered by the given answer.\nIt might be the original question or not.\nSometimes not even close—nobody knows until the end of the game.\nThe sheet is folded again and the next player has to answer the new question—without knowing the previous questions and answers.\n\nAs soon as one of the sheets is full of questions and answers or the players no longer want to go on, all sheets are finished by making sure they end with an answer.\nThen, the folding opened up, so everyone can enjoy the amusing chains of questions and answers.\n\nTo play this game in Telegram chats, this bot can be added to any number of Telegram groups.\nIn each group, a game can be created (`/newgame`) and joined by multiple group members (`/join`).\nEach player must also start a private chat with the bot.\n\nWhen the game is started (`/start_game`), the bot asks every player privately for a question.\nThe player answer with their question and the bot passes it privatly to the next player.\nIf the next player is still working on his previous sheet, all incoming sheets are queued.\nThis way, a player may also play several games in parallel—they are still always asked for one sheet at a time.\n\nThe bot supports synchronous and asynchronous games:\nIn a synchronous game (default and `/set_synchronous`), the sheets are not passed on to the next player until all players have finished writing their question/answer.\nIn an asynchronous game, the sheets are immediately passed on to the next player—as long as they are not busy with another sheet.\n\nWhen the game is finished—either when the target number of rounds (number of players or `/set_rounds`) is reached or when manually stopped (`/stop_game`, `/immediately_stop_game`)—, the virtual sheets are presented via a web server.\n\n## Architecture\n\nThe bot is built on the *SQLAlchemy* ORM framework.\nThe object-relational datamodel is defined in `qaqa_bot.model`.\n\nThe full business logic is contained in `qaqa_bot.game`, encapsulated in the `GameServer` class.\nAn instance of this class holds the game config, a database `sessionmaker` to generate individual database sessions, as well as a way to send outgoing messages (in the form of a callback function).\nIt provides specific methods for all interaction events that update the game state in the database and send messages as required.\n\nThe interaction with Telegram is provided by the `quqa_bot.bot` module, using the *Python Telegram Bot* library.\nInstances of its `Frontend` class hold an `Updater` object to interact with the Telegram API and an `GameServer` object to do the game logic.\nThe class has different handlers for any kind of Telegram update (esp. commands and text messages), that are automatically registered with the *Updater* on initialization and use the *GameServer's* interaction methods to carry out the actions.\n\nIn addition, a web server is included for serving the resulting sheets of finished games.\n(We first tried to deliver them as messages to the group chat, which unfortunately triggered Telegrams flood prevention reproducibly.)\nThe web frontend is built with the CherryPy web framework and its included WSGI web server.\nIn the `qaqa_bot.web` module, the Controller classes with endpoint handlers are defined.\nThe HTML templates are rendered with *Mako* and are located in `qaqa_bot/templates/`.\n\nIncoming updates from the Telegram API (esp. incoming messages) are handled either by the Frontend on its own or with help of the GameServer:\nTypically, response messages that do not require interaction with the database, are sent by the Frontend immediately.\n(It may use the GameServer's `get_translations()` or `translate_string()` methods to get the correct translation according to the chat's preferred language.) \nIn the other case, the Frontend's handler method identifies the correct game action, determines the action's arguments from the update data, and calls the respective method of the GameServer.\nThe response message/s are sent by the GameServer.\n\nWe use Alembic to manage database migrations.\nTo allow easy packaging and automatic migrations (see *Deployment* instructions below), the database versions are stored in `qaqa_bot/database_versions/`.\nHowever, you can still use the alembic cli tool normally. \n\n\n## Deployment\n\n### Prerequisites\n\nFor running this bot, a Python 3 environment (\u003e= Python 3.6) with the dependencies (see `requirements.txt`) installed is required.\nIt is recommended to use a virtualenv environment for easier management and updating of dependencies. \n\nAdditionally, a database in one of the DBMS supported by SQLAlchemy is required, including the appropriate Python driver library. \nSee https://docs.sqlalchemy.org/en/13/dialects/index.html for a list of supported database systems and instructions.\n\nFor a small installation, development and testing, an SQLite database is sufficient, which can be run with Python's integrated SQLite support.\nFor this purpose, use `sqlite:////path/to/your/database.db` as database connection string in the bot's `config.toml`.\nHowever, we recommend to use a proper™ database server for production use.\n\nFor the web frontend, an HTTP reverse proxy with HTTPS support should be configured, which makes the internal HTTP port publicly available.\nTypically, one would chose Apache (with a `ProxyPass` directive) or Nginx (with a `proxy_pass` command) and configure a Let's Encrypt TLS certificate.\n\n\n### Setup\n\nCurrently, the easiest setup is to clone this Git Repository and run the `qaqa_bot` python module from within it.\nWe may add proper Python packaging later, to make installation via pip possible. \n\n1. clone and enter repository\n   ```bash\n   git clone https://gitea.nephos.link/michael/QAQABot.git\n   cd QAQABot/\n   ```\n2. setup virtualenv\n   ```bash\n   python3 -m virtualenv -p python3 venv\n   ```\n3. install requirements\n   ```bash\n   venv/bin/pip install -r requirements.txt\n   ```\n4. create a Telegram Bot account: follow the instructions at https://core.telegram.org/bots#creating-a-new-bot\n5. create `config.toml`\n   ```bash\n   cp config.example.toml config.toml\n   $EDITOR config.toml\n   ```\n   Insert\n   * the bot's username,\n   * the bot's API token (recived from the BotFather),\n   * your personal Telegram username (will be used in the bot's description and help texts), and\n   * the connection URL of your database.\n   * the public base URL of your web server (virtual host), which is used for links to the web frontend\n   * the internal HTTP listening port\n6. compile i18n message catalouges\n   ```bash\n   pybabel compile -d qaqa_bot/i18n/ -D qaqa_bot\n   ```\n\n### Running\n\nRun the following command in the repository directory: \n```bash\nvenv/bin/python -m qaqa_bot\n```\n\nAt startup, the database will be initialized or upgraded automatically.\nAdditionally, the Telegram bot will be configured using the Telegram API.\nTo avoid this behaviour, add `--no-init` to the run command.\n\nTo run the database and bot setup manually, use `--init-only`.\nYou may also run database migrations with Alembic for full control: `alembic upgrade head`.\n\n\n### Updating\n\nSimply update the git repository, comple the new translations and restart the bot for updating:\n```bash\ngit pull\nvenv/bin/pybabel compile -d qaqa_bot/i18n/ -D qaqa_bot\nvenv/bin/python -m qaqa_bot\n```\nAs explained above, the database and Telegram bot settings will be updated automatically at startup.\n\n\n## License\n\nThis project is released under the Terms of the Apache License v2.0. See `NOTICE` and `LICENSE` files for more\ninformation.\n\n\n## Development\n\nCreating a new database version:\n```bash\nalembic upgrade head\n# do changes to model.py\nalembic revision --autogenerate -m \"do data things\"\n# revisit qaqa_bot/database_versions/*_do_data_things.py\ngit add qaqa_bot/model.py qaqa_bot/database_versions\n```\n\nUpdating i18n translation files:\n```bash\npybabel extract -F babel.cfg -k \"GetText\" -k \"NGetText:1,2\" -o qaqa_bot.pot .\npybabel update -i qaqa_bot.pot -d qaqa_bot/i18n/ -D qaqa_bot\n```\n\nCompiling i18n translation files:\n```bash\npybabel compile -d qaqa_bot/i18n/ -D qaqa_bot\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhthies%2Fqaqabot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmhthies%2Fqaqabot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhthies%2Fqaqabot/lists"}