Browse Source

Update docs

dave/xdcc
dpedu 7 years ago
parent
commit
c002c67807
  1. 10
      docs/api/irccore.rst
  2. 3
      docs/api/modules/attributestorage.rst
  3. 12
      docs/api/modules/attributestoragelite.rst
  4. 15
      docs/api/modules/bitcoinprice.rst
  5. 18
      docs/api/modules/calc.rst
  6. 3
      docs/api/modules/cryptowallet.rst
  7. 3
      docs/api/modules/cryptowalletrpc.rst
  8. 3
      docs/api/modules/dogedice.rst
  9. 3
      docs/api/modules/dogerpc.rst
  10. 3
      docs/api/modules/dogescramble.rst
  11. 3
      docs/api/modules/dogewallet.rst
  12. 3
      docs/api/modules/duckhunt.rst
  13. 3
      docs/api/modules/error.rst
  14. 3
      docs/api/modules/gamebase.rst
  15. 16
      docs/api/modules/inventory.rst
  16. 10
      docs/api/modules/linktitler.rst
  17. 3
      docs/api/modules/mysql.rst
  18. 10
      docs/api/modules/nfllive.rst
  19. 3
      docs/api/modules/nickuser.rst
  20. 6
      docs/api/modules/pingresponder.rst
  21. 15
      docs/api/modules/randquote.rst
  22. 18
      docs/api/modules/remind.rst
  23. 3
      docs/api/modules/scramble.rst
  24. 8
      docs/api/modules/seen.rst
  25. 113
      docs/api/modules/services.rst
  26. 12
      docs/api/modules/sqlite.rst
  27. 16
      docs/api/modules/tell.rst
  28. 15
      docs/api/modules/urban.rst
  29. 21
      docs/api/modules/weather.rst
  30. 16
      docs/api/modules/youtube.rst
  31. 2
      docs/api/pyircbot.rst
  32. 4
      docs/builder/Dockerfile
  33. 2
      docs/modules/_modules.rst
  34. 7
      docs/setup/dependancies.rst
  35. 93
      docs/setup/initial_config.rst
  36. 17
      docs/setup/running.rst
  37. 1
      pyircbot/modules/PingResponder.py
  38. 5
      pyircbot/modules/Services.py

10
docs/api/irccore.rst

@ -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:

3
docs/api/modules/attributestorage.rst

@ -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:

12
docs/api/modules/attributestoragelite.rst

@ -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:

15
docs/api/modules/bitcoinprice.rst

@ -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

@ -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:

3
docs/api/modules/cryptowallet.rst

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

3
docs/api/modules/cryptowalletrpc.rst

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

3
docs/api/modules/dogedice.rst

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

3
docs/api/modules/dogerpc.rst

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

3
docs/api/modules/dogescramble.rst

@ -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:

3
docs/api/modules/dogewallet.rst

@ -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:

3
docs/api/modules/duckhunt.rst

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

3
docs/api/modules/error.rst

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

3
docs/api/modules/gamebase.rst

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

16
docs/api/modules/inventory.rst

@ -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:

10
docs/api/modules/linktitler.rst

@ -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:

3
docs/api/modules/mysql.rst

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

10
docs/api/modules/nfllive.rst

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

3
docs/api/modules/nickuser.rst

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

6
docs/api/modules/pingresponder.rst

@ -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:

15
docs/api/modules/randquote.rst

@ -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:

18
docs/api/modules/remind.rst

@ -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:

3
docs/api/modules/scramble.rst

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

8
docs/api/modules/seen.rst

@ -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:

113
docs/api/modules/services.rst

@ -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:

12
docs/api/modules/sqlite.rst

@ -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

@ -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:

15
docs/api/modules/urban.rst

@ -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:

21
docs/api/modules/weather.rst

@ -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:

16
docs/api/modules/youtube.rst

@ -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:

2
docs/api/pyircbot.rst

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

4
docs/builder/Dockerfile

@ -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

2
docs/modules/_modules.rst

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

7
docs/setup/dependancies.rst

@ -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:

93
docs/setup/initial_config.rst

@ -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
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
The example bot instance is stored in `config.instance.yml`. This contains several options:
.. code-block:: json
{
"bot":{
"datadir":"./data/",
"rpcbind":"0.0.0.0",
"rpcport":1876
},
"connection":{
"server":"irc.freenode.net",
"ipv6":"off",
"port":6667
},
"modules":[
"PingResponder",
"Services"
]
}
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.

17
docs/setup/running.rst

@ -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.

1
pyircbot/modules/PingResponder.py

@ -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))

5
pyircbot/modules/Services.py

@ -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"]})

Loading…
Cancel
Save