From e2003eed471e57b312d19e22d76eca30b69a087d Mon Sep 17 00:00:00 2001 From: Collin R Date: Wed, 15 Jan 2020 22:48:32 -0800 Subject: [PATCH] Updated readme --- README.md | 133 ++++++++++++++++++++++++++++++++++++------- pointsbot.sample.ini | 10 ++-- pointsbot/bot.py | 11 ++-- praw.sample.ini | 10 ++-- 4 files changed, 129 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 84fa773..632a0af 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ * [Description](#description) * [Installation](#installation) +* [Configuration](#configuration) * [Usage](#usage) -* [TODO](#todo) * [Ideas](#ideas) * [Questions](#questions) * [License](#license) @@ -15,10 +15,8 @@ This is a bot for Reddit that monitors solutions to questions or problems in a subreddit and awards points to the user responsible for the solution. -This bot is based on the description in +This bot is intended as a solution for [this request](https://www.reddit.com/r/RequestABot/comments/emdeim/expert_level_bot_coding/). -While this could be used for other subreddits, this means that it is intended -for [r/MinecraftHelp](https://www.reddit.com/r/MinecraftHelp/). The bot will award a point to a redditor when the OP of a submission includes "!Solved" or "!solved" somewhere in a reply to the redditor's comment on that @@ -47,27 +45,118 @@ awarded for each submission. Requirements: -* [python3](www.python.org) (specifically, version 3.7 or greater) - * pip (should be installed automatically alongside python) +* [Python 3](https://www.python.org/downloads/) (specifically version 3.7 or greater) + * pip (should be installed automatically with Python) * [pipenv](https://pipenv.readthedocs.io/en/latest/) - * Install by running `pip install pipenv` + * After installying Python & pip, install by running `pip install pipenv` + * For other installation options, + [see here](https://pipenv.readthedocs.io/en/latest/install/#installing-pipenv) -First, download this project using `git` or by downloading a zipfile from the -Github repository. +First, download this project using `git` or by downloading a ZIP archive from +the Github repository using the green `Clone or download` button. If ZIP, be +sure to extract the files from the archive before moving on. -To install, navigate to the project root directory and run `pipenv install`. +To install the packages necessary for running the bot, navigate to the project +root directory and run `pipenv install`. To uninstall (i.e. delete the project's virtual environment and the installed -python packages), instead run `pipenv --rm`. +python packages), navigate to the project root directory and instead run +`pipenv --rm`. -## Usage +## Configuration -The bot can be configured by changing the values in the configuration files: +The bot can be configured by changing the values in the configuration files in +the project root directory: * `praw.ini` - Contains the account information for the bot * `pointsbot.ini` - Contains settings for bot behavior +You shouldn't have to worry about it, but if you need it, the syntax for the +config files can be found on the +[INI file format's Wikipedia page](https://en.wikipedia.org/wiki/INI_file). + +If this is your first time running the bot, you will need to copy +`praw.sample.ini` to a new file called `praw.ini`, and likewise copy +`pointsbot.sample.ini` to a new file called `pointsbot.ini`. Any instances of +the word "REDACTED" should be replaced with the desired values; other values +should work as-is, but can be changed as desired. + +The reason for this is that these config files (especially `praw.ini`) can +contain sensitive information, and maintaining only sample versions of these +files helps developers to avoid accidentally uploading that sensitive +information to a public (or even private) code repository. + +### praw.ini + +In order to make a bot, you must first have a bot account. This could be a +personal account, but it is wise to create a dedicate account for the bot, +especially one with the word "bot" somewhere in the name. + +Once you have that, you can create a Reddit app for the bot. This is needed for +authenticating with Reddit. + +1. First, go to your [app preferences](https://www.reddit.com/prefs/apps). +2. Select the "are you a developer? create an app..." button. +3. Provide a name for the bot, which could probably be the same as the account's + username. +4. Select the "script" radio button. +5. Provide a brief description. +6. For the "about url", you can provide a link to this Github repository: + https://github.com/cur33/PointsBot +7. Since it is unused, the "redirect uri" can be set to something like: + http://www.example.com/unused/redirect/uri +8. Select "create app". + +Now you should be redirected to a page which contains the credentials you will +need; under the name of the bot is the unlabeled `client_id`, and below that +with the label "secret" is the `client_secret`. + +If you have already done this in the past, the `client_id` and `client_secret` +can be found by navigating to your +[app preferences](https://www.reddit.com/prefs/apps) and selecting the "edit" +button for the app under the "developed applications" section. + +Several credentials are needed for running your bot, each of which is listed in +the `praw.ini` config file: + +* `client_id`: Copy from your app preferences, as specified in the previous + steps. +* `client_secret`: Copy from your app preferences, as specified in the previous + steps. +* `user-agent`: This field can be left as-is, thought if you'd like, you can + change it by following [these guidelines](). +* `username`: The username for the bot account. +* `password`: The password for the bot account. + +### pointsbot.ini + +For now, these settings are pretty straightforward. + +The `Core` section: + +* `subreddit_name`: The name of the subreddit to monitor +* `praw_site_name`: This should probably be left alone; it tells the bot which + credentials to use when authenticating with Reddit. It's useful for + development and easy testing with different accounts without having to + modify values in the code. +* `database_name`: This is the filepath to the SQLite database file, which ends + with the `.db` file extension. + +The `Levels` section is used to determine the available user levels and +corresponding flair texts. + +* The key on the left-hand side specifies the title and flair text for the + level; the case is ignored, and the text is converted to title case (first + letter of each word capitalized, and the rest lowercase). +* The value on the right-hand side of each line is the total number of points + required to reach that level. + +The order of these lines doesn't matter; the bot will sort them in order of +point totals. + +## Usage + The simplest way to run the bot is to navigate to the project root directory and run: @@ -75,12 +164,12 @@ run: pipenv run python -m pointsbot ``` -## Ideas & To-Do +## Ideas ### Config -* Store all config and data in a `.pointsbot` directory or similar in the user's - home or data directory (OS-dependent). +* Store all config and data in a hidden `.pointsbot` directory or similar in the + user's home or data directory (OS-dependent). * Could do something similar to packages like PRAW: 1. Look in current working directory first. 2. Look in OS-dependent location next. @@ -90,13 +179,15 @@ pipenv run python -m pointsbot could be a little too technical (though any more technically-minded users might appreciate the option). * Consolidate `pointsbot.ini` and `praw.ini` into a single config file. +* Write a CLI script or GUI to handle this so the config values don't have to be + changed manually. ### Database -Should it keep track of the solved posts for future reference and calculate -points on the fly, rather than just keeping track of points? If so, should have -a column denoting whether the post has been deleted, if that information is -decided to be useful when determining a user's points. +* Should it keep track of the solved posts for future reference and calculate + points on the fly, rather than just keeping track of points? If so, should + have a column denoting whether the post has been deleted, if that + information is decided to be useful when determining a user's points. ### Determining when to award points @@ -150,6 +241,8 @@ To ensure that a point is awarded to the correct user: * Should the reply comment always tag them, even if it's not their first point? * When a user levels up, should the reply comment also mention that they have been awarded a new flair? +* Should the comment contain a notice that the post was made by a bot, similar + to the notice on posts by automod? ## License diff --git a/pointsbot.sample.ini b/pointsbot.sample.ini index f638a0c..b122aae 100644 --- a/pointsbot.sample.ini +++ b/pointsbot.sample.ini @@ -1,9 +1,9 @@ [Core] subreddit_name = REDACTED -praw_site_name = REDACTED -database_name = REDACTED +praw_site_name = bot +database_name = pointsbot.db [Levels] -level one name = 1 -level two name = 5 -level three name = 10 +Helper = 5 +Trusted Helper = 15 +Super Helper = 40 diff --git a/pointsbot/bot.py b/pointsbot/bot.py index d8438ac..b5b3aaa 100644 --- a/pointsbot/bot.py +++ b/pointsbot/bot.py @@ -20,14 +20,15 @@ def run(): # TODO Make levels a dict instead # TODO Could also make a Level class or namedtuple that contains more info, e.g. # flair css or template id - levels = [(o, config.getint('Levels', o)) for o in config.options('Levels')] - levels.sort(key=lambda pair: pair[1]) - # levels = [] - # for opt in config.options('Levels'): - # levels.append((opt, config.getint('Levels', opt))) + # levels = [(o, config.getint('Levels', o)) for o in config.options('Levels')] # levels.sort(key=lambda pair: pair[1]) + levels = [] + for opt in config.options('Levels'): + levels.append((opt.title(), config.getint('Levels', opt))) + levels.sort(key=lambda pair: pair[1]) + # Connect to Reddit reddit = praw.Reddit(site_name=config['Core']['praw_site_name']) subreddit = reddit.subreddit(config['Core']['subreddit_name']) diff --git a/praw.sample.ini b/praw.sample.ini index 2afc426..ddce8d5 100644 --- a/praw.sample.ini +++ b/praw.sample.ini @@ -1,6 +1,6 @@ [bot] -client_id=REDACTED -client_secret=REDACTED -user_agent=PointsBot (by /u/GlipGlorp7) -username=REDACTED -password=REDACTED +client_id = REDACTED +client_secret = REDACTED +user_agent = PointsBot (by /u/GlipGlorp7) +username = REDACTED +password = REDACTED