Update docs

This commit is contained in:
dpedu 2015-06-19 20:23:36 -07:00
parent 48a45a0073
commit c002c67807
38 changed files with 425 additions and 72 deletions

10
docs/api/irccore.rst Normal file
View File

@ -0,0 +1,10 @@
:mod:`IRCCore` --- IRC protocol client
======================================
A simple and generic class for interacting with the IRC protocol.
.. automodule:: pyircbot.irccore
:members:
:undoc-members:
:show-inheritance:

View File

@ -15,6 +15,9 @@ Items are dicts. An item can have many keys. Each key points to one value.
+--> [ key ] --> [ value ]
Class Reference
---------------
.. automodule:: pyircbot.modules.AttributeStorage
:members:
:undoc-members:

View File

@ -0,0 +1,12 @@
:mod:`AttributeStorageLite` --- Item key/value storage
======================================================
With a SQLite backend.
Class Reference
---------------
.. automodule:: pyircbot.modules.AttributeStorageLite
:members:
:undoc-members:
:show-inheritance:

View File

@ -0,0 +1,15 @@
:mod:`BitcoinPrice` --- Fetch the current Bitcoin price
=======================================================
Commands
--------
- *.btc*, *.bitcoin* - fetch the bitcoin price
Class Reference
---------------
.. automodule:: pyircbot.modules.BitcoinPrice
:members:
:undoc-members:
:show-inheritance:

18
docs/api/modules/calc.rst Normal file
View File

@ -0,0 +1,18 @@
:mod:`Calc` --- IRC fact game
=============================
Commands
--------
- *calc* - returns a random fact
- *calc something = some definition* - add a fact
- *calc something =* - delete a fact
- *match keyword* - search facts
Class Reference
---------------
.. automodule:: pyircbot.modules.Calc
:members:
:undoc-members:
:show-inheritance:

View File

@ -3,6 +3,9 @@
Module to provide a multi-type cryptocurrency wallet
Class Reference
---------------
.. automodule:: pyircbot.modules.CryptoWallet
:members:
:undoc-members:

View File

@ -3,6 +3,9 @@
Module capable of operating Bitcoind-style RPC. Provided as a service.
Class Reference
---------------
.. automodule:: pyircbot.modules.CryptoWalletRPC
:members:
:undoc-members:

View File

@ -3,6 +3,9 @@
Module to provide a game for gambling Dogecoin
Class Reference
---------------
.. automodule:: pyircbot.modules.DogeDice
:members:
:undoc-members:

View File

@ -3,6 +3,9 @@
This module provides a service for interacting with dogecoind.
Class Reference
---------------
.. automodule:: pyircbot.modules.DogeRPC
:members:
:undoc-members:

View File

@ -4,6 +4,9 @@
This module provides a word scrambling game that rewards winners with small
amounts of Dogecoin
Class Reference
---------------
.. automodule:: pyircbot.modules.DogeScramble
:members:
:undoc-members:

View File

@ -3,6 +3,9 @@
This module provides a dogecoin wallet hosted on the IRC bot's server
Class Reference
---------------
.. automodule:: pyircbot.modules.DogeWallet
:members:
:undoc-members:

View File

@ -3,6 +3,9 @@
An animal hunting IRC game
Class Reference
---------------
.. automodule:: pyircbot.modules.DuckHunt
:members:
:undoc-members:

View File

@ -1,7 +1,8 @@
:mod:`Error` --- A module to cause an error
===========================================
yabba blahblah blahblah
Class Reference
---------------
.. automodule:: pyircbot.modules.Error
:members:

View File

@ -3,6 +3,9 @@
A codebase for making IRC games
Class Reference
---------------
.. automodule:: pyircbot.modules.GameBase
:members:
:undoc-members:

View File

@ -0,0 +1,16 @@
:mod:`Inventory` --- Allows the bot to carry items
==================================================
Commands
--------
- *botnick: inventory* - print current inventory
- *botnick: have a x* - give the bot an item
Class Reference
---------------
.. automodule:: pyircbot.modules.Inventory
:members:
:undoc-members:
:show-inheritance:

View File

@ -0,0 +1,10 @@
:mod:`LinkTitler` --- Fetch page titles for URLs posted in chat
===============================================================
Class Reference
---------------
.. automodule:: pyircbot.modules.LinkTitler
:members:
:undoc-members:
:show-inheritance:

View File

@ -3,6 +3,9 @@
Module providing a mysql type service
Class Reference
---------------
.. automodule:: pyircbot.modules.MySQL
:members:
:undoc-members:

View File

@ -0,0 +1,10 @@
:mod:`NFLLive` --- Fetch NFL scores & game times
================================================
Class Reference
---------------
.. automodule:: pyircbot.modules.NFLLive
:members:
:undoc-members:
:show-inheritance:

View File

@ -3,6 +3,9 @@
A module providing a simple login/logout account service
Class Reference
---------------
.. automodule:: pyircbot.modules.NickUser
:members:
:undoc-members:

View File

@ -1,7 +1,11 @@
:mod:`PingResponder` --- Service ping responder
===============================================
Module to repsond to irc server PING requests
Module to repsond to irc server PING requests. This module requires no
configuration
Class Reference
---------------
.. automodule:: pyircbot.modules.PingResponder
:members:

View File

@ -0,0 +1,15 @@
:mod:`RandQuote` --- Remember and retrieve quotes
=================================================
Commands
--------
- *.randomquote .randquote .rq* - fetch and say a random quote
Class Reference
---------------
.. automodule:: pyircbot.modules.RandQuote
:members:
:undoc-members:
:show-inheritance:

View File

@ -0,0 +1,18 @@
:mod:`Remind` --- Set reminders
===============================
Commands
--------
- *.at <time>* - remind at a specific time.
Example: *.at 20:45EST Do your homework!*
- *.in <time>* - Remind after an amount of time.
Example: *.in 1week5d2h1m Go fuck yourself*
Class Reference
---------------
.. automodule:: pyircbot.modules.Remind
:members:
:undoc-members:
:show-inheritance:

View File

@ -1,7 +1,8 @@
:mod:`Scramble` --- Module to provide a word scramble game
==========================================================
yabba blahblah blahblah
Class Reference
---------------
.. automodule:: pyircbot.modules.Scramble
:members:

View File

@ -1,7 +1,13 @@
:mod:`Seen` --- !seen <username>
================================
Provides !seen <username>
Commands
--------
- *!seen <username>* - finds the last time <username> was online
Class Reference
---------------
.. automodule:: pyircbot.modules.Seen
:members:

View File

@ -1,7 +1,118 @@
:mod:`Services` --- Module to provide nick and channel services
===============================================================
yabba blahblah blahblah
Services enables the bot to:
- Set it's nick on startup, and fall back to other names if one nick is taken
- Identify with nickserv or similar
- Ghost users using it's nick
- Request invites & join private channels
Config
-----
.. code-block:: json
{
"user":{
"nick":[
"pyircbot3",
"pyircbot3_",
"pyircbot3__"
],
"password":"nickservpassword",
"username":"pyircbot3",
"hostname":"pyircbot3.domain.com",
"realname":"pyircbot3"
},
"ident":{
"enable":"no",
"to":"nickserv",
"command":"identify %(password)s",
"ghost":"no",
"ghost_to":"nickserv",
"ghost_cmd":"ghost %(nick)s %(password)s"
},
"channels":[
"#xmopx"
],
"privatechannels":{
"to":"chanserv",
"command":"invite %(channel)s",
"list":[
"#aprivatechannel"
]
}
}
.. cmdoption:: user.nick
A list of nicks, the first being the preferred nick and the others being
fallbacks if the primary nick is taken.
.. cmdoption:: user.password
Nickserv password
.. cmdoption:: user.username
IRC username
.. cmdoption:: user.hostname
Host name for the USER command
.. cmdoption:: user.realname
IRC real name
.. cmdoption:: ident.enable
Yes/no if you want to identify with Nickserv or another nick-protection
entity
.. cmdoption:: ident.to
Nick the identify command will be sent to
.. cmdoption:: ident.command
String formatted command to be sent for identification. Available tokens:
- password
.. cmdoption:: ident.ghost
Yes/no if the bot should attempt to ghost anyone using it's nickname
.. cmdoption:: ident.ghost_to
Nick the ghost command will be sent to
.. cmdoption:: ident.ghostcmd
String formatted command to be sent for ghosting. Available tokens:
- nick
- password
.. cmdoption:: channels
List of channels to join on startup
.. cmdoption:: privatechannels.to
Nick to send the invite command to
.. cmdoption:: privatechannels.command
String formatted command to be sent for invitations. Available tokens:
- channel
.. cmdoption:: privatechannels.list
List of channels to request an invite to join on startup
Class Reference
---------------
.. automodule:: pyircbot.modules.Services
:members:

View File

@ -0,0 +1,12 @@
:mod:`SQLite` --- SQLite service
================================
Module providing a sqlite type service
Class Reference
---------------
.. automodule:: pyircbot.modules.SQLite
:members:
:undoc-members:
:show-inheritance:

16
docs/api/modules/tell.rst Normal file
View File

@ -0,0 +1,16 @@
:mod:`Tell` --- Pass messages to a user when they're next seen
==============================================================
Commands
--------
- *.tell <user> <message>* - When <user> is next seen online, they will be
a PM with <message>.
Class Reference
---------------
.. automodule:: pyircbot.modules.Tell
:members:
:undoc-members:
:show-inheritance:

View File

@ -0,0 +1,15 @@
:mod:`Urban` --- Fetch random facts from Urban Dictionary
=========================================================
Commands
--------
- *.urban* - fetch a random fact from Urban Dictionary
Class Reference
---------------
.. automodule:: pyircbot.modules.Urban
:members:
:undoc-members:
:show-inheritance:

View File

@ -0,0 +1,21 @@
:mod:`Weather` --- Fetch weather data by ZIP code
=================================================
Commands
--------
- *.weather <location>*, *.w <location>* - fetch weather for a locaiton. If no location is passed, the user's preferred location will be used.
Example: *.w 95051*
- *.setloc <location>* - set your preferred location
Example: *.setloc Rochester, NY*
*.setloc 14623*
- *.wunit <type>* - set your preference between fahrenheit or celsius.
Example: *.setloc F*
Class Reference
---------------
.. automodule:: pyircbot.modules.Weather
:members:
:undoc-members:
:show-inheritance:

View File

@ -0,0 +1,16 @@
:mod:`Youtube` --- Fetch information for Youtube links
======================================================
Commands
--------
- *.youtube <query>*, *.yt <query>* - search youtube for keywords <query>
Example: *.yt cute cats*
Class Reference
---------------
.. automodule:: pyircbot.modules.Youtube
:members:
:undoc-members:
:show-inheritance:

View File

@ -1,7 +1,7 @@
:mod:`PyIRCBot` --- Main class of the bot
=========================================
yabba blahblah blahblah
Main bot class
.. automodule:: pyircbot.pyircbot
:members:

View File

@ -2,8 +2,8 @@ FROM ubuntu:trusty
COPY start /start
RUN apt-get update ; apt-get install -y python3 python3-dev python3-pip python3-yaml make wget python3-sphinx python3-setuptools unzip libmysqlclient-dev ; cd /tmp ; wget https://github.com/jgarzik/python-bitcoinrpc/archive/master.zip ; unzip master.zip ; cd python-bitcoinrpc-master/ ; python3 setup.py install ; cd /tmp ; wget https://github.com/dpedu/MySQL-for-Python-3/archive/master.zip -O mysqldb.zip ; unzip mysqldb.zip ; cd MySQL-for-Python-3-master/ ; python3 setup.py install ; chmod +x /start ; mkdir /tmp/docs
RUN apt-get update ; apt-get install -y python3 python3-sphinx python3-setuptools python3-dev python3-requests python3-pip python3-yaml make wget unzip libmysqlclient-dev ; cd /tmp ; wget https://github.com/jgarzik/python-bitcoinrpc/archive/master.zip ; unzip master.zip ; cd python-bitcoinrpc-master/ ; python3 setup.py install ; cd /tmp ; wget https://github.com/dpedu/MySQL-for-Python-3/archive/master.zip -O mysqldb.zip ; unzip mysqldb.zip ; cd MySQL-for-Python-3-master/ ; python3 setup.py install ; chmod +x /start ; mkdir /tmp/docs
VOLUME /tmp/docs
CMD ["/start"]
CMD /start

View File

@ -6,7 +6,7 @@ PyIRCBot includes several modules to add basic functionality to your bot.
Contents:
.. toctree::
:maxdepth: 8
:maxdepth: 1
:glob:
../api/modules/*

View File

@ -2,8 +2,11 @@
Dependancies
************
PyIRCBot is designed to run on Python 3, and is usually tested with 3.4. Several
modules are needed that are available for both version of python.
PyIRCBot is designed to run on Python 3, and is usually tested with 3.4. Python
2.x is not supported.
Although **no** non-core modules are needed to run PyIRCBot in it's most basic
form, not all features and modules will be available.
The following non-core Python modules are needed, and easily available through
Pip for python 3:

View File

@ -7,71 +7,54 @@ This is a quick-start guide for the minimal setup to run PyIRCBot.
Getting Started
===============
PyIRCBot is modular. The core bot files may reside in one directory, modules in
another, and userdata in a third. This way, setups can be created where many
unprivileged users may rely one one set of core/module files they cannot edit,
but can customize their instance.
PyIRCBot is modular. The core bot files will reside whereever your system keeps
python modules. User modules and data are kept where you want. This way, setups
can be created where many unprivileged users may rely one one set of
core/module files they cannot edit, but can customize their instance.
Configuration is stored in 3 locations:
Configuration is stored in 2 locations:
- **Core config** - Environmental information for the bot, like where modules and
core code is.
- **Instance config** - Information about one instance of the bot, such as where
module data for the instance will be stored, server address, etc
- **Module config** - Where module configuration files will be stored
Core Configuration
==================
.. code-block:: python
botdir: /home/example/bot/pyircbot/
moduledir: /home/example/bot/pyircbot/modules/
The example core configuration is stored in `config.main.yml`. This contains two options:
.. cmdoption:: botdir
Must be the absolute path to where main.py and the directory `core` resides.
.. cmdoption:: moduledir
must be the absolute path to the directory of modules is.
.. note:: All paths require a trailing slash
- **Instance config** - Information about one instance of the bot, such as
where module data for the instance will be stored, server address, etc.
- **Module config** - Where module configuration settings are be stored
Instance Configuration
======================
.. code-block:: yaml
.. code-block:: json
bot:
datadir: /home/example/bot/data/
rpcbind: 0.0.0.0
rpcport: 1876
connection:
server: irc.freenode.net
ipv6: off
port: 6667
modules:
- PingResponder
- Services
- MySQL
- AttributeStorage
{
"bot":{
"datadir":"./data/",
"rpcbind":"0.0.0.0",
"rpcport":1876
},
"connection":{
"server":"irc.freenode.net",
"ipv6":"off",
"port":6667
},
"modules":[
"PingResponder",
"Services"
]
}
The example bot instance is stored in `config.instance.yml`. This contains several options:
In the example directory, this is stored in `config.json`. This may be
substituted for a YML file with the same data structure. This contains several
options:
.. cmdoption:: bot.datadir
Location where module data will be stored. This directory generally contains
two folders: `config` and `data`. Config contains a yml file for each module
of the same name. Data can be empty, the bot will create directories for
each module as needed.
Location where module data will be stored. This directory generally
contains two folders: `config` and `data`. Config contains a config file
for each module of the same name. Data can be empty, the bot will create
directories for each module as needed.
.. cmdoption:: bot.rpcbind
Address on which to listen for RPC conncetions. RPC has no authentication so
using 127.0.0.1 is reccommended.
Address on which to listen for RPC conncetions. RPC has no authentication
so using 127.0.0.1 is reccommended.
.. cmdoption:: bot.rpcport
@ -91,4 +74,6 @@ The example bot instance is stored in `config.instance.yml`. This contains sever
.. cmdoption:: modules
A YAML list of modules to load. Modules are loaded in the order they are listed here.
A list of modules to load. Modules are loaded in the order they are listed
here. :doc:`PingResponder </api/modules/pingresponder>` and :doc:`Services </api/modules/services>` are the *bare minimum* needed to open and
maintain and IRC connection.

View File

@ -2,21 +2,20 @@
Running a bot
*************
It is reccommended to install PyIRCBot3 with Pip or by running the install
script included in the module folder. This installs the `pyircbot` command into
your $PATH, which is the easiest way to launch a bot. This document assumes it
has been installed this way.
The bot is invoked from the command line:
.. code-block:: sh
./pyircbot/main.py -c config.main.yml -b config.instance.yml
pyircbot --config config.json
.. cmdoption:: -c --config
Path to the "core" config file
.. cmdoption:: -b --bot
Path to the "instance" config file
.. note:: A shell script, run-example.sh, is included in the source. This script
should be renamed and can be used to run the bot.
Path to the bot's :doc:`config </setup/initial_config>` file
The bot will run and print all logging information to stdout.

View File

@ -14,6 +14,7 @@ class PingResponder(ModuleBase):
ModuleBase.__init__(self, bot, moduleName);
self.hooks=[ModuleHook("PING", self.pingrespond)]
def pingrespond(self, args, prefix, trailing):
"""Respond to the PING command"""
# got a ping? send it right back
self.bot.act_PONG(trailing)
self.log.info("%s Responded to a ping: %s" % (self.bot.get_nick(), trailing))

View File

@ -18,10 +18,12 @@ class Services(ModuleBase):
self.current_nick = 0
self.do_ghost = False
def doConnect(self, args, prefix, trailing):
"""Hook for when the IRC conneciton is opened"""
self.bot.act_NICK(self.config["user"]["nick"][0])
self.bot.act_USER(self.config["user"]["username"], self.config["user"]["hostname"], self.config["user"]["realname"])
def nickTaken(self, args, prefix, trailing):
"""Hook that responds to 433, meaning our nick is taken"""
if self.config["ident"]["ghost"]:
self.do_ghost = True
self.current_nick+=1
@ -31,6 +33,7 @@ class Services(ModuleBase):
self.bot.act_NICK(self.config["user"]["nick"][self.current_nick])
def initservices(self, args, prefix, trailing):
"""Hook that sets our initial nickname"""
if self.do_ghost:
self.bot.act_PRIVMSG(self.config["ident"]["ghost_to"], self.config["ident"]["ghost_cmd"] % {"nick":self.config["user"]["nick"][0], "password":self.config["user"]["password"]})
sleep(2)
@ -38,11 +41,13 @@ class Services(ModuleBase):
self.do_initservices()
def invited(self, args, prefix, trailing):
"""Hook responding to INVITE channel invitations"""
if trailing.lower() in self.config["privatechannels"]["list"]:
self.log.info("Invited to %s, joining" % trailing)
self.bot.act_JOIN(trailing)
def do_initservices(self):
"""Identify with nickserv and join startup channels"""
" id to nickserv "
if self.config["ident"]["enable"]:
self.bot.act_PRIVMSG(self.config["ident"]["to"], self.config["ident"]["command"] % {"password":self.config["user"]["password"]})