CoreLib Documentation

Transcription

1 CoreLib Documentation Release 25 Bart Thate August 14, 2014

2

3 Contents 1 CONTACT 3 2 DOCS LICENSE README PLUGS core.plugs.add module core.plugs.all module core.plugs.allow module core.plugs.api module core.plugs.cmnds module core.plugs.edit module core.plugs.find module core.plugs.first module core.plugs.irc module core.plugs.join module core.plugs.last module core.plugs.log module core.plugs.mbox module core.plugs.rm module core.plugs.rss module core.plugs.show module core.plugs.start module core.plugs.status module core.plugs.stop module core.plugs.test module core.plugs.timer module core.plugs.trim module core.plugs.udp module core.plugs.uptime module core.plugs.version module core.plugs.xmpp module MODULE core.completer module core.defines module core.log module i

4 4.4 core.test module core.utils module core Python Module Index 31 ii

5 corelib is a library for writing bots. source is located at Contents 1

6 2 Contents

7 CHAPTER 1 CONTACT IRC: botfather on #dunkbots irc.freenode.net bthate@dds.nl till freedom come!! 3

8 4 Chapter 1. CONTACT

9 CHAPTER 2 DOCS 2.1 LICENSE Copyright 2014 B.H.J Thate CORELIB - a library for programming bots Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software ), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: As the creator of this piece of software, Bart Thate, i disclaim all rights on the code contained in this software package. Therefore this software is free of all claims on it. This program is a given, therefore no one can be able to put it under any restriction, limitations or bounds. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PAR- TICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFT- WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 2.2 README CORELIB is a library for writing bots. commands: add - add a <type> <value> all - show all possible keys cmnds - show all commands edit - edit object find - find objects 5

10 first - show first object join - join channel last - show last object log - add a log object mbox - import a mbox file rm - remove a object show - show JSON of an object start - start a service (xmpp/irc/udp/rss/api) status - show status of services stop - stop a service test - show test message timer - run a timer trim - remove duplicates in data dir uptime - show uptime of services version - show version 6 Chapter 2. DOCS

11 CHAPTER 3 PLUGS 3.1 core.plugs.add module add a value. add(event) 3.2 core.plugs.all module show all attributes available. all(event) 3.3 core.plugs.allow module add to allow list. allow(event) 3.4 core.plugs.api module Object Copy API. class APIHandler(request, client_address, server) Bases: http.server.basehttprequesthandler timeserver request handler class do_delete(zelf ) handle a REST request. do_get(zelf ) handle a REST request. do_post(zelf ) handle a REST request. do_put(zelf ) handle a REST request. 7

12 handle_request(zelf ) handle a REST request. log_request(zelf, code) log the request setup(zelf ) called on each incoming request. write_header(zelf, type= text/plain ) write headers to the client. class APIServer(zelf, *args, **kwargs) Bases: http.server.httpserver, core.object API server allow_reuse_address = True boot(zelf, *args, **kwargs) daemon_thread = True exit(zelf ) shutdown the API server. handle_error(zelf, request, addr) log the error serve(zelf ) serving loozelf. api_all(handler, request) api_get(handler, request) api_home(handler, request) api_show(handler, request) init(*args, **kwargs) 3.5 core.plugs.cmnds module show available commands. cmnds(event) 3.6 core.plugs.edit module edit. edit(event) 3.7 core.plugs.find module find objects based on attribute values. 8 Chapter 3. PLUGS

13 find(event) 3.8 core.plugs.first module first record found. first(event) 3.9 core.plugs.irc module irc related commands. init(*args, **kwargs) 3.10 core.plugs.join module join etc. join(event) 3.11 core.plugs.last module last record found. last(event) 3.12 core.plugs.log module add a value. log(event) 3.13 core.plugs.mbox module mailbox input plugin. mbox(event) 3.14 core.plugs.rm module remove. remove(event) 3.8. core.plugs.first module 9

14 3.15 core.plugs.rss module rss module. class RSS(zelf, sleep, *args, **kwargs) Bases: core.object boot(zelf, *args, **kwargs) display(zelf, *args, **kwargs) look(zelf, *args, **kwargs) run(zelf, *args, **kwargs) stop(zelf, *args, **kwargs) init(*args, **kwargs) 3.16 core.plugs.show module show JSON dump of objects. show(event) 3.17 core.plugs.start module run plugins initialization code. start(event) 3.18 core.plugs.status module show status. status(event) 3.19 core.plugs.stop module regen, regen. stop(event) 3.20 core.plugs.test module test command. cmnd(event) 10 Chapter 3. PLUGS

15 3.21 core.plugs.timer module time the timing. class Timer(zelf, time_alarm, event, *args, **kwargs) Bases: core.object echo(zelf, *args, **kwargs) timer(event) 3.22 core.plugs.trim module trim a core data directory into a new unique clone. trim(event) 3.23 core.plugs.udp module relay txt through a udp port listener. class UDP(zelf, *args, **kwargs) Bases: core.object output(zelf, input, addr) init(*args, **kwargs) 3.24 core.plugs.uptime module show uptimes. uptime(event) 3.25 core.plugs.version module show version. version(event) 3.26 core.plugs.xmpp module xmpp related stuff. init(*args, **kwargs) core.plugs.timer module 11

16 12 Chapter 3. PLUGS

17 CHAPTER 4 MODULE 4.1 core.completer module completer stuff. class TheCompleter(options) Bases: rlcompleter.completer complete(text, state) 4.2 core.defines module defines. 4.3 core.log module provide logging infrastructure. class Formatter(fmt=None, datefmt=none, style= % ) Bases: logging.formatter hooks into the logging system. format(zelf, record) init(loglevel) return a properly configured logger. 4.4 core.test module define core test classes. class Test(zelf, *args, **kwargs) Bases: unittest.case.testcase class that implements setup and teardow of tests. 13

18 4.5 core.utils module utils package. a_time(daystr) aj(sep=none, *args) b_time(daystr) cdir(path) check_permissions(ddir, dirmask=448, filemask=384) copyright() day() decode_char(txt, encoding= utf-8, what= ) dispatch(target, event, cmnd, *args, **kwargs) dj(*args) dtime(stamp) enc_char(s) enc_name(input) enc_needed(s) error(*args, **kwargs) feed(text) fetch_url(type, url, myheaders={}, postdata={}, keyfile=none, certfile=, port=80) format(*args, **kwargs) from_enc(txt, encoding= utf-8, what= ) ftime(datestr) full(a) get_clsname(obj) get_day(daystr) convert string to time. get_encoding(data) get_exception(*args, **kwargs) get_frame(search= code ) get_func(*args, **kwargs) get_funcname(func) get_highest(target, file_name) determine new file extension. get_hour(daystr) get_how(*args, **kwargs) get_name(obj) 14 Chapter 4. MODULE

19 get_plugname(*args, **kwargs) get_source(mod, package) get_state(obj, type= ) get_status(obj, type= ) get_strace(*args, **kwargs) get_uptime(obj) get_urls(data) get_zin(obj) hello(*args) hms() intersect(a, b) class istr Bases: builtins.str j(*args) list_eggs(filter= ) list_files(*args, **kwargs) loop(*args, **kwargs) make_opts(options) make_signature(data) make_time(daystr) mj(*args) need_redirect(resp) need_skip(obj, black=[], white=[]) nr_days(seconds) parse(txt) parse_ (fn) parse_url(*args, **kwargs) Attribute Index Value Value if not present scheme 0 URL scheme specifier empty string netloc 1 Network location part empty string path 2 Hierarchical path empty string query 3 Query component empty string fragment 4 Fragment identifier empty string parse_urls(*args, **kwargs) ptime(daystr) reduced_keys(*args, **kwargs) resolve(*args, **kwargs) resolve_host(ip=none, timeout=1.0) resolve_ip(hostname=none, timeout=1.0) rtime() 4.5. core.utils module 15

20 run_sed(filename, sedstring) replace oldcore strings with the new one. short_date(*args, **kwargs) short_time(*args, **kwargs) show_eggs(filter= core ) smooth(a) split_txt(what, l=375) str_day(seconds) strip_html(text) strip_wiki(text) stripbadchar(s) stripped(input) tdiff(d1, d2) time_string(*args, **kwargs) time_time(*args, **kwargs) to_enc(what, encoding= utf-8 ) today() return time of 0:00 today. touch(fname) txt_parse(txt) unescape(text) union(a, b) unique(a) useragent() verify_signature(data, signature) verzin(a) 4.6 core core package Subpackages core.plugs package Submodules core.plugs.add module add(event) add a value. 16 Chapter 4. MODULE

21 core.plugs.all module all(event) show all attributes available. core.plugs.allow module allow(event) add to allow list. core.plugs.api module Object Copy API. class APIHandler(request, client_address, server) Bases: http.server.basehttprequesthandler timeserver request handler class do_delete(zelf ) handle a REST request. do_get(zelf ) handle a REST request. do_post(zelf ) handle a REST request. do_put(zelf ) handle a REST request. handle_request(zelf ) handle a REST request. log_request(zelf, code) log the request setup(zelf ) called on each incoming request. write_header(zelf, type= text/plain ) write headers to the client. class APIServer(zelf, *args, **kwargs) Bases: http.server.httpserver, core.object API server allow_reuse_address = True boot(zelf, *args, **kwargs) daemon_thread = True exit(zelf ) shutdown the API server. handle_error(zelf, request, addr) log the error serve(zelf ) serving loozelf. api_all(handler, request) api_get(handler, request) api_home(handler, request) 4.6. core 17

22 api_show(handler, request) init(*args, **kwargs) core.plugs.cmnds module cmnds(event) show available commands. core.plugs.edit module edit(event) edit. core.plugs.find module find(event) find objects based on attribute values. core.plugs.first module first(event) first record found. core.plugs.irc module init(*args, **kwargs) irc related commands. core.plugs.join module join(event) join etc. core.plugs.last module last(event) last record found. core.plugs.log module log(event) add a value. core.plugs.mbox module mbox(event) mailbox input plugin. core.plugs.rm module remove(event) remove. core.plugs.rss module rss module. class RSS(zelf, sleep, *args, **kwargs) Bases: core.object boot(zelf, *args, **kwargs) display(zelf, *args, **kwargs) look(zelf, *args, **kwargs) 18 Chapter 4. MODULE

23 run(zelf, *args, **kwargs) stop(zelf, *args, **kwargs) init(*args, **kwargs) core.plugs.show module show(event) show JSON dump of objects. core.plugs.start module start(event) run plugins initialization code. core.plugs.status module status(event) show status. core.plugs.stop module stop(event) regen, regen. core.plugs.test module cmnd(event) test command. core.plugs.timer module time the timing. class Timer(zelf, time_alarm, event, *args, **kwargs) Bases: core.object echo(zelf, *args, **kwargs) timer(event) core.plugs.trim module trim(event) trim a core data directory into a new unique clone. core.plugs.udp module class UDP(zelf, *args, **kwargs) Bases: core.object output(zelf, input, addr) init(*args, **kwargs) relay txt through a udp port listener. core.plugs.uptime module uptime(event) show uptimes. core.plugs.version module version(event) show version core 19

24 core.plugs.xmpp module init(*args, **kwargs) xmpp related stuff. Module contents Submodules core.completer module completer stuff. class TheCompleter(options) Bases: rlcompleter.completer complete(text, state) core.defines module defines. core.log module provide logging infrastructure. class Formatter(fmt=None, datefmt=none, style= % ) Bases: logging.formatter hooks into the logging system. format(zelf, record) init(loglevel) return a properly configured logger. core.test module define core test classes. class Test(zelf, *args, **kwargs) Bases: unittest.case.testcase class that implements setup and teardow of tests. core.utils module utils package. a_time(daystr) aj(sep=none, *args) b_time(daystr) cdir(path) 20 Chapter 4. MODULE

25 check_permissions(ddir, dirmask=448, filemask=384) copyright() day() decode_char(txt, encoding= utf-8, what= ) dispatch(target, event, cmnd, *args, **kwargs) dj(*args) dtime(stamp) enc_char(s) enc_name(input) enc_needed(s) error(*args, **kwargs) feed(text) fetch_url(type, url, myheaders={}, postdata={}, keyfile=none, certfile=, port=80) format(*args, **kwargs) from_enc(txt, encoding= utf-8, what= ) ftime(datestr) full(a) get_clsname(obj) get_day(daystr) convert string to time. get_encoding(data) get_exception(*args, **kwargs) get_frame(search= code ) get_func(*args, **kwargs) get_funcname(func) get_highest(target, file_name) determine new file extension. get_hour(daystr) get_how(*args, **kwargs) get_name(obj) get_plugname(*args, **kwargs) get_source(mod, package) get_state(obj, type= ) get_status(obj, type= ) get_strace(*args, **kwargs) get_uptime(obj) get_urls(data) 4.6. core 21

26 get_zin(obj) hello(*args) hms() intersect(a, b) class istr Bases: builtins.str j(*args) list_eggs(filter= ) list_files(*args, **kwargs) loop(*args, **kwargs) make_opts(options) make_signature(data) make_time(daystr) mj(*args) need_redirect(resp) need_skip(obj, black=[], white=[]) nr_days(seconds) parse(txt) parse_ (fn) parse_url(*args, **kwargs) Attribute Index Value Value if not present scheme 0 URL scheme specifier empty string netloc 1 Network location part empty string path 2 Hierarchical path empty string query 3 Query component empty string fragment 4 Fragment identifier empty string parse_urls(*args, **kwargs) ptime(daystr) reduced_keys(*args, **kwargs) resolve(*args, **kwargs) resolve_host(ip=none, timeout=1.0) resolve_ip(hostname=none, timeout=1.0) rtime() run_sed(filename, sedstring) replace oldcore strings with the new one. short_date(*args, **kwargs) short_time(*args, **kwargs) show_eggs(filter= core ) smooth(a) split_txt(what, l=375) str_day(seconds) 22 Chapter 4. MODULE

27 strip_html(text) strip_wiki(text) stripbadchar(s) stripped(input) tdiff(d1, d2) time_string(*args, **kwargs) time_time(*args, **kwargs) to_enc(what, encoding= utf-8 ) today() return time of 0:00 today. touch(fname) txt_parse(txt) unescape(text) union(a, b) unique(a) useragent() verify_signature(data, signature) verzin(a) Module contents basic package for the program. exception AttributeSet Bases: core.error attribute is already set. class Bot(zelf, *args, **kwargs) Bases: core.dispatcher Base Bot class. announce(zelf, *args, **kwargs) announce on channels. begin(zelf, *args, **kwargs) start a bot. cmnd(zelf, *args, **kwargs) run a command with provided string. connect(zelf, *args, **kwargs) connect to server. exit(zelf, *args, **kwargs) shutdown a bot. get_event(zelf, *args, **kwargs) return an event> 4.6. core 23

28 get_prompt(zelf, *args, **kwargs) return a prompt. join_channels(zelf, *args, **kwargs) join channels. say(zelf, *args, **kwargs) output channel, txt. waiting = False class ConsoleBot(zelf, *args, **kwargs) Bases: core.bot bot running on the console. announce(zelf, *args, **kwargs) get_event(zelf, *args, **kwargs) get_prompt(zelf, *args, **kwargs) waiting = False exception DataNotSet Bases: core.error missing argument attribute. class Dispatcher(zelf, *args, **kwargs) Bases: core.object the dispatcher delegates the workload to the Runners. Runner gets instantiated when needed. allowed(zelf, *args, **kwargs) cleanup(zelf, dojoin=false) remove idle Runners. denied(zelf, *args, **kwargs) dispatch(zelf, *args, **kwargs) dispatch an event onto a Runner. execute(zelf, *args, **kwargs) execute a command, event pair. exit(zelf, name=none) stop the Runners. is_alive(zelf, *args, **kwargs) whether any Runners running. make_new(zelf, *args, **kwargs) create a Runner. put(zelf, *args, **kwargs) put load to the Runner. register(zelf, *args, **kwargs) callback type with corresponding callback function. run_func(zelf, *args, **kwargs) execute command/event pair. 24 Chapter 4. MODULE

29 exception Error Bases: builtins.baseexception basic Exception used in the program. exception FileNotFoundError Bases: core.error file is not found. class IRCBot(zelf, *args, **kwargs) Bases: core.bot IRC bot. action(zelf, printto, what, event=none, *args, **kwargs) bind(zelf ) cc =. close(zelf ) connect(zelf, reconnect=true) ctcp(zelf, printto, what) ctcpreply(zelf, printto, what) delop(zelf, channel, who) donick(zelf, nick, setorig=false, save=false, whois=false) doop(zelf, channel, who) get_event(zelf, *args, **kwargs) getchannelmode(zelf, channel) handle_366(zelf, *args, **kwargs) handle_433(zelf, event) handle_513(zelf, event) handle_ctcp(zelf, event) handle_invite(zelf, event) handle_join(zelf, event) handle_notice(zelf, event) handle_ping(zelf, event) handle_privmsg(zelf, event) join(zelf, channel, password=none) logon(zelf ) marker = \r\n names(zelf, channel) notice(zelf, printto, what) part(zelf, channel) ping(zelf, *args, **kwargs) 4.6. core 25

30 pong(zelf, *args, **kwargs) privmsg(zelf, printto, txt) quit(zelf, reason= ) read_some(zelf, *args, **kwargs) say(zelf, *args, **kwargs) send(zelf, txt) settopic(zelf, channel, txt) stop(zelf, *args, **kwargs) voice(zelf, channel, who) who(zelf, who) whois(zelf, who) class Looper(zelf, *args, **kwargs) Bases: core.object a Looper calls a function every x seconds. boot(zelf, *args, **kwargs) initialize a Looper. get_name(zelf, *args, **kwargs) exception NoJSON Bases: core.error no JSON could be decoded/encoded. exception NoTarget Bases: core.error missing argument attribute. exception NoWorkdirSet Bases: builtins.baseexception a working directory is needed. exception NotSet Bases: core.error attribute is not set. class Object Bases: builtins.dict basic Object on which the rest of the program is based. announce(zelf, *args, **kwargs) announce to all the running cores. check_notwanted(zelf, *args, **kwargs) whether an object is not desired. check_wanted(zelf, *args, **kwargs) whether an object is desired. clear(zelf ) clear the ready state. 26 Chapter 4. MODULE

31 define(zelf, *args, **kwargs) set a attribute on this object. first(zelf, *args, **kwargs) return the first object where the key and/or value matches. get_args(zelf, *args, **kwargs) get the arguments of the txt attribute. get_cmnd(zelf, *args, **kwargs) determine the command in the zelf.txt attribute, if present. get_days(zelf, *args, **kwargs) get the number of days relative to the object s creation time. get_filetime(zelf, *args, **kwargs) timestamp of related filename. get_keys(zelf, *args, **kwargs) skip the unwanted keys e.g those that start with a _. get_obj(zelf, *args, **kwargs) cloned object, with only the proper keys used. get_parsed(zelf, *args, **kwargs) parse the txt attribute. get_rest(zelf, *args, **kwargs) get the rest of the txt attribute. get_root(zelf, *args, **kwargs) root directory of the program. get_slice(zelf, *args, **kwargs) take a slice of the Object. get_timed(zelf, *args, **kwargs) retrieve the creation time of an object. get_url(zelf, *args, **kwargs) url of the object s file so that it can be retrieved when API server is running. last(zelf, *args, **kwargs) return the last object where the key and/or value matches. load(zelf, *args, **kwargs) load a JSON file into this object. make_path(zelf, *args, **kwargs) create workdir if necessary. make_signature(zelf, sig=none) signature of the data contained in this object. objects(zelf, *args, **kwargs) list of all object s. pretty(zelf ) nice formatted JSON string of this object. read(zelf, *args, **kwargs) read the JSON file from disk core 27

32 ready(zelf ) signal to ready state. register(zelf, *args, **kwargs) register a value in a list on this object. reply(zelf, *args, **kwargs) send reply to origin. save(zelf, *args, **kwargs) save JSON to disk. say(zelf, *args, **kwargs) output text through the _target attribute. selected(zelf, *args, **kwargs) list of desired objects. selector(zelf, *args, **kwargs) see if this objects has the desired attributes. show(zelf ) list of key,value pairs. sync(zelf, *args, **kwargs) sync JSON to disk. to_disk(zelf, *args, **kwargs) create JSON ready to be saved to disk. to_full(zelf, *args, **kwargs) full JSON dump of this object. to_json(zelf, *args, **kwargs) JSON string representation of this object. wait(zelf, sec=180.0) wait for ready state. write(zelf, *args, **kwargs) actual write to disk. exception Overload Bases: core.error method is trying to be overloaded. class Plugins(zelf, *args, **kwargs) Bases: core.object object to register plugins with. exit(zelf, *args, **kwargs) exit all plugins. get_names(zelf, plugsdir) plugnames from the plugin directory. init(zelf, *args, **kwargs) init all plugins or a specific one if argument is given. load_mod(zelf, plugname, pdir=, force=true) load module. 28 Chapter 4. MODULE

33 load_package(zelf, modname) load package. load_plugs(zelf, path) load plugins from the plugin directory. plug_init(zelf, *args, **kwargs) initialize plugin. plug_shutdown(zelf, plugname) call the shutdown() function, if provided. reload(zelf, plugname, force=false) reload a plugin. exception RemoteDisconnect Bases: core.error Exception thrown when the connection is disconnected. class Runner(zelf, *args, **kwargs) Bases: threading.thread the working unit of CORELIB. exit(zelf, *args, **kwargs) stop the Runner. get_name(zelf, *args, **kwargs) nr = 0 put(zelf, *args, **kwargs) put arguments/kwargs to the Runner. class TestBot(zelf, *args, **kwargs) Bases: core.bot Bot used in unittests. check(zelf, *args, **kwargs) class XMPPBot(zelf, *args, **kwargs) Bases: core.bot XMPP bot. connect(zelf ) exception(zelf, ex) get_event(zelf, *args, **kwargs) handle_connected(zelf, *args, **kwargs) handle_disconnected(zelf, *args, **kwargs) handle_failedauth(zelf, error, *args) handle_failure(zelf, ex, *args, **kwargs) handle_message(zelf, data, *args, **kwargs) handle_presence(zelf, data, *args, **kwargs) loop(zelf, *args, **kwargs) say(zelf, *args, **kwargs) 4.6. core 29

34 session_start(zelf, event) stop(zelf, *args, **kwargs) boot(*args, **kwargs) get the program properly initialized. irc_parse(obj, *args, **kwargs) parse a string into an IRC event. kernel_status() shutdown() close the program in a appropiate manner. 30 Chapter 4. MODULE

35 Python Module Index c core, 23 core.completer, 20 core.defines, 20 core.log, 20 core.plugs, 20 core.plugs.add, 16 core.plugs.all, 17 core.plugs.allow, 17 core.plugs.api, 17 core.plugs.cmnds, 18 core.plugs.edit, 18 core.plugs.find, 18 core.plugs.first, 18 core.plugs.irc, 18 core.plugs.join, 18 core.plugs.last, 18 core.plugs.log, 18 core.plugs.mbox, 18 core.plugs.rm, 18 core.plugs.rss, 18 core.plugs.show, 19 core.plugs.start, 19 core.plugs.status, 19 core.plugs.stop, 19 core.plugs.test, 19 core.plugs.timer, 19 core.plugs.trim, 19 core.plugs.udp, 19 core.plugs.uptime, 19 core.plugs.version, 19 core.plugs.xmpp, 20 core.test, 20 core.utils, 20 31