archangelic
/
pinhook
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update readme

pull/74/head v1.8.0
Mallory Hancock 2019-08-30 13:29:05 -07:00
parent 9e68e8e8a2
commit ff8a825846
2 changed files with 203 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
README.md
View File

@ -1,15 +1,78 @@
# pinhook # pinhook
[![Supported Python versions](https://img.shields.io/pypi/pyversions/pinhook.svg)](https://pypi.org/project/pinhook) [![Package License](https://img.shields.io/pypi/l/pinhook.svg)](https://github.com/archangelic/pinhook/blob/master/LICENSE) [![PyPI package format](https://img.shields.io/pypi/format/pinhook.svg)](https://pypi.org/project/pinhook) [![Package development status](https://img.shields.io/pypi/status/pinhook.svg)](https://pypi.org/project/pinhook) [![With love from tilde.town](https://img.shields.io/badge/with%20love%20from-tilde%20town-e0b0ff.svg)](https://tilde.town) [![Supported Python versions](https://img.shields.io/pypi/pyversions/pinhook.svg)](https://pypi.org/project/pinhook) [![Package License](https://img.shields.io/pypi/l/pinhook.svg)](https://github.com/archangelic/pinhook/blob/master/LICENSE) [![PyPI package format](https://img.shields.io/pypi/format/pinhook.svg)](https://pypi.org/project/pinhook) [![Package development status](https://img.shields.io/pypi/status/pinhook.svg)](https://pypi.org/project/pinhook) [![With love from tilde.town](https://img.shields.io/badge/with%20love%20from-tilde%20town-e0b0ff.svg)](https://tilde.town)
the pluggable python framework for IRC bots and Twitch bots The pluggable python framework for IRC bots and Twitch bots
## Tutorial * [Installation](#installation)
### Installation * [Creating an IRC Bot](#creating-an-irc-bot)
``` * [From Config File](#from-config-file)
$ pip install pinhook * [From Python File](#from-python-file)
* [Creating a Twitch Bot](#creating-a-twitch-bot)
* [Creating plugins](#creating-plugins)
* [Examples](#examples)
## Installation
Pinhook can be installed from PyPI:
``` bash
pip install pinhook
``` ```
### Creating an IRC Bot ## Creating an IRC Bot
A pinhook bot can be initialized using the command line tool `pinhook` with a config file, or by importing it into a python file to extend the base class.
### From Config File
Pinhook supports configuration files in YAML, TOML, and JSON formats.
Example YAML config:
```YAML
nickname: "ph-bot"
server: "irc.somewhere.net"
channels:
- "#foo"
- "#bar"
```
Required configuration keys:
* `nickname`: (string) nickname for your bot
* `server`: (string) server for the bot to connect
* `channels`: (array of strings) list of channels to connect to once connected
Optional keys:
* `port`: (default: `6667`) choose a custom port to connect to the server
* `ops`: (default: empty list) list of operators who can do things like make the bot join other channels or quit
* `plugin_dir`: (default: `"plugins"`) directory where the bot should look for plugins
* `log_level`: (default: `"info"`) string indicating logging level. Logging can be disabled by setting this to `"off"`
* `ns_pass`: this is the password to identify with nickserv
* `server_pass`: password for the server
* `ssl_required`: (default: `False`) boolean to turn ssl on or off
Once you have your configuration file ready and your plugins in place, you can start your bot from the command line:
```bash
pinhook config.yaml
```
Pinhook will try to detect the config format from the file extension, but the format can also be supplied using the `--format` option.
```bash
$ pinhook --help
Usage: pinhook [OPTIONS] CONFIG
Options:
-f, --format [json|yaml|toml]
--help Show this message and exit.
```
### From Python File
To create the bot, just create a python file with the following: To create the bot, just create a python file with the following:
```python ```python
@ -26,15 +89,17 @@ bot.start()
This will start a basic bot and look for plugins in the 'plugins' directory to add functionality. This will start a basic bot and look for plugins in the 'plugins' directory to add functionality.
Optional arguments are: Optional arguments are:
* `port`: choose a custom port to connect to the server (default: 6667)
* `ops`: list of operators who can do things like make the bot join other channels or quit (default: empty list) * `port`: (default: `6667`) choose a custom port to connect to the server
* `plugin_dir`: directory where the bot should look for plugins (default: "plugins") * `ops`: (default: empty list) list of operators who can do things like make the bot join other channels or quit
* `log_level`: string indicating logging level. Logging can be disabled by setting this to "off". (default: "info") * `plugin_dir`: (default: `"plugins"`) directory where the bot should look for plugins
* `log_level`: (default: `"info"`) string indicating logging level. Logging can be disabled by setting this to `"off"`
* `ns_pass`: this is the password to identify with nickserv * `ns_pass`: this is the password to identify with nickserv
* `server_pass`: password for the server * `server_pass`: password for the server
* `ssl_required`: boolean to turn ssl on or off * `ssl_required`: (default: `False`) boolean to turn ssl on or off
## Creating a Twitch Bot
### Creating a Twitch Bot
Pinhook has a baked in way to connect directly to a twitch channel Pinhook has a baked in way to connect directly to a twitch channel
```python ```python
@ -47,21 +112,25 @@ bot = TwitchBot(
) )
bot.start() bot.start()
``` ```
This function has far less options, as the server, port, and ssl are already handled by twitch. This function has far less options, as the server, port, and ssl are already handled by twitch.
Optional aguments are: Optional aguments are:
* `ops` * `ops`
* `plugin_dir` * `plugin_dir`
* `log_level` * `log_level`
These options are the same for both IRC and Twitch These options are the same for both IRC and Twitch
### Creating plugins ## Creating plugins
There are two types of plugins, commands and listeners. Commands only activate if a message starts with the command word, while listeners receive all messages and are parsed by the plugin for maximum flexibility. There are two types of plugins, commands and listeners. Commands only activate if a message starts with the command word, while listeners receive all messages and are parsed by the plugin for maximum flexibility.
In your chosen plugins directory ("plugins" by default) make a python file with a function. You use the `@pinhook.plugin.register` decorator to create command plugins, or `@pinhook.plugin.listener` to create listeners. In your chosen plugins directory ("plugins" by default) make a python file with a function. You use the `@pinhook.plugin.register` decorator to create command plugins, or `@pinhook.plugin.listener` to create listeners.
The function will need to be structured as such: The function will need to be structured as such:
```python ```python
import pinhook.plugin import pinhook.plugin
@ -74,6 +143,7 @@ def test_plugin(msg):
The function will need to accept a single argument in order to accept a `Message` object from the bot. The function will need to accept a single argument in order to accept a `Message` object from the bot.
The `Message` object has the following attributes: The `Message` object has the following attributes:
* `cmd`: (for command plugins) the command that triggered the function * `cmd`: (for command plugins) the command that triggered the function
* `nick`: the user who triggered the command * `nick`: the user who triggered the command
* `arg`: (for command plugins) all the trailing text after the command. This is what you will use to get optional information for the command * `arg`: (for command plugins) all the trailing text after the command. This is what you will use to get optional information for the command
@ -84,16 +154,20 @@ The `Message` object has the following attributes:
* `logger`: instance of `Bot`'s logger * `logger`: instance of `Bot`'s logger
* `datetime`: aware `datetime.datetime` object when the `Message` object was created * `datetime`: aware `datetime.datetime` object when the `Message` object was created
* `timestamp`: float for the unix timestamp when the `Message` object was created * `timestamp`: float for the unix timestamp when the `Message` object was created
* `bot`: the initialized Bot class
It also contains the following IRC functions: It also contains the following IRC functions:
* `privmsg`: send a message to an arbitrary channel or user * `privmsg`: send a message to an arbitrary channel or user
* `action`: same as privmsg, but does a CTCP action. (i.e., `/me does a thing`) * `action`: same as privmsg, but does a CTCP action. (i.e., `/me does a thing`)
* `notice`: send a notice * `notice`: send a notice
You can optionally use the `@pinhook.plugin.ops` decorator to denote that a command should only be executable by a bot op. You can optionally use the `@pinhook.plugin.ops` decorator to denote that a command should only be executable by a bot op.
* If you specify the optional second argument, it will be displayed when a non-op attempts to execute the command * If you specify the optional second argument, it will be displayed when a non-op attempts to execute the command
The function will need to be structured as such: The function will need to be structured as such:
```python ```python
@pinhook.plugin.register('!test') @pinhook.plugin.register('!test')
@pinhook.plugin.ops('!test', 'Only ops can run this command!') @pinhook.plugin.ops('!test', 'Only ops can run this command!')
@ -102,12 +176,15 @@ def test_plugin(msg):
``` ```
The plugin function can return one of the following in order to give a response to the command: The plugin function can return one of the following in order to give a response to the command:
* `pinhook.plugin.message`: basic message in channel where command was triggered * `pinhook.plugin.message`: basic message in channel where command was triggered
* `pinhook.plugin.action`: CTCP action in the channel where command was triggered (basically like using `/me does a thing`) * `pinhook.plugin.action`: CTCP action in the channel where command was triggered (basically like using `/me does a thing`)
## Examples ## Examples
There are some basic examples in the `examples` directory in this repository. There are some basic examples in the `examples` directory in this repository.
Here is a list of live bots using pinhook: Here is a list of live bots using pinhook:
* [pinhook-tilde](https://github.com/archangelic/pinhook-tilde) - fun bot for tilde.town * [pinhook-tilde](https://github.com/archangelic/pinhook-tilde) - fun bot for tilde.town
* [adminbot](https://github.com/tildetown/adminbot) - admin helper bot for tilde.town, featuring some of the ways you can change the Bot class to suit your needs * [adminbot](https://github.com/tildetown/adminbot) - admin helper bot for tilde.town, featuring some of the ways you can change the Bot class to suit your needs

108
README.rst
View File

@ -4,20 +4,91 @@ pinhook
|Supported Python versions| |Package License| |PyPI package format| |Supported Python versions| |Package License| |PyPI package format|
|Package development status| |With love from tilde.town| |Package development status| |With love from tilde.town|
the pluggable python framework for IRC bots and Twitch bots The pluggable python framework for IRC bots and Twitch bots
Tutorial - `Installation <#installation>`__
-------- - `Creating an IRC Bot <#creating-an-irc-bot>`__
- `From Config File <#from-config-file>`__
- `From Python File <#from-python-file>`__
- `Creating a Twitch Bot <#creating-a-twitch-bot>`__
- `Creating plugins <#creating-plugins>`__
- `Examples <#examples>`__
Installation Installation
~~~~~~~~~~~~ ------------
:: Pinhook can be installed from PyPI:
$ pip install pinhook .. code:: bash
pip install pinhook
Creating an IRC Bot Creating an IRC Bot
~~~~~~~~~~~~~~~~~~~ -------------------
A pinhook bot can be initialized using the command line tool ``pinhook``
with a config file, or by importing it into a python file to extend the
base class.
From Config File
~~~~~~~~~~~~~~~~
Pinhook supports configuration files in YAML, TOML, and JSON formats.
Example YAML config:
.. code:: YAML
nickname: "ph-bot"
server: "irc.somewhere.net"
channels:
- "#foo"
- "#bar"
Required configuration keys:
- ``nickname``: (string) nickname for your bot
- ``server``: (string) server for the bot to connect
- ``channels``: (array of strings) list of channels to connect to once
connected
Optional keys:
- ``port``: (default: ``6667``) choose a custom port to connect to the
server
- ``ops``: (default: empty list) list of operators who can do things
like make the bot join other channels or quit
- ``plugin_dir``: (default: ``"plugins"``) directory where the bot
should look for plugins
- ``log_level``: (default: ``"info"``) string indicating logging level.
Logging can be disabled by setting this to ``"off"``
- ``ns_pass``: this is the password to identify with nickserv
- ``server_pass``: password for the server
- ``ssl_required``: (default: ``False``) boolean to turn ssl on or off
Once you have your configuration file ready and your plugins in place,
you can start your bot from the command line:
.. code:: bash
pinhook config.yaml
Pinhook will try to detect the config format from the file extension,
but the format can also be supplied using the ``--format`` option.
.. code:: bash
$ pinhook --help
Usage: pinhook [OPTIONS] CONFIG
Options:
-f, --format [json|yaml|toml]
--help Show this message and exit.
From Python File
~~~~~~~~~~~~~~~~
To create the bot, just create a python file with the following: To create the bot, just create a python file with the following:
@ -37,20 +108,20 @@ directory to add functionality.
Optional arguments are: Optional arguments are:
- ``port``: choose a custom port to connect to the server (default: - ``port``: (default: ``6667``) choose a custom port to connect to the
6667) server
- ``ops``: list of operators who can do things like make the bot join - ``ops``: (default: empty list) list of operators who can do things
other channels or quit (default: empty list) like make the bot join other channels or quit
- ``plugin_dir``: directory where the bot should look for plugins - ``plugin_dir``: (default: ``"plugins"``) directory where the bot
(default: "plugins") should look for plugins
- ``log_level``: string indicating logging level. Logging can be - ``log_level``: (default: ``"info"``) string indicating logging level.
disabled by setting this to "off". (default: "info") Logging can be disabled by setting this to ``"off"``
- ``ns_pass``: this is the password to identify with nickserv - ``ns_pass``: this is the password to identify with nickserv
- ``server_pass``: password for the server - ``server_pass``: password for the server
- ``ssl_required``: boolean to turn ssl on or off - ``ssl_required``: (default: ``False``) boolean to turn ssl on or off
Creating a Twitch Bot Creating a Twitch Bot
~~~~~~~~~~~~~~~~~~~~~ ---------------------
Pinhook has a baked in way to connect directly to a twitch channel Pinhook has a baked in way to connect directly to a twitch channel
@ -77,7 +148,7 @@ Optional aguments are:
These options are the same for both IRC and Twitch These options are the same for both IRC and Twitch
Creating plugins Creating plugins
~~~~~~~~~~~~~~~~ ----------------
There are two types of plugins, commands and listeners. Commands only There are two types of plugins, commands and listeners. Commands only
activate if a message starts with the command word, while listeners activate if a message starts with the command word, while listeners
@ -120,6 +191,7 @@ The ``Message`` object has the following attributes:
object was created object was created
- ``timestamp``: float for the unix timestamp when the ``Message`` - ``timestamp``: float for the unix timestamp when the ``Message``
object was created object was created
- ``bot``: the initialized Bot class
It also contains the following IRC functions: It also contains the following IRC functions: