botje 54
Framework to program bots !!
License: MIT

README
######

intro
=====

| BOTJE is a python3 framework which you can use to program bots.
| BOTJE makes it possible to program your own module enabling your own commands.
| BOTJE contains serveral modules that can be used to program.
| BOTJE has a MIT no-clause license.

install
=======

you might need to do the following if the bot doesn't work:

::

  bart@okdan:~/botje$ export PYTHONPATH="."
  bart@okdan:~/botje$ export PYTHONIOENCODING="utf-8"

clone the source:

:: 

  bart@okdan:~$ hg clone https://bitbucket.org/bthate/botje
  bart@okdan:~$ cd botje
  bart@okdan:~/botje$ ./bin/botje --shell

another option is to download with pip3 and install globally:

::

  bart@okdan:~$ pip3 install botje --upgrade
  bart@okdan:~$ ./botje --shell

irc
===

use the botje-irc program to connect to an IRC server.

::

  bart@okdan:~$ botje-irc -n botje -s irc.freenode.net -c \#dunkbots --shell

xmpp
====

use the botje-xmpp to connect to an XMPP server

::

  bart@okdan:~$ botje-xmpp -u monitor@localhost --room test@conference.localhost --shell

users
=====

one needs to add a users origin to be able to give the bot commands. One can add a user with the meet command:

::

  bart@okdan:~$ botje meet user@server
  user user@server created

to give the user a permission you can use the perm command:

::

  bart@okdan:~$ botje perm user@server ps
  ok user@server

the default shell user is root@shell and gives access to all the commands that are available.

programming
===========

user programmed modules are read from the ~/.mods directory, you can put your .py files over there.

example:

::

  def hi(event):
      event.reply("hi %s" % event.origin)

modules
=======

.. csv-table::
    :header: "Name", "Description"
    :widths: auto
    :delim: #

    bot                      # bot package.
    bot.cli                  # command line interface bot.
    bot.clock                # timer, repeater. timed daemon.
    bot.cmds                 # bot commands package.
    bot.cmds.clock           # clock related commands.
    bot.cmds.db              # database related commands.
    bot.cmds.doc             # documentation related commands.
    bot.cmds.edit            # command to edit json files.
    bot.cmds.email           # email commands.
    bot.cmds.input           # input module.
    bot.cmds.license         # license command
    bot.cmds.loader          # loader related commands.
    bot.cmds.oper            # none
    bot.cmds.rss             # rss related commands.
    bot.cmds.test            # test commands.
    bot.cmds.users           # user management.
    bot.db                   # access saved json files.
    bot.dcc                  # direct client to client bot.
    bot.defines              # none
    bot.event                # event class.
    bot.handler              # event handler based on queue.queue.
    bot.irc                  # irc bot.
    bot.loader               # load modules.
    bot.obj                  # object class with save/load of json files.
    bot.raw                  # raw output using print.
    bot.rss                  # rss module (needs feedparser).
    bot.select               # select based loop.
    bot.thr                  # threading module.
    bot.udp                  # relay txt through a udp port listener.
    bot.users                # register an user and give them user , oper or uber permission.
    bot.utils                # botje utils package.
    bot.utils.decorators     # decorators module.
    bot.utils.log            # log module to set standard format of logging.
    bot.utils.shell          # shell related functionality.
    bot.utils.time           # timed helper functions.
    bot.utils.trace          # stack trace helper functions.
    bot.utils.url            # functions that fetch data from url.
    bot.xmpp                 # xmpp bot (requires sleekxmpp).

commands
========

Over 60 commands are now available in BOTJE.

.. csv-table::
    :header: "Name", "Description"
    :widths: auto
    :delim: #

    begin                    # begin stopwatch.
    end                      # stop stopwatch.
    timer                    # timer command to schedule a text to be printed on a given time. stopwatch to measure elapsed time.
    attr                     # show attributes of an object type.
    deleted                  # show deleted records.
    find                     # present a list of objects based on prompt input.
    first                    # show the first record matching the given criteria.
    fix                      # fix a object by loading and saving it.
    last                     # show last objectect matching the criteria.
    ls                       # show subdirs in working directory.
    restore                  # set deleted=false in selected records.
    rm                       # set deleted flag on objects.
    today                    # show last week's logged objects.
    week                     # show last week's logged objects.
    yesterday                # show last week's logged objects.
    cmds                     # show list of commands.
    man                      # show descriptions of the available commands.
    mods                     # show available modules.
    modules                  # show available modules.
    uptime                   # show uptime.
    version                  # show version.
    edit                     # edit and save objects.
    mbox                     # convert emails to botje objects.
    log                      # log some text.
    rss                      # add a rss url.
    shop                     # add a shopitem to the shopping list.
    todo                     # log a todo item.
    tomorrow                 # show todo items for tomorrow.
    reload                   # reload a plugin.
    start                    # start a plugin.
    stop                     # stop a plugin.
    exit                     # stop the program.
    load                     # force a plugin reload.
    pid                      # show pid of the bot.
    ps                       # show running threads.
    quit                     # stop the program.
    reboot                   # reboot the ldr, allowing statefull reboot (keeping connections alive).
    test                     # echo origin.
    tinder                   # loop an command nr of times.
    delperm                  # delete permissions of an user.
    meet                     # create an user record.
    perm                     # add/change permissions of an user.
    permissions              # show permissions granted to a user.
    perms                    # show permission of user.
    u                        # show user selected by userhost.
    w                        # show user data.

contact
=======

you can email me or contact me on IRC/freenode/#dunkbots.

| Bart Thate (bthate@dds.nl, thatebart@gmail.com)
| botfather on #dunkbots irc.freenode.net