YandereLewdBot/docs/configuration.md

# Configuration
Yandere Lewd Bot uses regular python files to configure posts. The default configuration is `cfg.py`

Included in the file are three [helper functions](#setting-up-profiles-in-a-single-line) to quickly configure posts. These are located at the top of the configuration file.

Below is a detailed description of each parameter in the configuration file.

## setting_server
Paste the generated credentials from `create_app.py` in the fields below.

**`app_name:`** The name of the application.

**`api_base_url:`** The URL of the instance.

**`client_id:`** The client ID generated by `create_app.py`

**`client_secret:`** The client secret generated by `create_app.py`

**`access_token:`** The client token generated by `create_app.py`

**NOTE:** If you enabled encryption when generating your tokens, the above should be long strings of seemingly incoherent text.

## settings_reminder
A setting to remind the user to regenerate their OAuth tokens

**`settings_reminder:`** A date and time, formatted as `settings_time["long_date_format"]`. Used to remind the user to regenerate their OAuth tokens.

## settings_encrypt
Paste the generated credentials from `create_app.py` in the fields below.

**`encrypt:`** If encryption is enabled this should be set to `True`

**`salt:`** The salt value generated by `create_app.py`

## settings_behavior
This is the main configuration setting for the bot.

**`master_list:`** The master list(s) for the bot to post from. This should be a GNU formatted hash file. If multiple lists are specified they will be concatenated in order.

**`master_blacklist_r:`** The master blacklist(s) to be *read* when the bot starts. This should be a GNU formatted hash file. All hashes and paths specified in this setting will be blacklisted when the bot initializes and will not be posted.

**`master_blacklist_w:`** The master file(s) to *write* to when the bot makes a successful post. This will be a GNU formatted hash file.

**`max_size:`** The max upload size (in bytes). Files that are over will be excluded from posting. Set this to `None` if there is no limit (not recommended). If you find that the bot is continuously attempting to repost a post that is failing, and the connection is timing out, it usually signifies that you are attempting to upload a large file over a slow connection and getting dropped from the server. Reducing this value should fix the issue.

**`visibility:`** The visibility of the post ('public', 'unlisted', 'private', or 'direct').

**`feature_set:`** The feature set of the instance you are connecting to ('mainline', 'fedibird', or 'pleroma'). **This bot has only been tested with 'pleroma'.**

**`sleep_seconds:`** The time between posts (in seconds)

**`uploads_per_post:`** The number of times the bot should post after `sleep_seconds`

**`retry_seconds:`** The time the bot should wait before attempting to re-upload a post that failed (in seconds). This value is ignored if the bot experiences a FileNotFoundError (the file was deleted after the bot was started) or encounters a 413 error (file upload size is too large). In either of the two cases the bot will continue posting the next image in the list.

**`multi_media_ext:`** Files ending with this extension will be treated as a multi-upload list. All GNU formatted hashes contained within will be uploaded in a single post when picked by the bot. Setting this value to `None` or `False` will disable this behavior.

**`content_type:`** The content type of the post ('text/plain' (default), 'text/markdown', 'text/html', 'text/bbcode'). **This bot has only been tested with `'text/plain'` and  `'text/markdown'`**.

**`content_newline:`** The newline character or string. This will be inserted between each line in the message. If `content_type` is `'text/plain'`, this value should be `'\n'`. If `content_type` is `'text/markdown'` you may need to experiment. On some instances the defualt `'\n'` works, on others you may need to change this to `'<br/>'`.

**`post_image_link:`** If set to `True` this will insert a direct media link at the end of the message for each media file uploaded. If `content_type` is `'text\markdown'` it will make the link actionable, otherwise it will simply be a plain text html link. Some instances add this link automatically, in which case this should be set to `False`. See `content_newline` and `content_type` to correctly configure actionable links.

**`post_random:`** Shuffle all items in `master_list` so that they post in random order.

**`atomic_saving:`** If set to `True`, when the bot blacklists a file it will create a temporary copy of the file(s) that it is writing to. It will write to the temp file, then write over the old file. This is basically a paranoid saving option in case your server loses power unexpectedly while the bot is writing data. Generally speaking setting this option to `True` is probably unnecessary and will result in excessive writes to the disk.

**`sync_save:`** If set to`True` the bot will synchronize data to the disk immediately when it writes to a blacklist file. Generally speaking this should be set to `True` in case the server looses power unexpectedly. It should be set to `False` you are posting a lot of images at once. You should also be aware that if `atomic_saving` is enabled, it will syncronize all writes to and from the temp file which is probobly excessive.

**`tmp_dir:`** The temporary directory to use if `atomic_saving` is set to `True`. The default location is `/var/tmp`.

**`debug:`** Set this to true for testing. This will prevent Yandere Lewd Bot from logging into the mastodon instance and asking for your encryption password (meaning that nothing will actually get posted to your account, but it will still do everything else).

**NOTE:** `master_list`, `master_blacklist_r`, and `master_blacklist_w` all take a tuple() of str(). Please see below for formatting help.
> To specify multiple files: `master_blacklist_r: ("./md5/blacklist.txt", "./md5/master_blacklist.txt"),`  
> To specify a single file: `master_blacklist_r: ("./md5/blacklist.txt",),`  
> To specify no file: `master_blacklist_r: tuple(),`

## settings_time
Time localization settings.

**`time_format:`** This is used to schedule posts using the `-t` switch. Referenced in `set_pretimer_hour()`

**`time_format_seconds:`** Unused. Should be the same as `time_format` but with a resolution in seconds.

**`date_format:`** This is used to schedule posts using the `-d` switch. Referenced in `set_pretimer_day()`

**`long_date_format:`** Time and date format. `settings_encrypt["reminder"]` Should be in this format. Referenced in `print_header_stats()` and `_sanity_warnings()`

**`long_date_seconds_format:`** Unused. Should be the same as `long_date_format` but with  a resolution in seconds.

**`long_date_week:`** The same as `long_date_format` but with the day of the week specified. Referenced in `print_header_stats()`

## settings_post
Configure Yandere Lewd Bot profiles. In the default configuration, images are sorted by safe and nsfw profiles. This means that all 'safe' images should be located in `./rsc/safe/*` and all 'nsfw' images should be located in `./rsc/nsfw/*`. The bot will apply profiles based on it's file path using [Unix filename pattern matching](https://docs.python.org/3/library/fnmatch.html).

**`settings_post:`** A tuple() containing all of the profile dictionaries that the bot can post. See `setup_profile()`, `setup_nsfw_profile()`, and `setup_safe_profile()` for help configuring custom profiles.

**`settings_post_default:`** The default post profile. If no profile can be matched for an item in the `master_list` it will default to the profile specified by this value. If the value is `None`, the bot will error out and output the offending line(s) from the hash file (recommended). If you want to apply a default post behavior for unmatched profiles, create a default setting with `setup_profile()` helper function. The Unix `path` keyword will be completely ignored.

# Setting Up Profiles
Each profile in `settings_post` contains a dictionary with the following keywords: `name`, `path`, `message`, and `spoiler`

Below is an explanation of each keyword:

* **`name:`** String value. The name of the profile. This is mainly used to help you identify what profile is being applied to posts. This information is printed by the bot, but is otherwise unused.

* **`path:`** String value. This should be a Unix path with wildcards. The bot will configure posts accordingly by using [Unix filename pattern matching](https://docs.python.org/3/library/fnmatch.html) implemented in the `fnmatch` python library.

* **`message:`** A tuple of strings. The message. Each string in the tuple will be placed on a new line.

* **`spoiler:`** Boolean value. Mark the media as sensitive. Use for nsfw or spoilers.

## Setting Up Profiles in a Single Line
At the top of the default configuration file are the following three helper functions to make setting up posts more intuative.
>**`setup_profile(name, path, spoiler, *message)`**  
**`setup_nsfw_profiles(name, path, *message)`**  
**`setup_safe_profiles(name, path, *message)`**  

---
**`setup_profile(name, path, spoiler, *message)`**  
Returns a post setting dictionary that contains all of the information about a single profile. Each parameter corresponds to the keywords listed above.

* **`name:`** The name of the profile.

* **`path:`** A Unix path with wildcards.

* **`spoiler:`** Mark the media as sensitive. Use for nsfw or spoilers.

* **`*message:`** The message. This is a variable length parameter (meaning that multiple parameters may be passed to it). Each line in your message should be passed as a separate string to the `*message` variable. 
>**DO NOT** use the newline character `\n` to configure multiline messages. Instead pass each line as a separate string parameter: ex. `setup_profile("profile.safe", "./rsc/safe/*", False, "First line in my message", "Second line in my message")`

	> Each line in the example above will be placed on a new line.

**`setup_nsfw_profiles(name, path, *message)`**  
Returns a post_setting dictionary that contains all of the information about a single **nsfw** profile.

**`setup_safe_profiles(name, path, *message)`**  
Returns a post_setting dictionary that contains all of the information about a single **safe** profile.