<commit_before>jkent-pybot
===========

This is a modular, plugin-based IRC bot written in Python.  Plugins can be dynamically loaded and unloaded at runtime.  A design goal is the abillity to develop plugins without being able to crash the bot.

Plugins have a simple, easy to pick up API.  All events, commands, and triggers use a simple decorator convention.

Clone with:  `git clone https://github.com/jkent/jkent-pybot.git`

### Dependencies

Pybot runs under Python 3, however it might run under Python 2.  It is recommended to run Pybot using [Pipenv](http://docs.python-guide.org/en/latest/dev/virtualenvs/) to handle all dependencies.  Install pipenv and run 'pipenv run python pybot' from within the top directory.

### Configuring

You need to copy `config.ini.sample` to `config.ini` and edit it to your liking.

The below examples in the **Plugins** section assume `directed_triggers = False`.  Directed triggers start with the bot's name, followed by a colon or comma, and finally the command and any arguments.  The other option, classic triggers, take a ! followed by the command and any arguments.  The default option is to use directed triggers, so multiple bots can peacefully coexist.

### Running

Pybot is a python package.  Using pipenv, you would run like `pipenv run python pybot`.

### Plugins

#### aftership

This plugin ties in with aftership.com for package tracking services.  Updates are private messaged to users.  Configuration:

    [aftership]
    api_key = <KEY>

Usage example:

    !aftership add [usps] LK437895158CN Ethernet adapter
    !aftership add 9405509699938114314372 Telephone handset


#### anyurl

This plugin will fetch and reply with the og:title or title of a HTML document.


#### base

This plugin handles some of the core behaviors of the bot, such as setting the nick, joining channels, and auto-reconnect.  Its required, please don't unload it unless you know what you're doing.


#### choose

A fun yet frustrating plugin that gives random responses. 

    should I|<nick> <question>?
    !choose a or b, c.


#### config

This plugin allows live editing of the config.ini file.  Usage is limited to level 1000.

    !config reload
    !config save
    !config set <section> <option> <value>
    !config unset <section> <option>
    !config list <section>


#### debug

This plugin prints all IRC traffic and module events while loaded.  Usage is limited to level 900.

    !raw <message> - send a raw IRC message


#### eval

This is a dangerous plugin that allows arbitrary execution of python code.  Usage is limited to level 1000.

    !eval <code>


#### math

The math plugin is a nifty calculator that has support for functions and variables.  Its state is saved in a database as workbooks which can be switched out as needed.

    !math [expr]
    !math var=[expr]
    !math func([var[, ...]])=[expr]
    !math workbook [name]
    !math varlist
    !math funclist
    !math describe <funcname> [description]


#### notes

Leave a message for someone when the bot next sees them talk.

    !tell <nick> <message>


#### perms

Manage bot permissions.  Usage is limited to level 1000.

    !perms list
    !perms allow [-][<plugin>=<n>]
    !perms deny [-][<plugin>=<n>]

Where plugin is the name of a plugin and n is the level to set.  Plugin can be the special constant ANY.


#### plugin

Load, unload, reload plugins at runtime.  Usage is limited to level 1000.

    !plugin load <name>
    !plugin reload [!]<name>
    !plugin unload [!]<name>
    !plugin list


For reload and unload, the "bang" means force.  Use with caution.


#### song

Choose a random song from a song database.

    !song
    !song add <artist> - <title>
    !song delete
    !song fix artist <artist>
    !song fix title <title>
    !song last
    !song load <data-file>
    !song search <query>
    !song stats
    !song who
    !song youtube <youtube-url>
    !song youtube delete


#### twitter

Parse URLs, get latest user tweet, and search keywords on Twitter.

Dependencies: `requests, tweepy`

Configuration requires Twitter account and application setup:

     [twitter]
     apikey=<api key>
     secret=<api secret>
     auth_t=<api access token>
     auth_ts=<api access token secret>

Usage:
<commit_msg>touch up README.md a bit<commit_after>jkent-pybot
===========

This is a modular, plugin-based IRC bot written in Python.  Plugins can be dynamically loaded and unloaded at runtime.  A design goal is the abillity to develop plugins without being able to crash the bot.

Plugins have a simple, easy to pick up API.  All events, commands, and triggers use a simple decorator convention.

Clone with:  `git clone https://github.com/jkent/jkent-pybot.git`

### Dependencies

Pybot is designed and tested to run under Python 3. It is not thoroughly tested under python 2, but it may work for you. It is also recommended to use `pipenv` to manage dependencies.

### Configuring

You need to copy `config.ini.sample` to `config.ini` and edit it to your liking.

The below examples in the **Plugins** section assume `directed_triggers = False`.  Directed triggers start with the bot's name, followed by a colon or comma, and finally the command and any arguments.  The other option, classic triggers, take a ! followed by the command and any arguments.  The default option is to use directed triggers, so multiple bots can peacefully coexist.

### Running

Pybot is a python package.  Using pipenv, you would run like `pipenv run python pybot`.

### Plugins

#### aftership

This plugin ties in with aftership.com for package tracking services.  Updates are private messaged to users.  Configuration:

    [aftership]
    api_key = <KEY>

Usage example:

    !aftership add [usps] LK437895158CN Ethernet adapter
    !aftership add 9405509699938114314372 Telephone handset


#### anyurl

This plugin will fetch and reply with the og:title or title of a HTML document.


#### base

This plugin handles some of the core behaviors of the bot, such as setting the nick, joining channels, and auto-reconnect.  Its required, please don't unload it unless you know what you're doing.


#### choose

A fun yet frustrating plugin that gives random responses. 

    should I|<nick> <question>?
    !choose a or b, c.


#### config

This plugin allows live editing of the config.ini file.  Usage is limited to level 1000.

    !config reload
    !config save
    !config set <section> <option> <value>
    !config unset <section> <option>
    !config list <section>


#### debug

This plugin prints all IRC traffic and module events while loaded.  Usage is limited to level 900.

    !raw <message> - send a raw IRC message


#### eval

This is a dangerous plugin that allows arbitrary execution of python code.  Usage is limited to level 1000.

    !eval <code>


#### math

The math plugin is a nifty calculator that has support for functions and variables.  Its state is saved in a database as workbooks which can be switched out as needed.

    !math [expr]
    !math var=[expr]
    !math func([var[, ...]])=[expr]
    !math workbook [name]
    !math varlist
    !math funclist
    !math describe <funcname> [description]


#### notes

Leave a message for someone when the bot next sees them talk.

    !tell <nick> <message>


#### perms

Manage bot permissions.  Usage is limited to level 1000.

    !perms list
    !perms allow [-][<plugin>=<n>]
    !perms deny [-][<plugin>=<n>]

Where plugin is the name of a plugin and n is the level to set.  Plugin can be the special constant ANY.


#### plugin

Load, unload, reload plugins at runtime.  Usage is limited to level 1000.

    !plugin load <name>
    !plugin reload [!]<name>
    !plugin unload [!]<name>
    !plugin list


For reload and unload, the "bang" means force.  Use with caution.


#### song

Choose a random song from a song database.

    !song
    !song add <artist> - <title>
    !song delete
    !song fix artist <artist>
    !song fix title <title>
    !song last
    !song load <data-file>
    !song search <query>
    !song stats
    !song who
    !song youtube <youtube-url>
    !song youtube delete


#### twitter

Parse URLs, get latest user tweet, and search keywords on Twitter.
Configuration requires Twitter account and application setup:

     [twitter]
     apikey=<api key>
     secret=<api secret>
     auth_t=<api access token>
     auth_ts=<api access token secret>

Usage:

{'fraction_non_alphanumeric': 0.08397763768288331, 'fraction_numerical': 0.012370643511359582, 'mean_word_length': 3.4299262381454163, 'pattern_counts': {'":': 0, '<': 67, '<?xml version=': 0, '>': 67, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3447668', 'n_tokens_mistral': 2586, 'n_tokens_neox': 2347, 'n_words': 1164}