Metadata-Version: 2.1
Name: doclib
Version: 1.4.2
Summary: A chatbot library for euphoria.io.
Home-page: https://gitlab.com/DoctorNumberFour/DocLib
Author: DoctorNumberFour
Author-email: miloszecket@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: websocket-client
Requires-Dist: websockets
Requires-Dist: attrdict

# **DocLib**
A chatbot library for euphoria.io.
# Usage
## Installation
To install, use `pip` or `pip3`:
```bash
pip3 install doclib
```
When beginning a new bot, import the `Bot` class:
```python
from doclib import Bot
```
## Basic Bots
A basic bot will be a `Bot` object, constructed with a `nick`(the bot's name, shown in the room), a `room`(where the bot is sent by default, defaults to bots or test in debug mode), and an `owner`(your euphoria username.):
```python
sampleBot = Bot(nick = 'bugBot', room = 'test', owner = 'sample user')
```
### Other Constructor Options
| option | default | usage |
| ------ | ------ | ------ |
| `password` | blank string |room password (used for private rooms)|
| `help`| `"[nick] is a bot made with Doctor Number Four's Python 3 bot library, DocLib (link: https://github.com/milovincent/DocLib) by @[owner].\nIt follows botrulez and does not have a custom !help message yet."` | your custom !help command response. can also be set by adding a `"^!help @[nick w/o spaces]$"` command to your regexes|
|`ping`| `"Pong!"` | your custom !ping response.|
|`important`|`False`|if `True`, the bot will only be killable by a roomhost or the owner. **NOT RECOMMENDED FOR SIMPLE BOTS OR BOTS PRONE TO SPAM**.|
|`killed`|`"/me has died"`|your custom message sent when bot is !killed.|
|`API_timeout`|`10`|ADVANCED: number of API responses to check for command responses. You should not need to change this unless the room is particularly active.|

Once constructed, the user should assign a regex dictionary for non-advanced use cases:
```python
sampleBot.set_regexes({r'^!command$' : function, r'(?i)word' : 'response'})
```
#### Regex Formatting
DocLib uses the default python `re` library for regex formatting.


## Custom Function Responses
Regexes with a function value run the function with a `Bot` object (`chatbot`), an `AttrDict` (`msg`), and the regex `match` object (`matches`).
Functions can utilise any of the numerous `Bot` methods:

|Method|Parameters|Effect|
|------|-------|-------|
|`send_msg`|`parent` (`AttrDict` or string), `msg` (string)|Sends `msg` as a reply to `parent`, where `parent` can either be a string containing the message id returned by the API or an `AttrDict` with the structure of a `send-reply` generated by the API (recommended: use the `msg` parameter given to your custom function)|
|`set_nick`|`nick` (string)|Sets the bot's name to `nick`|
|`get_userlist`|none|returns an array of user `AttrDict`s currently in the room, including bots, accounts, and agents.|
|`move_to`|`roomName` (string), `password` (string, default is an empty string)|Moves the bot to a different room, specified by `roomName`, and, if necessary, attempts to log into it using `password`.|
|`restart`|none|Restarts the bot.|
|`kill`|none|Kills the bot.|

#### Example:
Regex:
```python
sampleBot.set_regexes({'^!alive$' : alive})
```
Function (defined **above bot start**)
```python
def alive(chatbot, msg, matches):
    chatbot.send_msg(parent = msg, msg = '/me IS ALIVE!')
    chatbot.set_nick('Thunder')
    chatbot.send_msg(parent = msg, msg = '/me crashes')
    chatbot.set_nick('sampleBot')
```

## Custom Handlers
To set custom function handlers for any API response (when using `simple_start`, this does not include `ping-event`s, `send-event`s, `error`s, or `bounce-event`s), use `set_handler`:
```python
sampleBot.set_handler(eventString = "join-event", on_join)
```
All handler functions, including the universal function parameter for `advanced_start`, are passed the API response (`msg`) as an `AttrDict` every time the corresponding event is received. Custom handlers take precedence over `advanced_start`'s universal handler.

# Startup

Once the bot is set up and populated with commands, the user can connect and start it:
```python
sampleBot.connect()
sampleBot.simple_start()
```

## Advanced Usage
Using `advanced_start` instead of `simple_start` enables the user to set a universal handler for all API events, in addition to any custom handlers:
```python
sampleBot.advanced_start(handler_function)
```
If unspecified, `advanced_start` uses a filler function that does nothing, enabling the user to use entirely custom handlers for every API response.
# Command Line Options
When running any bot in the command line, the user has access to a few options:

|option|usage|
|--|--|
|`-t`, `--test`, `--debug`|Used to debug dev builds. Sends bot to &test instead of its default room.|
|`--room ROOM`, `-r ROOM`|Sends bot to &ROOM instead of its default room.|
|`--password PASSWORD`, `-p PASSWORD`|Password to use should the room be locked.|


