{"id":18405735,"url":"https://github.com/pybites-open-source/karmabot","last_synced_at":"2025-04-04T08:05:21.622Z","repository":{"id":22377687,"uuid":"95367692","full_name":"PyBites-Open-Source/karmabot","owner":"PyBites-Open-Source","description":"A Python based Slack Chatbot for community interaction","archived":false,"fork":false,"pushed_at":"2025-03-06T03:34:21.000Z","size":631,"stargazers_count":74,"open_issues_count":11,"forks_count":45,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-04T07:36:17.564Z","etag":null,"topics":["bot","hacktoberfest","poetry","python","slack","slack-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PyBites-Open-Source.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":"2017-06-25T15:16:51.000Z","updated_at":"2025-02-25T00:05:07.000Z","dependencies_parsed_at":"2023-10-03T05:02:47.524Z","dependency_job_id":"dd6df2a8-a79b-443c-aea1-6532c30926fe","html_url":"https://github.com/PyBites-Open-Source/karmabot","commit_stats":{"total_commits":213,"total_committers":13,"mean_commits":"16.384615384615383","dds":"0.46478873239436624","last_synced_commit":"48add01bcba7eda76361bb4ee0d5e63e69818826"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyBites-Open-Source%2Fkarmabot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyBites-Open-Source%2Fkarmabot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyBites-Open-Source%2Fkarmabot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PyBites-Open-Source%2Fkarmabot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PyBites-Open-Source","download_url":"https://codeload.github.com/PyBites-Open-Source/karmabot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142062,"owners_count":20890652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bot","hacktoberfest","poetry","python","slack","slack-bot"],"created_at":"2024-11-06T03:04:31.061Z","updated_at":"2025-04-04T08:05:21.594Z","avatar_url":"https://github.com/PyBites-Open-Source.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PyBites Karmabot - A Python based Slack Chatbot\n\n[![Tests](https://github.com/PyBites-Open-Source/karmabot/workflows/Tests/badge.svg)](https://github.com/PyBites-Open-Source/karmabot/actions?workflow=Tests) [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)](https://github.com/pre-commit/pre-commit) [![codecov.io](https://codecov.io/github/PyBites-Open-Source/karmabot/coverage.svg?branch=master)](https://codecov.io/github/PyBites-Open-Source/karmabot?branch=master)\n\n**A Python based Slack Chatbot for Community interaction**\n\n## Features\n\nKarmabot's main features is the management of Karma within the slack community server. You can give karma, reduce karma, check your current karma points and manage your karma related username.\n\n![karma example](https://www.pogross.de/uploads/karmabot.png)\n\n[Demo Youtube Video](https://www.youtube.com/watch?v=Yx9qYl6lmzM\u0026amp;t=2s)\n\nAdditional commands / features are:\n\n- Jokes powered by [PyJokes](https://github.com/pyjokes/pyjokes)\n- Overview on top channels of the slack server\n- Random Python tip, quote or nugget from CodeChalleng.es\n- Browse and search python documentation, \"pydoc help\"\n\n## Installation\n\n`pip install karmabot`\n\n## Basic Usage\n\nAfter installing you can start karmabot by using the command\n\n```bash\nkarmabot\n```\n\nHowever, you need to some setup and supply some settings prior to this.\n\n### Setup\n\nFor app creation and tokens please follow the [slack-bolt guide](https://slack.dev/bolt-python/tutorial/getting-started) and enable [socket mode](https://slack.dev/bolt-python/concepts#socket-mode).\n\n#### Settings\n\nBy default we will look for a `.karmabot` file in the directory you used the `karmabot` command. The file should supply the following information.\n\n```env\n# Slack bot app\nKARMABOT_SLACK_BOT_TOKEN=\nKARMABOT_SLACK_APP_TOKEN=\n\n# Workspace\nKARMABOT_SLACK_USER=\nKARMABOT_GENERAL_CHANNEL=\nKARMABOT_LOG_CHANNEL=\nKARMABOT_ADMINS=\n\n# Backend\nKARMABOT_DATABASE_URL=\n\n# Testing\nKARMABOT_TEST_MODE=\n```\n\nKARMABOT_SLACK_BOT_TOKEN\n:   The [SLACK_BOT_TOKEN](https://slack.dev/bolt-python/tutorial/getting-started) for your bot. You will find it under **OAuth \u0026 Permission 🠊 Bot User OAuth Access Token** in your [app](https://api.slack.com/apps/). The token starts with `xoxb-`.\n\nKARMABOT_SLACK_APP_TOKEN\n: The SLACK_APP_TOKEN used for running the bot in [Socket Mode](https://slack.dev/bolt-python/concepts#socket-mode). You will find it under **Basic Information 🠊 App-Level Tokens** in your [app](https://api.slack.com/apps/).\n  The token starts with `xapp-`.\n\nKARMABOT_SLACK_USER\n: The bot's user id. Initially, you can fill in a placeholder. Once you've run your own Karmabot for the first time, you can ask it as admin in private chat via `@Karmabot your_id`. This will return a value starting with `U`, e.g., `U0123XYZ`. Replace your placeholder with this value.\n\nKARMABOT_GENERAL_CHANNEL\n: The channel id of your main channel in slack. Initially, you can fill in a placeholder. Once you've run your own Karmabot for the first time, you can ask it as admin in private chat via `@Karmabot general_channel_id`. This will return a value starting with `C`, e.g., `C0123XYZ`. Replace your placeholder with this value.\n\nKARMABOT_LOG_CHANNEL\n: The channel id (Cxyz) of the channel the bot logs karma point changes to (e.g. \"bobtester2's karma increased to 9\")\n\nKARMABOT_ADMINS\n: The [slack user ids](https://api.slack.com/methods/users.identity) of the users that should have admin command access separated by commas.\n\nKARMABOT_DATABASE_URL\n  : The database url which should be compatible with SqlAlchemy. For the provided docker file use `postgresql://user42:pw42@localhost:5432/karmabot`.\n  :heavy_exclamation_mark: To start the provided Docker-based Postgres server, be sure you have Docker Compose [installed](https://docs.docker.com/compose/install/) and run `docker-compose up -d` from the karmabot directory.\n\nKARMABOT_TEST_MODE=\n  : Determines if the code is run in test mode. User `KARMABOT_TEST_MODE=true` to enable testing mode. Everything else will default to `false`. This setting has to be provided as `true`, if you want run tests without a valid `KARMABOT_SLACK_BOT_TOKEN`. Otherwise, you will receive an exceptions with `slack_bolt.error.BoltError: token is invalid ...`.\n\nIf you do not want to use a file you have to provide environment variables with the above names. If no file is present we default to environment variables.\n\n#### Permissions\n\nGo to your [slack app](https://api.slack.com/apps/) and click on **Add features and functionality**. Then go into the following categories and set permissions.\n\n- Event Subscriptions\n  - Enable Events 🠊 Toggle the slider to on\n  - Subscribe to bot events 🠊 Add via the **Add Bot User Event** button\n    - team_join\n    - channel_create\n    - message.channels\n    - message.groups\n    - message.im\n- Permissions\n  - Scopes 🠊 Add the following permissions via the **Add an OAuth Scope** button\n    - app_mentions:read\n    - channels:history\n    - channels:join\n    - channels:read\n    - chat:write\n    - groups:history\n    - groups:read\n    - groups:write\n    - im:history\n    - im:read\n    - im:write\n    - users.profile:read\n    - users:read\n\n## Development pattern for contributors\n\nWe use [poetry](https://github.com/python-poetry/poetry) and `pyproject.toml` for managing packages, dependencies and some settings.\n\n### Setup virtual environment for development\n\nYou should follow the [instructions](https://github.com/python-poetry/poetry) to get poetry up and running for your system. We recommend to use a UNIX-based development system (Linux, Mac, WSL). After setting up poetry you can use `poetry install` within the project folder to install all dependencies.\n\nThe poetry virtual environment should be available in the the project folder as `.venv` folder as specified in `poetry.toml`. This helps with `.venv` detection in IDEs.\n\n#### Conda users\n\nIf you use the Anaconda Python distribution (strongly recommended for Windows users) and `conda create` for your virtual environments, then you will not be able to use the `.venv` environment created by poetry because it is not a conda environment. If you want to use `poetry` disable poetry's behavior of creating a new virtual environment with the following command: `poetry config virtualenvs.create false`. You can add `--local` if you don't want to change this setting globally but only for the current project. See the [poetry configuration docs](https://python-poetry.org/docs/configuration/) for more details.\n\nNow, when you run `poetry install`, poetry will install all dependencies to your conda environment. You can verify this by running `pip freeze` after `poetry install`.\n\n### Testing and linting\n\nFor testing you need to install [nox](https://nox.thea.codes/en/stable/) separately from the project venv created by poetry. For testing just use the `nox` command within the project folder. You can run all the nox sessions separately if need, e.g.,\n\n- only linting `nox -rs lint`\n- only testing `nox -rs tests`\n\nIf `nox` cannot be found, use `python -m nox` instead.\n\nFor different sessions see the `nox.py` file. You can run `nox --list` to see a list of all available sessions.\n\nIf you want to run tests locally via `pytest` you have to provide a valid `.karmabot` settings file or the respective enviroment variables.\n\nPlease make sure all tests and checks pass before opening pull requests!\n\n#### Using nox under Windows and Linux (WSL)\n\nMake sure to delete the `.nox` folder when you switch from Windows to WSL and vice versa, because the environments are not compatible.\n\n### [pre-commit](https://pre-commit.com/)\n\nTo ensure consistency you can use pre-commit. `pip install pre-commit` and after cloning the karmabot repo run `pre-commit install` within the project folder.\n\nThis will enable pre-commit hooks for checking before every commit.\n\n### The story behind Karmabot\n\nListen to Karmabot's core developer / maintainer Patrick Groß sharing the backstory of this project [on our podcast](https://www.pybitespodcast.com/1501156/8317703-022-the-karmabot-story-and-contributing-to-open-source).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpybites-open-source%2Fkarmabot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpybites-open-source%2Fkarmabot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpybites-open-source%2Fkarmabot/lists"}